]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/button.h
Added wxPropertyGridInterface::SetColumnProportion(); wxPG_SPLITTER_AUTO_CENTER windo...
[wxWidgets.git] / interface / wx / button.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: button.h
3 // Purpose: interface of wxButton
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 @class wxButton
11
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.
17
18 @beginStyleTable
19 @style{wxBU_LEFT}
20 Left-justifies the label. Windows and GTK+ only.
21 @style{wxBU_TOP}
22 Aligns the label to the top of the button. Windows and GTK+ only.
23 @style{wxBU_RIGHT}
24 Right-justifies the bitmap label. Windows and GTK+ only.
25 @style{wxBU_BOTTOM}
26 Aligns the label to the bottom of the button. Windows and GTK+ only.
27 @style{wxBU_EXACTFIT}
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.
35 @style{wxBORDER_NONE}
36 Creates a button without border. This is currently implemented in MSW,
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
39 128*128, 48*48, 24*24 or 16*16. In all the other cases wxBORDER_NONE is
40 ignored under OSX.
41 @endStyleTable
42
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
51 @beginEventEmissionTable{wxCommandEvent}
52 @event{EVT_BUTTON(id, func)}
53 Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is clicked.
54 @endEventTable
55
56
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
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
65 for the following states (different images are not currently supported
66 under OS X where the normal image is used for all states):
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
86 @library{wxcore}
87 @category{ctrl}
88 @appearance{button.png}
89
90 @see wxBitmapButton
91 */
92 class wxButton : public wxControl
93 {
94 public:
95 /**
96 Default ctor.
97 */
98 wxButton();
99
100 /**
101 Constructor, creating and showing a button.
102
103 The preferred way to create standard buttons is to use default value of
104 @a label. If no label is supplied and @a id is one of standard IDs from
105 @ref page_stockitems "this list", a standard label will be used.
106
107 In addition to that, the button will be decorated with stock icons under GTK+ 2.
108
109 @param parent
110 Parent window. Must not be @NULL.
111 @param id
112 Button identifier. A value of wxID_ANY indicates a default value.
113 @param label
114 Text to be displayed on the button.
115 @param pos
116 Button position.
117 @param size
118 Button size. If the default size is specified then the button is sized
119 appropriately for the text.
120 @param style
121 Window style. See wxButton class description.
122 @param validator
123 Window validator.
124 @param name
125 Window name.
126
127 @see Create(), wxValidator
128 */
129 wxButton(wxWindow* parent, wxWindowID id,
130 const wxString& label = wxEmptyString,
131 const wxPoint& pos = wxDefaultPosition,
132 const wxSize& size = wxDefaultSize,
133 long style = 0,
134 const wxValidator& validator = wxDefaultValidator,
135 const wxString& name = wxButtonNameStr);
136
137 /**
138 Button creation function for two-step creation.
139 For more details, see wxButton().
140 */
141 bool Create(wxWindow* parent, wxWindowID id,
142 const wxString& label = wxEmptyString,
143 const wxPoint& pos = wxDefaultPosition,
144 const wxSize& size = wxDefaultSize,
145 long style = 0,
146 const wxValidator& validator = wxDefaultValidator,
147 const wxString& name = wxButtonNameStr);
148
149 /**
150 Returns @true if an authentication needed symbol is displayed on the
151 button.
152
153 @remarks This method always returns @false if the platform is not
154 Windows Vista or newer.
155
156 @see SetAuthNeeded()
157
158 @since 2.9.1
159 */
160 bool GetAuthNeeded() const;
161
162 /**
163 Return the bitmap shown by the button.
164
165 The returned bitmap may be invalid only if the button doesn't show any
166 images.
167
168 @see SetBitmap()
169
170 @since 2.9.1
171 */
172 wxBitmap GetBitmap() const;
173
174 /**
175 Returns the bitmap used when the mouse is over the button, which may be
176 invalid.
177
178 @see SetBitmapCurrent()
179
180 @since 2.9.1 (available as wxBitmapButton::GetBitmapHover() in previous
181 versions)
182 */
183 wxBitmap GetBitmapCurrent() const;
184
185 /**
186 Returns the bitmap for the disabled state, which may be invalid.
187
188 @see SetBitmapDisabled()
189
190 @since 2.9.1 (available in wxBitmapButton only in previous versions)
191 */
192 wxBitmap GetBitmapDisabled() const;
193
194 /**
195 Returns the bitmap for the focused state, which may be invalid.
196
197 @see SetBitmapFocus()
198
199 @since 2.9.1 (available in wxBitmapButton only in previous versions)
200 */
201 wxBitmap GetBitmapFocus() const;
202
203 /**
204 Returns the bitmap for the normal state.
205
206 This is exactly the same as GetBitmap() but uses a name
207 backwards-compatible with wxBitmapButton.
208
209 @see SetBitmap(), SetBitmapLabel()
210
211 @since 2.9.1 (available in wxBitmapButton only in previous versions)
212 */
213 wxBitmap GetBitmapLabel() const;
214
215 /**
216 Returns the bitmap for the pressed state, which may be invalid.
217
218 @see SetBitmapPressed()
219
220 @since 2.9.1 (available as wxBitmapButton::GetBitmapSelected() in
221 previous versions)
222 */
223 wxBitmap GetBitmapPressed() const;
224
225 /**
226 Returns the default size for the buttons. It is advised to make all the dialog
227 buttons of the same size and this function allows to retrieve the (platform and
228 current font dependent size) which should be the best suited for this.
229 */
230 static wxSize GetDefaultSize();
231
232 /**
233 Returns the string label for the button.
234
235 @see SetLabel()
236 */
237 wxString GetLabel() const;
238
239 /**
240 Sets whether an authentication needed symbol should be displayed on the
241 button.
242
243 @remarks This method doesn't do anything if the platform is not Windows
244 Vista or newer.
245
246 @see GetAuthNeeded()
247
248 @since 2.9.1
249 */
250 void SetAuthNeeded(bool needed = true);
251
252 /**
253 Sets the bitmap to display in the button.
254
255 The bitmap is displayed together with the button label. This method
256 sets up a single bitmap which is used in all button states, use
257 SetBitmapDisabled(), SetBitmapPressed(), SetBitmapCurrent() or
258 SetBitmapFocus() to change the individual images used in different
259 states.
260
261 @param bitmap
262 The bitmap to display in the button. May be invalid to remove any
263 currently displayed bitmap.
264 @param dir
265 The position of the bitmap inside the button. By default it is
266 positioned to the left of the text, near to the left button border.
267 Other possible values include wxRIGHT, wxTOP and wxBOTTOM.
268
269 @see SetBitmapPosition(), SetBitmapMargins()
270
271 @since 2.9.1
272 */
273 void SetBitmap(const wxBitmap& bitmap, wxDirection dir = wxLEFT);
274
275 /**
276 Sets the bitmap to be shown when the mouse is over the button.
277
278 @see GetBitmapCurrent()
279
280 @since 2.9.1 (available as wxBitmapButton::SetBitmapHover() in previous
281 versions)
282 */
283 void SetBitmapCurrent(const wxBitmap& bitmap);
284
285 /**
286 Sets the bitmap for the disabled button appearance.
287
288 @see GetBitmapDisabled(), SetBitmapLabel(),
289 SetBitmapPressed(), SetBitmapFocus()
290
291 @since 2.9.1 (available in wxBitmapButton only in previous versions)
292 */
293 void SetBitmapDisabled(const wxBitmap& bitmap);
294
295 /**
296 Sets the bitmap for the button appearance when it has the keyboard
297 focus.
298
299 @see GetBitmapFocus(), SetBitmapLabel(),
300 SetBitmapPressed(), SetBitmapDisabled()
301
302 @since 2.9.1 (available in wxBitmapButton only in previous versions)
303 */
304 void SetBitmapFocus(const wxBitmap& bitmap);
305
306 /**
307 Sets the bitmap label for the button.
308
309 @remarks This is the bitmap used for the unselected state, and for all
310 other states if no other bitmaps are provided.
311
312 @see SetBitmap(), GetBitmapLabel()
313
314 @since 2.9.1 (available in wxBitmapButton only in previous versions)
315 */
316 void SetBitmapLabel(const wxBitmap& bitmap);
317
318 /**
319 Sets the bitmap for the selected (depressed) button appearance.
320
321 @since 2.9.1 (available as wxBitmapButton::SetBitmapSelected() in
322 previous versions)
323 */
324 void SetBitmapPressed(const wxBitmap& bitmap);
325
326 /**
327 Set the margins between the bitmap and the text of the button.
328
329 This method is currently only implemented under MSW. If it is not
330 called, default margin is used around the bitmap.
331
332 @see SetBitmap(), SetBitmapPosition()
333
334 @since 2.9.1
335 */
336 //@{
337 void SetBitmapMargins(wxCoord x, wxCoord y);
338 void SetBitmapMargins(const wxSize& sz);
339 //@}
340
341 /**
342 Set the position at which the bitmap is displayed.
343
344 This method should only be called if the button does have an associated
345 bitmap.
346
347 @since 2.9.1
348
349 @param dir
350 Direction in which the bitmap should be positioned, one of wxLEFT,
351 wxRIGHT, wxTOP or wxBOTTOM.
352 */
353 void SetBitmapPosition(wxDirection dir);
354
355 /**
356 This sets the button to be the default item in its top-level window
357 (e.g. the panel or the dialog box containing it).
358
359 As normal, pressing return causes the default button to be depressed when
360 the return key is pressed.
361
362 See also wxWindow::SetFocus() which sets the keyboard focus for windows
363 and text panel items, and wxTopLevelWindow::SetDefaultItem().
364
365 @remarks Under Windows, only dialog box buttons respond to this function.
366
367 @return the old default item (possibly NULL)
368 */
369 virtual wxWindow* SetDefault();
370
371 /**
372 Sets the string label for the button.
373
374 @param label
375 The label to set.
376 */
377 void SetLabel(const wxString& label);
378 };
379