]>
Commit | Line | Data |
---|---|---|
23324ae1 FM |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: button.h | |
e54c96f1 | 3 | // Purpose: interface of wxButton |
23324ae1 FM |
4 | // Author: wxWidgets team |
5 | // RCS-ID: $Id$ | |
526954c5 | 6 | // Licence: wxWindows licence |
23324ae1 FM |
7 | ///////////////////////////////////////////////////////////////////////////// |
8 | ||
9 | /** | |
10 | @class wxButton | |
7c913512 | 11 | |
8024723d FM |
12 | A button is a control that contains a text string, and is one of the most |
13 | common elements of a GUI. | |
14 | ||
15 | It may be placed on a @ref wxDialog "dialog box" or on a @ref wxPanel panel, | |
16 | or indeed on almost any other window. | |
7c913512 | 17 | |
23324ae1 | 18 | @beginStyleTable |
8c6791e4 | 19 | @style{wxBU_LEFT} |
a2117591 | 20 | Left-justifies the label. Windows and GTK+ only. |
8c6791e4 | 21 | @style{wxBU_TOP} |
a2117591 | 22 | Aligns the label to the top of the button. Windows and GTK+ only. |
8c6791e4 | 23 | @style{wxBU_RIGHT} |
a2117591 | 24 | Right-justifies the bitmap label. Windows and GTK+ only. |
8c6791e4 | 25 | @style{wxBU_BOTTOM} |
a2117591 | 26 | Aligns the label to the bottom of the button. Windows and GTK+ only. |
8c6791e4 | 27 | @style{wxBU_EXACTFIT} |
a2117591 VZ |
28 | Creates the button as small as possible instead of making it of the |
29 | standard size (which is the default behaviour ). | |
30 | @style{wxBU_NOTEXT} | |
31 | Disables the display of the text label in the button even if it has one | |
32 | or its id is one of the standard stock ids with an associated label: | |
33 | without using this style a button which is only supposed to show a | |
34 | bitmap but uses a standard id would display a label too. | |
8c6791e4 | 35 | @style{wxBORDER_NONE} |
6398a32d | 36 | Creates a button without border. This is currently implemented in MSW, |
e5d05b90 VZ |
37 | GTK2 and OSX/Carbon ports but in the latter only applies to buttons |
38 | with bitmaps and using bitmap of one of the standard sizes only, namely | |
6398a32d VZ |
39 | 128*128, 48*48, 24*24 or 16*16. In all the other cases wxBORDER_NONE is |
40 | ignored under OSX. | |
23324ae1 | 41 | @endStyleTable |
7c913512 | 42 | |
0f5fe332 VZ |
43 | By default, i.e. if none of the alignment styles are specified, the label |
44 | is centered both horizontally and vertically. If the button has both a | |
45 | label and a bitmap, the alignment styles above specify the location of the | |
46 | rectangle combining both the label and the bitmap and the bitmap position | |
47 | set with wxButton::SetBitmapPosition() defines the relative position of the | |
48 | bitmap with respect to the label (however currently non-default alignment | |
49 | combinations are not implemented on all platforms). | |
50 | ||
3051a44a | 51 | @beginEventEmissionTable{wxCommandEvent} |
8c6791e4 | 52 | @event{EVT_BUTTON(id, func)} |
3a194bda | 53 | Process a @c wxEVT_COMMAND_BUTTON_CLICKED event, when the button is clicked. |
23324ae1 | 54 | @endEventTable |
7c913512 | 55 | |
2352862a | 56 | |
e5d05b90 VZ |
57 | Since version 2.9.1 wxButton supports showing both text and an image |
58 | (currently only when using wxMSW, wxGTK or wxOSX/Cocoa ports), see | |
2352862a VZ |
59 | SetBitmap() and SetBitmapLabel(), SetBitmapDisabled() &c methods. In the |
60 | previous wxWidgets versions this functionality was only available in (the | |
61 | now trivial) wxBitmapButton class which was only capable of showing an | |
62 | image without text. | |
63 | ||
64 | A button may have either a single image for all states or different images | |
e5d05b90 VZ |
65 | for the following states (different images are not currently supported |
66 | under OS X where the normal image is used for all states): | |
2352862a VZ |
67 | @li @b normal: the default state |
68 | @li @b disabled: bitmap shown when the button is disabled. | |
69 | @li @b pressed: bitmap shown when the button is pushed (e.g. while the user | |
70 | keeps the mouse button pressed on it) | |
71 | @li @b focus: bitmap shown when the button has keyboard focus (but is not | |
72 | pressed as in this case the button is in the pressed state) | |
73 | @li @b current: bitmap shown when the mouse is over the button (but it is | |
74 | not pressed although it may have focus). Notice that if current bitmap | |
75 | is not specified but the current platform UI uses hover images for the | |
76 | buttons (such as Windows XP or GTK+), then the focus bitmap is used for | |
77 | hover state as well. This makes it possible to set focus bitmap only to | |
78 | get reasonably good behaviour on all platforms. | |
79 | ||
80 | All of the bitmaps must be of the same size and the normal bitmap must be | |
81 | set first (to a valid bitmap), before setting any other ones. | |
82 | ||
83 | The position of the image inside the button be configured using | |
84 | SetBitmapPosition(). By default the image is on the left of the text. | |
85 | ||
b3f5fbf6 VZ |
86 | Please also notice that GTK+ uses a global setting called @c |
87 | gtk-button-images to determine if the images should be shown in the buttons | |
88 | at all. If it is off (which is the case in e.g. Gnome 2.28 by default), no | |
89 | images will be shown, consistently with the native behaviour. | |
90 | ||
23324ae1 FM |
91 | @library{wxcore} |
92 | @category{ctrl} | |
7e59b885 | 93 | @appearance{button.png} |
7c913512 | 94 | |
e54c96f1 | 95 | @see wxBitmapButton |
23324ae1 FM |
96 | */ |
97 | class wxButton : public wxControl | |
98 | { | |
99 | public: | |
8024723d FM |
100 | /** |
101 | Default ctor. | |
102 | */ | |
103 | wxButton(); | |
104 | ||
23324ae1 FM |
105 | /** |
106 | Constructor, creating and showing a button. | |
8024723d | 107 | |
23324ae1 | 108 | The preferred way to create standard buttons is to use default value of |
8024723d | 109 | @a label. If no label is supplied and @a id is one of standard IDs from |
01495abf VZ |
110 | @ref page_stockitems "this list", a standard label will be used. In |
111 | other words, if you use a predefined @c wxID_XXX constant, just omit | |
112 | the label completely rather than specifying it. In particular, help | |
113 | buttons (the ones with @a id of @c wxID_HELP) under Mac OS X can't | |
114 | display any label at all and while wxButton will detect if the standard | |
115 | "Help" label is used and ignore it, using any other label will prevent | |
116 | the button from correctly appearing as a help button and so should be | |
117 | avoided. | |
118 | ||
8024723d FM |
119 | |
120 | In addition to that, the button will be decorated with stock icons under GTK+ 2. | |
121 | ||
7c913512 | 122 | @param parent |
4cc4bfaf | 123 | Parent window. Must not be @NULL. |
7c913512 | 124 | @param id |
4cc4bfaf | 125 | Button identifier. A value of wxID_ANY indicates a default value. |
7c913512 | 126 | @param label |
4cc4bfaf | 127 | Text to be displayed on the button. |
7c913512 | 128 | @param pos |
4cc4bfaf | 129 | Button position. |
7c913512 | 130 | @param size |
4cc4bfaf FM |
131 | Button size. If the default size is specified then the button is sized |
132 | appropriately for the text. | |
7c913512 | 133 | @param style |
8024723d | 134 | Window style. See wxButton class description. |
7c913512 | 135 | @param validator |
4cc4bfaf | 136 | Window validator. |
7c913512 | 137 | @param name |
4cc4bfaf | 138 | Window name. |
8024723d | 139 | |
4cc4bfaf | 140 | @see Create(), wxValidator |
23324ae1 | 141 | */ |
7c913512 FM |
142 | wxButton(wxWindow* parent, wxWindowID id, |
143 | const wxString& label = wxEmptyString, | |
144 | const wxPoint& pos = wxDefaultPosition, | |
145 | const wxSize& size = wxDefaultSize, | |
146 | long style = 0, | |
147 | const wxValidator& validator = wxDefaultValidator, | |
a6052817 | 148 | const wxString& name = wxButtonNameStr); |
23324ae1 | 149 | |
23324ae1 | 150 | /** |
8024723d FM |
151 | Button creation function for two-step creation. |
152 | For more details, see wxButton(). | |
23324ae1 FM |
153 | */ |
154 | bool Create(wxWindow* parent, wxWindowID id, | |
155 | const wxString& label = wxEmptyString, | |
156 | const wxPoint& pos = wxDefaultPosition, | |
157 | const wxSize& size = wxDefaultSize, | |
158 | long style = 0, | |
a6052817 FM |
159 | const wxValidator& validator = wxDefaultValidator, |
160 | const wxString& name = wxButtonNameStr); | |
23324ae1 | 161 | |
f2d7fdf7 VZ |
162 | /** |
163 | Returns @true if an authentication needed symbol is displayed on the | |
164 | button. | |
165 | ||
166 | @remarks This method always returns @false if the platform is not | |
167 | Windows Vista or newer. | |
168 | ||
169 | @see SetAuthNeeded() | |
170 | ||
171 | @since 2.9.1 | |
172 | */ | |
173 | bool GetAuthNeeded() const; | |
174 | ||
2352862a VZ |
175 | /** |
176 | Return the bitmap shown by the button. | |
177 | ||
178 | The returned bitmap may be invalid only if the button doesn't show any | |
179 | images. | |
180 | ||
181 | @see SetBitmap() | |
182 | ||
183 | @since 2.9.1 | |
184 | */ | |
185 | wxBitmap GetBitmap() const; | |
186 | ||
187 | /** | |
188 | Returns the bitmap used when the mouse is over the button, which may be | |
189 | invalid. | |
190 | ||
191 | @see SetBitmapCurrent() | |
192 | ||
193 | @since 2.9.1 (available as wxBitmapButton::GetBitmapHover() in previous | |
194 | versions) | |
195 | */ | |
196 | wxBitmap GetBitmapCurrent() const; | |
197 | ||
198 | /** | |
199 | Returns the bitmap for the disabled state, which may be invalid. | |
200 | ||
201 | @see SetBitmapDisabled() | |
202 | ||
203 | @since 2.9.1 (available in wxBitmapButton only in previous versions) | |
204 | */ | |
205 | wxBitmap GetBitmapDisabled() const; | |
206 | ||
207 | /** | |
208 | Returns the bitmap for the focused state, which may be invalid. | |
209 | ||
210 | @see SetBitmapFocus() | |
211 | ||
212 | @since 2.9.1 (available in wxBitmapButton only in previous versions) | |
213 | */ | |
214 | wxBitmap GetBitmapFocus() const; | |
215 | ||
216 | /** | |
217 | Returns the bitmap for the normal state. | |
218 | ||
219 | This is exactly the same as GetBitmap() but uses a name | |
220 | backwards-compatible with wxBitmapButton. | |
221 | ||
222 | @see SetBitmap(), SetBitmapLabel() | |
223 | ||
224 | @since 2.9.1 (available in wxBitmapButton only in previous versions) | |
225 | */ | |
226 | wxBitmap GetBitmapLabel() const; | |
227 | ||
228 | /** | |
229 | Returns the bitmap for the pressed state, which may be invalid. | |
230 | ||
231 | @see SetBitmapPressed() | |
232 | ||
233 | @since 2.9.1 (available as wxBitmapButton::GetBitmapSelected() in | |
234 | previous versions) | |
235 | */ | |
236 | wxBitmap GetBitmapPressed() const; | |
237 | ||
1404c3f3 RD |
238 | /** |
239 | Get the margins between the bitmap and the text of the button. | |
240 | ||
241 | @see SetBitmapMargins() | |
242 | ||
243 | @since 2.9.1 | |
244 | */ | |
245 | wxSize GetBitmapMargins(); | |
246 | ||
23324ae1 FM |
247 | /** |
248 | Returns the default size for the buttons. It is advised to make all the dialog | |
249 | buttons of the same size and this function allows to retrieve the (platform and | |
250 | current font dependent size) which should be the best suited for this. | |
251 | */ | |
d2aa927a | 252 | static wxSize GetDefaultSize(); |
23324ae1 FM |
253 | |
254 | /** | |
255 | Returns the string label for the button. | |
8024723d | 256 | |
4cc4bfaf | 257 | @see SetLabel() |
23324ae1 | 258 | */ |
328f5751 | 259 | wxString GetLabel() const; |
23324ae1 | 260 | |
f2d7fdf7 VZ |
261 | /** |
262 | Sets whether an authentication needed symbol should be displayed on the | |
263 | button. | |
264 | ||
265 | @remarks This method doesn't do anything if the platform is not Windows | |
266 | Vista or newer. | |
267 | ||
268 | @see GetAuthNeeded() | |
269 | ||
270 | @since 2.9.1 | |
271 | */ | |
272 | void SetAuthNeeded(bool needed = true); | |
273 | ||
2352862a VZ |
274 | /** |
275 | Sets the bitmap to display in the button. | |
276 | ||
277 | The bitmap is displayed together with the button label. This method | |
278 | sets up a single bitmap which is used in all button states, use | |
279 | SetBitmapDisabled(), SetBitmapPressed(), SetBitmapCurrent() or | |
280 | SetBitmapFocus() to change the individual images used in different | |
281 | states. | |
282 | ||
283 | @param bitmap | |
284 | The bitmap to display in the button. May be invalid to remove any | |
285 | currently displayed bitmap. | |
286 | @param dir | |
287 | The position of the bitmap inside the button. By default it is | |
288 | positioned to the left of the text, near to the left button border. | |
289 | Other possible values include wxRIGHT, wxTOP and wxBOTTOM. | |
290 | ||
291 | @see SetBitmapPosition(), SetBitmapMargins() | |
292 | ||
293 | @since 2.9.1 | |
294 | */ | |
295 | void SetBitmap(const wxBitmap& bitmap, wxDirection dir = wxLEFT); | |
296 | ||
297 | /** | |
298 | Sets the bitmap to be shown when the mouse is over the button. | |
299 | ||
300 | @see GetBitmapCurrent() | |
301 | ||
302 | @since 2.9.1 (available as wxBitmapButton::SetBitmapHover() in previous | |
303 | versions) | |
304 | */ | |
305 | void SetBitmapCurrent(const wxBitmap& bitmap); | |
306 | ||
307 | /** | |
308 | Sets the bitmap for the disabled button appearance. | |
309 | ||
310 | @see GetBitmapDisabled(), SetBitmapLabel(), | |
311 | SetBitmapPressed(), SetBitmapFocus() | |
312 | ||
313 | @since 2.9.1 (available in wxBitmapButton only in previous versions) | |
314 | */ | |
315 | void SetBitmapDisabled(const wxBitmap& bitmap); | |
316 | ||
317 | /** | |
318 | Sets the bitmap for the button appearance when it has the keyboard | |
319 | focus. | |
320 | ||
321 | @see GetBitmapFocus(), SetBitmapLabel(), | |
322 | SetBitmapPressed(), SetBitmapDisabled() | |
323 | ||
324 | @since 2.9.1 (available in wxBitmapButton only in previous versions) | |
325 | */ | |
326 | void SetBitmapFocus(const wxBitmap& bitmap); | |
327 | ||
328 | /** | |
329 | Sets the bitmap label for the button. | |
330 | ||
331 | @remarks This is the bitmap used for the unselected state, and for all | |
332 | other states if no other bitmaps are provided. | |
333 | ||
334 | @see SetBitmap(), GetBitmapLabel() | |
335 | ||
336 | @since 2.9.1 (available in wxBitmapButton only in previous versions) | |
337 | */ | |
338 | void SetBitmapLabel(const wxBitmap& bitmap); | |
339 | ||
340 | /** | |
341 | Sets the bitmap for the selected (depressed) button appearance. | |
342 | ||
343 | @since 2.9.1 (available as wxBitmapButton::SetBitmapSelected() in | |
344 | previous versions) | |
345 | */ | |
346 | void SetBitmapPressed(const wxBitmap& bitmap); | |
347 | ||
348 | /** | |
349 | Set the margins between the bitmap and the text of the button. | |
350 | ||
351 | This method is currently only implemented under MSW. If it is not | |
352 | called, default margin is used around the bitmap. | |
353 | ||
354 | @see SetBitmap(), SetBitmapPosition() | |
355 | ||
356 | @since 2.9.1 | |
357 | */ | |
358 | //@{ | |
359 | void SetBitmapMargins(wxCoord x, wxCoord y); | |
360 | void SetBitmapMargins(const wxSize& sz); | |
361 | //@} | |
362 | ||
363 | /** | |
364 | Set the position at which the bitmap is displayed. | |
365 | ||
366 | This method should only be called if the button does have an associated | |
367 | bitmap. | |
368 | ||
369 | @since 2.9.1 | |
370 | ||
371 | @param dir | |
372 | Direction in which the bitmap should be positioned, one of wxLEFT, | |
373 | wxRIGHT, wxTOP or wxBOTTOM. | |
374 | */ | |
375 | void SetBitmapPosition(wxDirection dir); | |
376 | ||
23324ae1 | 377 | /** |
2fd0ada5 FM |
378 | This sets the button to be the default item in its top-level window |
379 | (e.g. the panel or the dialog box containing it). | |
8024723d FM |
380 | |
381 | As normal, pressing return causes the default button to be depressed when | |
382 | the return key is pressed. | |
383 | ||
384 | See also wxWindow::SetFocus() which sets the keyboard focus for windows | |
385 | and text panel items, and wxTopLevelWindow::SetDefaultItem(). | |
386 | ||
23324ae1 | 387 | @remarks Under Windows, only dialog box buttons respond to this function. |
2fd0ada5 | 388 | |
d29a9a8a | 389 | @return the old default item (possibly NULL) |
23324ae1 | 390 | */ |
2fd0ada5 | 391 | virtual wxWindow* SetDefault(); |
23324ae1 FM |
392 | |
393 | /** | |
394 | Sets the string label for the button. | |
8024723d | 395 | |
7c913512 | 396 | @param label |
4cc4bfaf | 397 | The label to set. |
23324ae1 FM |
398 | */ |
399 | void SetLabel(const wxString& label); | |
400 | }; | |
e54c96f1 | 401 |