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