// Purpose: interface of wxSlider
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
@class wxSlider
- A slider is a control with a handle which can be pulled
- back and forth to change the value.
+ A slider is a control with a handle which can be pulled back and forth to
+ change the value.
On Windows, the track bar control is used.
@style{wxSL_VERTICAL}
Displays the slider vertically.
@style{wxSL_AUTOTICKS}
- Displays tick marks.
+ Displays tick marks. Windows only.
+ @style{wxSL_MIN_MAX_LABELS}
+ Displays minimum, maximum labels (new since wxWidgets 2.9.1).
+ @style{wxSL_VALUE_LABEL}
+ Displays value label (new since wxWidgets 2.9.1).
@style{wxSL_LABELS}
- Displays minimum, maximum and value labels.
+ Displays minimum, maximum and value labels (same as wxSL_VALUE_LABEL
+ and wxSL_MIN_MAX_LABELS together).
@style{wxSL_LEFT}
Displays ticks on the left and forces the slider to be vertical.
@style{wxSL_RIGHT}
compatible with wxSL_SELRANGE.
@endStyleTable
+ Notice that @c wxSL_LEFT, @c wxSL_TOP, @c wxSL_RIGHT and @c wxSL_BOTTOM
+ specify the position of the slider ticks in MSW implementation and that the
+ slider labels, if any, are positioned on the opposite side. So, to have a
+ label on the left side of a vertical slider, @b wxSL_RIGHT must be used (or
+ none of these styles at all should be specified as left and top are default
+ positions for the vertical and horizontal sliders respectively).
+
+ @beginEventEmissionTable{wxScrollEvent}
+ You can use EVT_COMMAND_SCROLL... macros with window IDs for when intercepting
+ scroll events from controls, or EVT_SCROLL... macros without window IDs for
+ intercepting scroll events from the receiving window -- except for this,
+ the macros behave exactly the same.
+ @event{EVT_SCROLL(func)}
+ Process all scroll events.
+ @event{EVT_SCROLL_TOP(func)}
+ Process wxEVT_SCROLL_TOP scroll-to-top events (minimum position).
+ @event{EVT_SCROLL_BOTTOM(func)}
+ Process wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position).
+ @event{EVT_SCROLL_LINEUP(func)}
+ Process wxEVT_SCROLL_LINEUP line up events.
+ @event{EVT_SCROLL_LINEDOWN(func)}
+ Process wxEVT_SCROLL_LINEDOWN line down events.
+ @event{EVT_SCROLL_PAGEUP(func)}
+ Process wxEVT_SCROLL_PAGEUP page up events.
+ @event{EVT_SCROLL_PAGEDOWN(func)}
+ Process wxEVT_SCROLL_PAGEDOWN page down events.
+ @event{EVT_SCROLL_THUMBTRACK(func)}
+ Process wxEVT_SCROLL_THUMBTRACK thumbtrack events
+ (frequent events sent as the user drags the thumbtrack).
+ @event{EVT_SCROLL_THUMBRELEASE(func)}
+ Process wxEVT_SCROLL_THUMBRELEASE thumb release events.
+ @event{EVT_SCROLL_CHANGED(func)}
+ Process wxEVT_SCROLL_CHANGED end of scrolling events (MSW only).
+ @event{EVT_COMMAND_SCROLL(id, func)}
+ Process all scroll events.
+ @event{EVT_COMMAND_SCROLL_TOP(id, func)}
+ Process wxEVT_SCROLL_TOP scroll-to-top events (minimum position).
+ @event{EVT_COMMAND_SCROLL_BOTTOM(id, func)}
+ Process wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position).
+ @event{EVT_COMMAND_SCROLL_LINEUP(id, func)}
+ Process wxEVT_SCROLL_LINEUP line up events.
+ @event{EVT_COMMAND_SCROLL_LINEDOWN(id, func)}
+ Process wxEVT_SCROLL_LINEDOWN line down events.
+ @event{EVT_COMMAND_SCROLL_PAGEUP(id, func)}
+ Process wxEVT_SCROLL_PAGEUP page up events.
+ @event{EVT_COMMAND_SCROLL_PAGEDOWN(id, func)}
+ Process wxEVT_SCROLL_PAGEDOWN page down events.
+ @event{EVT_COMMAND_SCROLL_THUMBTRACK(id, func)}
+ Process wxEVT_SCROLL_THUMBTRACK thumbtrack events
+ (frequent events sent as the user drags the thumbtrack).
+ @event{EVT_COMMAND_SCROLL_THUMBRELEASE(func)}
+ Process wxEVT_SCROLL_THUMBRELEASE thumb release events.
+ @event{EVT_COMMAND_SCROLL_CHANGED(func)}
+ Process wxEVT_SCROLL_CHANGED end of scrolling events (MSW only).
+ @endEventTable
+
+ @section slider_diff The difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED
+
+ The EVT_SCROLL_THUMBRELEASE event is only emitted when actually dragging the
+ thumb using the mouse and releasing it (This EVT_SCROLL_THUMBRELEASE event
+ is also followed by an EVT_SCROLL_CHANGED event).
+
+ The EVT_SCROLL_CHANGED event also occurs when using the keyboard to change
+ the thumb position, and when clicking next to the thumb
+ (In all these cases the EVT_SCROLL_THUMBRELEASE event does not happen).
+ In short, the EVT_SCROLL_CHANGED event is triggered when scrolling/ moving
+ has finished independently of the way it had started.
+ Please see the widgets sample ("Slider" page) to see the difference between
+ EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED in action.
+
@library{wxcore}
@category{ctrl}
- <!-- @appearance{slider.png} -->
+ @appearance{slider.png}
- @see @ref overview_eventhandlingoverview, wxScrollBar
+ @see @ref overview_events, wxScrollBar
*/
class wxSlider : public wxControl
{
Default constructor
*/
wxSlider();
-
+
/**
Constructor, creating and showing a slider.
Minimum slider position.
@param maxValue
Maximum slider position.
+ @param pos
+ Window position.
+ If ::wxDefaultPosition is specified then a default position is chosen.
@param size
- Window size. If wxDefaultSize is specified then a default size
- is chosen.
+ Window size.
+ If ::wxDefaultSize is specified then a default size is chosen.
@param style
Window style. See wxSlider.
@param validator
*/
wxSlider(wxWindow* parent, wxWindowID id, int value,
int minValue, int maxValue,
- const wxPoint& point = wxDefaultPosition,
+ const wxPoint& pos = wxDefaultPosition,
const wxSize& size = wxDefaultSize,
long style = wxSL_HORIZONTAL,
const wxValidator& validator = wxDefaultValidator,
- const wxString& name = "slider");
+ const wxString& name = wxSliderNameStr);
/**
Destructor, destroying the slider.
/**
Clears the selection, for a slider with the @b wxSL_SELRANGE style.
- @remarks Windows 95 only.
+ @onlyfor{wxmsw}
*/
virtual void ClearSel();
/**
Clears the ticks.
- @remarks Windows 95 only.
+ @onlyfor{wxmsw}
*/
virtual void ClearTicks();
/**
- Used for two-step slider construction. See wxSlider()
- for further details.
+ Used for two-step slider construction.
+ See wxSlider() for further details.
*/
- bool Create(wxWindow* parent, wxWindowID id, int value,
- int minValue, int maxValue,
- const wxPoint& point = wxDefaultPosition,
- const wxSize& size = wxDefaultSize,
- long style = wxSL_HORIZONTAL,
+ bool Create(wxWindow* parent, wxWindowID id, int value, int minValue,
+ int maxValue, const wxPoint& point = wxDefaultPosition,
+ const wxSize& size = wxDefaultSize, long style = wxSL_HORIZONTAL,
const wxValidator& validator = wxDefaultValidator,
- const wxString& name = "slider");
+ const wxString& name = wxSliderNameStr);
/**
Returns the line size.
/**
Returns the selection end point.
- @remarks Windows 95 only.
+ @onlyfor{wxmsw}
@see GetSelStart(), SetSelection()
*/
/**
Returns the selection start point.
- @remarks Windows 95 only.
+ @onlyfor{wxmsw}
@see GetSelEnd(), SetSelection()
*/
/**
Returns the thumb length.
- @remarks Windows 95 only.
+ @onlyfor{wxmsw}
@see SetThumbLength()
*/
/**
Returns the tick frequency.
- @remarks Windows 95 only.
+ @onlyfor{wxmsw}
@see SetTickFreq()
*/
Sets the line size for the slider.
@param lineSize
- The number of steps the slider moves when the user moves it up or down a
- line.
+ The number of steps the slider moves when the user moves it up
+ or down a line.
@see GetLineSize()
*/
@param endPos
The selection end position.
- @remarks Windows 95 only.
+ @onlyfor{wxmsw}
@see GetSelStart(), GetSelEnd()
*/
@param len
The thumb length.
- @remarks Windows 95 only.
+ @onlyfor{wxmsw}
@see GetThumbLength()
*/
@param tickPos
The tick position.
- @remarks Windows 95 only.
+ @onlyfor{wxmsw}
@see SetTickFreq()
*/
@param n
Frequency. For example, if the frequency is set to two, a tick mark is
- displayed for
- every other increment in the slider's range.
+ displayed for every other increment in the slider's range.
@param pos
- Position. Must be greater than zero. TODO: what is this for?
+ Position. Must be greater than zero. @todo: what is this for?
- @remarks Windows 95 only.
+ @onlyfor{wxmsw}
@see GetTickFreq()
*/
projects / wxWidgets.git / blobdiff