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