interface/wx/slider.h

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