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