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