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