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