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