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