interface/wx/button.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        button.h
   3 // Purpose:     interface of wxButton
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   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     By default, i.e. if none of the alignment styles are specified, the label
  19     is centered both horizontally and vertically. If the button has both a
  20     label and a bitmap, the alignment styles above specify the location of the
  21     rectangle combining both the label and the bitmap and the bitmap position
  22     set with wxButton::SetBitmapPosition() defines the relative position of the
  23     bitmap with respect to the label (however currently non-default alignment
  24     combinations are not implemented on all platforms).
  25
  26     Since version 2.9.1 wxButton supports showing both text and an image
  27     (currently only when using wxMSW, wxGTK or wxOSX/Cocoa ports), see
  28     SetBitmap() and SetBitmapLabel(), SetBitmapDisabled() &c methods. In the
  29     previous wxWidgets versions this functionality was only available in (the
  30     now trivial) wxBitmapButton class which was only capable of showing an
  31     image without text.
  32
  33     A button may have either a single image for all states or different images
  34     for the following states (different images are not currently supported
  35     under OS X where the normal image is used for all states):
  36     @li @b normal: the default state
  37     @li @b disabled: bitmap shown when the button is disabled.
  38     @li @b pressed: bitmap shown when the button is pushed (e.g. while the user
  39         keeps the mouse button pressed on it)
  40     @li @b focus: bitmap shown when the button has keyboard focus (but is not
  41         pressed as in this case the button is in the pressed state)
  42     @li @b current: bitmap shown when the mouse is over the button (but it is
  43         not pressed although it may have focus). Notice that if current bitmap
  44         is not specified but the current platform UI uses hover images for the
  45         buttons (such as Windows XP or GTK+), then the focus bitmap is used for
  46         hover state as well. This makes it possible to set focus bitmap only to
  47         get reasonably good behaviour on all platforms.
  48
  49     All of the bitmaps must be of the same size and the normal bitmap must be
  50     set first (to a valid bitmap), before setting any other ones. Also, if the
  51     size of the bitmaps is changed later, you need to change the size of the
  52     normal bitmap before setting any other bitmaps with the new size (and you
  53     do need to reset all of them as their original values can be lost when the
  54     normal bitmap size changes).
  55
  56     The position of the image inside the button be configured using
  57     SetBitmapPosition(). By default the image is on the left of the text.
  58
  59     Please also notice that GTK+ uses a global setting called @c gtk-button-images
  60     to determine if the images should be shown in the buttons
  61     at all. If it is off (which is the case in e.g. Gnome 2.28 by default), no
  62     images will be shown, consistently with the native behaviour.
  63
  64     @beginStyleTable
  65     @style{wxBU_LEFT}
  66         Left-justifies the label. Windows and GTK+ only.
  67     @style{wxBU_TOP}
  68         Aligns the label to the top of the button. Windows and GTK+ only.
  69     @style{wxBU_RIGHT}
  70         Right-justifies the bitmap label. Windows and GTK+ only.
  71     @style{wxBU_BOTTOM}
  72         Aligns the label to the bottom of the button. Windows and GTK+ only.
  73     @style{wxBU_EXACTFIT}
  74         By default, all buttons are made of at least the standard button size,
  75         even if their contents is small enough to fit into a smaller size. This
  76         is done for consistency as most platforms use buttons of the same size
  77         in the native dialogs, but can be overridden by specifying this flag.
  78         If it is given, the button will be made just big enough for its
  79         contents. Notice that under MSW the button will still have at least the
  80         standard height, even with this style, if it has a non-empty label.
  81     @style{wxBU_NOTEXT}
  82         Disables the display of the text label in the button even if it has one
  83         or its id is one of the standard stock ids with an associated label:
  84         without using this style a button which is only supposed to show a
  85         bitmap but uses a standard id would display a label too.
  86     @style{wxBORDER_NONE}
  87         Creates a button without border. This is currently implemented in MSW,
  88         GTK2 and OSX/Cocoa and OSX/Carbon ports but in the latter only applies
  89         to buttons with bitmaps and using bitmap of one of the standard sizes
  90         only, namely 128*128, 48*48, 24*24 or 16*16. In all the other cases
  91         wxBORDER_NONE is ignored under OSX/Carbon (these restrictions don't
  92         exist in OSX/Cocoa however).
  93     @endStyleTable
  94
  95     @beginEventEmissionTable{wxCommandEvent}
  96     @event{EVT_BUTTON(id, func)}
  97            Process a @c wxEVT_BUTTON event, when the button is clicked.
  98     @endEventTable
  99
 100     @library{wxcore}
 101     @category{ctrl}
 102     @appearance{button}
 103
 104     @see wxBitmapButton
 105 */
 106 class wxButton : public wxAnyButton
 107 {
 108 public:
 109     /**
 110         Default ctor.
 111     */
 112     wxButton();
 113
 114     /**
 115         Constructor, creating and showing a button.
 116
 117         The preferred way to create standard buttons is to use default value of
 118         @a label. If no label is supplied and @a id is one of standard IDs from
 119         @ref page_stockitems "this list", a standard label will be used. In
 120         other words, if you use a predefined @c wxID_XXX constant, just omit
 121         the label completely rather than specifying it. In particular, help
 122         buttons (the ones with @a id of @c wxID_HELP) under Mac OS X can't
 123         display any label at all and while wxButton will detect if the standard
 124         "Help" label is used and ignore it, using any other label will prevent
 125         the button from correctly appearing as a help button and so should be
 126         avoided.
 127
 128
 129         In addition to that, the button will be decorated with stock icons under GTK+ 2.
 130
 131         @param parent
 132             Parent window. Must not be @NULL.
 133         @param id
 134             Button identifier. A value of @c wxID_ANY indicates a default value.
 135         @param label
 136             Text to be displayed on the button.
 137         @param pos
 138             Button position.
 139         @param size
 140             Button size. If the default size is specified then the button is sized
 141             appropriately for the text.
 142         @param style
 143             Window style. See wxButton class description.
 144         @param validator
 145             Window validator.
 146         @param name
 147             Window name.
 148
 149         @see Create(), wxValidator
 150     */
 151     wxButton(wxWindow* parent, wxWindowID id,
 152              const wxString& label = wxEmptyString,
 153              const wxPoint& pos = wxDefaultPosition,
 154              const wxSize& size = wxDefaultSize,
 155              long style = 0,
 156              const wxValidator& validator = wxDefaultValidator,
 157              const wxString& name = wxButtonNameStr);
 158
 159     /**
 160         Button creation function for two-step creation.
 161         For more details, see wxButton().
 162     */
 163     bool Create(wxWindow* parent, wxWindowID id,
 164                 const wxString& label = wxEmptyString,
 165                 const wxPoint& pos = wxDefaultPosition,
 166                 const wxSize& size = wxDefaultSize,
 167                 long style = 0,
 168                 const wxValidator& validator = wxDefaultValidator,
 169                 const wxString& name = wxButtonNameStr);
 170
 171     /**
 172         Returns @true if an authentication needed symbol is displayed on the
 173         button.
 174
 175         @remarks This method always returns @false if the platform is not
 176                  Windows Vista or newer.
 177
 178         @see SetAuthNeeded()
 179
 180         @since 2.9.1
 181      */
 182     bool GetAuthNeeded() const;
 183
 184
 185     /**
 186         Returns the default size for the buttons. It is advised to make all the dialog
 187         buttons of the same size and this function allows to retrieve the (platform and
 188         current font dependent size) which should be the best suited for this.
 189     */
 190     static wxSize GetDefaultSize();
 191
 192     /**
 193         Returns the string label for the button.
 194
 195         @see SetLabel()
 196     */
 197     wxString GetLabel() const;
 198
 199     /**
 200         Sets whether an authentication needed symbol should be displayed on the
 201         button.
 202
 203         @remarks This method doesn't do anything if the platform is not Windows
 204                  Vista or newer.
 205
 206         @see GetAuthNeeded()
 207
 208         @since 2.9.1
 209      */
 210     void SetAuthNeeded(bool needed = true);
 211
 212
 213     /**
 214         This sets the button to be the default item in its top-level window
 215         (e.g. the panel or the dialog box containing it).
 216
 217         As normal, pressing return causes the default button to be depressed when
 218         the return key is pressed.
 219
 220         See also wxWindow::SetFocus() which sets the keyboard focus for windows
 221         and text panel items, and wxTopLevelWindow::SetDefaultItem().
 222
 223         @remarks Under Windows, only dialog box buttons respond to this function.
 224
 225         @return the old default item (possibly @NULL)
 226     */
 227     virtual wxWindow* SetDefault();
 228
 229     /**
 230         Sets the string label for the button.
 231
 232         @param label
 233             The label to set.
 234     */
 235     void SetLabel(const wxString& label);
 236 };
 237