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'll 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, 0, \&xx, \&yy) will return 10 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 \membersection{wxScrolledWindow::CalcUnscrolledPosition}\label{wxscrolledwindowcalcunscrolledposition}
 125
 126 \constfunc{void}{CalcUnscrolledPosition}{
 127    \param{int }{x},
 128    \param{int }{y},
 129    \param{int *}{xx}
 130    \param{int *}{yy}}
 131
 132 Translates the device coordinates to the logical ones. For example, if a window is
 133 scrolled 10 pixels to the bottom, the device coordinates of the origin are (0, 0)
 134 (as always), but the logical coordinates are (0, 10) and so the call to
 135 CalcUnscrolledPosition(0, 10, \&xx, \&yy) will return 0 in yy.
 136
 137 \wxheading{See also}
 138
 139 \helpref{CalcScrolledPosition}{wxscrolledwindowcalcscrolledposition}
 140
 141 \pythonnote{The wxPython version of this methods accepts only two
 142 parameters and returns xx and yy as a tuple of values.}
 143
 144 \membersection{wxScrolledWindow::Create}\label{wxscrolledwindowcreate}
 145
 146 \func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID }{id = -1},\rtfsp
 147 \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
 148 \param{long}{ style = wxHSCROLL \pipe wxVSCROLL}, \param{const wxString\& }{name = ``scrolledWindow"}}
 149
 150 Creates the window for two-step construction. Derived classes
 151 should call or replace this function. See \helpref{wxScrolledWindow::wxScrolledWindow}{wxscrolledwindowconstr}\rtfsp
 152 for details.
 153
 154 \membersection{wxScrolledWindow::EnableScrolling}\label{wxscrolledwindowenablescrolling}
 155
 156 \func{void}{EnableScrolling}{\param{const bool}{ xScrolling}, \param{const bool}{ yScrolling}}
 157
 158 Enable or disable physical scrolling in the given direction. Physical
 159 scrolling is the physical transfer of bits up or down the
 160 screen when a scroll event occurs. If the application scrolls by a
 161 variable amount (e.g. if there are different font sizes) then physical
 162 scrolling will not work, and you should switch it off. Note that you
 163 will have to reposition child windows yourself, if physical scrolling
 164 is disabled.
 165
 166 \wxheading{Parameters}
 167
 168 \docparam{xScrolling}{If TRUE, enables physical scrolling in the x direction.}
 169
 170 \docparam{yScrolling}{If TRUE, enables physical scrolling in the y direction.}
 171
 172 \wxheading{Remarks}
 173
 174 Physical scrolling may not be available on all platforms. Where it is available, it is enabled
 175 by default.
 176
 177 \membersection{wxScrolledWindow::GetScrollPixelsPerUnit}\label{wxscrolledwindowgetscrollpixelsperunit}
 178
 179 \constfunc{void}{GetScrollPixelsPerUnit}{\param{int* }{xUnit}, \param{int* }{yUnit}}
 180
 181 Get the number of pixels per scroll unit (line), in each direction, as set
 182 by \helpref{wxScrolledWindow::SetScrollbars}{wxscrolledwindowsetscrollbars}. A value of zero indicates no
 183 scrolling in that direction.
 184
 185 \wxheading{Parameters}
 186
 187 \docparam{xUnit}{Receives the number of pixels per horizontal unit.}
 188
 189 \docparam{yUnit}{Receives the number of pixels per vertical unit.}
 190
 191 \wxheading{See also}
 192
 193 \helpref{wxScrolledWindow::SetScrollbars}{wxscrolledwindowsetscrollbars},\rtfsp
 194 \helpref{wxScrolledWindow::GetVirtualSize}{wxscrolledwindowgetvirtualsize}
 195
 196 \pythonnote{The wxPython version of this methods accepts no
 197 parameters and returns a tuple of values for xUnit and yUnit.}
 198
 199
 200 \membersection{wxScrolledWindow::GetVirtualSize}\label{wxscrolledwindowgetvirtualsize}
 201
 202 \constfunc{void}{GetVirtualSize}{\param{int* }{x}, \param{int* }{y}}
 203
 204 Gets the size in device units of the scrollable window area (as
 205 opposed to the client size, which is the area of the window currently
 206 visible).
 207
 208 \wxheading{Parameters}
 209
 210 \docparam{x}{Receives the length of the scrollable window, in pixels.}
 211
 212 \docparam{y}{Receives the height of the scrollable window, in pixels.}
 213
 214 \wxheading{Remarks}
 215
 216 Use \helpref{wxDC::DeviceToLogicalX}{wxdcdevicetologicalx} and \helpref{wxDC::DeviceToLogicalY}{wxdcdevicetologicaly}\rtfsp
 217 to translate these units to logical units.
 218
 219 \wxheading{See also}
 220
 221 \helpref{wxScrolledWindow::SetScrollbars}{wxscrolledwindowsetscrollbars},\rtfsp
 222 \helpref{wxScrolledWindow::GetScrollPixelsPerUnit}{wxscrolledwindowgetscrollpixelsperunit}
 223
 224 \pythonnote{The wxPython version of this methods accepts no
 225 parameters and returns a tuple of values for x and y.}
 226
 227 \membersection{wxScrolledWindow::IsRetained}\label{wxscrolledwindowisretained}
 228
 229 \constfunc{bool}{IsRetained}{\void}
 230
 231 Motif only: TRUE if the window has a backing bitmap.
 232
 233 \membersection{wxScrolledWindow::PrepareDC}\label{wxscrolledwindowpreparedc}
 234
 235 \func{void}{PrepareDC}{\param{wxDC\& }{dc}}
 236
 237 Call this function to prepare the device context for drawing a scrolled image. It
 238 sets the device origin according to the current scroll position.
 239
 240 PrepareDC is called automatically within the default wxScrolledWindow::OnPaint event
 241 handler, so your \helpref{wxScrolledWindow::OnDraw}{wxscrolledwindowondraw} override
 242 will be passed a 'pre-scrolled' device context. However, if you wish to draw from
 243 outside of OnDraw (via OnPaint), or you wish to implement OnPaint yourself, you must
 244 call this function yourself. For example:
 245
 246 \begin{verbatim}
 247 void MyWindow::OnEvent(wxMouseEvent& event)
 248 {
 249   wxClientDC dc(this);
 250   PrepareDC(dc);
 251
 252   dc.SetPen(*wxBLACK_PEN);
 253   float x, y;
 254   event.Position(&x, &y);
 255   if (xpos > -1 && ypos > -1 && event.Dragging())
 256   {
 257     dc.DrawLine(xpos, ypos, x, y);
 258   }
 259   xpos = x;
 260   ypos = y;
 261 }
 262 \end{verbatim}
 263
 264 \membersection{wxScrolledWindow::OnDraw}\label{wxscrolledwindowondraw}
 265
 266 \func{virtual void}{OnDraw}{\param{wxDC\& }{dc}}
 267
 268 Called by the default paint event handler to allow the application to define
 269 painting behaviour without having to worry about calling
 270 \helpref{wxScrolledWindow::PrepareDC}{wxscrolledwindowpreparedc}.
 271
 272 Instead of overriding this function you may also just process the paint event
 273 in the derived class as usual, but then you will have to call PrepareDC()
 274 yourself.
 275
 276 \membersection{wxScrolledWindow::Scroll}\label{wxscrolledwindowscroll}
 277
 278 \func{void}{Scroll}{\param{int}{ x}, \param{int}{ y}}
 279
 280 Scrolls a window so the view start is at the given point.
 281
 282 \wxheading{Parameters}
 283
 284 \docparam{x}{The x position to scroll to, in scroll units.}
 285
 286 \docparam{y}{The y position to scroll to, in scroll units.}
 287
 288 \wxheading{Remarks}
 289
 290 The positions are in scroll units, not pixels, so to convert to pixels you
 291 will have to multiply by the number of pixels per scroll increment.
 292 If either parameter is -1, that position will be ignored (no change in
 293 that direction).
 294
 295 \wxheading{See also}
 296
 297 \helpref{wxScrolledWindow::SetScrollbars}{wxscrolledwindowsetscrollbars},\rtfsp
 298 \helpref{wxScrolledWindow::GetScrollPixelsPerUnit}{wxscrolledwindowgetscrollpixelsperunit}
 299
 300 \membersection{wxScrolledWindow::SetScrollbars}\label{wxscrolledwindowsetscrollbars}
 301
 302 \func{void}{SetScrollbars}{\param{int}{ pixelsPerUnitX}, \param{int}{ pixelsPerUnitY},\rtfsp
 303 \param{int}{ noUnitsX}, \param{int}{ noUnitsY},\rtfsp
 304 \param{int }{xPos = 0}, \param{int}{ yPos = 0},\rtfsp
 305 \param{bool }{noRefresh = FALSE}}
 306
 307 Sets up vertical and/or horizontal scrollbars.
 308
 309 \wxheading{Parameters}
 310
 311 \docparam{pixelsPerUnitX}{Pixels per scroll unit in the horizontal direction.}
 312
 313 \docparam{pixelsPerUnitY}{Pixels per scroll unit in the vertical direction.}
 314
 315 \docparam{noUnitsX}{Number of units in the horizontal direction.}
 316
 317 \docparam{noUnitsY}{Number of units in the vertical direction.}
 318
 319 \docparam{xPos}{Position to initialize the scrollbars in the horizontal direction, in scroll units.}
 320
 321 \docparam{yPos}{Position to initialize the scrollbars in the vertical direction, in scroll units.}
 322
 323 \docparam{noRefresh}{Will not refresh window if TRUE.}
 324
 325 \wxheading{Remarks}
 326
 327 The first pair of parameters give the number of pixels per `scroll step', i.e. amount
 328 moved when the up or down scroll arrows are pressed.
 329 The second pair gives the length of scrollbar in scroll steps, which sets the size of the virtual
 330 window.
 331
 332 {\it xPos} and {\it yPos} optionally specify a position to scroll to immediately.
 333
 334 For example, the following gives a window horizontal and vertical
 335 scrollbars with 20 pixels per scroll step, and a size of 50 steps (1000
 336 pixels) in each direction.
 337
 338 \begin{verbatim}
 339   window->SetScrollbars(20, 20, 50, 50);
 340 \end{verbatim}
 341
 342 wxScrolledWindow manages the page size itself,
 343 using the current client window size as the page size.
 344
 345 Note that for more sophisticated scrolling applications, for example where
 346 scroll steps may be variable according to the position in the document, it will be
 347 necessary to derive a new class from wxWindow, overriding {\bf OnSize} and
 348 adjusting the scrollbars appropriately.
 349
 350 \membersection{wxScrolledWindow::SetTargetWindow}\label{wxscrolledwindowsettargetwindow}
 351
 352 \func{void}{SetTargetWindow}{\param{wxWindow* }{window}}
 353
 354 Call this function to tell wxScrolledWindow to perform the actually scrolling on
 355 a different window (not on itself).
 356
 357 \membersection{wxScrolledWindow::GetViewStart}\label{wxscrolledwindowgetviewstart}
 358
 359 \constfunc{void}{GetViewStart}{\param{int* }{x}, \param{int* }{ y}}
 360
 361 Get the position at which the visible portion of the window starts.
 362
 363 \wxheading{Parameters}
 364
 365 \docparam{x}{Receives the first visible x position in scroll units.}
 366
 367 \docparam{y}{Receives the first visible y position in scroll units.}
 368
 369 \wxheading{Remarks}
 370
 371 If either of the scrollbars is not at the home position, {\it x} and/or
 372 \rtfsp{\it y} will be greater than zero.  Combined with \helpref{wxWindow::GetClientSize}{wxwindowgetclientsize},
 373 the application can use this function to efficiently redraw only the
 374 visible portion of the window.  The positions are in logical scroll
 375 units, not pixels, so to convert to pixels you will have to multiply
 376 by the number of pixels per scroll increment.
 377
 378 \wxheading{See also}
 379
 380 \helpref{wxScrolledWindow::SetScrollbars}{wxscrolledwindowsetscrollbars}
 381
 382 \pythonnote{The wxPython version of this methods accepts no
 383 parameters and returns a tuple of values for x and y.}
 384