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