interface/wx/button.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        button.h
   3 // Purpose:     interface of wxButton
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxButton
  11
  12     A button is a control that contains a text string, and is one of the most
  13     common elements of a GUI.
  14
  15     It may be placed on a @ref wxDialog "dialog box" or on a @ref wxPanel panel,
  16     or indeed on almost any other window.
  17
  18     @beginStyleTable
  19     @style{wxBU_LEFT}
  20         Left-justifies the label. Windows and GTK+ only.
  21     @style{wxBU_TOP}
  22         Aligns the label to the top of the button. Windows and GTK+ only.
  23     @style{wxBU_RIGHT}
  24         Right-justifies the bitmap label. Windows and GTK+ only.
  25     @style{wxBU_BOTTOM}
  26         Aligns the label to the bottom of the button. Windows and GTK+ only.
  27     @style{wxBU_EXACTFIT}
  28         Creates the button as small as possible instead of making it of the
  29         standard size (which is the default behaviour ).
  30     @style{wxBU_NOTEXT}
  31         Disables the display of the text label in the button even if it has one
  32         or its id is one of the standard stock ids with an associated label:
  33         without using this style a button which is only supposed to show a
  34         bitmap but uses a standard id would display a label too.
  35     @style{wxBORDER_NONE}
  36         Creates a button without border. This is currently implemented in MSW,
  37         GTK2 and OSX/Carbon ports but in the latter only applies to buttons
  38         with bitmaps and using bitmap of one of the standard sizes only, namely
  39         128*128, 48*48, 24*24 or 16*16. In all the other cases wxBORDER_NONE is
  40         ignored under OSX.
  41     @endStyleTable
  42
  43     By default, i.e. if none of the alignment styles are specified, the label
  44     is centered both horizontally and vertically. If the button has both a
  45     label and a bitmap, the alignment styles above specify the location of the
  46     rectangle combining both the label and the bitmap and the bitmap position
  47     set with wxButton::SetBitmapPosition() defines the relative position of the
  48     bitmap with respect to the label (however currently non-default alignment
  49     combinations are not implemented on all platforms).
  50
  51     @beginEventEmissionTable{wxCommandEvent}
  52     @event{EVT_BUTTON(id, func)}
  53            Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is clicked.
  54     @endEventTable
  55
  56
  57     Since version 2.9.1 wxButton supports showing both text and an image
  58     (currently only when using wxMSW, wxGTK or wxOSX/Cocoa ports), see
  59     SetBitmap() and SetBitmapLabel(), SetBitmapDisabled() &c methods. In the
  60     previous wxWidgets versions this functionality was only available in (the
  61     now trivial) wxBitmapButton class which was only capable of showing an
  62     image without text.
  63
  64     A button may have either a single image for all states or different images
  65     for the following states (different images are not currently supported
  66     under OS X where the normal image is used for all states):
  67     @li @b normal: the default state
  68     @li @b disabled: bitmap shown when the button is disabled.
  69     @li @b pressed: bitmap shown when the button is pushed (e.g. while the user
  70         keeps the mouse button pressed on it)
  71     @li @b focus: bitmap shown when the button has keyboard focus (but is not
  72         pressed as in this case the button is in the pressed state)
  73     @li @b current: bitmap shown when the mouse is over the button (but it is
  74         not pressed although it may have focus). Notice that if current bitmap
  75         is not specified but the current platform UI uses hover images for the
  76         buttons (such as Windows XP or GTK+), then the focus bitmap is used for
  77         hover state as well. This makes it possible to set focus bitmap only to
  78         get reasonably good behaviour on all platforms.
  79
  80     All of the bitmaps must be of the same size and the normal bitmap must be
  81     set first (to a valid bitmap), before setting any other ones.
  82
  83     The position of the image inside the button be configured using
  84     SetBitmapPosition(). By default the image is on the left of the text.
  85
  86     @library{wxcore}
  87     @category{ctrl}
  88     @appearance{button.png}
  89
  90     @see wxBitmapButton
  91 */
  92 class wxButton : public wxControl
  93 {
  94 public:
  95     /**
  96         Default ctor.
  97     */
  98     wxButton();
  99
 100     /**
 101         Constructor, creating and showing a button.
 102
 103         The preferred way to create standard buttons is to use default value of
 104         @a label. If no label is supplied and @a id is one of standard IDs from
 105         @ref page_stockitems "this list", a standard label will be used.
 106
 107         In addition to that, the button will be decorated with stock icons under GTK+ 2.
 108
 109         @param parent
 110             Parent window. Must not be @NULL.
 111         @param id
 112             Button identifier. A value of wxID_ANY indicates a default value.
 113         @param label
 114             Text to be displayed on the button.
 115         @param pos
 116             Button position.
 117         @param size
 118             Button size. If the default size is specified then the button is sized
 119             appropriately for the text.
 120         @param style
 121             Window style. See wxButton class description.
 122         @param validator
 123             Window validator.
 124         @param name
 125             Window name.
 126
 127         @see Create(), wxValidator
 128     */
 129     wxButton(wxWindow* parent, wxWindowID id,
 130              const wxString& label = wxEmptyString,
 131              const wxPoint& pos = wxDefaultPosition,
 132              const wxSize& size = wxDefaultSize,
 133              long style = 0,
 134              const wxValidator& validator = wxDefaultValidator,
 135              const wxString& name = wxButtonNameStr);
 136
 137     /**
 138         Button creation function for two-step creation.
 139         For more details, see wxButton().
 140     */
 141     bool Create(wxWindow* parent, wxWindowID id,
 142                 const wxString& label = wxEmptyString,
 143                 const wxPoint& pos = wxDefaultPosition,
 144                 const wxSize& size = wxDefaultSize,
 145                 long style = 0,
 146                 const wxValidator& validator = wxDefaultValidator,
 147                 const wxString& name = wxButtonNameStr);
 148
 149     /**
 150         Returns @true if an authentication needed symbol is displayed on the
 151         button.
 152
 153         @remarks This method always returns @false if the platform is not
 154                  Windows Vista or newer.
 155
 156         @see SetAuthNeeded()
 157
 158         @since 2.9.1
 159      */
 160     bool GetAuthNeeded() const;
 161
 162     /**
 163         Return the bitmap shown by the button.
 164
 165         The returned bitmap may be invalid only if the button doesn't show any
 166         images.
 167
 168         @see SetBitmap()
 169
 170         @since 2.9.1
 171      */
 172     wxBitmap GetBitmap() const;
 173
 174     /**
 175         Returns the bitmap used when the mouse is over the button, which may be
 176         invalid.
 177
 178         @see SetBitmapCurrent()
 179
 180         @since 2.9.1 (available as wxBitmapButton::GetBitmapHover() in previous
 181             versions)
 182     */
 183     wxBitmap GetBitmapCurrent() const;
 184
 185     /**
 186         Returns the bitmap for the disabled state, which may be invalid.
 187
 188         @see SetBitmapDisabled()
 189
 190         @since 2.9.1 (available in wxBitmapButton only in previous versions)
 191     */
 192     wxBitmap GetBitmapDisabled() const;
 193
 194     /**
 195         Returns the bitmap for the focused state, which may be invalid.
 196
 197         @see SetBitmapFocus()
 198
 199         @since 2.9.1 (available in wxBitmapButton only in previous versions)
 200     */
 201     wxBitmap GetBitmapFocus() const;
 202
 203     /**
 204         Returns the bitmap for the normal state.
 205
 206         This is exactly the same as GetBitmap() but uses a name
 207         backwards-compatible with wxBitmapButton.
 208
 209         @see SetBitmap(), SetBitmapLabel()
 210
 211         @since 2.9.1 (available in wxBitmapButton only in previous versions)
 212     */
 213     wxBitmap GetBitmapLabel() const;
 214
 215     /**
 216         Returns the bitmap for the pressed state, which may be invalid.
 217
 218         @see SetBitmapPressed()
 219
 220         @since 2.9.1 (available as wxBitmapButton::GetBitmapSelected() in
 221             previous versions)
 222     */
 223     wxBitmap GetBitmapPressed() const;
 224
 225     /**
 226         Get the margins between the bitmap and the text of the button.
 227
 228         @see SetBitmapMargins()
 229
 230         @since 2.9.1
 231      */
 232     wxSize GetBitmapMargins();
 233
 234     /**
 235         Returns the default size for the buttons. It is advised to make all the dialog
 236         buttons of the same size and this function allows to retrieve the (platform and
 237         current font dependent size) which should be the best suited for this.
 238     */
 239     static wxSize GetDefaultSize();
 240
 241     /**
 242         Returns the string label for the button.
 243
 244         @see SetLabel()
 245     */
 246     wxString GetLabel() const;
 247
 248     /**
 249         Sets whether an authentication needed symbol should be displayed on the
 250         button.
 251
 252         @remarks This method doesn't do anything if the platform is not Windows
 253                  Vista or newer.
 254
 255         @see GetAuthNeeded()
 256
 257         @since 2.9.1
 258      */
 259     void SetAuthNeeded(bool needed = true);
 260
 261     /**
 262         Sets the bitmap to display in the button.
 263
 264         The bitmap is displayed together with the button label. This method
 265         sets up a single bitmap which is used in all button states, use
 266         SetBitmapDisabled(), SetBitmapPressed(), SetBitmapCurrent() or
 267         SetBitmapFocus() to change the individual images used in different
 268         states.
 269
 270         @param bitmap
 271             The bitmap to display in the button. May be invalid to remove any
 272             currently displayed bitmap.
 273         @param dir
 274             The position of the bitmap inside the button. By default it is
 275             positioned to the left of the text, near to the left button border.
 276             Other possible values include wxRIGHT, wxTOP and wxBOTTOM.
 277
 278         @see SetBitmapPosition(), SetBitmapMargins()
 279
 280         @since 2.9.1
 281      */
 282     void SetBitmap(const wxBitmap& bitmap, wxDirection dir = wxLEFT);
 283
 284     /**
 285         Sets the bitmap to be shown when the mouse is over the button.
 286
 287         @see GetBitmapCurrent()
 288
 289         @since 2.9.1 (available as wxBitmapButton::SetBitmapHover() in previous
 290             versions)
 291     */
 292     void SetBitmapCurrent(const wxBitmap& bitmap);
 293
 294     /**
 295         Sets the bitmap for the disabled button appearance.
 296
 297         @see GetBitmapDisabled(), SetBitmapLabel(),
 298              SetBitmapPressed(), SetBitmapFocus()
 299
 300         @since 2.9.1 (available in wxBitmapButton only in previous versions)
 301     */
 302     void SetBitmapDisabled(const wxBitmap& bitmap);
 303
 304     /**
 305         Sets the bitmap for the button appearance when it has the keyboard
 306         focus.
 307
 308         @see GetBitmapFocus(), SetBitmapLabel(),
 309              SetBitmapPressed(), SetBitmapDisabled()
 310
 311         @since 2.9.1 (available in wxBitmapButton only in previous versions)
 312     */
 313     void SetBitmapFocus(const wxBitmap& bitmap);
 314
 315     /**
 316         Sets the bitmap label for the button.
 317
 318         @remarks This is the bitmap used for the unselected state, and for all
 319                  other states if no other bitmaps are provided.
 320
 321         @see SetBitmap(), GetBitmapLabel()
 322
 323         @since 2.9.1 (available in wxBitmapButton only in previous versions)
 324     */
 325     void SetBitmapLabel(const wxBitmap& bitmap);
 326
 327     /**
 328         Sets the bitmap for the selected (depressed) button appearance.
 329
 330         @since 2.9.1 (available as wxBitmapButton::SetBitmapSelected() in
 331             previous versions)
 332     */
 333     void SetBitmapPressed(const wxBitmap& bitmap);
 334
 335     /**
 336         Set the margins between the bitmap and the text of the button.
 337
 338         This method is currently only implemented under MSW. If it is not
 339         called, default margin is used around the bitmap.
 340
 341         @see SetBitmap(), SetBitmapPosition()
 342
 343         @since 2.9.1
 344      */
 345     //@{
 346     void SetBitmapMargins(wxCoord x, wxCoord y);
 347     void SetBitmapMargins(const wxSize& sz);
 348     //@}
 349
 350     /**
 351         Set the position at which the bitmap is displayed.
 352
 353         This method should only be called if the button does have an associated
 354         bitmap.
 355
 356         @since 2.9.1
 357
 358         @param dir
 359             Direction in which the bitmap should be positioned, one of wxLEFT,
 360             wxRIGHT, wxTOP or wxBOTTOM.
 361      */
 362     void SetBitmapPosition(wxDirection dir);
 363
 364     /**
 365         This sets the button to be the default item in its top-level window
 366         (e.g. the panel or the dialog box containing it).
 367
 368         As normal, pressing return causes the default button to be depressed when
 369         the return key is pressed.
 370
 371         See also wxWindow::SetFocus() which sets the keyboard focus for windows
 372         and text panel items, and wxTopLevelWindow::SetDefaultItem().
 373
 374         @remarks Under Windows, only dialog box buttons respond to this function.
 375
 376         @return the old default item (possibly NULL)
 377     */
 378     virtual wxWindow* SetDefault();
 379
 380     /**
 381         Sets the string label for the button.
 382
 383         @param label
 384             The label to set.
 385     */
 386     void SetLabel(const wxString& label);
 387 };
 388