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