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