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 ports but in the latter only applies to buttons with
  38         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, see
  58     SetBitmap() and SetBitmapLabel(), SetBitmapDisabled() &c methods. In the
  59     previous wxWidgets versions this functionality was only available in (the
  60     now trivial) wxBitmapButton class which was only capable of showing an
  61     image without text.
  62
  63     A button may have either a single image for all states or different images
  64     for the following states:
  65     @li @b normal: the default state
  66     @li @b disabled: bitmap shown when the button is disabled.
  67     @li @b pressed: bitmap shown when the button is pushed (e.g. while the user
  68         keeps the mouse button pressed on it)
  69     @li @b focus: bitmap shown when the button has keyboard focus (but is not
  70         pressed as in this case the button is in the pressed state)
  71     @li @b current: bitmap shown when the mouse is over the button (but it is
  72         not pressed although it may have focus). Notice that if current bitmap
  73         is not specified but the current platform UI uses hover images for the
  74         buttons (such as Windows XP or GTK+), then the focus bitmap is used for
  75         hover state as well. This makes it possible to set focus bitmap only to
  76         get reasonably good behaviour on all platforms.
  77
  78     All of the bitmaps must be of the same size and the normal bitmap must be
  79     set first (to a valid bitmap), before setting any other ones.
  80
  81     The position of the image inside the button be configured using
  82     SetBitmapPosition(). By default the image is on the left of the text.
  83
  84     @library{wxcore}
  85     @category{ctrl}
  86     @appearance{button.png}
  87
  88     @see wxBitmapButton
  89 */
  90 class wxButton : public wxControl
  91 {
  92 public:
  93     /**
  94         Default ctor.
  95     */
  96     wxButton();
  97
  98     /**
  99         Constructor, creating and showing a button.
 100
 101         The preferred way to create standard buttons is to use default value of
 102         @a label. If no label is supplied and @a id is one of standard IDs from
 103         @ref page_stockitems "this list", a standard label will be used.
 104
 105         In addition to that, the button will be decorated with stock icons under GTK+ 2.
 106
 107         @param parent
 108             Parent window. Must not be @NULL.
 109         @param id
 110             Button identifier. A value of wxID_ANY indicates a default value.
 111         @param label
 112             Text to be displayed on the button.
 113         @param pos
 114             Button position.
 115         @param size
 116             Button size. If the default size is specified then the button is sized
 117             appropriately for the text.
 118         @param style
 119             Window style. See wxButton class description.
 120         @param validator
 121             Window validator.
 122         @param name
 123             Window name.
 124
 125         @see Create(), wxValidator
 126     */
 127     wxButton(wxWindow* parent, wxWindowID id,
 128              const wxString& label = wxEmptyString,
 129              const wxPoint& pos = wxDefaultPosition,
 130              const wxSize& size = wxDefaultSize,
 131              long style = 0,
 132              const wxValidator& validator = wxDefaultValidator,
 133              const wxString& name = wxButtonNameStr);
 134
 135     /**
 136         Button creation function for two-step creation.
 137         For more details, see wxButton().
 138     */
 139     bool Create(wxWindow* parent, wxWindowID id,
 140                 const wxString& label = wxEmptyString,
 141                 const wxPoint& pos = wxDefaultPosition,
 142                 const wxSize& size = wxDefaultSize,
 143                 long style = 0,
 144                 const wxValidator& validator = wxDefaultValidator,
 145                 const wxString& name = wxButtonNameStr);
 146
 147     /**
 148         Return the bitmap shown by the button.
 149
 150         The returned bitmap may be invalid only if the button doesn't show any
 151         images.
 152
 153         @see SetBitmap()
 154
 155         @since 2.9.1
 156      */
 157     wxBitmap GetBitmap() const;
 158
 159     /**
 160         Returns the bitmap used when the mouse is over the button, which may be
 161         invalid.
 162
 163         @see SetBitmapCurrent()
 164
 165         @since 2.9.1 (available as wxBitmapButton::GetBitmapHover() in previous
 166             versions)
 167     */
 168     wxBitmap GetBitmapCurrent() const;
 169
 170     /**
 171         Returns the bitmap for the disabled state, which may be invalid.
 172
 173         @see SetBitmapDisabled()
 174
 175         @since 2.9.1 (available in wxBitmapButton only in previous versions)
 176     */
 177     wxBitmap GetBitmapDisabled() const;
 178
 179     /**
 180         Returns the bitmap for the focused state, which may be invalid.
 181
 182         @see SetBitmapFocus()
 183
 184         @since 2.9.1 (available in wxBitmapButton only in previous versions)
 185     */
 186     wxBitmap GetBitmapFocus() const;
 187
 188     /**
 189         Returns the bitmap for the normal state.
 190
 191         This is exactly the same as GetBitmap() but uses a name
 192         backwards-compatible with wxBitmapButton.
 193
 194         @see SetBitmap(), SetBitmapLabel()
 195
 196         @since 2.9.1 (available in wxBitmapButton only in previous versions)
 197     */
 198     wxBitmap GetBitmapLabel() const;
 199
 200     /**
 201         Returns the bitmap for the pressed state, which may be invalid.
 202
 203         @see SetBitmapPressed()
 204
 205         @since 2.9.1 (available as wxBitmapButton::GetBitmapSelected() in
 206             previous versions)
 207     */
 208     wxBitmap GetBitmapPressed() const;
 209
 210     /**
 211         Returns the default size for the buttons. It is advised to make all the dialog
 212         buttons of the same size and this function allows to retrieve the (platform and
 213         current font dependent size) which should be the best suited for this.
 214     */
 215     static wxSize GetDefaultSize();
 216
 217     /**
 218         Returns the string label for the button.
 219
 220         @see SetLabel()
 221     */
 222     wxString GetLabel() const;
 223
 224     /**
 225         Sets the bitmap to display in the button.
 226
 227         The bitmap is displayed together with the button label. This method
 228         sets up a single bitmap which is used in all button states, use
 229         SetBitmapDisabled(), SetBitmapPressed(), SetBitmapCurrent() or
 230         SetBitmapFocus() to change the individual images used in different
 231         states.
 232
 233         @param bitmap
 234             The bitmap to display in the button. May be invalid to remove any
 235             currently displayed bitmap.
 236         @param dir
 237             The position of the bitmap inside the button. By default it is
 238             positioned to the left of the text, near to the left button border.
 239             Other possible values include wxRIGHT, wxTOP and wxBOTTOM.
 240
 241         @see SetBitmapPosition(), SetBitmapMargins()
 242
 243         @since 2.9.1
 244      */
 245     void SetBitmap(const wxBitmap& bitmap, wxDirection dir = wxLEFT);
 246
 247     /**
 248         Sets the bitmap to be shown when the mouse is over the button.
 249
 250         @see GetBitmapCurrent()
 251
 252         @since 2.9.1 (available as wxBitmapButton::SetBitmapHover() in previous
 253             versions)
 254     */
 255     void SetBitmapCurrent(const wxBitmap& bitmap);
 256
 257     /**
 258         Sets the bitmap for the disabled button appearance.
 259
 260         @see GetBitmapDisabled(), SetBitmapLabel(),
 261              SetBitmapPressed(), SetBitmapFocus()
 262
 263         @since 2.9.1 (available in wxBitmapButton only in previous versions)
 264     */
 265     void SetBitmapDisabled(const wxBitmap& bitmap);
 266
 267     /**
 268         Sets the bitmap for the button appearance when it has the keyboard
 269         focus.
 270
 271         @see GetBitmapFocus(), SetBitmapLabel(),
 272              SetBitmapPressed(), SetBitmapDisabled()
 273
 274         @since 2.9.1 (available in wxBitmapButton only in previous versions)
 275     */
 276     void SetBitmapFocus(const wxBitmap& bitmap);
 277
 278     /**
 279         Sets the bitmap label for the button.
 280
 281         @remarks This is the bitmap used for the unselected state, and for all
 282                  other states if no other bitmaps are provided.
 283
 284         @see SetBitmap(), GetBitmapLabel()
 285
 286         @since 2.9.1 (available in wxBitmapButton only in previous versions)
 287     */
 288     void SetBitmapLabel(const wxBitmap& bitmap);
 289
 290     /**
 291         Sets the bitmap for the selected (depressed) button appearance.
 292
 293         @since 2.9.1 (available as wxBitmapButton::SetBitmapSelected() in
 294             previous versions)
 295     */
 296     void SetBitmapPressed(const wxBitmap& bitmap);
 297
 298     /**
 299         Set the margins between the bitmap and the text of the button.
 300
 301         This method is currently only implemented under MSW. If it is not
 302         called, default margin is used around the bitmap.
 303
 304         @see SetBitmap(), SetBitmapPosition()
 305
 306         @since 2.9.1
 307      */
 308     //@{
 309     void SetBitmapMargins(wxCoord x, wxCoord y);
 310     void SetBitmapMargins(const wxSize& sz);
 311     //@}
 312
 313     /**
 314         Set the position at which the bitmap is displayed.
 315
 316         This method should only be called if the button does have an associated
 317         bitmap.
 318
 319         @since 2.9.1
 320
 321         @param dir
 322             Direction in which the bitmap should be positioned, one of wxLEFT,
 323             wxRIGHT, wxTOP or wxBOTTOM.
 324      */
 325     void SetBitmapPosition(wxDirection dir);
 326
 327     /**
 328         This sets the button to be the default item in its top-level window
 329         (e.g. the panel or the dialog box containing it).
 330
 331         As normal, pressing return causes the default button to be depressed when
 332         the return key is pressed.
 333
 334         See also wxWindow::SetFocus() which sets the keyboard focus for windows
 335         and text panel items, and wxTopLevelWindow::SetDefaultItem().
 336
 337         @remarks Under Windows, only dialog box buttons respond to this function.
 338
 339         @return the old default item (possibly NULL)
 340     */
 341     virtual wxWindow* SetDefault();
 342
 343     /**
 344         Sets the string label for the button.
 345
 346         @param label
 347             The label to set.
 348     */
 349     void SetLabel(const wxString& label);
 350 };
 351