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