interface/wx/slider.h

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