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