]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/slider.h
undo the last change as it results in buildbot configuration error
[wxWidgets.git] / interface / wx / slider.h
index 5d20acb9fc373b31ab1b79fa746b75df22cc5638..9ce912e3f43f4d206cd60f8d4831e76ac72904ff 100644 (file)
@@ -8,10 +8,9 @@
 
 /**
     @class wxSlider
 
 /**
     @class wxSlider
-    @wxheader{slider.h}
 
 
-    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.
 
 
     On Windows, the track bar control is used.
 
            compatible with wxSL_SELRANGE.
     @endStyleTable
 
            compatible with wxSL_SELRANGE.
     @endStyleTable
 
+    @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}
     @library{wxcore}
     @category{ctrl}
-    <!-- @appearance{slider.png} -->
+    @appearance{slider.png}
 
 
-    @see @ref overview_eventhandlingoverview, wxScrollBar
+    @see @ref overview_events, wxScrollBar
 */
 class wxSlider : public wxControl
 {
 */
 class wxSlider : public wxControl
 {
@@ -54,7 +116,7 @@ public:
        Default constructor
     */
     wxSlider();
        Default constructor
     */
     wxSlider();
-    
+
     /**
         Constructor, creating and showing a slider.
 
     /**
         Constructor, creating and showing a slider.
 
@@ -68,9 +130,12 @@ public:
             Minimum slider position.
         @param maxValue
             Maximum slider position.
             Minimum slider position.
         @param maxValue
             Maximum slider position.
+        @param pos
+            Window position. 
+            If ::wxDefaultPosition is specified then a default position is chosen.
         @param size
         @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
         @param style
             Window style. See wxSlider.
         @param validator
@@ -82,124 +147,122 @@ public:
     */
     wxSlider(wxWindow* parent, wxWindowID id, int value,
              int minValue, int maxValue,
     */
     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 wxSize& size = wxDefaultSize,
              long style = wxSL_HORIZONTAL,
              const wxValidator& validator = wxDefaultValidator,
-             const wxString& name = "slider");
+             const wxString& name = wxSliderNameStr);
 
     /**
         Destructor, destroying the slider.
     */
 
     /**
         Destructor, destroying the slider.
     */
-    ~wxSlider();
+    virtual ~wxSlider();
 
     /**
         Clears the selection, for a slider with the @b wxSL_SELRANGE style.
 
 
     /**
         Clears the selection, for a slider with the @b wxSL_SELRANGE style.
 
-        @remarks Windows 95 only.
+        @onlyfor{wxmsw}
     */
     */
-    void ClearSel();
+    virtual void ClearSel();
 
     /**
         Clears the ticks.
 
 
     /**
         Clears the ticks.
 
-        @remarks Windows 95 only.
+        @onlyfor{wxmsw}
     */
     */
-    void ClearTicks();
+    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 wxValidator& validator = wxDefaultValidator,
-                const wxString& name = "slider");
+                const wxString& name = wxSliderNameStr);
 
     /**
         Returns the line size.
 
         @see SetLineSize()
     */
 
     /**
         Returns the line size.
 
         @see SetLineSize()
     */
-    int GetLineSize() const;
+    virtual int GetLineSize() const;
 
     /**
         Gets the maximum slider value.
 
         @see GetMin(), SetRange()
     */
 
     /**
         Gets the maximum slider value.
 
         @see GetMin(), SetRange()
     */
-    int GetMax() const;
+    virtual int GetMax() const;
 
     /**
         Gets the minimum slider value.
 
         @see GetMin(), SetRange()
     */
 
     /**
         Gets the minimum slider value.
 
         @see GetMin(), SetRange()
     */
-    int GetMin() const;
+    virtual int GetMin() const;
 
     /**
         Returns the page size.
 
         @see SetPageSize()
     */
 
     /**
         Returns the page size.
 
         @see SetPageSize()
     */
-    int GetPageSize() const;
+    virtual int GetPageSize() const;
 
     /**
         Returns the selection end point.
 
 
     /**
         Returns the selection end point.
 
-        @remarks Windows 95 only.
+        @onlyfor{wxmsw}
 
         @see GetSelStart(), SetSelection()
     */
 
         @see GetSelStart(), SetSelection()
     */
-    int GetSelEnd() const;
+    virtual int GetSelEnd() const;
 
     /**
         Returns the selection start point.
 
 
     /**
         Returns the selection start point.
 
-        @remarks Windows 95 only.
+        @onlyfor{wxmsw}
 
         @see GetSelEnd(), SetSelection()
     */
 
         @see GetSelEnd(), SetSelection()
     */
-    int GetSelStart() const;
+    virtual int GetSelStart() const;
 
     /**
         Returns the thumb length.
 
 
     /**
         Returns the thumb length.
 
-        @remarks Windows 95 only.
+        @onlyfor{wxmsw}
 
         @see SetThumbLength()
     */
 
         @see SetThumbLength()
     */
-    int GetThumbLength() const;
+    virtual int GetThumbLength() const;
 
     /**
         Returns the tick frequency.
 
 
     /**
         Returns the tick frequency.
 
-        @remarks Windows 95 only.
+        @onlyfor{wxmsw}
 
         @see SetTickFreq()
     */
 
         @see SetTickFreq()
     */
-    int GetTickFreq() const;
+    virtual int GetTickFreq() const;
 
     /**
         Gets the current slider value.
 
         @see GetMin(), GetMax(), SetValue()
     */
 
     /**
         Gets the current slider value.
 
         @see GetMin(), GetMax(), SetValue()
     */
-    int GetValue() const;
+    virtual int GetValue() const;
 
     /**
         Sets the line size for the slider.
 
         @param lineSize
 
     /**
         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()
     */
 
         @see GetLineSize()
     */
-    void SetLineSize(int lineSize);
+    virtual void SetLineSize(int lineSize);
 
     /**
         Sets the page size for the slider.
 
     /**
         Sets the page size for the slider.
@@ -209,14 +272,14 @@ public:
 
         @see GetPageSize()
     */
 
         @see GetPageSize()
     */
-    void SetPageSize(int pageSize);
+    virtual void SetPageSize(int pageSize);
 
     /**
         Sets the minimum and maximum slider values.
 
         @see GetMin(), GetMax()
     */
 
     /**
         Sets the minimum and maximum slider values.
 
         @see GetMin(), GetMax()
     */
-    void SetRange(int minValue, int maxValue);
+    virtual void SetRange(int minValue, int maxValue);
 
     /**
         Sets the selection.
 
     /**
         Sets the selection.
@@ -226,11 +289,11 @@ public:
         @param endPos
             The selection end position.
 
         @param endPos
             The selection end position.
 
-        @remarks Windows 95 only.
+        @onlyfor{wxmsw}
 
         @see GetSelStart(), GetSelEnd()
     */
 
         @see GetSelStart(), GetSelEnd()
     */
-    void SetSelection(int startPos, int endPos);
+    virtual void SetSelection(int startPos, int endPos);
 
     /**
         Sets the slider thumb length.
 
     /**
         Sets the slider thumb length.
@@ -238,11 +301,11 @@ public:
         @param len
             The thumb length.
 
         @param len
             The thumb length.
 
-        @remarks Windows 95 only.
+        @onlyfor{wxmsw}
 
         @see GetThumbLength()
     */
 
         @see GetThumbLength()
     */
-    void SetThumbLength(int len);
+    virtual void SetThumbLength(int len);
 
     /**
         Sets a tick position.
 
     /**
         Sets a tick position.
@@ -250,27 +313,26 @@ public:
         @param tickPos
             The tick position.
 
         @param tickPos
             The tick position.
 
-        @remarks Windows 95 only.
+        @onlyfor{wxmsw}
 
         @see SetTickFreq()
     */
 
         @see SetTickFreq()
     */
-    void SetTick(int tickPos);
+    virtual void SetTick(int tickPos);
 
     /**
         Sets the tick mark frequency and position.
 
         @param n
             Frequency. For example, if the frequency is set to two, a tick mark is
 
     /**
         Sets the tick mark frequency and position.
 
         @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
         @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()
     */
 
         @see GetTickFreq()
     */
-    void SetTickFreq(int n, int pos);
+    virtual void SetTickFreq(int n, int pos);
 
     /**
         Sets the slider position.
 
     /**
         Sets the slider position.
@@ -278,6 +340,6 @@ public:
         @param value
             The slider position.
     */
         @param value
             The slider position.
     */
-    void SetValue(int value);
+    virtual void SetValue(int value);
 };
 
 };