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. ote 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::GetFirstVisibleLine}\label{wxvscrolledwindowgetfirstvisibleline}
  94
  95 \constfunc{size\_t}{GetFirstVisibleLine}{\void}
  96
  97 Returns the index of the first currently visible line.
  98
  99
 100 \membersection{wxVScrolledWindow::GetLastVisibleLine}\label{wxvscrolledwindowgetlastvisibleline}
 101
 102 \constfunc{size\_t}{GetLastVisibleLine}{\void}
 103
 104 Returns the index of the last currently visible line.
 105
 106
 107 \membersection{wxVScrolledWindow::GetLineCount}\label{wxvscrolledwindowgetlinecount}
 108
 109 \constfunc{size\_t}{GetLineCount}{\void}
 110
 111 Get the number of lines this window contains (previously set by
 112 \helpref{SetLineCount()}{wxvscrolledwindowsetlinecount})
 113
 114
 115 \membersection{wxVScrolledWindow::HitTest}\label{wxvscrolledwindowhittest}
 116
 117 \constfunc{int}{HitTest}{\param{wxCoord }{x}, \param{wxCoord }{y}}
 118
 119 \constfunc{int}{HitTest}{\param{const wxPoint\& }{pt}}
 120
 121 Return the item at the specified (in physical coordinates) position or
 122 {\tt wxNOT\_FOUND} if none, i.e. if it is below the last item.
 123
 124
 125 \membersection{wxVScrolledWindow::IsVisible}\label{wxvscrolledwindowisvisible}
 126
 127 \constfunc{bool}{IsVisible}{\param{size\_t }{line}}
 128
 129 Returns {\tt true} if the given line is (at least partially) visible or
 130 {\tt false} otherwise.
 131
 132
 133 \membersection{wxVScrolledWindow::OnGetLineHeight}\label{wxvscrolledwindowongetlineheight}
 134
 135 \constfunc{wxCoord}{OnGetLineHeight}{\param{size\_t }{n}}
 136
 137 This protected virtual function must be overridden in the derived class and it
 138 should return the height of the given line in pixels.
 139
 140 \wxheading{See also}
 141
 142 \helpref{OnGetLinesHint}{wxvscrolledwindowongetlineshint}
 143
 144
 145 \membersection{wxVScrolledWindow::OnGetLinesHint}\label{wxvscrolledwindowongetlineshint}
 146
 147 \constfunc{void}{OnGetLinesHint}{\param{size\_t }{lineMin}, \param{size\_t }{lineMax}}
 148
 149 This function doesn't have to be overridden but it may be useful to do
 150 it if calculating the lines heights is a relatively expensive operation
 151 as it gives the user code a possibility to calculate several of them at
 152 once.
 153
 154 {\tt OnGetLinesHint()} is normally called just before
 155 \helpref{OnGetLineHeight()}{wxvscrolledwindowongetlineheight} but you
 156 shouldn't rely on the latter being called for all lines in the interval
 157 specified here. It is also possible that OnGetLineHeight() will be
 158 called for the lines outside of this interval, so this is really just a
 159 hint, not a promise.
 160
 161 Finally note that {\it lineMin} is inclusive, while {\it lineMax} is exclusive,
 162 as usual.
 163
 164
 165 \membersection{wxVScrolledWindow::RefreshLine}\label{wxvscrolledwindowrefreshline}
 166
 167 \func{void}{RefreshLine}{\param{size\_t }{line}}
 168
 169 Refreshes the specified line -- it will be redrawn during the next main loop
 170 iteration.
 171
 172 \wxheading{See also}
 173
 174 \helpref{RefreshLines}{wxvscrolledwindowrefreshlines}
 175
 176
 177 \membersection{wxVScrolledWindow::RefreshLines}\label{wxvscrolledwindowrefreshlines}
 178
 179 \func{void}{RefreshLines}{\param{size\_t }{from}, \param{size\_t }{to}}
 180
 181 Refreshes all lines between {\it from} and {\it to}, inclusive. {\it from}
 182 should be less than or equal to {\it to}.
 183
 184 \wxheading{See also}
 185
 186 \helpref{RefreshLine}{wxvscrolledwindowrefreshline}
 187
 188
 189 \membersection{wxVScrolledWindow::RefreshAll}\label{wxvscrolledwindowrefreshall}
 190
 191 \func{void}{RefreshAll}{\void}
 192
 193 This function completely refreshes the control, recalculating the number of
 194 items shown on screen and repaining them. It should be called when the values
 195 returned by \helpref{OnGetLineHeight}{wxvscrolledwindowongetlineheight} change
 196 for some reason and the window must be updated to reflect this.
 197
 198
 199 \membersection{wxVScrolledWindow::ScrollLines}\label{wxvscrolledwindowscrolllines}
 200
 201 \func{bool}{ScrollLines}{\param{int }{lines}}
 202
 203 Scroll by the specified number of lines which may be positive (to scroll down)
 204 or negative (to scroll up).
 205
 206 Returns {\tt true} if the window was scrolled, {\tt false} otherwise (for
 207 example if we're trying to scroll down but we are already showing the last
 208 line).
 209
 210 \wxheading{See also}
 211
 212 \helpref{LineUp}{wxwindowlineup}, \helpref{LineDown}{wxwindowlinedown}
 213
 214
 215 \membersection{wxVScrolledWindow::ScrollPages}\label{wxvscrolledwindowscrollpages}
 216
 217 \func{bool}{ScrollPages}{\param{int }{pages}}
 218
 219 Scroll by the specified number of pages which may be positive (to scroll down)
 220 or negative (to scroll up).
 221
 222 \wxheading{See also}
 223
 224 \helpref{ScrollLines}{wxvscrolledwindowscrolllines},\\
 225 \helpref{PageUp}{wxwindowpageup}, \helpref{PageDown}{wxwindowpagedown}
 226
 227
 228 \membersection{wxVScrolledWindow::ScrollToLine}\label{wxvscrolledwindowscrolltoline}
 229
 230 \func{bool}{ScrollToLine}{\param{size\_t }{line}}
 231
 232 Scroll to the specified line: it will become the first visible line in
 233 the window.
 234
 235 Return {\tt true} if we scrolled the window, {\tt false} if nothing was done.
 236
 237
 238 \membersection{wxVScrolledWindow::SetLineCount}\label{wxvscrolledwindowsetlinecount}
 239
 240 \func{void}{SetLineCount}{\param{size\_t }{count}}
 241
 242 Set the number of lines the window contains: the derived class must
 243 provide the heights for all lines with indices up to the one given here
 244 in its \helpref{OnGetLineHeight()}{wxvscrolledwindowongetlineheight}.
 245
 246