1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
|
/////////////////////////////////////////////////////////////////////////////
// Name: button.h
// Purpose: interface of wxButton
// Author: wxWidgets team
// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
@class wxButton
A button is a control that contains a text string, and is one of the most
common elements of a GUI.
It may be placed on a @ref wxDialog "dialog box" or on a @ref wxPanel panel,
or indeed on almost any other window.
By default, i.e. if none of the alignment styles are specified, the label
is centered both horizontally and vertically. If the button has both a
label and a bitmap, the alignment styles above specify the location of the
rectangle combining both the label and the bitmap and the bitmap position
set with wxButton::SetBitmapPosition() defines the relative position of the
bitmap with respect to the label (however currently non-default alignment
combinations are not implemented on all platforms).
Since version 2.9.1 wxButton supports showing both text and an image
(currently only when using wxMSW, wxGTK or wxOSX/Cocoa ports), see
SetBitmap() and SetBitmapLabel(), SetBitmapDisabled() &c methods. In the
previous wxWidgets versions this functionality was only available in (the
now trivial) wxBitmapButton class which was only capable of showing an
image without text.
A button may have either a single image for all states or different images
for the following states (different images are not currently supported
under OS X where the normal image is used for all states):
@li @b normal: the default state
@li @b disabled: bitmap shown when the button is disabled.
@li @b pressed: bitmap shown when the button is pushed (e.g. while the user
keeps the mouse button pressed on it)
@li @b focus: bitmap shown when the button has keyboard focus (but is not
pressed as in this case the button is in the pressed state)
@li @b current: bitmap shown when the mouse is over the button (but it is
not pressed although it may have focus). Notice that if current bitmap
is not specified but the current platform UI uses hover images for the
buttons (such as Windows XP or GTK+), then the focus bitmap is used for
hover state as well. This makes it possible to set focus bitmap only to
get reasonably good behaviour on all platforms.
All of the bitmaps must be of the same size and the normal bitmap must be
set first (to a valid bitmap), before setting any other ones. Also, if the
size of the bitmaps is changed later, you need to change the size of the
normal bitmap before setting any other bitmaps with the new size (and you
do need to reset all of them as their original values can be lost when the
normal bitmap size changes).
The position of the image inside the button be configured using
SetBitmapPosition(). By default the image is on the left of the text.
Please also notice that GTK+ uses a global setting called @c gtk-button-images
to determine if the images should be shown in the buttons
at all. If it is off (which is the case in e.g. Gnome 2.28 by default), no
images will be shown, consistently with the native behaviour.
@beginStyleTable
@style{wxBU_LEFT}
Left-justifies the label. Windows and GTK+ only.
@style{wxBU_TOP}
Aligns the label to the top of the button. Windows and GTK+ only.
@style{wxBU_RIGHT}
Right-justifies the bitmap label. Windows and GTK+ only.
@style{wxBU_BOTTOM}
Aligns the label to the bottom of the button. Windows and GTK+ only.
@style{wxBU_EXACTFIT}
By default, all buttons are made of at least the standard button size,
even if their contents is small enough to fit into a smaller size. This
is done for consistency as most platforms use buttons of the same size
in the native dialogs, but can be overridden by specifying this flag.
If it is given, the button will be made just big enough for its
contents. Notice that under MSW the button will still have at least the
standard height, even with this style, if it has a non-empty label.
@style{wxBU_NOTEXT}
Disables the display of the text label in the button even if it has one
or its id is one of the standard stock ids with an associated label:
without using this style a button which is only supposed to show a
bitmap but uses a standard id would display a label too.
@style{wxBORDER_NONE}
Creates a button without border. This is currently implemented in MSW,
GTK2 and OSX/Cocoa and OSX/Carbon ports but in the latter only applies
to buttons with bitmaps and using bitmap of one of the standard sizes
only, namely 128*128, 48*48, 24*24 or 16*16. In all the other cases
wxBORDER_NONE is ignored under OSX/Carbon (these restrictions don't
exist in OSX/Cocoa however).
@endStyleTable
@beginEventEmissionTable{wxCommandEvent}
@event{EVT_BUTTON(id, func)}
Process a @c wxEVT_BUTTON event, when the button is clicked.
@endEventTable
@library{wxcore}
@category{ctrl}
@appearance{button}
@see wxBitmapButton
*/
class wxButton : public wxAnyButton
{
public:
/**
Default ctor.
*/
wxButton();
/**
Constructor, creating and showing a button.
The preferred way to create standard buttons is to use default value of
@a label. If no label is supplied and @a id is one of standard IDs from
@ref page_stockitems "this list", a standard label will be used. In
other words, if you use a predefined @c wxID_XXX constant, just omit
the label completely rather than specifying it. In particular, help
buttons (the ones with @a id of @c wxID_HELP) under Mac OS X can't
display any label at all and while wxButton will detect if the standard
"Help" label is used and ignore it, using any other label will prevent
the button from correctly appearing as a help button and so should be
avoided.
In addition to that, the button will be decorated with stock icons under GTK+ 2.
@param parent
Parent window. Must not be @NULL.
@param id
Button identifier. A value of @c wxID_ANY indicates a default value.
@param label
Text to be displayed on the button.
@param pos
Button position.
@param size
Button size. If the default size is specified then the button is sized
appropriately for the text.
@param style
Window style. See wxButton class description.
@param validator
Window validator.
@param name
Window name.
@see Create(), wxValidator
*/
wxButton(wxWindow* parent, wxWindowID id,
const wxString& label = wxEmptyString,
const wxPoint& pos = wxDefaultPosition,
const wxSize& size = wxDefaultSize,
long style = 0,
const wxValidator& validator = wxDefaultValidator,
const wxString& name = wxButtonNameStr);
/**
Button creation function for two-step creation.
For more details, see wxButton().
*/
bool Create(wxWindow* parent, wxWindowID id,
const wxString& label = wxEmptyString,
const wxPoint& pos = wxDefaultPosition,
const wxSize& size = wxDefaultSize,
long style = 0,
const wxValidator& validator = wxDefaultValidator,
const wxString& name = wxButtonNameStr);
/**
Returns @true if an authentication needed symbol is displayed on the
button.
@remarks This method always returns @false if the platform is not
Windows Vista or newer.
@see SetAuthNeeded()
@since 2.9.1
*/
bool GetAuthNeeded() const;
/**
Returns the default size for the buttons. It is advised to make all the dialog
buttons of the same size and this function allows to retrieve the (platform and
current font dependent size) which should be the best suited for this.
*/
static wxSize GetDefaultSize();
/**
Returns the string label for the button.
@see SetLabel()
*/
wxString GetLabel() const;
/**
Sets whether an authentication needed symbol should be displayed on the
button.
@remarks This method doesn't do anything if the platform is not Windows
Vista or newer.
@see GetAuthNeeded()
@since 2.9.1
*/
void SetAuthNeeded(bool needed = true);
/**
This sets the button to be the default item in its top-level window
(e.g. the panel or the dialog box containing it).
As normal, pressing return causes the default button to be depressed when
the return key is pressed.
See also wxWindow::SetFocus() which sets the keyboard focus for windows
and text panel items, and wxTopLevelWindow::SetDefaultItem().
@remarks Under Windows, only dialog box buttons respond to this function.
@return the old default item (possibly @NULL)
*/
virtual wxWindow* SetDefault();
/**
Sets the string label for the button.
@param label
The label to set.
*/
void SetLabel(const wxString& label);
};
|
