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