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