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     @beginEventTable{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     @todo are all strings "Windows 95 only" really up2date?
 107
 108     @library{wxcore}
 109     @category{ctrl}
 110     @appearance{slider.png}
 111
 112     @see @ref overview_eventhandling, wxScrollBar
 113 */
 114 class wxSlider : public wxControl
 115 {
 116 public:
 117     /**
 118        Default constructor
 119     */
 120     wxSlider();
 121
 122     /**
 123         Constructor, creating and showing a slider.
 124
 125         @param parent
 126             Parent window. Must not be @NULL.
 127         @param id
 128             Window identifier. The value wxID_ANY indicates a default value.
 129         @param value
 130             Initial position for the slider.
 131         @param minValue
 132             Minimum slider position.
 133         @param maxValue
 134             Maximum slider position.
 135         @param pos
 136             Window position. If wxDefaultPosition is specified then a default position is chosen.
 137         @param size
 138             Window size. If wxDefaultSize is specified then a default size is chosen.
 139         @param style
 140             Window style. See wxSlider.
 141         @param validator
 142             Window validator.
 143         @param name
 144             Window name.
 145
 146         @see Create(), wxValidator
 147     */
 148     wxSlider(wxWindow* parent, wxWindowID id, int value,
 149              int minValue, int maxValue,
 150              const wxPoint& pos = wxDefaultPosition,
 151              const wxSize& size = wxDefaultSize,
 152              long style = wxSL_HORIZONTAL,
 153              const wxValidator& validator = wxDefaultValidator,
 154              const wxString& name = wxSliderNameStr);
 155
 156     /**
 157         Destructor, destroying the slider.
 158     */
 159     virtual ~wxSlider();
 160
 161     /**
 162         Clears the selection, for a slider with the @b wxSL_SELRANGE style.
 163
 164         @remarks Windows 95 only.
 165     */
 166     virtual void ClearSel();
 167
 168     /**
 169         Clears the ticks.
 170
 171         @remarks Windows 95 only.
 172     */
 173     virtual void ClearTicks();
 174
 175     /**
 176         Used for two-step slider construction.
 177         See wxSlider() for further details.
 178     */
 179     bool Create(wxWindow* parent, wxWindowID id, int value, int minValue,
 180                 int maxValue, const wxPoint& point = wxDefaultPosition,
 181                 const wxSize& size = wxDefaultSize, long style = wxSL_HORIZONTAL,
 182                 const wxValidator& validator = wxDefaultValidator,
 183                 const wxString& name = wxSliderNameStr);
 184
 185     /**
 186         Returns the line size.
 187
 188         @see SetLineSize()
 189     */
 190     virtual int GetLineSize() const;
 191
 192     /**
 193         Gets the maximum slider value.
 194
 195         @see GetMin(), SetRange()
 196     */
 197     virtual int GetMax() const;
 198
 199     /**
 200         Gets the minimum slider value.
 201
 202         @see GetMin(), SetRange()
 203     */
 204     virtual int GetMin() const;
 205
 206     /**
 207         Returns the page size.
 208
 209         @see SetPageSize()
 210     */
 211     virtual int GetPageSize() const;
 212
 213     /**
 214         Returns the selection end point.
 215
 216         @remarks Windows 95 only.
 217
 218         @see GetSelStart(), SetSelection()
 219     */
 220     virtual int GetSelEnd() const;
 221
 222     /**
 223         Returns the selection start point.
 224
 225         @remarks Windows 95 only.
 226
 227         @see GetSelEnd(), SetSelection()
 228     */
 229     virtual int GetSelStart() const;
 230
 231     /**
 232         Returns the thumb length.
 233
 234         @remarks Windows 95 only.
 235
 236         @see SetThumbLength()
 237     */
 238     virtual int GetThumbLength() const;
 239
 240     /**
 241         Returns the tick frequency.
 242
 243         @remarks Windows 95 only.
 244
 245         @see SetTickFreq()
 246     */
 247     virtual int GetTickFreq() const;
 248
 249     /**
 250         Gets the current slider value.
 251
 252         @see GetMin(), GetMax(), SetValue()
 253     */
 254     virtual int GetValue() const;
 255
 256     /**
 257         Sets the line size for the slider.
 258
 259         @param lineSize
 260             The number of steps the slider moves when the user moves it up
 261             or down a line.
 262
 263         @see GetLineSize()
 264     */
 265     virtual void SetLineSize(int lineSize);
 266
 267     /**
 268         Sets the page size for the slider.
 269
 270         @param pageSize
 271             The number of steps the slider moves when the user pages up or down.
 272
 273         @see GetPageSize()
 274     */
 275     virtual void SetPageSize(int pageSize);
 276
 277     /**
 278         Sets the minimum and maximum slider values.
 279
 280         @see GetMin(), GetMax()
 281     */
 282     virtual void SetRange(int minValue, int maxValue);
 283
 284     /**
 285         Sets the selection.
 286
 287         @param startPos
 288             The selection start position.
 289         @param endPos
 290             The selection end position.
 291
 292         @remarks Windows 95 only.
 293
 294         @see GetSelStart(), GetSelEnd()
 295     */
 296     virtual void SetSelection(int startPos, int endPos);
 297
 298     /**
 299         Sets the slider thumb length.
 300
 301         @param len
 302             The thumb length.
 303
 304         @remarks Windows 95 only.
 305
 306         @see GetThumbLength()
 307     */
 308     virtual void SetThumbLength(int len);
 309
 310     /**
 311         Sets a tick position.
 312
 313         @param tickPos
 314             The tick position.
 315
 316         @remarks Windows 95 only.
 317
 318         @see SetTickFreq()
 319     */
 320     virtual void SetTick(int tickPos);
 321
 322     /**
 323         Sets the tick mark frequency and position.
 324
 325         @param n
 326             Frequency. For example, if the frequency is set to two, a tick mark is
 327             displayed for every other increment in the slider's range.
 328         @param pos
 329             Position. Must be greater than zero. @todo: what is this for?
 330
 331         @remarks Windows 95 only.
 332
 333         @see GetTickFreq()
 334     */
 335     virtual void SetTickFreq(int n, int pos);
 336
 337     /**
 338         Sets the slider position.
 339
 340         @param value
 341             The slider position.
 342     */
 343     virtual void SetValue(int value);
 344 };
 345