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