X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e5d05b907c823c87f7d4f92e535c15a7ee0124f2..b02dd12239c8a59b9a545d9fcb04974f8ad02c6b:/interface/wx/button.h?ds=inline diff --git a/interface/wx/button.h b/interface/wx/button.h index 5669cfc7bc..7220330818 100644 --- a/interface/wx/button.h +++ b/interface/wx/button.h @@ -3,9 +3,10 @@ // Purpose: interface of wxButton // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// + /** @class wxButton @@ -15,31 +16,6 @@ It may be placed on a @ref wxDialog "dialog box" or on a @ref wxPanel panel, or indeed on almost any other window. - @beginStyleTable - @style{wxBU_LEFT} - Left-justifies the label. Windows and GTK+ only. - @style{wxBU_TOP} - 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. - @style{wxBU_BOTTOM} - 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 ). - @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 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 @@ -48,12 +24,6 @@ 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 @@ -78,18 +48,58 @@ 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. + 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. + @style{wxBU_TOP} + 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. + @style{wxBU_BOTTOM} + 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 ). + @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 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 + + @beginEventEmissionTable{wxCommandEvent} + @event{EVT_BUTTON(id, func)} + Process a @c wxEVT_COMMAND_BUTTON_CLICKED event, when the button is clicked. + @endEventTable + @library{wxcore} @category{ctrl} @appearance{button.png} @see wxBitmapButton */ -class wxButton : public wxControl +class wxButton : public wxAnyButton { public: /** @@ -102,14 +112,22 @@ 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 @@ -147,67 +165,18 @@ public: const wxString& name = wxButtonNameStr); /** - Return the bitmap shown by the button. + Returns @true if an authentication needed symbol is displayed on the + button. - The returned bitmap may be invalid only if the button doesn't show any - images. + @remarks This method always returns @false if the platform is not + Windows Vista or newer. - @see SetBitmap() + @see SetAuthNeeded() @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; + bool GetAuthNeeded() 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 @@ -224,107 +193,18 @@ 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. + Sets whether an authentication needed symbol should be displayed on the + button. - @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. + @remarks This method doesn't do anything if the platform is not Windows + Vista or newer. - @see SetBitmapPosition(), SetBitmapMargins() + @see GetAuthNeeded() @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. + void SetAuthNeeded(bool needed = true); - @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 @@ -338,7 +218,7 @@ public: @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();