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