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_COMMAND_SLIDER_UPDATED 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         Sets the page size for the slider.
 301
 302         @param pageSize
 303             The number of steps the slider moves when the user pages up or down.
 304
 305         @see GetPageSize()
 306     */
 307     virtual void SetPageSize(int pageSize);
 308
 309     /**
 310         Sets the minimum and maximum slider values.
 311
 312         @see GetMin(), GetMax()
 313     */
 314     virtual void SetRange(int minValue, int maxValue);
 315
 316     /**
 317         Sets the selection.
 318
 319         @param startPos
 320             The selection start position.
 321         @param endPos
 322             The selection end position.
 323
 324         @onlyfor{wxmsw}
 325
 326         @see GetSelStart(), GetSelEnd()
 327     */
 328     virtual void SetSelection(int startPos, int endPos);
 329
 330     /**
 331         Sets the slider thumb length.
 332
 333         @param len
 334             The thumb length.
 335
 336         @onlyfor{wxmsw}
 337
 338         @see GetThumbLength()
 339     */
 340     virtual void SetThumbLength(int len);
 341
 342     /**
 343         Sets a tick position.
 344
 345         @param tickPos
 346             The tick position.
 347
 348         @onlyfor{wxmsw}
 349
 350         @see SetTickFreq()
 351     */
 352     virtual void SetTick(int tickPos);
 353
 354     /**
 355         Sets the tick mark frequency and position.
 356
 357         @param n
 358             Frequency. For example, if the frequency is set to two, a tick mark is
 359             displayed for every other increment in the slider's range.
 360
 361         @onlyfor{wxmsw}
 362
 363         @see GetTickFreq()
 364     */
 365     virtual void SetTickFreq(int n);
 366
 367     /**
 368         Sets the slider position.
 369
 370         @param value
 371             The slider position.
 372     */
 373     virtual void SetValue(int value);
 374 };
 375