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