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