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 licence
   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 @c 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. Also, if the
  82     size of the bitmaps is changed later, you need to change the size of the
  83     normal bitmap before setting any other bitmaps with the new size (and you
  84     do need to reset all of them as their original values can be lost when the
  85     normal bitmap size changes).
  86
  87     The position of the image inside the button be configured using
  88     SetBitmapPosition(). By default the image is on the left of the text.
  89
  90     Please also notice that GTK+ uses a global setting called @c
  91     gtk-button-images to determine if the images should be shown in the buttons
  92     at all. If it is off (which is the case in e.g. Gnome 2.28 by default), no
  93     images will be shown, consistently with the native behaviour.
  94
  95     @library{wxcore}
  96     @category{ctrl}
  97     @appearance{button.png}
  98
  99     @see wxBitmapButton
 100 */
 101 class wxButton : public wxControl
 102 {
 103 public:
 104     /**
 105         Default ctor.
 106     */
 107     wxButton();
 108
 109     /**
 110         Constructor, creating and showing a button.
 111
 112         The preferred way to create standard buttons is to use default value of
 113         @a label. If no label is supplied and @a id is one of standard IDs from
 114         @ref page_stockitems "this list", a standard label will be used. In
 115         other words, if you use a predefined @c wxID_XXX constant, just omit
 116         the label completely rather than specifying it. In particular, help
 117         buttons (the ones with @a id of @c wxID_HELP) under Mac OS X can't
 118         display any label at all and while wxButton will detect if the standard
 119         "Help" label is used and ignore it, using any other label will prevent
 120         the button from correctly appearing as a help button and so should be
 121         avoided.
 122
 123
 124         In addition to that, the button will be decorated with stock icons under GTK+ 2.
 125
 126         @param parent
 127             Parent window. Must not be @NULL.
 128         @param id
 129             Button identifier. A value of wxID_ANY indicates a default value.
 130         @param label
 131             Text to be displayed on the button.
 132         @param pos
 133             Button position.
 134         @param size
 135             Button size. If the default size is specified then the button is sized
 136             appropriately for the text.
 137         @param style
 138             Window style. See wxButton class description.
 139         @param validator
 140             Window validator.
 141         @param name
 142             Window name.
 143
 144         @see Create(), wxValidator
 145     */
 146     wxButton(wxWindow* parent, wxWindowID id,
 147              const wxString& label = wxEmptyString,
 148              const wxPoint& pos = wxDefaultPosition,
 149              const wxSize& size = wxDefaultSize,
 150              long style = 0,
 151              const wxValidator& validator = wxDefaultValidator,
 152              const wxString& name = wxButtonNameStr);
 153
 154     /**
 155         Button creation function for two-step creation.
 156         For more details, see wxButton().
 157     */
 158     bool Create(wxWindow* parent, wxWindowID id,
 159                 const wxString& label = wxEmptyString,
 160                 const wxPoint& pos = wxDefaultPosition,
 161                 const wxSize& size = wxDefaultSize,
 162                 long style = 0,
 163                 const wxValidator& validator = wxDefaultValidator,
 164                 const wxString& name = wxButtonNameStr);
 165
 166     /**
 167         Returns @true if an authentication needed symbol is displayed on the
 168         button.
 169
 170         @remarks This method always returns @false if the platform is not
 171                  Windows Vista or newer.
 172
 173         @see SetAuthNeeded()
 174
 175         @since 2.9.1
 176      */
 177     bool GetAuthNeeded() const;
 178
 179     /**
 180         Return the bitmap shown by the button.
 181
 182         The returned bitmap may be invalid only if the button doesn't show any
 183         images.
 184
 185         @see SetBitmap()
 186
 187         @since 2.9.1
 188      */
 189     wxBitmap GetBitmap() const;
 190
 191     /**
 192         Returns the bitmap used when the mouse is over the button, which may be
 193         invalid.
 194
 195         @see SetBitmapCurrent()
 196
 197         @since 2.9.1 (available as wxBitmapButton::GetBitmapHover() in previous
 198             versions)
 199     */
 200     wxBitmap GetBitmapCurrent() const;
 201
 202     /**
 203         Returns the bitmap for the disabled state, which may be invalid.
 204
 205         @see SetBitmapDisabled()
 206
 207         @since 2.9.1 (available in wxBitmapButton only in previous versions)
 208     */
 209     wxBitmap GetBitmapDisabled() const;
 210
 211     /**
 212         Returns the bitmap for the focused state, which may be invalid.
 213
 214         @see SetBitmapFocus()
 215
 216         @since 2.9.1 (available in wxBitmapButton only in previous versions)
 217     */
 218     wxBitmap GetBitmapFocus() const;
 219
 220     /**
 221         Returns the bitmap for the normal state.
 222
 223         This is exactly the same as GetBitmap() but uses a name
 224         backwards-compatible with wxBitmapButton.
 225
 226         @see SetBitmap(), SetBitmapLabel()
 227
 228         @since 2.9.1 (available in wxBitmapButton only in previous versions)
 229     */
 230     wxBitmap GetBitmapLabel() const;
 231
 232     /**
 233         Returns the bitmap for the pressed state, which may be invalid.
 234
 235         @see SetBitmapPressed()
 236
 237         @since 2.9.1 (available as wxBitmapButton::GetBitmapSelected() in
 238             previous versions)
 239     */
 240     wxBitmap GetBitmapPressed() const;
 241
 242     /**
 243         Get the margins between the bitmap and the text of the button.
 244
 245         @see SetBitmapMargins()
 246
 247         @since 2.9.1
 248      */
 249     wxSize GetBitmapMargins();
 250
 251     /**
 252         Returns the default size for the buttons. It is advised to make all the dialog
 253         buttons of the same size and this function allows to retrieve the (platform and
 254         current font dependent size) which should be the best suited for this.
 255     */
 256     static wxSize GetDefaultSize();
 257
 258     /**
 259         Returns the string label for the button.
 260
 261         @see SetLabel()
 262     */
 263     wxString GetLabel() const;
 264
 265     /**
 266         Sets whether an authentication needed symbol should be displayed on the
 267         button.
 268
 269         @remarks This method doesn't do anything if the platform is not Windows
 270                  Vista or newer.
 271
 272         @see GetAuthNeeded()
 273
 274         @since 2.9.1
 275      */
 276     void SetAuthNeeded(bool needed = true);
 277
 278     /**
 279         Sets the bitmap to display in the button.
 280
 281         The bitmap is displayed together with the button label. This method
 282         sets up a single bitmap which is used in all button states, use
 283         SetBitmapDisabled(), SetBitmapPressed(), SetBitmapCurrent() or
 284         SetBitmapFocus() to change the individual images used in different
 285         states.
 286
 287         @param bitmap
 288             The bitmap to display in the button. May be invalid to remove any
 289             currently displayed bitmap.
 290         @param dir
 291             The position of the bitmap inside the button. By default it is
 292             positioned to the left of the text, near to the left button border.
 293             Other possible values include wxRIGHT, wxTOP and wxBOTTOM.
 294
 295         @see SetBitmapPosition(), SetBitmapMargins()
 296
 297         @since 2.9.1
 298      */
 299     void SetBitmap(const wxBitmap& bitmap, wxDirection dir = wxLEFT);
 300
 301     /**
 302         Sets the bitmap to be shown when the mouse is over the button.
 303
 304         @see GetBitmapCurrent()
 305
 306         @since 2.9.1 (available as wxBitmapButton::SetBitmapHover() in previous
 307             versions)
 308     */
 309     void SetBitmapCurrent(const wxBitmap& bitmap);
 310
 311     /**
 312         Sets the bitmap for the disabled button appearance.
 313
 314         @see GetBitmapDisabled(), SetBitmapLabel(),
 315              SetBitmapPressed(), SetBitmapFocus()
 316
 317         @since 2.9.1 (available in wxBitmapButton only in previous versions)
 318     */
 319     void SetBitmapDisabled(const wxBitmap& bitmap);
 320
 321     /**
 322         Sets the bitmap for the button appearance when it has the keyboard
 323         focus.
 324
 325         @see GetBitmapFocus(), SetBitmapLabel(),
 326              SetBitmapPressed(), SetBitmapDisabled()
 327
 328         @since 2.9.1 (available in wxBitmapButton only in previous versions)
 329     */
 330     void SetBitmapFocus(const wxBitmap& bitmap);
 331
 332     /**
 333         Sets the bitmap label for the button.
 334
 335         @remarks This is the bitmap used for the unselected state, and for all
 336                  other states if no other bitmaps are provided.
 337
 338         @see SetBitmap(), GetBitmapLabel()
 339
 340         @since 2.9.1 (available in wxBitmapButton only in previous versions)
 341     */
 342     void SetBitmapLabel(const wxBitmap& bitmap);
 343
 344     /**
 345         Sets the bitmap for the selected (depressed) button appearance.
 346
 347         @since 2.9.1 (available as wxBitmapButton::SetBitmapSelected() in
 348             previous versions)
 349     */
 350     void SetBitmapPressed(const wxBitmap& bitmap);
 351
 352     /**
 353         Set the margins between the bitmap and the text of the button.
 354
 355         This method is currently only implemented under MSW. If it is not
 356         called, default margin is used around the bitmap.
 357
 358         @see SetBitmap(), SetBitmapPosition()
 359
 360         @since 2.9.1
 361      */
 362     //@{
 363     void SetBitmapMargins(wxCoord x, wxCoord y);
 364     void SetBitmapMargins(const wxSize& sz);
 365     //@}
 366
 367     /**
 368         Set the position at which the bitmap is displayed.
 369
 370         This method should only be called if the button does have an associated
 371         bitmap.
 372
 373         @since 2.9.1
 374
 375         @param dir
 376             Direction in which the bitmap should be positioned, one of wxLEFT,
 377             wxRIGHT, wxTOP or wxBOTTOM.
 378      */
 379     void SetBitmapPosition(wxDirection dir);
 380
 381     /**
 382         This sets the button to be the default item in its top-level window
 383         (e.g. the panel or the dialog box containing it).
 384
 385         As normal, pressing return causes the default button to be depressed when
 386         the return key is pressed.
 387
 388         See also wxWindow::SetFocus() which sets the keyboard focus for windows
 389         and text panel items, and wxTopLevelWindow::SetDefaultItem().
 390
 391         @remarks Under Windows, only dialog box buttons respond to this function.
 392
 393         @return the old default item (possibly NULL)
 394     */
 395     virtual wxWindow* SetDefault();
 396
 397     /**
 398         Sets the string label for the button.
 399
 400         @param label
 401             The label to set.
 402     */
 403     void SetLabel(const wxString& label);
 404 };
 405