docs/latex/wx/scrolwin.tex

   1 \section{\class{wxScrolledWindow}}\label{wxscrolledwindow}
   2
   3 The wxScrolledWindow class manages scrolling for its client area, transforming
   4 the coordinates according to the scrollbar positions, and setting the
   5 scroll positions, thumb sizes and ranges according to the area in view.
   6
   7 As with all windows, an application can draw onto a wxScrolledWindow using a \helpref{device context}{dcoverview}.
   8
   9 You have the option of handling the OnPaint handler
  10 or overriding the \helpref{OnDraw}{wxscrolledwindowondraw} function, which is passed
  11 a pre-scrolled device context (prepared by \helpref{PrepareDC}{wxscrolledwindowpreparedc}).
  12
  13 If you don't wish to calculate your own scrolling, you must call PrepareDC when not drawing from
  14 within OnDraw, to set the device origin for the device context according to the current
  15 scroll position.
  16
  17 \wxheading{Derived from}
  18
  19 \helpref{wxPanel}{wxpanel}\\
  20 \helpref{wxWindow}{wxwindow}\\
  21 \helpref{wxEvtHandler}{wxevthandler}\\
  22 \helpref{wxObject}{wxobject}
  23
  24 \wxheading{Include files}
  25
  26 <wx/scrolwin.h>
  27
  28 \wxheading{Window styles}
  29
  30 \twocolwidtha{5cm}
  31 \begin{twocollist}\itemsep=0pt
  32 \twocolitem{\windowstyle{wxRETAINED}}{Uses a backing pixmap to speed refreshes. Motif only.}
  33 \end{twocollist}
  34
  35 See also \helpref{window styles overview}{windowstyles}.
  36
  37 \wxheading{Remarks}
  38
  39 Use wxScrolledWindow for applications where the user scrolls by a fixed amount, and
  40 where a `page' can be interpreted to be the current visible portion of the window. For
  41 more sophisticated applications, use the wxScrolledWindow implementation as a guide
  42 to build your own scroll behaviour.
  43
  44 \wxheading{See also}
  45
  46 \helpref{wxScrollBar}{wxscrollbar}, \helpref{wxClientDC}{wxclientdc}, \helpref{wxPaintDC}{wxpaintdc}
  47
  48 \latexignore{\rtfignore{\wxheading{Members}}}
  49
  50 \membersection{wxScrolledWindow::wxScrolledWindow}\label{wxscrolledwindowconstr}
  51
  52 \func{}{wxScrolledWindow}{\void}
  53
  54 Default constructor.
  55
  56 \func{}{wxScrolledWindow}{\param{wxWindow*}{ parent}, \param{wxWindowID }{id = -1},\rtfsp
  57 \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
  58 \param{long}{ style = wxHSCROLL \pipe wxVSCROLL}, \param{const wxString\& }{name = ``scrolledWindow"}}
  59
  60 Constructor.
  61
  62 \wxheading{Parameters}
  63
  64 \docparam{parent}{Parent window.}
  65
  66 \docparam{id}{Window identifier. A value of -1 indicates a default value.}
  67
  68 \docparam{pos}{Window position. If a position of (-1, -1) is specified then a default position
  69 is chosen.}
  70
  71 \docparam{size}{Window size. If a size of (-1, -1) is specified then the window is sized
  72 appropriately.}
  73
  74 \docparam{style}{Window style. See \helpref{wxScrolledWindow}{wxscrolledwindow}.}
  75
  76 \docparam{name}{Window name.}
  77
  78 \wxheading{Remarks}
  79
  80 The window is initially created without visible scrollbars.
  81 Call \helpref{wxScrolledWindow::SetScrollbars}{wxscrolledwindowsetscrollbars} to
  82 specify how big the virtual window size should be.
  83
  84 \membersection{wxScrolledWindow::\destruct{wxScrolledWindow}}
  85
  86 \func{}{\destruct{wxScrolledWindow}}{\void}
  87
  88 Destructor.
  89
  90 \membersection{wxScrolledWindow::CalcScrolledPosition}\label{wxscrolledwindowcalcscrolledposition}
  91
  92 \constfunc{void}{CalcScrolledPosition}{
  93    \param{int }{x},
  94    \param{int }{y},
  95    \param{int *}{xx}
  96    \param{int *}{yy}}
  97
  98 Translates the logical coordinates to the device ones. For example, if a window is
  99 scrolled 10 pixels to the bottom, the device coordinates of the origin are (0, 0)
 100 (as always), but the logical coordinates are (0, 10) and so the call to
 101 CalcScrolledPosition(0, 0, \&xx, \&yy) will return 10 in yy.
 102
 103 \wxheading{See also}
 104
 105 \helpref{CalcUnscrolledPosition}{wxscrolledwindowcalcunscrolledposition}
 106
 107 \membersection{wxScrolledWindow::CalcUnscrolledPosition}\label{wxscrolledwindowcalcunscrolledposition}
 108
 109 \constfunc{void}{CalcUnscrolledPosition}{
 110    \param{int }{x},
 111    \param{int }{y},
 112    \param{int *}{xx}
 113    \param{int *}{yy}}
 114
 115 Translates the device coordinates to the logical ones. For example, if a window is
 116 scrolled 10 pixels to the bottom, the device coordinates of the origin are (0, 0)
 117 (as always), but the logical coordinates are (0, 10) and so the call to
 118 CalcUnscrolledPosition(0, 10, \&xx, \&yy) will return 0 in yy.
 119
 120 \wxheading{See also}
 121
 122 \helpref{CalcScrolledPosition}{wxscrolledwindowcalcscrolledposition}
 123
 124 \membersection{wxScrolledWindow::Create}\label{wxscrolledwindowcreate}
 125
 126 \func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID }{id = -1},\rtfsp
 127 \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
 128 \param{long}{ style = wxHSCROLL \pipe wxVSCROLL}, \param{const wxString\& }{name = ``scrolledWindow"}}
 129
 130 Creates the window for two-step construction. Derived classes
 131 should call or replace this function. See \helpref{wxScrolledWindow::wxScrolledWindow}{wxscrolledwindowconstr}\rtfsp
 132 for details.
 133
 134 \membersection{wxScrolledWindow::EnableScrolling}\label{wxscrolledwindowenablescrolling}
 135
 136 \func{void}{EnableScrolling}{\param{const bool}{ xScrolling}, \param{const bool}{ yScrolling}}
 137
 138 Enable or disable physical scrolling in the given direction. Physical
 139 scrolling is the physical transfer of bits up or down the
 140 screen when a scroll event occurs. If the application scrolls by a
 141 variable amount (e.g. if there are different font sizes) then physical
 142 scrolling will not work, and you should switch it off.
 143
 144 \wxheading{Parameters}
 145
 146 \docparam{xScrolling}{If TRUE, enables physical scrolling in the x direction.}
 147
 148 \docparam{yScrolling}{If TRUE, enables physical scrolling in the y direction.}
 149
 150 \wxheading{Remarks}
 151
 152 Physical scrolling may not be available on all platforms. Where it is available, it is enabled
 153 by default.
 154
 155 \membersection{wxScrolledWindow::GetScrollPixelsPerUnit}\label{wxscrolledwindowgetscrollpixelsperunit}
 156
 157 \constfunc{void}{GetScrollPixelsPerUnit}{\param{int* }{xUnit}, \param{int* }{yUnit}}
 158
 159 Get the number of pixels per scroll unit (line), in each direction, as set
 160 by \helpref{wxScrolledWindow::SetScrollbars}{wxscrolledwindowsetscrollbars}. A value of zero indicates no
 161 scrolling in that direction.
 162
 163 \wxheading{Parameters}
 164
 165 \docparam{xUnit}{Receives the number of pixels per horizontal unit.}
 166
 167 \docparam{yUnit}{Receives the number of pixels per vertical unit.}
 168
 169 \wxheading{See also}
 170
 171 \helpref{wxScrolledWindow::SetScrollbars}{wxscrolledwindowsetscrollbars},\rtfsp
 172 \helpref{wxScrolledWindow::GetVirtualSize}{wxscrolledwindowgetvirtualsize}
 173
 174 \membersection{wxScrolledWindow::GetVirtualSize}\label{wxscrolledwindowgetvirtualsize}
 175
 176 \constfunc{void}{GetVirtualSize}{\param{int* }{x}, \param{int* }{y}}
 177
 178 Gets the size in device units of the scrollable window area (as
 179 opposed to the client size, which is the area of the window currently
 180 visible).
 181
 182 \wxheading{Parameters}
 183
 184 \docparam{x}{Receives the length of the scrollable window, in pixels.}
 185
 186 \docparam{y}{Receives the height of the scrollable window, in pixels.}
 187
 188 \wxheading{Remarks}
 189
 190 Use \helpref{wxDC::DeviceToLogicalX}{wxdcdevicetologicalx} and \helpref{wxDC::DeviceToLogicalY}{wxdcdevicetologicaly}\rtfsp
 191 to translate these units to logical units.
 192
 193 \wxheading{See also}
 194
 195 \helpref{wxScrolledWindow::SetScrollbars}{wxscrolledwindowsetscrollbars},\rtfsp
 196 \helpref{wxScrolledWindow::GetScrollPixelsPerUnit}{wxscrolledwindowgetscrollpixelsperunit}
 197
 198 \membersection{wxScrolledWindow::IsRetained}\label{wxscrolledwindowisretained}
 199
 200 \constfunc{bool}{IsRetained}{\void}
 201
 202 Motif only: TRUE if the window has a backing bitmap.
 203
 204 \membersection{wxScrolledWindow::PrepareDC}\label{wxscrolledwindowpreparedc}
 205
 206 \func{void}{PrepareDC}{\param{wxDC\& }{dc}}
 207
 208 Call this function to prepare the device context for drawing a scrolled image. It
 209 sets the device origin according to the current scroll position.
 210
 211 PrepareDC is called automatically within the default wxScrolledWindow::OnPaint event
 212 handler, so your \helpref{wxScrolledWindow::OnDraw}{wxscrolledwindowondraw} override
 213 will be passed a 'pre-scrolled' device context. However, if you wish to draw from
 214 outside of OnDraw (via OnPaint), or you wish to implement OnPaint yourself, you must
 215 call this function yourself. For example:
 216
 217 \begin{verbatim}
 218 void MyWindow::OnEvent(wxMouseEvent& event)
 219 {
 220   wxClientDC dc(this);
 221   PrepareDC(dc);
 222
 223   dc.SetPen(*wxBLACK_PEN);
 224   float x, y;
 225   event.Position(&x, &y);
 226   if (xpos > -1 && ypos > -1 && event.Dragging())
 227   {
 228     dc.DrawLine(xpos, ypos, x, y);
 229   }
 230   xpos = x;
 231   ypos = y;
 232 }
 233 \end{verbatim}
 234
 235 \membersection{wxScrolledWindow::OnDraw}\label{wxscrolledwindowondraw}
 236
 237 \func{virtual void}{OnDraw}{\param{wxDC\& }{dc}}
 238
 239 Called by the default paint event handler to allow the application to define
 240 painting behaviour without having to worry about calling
 241 \helpref{wxScrolledWindow::PrepareDC}{wxscrolledwindowpreparedc}.
 242
 243 Instead of overriding this function you may also just process the paint event
 244 in the derived class as usual, but then you will have to call PrepareDC()
 245 yourself.
 246
 247 \membersection{wxScrolledWindow::Scroll}\label{wxscrolledwindowscroll}
 248
 249 \func{void}{Scroll}{\param{int}{ x}, \param{int}{ y}}
 250
 251 Scrolls a window so the view start is at the given point.
 252
 253 \wxheading{Parameters}
 254
 255 \docparam{x}{The x position to scroll to, in scroll units.}
 256
 257 \docparam{y}{The y position to scroll to, in scroll units.}
 258
 259 \wxheading{Remarks}
 260
 261 The positions are in scroll units, not pixels, so to convert to pixels you
 262 will have to multiply by the number of pixels per scroll increment.
 263 If either parameter is -1, that position will be ignored (no change in
 264 that direction).
 265
 266 \wxheading{See also}
 267
 268 \helpref{wxScrolledWindow::SetScrollbars}{wxscrolledwindowsetscrollbars},\rtfsp
 269 \helpref{wxScrolledWindow::GetScrollPixelsPerUnit}{wxscrolledwindowgetscrollpixelsperunit}
 270
 271 \membersection{wxScrolledWindow::SetScrollbars}\label{wxscrolledwindowsetscrollbars}
 272
 273 \func{void}{SetScrollbars}{\param{int}{ pixelsPerUnitX}, \param{int}{ pixelsPerUnitY},\rtfsp
 274 \param{int}{ noUnitsX}, \param{int}{ noUnitsY},\rtfsp
 275 \param{int }{xPos = 0}, \param{int}{ yPos = 0}}
 276
 277 Sets up vertical and/or horizontal scrollbars.
 278
 279 \wxheading{Parameters}
 280
 281 \docparam{pixelsPerUnitX}{Pixels per scroll unit in the horizontal direction.}
 282
 283 \docparam{pixelsPerUnitY}{Pixels per scroll unit in the vertical direction.}
 284
 285 \docparam{noUnitsX}{Number of units in the horizontal direction.}
 286
 287 \docparam{noUnitsY}{Number of units in the vertical direction.}
 288
 289 \docparam{xPos}{Position to initialize the scrollbars in the horizontal direction, in scroll units.}
 290
 291 \docparam{yPos}{Position to initialize the scrollbars in the vertical direction, in scroll units.}
 292
 293 \wxheading{Remarks}
 294
 295 The first pair of parameters give the number of pixels per `scroll step', i.e. amount
 296 moved when the up or down scroll arrows are pressed.
 297 The second pair gives the length of scrollbar in scroll steps, which sets the size of the virtual
 298 window.
 299
 300 {\it xPos} and {\it yPos} optionally specify a position to scroll to immediately.
 301
 302 For example, the following gives a window horizontal and vertical
 303 scrollbars with 20 pixels per scroll step, and a size of 50 steps (1000
 304 pixels) in each direction.
 305
 306 \begin{verbatim}
 307   window->SetScrollbars(20, 20, 50, 50);
 308 \end{verbatim}
 309
 310 wxScrolledWindow manages the page size itself,
 311 using the current client window size as the page size.
 312
 313 Note that for more sophisticated scrolling applications, for example where
 314 scroll steps may be variable according to the position in the document, it will be
 315 necessary to derive a new class from wxWindow, overriding {\bf OnSize} and
 316 adjusting the scrollbars appropriately.
 317
 318 \membersection{wxScrolledWindow::ViewStart}\label{wxscrolledwindowviewstart}
 319
 320 \constfunc{void}{ViewStart}{\param{int* }{x}, \param{int* }{ y}}
 321
 322 Get the position at which the visible portion of the window starts.
 323
 324 \wxheading{Parameters}
 325
 326 \docparam{x}{Receives the first visible x position in scroll units.}
 327
 328 \docparam{y}{Receives the first visible y position in scroll units.}
 329
 330 \wxheading{Remarks}
 331
 332 If either of the scrollbars is not at the home position, {\it x} and/or
 333 \rtfsp{\it y} will be greater than zero.  Combined with \helpref{wxWindow::GetClientSize}{wxwindowgetclientsize},
 334 the application can use this function to efficiently redraw only the
 335 visible portion of the window.  The positions are in logical scroll
 336 units, not pixels, so to convert to pixels you will have to multiply
 337 by the number of pixels per scroll increment.
 338
 339 \wxheading{See also}
 340
 341 \helpref{wxScrolledWindow::SetScrollbars}{wxscrolledwindowsetscrollbars}
 342