X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/2352862a7ee8440fdc2ae65baff31b73e40179d5..b72ed64277a2b16c6c8681995e5f3f304a8fe38d:/interface/wx/button.h diff --git a/interface/wx/button.h b/interface/wx/button.h index fa2882bc24..697fc73f6c 100644 --- a/interface/wx/button.h +++ b/interface/wx/button.h @@ -3,7 +3,7 @@ // Purpose: interface of wxButton // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @@ -17,34 +17,53 @@ @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. + Process a @c wxEVT_COMMAND_BUTTON_CLICKED event, when the button is clicked. @endEventTable - Since version 2.9.1 wxButton supports showing both text and an image, see + 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: + 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 @@ -59,11 +78,20 @@ 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. + @library{wxcore} @category{ctrl} @appearance{button.png} @@ -83,7 +111,15 @@ 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. @@ -127,6 +163,19 @@ public: 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; + /** Return the bitmap shown by the button. @@ -190,6 +239,15 @@ public: */ wxBitmap GetBitmapPressed() const; + /** + Get the margins between the bitmap and the text of the button. + + @see SetBitmapMargins() + + @since 2.9.1 + */ + wxSize GetBitmapMargins(); + /** 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 @@ -204,6 +262,19 @@ public: */ 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); + /** Sets the bitmap to display in the button.