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         Return the bitmap shown by the button.
 151
 152         The returned bitmap may be invalid only if the button doesn't show any
 153         images.
 154
 155         @see SetBitmap()
 156
 157         @since 2.9.1
 158      */
 159     wxBitmap GetBitmap() const;
 160
 161     /**
 162         Returns the bitmap used when the mouse is over the button, which may be
 163         invalid.
 164
 165         @see SetBitmapCurrent()
 166
 167         @since 2.9.1 (available as wxBitmapButton::GetBitmapHover() in previous
 168             versions)
 169     */
 170     wxBitmap GetBitmapCurrent() const;
 171
 172     /**
 173         Returns the bitmap for the disabled state, which may be invalid.
 174
 175         @see SetBitmapDisabled()
 176
 177         @since 2.9.1 (available in wxBitmapButton only in previous versions)
 178     */
 179     wxBitmap GetBitmapDisabled() const;
 180
 181     /**
 182         Returns the bitmap for the focused state, which may be invalid.
 183
 184         @see SetBitmapFocus()
 185
 186         @since 2.9.1 (available in wxBitmapButton only in previous versions)
 187     */
 188     wxBitmap GetBitmapFocus() const;
 189
 190     /**
 191         Returns the bitmap for the normal state.
 192
 193         This is exactly the same as GetBitmap() but uses a name
 194         backwards-compatible with wxBitmapButton.
 195
 196         @see SetBitmap(), SetBitmapLabel()
 197
 198         @since 2.9.1 (available in wxBitmapButton only in previous versions)
 199     */
 200     wxBitmap GetBitmapLabel() const;
 201
 202     /**
 203         Returns the bitmap for the pressed state, which may be invalid.
 204
 205         @see SetBitmapPressed()
 206
 207         @since 2.9.1 (available as wxBitmapButton::GetBitmapSelected() in
 208             previous versions)
 209     */
 210     wxBitmap GetBitmapPressed() const;
 211
 212     /**
 213         Returns the default size for the buttons. It is advised to make all the dialog
 214         buttons of the same size and this function allows to retrieve the (platform and
 215         current font dependent size) which should be the best suited for this.
 216     */
 217     static wxSize GetDefaultSize();
 218
 219     /**
 220         Returns the string label for the button.
 221
 222         @see SetLabel()
 223     */
 224     wxString GetLabel() const;
 225
 226     /**
 227         Sets the bitmap to display in the button.
 228
 229         The bitmap is displayed together with the button label. This method
 230         sets up a single bitmap which is used in all button states, use
 231         SetBitmapDisabled(), SetBitmapPressed(), SetBitmapCurrent() or
 232         SetBitmapFocus() to change the individual images used in different
 233         states.
 234
 235         @param bitmap
 236             The bitmap to display in the button. May be invalid to remove any
 237             currently displayed bitmap.
 238         @param dir
 239             The position of the bitmap inside the button. By default it is
 240             positioned to the left of the text, near to the left button border.
 241             Other possible values include wxRIGHT, wxTOP and wxBOTTOM.
 242
 243         @see SetBitmapPosition(), SetBitmapMargins()
 244
 245         @since 2.9.1
 246      */
 247     void SetBitmap(const wxBitmap& bitmap, wxDirection dir = wxLEFT);
 248
 249     /**
 250         Sets the bitmap to be shown when the mouse is over the button.
 251
 252         @see GetBitmapCurrent()
 253
 254         @since 2.9.1 (available as wxBitmapButton::SetBitmapHover() in previous
 255             versions)
 256     */
 257     void SetBitmapCurrent(const wxBitmap& bitmap);
 258
 259     /**
 260         Sets the bitmap for the disabled button appearance.
 261
 262         @see GetBitmapDisabled(), SetBitmapLabel(),
 263              SetBitmapPressed(), SetBitmapFocus()
 264
 265         @since 2.9.1 (available in wxBitmapButton only in previous versions)
 266     */
 267     void SetBitmapDisabled(const wxBitmap& bitmap);
 268
 269     /**
 270         Sets the bitmap for the button appearance when it has the keyboard
 271         focus.
 272
 273         @see GetBitmapFocus(), SetBitmapLabel(),
 274              SetBitmapPressed(), SetBitmapDisabled()
 275
 276         @since 2.9.1 (available in wxBitmapButton only in previous versions)
 277     */
 278     void SetBitmapFocus(const wxBitmap& bitmap);
 279
 280     /**
 281         Sets the bitmap label for the button.
 282
 283         @remarks This is the bitmap used for the unselected state, and for all
 284                  other states if no other bitmaps are provided.
 285
 286         @see SetBitmap(), GetBitmapLabel()
 287
 288         @since 2.9.1 (available in wxBitmapButton only in previous versions)
 289     */
 290     void SetBitmapLabel(const wxBitmap& bitmap);
 291
 292     /**
 293         Sets the bitmap for the selected (depressed) button appearance.
 294
 295         @since 2.9.1 (available as wxBitmapButton::SetBitmapSelected() in
 296             previous versions)
 297     */
 298     void SetBitmapPressed(const wxBitmap& bitmap);
 299
 300     /**
 301         Set the margins between the bitmap and the text of the button.
 302
 303         This method is currently only implemented under MSW. If it is not
 304         called, default margin is used around the bitmap.
 305
 306         @see SetBitmap(), SetBitmapPosition()
 307
 308         @since 2.9.1
 309      */
 310     //@{
 311     void SetBitmapMargins(wxCoord x, wxCoord y);
 312     void SetBitmapMargins(const wxSize& sz);
 313     //@}
 314
 315     /**
 316         Set the position at which the bitmap is displayed.
 317
 318         This method should only be called if the button does have an associated
 319         bitmap.
 320
 321         @since 2.9.1
 322
 323         @param dir
 324             Direction in which the bitmap should be positioned, one of wxLEFT,
 325             wxRIGHT, wxTOP or wxBOTTOM.
 326      */
 327     void SetBitmapPosition(wxDirection dir);
 328
 329     /**
 330         This sets the button to be the default item in its top-level window
 331         (e.g. the panel or the dialog box containing it).
 332
 333         As normal, pressing return causes the default button to be depressed when
 334         the return key is pressed.
 335
 336         See also wxWindow::SetFocus() which sets the keyboard focus for windows
 337         and text panel items, and wxTopLevelWindow::SetDefaultItem().
 338
 339         @remarks Under Windows, only dialog box buttons respond to this function.
 340
 341         @return the old default item (possibly NULL)
 342     */
 343     virtual wxWindow* SetDefault();
 344
 345     /**
 346         Sets the string label for the button.
 347
 348         @param label
 349             The label to set.
 350     */
 351     void SetLabel(const wxString& label);
 352 };
 353