X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/adaaa68635b4c8a4d8c5284add40366ea3eefb07..76b92fa5c75d542c44dcccd551e432fbad660fda:/interface/wx/scrolbar.h diff --git a/interface/wx/scrolbar.h b/interface/wx/scrolbar.h index 8ca586e5b2..5ecc481320 100644 --- a/interface/wx/scrolbar.h +++ b/interface/wx/scrolbar.h @@ -3,16 +3,34 @@ // Purpose: interface of wxScrollBar // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @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} @@ -21,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 { @@ -34,7 +116,7 @@ public: Default constructor */ wxScrollBar(); - + /** 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 - 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 @@ -62,7 +144,7 @@ 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. @@ -75,15 +157,15 @@ 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() */ @@ -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 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,