Fix spelling in the comments in wxPropertyGrid code.

[wxWidgets.git] / interface / wx / scrolbar.h

diff --git a/interface/wx/scrolbar.h b/interface/wx/scrolbar.h
index db0395ecb7827c0d013f2cda8195aaf51ce6fa80..9a90d332ad81a965f58ba71fd4ce4bd681874513 100644 (file)
--- a/interface/wx/scrolbar.h
+++ b/interface/wx/scrolbar.h
@@ -3,16 +3,34 @@
 // Purpose:     interface of wxScrollBar
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxScrollBar
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
     @class wxScrollBar
 
 /////////////////////////////////////////////////////////////////////////////
 
 /**
     @class wxScrollBar
 

-    A wxScrollBar is a control that represents a horizontal or
-    vertical scrollbar. It is distinct from the two scrollbars that some windows
-    provide automatically, but the two types of scrollbar share the way
-    events are received.
+    A wxScrollBar is a control that represents a horizontal or vertical scrollbar.
+
+    It is distinct from the two scrollbars that some windows provide automatically,
+    but the two types of scrollbar share the way events are received.
+
+    @remarks
+    A scrollbar has the following main attributes: range, thumb size, page size, and position.
+    The range is the total number of units associated with the view represented by the scrollbar.
+    For a table with 15 columns, the range would be 15.
+    The thumb size is the number of units that are currently visible.
+    For the table example, the window might be sized so that only 5 columns are
+    currently visible, in which case the application would set the thumb size to 5.
+    When the thumb size becomes the same as or greater than the range, the scrollbar
+    will be automatically hidden on most platforms.
+    The page size is the number of units that the scrollbar should scroll by,
+    when 'paging' through the data. This value is normally the same as the thumb
+    size length, because it is natural to assume that the visible window size defines a page.
+    The scrollbar position is the current thumb position.
+    Most applications will find it convenient to provide a function called AdjustScrollbars()
+    which can be called initially, from an OnSize event handler, and whenever the
+    application data changes in size. It will adjust the view, object and page
+    size according to the size of the window and the size of the data.

 
     @beginStyleTable
     @style{wxSB_HORIZONTAL}
 
     @beginStyleTable
     @style{wxSB_HORIZONTAL}


@@ -21,11 +39,75 @@
            Specifies a vertical scrollbar.
     @endStyleTable
 
            Specifies a vertical scrollbar.
     @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 @c wxEVT_SCROLL_TOP scroll-to-top events (minimum position).
+    @event{EVT_SCROLL_BOTTOM(func)}
+        Process @c wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position).
+    @event{EVT_SCROLL_LINEUP(func)}
+        Process @c wxEVT_SCROLL_LINEUP line up events.
+    @event{EVT_SCROLL_LINEDOWN(func)}
+        Process @c wxEVT_SCROLL_LINEDOWN line down events.
+    @event{EVT_SCROLL_PAGEUP(func)}
+        Process @c wxEVT_SCROLL_PAGEUP page up events.
+    @event{EVT_SCROLL_PAGEDOWN(func)}
+        Process @c wxEVT_SCROLL_PAGEDOWN page down events.
+    @event{EVT_SCROLL_THUMBTRACK(func)}
+        Process @c wxEVT_SCROLL_THUMBTRACK thumbtrack events
+        (frequent events sent as the user drags the thumbtrack).
+    @event{EVT_SCROLL_THUMBRELEASE(func)}
+        Process @c wxEVT_SCROLL_THUMBRELEASE thumb release events.
+    @event{EVT_SCROLL_CHANGED(func)}
+        Process @c 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 @c wxEVT_SCROLL_TOP scroll-to-top events (minimum position).
+    @event{EVT_COMMAND_SCROLL_BOTTOM(id, func)}
+        Process @c wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position).
+    @event{EVT_COMMAND_SCROLL_LINEUP(id, func)}
+        Process @c wxEVT_SCROLL_LINEUP line up events.
+    @event{EVT_COMMAND_SCROLL_LINEDOWN(id, func)}
+        Process @c wxEVT_SCROLL_LINEDOWN line down events.
+    @event{EVT_COMMAND_SCROLL_PAGEUP(id, func)}
+        Process @c wxEVT_SCROLL_PAGEUP page up events.
+    @event{EVT_COMMAND_SCROLL_PAGEDOWN(id, func)}
+        Process @c wxEVT_SCROLL_PAGEDOWN page down events.
+    @event{EVT_COMMAND_SCROLL_THUMBTRACK(id, func)}
+        Process @c wxEVT_SCROLL_THUMBTRACK thumbtrack events
+        (frequent events sent as the user drags the thumbtrack).
+    @event{EVT_COMMAND_SCROLL_THUMBRELEASE(func)}
+        Process @c wxEVT_SCROLL_THUMBRELEASE thumb release events.
+    @event{EVT_COMMAND_SCROLL_CHANGED(func)}
+        Process @c wxEVT_SCROLL_CHANGED end of scrolling events (MSW only).
+    @endEventTable
+
+    @section scrollbar_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{scrollbar.png} -->
+    @appearance{scrollbar.png}

 
 

-    @see @ref overview_scrolling, @ref overview_eventhandling, wxScrolled
+    @see @ref overview_scrolling, @ref overview_events, wxScrolled

 */
 class wxScrollBar : public wxControl
 {
 */
 class wxScrollBar : public wxControl
 {


@@ -34,7 +116,7 @@ public:
       Default constructor
     */
     wxScrollBar();
       Default constructor
     */
     wxScrollBar();

-    
+

     /**
         Constructor, creating and showing a scrollbar.
 
     /**
         Constructor, creating and showing a scrollbar.
 


@@ -43,11 +125,11 @@ public:
         @param id
             Window identifier. The value wxID_ANY indicates a default value.
         @param pos
         @param id
             Window identifier. The value wxID_ANY indicates a default value.
         @param pos

-            Window position. If wxDefaultPosition is specified then a default
-        position is chosen.
+            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 wxScrollBar.
         @param validator
         @param style
             Window style. See wxScrollBar.
         @param validator


@@ -62,12 +144,12 @@ public:
                 const wxSize& size = wxDefaultSize,
                 long style = wxSB_HORIZONTAL,
                 const wxValidator& validator = wxDefaultValidator,
                 const wxSize& size = wxDefaultSize,
                 long style = wxSB_HORIZONTAL,
                 const wxValidator& validator = wxDefaultValidator,

-                const wxString& name = "scrollBar");
+                const wxString& name = wxScrollBarNameStr);

 
     /**
         Destructor, destroying the scrollbar.
     */
 
     /**
         Destructor, destroying the scrollbar.
     */

-    ~wxScrollBar();
+    virtual ~wxScrollBar();

 
     /**
         Scrollbar creation function called by the scrollbar constructor.
 
     /**
         Scrollbar creation function called by the scrollbar constructor.


@@ -75,40 +157,40 @@ public:
     */
     bool Create(wxWindow* parent, wxWindowID id,
                 const wxPoint& pos = wxDefaultPosition,
     */
     bool Create(wxWindow* parent, wxWindowID id,
                 const wxPoint& pos = wxDefaultPosition,

-                const wxSize& size = wxDefaultSize,
-                long style = wxSB_HORIZONTAL,
+                const wxSize& size = wxDefaultSize, long style = wxSB_HORIZONTAL,

                 const wxValidator& validator = wxDefaultValidator,
                 const wxValidator& validator = wxDefaultValidator,

-                const wxString& name = "scrollBar");
+                const wxString& name = wxScrollBarNameStr);

 
     /**
 
     /**

-        Returns the page size of the scrollbar. This is the number of scroll units
-        that will be scrolled when the user pages up or down. Often it is the
-        same as the thumb size.
+        Returns the page size of the scrollbar.
+
+        This is the number of scroll units that will be scrolled when the user
+        pages up or down. Often it is the same as the thumb size.

 
         @see SetScrollbar()
     */
 
         @see SetScrollbar()
     */

-    int GetPageSize() const;
+    virtual int GetPageSize() const;

 
     /**
         Returns the length of the scrollbar.
 
         @see SetScrollbar()
     */
 
     /**
         Returns the length of the scrollbar.
 
         @see SetScrollbar()
     */

-    int GetRange() const;
+    virtual int GetRange() const;

 
     /**
         Returns the current position of the scrollbar thumb.
 
         @see SetThumbPosition()
     */
 
     /**
         Returns the current position of the scrollbar thumb.
 
         @see SetThumbPosition()
     */

-    int GetThumbPosition() const;
+    virtual int GetThumbPosition() const;

 
     /**
         Returns the thumb or 'view' size.
 
         @see SetScrollbar()
     */
 
     /**
         Returns the thumb or 'view' size.
 
         @see SetScrollbar()
     */

-    int GetThumbSize() const;
+    virtual int GetThumbSize() const;

 
     /**
         Sets the scrollbar properties.
 
     /**
         Sets the scrollbar properties.


@@ -121,15 +203,29 @@ public:
             The maximum position of the scrollbar.
         @param pageSize
             The size of the page size in scroll units. This is the number of units
             The maximum position of the scrollbar.
         @param pageSize
             The size of the page size in scroll units. This is the number of units

-            the scrollbar will scroll when it is paged up or down. Often it is the same
-        as
-            the thumb size.
+            the scrollbar will scroll when it is paged up or down.
+            Often it is the same as the thumb size.

         @param refresh
             @true to redraw the scrollbar, @false otherwise.
 
         @param refresh
             @true to redraw the scrollbar, @false otherwise.
 

-        @remarks Let's say you wish to display 50 lines of text, using the same
-                 font. The window is sized so that you can only see 16
-                 lines at a time.
+        @remarks
+            Let's say you wish to display 50 lines of text, using the same
+            font. The window is sized so that you can only see 16 lines at a time.
+            You would use:
+            @code
+            scrollbar->SetScrollbar(0, 16, 50, 15);
+            @endcode
+            The page size is 1 less than the thumb size so that the last line of
+            the previous page will be visible on the next page, to help orient the user.
+            Note that with the window at this size, the thumb position can never
+            go above 50 minus 16, or 34.
+            You can determine how many lines are currently visible by dividing
+            the current view size by the character height in pixels.
+            When defining your own scrollbar behaviour, you will always need to
+            recalculate the scrollbar settings when the window size changes.
+            You could therefore put your scrollbar calculations and SetScrollbar()
+            call into a function named AdjustScrollbars, which can be called
+            initially and also from a wxSizeEvent event handler function.

     */
     virtual void SetScrollbar(int position, int thumbSize, int range,
                               int pageSize,
     */
     virtual void SetScrollbar(int position, int thumbSize, int range,
                               int pageSize,


@@ -143,6 +239,11 @@ public:
 
         @see GetThumbPosition()
     */
 
         @see GetThumbPosition()
     */

-    void SetThumbPosition(int viewStart);
+    virtual void SetThumbPosition(int viewStart);
+
+    /**
+       Returns @true for scrollbars that have the vertical style set.
+    */
+    bool IsVertical() const;

 };
 
 };