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