docs/latex/wx/vscroll.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        vscroll.tex
   3 %% Purpose:     wxVScrolledWindow documentation
   4 %% Author:      Vadim Zeitlin
   5 %% Modified by:
   6 %% Created:     30.05.03
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) 2003 Vadim Zeitlin <vadim@wxwindows.org>
   9 %% License:     wxWindows license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxVScrolledWindow}}\label{wxvscrolledwindow}
  13
  14 In the name of this class, "V" may stand for "variable" because it can be
  15 used for scrolling lines of variable heights; "virtual" because it is not
  16 necessary to know the heights of all lines in advance -- only those which
  17 are shown on the screen need to be measured; or, even, "vertical" because
  18 this class only supports scrolling in one direction currently (this could
  19 and probably will change in the future however).
  20
  21 In any case, this is a generalization of the
  22 \helpref{wxScrolledWindow}{wxscrolledwindow} class which can be only used when
  23 all lines have the same height. It lacks some other wxScrolledWindow features
  24 however, notably there is currently no support for horizontal scrolling; it
  25 can't scroll another window nor only a rectangle of the window and not its
  26 entire client area.
  27
  28 To use this class, you need to derive from it and implement
  29 \helpref{OnGetLineHeight()}{wxvscrolledwindowongetlineheight} pure virtual
  30 method. You also must call \helpref{SetLineCount}{wxvscrolledwindowsetlinecount}
  31 to let the base class know how many lines it should display but from that
  32 moment on the scrolling is handled entirely by wxVScrolledWindow, you only
  33 need to draw the visible part of contents in your {\tt OnPaint()} method as
  34 usual. You should use \helpref{GetFirstVisibleLine()}{wxvscrolledwindowgetfirstvisibleline}
  35 and \helpref{GetLastVisibleLine()}{wxvscrolledwindowgetlastvisibleline} to
  36 select the lines to display. Note that the device context origin is not shifted
  37 so the first visible line always appears at the point $(0, 0)$ in physical as
  38 well as logical coordinates.
  39
  40 \wxheading{Derived from}
  41
  42 \helpref{wxPanel}{wxpanel}\\
  43 \helpref{wxWindow}{wxwindow}\\
  44 \helpref{wxEvtHandler}{wxevthandler}\\
  45 \helpref{wxObject}{wxobject}
  46
  47 \wxheading{Include files}
  48
  49 <wx/vscroll.h>
  50
  51
  52 \latexignore{\rtfignore{\wxheading{Members}}}
  53
  54
  55 \membersection{wxVScrolledWindow::wxVScrolledWindow}\label{wxvscrolledwindowctor}
  56
  57 \func{}{wxVScrolledWindow}{\param{wxWindow* }{parent}, \param{wxWindowID }{id = wxID\_ANY}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize}, \param{long }{style = 0}, \param{const wxString\& }{name = wxPanelNameStr}}
  58
  59 This is the normal constructor, no need to call Create() after using this one.
  60
  61 Note that {\tt wxVSCROLL} is always automatically added to our style, there is
  62 no need to specify it explicitly.
  63
  64 \func{}{wxVScrolledWindow}{\void}
  65
  66 Default constructor, you must call \helpref{Create()}{wxvscrolledwindowcreate}
  67 later.
  68
  69 \wxheading{Parameters}
  70
  71 \docparam{parent}{The parent window, must not be {\tt NULL}}
  72
  73 \docparam{id}{The identifier of this window, {\tt wxID\_ANY} by default}
  74
  75 \docparam{pos}{The initial window position}
  76
  77 \docparam{size}{The initial window size}
  78
  79 \docparam{style}{The window style. There are no special style bits defined for
  80 this class.}
  81
  82 \docparam{name}{The name for this window; usually not used}
  83
  84
  85 \membersection{wxVScrolledWindow::Create}\label{wxvscrolledwindowcreate}
  86
  87 \func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID }{id = wxID\_ANY}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize}, \param{long }{style = 0}, \param{const wxString\& }{name = wxPanelNameStr}}
  88
  89 Same as the \helpref{non default ctor}{wxvscrolledwindowctor} but returns
  90 status code: {\tt true} if ok, {\tt false} if the window couldn't have been created.
  91
  92 Just as with the ctor above, {\tt wxVSCROLL} style is always used, there is no
  93 need to specify it explicitly.
  94
  95
  96 \membersection{wxVScrolledWindow::EstimateTotalHeight}\label{wxvscrolledwindowestimatetotalheight}
  97
  98 \constfunc{virtual wxCoord}{EstimateTotalHeight}{\void}
  99
 100 This protected function is used internally by wxVScrolledWindow to estimate the
 101 total height of the window when \helpref{SetLineCount}{wxvscrolledwindowsetlinecount}
 102 is called. The default implementation uses the brute force approach if the
 103 number of the items in the control is small enough. Otherwise, it tries to find
 104 the average line height using some lines in the beginning, middle and the end.
 105
 106 If it is undesirable to access all these lines (some of which might be never
 107 shown) just for the total height calculation, you may override the function and
 108 provide your own guess better and/or faster.
 109
 110 Note that although returning a totally wrong value would still work, it risks
 111 to result in very strange scrollbar behaviour so this function should really
 112 try to make the best guess possible.
 113
 114
 115 \membersection{wxVScrolledWindow::GetFirstVisibleLine}\label{wxvscrolledwindowgetfirstvisibleline}
 116
 117 \constfunc{size\_t}{GetFirstVisibleLine}{\void}
 118
 119 Returns the index of the first currently visible line.
 120
 121 This is same as \helpref{GetVisibleBegin}{wxvscrolledwindowgetvisiblebegin} and
 122 exists only for symmetry with \helpref{GetLastVisibleLine}{wxvscrolledwindowgetlastvisibleline}.
 123
 124
 125 \membersection{wxVScrolledWindow::GetLastVisibleLine}\label{wxvscrolledwindowgetlastvisibleline}
 126
 127 \constfunc{size\_t}{GetLastVisibleLine}{\void}
 128
 129 Returns the index of the last currently visible line. Note that this method
 130 returns \texttt{(size\_t)-1} (i.e. a huge positive number) if the control is
 131 empty so if this is possible you should use \helpref{GetVisibleEnd}{wxvscrolledwindowgetvisibleend}
 132 instead.
 133
 134 \wxheading{See also}
 135
 136 \helpref{GetFirstVisibleLine}{wxvscrolledwindowgetfirstvisibleline}
 137
 138
 139 \membersection{wxVScrolledWindow::GetLineCount}\label{wxvscrolledwindowgetlinecount}
 140
 141 \constfunc{size\_t}{GetLineCount}{\void}
 142
 143 Get the number of lines this window contains (previously set by
 144 \helpref{SetLineCount()}{wxvscrolledwindowsetlinecount})
 145
 146
 147 \membersection{wxVScrolledWindow::GetVisibleBegin}\label{wxvscrolledwindowgetvisiblebegin}
 148
 149 \constfunc{size\_t}{GetVisibleBegin}{\void}
 150
 151 Returns the index of the first currently visible line.
 152
 153 \wxheading{See also}
 154
 155 \helpref{GetVisibleEnd}{wxvscrolledwindowgetvisibleend}
 156
 157
 158 \membersection{wxVScrolledWindow::GetVisibleEnd}\label{wxvscrolledwindowgetvisibleend}
 159
 160 \constfunc{size\_t}{GetVisibleEnd}{\void}
 161
 162 Returns the index of the first line after the currently visible one. If the
 163 return value is $0$ it means that no lines are currently shown (which only
 164 happens if the control is empty). Note that the index returned by this method
 165 is not always a valid index as it may be equal to \helpref{GetLineCount}{wxvscrolledwindowgetlinecount}.
 166
 167 \wxheading{See also}
 168
 169 \helpref{GetVisibleBegin}{wxvscrolledwindowgetvisiblebegin}
 170
 171
 172 \membersection{wxVScrolledWindow::HitTest}\label{wxvscrolledwindowhittest}
 173
 174 \constfunc{int}{HitTest}{\param{wxCoord }{x}, \param{wxCoord }{y}}
 175
 176 \constfunc{int}{HitTest}{\param{const wxPoint\& }{pt}}
 177
 178 Return the item at the specified (in physical coordinates) position or
 179 {\tt wxNOT\_FOUND} if none, i.e. if it is below the last item.
 180
 181
 182 \membersection{wxVScrolledWindow::IsVisible}\label{wxvscrolledwindowisvisible}
 183
 184 \constfunc{bool}{IsVisible}{\param{size\_t }{line}}
 185
 186 Returns {\tt true} if the given line is (at least partially) visible or
 187 {\tt false} otherwise.
 188
 189
 190 \membersection{wxVScrolledWindow::OnGetLineHeight}\label{wxvscrolledwindowongetlineheight}
 191
 192 \constfunc{virtual wxCoord}{OnGetLineHeight}{\param{size\_t }{n}}
 193
 194 This protected virtual function must be overridden in the derived class and it
 195 should return the height of the given line in pixels.
 196
 197 \wxheading{See also}
 198
 199 \helpref{OnGetLinesHint}{wxvscrolledwindowongetlineshint}
 200
 201
 202 \membersection{wxVScrolledWindow::OnGetLinesHint}\label{wxvscrolledwindowongetlineshint}
 203
 204 \constfunc{virtual void}{OnGetLinesHint}{\param{size\_t }{lineMin}, \param{size\_t }{lineMax}}
 205
 206 This function doesn't have to be overridden but it may be useful to do
 207 it if calculating the lines heights is a relatively expensive operation
 208 as it gives the user code a possibility to calculate several of them at
 209 once.
 210
 211 {\tt OnGetLinesHint()} is normally called just before
 212 \helpref{OnGetLineHeight()}{wxvscrolledwindowongetlineheight} but you
 213 shouldn't rely on the latter being called for all lines in the interval
 214 specified here. It is also possible that OnGetLineHeight() will be
 215 called for the lines outside of this interval, so this is really just a
 216 hint, not a promise.
 217
 218 Finally note that {\it lineMin} is inclusive, while {\it lineMax} is exclusive,
 219 as usual.
 220
 221
 222 \membersection{wxVScrolledWindow::RefreshLine}\label{wxvscrolledwindowrefreshline}
 223
 224 \func{void}{RefreshLine}{\param{size\_t }{line}}
 225
 226 Refreshes the specified line -- it will be redrawn during the next main loop
 227 iteration.
 228
 229 \wxheading{See also}
 230
 231 \helpref{RefreshLines}{wxvscrolledwindowrefreshlines}
 232
 233
 234 \membersection{wxVScrolledWindow::RefreshLines}\label{wxvscrolledwindowrefreshlines}
 235
 236 \func{void}{RefreshLines}{\param{size\_t }{from}, \param{size\_t }{to}}
 237
 238 Refreshes all lines between {\it from} and {\it to}, inclusive. {\it from}
 239 should be less than or equal to {\it to}.
 240
 241 \wxheading{See also}
 242
 243 \helpref{RefreshLine}{wxvscrolledwindowrefreshline}
 244
 245
 246 \membersection{wxVScrolledWindow::RefreshAll}\label{wxvscrolledwindowrefreshall}
 247
 248 \func{void}{RefreshAll}{\void}
 249
 250 This function completely refreshes the control, recalculating the number of
 251 items shown on screen and repainting them. It should be called when the values
 252 returned by \helpref{OnGetLineHeight}{wxvscrolledwindowongetlineheight} change
 253 for some reason and the window must be updated to reflect this.
 254
 255
 256 \membersection{wxVScrolledWindow::ScrollLines}\label{wxvscrolledwindowscrolllines}
 257
 258 \func{bool}{ScrollLines}{\param{int }{lines}}
 259
 260 Scroll by the specified number of lines which may be positive (to scroll down)
 261 or negative (to scroll up).
 262
 263 Returns {\tt true} if the window was scrolled, {\tt false} otherwise (for
 264 example if we're trying to scroll down but we are already showing the last
 265 line).
 266
 267 \wxheading{See also}
 268
 269 \helpref{LineUp}{wxwindowlineup}, \helpref{LineDown}{wxwindowlinedown}
 270
 271
 272 \membersection{wxVScrolledWindow::ScrollPages}\label{wxvscrolledwindowscrollpages}
 273
 274 \func{bool}{ScrollPages}{\param{int }{pages}}
 275
 276 Scroll by the specified number of pages which may be positive (to scroll down)
 277 or negative (to scroll up).
 278
 279 \wxheading{See also}
 280
 281 \helpref{ScrollLines}{wxvscrolledwindowscrolllines},\\
 282 \helpref{PageUp}{wxwindowpageup}, \helpref{PageDown}{wxwindowpagedown}
 283
 284
 285 \membersection{wxVScrolledWindow::ScrollToLine}\label{wxvscrolledwindowscrolltoline}
 286
 287 \func{bool}{ScrollToLine}{\param{size\_t }{line}}
 288
 289 Scroll to the specified line: it will become the first visible line in
 290 the window.
 291
 292 Return {\tt true} if we scrolled the window, {\tt false} if nothing was done.
 293
 294
 295 \membersection{wxVScrolledWindow::SetLineCount}\label{wxvscrolledwindowsetlinecount}
 296
 297 \func{void}{SetLineCount}{\param{size\_t }{count}}
 298
 299 Set the number of lines the window contains: the derived class must
 300 provide the heights for all lines with indices up to the one given here
 301 in its \helpref{OnGetLineHeight()}{wxvscrolledwindowongetlineheight}.
 302