]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/scrolbar.tex
documented return value of wxListCtrl::HitTest
[wxWidgets.git] / docs / latex / wx / scrolbar.tex
1 \section{\class{wxScrollBar}}\label{wxscrollbar}
2
3 A wxScrollBar is a control that represents a horizontal or
4 vertical scrollbar. It is distinct from the two scrollbars that some windows
5 provide automatically, but the two types of scrollbar share the way
6 events are received.
7
8 \wxheading{Derived from}
9
10 \helpref{wxControl}{wxcontrol}\\
11 \helpref{wxWindow}{wxwindow}\\
12 \helpref{wxEvtHandler}{wxevthandler}\\
13 \helpref{wxObject}{wxobject}
14
15 \wxheading{Include files}
16
17 <wx/scrolbar.h>
18
19 \wxheading{Remarks}
20
21 A scrollbar has the following main attributes: {\it range}, {\it thumb size}, {\it page size}, and {\it position}.
22
23 The range is the total number of units associated with the view represented by the scrollbar.
24 For a table with 15 columns, the range would be 15.
25
26 The thumb size is the number of units that are currently visible. For the table example, the window
27 might be sized so that only 5 columns are currently visible, in which case the application would
28 set the thumb size to 5. When the thumb size becomes the same as or greater than the range,
29 the scrollbar will be automatically hidden on most platforms.
30
31 The page size is the number of units that the scrollbar should scroll by, when `paging' through
32 the data. This value is normally the same as the thumb size length, because
33 it is natural to assume that the visible window size defines a page.
34
35 The scrollbar position is the current thumb position.
36
37 Most applications will find it convenient to provide a function called {\bf AdjustScrollbars} which can
38 be called initially, from an {\bf OnSize} event handler, and whenever the application data
39 changes in size. It will adjust the view, object and page size according
40 to the size of the window and the size of the data.
41
42 \wxheading{Window styles}
43
44 \twocolwidtha{5cm}
45 \begin{twocollist}\itemsep=0pt
46 \twocolitem{\windowstyle{wxSB\_HORIZONTAL}}{Specifies a horizontal scrollbar.}
47 \twocolitem{\windowstyle{wxSB\_VERTICAL}}{Specifies a vertical scrollbar.}
48 \end{twocollist}
49
50 See also \helpref{window styles overview}{windowstyles}.
51
52 \input scrolevt.inc
53
54 \wxheading{See also}
55
56 \helpref{Scrolling overview}{scrollingoverview},\rtfsp
57 \helpref{Event handling overview}{eventhandlingoverview},\rtfsp
58 \helpref{wxScrolledWindow}{wxscrolledwindow}
59
60 \latexignore{\rtfignore{\wxheading{Members}}}
61
62
63 \membersection{wxScrollBar::wxScrollBar}\label{wxscrollbarctor}
64
65 \func{}{wxScrollBar}{\void}
66
67 Default constructor.
68
69 \func{}{wxScrollBar}{\param{wxWindow*}{ parent}, \param{wxWindowID }{id},\rtfsp
70 \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
71 \param{long}{ style = wxSB\_HORIZONTAL}, \param{const wxValidator\& }{validator = wxDefaultValidator},\rtfsp
72 \param{const wxString\& }{name = ``scrollBar"}}
73
74 Constructor, creating and showing a scrollbar.
75
76 \wxheading{Parameters}
77
78 \docparam{parent}{Parent window. Must not be NULL.}
79
80 \docparam{id}{Window identifier. A value of -1 indicates a default value.}
81
82 \docparam{pos}{Window position. If the position (-1, -1) is specified then a default position is chosen.}
83
84 \docparam{size}{Window size. If the default size (-1, -1) is specified then a default size is chosen.}
85
86 \docparam{style}{Window style. See \helpref{wxScrollBar}{wxscrollbar}.}
87
88 \docparam{validator}{Window validator.}
89
90 \docparam{name}{Window name.}
91
92 \wxheading{See also}
93
94 \helpref{wxScrollBar::Create}{wxscrollbarcreate}, \helpref{wxValidator}{wxvalidator}
95
96
97 \membersection{wxScrollBar::\destruct{wxScrollBar}}\label{wxscrollbardtor}
98
99 \func{void}{\destruct{wxScrollBar}}{\void}
100
101 Destructor, destroying the scrollbar.
102
103
104 \membersection{wxScrollBar::Create}\label{wxscrollbarcreate}
105
106 \func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID }{id},\rtfsp
107 \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
108 \param{long}{ style = wxSB\_HORIZONTAL}, \param{const wxValidator\& }{validator = wxDefaultValidator},\rtfsp
109 \param{const wxString\& }{name = ``scrollBar"}}
110
111 Scrollbar creation function called by the scrollbar constructor.
112 See \helpref{wxScrollBar::wxScrollBar}{wxscrollbarctor} for details.
113
114
115 \membersection{wxScrollBar::GetRange}\label{wxscrollbargetrange}
116
117 \constfunc{int}{GetRange}{\void}
118
119 Returns the length of the scrollbar.
120
121 \wxheading{See also}
122
123 \helpref{wxScrollBar::SetScrollbar}{wxscrollbarsetscrollbar}
124
125
126 \membersection{wxScrollBar::GetPageSize}\label{wxscrollbargetpagesize}
127
128 \constfunc{int}{GetPageSize}{\void}
129
130 Returns the page size of the scrollbar. This is the number of scroll units
131 that will be scrolled when the user pages up or down. Often it is the
132 same as the thumb size.
133
134 \wxheading{See also}
135
136 \helpref{wxScrollBar::SetScrollbar}{wxscrollbarsetscrollbar}
137
138
139 \membersection{wxScrollBar::GetThumbPosition}\label{wxscrollbargetthumbposition}
140
141 \constfunc{int}{GetThumbPosition}{\void}
142
143 Returns the current position of the scrollbar thumb.
144
145 \wxheading{See also}
146
147 \helpref{wxScrollBar::SetThumbPosition}{wxscrollbarsetthumbposition}
148
149
150 \membersection{wxScrollBar::GetThumbSize}\label{wxscrollbargetthumbsize}
151
152 \constfunc{int}{GetThumbSize}{\void}
153
154 Returns the thumb or `view' size.
155
156 \wxheading{See also}
157
158 \helpref{wxScrollBar::SetScrollbar}{wxscrollbarsetscrollbar}
159
160 \begin{comment}
161
162 \membersection{wxScrollBar::SetObjectLength}\label{wxscrollbarsetobjectlength}
163
164 \func{void}{SetObjectLength}{\param{int}{ objectLength}}
165
166 Sets the object length for the scrollbar. This is the total object size (virtual size). You must
167 call \helpref{SetViewLength}{wxscrollbarsetviewlength} {\it before} calling SetObjectLength.
168
169 \wxheading{Parameters}
170
171 \docparam{objectLength}{The object length of the scrollbar.}
172
173 \wxheading{Remarks}
174
175 Example: you are implementing scrollbars on a text window, where text lines have a maximum width
176 of 100 characters. Your text window has a current width of 60 characters. So the view length is 60,
177 and the object length is 100. The scrollbar will then enable you to scroll to see the other 40 characters.
178
179 You will need to call {\bf SetViewLength} and {\bf SetObjectLength} whenever there
180 is a change in the size of the window (the view size) or the size of the
181 contents (the object length).
182
183 \wxheading{See also}
184
185 \helpref{wxScrollBar::GetObjectLength}{wxscrollbargetobjectlength}
186
187
188 \membersection{wxScrollBar::SetPageSize}\label{wxscrollbarsetpagesize}
189
190 \func{void}{SetPageSize}{\param{int}{ pageSize}}
191
192 Sets the page size for the scrollbar. This is the number of scroll units which are scrolled when the
193 user pages down (clicks on the scrollbar outside the thumbtrack area).
194
195 \wxheading{Parameters}
196
197 \docparam{pageSize}{The page size in scroll units.}
198
199 \wxheading{Remarks}
200
201 At present, this needs to be called {\it before} other set functions.
202
203 \wxheading{See also}
204
205 \helpref{wxScrollBar::GetPageSize}{wxscrollbargetpagesize}
206 \end{comment}
207
208
209 \membersection{wxScrollBar::SetThumbPosition}\label{wxscrollbarsetthumbposition}
210
211 \func{void}{SetThumbPosition}{\param{int}{ viewStart}}
212
213 Sets the position of the scrollbar.
214
215 \wxheading{Parameters}
216
217 \docparam{viewStart}{The position of the scrollbar thumb.}
218
219 \wxheading{See also}
220
221 \helpref{wxScrollBar::GetThumbPosition}{wxscrollbargetthumbposition}
222
223
224 \membersection{wxScrollBar::SetScrollbar}\label{wxscrollbarsetscrollbar}
225
226 \func{virtual void}{SetScrollbar}{\param{int }{position},\rtfsp
227 \param{int }{thumbSize}, \param{int }{range},\rtfsp
228 \param{int }{pageSize},\rtfsp
229 \param{const bool }{refresh = true}}
230
231 Sets the scrollbar properties.
232
233 \wxheading{Parameters}
234
235 \docparam{position}{The position of the scrollbar in scroll units.}
236
237 \docparam{thumbSize}{The size of the thumb, or visible portion of the scrollbar, in scroll units.}
238
239 \docparam{range}{The maximum position of the scrollbar.}
240
241 \docparam{pageSize}{The size of the page size in scroll units. This is the number of units
242 the scrollbar will scroll when it is paged up or down. Often it is the same as
243 the thumb size.}
244
245 \docparam{refresh}{true to redraw the scrollbar, false otherwise.}
246
247 \wxheading{Remarks}
248
249 Let's say you wish to display 50 lines of text, using the same font.
250 The window is sized so that you can only see 16 lines at a time.
251
252 You would use:
253
254 {\small%
255 \begin{verbatim}
256 scrollbar->SetScrollbar(0, 16, 50, 15);
257 \end{verbatim}
258 }
259
260 The page size is 1 less than the thumb size so that the last line of the previous
261 page will be visible on the next page, to help orient the user.
262
263 Note that with the window at this size, the thumb position can never go
264 above 50 minus 16, or 34.
265
266 You can determine how many lines are currently visible by dividing the current view
267 size by the character height in pixels.
268
269 When defining your own scrollbar behaviour, you will always need to recalculate
270 the scrollbar settings when the window size changes. You could therefore put your
271 scrollbar calculations and SetScrollbar
272 call into a function named AdjustScrollbars, which can be called initially and also
273 from a \helpref{wxSizeEvent}{wxsizeevent} event handler function.
274
275 \wxheading{See also}
276
277 \helpref{Scrolling overview}{scrollingoverview},\rtfsp
278 \helpref{wxWindow::SetScrollbar}{wxwindowsetscrollbar}, \helpref{wxScrolledWindow}{wxscrolledwindow}
279
280
281 \begin{comment}
282
283 \membersection{wxScrollBar::SetViewLength}\label{wxscrollbarsetviewlength}
284
285 \func{void}{SetViewLength}{\param{int}{ viewLength}}
286
287 Sets the view length for the scrollbar.
288
289 \wxheading{Parameters}
290
291 \docparam{viewLength}{View length.}
292
293 \wxheading{See also}
294
295 \helpref{wxScrollBar::GetViewLength}{wxscrollbargetviewlength}
296 \end{comment}
297