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