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