1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxScrollBar
4 // Author: wxWidgets team
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
12 A wxScrollBar is a control that represents a horizontal or vertical scrollbar.
14 It is distinct from the two scrollbars that some windows provide automatically,
15 but the two types of scrollbar share the way events are received.
18 A scrollbar has the following main attributes: range, thumb size, page size, and position.
19 The range is the total number of units associated with the view represented by the scrollbar.
20 For a table with 15 columns, the range would be 15.
21 The thumb size is the number of units that are currently visible.
22 For the table example, the window might be sized so that only 5 columns are
23 currently visible, in which case the application would set the thumb size to 5.
24 When the thumb size becomes the same as or greater than the range, the scrollbar
25 will be automatically hidden on most platforms.
26 The page size is the number of units that the scrollbar should scroll by,
27 when 'paging' through the data. This value is normally the same as the thumb
28 size length, because it is natural to assume that the visible window size defines a page.
29 The scrollbar position is the current thumb position.
30 Most applications will find it convenient to provide a function called AdjustScrollbars()
31 which can be called initially, from an OnSize event handler, and whenever the
32 application data changes in size. It will adjust the view, object and page
33 size according to the size of the window and the size of the data.
36 @style{wxSB_HORIZONTAL}
37 Specifies a horizontal scrollbar.
39 Specifies a vertical scrollbar.
42 @beginEventEmissionTable{wxScrollEvent}
43 You can use EVT_COMMAND_SCROLL... macros with window IDs for when intercepting
44 scroll events from controls, or EVT_SCROLL... macros without window IDs for
45 intercepting scroll events from the receiving window -- except for this,
46 the macros behave exactly the same.
47 @event{EVT_SCROLL(func)}
48 Process all scroll events.
49 @event{EVT_SCROLL_TOP(func)}
50 Process @c wxEVT_SCROLL_TOP scroll-to-top events (minimum position).
51 @event{EVT_SCROLL_BOTTOM(func)}
52 Process @c wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position).
53 @event{EVT_SCROLL_LINEUP(func)}
54 Process @c wxEVT_SCROLL_LINEUP line up events.
55 @event{EVT_SCROLL_LINEDOWN(func)}
56 Process @c wxEVT_SCROLL_LINEDOWN line down events.
57 @event{EVT_SCROLL_PAGEUP(func)}
58 Process @c wxEVT_SCROLL_PAGEUP page up events.
59 @event{EVT_SCROLL_PAGEDOWN(func)}
60 Process @c wxEVT_SCROLL_PAGEDOWN page down events.
61 @event{EVT_SCROLL_THUMBTRACK(func)}
62 Process @c wxEVT_SCROLL_THUMBTRACK thumbtrack events
63 (frequent events sent as the user drags the thumbtrack).
64 @event{EVT_SCROLL_THUMBRELEASE(func)}
65 Process @c wxEVT_SCROLL_THUMBRELEASE thumb release events.
66 @event{EVT_SCROLL_CHANGED(func)}
67 Process @c wxEVT_SCROLL_CHANGED end of scrolling events (MSW only).
68 @event{EVT_COMMAND_SCROLL(id, func)}
69 Process all scroll events.
70 @event{EVT_COMMAND_SCROLL_TOP(id, func)}
71 Process @c wxEVT_SCROLL_TOP scroll-to-top events (minimum position).
72 @event{EVT_COMMAND_SCROLL_BOTTOM(id, func)}
73 Process @c wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position).
74 @event{EVT_COMMAND_SCROLL_LINEUP(id, func)}
75 Process @c wxEVT_SCROLL_LINEUP line up events.
76 @event{EVT_COMMAND_SCROLL_LINEDOWN(id, func)}
77 Process @c wxEVT_SCROLL_LINEDOWN line down events.
78 @event{EVT_COMMAND_SCROLL_PAGEUP(id, func)}
79 Process @c wxEVT_SCROLL_PAGEUP page up events.
80 @event{EVT_COMMAND_SCROLL_PAGEDOWN(id, func)}
81 Process @c wxEVT_SCROLL_PAGEDOWN page down events.
82 @event{EVT_COMMAND_SCROLL_THUMBTRACK(id, func)}
83 Process @c wxEVT_SCROLL_THUMBTRACK thumbtrack events
84 (frequent events sent as the user drags the thumbtrack).
85 @event{EVT_COMMAND_SCROLL_THUMBRELEASE(func)}
86 Process @c wxEVT_SCROLL_THUMBRELEASE thumb release events.
87 @event{EVT_COMMAND_SCROLL_CHANGED(func)}
88 Process @c wxEVT_SCROLL_CHANGED end of scrolling events (MSW only).
91 @section scrollbar_diff The difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED
93 The EVT_SCROLL_THUMBRELEASE event is only emitted when actually dragging the
94 thumb using the mouse and releasing it (This EVT_SCROLL_THUMBRELEASE event
95 is also followed by an EVT_SCROLL_CHANGED event).
97 The EVT_SCROLL_CHANGED event also occurs when using the keyboard to change
98 the thumb position, and when clicking next to the thumb
99 (In all these cases the EVT_SCROLL_THUMBRELEASE event does not happen).
101 In short, the EVT_SCROLL_CHANGED event is triggered when scrolling/moving has
102 finished independently of the way it had started. Please see the widgets sample
103 ("Slider" page) to see the difference between EVT_SCROLL_THUMBRELEASE and
104 EVT_SCROLL_CHANGED in action.
108 @appearance{scrollbar}
110 @see @ref overview_scrolling, @ref overview_events, wxScrolled
112 class wxScrollBar
: public wxControl
121 Constructor, creating and showing a scrollbar.
124 Parent window. Must be non-@NULL.
126 Window identifier. The value wxID_ANY indicates a default value.
129 If ::wxDefaultPosition is specified then a default position is chosen.
132 If ::wxDefaultSize is specified then a default size is chosen.
134 Window style. See wxScrollBar.
140 @see Create(), wxValidator
142 wxScrollBar(wxWindow
* parent
, wxWindowID id
,
143 const wxPoint
& pos
= wxDefaultPosition
,
144 const wxSize
& size
= wxDefaultSize
,
145 long style
= wxSB_HORIZONTAL
,
146 const wxValidator
& validator
= wxDefaultValidator
,
147 const wxString
& name
= wxScrollBarNameStr
);
150 Destructor, destroying the scrollbar.
152 virtual ~wxScrollBar();
155 Scrollbar creation function called by the scrollbar constructor.
156 See wxScrollBar() for details.
158 bool Create(wxWindow
* parent
, wxWindowID id
,
159 const wxPoint
& pos
= wxDefaultPosition
,
160 const wxSize
& size
= wxDefaultSize
, long style
= wxSB_HORIZONTAL
,
161 const wxValidator
& validator
= wxDefaultValidator
,
162 const wxString
& name
= wxScrollBarNameStr
);
165 Returns the page size of the scrollbar.
167 This is the number of scroll units that will be scrolled when the user
168 pages up or down. Often it is the same as the thumb size.
172 virtual int GetPageSize() const;
175 Returns the length of the scrollbar.
179 virtual int GetRange() const;
182 Returns the current position of the scrollbar thumb.
184 @see SetThumbPosition()
186 virtual int GetThumbPosition() const;
189 Returns the thumb or 'view' size.
193 virtual int GetThumbSize() const;
196 Sets the scrollbar properties.
199 The position of the scrollbar in scroll units.
201 The size of the thumb, or visible portion of the scrollbar, in scroll units.
203 The maximum position of the scrollbar.
205 The size of the page size in scroll units. This is the number of units
206 the scrollbar will scroll when it is paged up or down.
207 Often it is the same as the thumb size.
209 @true to redraw the scrollbar, @false otherwise.
212 Let's say you wish to display 50 lines of text, using the same
213 font. The window is sized so that you can only see 16 lines at a time.
216 scrollbar->SetScrollbar(0, 16, 50, 15);
218 The page size is 1 less than the thumb size so that the last line of
219 the previous page will be visible on the next page, to help orient the user.
220 Note that with the window at this size, the thumb position can never
221 go above 50 minus 16, or 34.
222 You can determine how many lines are currently visible by dividing
223 the current view size by the character height in pixels.
224 When defining your own scrollbar behaviour, you will always need to
225 recalculate the scrollbar settings when the window size changes.
226 You could therefore put your scrollbar calculations and SetScrollbar()
227 call into a function named AdjustScrollbars, which can be called
228 initially and also from a wxSizeEvent event handler function.
230 virtual void SetScrollbar(int position
, int thumbSize
, int range
,
232 bool refresh
= true);
235 Sets the position of the scrollbar.
238 The position of the scrollbar thumb.
240 @see GetThumbPosition()
242 virtual void SetThumbPosition(int viewStart
);
245 Returns @true for scrollbars that have the vertical style set.
247 bool IsVertical() const;