X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/3051a44a73502c2b03d1618d0a8e94274ee67e16..0f08aa44323c65b92cbef304c59b742af8fd717c:/interface/wx/button.h diff --git a/interface/wx/button.h b/interface/wx/button.h index 5bb2bff16e..5669cfc7bc 100644 --- a/interface/wx/button.h +++ b/interface/wx/button.h @@ -17,25 +17,72 @@ @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 ). + Creates the button as small as possible instead of making it of the + standard size (which is the default behaviour ). + @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/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. @endStyleTable + 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). + @beginEventEmissionTable{wxCommandEvent} @event{EVT_BUTTON(id, func)} Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is clicked. @endEventTable + + 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. + + The position of the image inside the button be configured using + SetBitmapPosition(). By default the image is on the left of the text. + @library{wxcore} @category{ctrl} @appearance{button.png} @@ -87,11 +134,6 @@ public: 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(). @@ -104,6 +146,69 @@ public: const wxValidator& validator = wxDefaultValidator, const wxString& name = wxButtonNameStr); + /** + Return the bitmap shown by the button. + + The returned bitmap may be invalid only if the button doesn't show any + images. + + @see SetBitmap() + + @since 2.9.1 + */ + wxBitmap GetBitmap() const; + + /** + Returns the bitmap used when the mouse is over the button, which may be + invalid. + + @see SetBitmapCurrent() + + @since 2.9.1 (available as wxBitmapButton::GetBitmapHover() in previous + versions) + */ + wxBitmap GetBitmapCurrent() const; + + /** + Returns the bitmap for the disabled state, which may be invalid. + + @see SetBitmapDisabled() + + @since 2.9.1 (available in wxBitmapButton only in previous versions) + */ + wxBitmap GetBitmapDisabled() const; + + /** + Returns the bitmap for the focused state, which may be invalid. + + @see SetBitmapFocus() + + @since 2.9.1 (available in wxBitmapButton only in previous versions) + */ + wxBitmap GetBitmapFocus() const; + + /** + Returns the bitmap for the normal state. + + This is exactly the same as GetBitmap() but uses a name + backwards-compatible with wxBitmapButton. + + @see SetBitmap(), SetBitmapLabel() + + @since 2.9.1 (available in wxBitmapButton only in previous versions) + */ + wxBitmap GetBitmapLabel() const; + + /** + Returns the bitmap for the pressed state, which may be invalid. + + @see SetBitmapPressed() + + @since 2.9.1 (available as wxBitmapButton::GetBitmapSelected() in + previous versions) + */ + wxBitmap GetBitmapPressed() 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 @@ -118,6 +223,109 @@ public: */ wxString GetLabel() const; + /** + Sets the bitmap to display in the button. + + The bitmap is displayed together with the button label. This method + sets up a single bitmap which is used in all button states, use + SetBitmapDisabled(), SetBitmapPressed(), SetBitmapCurrent() or + SetBitmapFocus() to change the individual images used in different + states. + + @param bitmap + The bitmap to display in the button. May be invalid to remove any + currently displayed bitmap. + @param dir + The position of the bitmap inside the button. By default it is + positioned to the left of the text, near to the left button border. + Other possible values include wxRIGHT, wxTOP and wxBOTTOM. + + @see SetBitmapPosition(), SetBitmapMargins() + + @since 2.9.1 + */ + void SetBitmap(const wxBitmap& bitmap, wxDirection dir = wxLEFT); + + /** + Sets the bitmap to be shown when the mouse is over the button. + + @see GetBitmapCurrent() + + @since 2.9.1 (available as wxBitmapButton::SetBitmapHover() in previous + versions) + */ + void SetBitmapCurrent(const wxBitmap& bitmap); + + /** + Sets the bitmap for the disabled button appearance. + + @see GetBitmapDisabled(), SetBitmapLabel(), + SetBitmapPressed(), SetBitmapFocus() + + @since 2.9.1 (available in wxBitmapButton only in previous versions) + */ + void SetBitmapDisabled(const wxBitmap& bitmap); + + /** + Sets the bitmap for the button appearance when it has the keyboard + focus. + + @see GetBitmapFocus(), SetBitmapLabel(), + SetBitmapPressed(), SetBitmapDisabled() + + @since 2.9.1 (available in wxBitmapButton only in previous versions) + */ + void SetBitmapFocus(const wxBitmap& bitmap); + + /** + Sets the bitmap label for the button. + + @remarks This is the bitmap used for the unselected state, and for all + other states if no other bitmaps are provided. + + @see SetBitmap(), GetBitmapLabel() + + @since 2.9.1 (available in wxBitmapButton only in previous versions) + */ + void SetBitmapLabel(const wxBitmap& bitmap); + + /** + Sets the bitmap for the selected (depressed) button appearance. + + @since 2.9.1 (available as wxBitmapButton::SetBitmapSelected() in + previous versions) + */ + void SetBitmapPressed(const wxBitmap& bitmap); + + /** + Set the margins between the bitmap and the text of the button. + + This method is currently only implemented under MSW. If it is not + called, default margin is used around the bitmap. + + @see SetBitmap(), SetBitmapPosition() + + @since 2.9.1 + */ + //@{ + void SetBitmapMargins(wxCoord x, wxCoord y); + void SetBitmapMargins(const wxSize& sz); + //@} + + /** + Set the position at which the bitmap is displayed. + + This method should only be called if the button does have an associated + bitmap. + + @since 2.9.1 + + @param dir + Direction in which the bitmap should be positioned, one of wxLEFT, + wxRIGHT, wxTOP or wxBOTTOM. + */ + void SetBitmapPosition(wxDirection dir); + /** This sets the button to be the default item in its top-level window (e.g. the panel or the dialog box containing it).