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