X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ae3c17b4013e80b99976c750c19fca47729517f6..50d4763f1710f6e45ac6af7112d1ce9effe93bc4:/interface/wx/scrolbar.h?ds=sidebyside diff --git a/interface/wx/scrolbar.h b/interface/wx/scrolbar.h index d6574c6b06..9a90d332ad 100644 --- a/interface/wx/scrolbar.h +++ b/interface/wx/scrolbar.h @@ -3,17 +3,34 @@ // Purpose: interface of wxScrollBar // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @class wxScrollBar - @wxheader{scrolbar.h} - 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} @@ -22,11 +39,75 @@ 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} - + @appearance{scrollbar.png} - @see @ref overview_scrolling, @ref overview_eventhandling, wxScrolled + @see @ref overview_scrolling, @ref overview_events, wxScrolled */ class wxScrollBar : public wxControl { @@ -35,7 +116,7 @@ public: Default constructor */ wxScrollBar(); - + /** Constructor, creating and showing a scrollbar. @@ -44,11 +125,11 @@ public: @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 - 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 @@ -63,12 +144,12 @@ public: const wxSize& size = wxDefaultSize, long style = wxSB_HORIZONTAL, const wxValidator& validator = wxDefaultValidator, - const wxString& name = "scrollBar"); + const wxString& name = wxScrollBarNameStr); /** Destructor, destroying the scrollbar. */ - ~wxScrollBar(); + virtual ~wxScrollBar(); /** Scrollbar creation function called by the scrollbar constructor. @@ -76,40 +157,40 @@ public: */ 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 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() */ - int GetPageSize() const; + virtual int GetPageSize() const; /** 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() */ - int GetThumbPosition() const; + virtual int GetThumbPosition() const; /** Returns the thumb or 'view' size. @see SetScrollbar() */ - int GetThumbSize() const; + virtual int GetThumbSize() const; /** Sets the scrollbar properties. @@ -122,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 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. - @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, @@ -144,6 +239,11 @@ public: @see GetThumbPosition() */ - void SetThumbPosition(int viewStart); + virtual void SetThumbPosition(int viewStart); + + /** + Returns @true for scrollbars that have the vertical style set. + */ + bool IsVertical() const; };