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