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         Returns the default size for the buttons. It is advised to make all the dialog
 227         buttons of the same size and this function allows to retrieve the (platform and
 228         current font dependent size) which should be the best suited for this.
 229     */
 230     static wxSize GetDefaultSize();
 231
 232     /**
 233         Returns the string label for the button.
 234
 235         @see SetLabel()
 236     */
 237     wxString GetLabel() const;
 238
 239     /**
 240         Sets whether an authentication needed symbol should be displayed on the
 241         button.
 242
 243         @remarks This method doesn't do anything if the platform is not Windows
 244                  Vista or newer.
 245
 246         @see GetAuthNeeded()
 247
 248         @since 2.9.1
 249      */
 250     void SetAuthNeeded(bool needed = true);
 251
 252     /**
 253         Sets the bitmap to display in the button.
 254
 255         The bitmap is displayed together with the button label. This method
 256         sets up a single bitmap which is used in all button states, use
 257         SetBitmapDisabled(), SetBitmapPressed(), SetBitmapCurrent() or
 258         SetBitmapFocus() to change the individual images used in different
 259         states.
 260
 261         @param bitmap
 262             The bitmap to display in the button. May be invalid to remove any
 263             currently displayed bitmap.
 264         @param dir
 265             The position of the bitmap inside the button. By default it is
 266             positioned to the left of the text, near to the left button border.
 267             Other possible values include wxRIGHT, wxTOP and wxBOTTOM.
 268
 269         @see SetBitmapPosition(), SetBitmapMargins()
 270
 271         @since 2.9.1
 272      */
 273     void SetBitmap(const wxBitmap& bitmap, wxDirection dir = wxLEFT);
 274
 275     /**
 276         Sets the bitmap to be shown when the mouse is over the button.
 277
 278         @see GetBitmapCurrent()
 279
 280         @since 2.9.1 (available as wxBitmapButton::SetBitmapHover() in previous
 281             versions)
 282     */
 283     void SetBitmapCurrent(const wxBitmap& bitmap);
 284
 285     /**
 286         Sets the bitmap for the disabled button appearance.
 287
 288         @see GetBitmapDisabled(), SetBitmapLabel(),
 289              SetBitmapPressed(), SetBitmapFocus()
 290
 291         @since 2.9.1 (available in wxBitmapButton only in previous versions)
 292     */
 293     void SetBitmapDisabled(const wxBitmap& bitmap);
 294
 295     /**
 296         Sets the bitmap for the button appearance when it has the keyboard
 297         focus.
 298
 299         @see GetBitmapFocus(), SetBitmapLabel(),
 300              SetBitmapPressed(), SetBitmapDisabled()
 301
 302         @since 2.9.1 (available in wxBitmapButton only in previous versions)
 303     */
 304     void SetBitmapFocus(const wxBitmap& bitmap);
 305
 306     /**
 307         Sets the bitmap label for the button.
 308
 309         @remarks This is the bitmap used for the unselected state, and for all
 310                  other states if no other bitmaps are provided.
 311
 312         @see SetBitmap(), GetBitmapLabel()
 313
 314         @since 2.9.1 (available in wxBitmapButton only in previous versions)
 315     */
 316     void SetBitmapLabel(const wxBitmap& bitmap);
 317
 318     /**
 319         Sets the bitmap for the selected (depressed) button appearance.
 320
 321         @since 2.9.1 (available as wxBitmapButton::SetBitmapSelected() in
 322             previous versions)
 323     */
 324     void SetBitmapPressed(const wxBitmap& bitmap);
 325
 326     /**
 327         Set the margins between the bitmap and the text of the button.
 328
 329         This method is currently only implemented under MSW. If it is not
 330         called, default margin is used around the bitmap.
 331
 332         @see SetBitmap(), SetBitmapPosition()
 333
 334         @since 2.9.1
 335      */
 336     //@{
 337     void SetBitmapMargins(wxCoord x, wxCoord y);
 338     void SetBitmapMargins(const wxSize& sz);
 339     //@}
 340
 341     /**
 342         Set the position at which the bitmap is displayed.
 343
 344         This method should only be called if the button does have an associated
 345         bitmap.
 346
 347         @since 2.9.1
 348
 349         @param dir
 350             Direction in which the bitmap should be positioned, one of wxLEFT,
 351             wxRIGHT, wxTOP or wxBOTTOM.
 352      */
 353     void SetBitmapPosition(wxDirection dir);
 354
 355     /**
 356         This sets the button to be the default item in its top-level window
 357         (e.g. the panel or the dialog box containing it).
 358
 359         As normal, pressing return causes the default button to be depressed when
 360         the return key is pressed.
 361
 362         See also wxWindow::SetFocus() which sets the keyboard focus for windows
 363         and text panel items, and wxTopLevelWindow::SetDefaultItem().
 364
 365         @remarks Under Windows, only dialog box buttons respond to this function.
 366
 367         @return the old default item (possibly NULL)
 368     */
 369     virtual wxWindow* SetDefault();
 370
 371     /**
 372         Sets the string label for the button.
 373
 374         @param label
 375             The label to set.
 376     */
 377     void SetLabel(const wxString& label);
 378 };
 379