]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/vscroll.tex
Build fix after DrawPushButton introduction.
[wxWidgets.git] / 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
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 This is same as \helpref{GetVisibleBegin}{wxvscrolledwindowgetvisiblebegin} and
119 exists only for symmetry with \helpref{GetLastVisibleLine}{wxvscrolledwindowgetlastvisibleline}.
120
121
122 \membersection{wxVScrolledWindow::GetLastVisibleLine}\label{wxvscrolledwindowgetlastvisibleline}
123
124 \constfunc{size\_t}{GetLastVisibleLine}{\void}
125
126 Returns the index of the last currently visible line. Note that this method
127 returns \texttt{(size\_t)-1} (i.e. a huge positive number) if the control is
128 empty so if this is possible you should use \helpref{GetVisibleEnd}{wxvscrolledwindowgetvisibleend}
129 instead.
130
131 \wxheading{See also}
132
133 \helpref{GetFirstVisibleLine}{wxvscrolledwindowgetfirstvisibleline}
134
135
136 \membersection{wxVScrolledWindow::GetLineCount}\label{wxvscrolledwindowgetlinecount}
137
138 \constfunc{size\_t}{GetLineCount}{\void}
139
140 Get the number of lines this window contains (previously set by
141 \helpref{SetLineCount()}{wxvscrolledwindowsetlinecount})
142
143
144 \membersection{wxVScrolledWindow::GetVisibleBegin}\label{wxvscrolledwindowgetvisiblebegin}
145
146 \constfunc{size\_t}{GetVisibleBegin}{\void}
147
148 Returns the index of the first currently visible line.
149
150 \wxheading{See also}
151
152 \helpref{GetVisibleEnd}{wxvscrolledwindowgetvisibleend}
153
154
155 \membersection{wxVScrolledWindow::GetVisibleEnd}\label{wxvscrolledwindowgetvisibleend}
156
157 \constfunc{size\_t}{GetVisibleEnd}{\void}
158
159 Returns the index of the first line after the currently visible one. If the
160 return value is $0$ it means that no lines are currently shown (which only
161 happens if the control is empty). Note that the index returned by this method
162 is not always a valid index as it may be equal to \helpref{GetLineCount}{wxvscrolledwindowgetlinecount}.
163
164 \wxheading{See also}
165
166 \helpref{GetVisibleBegin}{wxvscrolledwindowgetvisiblebegin}
167
168
169 \membersection{wxVScrolledWindow::HitTest}\label{wxvscrolledwindowhittest}
170
171 \constfunc{int}{HitTest}{\param{wxCoord }{x}, \param{wxCoord }{y}}
172
173 \constfunc{int}{HitTest}{\param{const wxPoint\& }{pt}}
174
175 Return the item at the specified (in physical coordinates) position or
176 {\tt wxNOT\_FOUND} if none, i.e. if it is below the last item.
177
178
179 \membersection{wxVScrolledWindow::IsVisible}\label{wxvscrolledwindowisvisible}
180
181 \constfunc{bool}{IsVisible}{\param{size\_t }{line}}
182
183 Returns {\tt true} if the given line is (at least partially) visible or
184 {\tt false} otherwise.
185
186
187 \membersection{wxVScrolledWindow::OnGetLineHeight}\label{wxvscrolledwindowongetlineheight}
188
189 \constfunc{virtual wxCoord}{OnGetLineHeight}{\param{size\_t }{n}}
190
191 This protected virtual function must be overridden in the derived class and it
192 should return the height of the given line in pixels.
193
194 \wxheading{See also}
195
196 \helpref{OnGetLinesHint}{wxvscrolledwindowongetlineshint}
197
198
199 \membersection{wxVScrolledWindow::OnGetLinesHint}\label{wxvscrolledwindowongetlineshint}
200
201 \constfunc{virtual void}{OnGetLinesHint}{\param{size\_t }{lineMin}, \param{size\_t }{lineMax}}
202
203 This function doesn't have to be overridden but it may be useful to do
204 it if calculating the lines heights is a relatively expensive operation
205 as it gives the user code a possibility to calculate several of them at
206 once.
207
208 {\tt OnGetLinesHint()} is normally called just before
209 \helpref{OnGetLineHeight()}{wxvscrolledwindowongetlineheight} but you
210 shouldn't rely on the latter being called for all lines in the interval
211 specified here. It is also possible that OnGetLineHeight() will be
212 called for the lines outside of this interval, so this is really just a
213 hint, not a promise.
214
215 Finally note that {\it lineMin} is inclusive, while {\it lineMax} is exclusive,
216 as usual.
217
218
219 \membersection{wxVScrolledWindow::RefreshLine}\label{wxvscrolledwindowrefreshline}
220
221 \func{void}{RefreshLine}{\param{size\_t }{line}}
222
223 Refreshes the specified line -- it will be redrawn during the next main loop
224 iteration.
225
226 \wxheading{See also}
227
228 \helpref{RefreshLines}{wxvscrolledwindowrefreshlines}
229
230
231 \membersection{wxVScrolledWindow::RefreshLines}\label{wxvscrolledwindowrefreshlines}
232
233 \func{void}{RefreshLines}{\param{size\_t }{from}, \param{size\_t }{to}}
234
235 Refreshes all lines between {\it from} and {\it to}, inclusive. {\it from}
236 should be less than or equal to {\it to}.
237
238 \wxheading{See also}
239
240 \helpref{RefreshLine}{wxvscrolledwindowrefreshline}
241
242
243 \membersection{wxVScrolledWindow::RefreshAll}\label{wxvscrolledwindowrefreshall}
244
245 \func{void}{RefreshAll}{\void}
246
247 This function completely refreshes the control, recalculating the number of
248 items shown on screen and repainting them. It should be called when the values
249 returned by \helpref{OnGetLineHeight}{wxvscrolledwindowongetlineheight} change
250 for some reason and the window must be updated to reflect this.
251
252
253 \membersection{wxVScrolledWindow::ScrollLines}\label{wxvscrolledwindowscrolllines}
254
255 \func{bool}{ScrollLines}{\param{int }{lines}}
256
257 Scroll by the specified number of lines which may be positive (to scroll down)
258 or negative (to scroll up).
259
260 Returns {\tt true} if the window was scrolled, {\tt false} otherwise (for
261 example if we're trying to scroll down but we are already showing the last
262 line).
263
264 \wxheading{See also}
265
266 \helpref{LineUp}{wxwindowlineup}, \helpref{LineDown}{wxwindowlinedown}
267
268
269 \membersection{wxVScrolledWindow::ScrollPages}\label{wxvscrolledwindowscrollpages}
270
271 \func{bool}{ScrollPages}{\param{int }{pages}}
272
273 Scroll by the specified number of pages which may be positive (to scroll down)
274 or negative (to scroll up).
275
276 \wxheading{See also}
277
278 \helpref{ScrollLines}{wxvscrolledwindowscrolllines},\\
279 \helpref{PageUp}{wxwindowpageup}, \helpref{PageDown}{wxwindowpagedown}
280
281
282 \membersection{wxVScrolledWindow::ScrollToLine}\label{wxvscrolledwindowscrolltoline}
283
284 \func{bool}{ScrollToLine}{\param{size\_t }{line}}
285
286 Scroll to the specified line: it will become the first visible line in
287 the window.
288
289 Return {\tt true} if we scrolled the window, {\tt false} if nothing was done.
290
291
292 \membersection{wxVScrolledWindow::SetLineCount}\label{wxvscrolledwindowsetlinecount}
293
294 \func{void}{SetLineCount}{\param{size\_t }{count}}
295
296 Set the number of lines the window contains: the derived class must
297 provide the heights for all lines with indices up to the one given here
298 in its \helpref{OnGetLineHeight()}{wxvscrolledwindowongetlineheight}.
299
300