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