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