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