]>
Commit | Line | Data |
---|---|---|
1 | ///////////////////////////////////////////////////////////////////////////// | |
2 | // Name: slider.h | |
3 | // Purpose: interface of wxSlider | |
4 | // Author: wxWidgets team | |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | /** | |
10 | @class wxSlider | |
11 | ||
12 | A slider is a control with a handle which can be pulled back and forth to | |
13 | change the value. | |
14 | ||
15 | On Windows, the track bar control is used. | |
16 | ||
17 | Slider events are handled in the same way as a scrollbar. | |
18 | ||
19 | @beginStyleTable | |
20 | @style{wxSL_HORIZONTAL} | |
21 | Displays the slider horizontally (this is the default). | |
22 | @style{wxSL_VERTICAL} | |
23 | Displays the slider vertically. | |
24 | @style{wxSL_AUTOTICKS} | |
25 | Displays tick marks. Windows only. | |
26 | @style{wxSL_MIN_MAX_LABELS} | |
27 | Displays minimum, maximum labels (new since wxWidgets 2.9.1). | |
28 | @style{wxSL_VALUE_LABEL} | |
29 | Displays value label (new since wxWidgets 2.9.1). | |
30 | @style{wxSL_LABELS} | |
31 | Displays minimum, maximum and value labels (same as wxSL_VALUE_LABEL | |
32 | and wxSL_MIN_MAX_LABELS together). | |
33 | @style{wxSL_LEFT} | |
34 | Displays ticks on the left and forces the slider to be vertical. | |
35 | @style{wxSL_RIGHT} | |
36 | Displays ticks on the right and forces the slider to be vertical. | |
37 | @style{wxSL_TOP} | |
38 | Displays ticks on the top. | |
39 | @style{wxSL_BOTTOM} | |
40 | Displays ticks on the bottom (this is the default). | |
41 | @style{wxSL_SELRANGE} | |
42 | Allows the user to select a range on the slider. Windows only. | |
43 | @style{wxSL_INVERSE} | |
44 | Inverses the mininum and maximum endpoints on the slider. Not | |
45 | compatible with wxSL_SELRANGE. | |
46 | @endStyleTable | |
47 | ||
48 | Notice that @c wxSL_LEFT, @c wxSL_TOP, @c wxSL_RIGHT and @c wxSL_BOTTOM | |
49 | specify the position of the slider ticks in MSW implementation and that the | |
50 | slider labels, if any, are positioned on the opposite side. So, to have a | |
51 | label on the left side of a vertical slider, @b wxSL_RIGHT must be used (or | |
52 | none of these styles at all should be specified as left and top are default | |
53 | positions for the vertical and horizontal sliders respectively). | |
54 | ||
55 | @beginEventEmissionTable{wxScrollEvent} | |
56 | You can use EVT_COMMAND_SCROLL... macros with window IDs for when intercepting | |
57 | scroll events from controls, or EVT_SCROLL... macros without window IDs for | |
58 | intercepting scroll events from the receiving window -- except for this, | |
59 | the macros behave exactly the same. | |
60 | @event{EVT_SCROLL(func)} | |
61 | Process all scroll events. | |
62 | @event{EVT_SCROLL_TOP(func)} | |
63 | Process wxEVT_SCROLL_TOP scroll-to-top events (minimum position). | |
64 | @event{EVT_SCROLL_BOTTOM(func)} | |
65 | Process wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position). | |
66 | @event{EVT_SCROLL_LINEUP(func)} | |
67 | Process wxEVT_SCROLL_LINEUP line up events. | |
68 | @event{EVT_SCROLL_LINEDOWN(func)} | |
69 | Process wxEVT_SCROLL_LINEDOWN line down events. | |
70 | @event{EVT_SCROLL_PAGEUP(func)} | |
71 | Process wxEVT_SCROLL_PAGEUP page up events. | |
72 | @event{EVT_SCROLL_PAGEDOWN(func)} | |
73 | Process wxEVT_SCROLL_PAGEDOWN page down events. | |
74 | @event{EVT_SCROLL_THUMBTRACK(func)} | |
75 | Process wxEVT_SCROLL_THUMBTRACK thumbtrack events | |
76 | (frequent events sent as the user drags the thumbtrack). | |
77 | @event{EVT_SCROLL_THUMBRELEASE(func)} | |
78 | Process wxEVT_SCROLL_THUMBRELEASE thumb release events. | |
79 | @event{EVT_SCROLL_CHANGED(func)} | |
80 | Process wxEVT_SCROLL_CHANGED end of scrolling events (MSW only). | |
81 | @event{EVT_COMMAND_SCROLL(id, func)} | |
82 | Process all scroll events. | |
83 | @event{EVT_COMMAND_SCROLL_TOP(id, func)} | |
84 | Process wxEVT_SCROLL_TOP scroll-to-top events (minimum position). | |
85 | @event{EVT_COMMAND_SCROLL_BOTTOM(id, func)} | |
86 | Process wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position). | |
87 | @event{EVT_COMMAND_SCROLL_LINEUP(id, func)} | |
88 | Process wxEVT_SCROLL_LINEUP line up events. | |
89 | @event{EVT_COMMAND_SCROLL_LINEDOWN(id, func)} | |
90 | Process wxEVT_SCROLL_LINEDOWN line down events. | |
91 | @event{EVT_COMMAND_SCROLL_PAGEUP(id, func)} | |
92 | Process wxEVT_SCROLL_PAGEUP page up events. | |
93 | @event{EVT_COMMAND_SCROLL_PAGEDOWN(id, func)} | |
94 | Process wxEVT_SCROLL_PAGEDOWN page down events. | |
95 | @event{EVT_COMMAND_SCROLL_THUMBTRACK(id, func)} | |
96 | Process wxEVT_SCROLL_THUMBTRACK thumbtrack events | |
97 | (frequent events sent as the user drags the thumbtrack). | |
98 | @event{EVT_COMMAND_SCROLL_THUMBRELEASE(func)} | |
99 | Process wxEVT_SCROLL_THUMBRELEASE thumb release events. | |
100 | @event{EVT_COMMAND_SCROLL_CHANGED(func)} | |
101 | Process wxEVT_SCROLL_CHANGED end of scrolling events (MSW only). | |
102 | @endEventTable | |
103 | ||
104 | @section slider_diff The difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED | |
105 | ||
106 | The EVT_SCROLL_THUMBRELEASE event is only emitted when actually dragging the | |
107 | thumb using the mouse and releasing it (This EVT_SCROLL_THUMBRELEASE event | |
108 | is also followed by an EVT_SCROLL_CHANGED event). | |
109 | ||
110 | The EVT_SCROLL_CHANGED event also occurs when using the keyboard to change | |
111 | the thumb position, and when clicking next to the thumb | |
112 | (In all these cases the EVT_SCROLL_THUMBRELEASE event does not happen). | |
113 | In short, the EVT_SCROLL_CHANGED event is triggered when scrolling/ moving | |
114 | has finished independently of the way it had started. | |
115 | Please see the widgets sample ("Slider" page) to see the difference between | |
116 | EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED in action. | |
117 | ||
118 | @library{wxcore} | |
119 | @category{ctrl} | |
120 | @appearance{slider.png} | |
121 | ||
122 | @see @ref overview_events, wxScrollBar | |
123 | */ | |
124 | class wxSlider : public wxControl | |
125 | { | |
126 | public: | |
127 | /** | |
128 | Default constructor | |
129 | */ | |
130 | wxSlider(); | |
131 | ||
132 | /** | |
133 | Constructor, creating and showing a slider. | |
134 | ||
135 | @param parent | |
136 | Parent window. Must not be @NULL. | |
137 | @param id | |
138 | Window identifier. The value wxID_ANY indicates a default value. | |
139 | @param value | |
140 | Initial position for the slider. | |
141 | @param minValue | |
142 | Minimum slider position. | |
143 | @param maxValue | |
144 | Maximum slider position. | |
145 | @param pos | |
146 | Window position. | |
147 | If ::wxDefaultPosition is specified then a default position is chosen. | |
148 | @param size | |
149 | Window size. | |
150 | If ::wxDefaultSize is specified then a default size is chosen. | |
151 | @param style | |
152 | Window style. See wxSlider. | |
153 | @param validator | |
154 | Window validator. | |
155 | @param name | |
156 | Window name. | |
157 | ||
158 | @see Create(), wxValidator | |
159 | */ | |
160 | wxSlider(wxWindow* parent, wxWindowID id, int value, | |
161 | int minValue, int maxValue, | |
162 | const wxPoint& pos = wxDefaultPosition, | |
163 | const wxSize& size = wxDefaultSize, | |
164 | long style = wxSL_HORIZONTAL, | |
165 | const wxValidator& validator = wxDefaultValidator, | |
166 | const wxString& name = wxSliderNameStr); | |
167 | ||
168 | /** | |
169 | Destructor, destroying the slider. | |
170 | */ | |
171 | virtual ~wxSlider(); | |
172 | ||
173 | /** | |
174 | Clears the selection, for a slider with the @b wxSL_SELRANGE style. | |
175 | ||
176 | @onlyfor{wxmsw} | |
177 | */ | |
178 | virtual void ClearSel(); | |
179 | ||
180 | /** | |
181 | Clears the ticks. | |
182 | ||
183 | @onlyfor{wxmsw} | |
184 | */ | |
185 | virtual void ClearTicks(); | |
186 | ||
187 | /** | |
188 | Used for two-step slider construction. | |
189 | See wxSlider() for further details. | |
190 | */ | |
191 | bool Create(wxWindow* parent, wxWindowID id, int value, int minValue, | |
192 | int maxValue, const wxPoint& point = wxDefaultPosition, | |
193 | const wxSize& size = wxDefaultSize, long style = wxSL_HORIZONTAL, | |
194 | const wxValidator& validator = wxDefaultValidator, | |
195 | const wxString& name = wxSliderNameStr); | |
196 | ||
197 | /** | |
198 | Returns the line size. | |
199 | ||
200 | @see SetLineSize() | |
201 | */ | |
202 | virtual int GetLineSize() const; | |
203 | ||
204 | /** | |
205 | Gets the maximum slider value. | |
206 | ||
207 | @see GetMin(), SetRange() | |
208 | */ | |
209 | virtual int GetMax() const; | |
210 | ||
211 | /** | |
212 | Gets the minimum slider value. | |
213 | ||
214 | @see GetMin(), SetRange() | |
215 | */ | |
216 | virtual int GetMin() const; | |
217 | ||
218 | /** | |
219 | Returns the page size. | |
220 | ||
221 | @see SetPageSize() | |
222 | */ | |
223 | virtual int GetPageSize() const; | |
224 | ||
225 | /** | |
226 | Returns the selection end point. | |
227 | ||
228 | @onlyfor{wxmsw} | |
229 | ||
230 | @see GetSelStart(), SetSelection() | |
231 | */ | |
232 | virtual int GetSelEnd() const; | |
233 | ||
234 | /** | |
235 | Returns the selection start point. | |
236 | ||
237 | @onlyfor{wxmsw} | |
238 | ||
239 | @see GetSelEnd(), SetSelection() | |
240 | */ | |
241 | virtual int GetSelStart() const; | |
242 | ||
243 | /** | |
244 | Returns the thumb length. | |
245 | ||
246 | @onlyfor{wxmsw} | |
247 | ||
248 | @see SetThumbLength() | |
249 | */ | |
250 | virtual int GetThumbLength() const; | |
251 | ||
252 | /** | |
253 | Returns the tick frequency. | |
254 | ||
255 | @onlyfor{wxmsw} | |
256 | ||
257 | @see SetTickFreq() | |
258 | */ | |
259 | virtual int GetTickFreq() const; | |
260 | ||
261 | /** | |
262 | Gets the current slider value. | |
263 | ||
264 | @see GetMin(), GetMax(), SetValue() | |
265 | */ | |
266 | virtual int GetValue() const; | |
267 | ||
268 | /** | |
269 | Sets the line size for the slider. | |
270 | ||
271 | @param lineSize | |
272 | The number of steps the slider moves when the user moves it up | |
273 | or down a line. | |
274 | ||
275 | @see GetLineSize() | |
276 | */ | |
277 | virtual void SetLineSize(int lineSize); | |
278 | ||
279 | /** | |
280 | Sets the page size for the slider. | |
281 | ||
282 | @param pageSize | |
283 | The number of steps the slider moves when the user pages up or down. | |
284 | ||
285 | @see GetPageSize() | |
286 | */ | |
287 | virtual void SetPageSize(int pageSize); | |
288 | ||
289 | /** | |
290 | Sets the minimum and maximum slider values. | |
291 | ||
292 | @see GetMin(), GetMax() | |
293 | */ | |
294 | virtual void SetRange(int minValue, int maxValue); | |
295 | ||
296 | /** | |
297 | Sets the selection. | |
298 | ||
299 | @param startPos | |
300 | The selection start position. | |
301 | @param endPos | |
302 | The selection end position. | |
303 | ||
304 | @onlyfor{wxmsw} | |
305 | ||
306 | @see GetSelStart(), GetSelEnd() | |
307 | */ | |
308 | virtual void SetSelection(int startPos, int endPos); | |
309 | ||
310 | /** | |
311 | Sets the slider thumb length. | |
312 | ||
313 | @param len | |
314 | The thumb length. | |
315 | ||
316 | @onlyfor{wxmsw} | |
317 | ||
318 | @see GetThumbLength() | |
319 | */ | |
320 | virtual void SetThumbLength(int len); | |
321 | ||
322 | /** | |
323 | Sets a tick position. | |
324 | ||
325 | @param tickPos | |
326 | The tick position. | |
327 | ||
328 | @onlyfor{wxmsw} | |
329 | ||
330 | @see SetTickFreq() | |
331 | */ | |
332 | virtual void SetTick(int tickPos); | |
333 | ||
334 | /** | |
335 | Sets the tick mark frequency and position. | |
336 | ||
337 | @param n | |
338 | Frequency. For example, if the frequency is set to two, a tick mark is | |
339 | displayed for every other increment in the slider's range. | |
340 | @param pos | |
341 | Position. Must be greater than zero. @todo: what is this for? | |
342 | ||
343 | @onlyfor{wxmsw} | |
344 | ||
345 | @see GetTickFreq() | |
346 | */ | |
347 | virtual void SetTickFreq(int n, int pos); | |
348 | ||
349 | /** | |
350 | Sets the slider position. | |
351 | ||
352 | @param value | |
353 | The slider position. | |
354 | */ | |
355 | virtual void SetValue(int value); | |
356 | }; | |
357 |