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 = "slider");
 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,
 180                 int minValue, int maxValue,
 181                 const wxPoint& point = wxDefaultPosition,
 182                 const wxSize& size = wxDefaultSize,
 183                 long style = wxSL_HORIZONTAL,
 184                 const wxValidator& validator = wxDefaultValidator,
 185                 const wxString& name = "slider");
 186
 187     /**
 188         Returns the line size.
 189
 190         @see SetLineSize()
 191     */
 192     virtual int GetLineSize() const;
 193
 194     /**
 195         Gets the maximum slider value.
 196
 197         @see GetMin(), SetRange()
 198     */
 199     virtual int GetMax() const;
 200
 201     /**
 202         Gets the minimum slider value.
 203
 204         @see GetMin(), SetRange()
 205     */
 206     virtual int GetMin() const;
 207
 208     /**
 209         Returns the page size.
 210
 211         @see SetPageSize()
 212     */
 213     virtual int GetPageSize() const;
 214
 215     /**
 216         Returns the selection end point.
 217
 218         @remarks Windows 95 only.
 219
 220         @see GetSelStart(), SetSelection()
 221     */
 222     virtual int GetSelEnd() const;
 223
 224     /**
 225         Returns the selection start point.
 226
 227         @remarks Windows 95 only.
 228
 229         @see GetSelEnd(), SetSelection()
 230     */
 231     virtual int GetSelStart() const;
 232
 233     /**
 234         Returns the thumb length.
 235
 236         @remarks Windows 95 only.
 237
 238         @see SetThumbLength()
 239     */
 240     virtual int GetThumbLength() const;
 241
 242     /**
 243         Returns the tick frequency.
 244
 245         @remarks Windows 95 only.
 246
 247         @see SetTickFreq()
 248     */
 249     virtual int GetTickFreq() const;
 250
 251     /**
 252         Gets the current slider value.
 253
 254         @see GetMin(), GetMax(), SetValue()
 255     */
 256     virtual int GetValue() const;
 257
 258     /**
 259         Sets the line size for the slider.
 260
 261         @param lineSize
 262             The number of steps the slider moves when the user moves it up
 263             or down a line.
 264
 265         @see GetLineSize()
 266     */
 267     virtual void SetLineSize(int lineSize);
 268
 269     /**
 270         Sets the page size for the slider.
 271
 272         @param pageSize
 273             The number of steps the slider moves when the user pages up or down.
 274
 275         @see GetPageSize()
 276     */
 277     virtual void SetPageSize(int pageSize);
 278
 279     /**
 280         Sets the minimum and maximum slider values.
 281
 282         @see GetMin(), GetMax()
 283     */
 284     virtual void SetRange(int minValue, int maxValue);
 285
 286     /**
 287         Sets the selection.
 288
 289         @param startPos
 290             The selection start position.
 291         @param endPos
 292             The selection end position.
 293
 294         @remarks Windows 95 only.
 295
 296         @see GetSelStart(), GetSelEnd()
 297     */
 298     virtual void SetSelection(int startPos, int endPos);
 299
 300     /**
 301         Sets the slider thumb length.
 302
 303         @param len
 304             The thumb length.
 305
 306         @remarks Windows 95 only.
 307
 308         @see GetThumbLength()
 309     */
 310     virtual void SetThumbLength(int len);
 311
 312     /**
 313         Sets a tick position.
 314
 315         @param tickPos
 316             The tick position.
 317
 318         @remarks Windows 95 only.
 319
 320         @see SetTickFreq()
 321     */
 322     virtual void SetTick(int tickPos);
 323
 324     /**
 325         Sets the tick mark frequency and position.
 326
 327         @param n
 328             Frequency. For example, if the frequency is set to two, a tick mark is
 329             displayed for every other increment in the slider's range.
 330         @param pos
 331             Position. Must be greater than zero. @todo: what is this for?
 332
 333         @remarks Windows 95 only.
 334
 335         @see GetTickFreq()
 336     */
 337     virtual void SetTickFreq(int n, int pos);
 338
 339     /**
 340         Sets the slider position.
 341
 342         @param value
 343             The slider position.
 344     */
 345     virtual void SetValue(int value);
 346 };
 347