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::SetBitmapDisabled}\label{wxbitmapbuttonsetbitmapdisabled}
 236
 237 \func{void}{SetBitmapDisabled}{\param{const wxBitmap\& }{bitmap}}
 238
 239 Sets the bitmap for the disabled button appearance.
 240
 241 \wxheading{Parameters}
 242
 243 \docparam{bitmap}{The bitmap to set.}
 244
 245 \wxheading{See also}
 246
 247 \helpref{wxBitmapButton::GetBitmapDisabled}{wxbitmapbuttongetbitmapdisabled},\rtfsp
 248 \helpref{wxBitmapButton::SetBitmapLabel}{wxbitmapbuttonsetbitmaplabel},\rtfsp
 249 \helpref{wxBitmapButton::SetBitmapSelected}{wxbitmapbuttonsetbitmapselected},\rtfsp
 250 \helpref{wxBitmapButton::SetBitmapFocus}{wxbitmapbuttonsetbitmapfocus}
 251
 252
 253 \membersection{wxBitmapButton::SetBitmapFocus}\label{wxbitmapbuttonsetbitmapfocus}
 254
 255 \func{void}{SetBitmapFocus}{\param{const wxBitmap\& }{bitmap}}
 256
 257 Sets the bitmap for the button appearance when it has the keyboard focus.
 258
 259 \wxheading{Parameters}
 260
 261 \docparam{bitmap}{The bitmap to set.}
 262
 263 \wxheading{See also}
 264
 265 \helpref{wxBitmapButton::GetBitmapFocus}{wxbitmapbuttongetbitmapfocus},\rtfsp
 266 \helpref{wxBitmapButton::SetBitmapLabel}{wxbitmapbuttonsetbitmaplabel},\rtfsp
 267 \helpref{wxBitmapButton::SetBitmapSelected}{wxbitmapbuttonsetbitmapselected},\rtfsp
 268 \helpref{wxBitmapButton::SetBitmapDisabled}{wxbitmapbuttonsetbitmapdisabled}
 269
 270
 271 \membersection{wxBitmapButton::SetBitmapHover}\label{wxbitmapbuttonsetbitmaphover}
 272
 273 \func{void}{SetBitmapHover}{\param{const wxBitmap\& }{bitmap}}
 274
 275 Sets the bitmap to be shown when the mouse is over the button.
 276
 277 \newsince{2.7.0} and the hover bitmap is currently only supported in wxMSW.
 278
 279 \wxheading{See also}
 280
 281 \helpref{wxBitmapButton::GetBitmapHover}{wxbitmapbuttongetbitmaphover}
 282
 283 \membersection{wxBitmapButton::SetBitmapLabel}\label{wxbitmapbuttonsetbitmaplabel}
 284
 285 \func{void}{SetBitmapLabel}{\param{const wxBitmap\& }{bitmap}}
 286
 287 Sets the bitmap label for the button.
 288
 289 \wxheading{Parameters}
 290
 291 \docparam{bitmap}{The bitmap label to set.}
 292
 293 \wxheading{Remarks}
 294
 295 This is the bitmap used for the unselected state, and for all other states
 296 if no other bitmaps are provided.
 297
 298 \wxheading{See also}
 299
 300 \helpref{wxBitmapButton::GetBitmapLabel}{wxbitmapbuttongetbitmaplabel}
 301
 302
 303 \membersection{wxBitmapButton::SetBitmapSelected}\label{wxbitmapbuttonsetbitmapselected}
 304
 305 \func{void}{SetBitmapSelected}{\param{const wxBitmap\& }{bitmap}}
 306
 307 Sets the bitmap for the selected (depressed) button appearance.
 308
 309 \wxheading{Parameters}
 310
 311 \docparam{bitmap}{The bitmap to set.}
 312
 313 \wxheading{See also}
 314
 315 \helpref{wxBitmapButton::GetBitmapSelected}{wxbitmapbuttongetbitmapselected},\rtfsp
 316 \helpref{wxBitmapButton::SetBitmapLabel}{wxbitmapbuttonsetbitmaplabel},\rtfsp
 317 \helpref{wxBitmapButton::SetBitmapFocus}{wxbitmapbuttonsetbitmapfocus},\rtfsp
 318 \helpref{wxBitmapButton::SetBitmapDisabled}{wxbitmapbuttonsetbitmapdisabled}
 319