Commit | Line | Data |
---|---|---|
23324ae1 FM |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: scrolbar.h | |
e54c96f1 | 3 | // Purpose: interface of wxScrollBar |
23324ae1 FM |
4 | // Author: wxWidgets team |
5 | // RCS-ID: $Id$ | |
526954c5 | 6 | // Licence: wxWindows licence |
23324ae1 FM |
7 | ///////////////////////////////////////////////////////////////////////////// |
8 | ||
9 | /** | |
10 | @class wxScrollBar | |
7c913512 | 11 | |
4876436a FM |
12 | A wxScrollBar is a control that represents a horizontal or vertical scrollbar. |
13 | ||
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. | |
16 | ||
17 | @remarks | |
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. | |
7c913512 | 34 | |
23324ae1 | 35 | @beginStyleTable |
8c6791e4 | 36 | @style{wxSB_HORIZONTAL} |
23324ae1 | 37 | Specifies a horizontal scrollbar. |
8c6791e4 | 38 | @style{wxSB_VERTICAL} |
23324ae1 FM |
39 | Specifies a vertical scrollbar. |
40 | @endStyleTable | |
7c913512 | 41 | |
3051a44a | 42 | @beginEventEmissionTable{wxScrollEvent} |
4876436a FM |
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)} | |
3a194bda | 50 | Process @c wxEVT_SCROLL_TOP scroll-to-top events (minimum position). |
4876436a | 51 | @event{EVT_SCROLL_BOTTOM(func)} |
3a194bda | 52 | Process @c wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position). |
4876436a | 53 | @event{EVT_SCROLL_LINEUP(func)} |
3a194bda | 54 | Process @c wxEVT_SCROLL_LINEUP line up events. |
4876436a | 55 | @event{EVT_SCROLL_LINEDOWN(func)} |
3a194bda | 56 | Process @c wxEVT_SCROLL_LINEDOWN line down events. |
4876436a | 57 | @event{EVT_SCROLL_PAGEUP(func)} |
3a194bda | 58 | Process @c wxEVT_SCROLL_PAGEUP page up events. |
4876436a | 59 | @event{EVT_SCROLL_PAGEDOWN(func)} |
3a194bda | 60 | Process @c wxEVT_SCROLL_PAGEDOWN page down events. |
4876436a | 61 | @event{EVT_SCROLL_THUMBTRACK(func)} |
3a194bda | 62 | Process @c wxEVT_SCROLL_THUMBTRACK thumbtrack events |
4876436a FM |
63 | (frequent events sent as the user drags the thumbtrack). |
64 | @event{EVT_SCROLL_THUMBRELEASE(func)} | |
3a194bda | 65 | Process @c wxEVT_SCROLL_THUMBRELEASE thumb release events. |
4876436a | 66 | @event{EVT_SCROLL_CHANGED(func)} |
3a194bda | 67 | Process @c wxEVT_SCROLL_CHANGED end of scrolling events (MSW only). |
4876436a FM |
68 | @event{EVT_COMMAND_SCROLL(id, func)} |
69 | Process all scroll events. | |
70 | @event{EVT_COMMAND_SCROLL_TOP(id, func)} | |
3a194bda | 71 | Process @c wxEVT_SCROLL_TOP scroll-to-top events (minimum position). |
4876436a | 72 | @event{EVT_COMMAND_SCROLL_BOTTOM(id, func)} |
3a194bda | 73 | Process @c wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position). |
4876436a | 74 | @event{EVT_COMMAND_SCROLL_LINEUP(id, func)} |
3a194bda | 75 | Process @c wxEVT_SCROLL_LINEUP line up events. |
4876436a | 76 | @event{EVT_COMMAND_SCROLL_LINEDOWN(id, func)} |
3a194bda | 77 | Process @c wxEVT_SCROLL_LINEDOWN line down events. |
4876436a | 78 | @event{EVT_COMMAND_SCROLL_PAGEUP(id, func)} |
3a194bda | 79 | Process @c wxEVT_SCROLL_PAGEUP page up events. |
4876436a | 80 | @event{EVT_COMMAND_SCROLL_PAGEDOWN(id, func)} |
3a194bda | 81 | Process @c wxEVT_SCROLL_PAGEDOWN page down events. |
4876436a | 82 | @event{EVT_COMMAND_SCROLL_THUMBTRACK(id, func)} |
3a194bda | 83 | Process @c wxEVT_SCROLL_THUMBTRACK thumbtrack events |
4876436a FM |
84 | (frequent events sent as the user drags the thumbtrack). |
85 | @event{EVT_COMMAND_SCROLL_THUMBRELEASE(func)} | |
3a194bda | 86 | Process @c wxEVT_SCROLL_THUMBRELEASE thumb release events. |
4876436a | 87 | @event{EVT_COMMAND_SCROLL_CHANGED(func)} |
3a194bda | 88 | Process @c wxEVT_SCROLL_CHANGED end of scrolling events (MSW only). |
4876436a FM |
89 | @endEventTable |
90 | ||
91 | @section scrollbar_diff The difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED | |
92 | ||
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). | |
96 | ||
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). | |
100 | ||
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. | |
105 | ||
23324ae1 FM |
106 | @library{wxcore} |
107 | @category{ctrl} | |
ce154616 | 108 | @appearance{scrollbar} |
7c913512 | 109 | |
830b7aa7 | 110 | @see @ref overview_scrolling, @ref overview_events, wxScrolled |
23324ae1 FM |
111 | */ |
112 | class wxScrollBar : public wxControl | |
113 | { | |
114 | public: | |
671600d8 RR |
115 | /** |
116 | Default constructor | |
117 | */ | |
118 | wxScrollBar(); | |
4876436a | 119 | |
23324ae1 FM |
120 | /** |
121 | Constructor, creating and showing a scrollbar. | |
3c4f71cc | 122 | |
7c913512 | 123 | @param parent |
4cc4bfaf | 124 | Parent window. Must be non-@NULL. |
7c913512 | 125 | @param id |
4cc4bfaf | 126 | Window identifier. The value wxID_ANY indicates a default value. |
7c913512 | 127 | @param pos |
dc1b07fd FM |
128 | Window position. |
129 | If ::wxDefaultPosition is specified then a default position is chosen. | |
7c913512 | 130 | @param size |
dc1b07fd FM |
131 | Window size. |
132 | If ::wxDefaultSize is specified then a default size is chosen. | |
7c913512 | 133 | @param style |
4cc4bfaf | 134 | Window style. See wxScrollBar. |
7c913512 | 135 | @param validator |
4cc4bfaf | 136 | Window validator. |
7c913512 | 137 | @param name |
4cc4bfaf | 138 | Window name. |
3c4f71cc | 139 | |
4cc4bfaf | 140 | @see Create(), wxValidator |
23324ae1 | 141 | */ |
7c913512 FM |
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, | |
11e3af6e | 147 | const wxString& name = wxScrollBarNameStr); |
23324ae1 FM |
148 | |
149 | /** | |
150 | Destructor, destroying the scrollbar. | |
151 | */ | |
adaaa686 | 152 | virtual ~wxScrollBar(); |
23324ae1 FM |
153 | |
154 | /** | |
155 | Scrollbar creation function called by the scrollbar constructor. | |
156 | See wxScrollBar() for details. | |
157 | */ | |
158 | bool Create(wxWindow* parent, wxWindowID id, | |
159 | const wxPoint& pos = wxDefaultPosition, | |
43c48e1e | 160 | const wxSize& size = wxDefaultSize, long style = wxSB_HORIZONTAL, |
23324ae1 | 161 | const wxValidator& validator = wxDefaultValidator, |
43c48e1e | 162 | const wxString& name = wxScrollBarNameStr); |
23324ae1 FM |
163 | |
164 | /** | |
4876436a FM |
165 | Returns the page size of the scrollbar. |
166 | ||
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. | |
3c4f71cc | 169 | |
4cc4bfaf | 170 | @see SetScrollbar() |
23324ae1 | 171 | */ |
adaaa686 | 172 | virtual int GetPageSize() const; |
23324ae1 FM |
173 | |
174 | /** | |
175 | Returns the length of the scrollbar. | |
3c4f71cc | 176 | |
4cc4bfaf | 177 | @see SetScrollbar() |
23324ae1 | 178 | */ |
adaaa686 | 179 | virtual int GetRange() const; |
23324ae1 FM |
180 | |
181 | /** | |
182 | Returns the current position of the scrollbar thumb. | |
3c4f71cc | 183 | |
4cc4bfaf | 184 | @see SetThumbPosition() |
23324ae1 | 185 | */ |
adaaa686 | 186 | virtual int GetThumbPosition() const; |
23324ae1 FM |
187 | |
188 | /** | |
189 | Returns the thumb or 'view' size. | |
3c4f71cc | 190 | |
4cc4bfaf | 191 | @see SetScrollbar() |
23324ae1 | 192 | */ |
adaaa686 | 193 | virtual int GetThumbSize() const; |
23324ae1 FM |
194 | |
195 | /** | |
196 | Sets the scrollbar properties. | |
3c4f71cc | 197 | |
7c913512 | 198 | @param position |
4cc4bfaf | 199 | The position of the scrollbar in scroll units. |
7c913512 | 200 | @param thumbSize |
4cc4bfaf | 201 | The size of the thumb, or visible portion of the scrollbar, in scroll units. |
7c913512 | 202 | @param range |
4cc4bfaf | 203 | The maximum position of the scrollbar. |
7c913512 | 204 | @param pageSize |
4cc4bfaf | 205 | The size of the page size in scroll units. This is the number of units |
4876436a FM |
206 | the scrollbar will scroll when it is paged up or down. |
207 | Often it is the same as the thumb size. | |
7c913512 | 208 | @param refresh |
4cc4bfaf | 209 | @true to redraw the scrollbar, @false otherwise. |
3c4f71cc | 210 | |
4876436a FM |
211 | @remarks |
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. | |
214 | You would use: | |
215 | @code | |
216 | scrollbar->SetScrollbar(0, 16, 50, 15); | |
217 | @endcode | |
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. | |
23324ae1 FM |
229 | */ |
230 | virtual void SetScrollbar(int position, int thumbSize, int range, | |
231 | int pageSize, | |
4cc4bfaf | 232 | bool refresh = true); |
23324ae1 FM |
233 | |
234 | /** | |
235 | Sets the position of the scrollbar. | |
3c4f71cc | 236 | |
7c913512 | 237 | @param viewStart |
4cc4bfaf | 238 | The position of the scrollbar thumb. |
3c4f71cc | 239 | |
4cc4bfaf | 240 | @see GetThumbPosition() |
23324ae1 | 241 | */ |
adaaa686 | 242 | virtual void SetThumbPosition(int viewStart); |
50e55c13 RD |
243 | |
244 | /** | |
245 | Returns @true for scrollbars that have the vertical style set. | |
246 | */ | |
247 | bool IsVertical() const; | |
23324ae1 | 248 | }; |
e54c96f1 | 249 |