]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/vscroll.tex
documented return value of wxListCtrl::HitTest
[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: 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. 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::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 repaining 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