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