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