// Purpose: interface of wxButton
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
+
/**
@class wxButton
- @wxheader{button.h}
A button is a control that contains a text string, and is one of the most
common elements of a GUI.
It may be placed on a @ref wxDialog "dialog box" or on a @ref wxPanel panel,
or indeed on almost any other window.
+ By default, i.e. if none of the alignment styles are specified, the label
+ is centered both horizontally and vertically. If the button has both a
+ label and a bitmap, the alignment styles above specify the location of the
+ rectangle combining both the label and the bitmap and the bitmap position
+ set with wxButton::SetBitmapPosition() defines the relative position of the
+ bitmap with respect to the label (however currently non-default alignment
+ combinations are not implemented on all platforms).
+
+ Since version 2.9.1 wxButton supports showing both text and an image
+ (currently only when using wxMSW, wxGTK or wxOSX/Cocoa ports), see
+ SetBitmap() and SetBitmapLabel(), SetBitmapDisabled() &c methods. In the
+ previous wxWidgets versions this functionality was only available in (the
+ now trivial) wxBitmapButton class which was only capable of showing an
+ image without text.
+
+ A button may have either a single image for all states or different images
+ for the following states (different images are not currently supported
+ under OS X where the normal image is used for all states):
+ @li @b normal: the default state
+ @li @b disabled: bitmap shown when the button is disabled.
+ @li @b pressed: bitmap shown when the button is pushed (e.g. while the user
+ keeps the mouse button pressed on it)
+ @li @b focus: bitmap shown when the button has keyboard focus (but is not
+ pressed as in this case the button is in the pressed state)
+ @li @b current: bitmap shown when the mouse is over the button (but it is
+ not pressed although it may have focus). Notice that if current bitmap
+ is not specified but the current platform UI uses hover images for the
+ buttons (such as Windows XP or GTK+), then the focus bitmap is used for
+ hover state as well. This makes it possible to set focus bitmap only to
+ get reasonably good behaviour on all platforms.
+
+ All of the bitmaps must be of the same size and the normal bitmap must be
+ set first (to a valid bitmap), before setting any other ones. Also, if the
+ size of the bitmaps is changed later, you need to change the size of the
+ normal bitmap before setting any other bitmaps with the new size (and you
+ do need to reset all of them as their original values can be lost when the
+ normal bitmap size changes).
+
+ The position of the image inside the button be configured using
+ SetBitmapPosition(). By default the image is on the left of the text.
+
+ Please also notice that GTK+ uses a global setting called @c gtk-button-images
+ to determine if the images should be shown in the buttons
+ at all. If it is off (which is the case in e.g. Gnome 2.28 by default), no
+ images will be shown, consistently with the native behaviour.
+
@beginStyleTable
@style{wxBU_LEFT}
- Left-justifies the label. Windows and GTK+ only.
+ Left-justifies the label. Windows and GTK+ only.
@style{wxBU_TOP}
- Aligns the label to the top of the button. Windows and GTK+ only.
+ Aligns the label to the top of the button. Windows and GTK+ only.
@style{wxBU_RIGHT}
- Right-justifies the bitmap label. Windows and GTK+ only.
+ Right-justifies the bitmap label. Windows and GTK+ only.
@style{wxBU_BOTTOM}
- Aligns the label to the bottom of the button. Windows and GTK+ only.
+ Aligns the label to the bottom of the button. Windows and GTK+ only.
@style{wxBU_EXACTFIT}
- Creates the button as small as possible instead of making it of the
- standard size (which is the default behaviour ).
+ By default, all buttons are made of at least the standard button size,
+ even if their contents is small enough to fit into a smaller size. This
+ is done for consistency as most platforms use buttons of the same size
+ in the native dialogs, but can be overridden by specifying this flag.
+ If it is given, the button will be made just big enough for its
+ contents. Notice that under MSW the button will still have at least the
+ standard height, even with this style, if it has a non-empty label.
+ @style{wxBU_NOTEXT}
+ Disables the display of the text label in the button even if it has one
+ or its id is one of the standard stock ids with an associated label:
+ without using this style a button which is only supposed to show a
+ bitmap but uses a standard id would display a label too.
@style{wxBORDER_NONE}
- Creates a flat button. Windows and GTK+ only.
+ Creates a button without border. This is currently implemented in MSW,
+ GTK2 and OSX/Cocoa and OSX/Carbon ports but in the latter only applies
+ to buttons with bitmaps and using bitmap of one of the standard sizes
+ only, namely 128*128, 48*48, 24*24 or 16*16. In all the other cases
+ wxBORDER_NONE is ignored under OSX/Carbon (these restrictions don't
+ exist in OSX/Cocoa however).
@endStyleTable
- @beginEventTable{wxCommandEvent}
+ @beginEventEmissionTable{wxCommandEvent}
@event{EVT_BUTTON(id, func)}
- Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is clicked.
+ Process a @c wxEVT_BUTTON event, when the button is clicked.
@endEventTable
@library{wxcore}
@category{ctrl}
- <!-- @appearance{button.png} -->
+ @appearance{button}
@see wxBitmapButton
*/
-class wxButton : public wxControl
+class wxButton : public wxAnyButton
{
public:
/**
The preferred way to create standard buttons is to use default value of
@a label. If no label is supplied and @a id is one of standard IDs from
- @ref page_stockitems "this list", a standard label will be used.
+ @ref page_stockitems "this list", a standard label will be used. In
+ other words, if you use a predefined @c wxID_XXX constant, just omit
+ the label completely rather than specifying it. In particular, help
+ buttons (the ones with @a id of @c wxID_HELP) under Mac OS X can't
+ display any label at all and while wxButton will detect if the standard
+ "Help" label is used and ignore it, using any other label will prevent
+ the button from correctly appearing as a help button and so should be
+ avoided.
+
In addition to that, the button will be decorated with stock icons under GTK+ 2.
@param parent
Parent window. Must not be @NULL.
@param id
- Button identifier. A value of wxID_ANY indicates a default value.
+ Button identifier. A value of @c wxID_ANY indicates a default value.
@param label
Text to be displayed on the button.
@param pos
const wxValidator& validator = wxDefaultValidator,
const wxString& name = wxButtonNameStr);
- /**
- Destructor, destroying the button.
- */
- virtual ~wxButton();
-
/**
Button creation function for two-step creation.
For more details, see wxButton().
const wxValidator& validator = wxDefaultValidator,
const wxString& name = wxButtonNameStr);
+ /**
+ Returns @true if an authentication needed symbol is displayed on the
+ button.
+
+ @remarks This method always returns @false if the platform is not
+ Windows Vista or newer.
+
+ @see SetAuthNeeded()
+
+ @since 2.9.1
+ */
+ bool GetAuthNeeded() const;
+
+
/**
Returns the default size for the buttons. It is advised to make all the dialog
buttons of the same size and this function allows to retrieve the (platform and
*/
wxString GetLabel() const;
+ /**
+ Sets whether an authentication needed symbol should be displayed on the
+ button.
+
+ @remarks This method doesn't do anything if the platform is not Windows
+ Vista or newer.
+
+ @see GetAuthNeeded()
+
+ @since 2.9.1
+ */
+ void SetAuthNeeded(bool needed = true);
+
+
/**
This sets the button to be the default item in its top-level window
(e.g. the panel or the dialog box containing it).
@remarks Under Windows, only dialog box buttons respond to this function.
- @return the old default item (possibly NULL)
+ @return the old default item (possibly @NULL)
*/
virtual wxWindow* SetDefault();
projects / wxWidgets.git / blobdiff