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 \func{wxBitmap\&}{GetBitmapSelected}{\void}
 227
 228 Returns the bitmap for the pushed button state, may be invalid.
 229
 230 \wxheading{Return value}
 231
 232 A reference to the selected state bitmap.
 233
 234 \wxheading{See also}
 235
 236 \helpref{wxBitmapButton::SetBitmapSelected}{wxbitmapbuttonsetbitmapselected}
 237
 238
 239 \membersection{wxBitmapButton::GetBitmapSelected}\label{wxbitmapbuttongetbitmapselected}
 240
 241 \constfunc{wxBitmap\&}{GetBitmapSelected}{\void}
 242
 243 Returns the bitmap for the selected state.
 244
 245 \wxheading{Return value}
 246
 247 A reference to the selected state bitmap.
 248
 249 \wxheading{See also}
 250
 251 \helpref{wxBitmapButton::SetBitmapSelected}{wxbitmapbuttonsetbitmapselected}
 252
 253
 254 \membersection{wxBitmapButton::SetBitmapDisabled}\label{wxbitmapbuttonsetbitmapdisabled}
 255
 256 \func{void}{SetBitmapDisabled}{\param{const wxBitmap\& }{bitmap}}
 257
 258 Sets the bitmap for the disabled button appearance.
 259
 260 \wxheading{Parameters}
 261
 262 \docparam{bitmap}{The bitmap to set.}
 263
 264 \wxheading{See also}
 265
 266 \helpref{wxBitmapButton::GetBitmapDisabled}{wxbitmapbuttongetbitmapdisabled},\rtfsp
 267 \helpref{wxBitmapButton::SetBitmapLabel}{wxbitmapbuttonsetbitmaplabel},\rtfsp
 268 \helpref{wxBitmapButton::SetBitmapSelected}{wxbitmapbuttonsetbitmapselected},\rtfsp
 269 \helpref{wxBitmapButton::SetBitmapFocus}{wxbitmapbuttonsetbitmapfocus}
 270
 271
 272 \membersection{wxBitmapButton::SetBitmapFocus}\label{wxbitmapbuttonsetbitmapfocus}
 273
 274 \func{void}{SetBitmapFocus}{\param{const wxBitmap\& }{bitmap}}
 275
 276 Sets the bitmap for the button appearance when it has the keyboard focus.
 277
 278 \wxheading{Parameters}
 279
 280 \docparam{bitmap}{The bitmap to set.}
 281
 282 \wxheading{See also}
 283
 284 \helpref{wxBitmapButton::GetBitmapFocus}{wxbitmapbuttongetbitmapfocus},\rtfsp
 285 \helpref{wxBitmapButton::SetBitmapLabel}{wxbitmapbuttonsetbitmaplabel},\rtfsp
 286 \helpref{wxBitmapButton::SetBitmapSelected}{wxbitmapbuttonsetbitmapselected},\rtfsp
 287 \helpref{wxBitmapButton::SetBitmapDisabled}{wxbitmapbuttonsetbitmapdisabled}
 288
 289
 290 \membersection{wxBitmapButton::SetBitmapHover}\label{wxbitmapbuttonsetbitmaphover}
 291
 292 \func{void}{SetBitmapHover}{\param{const wxBitmap\& }{bitmap}}
 293
 294 Sets the bitmap to be shown when the mouse is over the button.
 295
 296 \newsince{2.7.0} and the hover bitmap is currently only supported in wxMSW.
 297
 298 \wxheading{See also}
 299
 300 \helpref{wxBitmapButton::GetBitmapHover}{wxbitmapbuttongetbitmaphover}
 301
 302 \membersection{wxBitmapButton::SetBitmapLabel}\label{wxbitmapbuttonsetbitmaplabel}
 303
 304 \func{void}{SetBitmapLabel}{\param{const wxBitmap\& }{bitmap}}
 305
 306 Sets the bitmap label for the button.
 307
 308 \wxheading{Parameters}
 309
 310 \docparam{bitmap}{The bitmap label to set.}
 311
 312 \wxheading{Remarks}
 313
 314 This is the bitmap used for the unselected state, and for all other states
 315 if no other bitmaps are provided.
 316
 317 \wxheading{See also}
 318
 319 \helpref{wxBitmapButton::GetBitmapLabel}{wxbitmapbuttongetbitmaplabel}
 320
 321
 322 \membersection{wxBitmapButton::SetBitmapSelected}\label{wxbitmapbuttonsetbitmapselected}
 323
 324 \func{void}{SetBitmapSelected}{\param{const wxBitmap\& }{bitmap}}
 325
 326 Sets the bitmap for the selected (depressed) button appearance.
 327
 328 \wxheading{Parameters}
 329
 330 \docparam{bitmap}{The bitmap to set.}
 331
 332 \wxheading{See also}
 333
 334 \helpref{wxBitmapButton::GetBitmapSelected}{wxbitmapbuttongetbitmapselected},\rtfsp
 335 \helpref{wxBitmapButton::SetBitmapLabel}{wxbitmapbuttonsetbitmaplabel},\rtfsp
 336 \helpref{wxBitmapButton::SetBitmapFocus}{wxbitmapbuttonsetbitmapfocus},\rtfsp
 337 \helpref{wxBitmapButton::SetBitmapDisabled}{wxbitmapbuttonsetbitmapdisabled}
 338
 339
 340 \membersection{wxBitmapButton::SetBitmapSelected}\label{wxbitmapbuttonsetbitmapselected}
 341
 342 \func{void}{SetBitmapSelected}{\param{const wxBitmap\& }{bitmap}}
 343
 344 Sets the bitmap for the selected (depressed) button appearance.
 345
 346 \wxheading{Parameters}
 347
 348 \docparam{bitmap}{The bitmap to set.}
 349
 350 \wxheading{See also}
 351
 352 \helpref{wxBitmapButton::GetBitmapSelected}{wxbitmapbuttongetbitmapselected},\rtfsp
 353 \helpref{wxBitmapButton::SetBitmapLabel}{wxbitmapbuttonsetbitmaplabel},\rtfsp
 354 \helpref{wxBitmapButton::SetBitmapFocus}{wxbitmapbuttonsetbitmapfocus},\rtfsp
 355 \helpref{wxBitmapButton::SetBitmapDisabled}{wxbitmapbuttonsetbitmapdisabled}
 356