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:     wxWidgets 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
  44 \wxheading{Include files}
  45
  46 <wx/vscroll.h>
  47
  48
  49 \latexignore{\rtfignore{\wxheading{Members}}}
  50
  51
  52 \membersection{wxVScrolledWindow::wxVScrolledWindow}\label{wxvscrolledwindowctor}
  53
  54 \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}}
  55
  56 This is the normal constructor, no need to call Create() after using this one.
  57
  58 Note that {\tt wxVSCROLL} is always automatically added to our style, there is
  59 no need to specify it explicitly.
  60
  61 \func{}{wxVScrolledWindow}{\void}
  62
  63 Default constructor, you must call \helpref{Create()}{wxvscrolledwindowcreate}
  64 later.
  65
  66 \wxheading{Parameters}
  67
  68 \docparam{parent}{The parent window, must not be {\tt NULL}}
  69
  70 \docparam{id}{The identifier of this window, {\tt wxID\_ANY} by default}
  71
  72 \docparam{pos}{The initial window position}
  73
  74 \docparam{size}{The initial window size}
  75
  76 \docparam{style}{The window style. There are no special style bits defined for
  77 this class.}
  78
  79 \docparam{name}{The name for this window; usually not used}
  80
  81
  82 \membersection{wxVScrolledWindow::Create}\label{wxvscrolledwindowcreate}
  83
  84 \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}}
  85
  86 Same as the \helpref{non default ctor}{wxvscrolledwindowctor} but returns
  87 status code: {\tt true} if ok, {\tt false} if the window couldn't have been created.
  88
  89 Just as with the ctor above, {\tt wxVSCROLL} style is always used, there is no
  90 need to specify it explicitly.
  91
  92
  93 \membersection{wxVScrolledWindow::EstimateTotalHeight}\label{wxvscrolledwindowestimatetotalheight}
  94
  95 \constfunc{virtual wxCoord}{EstimateTotalHeight}{\void}
  96
  97 This protected function is used internally by wxVScrolledWindow to estimate the
  98 total height of the window when \helpref{SetLineCount}{wxvscrolledwindowsetlinecount}
  99 is called. The default implementation uses the brute force approach if the
 100 number of the items in the control is small enough. Otherwise, it tries to find
 101 the average line height using some lines in the beginning, middle and the end.
 102
 103 If it is undesirable to access all these lines (some of which might be never
 104 shown) just for the total height calculation, you may override the function and
 105 provide your own guess better and/or faster.
 106
 107 Note that although returning a totally wrong value would still work, it risks
 108 to result in very strange scrollbar behaviour so this function should really
 109 try to make the best guess possible.
 110
 111
 112 \membersection{wxVScrolledWindow::GetFirstVisibleLine}\label{wxvscrolledwindowgetfirstvisibleline}
 113
 114 \constfunc{size\_t}{GetFirstVisibleLine}{\void}
 115
 116 Returns the index of the first currently visible line.
 117
 118
 119 \membersection{wxVScrolledWindow::GetLastVisibleLine}\label{wxvscrolledwindowgetlastvisibleline}
 120
 121 \constfunc{size\_t}{GetLastVisibleLine}{\void}
 122
 123 Returns the index of the last currently visible line.
 124
 125
 126 \membersection{wxVScrolledWindow::GetLineCount}\label{wxvscrolledwindowgetlinecount}
 127
 128 \constfunc{size\_t}{GetLineCount}{\void}
 129
 130 Get the number of lines this window contains (previously set by
 131 \helpref{SetLineCount()}{wxvscrolledwindowsetlinecount})
 132
 133
 134 \membersection{wxVScrolledWindow::HitTest}\label{wxvscrolledwindowhittest}
 135
 136 \constfunc{int}{HitTest}{\param{wxCoord }{x}, \param{wxCoord }{y}}
 137
 138 \constfunc{int}{HitTest}{\param{const wxPoint\& }{pt}}
 139
 140 Return the item at the specified (in physical coordinates) position or
 141 {\tt wxNOT\_FOUND} if none, i.e. if it is below the last item.
 142
 143
 144 \membersection{wxVScrolledWindow::IsVisible}\label{wxvscrolledwindowisvisible}
 145
 146 \constfunc{bool}{IsVisible}{\param{size\_t }{line}}
 147
 148 Returns {\tt true} if the given line is (at least partially) visible or
 149 {\tt false} otherwise.
 150
 151
 152 \membersection{wxVScrolledWindow::OnGetLineHeight}\label{wxvscrolledwindowongetlineheight}
 153
 154 \constfunc{wxCoord}{OnGetLineHeight}{\param{size\_t }{n}}
 155
 156 This protected virtual function must be overridden in the derived class and it
 157 should return the height of the given line in pixels.
 158
 159 \wxheading{See also}
 160
 161 \helpref{OnGetLinesHint}{wxvscrolledwindowongetlineshint}
 162
 163
 164 \membersection{wxVScrolledWindow::OnGetLinesHint}\label{wxvscrolledwindowongetlineshint}
 165
 166 \constfunc{void}{OnGetLinesHint}{\param{size\_t }{lineMin}, \param{size\_t }{lineMax}}
 167
 168 This function doesn't have to be overridden but it may be useful to do
 169 it if calculating the lines heights is a relatively expensive operation
 170 as it gives the user code a possibility to calculate several of them at
 171 once.
 172
 173 {\tt OnGetLinesHint()} is normally called just before
 174 \helpref{OnGetLineHeight()}{wxvscrolledwindowongetlineheight} but you
 175 shouldn't rely on the latter being called for all lines in the interval
 176 specified here. It is also possible that OnGetLineHeight() will be
 177 called for the lines outside of this interval, so this is really just a
 178 hint, not a promise.
 179
 180 Finally note that {\it lineMin} is inclusive, while {\it lineMax} is exclusive,
 181 as usual.
 182
 183
 184 \membersection{wxVScrolledWindow::RefreshLine}\label{wxvscrolledwindowrefreshline}
 185
 186 \func{void}{RefreshLine}{\param{size\_t }{line}}
 187
 188 Refreshes the specified line -- it will be redrawn during the next main loop
 189 iteration.
 190
 191 \wxheading{See also}
 192
 193 \helpref{RefreshLines}{wxvscrolledwindowrefreshlines}
 194
 195
 196 \membersection{wxVScrolledWindow::RefreshLines}\label{wxvscrolledwindowrefreshlines}
 197
 198 \func{void}{RefreshLines}{\param{size\_t }{from}, \param{size\_t }{to}}
 199
 200 Refreshes all lines between {\it from} and {\it to}, inclusive. {\it from}
 201 should be less than or equal to {\it to}.
 202
 203 \wxheading{See also}
 204
 205 \helpref{RefreshLine}{wxvscrolledwindowrefreshline}
 206
 207
 208 \membersection{wxVScrolledWindow::RefreshAll}\label{wxvscrolledwindowrefreshall}
 209
 210 \func{void}{RefreshAll}{\void}
 211
 212 This function completely refreshes the control, recalculating the number of
 213 items shown on screen and repainting them. It should be called when the values
 214 returned by \helpref{OnGetLineHeight}{wxvscrolledwindowongetlineheight} change
 215 for some reason and the window must be updated to reflect this.
 216
 217
 218 \membersection{wxVScrolledWindow::ScrollLines}\label{wxvscrolledwindowscrolllines}
 219
 220 \func{bool}{ScrollLines}{\param{int }{lines}}
 221
 222 Scroll by the specified number of lines which may be positive (to scroll down)
 223 or negative (to scroll up).
 224
 225 Returns {\tt true} if the window was scrolled, {\tt false} otherwise (for
 226 example if we're trying to scroll down but we are already showing the last
 227 line).
 228
 229 \wxheading{See also}
 230
 231 \helpref{LineUp}{wxwindowlineup}, \helpref{LineDown}{wxwindowlinedown}
 232
 233
 234 \membersection{wxVScrolledWindow::ScrollPages}\label{wxvscrolledwindowscrollpages}
 235
 236 \func{bool}{ScrollPages}{\param{int }{pages}}
 237
 238 Scroll by the specified number of pages which may be positive (to scroll down)
 239 or negative (to scroll up).
 240
 241 \wxheading{See also}
 242
 243 \helpref{ScrollLines}{wxvscrolledwindowscrolllines},\\
 244 \helpref{PageUp}{wxwindowpageup}, \helpref{PageDown}{wxwindowpagedown}
 245
 246
 247 \membersection{wxVScrolledWindow::ScrollToLine}\label{wxvscrolledwindowscrolltoline}
 248
 249 \func{bool}{ScrollToLine}{\param{size\_t }{line}}
 250
 251 Scroll to the specified line: it will become the first visible line in
 252 the window.
 253
 254 Return {\tt true} if we scrolled the window, {\tt false} if nothing was done.
 255
 256
 257 \membersection{wxVScrolledWindow::SetLineCount}\label{wxvscrolledwindowsetlinecount}
 258
 259 \func{void}{SetLineCount}{\param{size\_t }{count}}
 260
 261 Set the number of lines the window contains: the derived class must
 262 provide the heights for all lines with indices up to the one given here
 263 in its \helpref{OnGetLineHeight()}{wxvscrolledwindowongetlineheight}.
 264
 265