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