]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/bbutton.tex
added wxWindow::HandleAsNavigationKey() helper for handling (not only) TAB key in...
[wxWidgets.git] / docs / latex / wx / bbutton.tex
1 \section{\class{wxBitmapButton}}\label{wxbitmapbutton}
2
3 A bitmap button is a control that contains a bitmap.
4 It may be placed on a \helpref{dialog box}{wxdialog} or \helpref{panel}{wxpanel}, or indeed
5 almost any other window.
6
7
8 \wxheading{Derived from}
9
10 \helpref{wxButton}{wxbutton}\\
11 \helpref{wxControl}{wxcontrol}\\
12 \helpref{wxWindow}{wxwindow}\\
13 \helpref{wxEvtHandler}{wxevthandler}\\
14 \helpref{wxObject}{wxobject}
15
16
17 \wxheading{Include files}
18
19 <wx/bmpbuttn.h>
20
21 \wxheading{Library}
22
23 \helpref{wxCore}{librarieslist}
24
25
26 \wxheading{Remarks}
27
28 A bitmap button can be supplied with a single bitmap, and wxWidgets will draw
29 all button states using this bitmap. If the application needs more control, additional bitmaps for
30 the selected state, unpressed focused state, and greyed-out state may be supplied.
31
32
33 \wxheading{Button states}
34
35 This class supports bitmaps for several different states:
36
37 \twocolwidtha{5cm}
38 \begin{twocollist}\itemsep=0pt
39 \twocolitem{\windowstyle{normal}}{This is the bitmap shown in the default state,
40 it must be always valid while all the other bitmaps are optional and don't have
41 to be set.}
42 \twocolitem{\windowstyle{disabled}}{Bitmap shown when the button is disabled.}
43 \twocolitem{\windowstyle{selected}}{Bitmap shown when the button is pushed
44 (e.g. while the user keeps the mouse button pressed on it)}
45 \twocolitem{\windowstyle{focus}}{Bitmap shown when the button has keyboard
46 focus but is not pressed.}
47 \twocolitem{\windowstyle{hover}}{Bitmap shown when the mouse is over the
48 button (but it is not pressed). Notice that if hover bitmap is not specified
49 but the current platform UI uses hover images for the buttons (such as Windows
50 XP or GTK+), then the focus bitmap is used for hover state as well. This makes
51 it possible to set focus bitmap only to get reasonably good behaviour on all
52 platforms.}
53 \end{twocollist}
54
55
56 \wxheading{Window styles}
57
58 \twocolwidtha{5cm}
59 \begin{twocollist}\itemsep=0pt
60 \twocolitem{\windowstyle{wxBU\_AUTODRAW}}{If
61 this is specified, the button will be drawn automatically using the label bitmap only, providing
62 a 3D-look border. If this style is not specified, the button will be drawn without borders and using all
63 provided bitmaps. WIN32 only.}
64 \twocolitem{\windowstyle{wxBU\_LEFT}}{Left-justifies the bitmap label. WIN32 only.}
65 \twocolitem{\windowstyle{wxBU\_TOP}}{Aligns the bitmap label to the top of the button. WIN32 only.}
66 \twocolitem{\windowstyle{wxBU\_RIGHT}}{Right-justifies the bitmap label. WIN32 only.}
67 \twocolitem{\windowstyle{wxBU\_BOTTOM}}{Aligns the bitmap label to the bottom of the button. WIN32 only.}
68 \end{twocollist}
69
70 Note that \windowstyle{wxBU\_EXACTFIT} supported by
71 \helpref{wxButton}{wxbutton} is \emph{not} used by this class as bitmap buttons
72 don't have any minimal standard size by default.
73
74 See also \helpref{window styles overview}{windowstyles}.
75
76
77 \wxheading{Event handling}
78
79 \twocolwidtha{7cm}
80 \begin{twocollist}\itemsep=0pt
81 \twocolitem{{\bf EVT\_BUTTON(id, func)}}{Process a wxEVT\_COMMAND\_BUTTON\_CLICKED event,
82 when the button is clicked.}
83 \end{twocollist}
84
85
86 \wxheading{See also}
87
88 \helpref{wxButton}{wxbutton}
89
90
91
92 \latexignore{\rtfignore{\wxheading{Members}}}
93
94
95 \membersection{wxBitmapButton::wxBitmapButton}\label{wxbitmapbuttonctor}
96
97 \func{}{wxBitmapButton}{\void}
98
99 Default constructor.
100
101 \func{}{wxBitmapButton}{
102 \param{wxWindow* }{parent},
103 \param{wxWindowID }{id},
104 \param{const wxBitmap\& }{bitmap},\rtfsp
105 \param{const wxPoint\& }{pos = wxDefaultPosition},
106 \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
107 \param{long }{style = wxBU\_AUTODRAW},
108 \param{const wxValidator\& }{validator = wxDefaultValidator},
109 \param{const wxString\& }{name = ``button"}}
110
111 Constructor, creating and showing a button.
112
113 \wxheading{Parameters}
114
115 \docparam{parent}{Parent window. Must not be NULL.}
116
117 \docparam{id}{Button identifier. A value of -1 indicates a default value.}
118
119 \docparam{bitmap}{Bitmap to be displayed.}
120
121 \docparam{pos}{Button position.}
122
123 \docparam{size}{Button size. If the default size (-1, -1) is specified then the button is sized
124 appropriately for the bitmap.}
125
126 \docparam{style}{Window style. See \helpref{wxBitmapButton}{wxbitmapbutton}.}
127
128 \docparam{validator}{Window validator.}
129
130 \docparam{name}{Window name.}
131
132 \wxheading{Remarks}
133
134 The {\it bitmap} parameter is normally the only bitmap you need to provide, and wxWidgets will
135 draw the button correctly in its different states. If you want more control, call
136 any of the functions \helpref{wxBitmapButton::SetBitmapSelected}{wxbitmapbuttonsetbitmapselected},\rtfsp
137 \helpref{wxBitmapButton::SetBitmapFocus}{wxbitmapbuttonsetbitmapfocus},\rtfsp
138 \helpref{wxBitmapButton::SetBitmapDisabled}{wxbitmapbuttonsetbitmapdisabled}.
139
140 Note that the bitmap passed is smaller than the actual button created.
141
142 \wxheading{See also}
143
144 \helpref{wxBitmapButton::Create}{wxbitmapbuttoncreate}, \helpref{wxValidator}{wxvalidator}
145
146
147 \membersection{wxBitmapButton::\destruct{wxBitmapButton}}\label{wxbitmapbuttondtor}
148
149 \func{}{\destruct{wxBitmapButton}}{\void}
150
151 Destructor, destroying the button.
152
153
154 \membersection{wxBitmapButton::Create}\label{wxbitmapbuttoncreate}
155
156 \func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id}, \param{const wxBitmap\& }{bitmap},\rtfsp
157 \param{const wxPoint\& }{pos}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
158 \param{long}{ style = 0}, \param{const wxValidator\& }{validator}, \param{const wxString\& }{name = ``button"}}
159
160 Button creation function for two-step creation. For more details, see \helpref{wxBitmapButton::wxBitmapButton}{wxbitmapbuttonctor}.
161
162
163 \membersection{wxBitmapButton::GetBitmapDisabled}\label{wxbitmapbuttongetbitmapdisabled}
164
165 \constfunc{const wxBitmap\&}{GetBitmapDisabled}{\void}
166 \func{wxBitmap\&}{GetBitmapDisabled}{\void}
167
168 Returns the bitmap for the disabled state, may be invalid.
169
170 \wxheading{Return value}
171
172 A reference to the disabled state bitmap.
173
174 \wxheading{See also}
175
176 \helpref{wxBitmapButton::SetBitmapDisabled}{wxbitmapbuttonsetbitmapdisabled}
177
178
179 \membersection{wxBitmapButton::GetBitmapFocus}\label{wxbitmapbuttongetbitmapfocus}
180
181 \constfunc{const wxBitmap\&}{GetBitmapFocus}{\void}
182 \func{wxBitmap\&}{GetBitmapFocus}{\void}
183
184 Returns the bitmap for the focused state, may be invalid.
185
186 \wxheading{Return value}
187
188 A reference to the focused state bitmap.
189
190 \wxheading{See also}
191
192 \helpref{wxBitmapButton::SetBitmapFocus}{wxbitmapbuttonsetbitmapfocus}
193
194
195 \membersection{wxBitmapButton::GetBitmapHover}\label{wxbitmapbuttongetbitmaphover}
196
197 \constfunc{const wxBitmap\&}{GetBitmapHover}{\void}
198 \func{wxBitmap\&}{GetBitmapHover}{\void}
199
200 Returns the bitmap used when the mouse is over the button, may be invalid.
201
202 \wxheading{See also}
203
204 \helpref{wxBitmapButton::SetBitmapHover}{wxbitmapbuttonsetbitmaphover}
205
206
207 \membersection{wxBitmapButton::GetBitmapLabel}\label{wxbitmapbuttongetbitmaplabel}
208
209 \constfunc{const wxBitmap\&}{GetBitmapLabel}{\void}
210 \func{wxBitmap\&}{GetBitmapLabel}{\void}
211
212 Returns the label bitmap (the one passed to the constructor), always valid.
213
214 \wxheading{Return value}
215
216 A reference to the button's label bitmap.
217
218 \wxheading{See also}
219
220 \helpref{wxBitmapButton::SetBitmapLabel}{wxbitmapbuttonsetbitmaplabel}
221
222
223 \membersection{wxBitmapButton::GetBitmapSelected}\label{wxbitmapbuttongetbitmapselected}
224
225 \constfunc{wxBitmap\&}{GetBitmapSelected}{\void}
226
227 Returns the bitmap for the selected state.
228
229 \wxheading{Return value}
230
231 A reference to the selected state bitmap.
232
233 \wxheading{See also}
234
235 \helpref{wxBitmapButton::SetBitmapSelected}{wxbitmapbuttonsetbitmapselected}
236
237
238 \membersection{wxBitmapButton::SetBitmapDisabled}\label{wxbitmapbuttonsetbitmapdisabled}
239
240 \func{void}{SetBitmapDisabled}{\param{const wxBitmap\& }{bitmap}}
241
242 Sets the bitmap for the disabled button appearance.
243
244 \wxheading{Parameters}
245
246 \docparam{bitmap}{The bitmap to set.}
247
248 \wxheading{See also}
249
250 \helpref{wxBitmapButton::GetBitmapDisabled}{wxbitmapbuttongetbitmapdisabled},\rtfsp
251 \helpref{wxBitmapButton::SetBitmapLabel}{wxbitmapbuttonsetbitmaplabel},\rtfsp
252 \helpref{wxBitmapButton::SetBitmapSelected}{wxbitmapbuttonsetbitmapselected},\rtfsp
253 \helpref{wxBitmapButton::SetBitmapFocus}{wxbitmapbuttonsetbitmapfocus}
254
255
256 \membersection{wxBitmapButton::SetBitmapFocus}\label{wxbitmapbuttonsetbitmapfocus}
257
258 \func{void}{SetBitmapFocus}{\param{const wxBitmap\& }{bitmap}}
259
260 Sets the bitmap for the button appearance when it has the keyboard focus.
261
262 \wxheading{Parameters}
263
264 \docparam{bitmap}{The bitmap to set.}
265
266 \wxheading{See also}
267
268 \helpref{wxBitmapButton::GetBitmapFocus}{wxbitmapbuttongetbitmapfocus},\rtfsp
269 \helpref{wxBitmapButton::SetBitmapLabel}{wxbitmapbuttonsetbitmaplabel},\rtfsp
270 \helpref{wxBitmapButton::SetBitmapSelected}{wxbitmapbuttonsetbitmapselected},\rtfsp
271 \helpref{wxBitmapButton::SetBitmapDisabled}{wxbitmapbuttonsetbitmapdisabled}
272
273
274 \membersection{wxBitmapButton::SetBitmapHover}\label{wxbitmapbuttonsetbitmaphover}
275
276 \func{void}{SetBitmapHover}{\param{const wxBitmap\& }{bitmap}}
277
278 Sets the bitmap to be shown when the mouse is over the button.
279
280 \newsince{2.7.0} and the hover bitmap is currently only supported in wxMSW.
281
282 \wxheading{See also}
283
284 \helpref{wxBitmapButton::GetBitmapHover}{wxbitmapbuttongetbitmaphover}
285
286 \membersection{wxBitmapButton::SetBitmapLabel}\label{wxbitmapbuttonsetbitmaplabel}
287
288 \func{void}{SetBitmapLabel}{\param{const wxBitmap\& }{bitmap}}
289
290 Sets the bitmap label for the button.
291
292 \wxheading{Parameters}
293
294 \docparam{bitmap}{The bitmap label to set.}
295
296 \wxheading{Remarks}
297
298 This is the bitmap used for the unselected state, and for all other states
299 if no other bitmaps are provided.
300
301 \wxheading{See also}
302
303 \helpref{wxBitmapButton::GetBitmapLabel}{wxbitmapbuttongetbitmaplabel}
304
305
306 \membersection{wxBitmapButton::SetBitmapSelected}\label{wxbitmapbuttonsetbitmapselected}
307
308 \func{void}{SetBitmapSelected}{\param{const wxBitmap\& }{bitmap}}
309
310 Sets the bitmap for the selected (depressed) button appearance.
311
312 \wxheading{Parameters}
313
314 \docparam{bitmap}{The bitmap to set.}
315
316 \wxheading{See also}
317
318 \helpref{wxBitmapButton::GetBitmapSelected}{wxbitmapbuttongetbitmapselected},\rtfsp
319 \helpref{wxBitmapButton::SetBitmapLabel}{wxbitmapbuttonsetbitmaplabel},\rtfsp
320 \helpref{wxBitmapButton::SetBitmapFocus}{wxbitmapbuttonsetbitmapfocus},\rtfsp
321 \helpref{wxBitmapButton::SetBitmapDisabled}{wxbitmapbuttonsetbitmapdisabled}
322