X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e54c96f187f46c06bd36be8cd52b35c19884aa2b..e333075415c35d2e869ea585fa41f01a2c938897:/interface/bmpbuttn.h?ds=sidebyside diff --git a/interface/bmpbuttn.h b/interface/bmpbuttn.h index 02503fedfa..76df95492e 100644 --- a/interface/bmpbuttn.h +++ b/interface/bmpbuttn.h @@ -11,29 +11,53 @@ @wxheader{bmpbuttn.h} A bitmap button is a control that contains a bitmap. - It may be placed on a @ref overview_wxdialog "dialog box" or panel(), or indeed - almost any other window. + It may be placed on a wxDialog or a wxPanel, or indeed almost any other window. + + @remarks + A bitmap button can be supplied with a single bitmap, and wxWidgets will draw + all button states using this bitmap. If the application needs more control, + additional bitmaps for the selected state, unpressed focused state, and greyed-out + state may be supplied. + + @section wxbitmapbutton_states Button states + This class supports bitmaps for several different states: + + @li @b normal: this is the bitmap shown in the default state, it must be always + valid while all the other bitmaps are optional and don't have to be set. + @li @b disabled: bitmap shown when the button is disabled. + @li @b selected: 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. + @li @b hover: bitmap shown when the mouse is over the button (but it is not pressed). + Notice that if hover 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. @beginStyleTable @style{wxBU_AUTODRAW}: If this is specified, the button will be drawn automatically using the label bitmap only, providing a 3D-look border. If this style is not specified, the button will be drawn without borders and using - all provided bitmaps. WIN32 only. + all provided bitmaps. Has effect only under MS Windows. @style{wxBU_LEFT}: - Left-justifies the bitmap label. WIN32 only. + Left-justifies the bitmap label. Has effect only under MS Windows. @style{wxBU_TOP}: - Aligns the bitmap label to the top of the button. WIN32 only. + Aligns the bitmap label to the top of the button. + Has effect only under MS Windows. @style{wxBU_RIGHT}: - Right-justifies the bitmap label. WIN32 only. + Right-justifies the bitmap label. Has effect only under MS Windows. @style{wxBU_BOTTOM}: - Aligns the bitmap label to the bottom of the button. WIN32 only. + Aligns the bitmap label to the bottom of the button. + Has effect only under MS Windows. @endStyleTable + Note that the wxBU_EXACTFIT style supported by wxButton is not used by this + class as bitmap buttons don't have any minimal standard size by default. + @beginEventTable @event{EVT_BUTTON(id, func)}: - Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is - clicked. + Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is clicked. @endEventTable @library{wxcore} @@ -45,10 +69,14 @@ class wxBitmapButton : public wxButton { public: - //@{ + /** + Default ctor. + */ + wxBitmapButton(); + /** Constructor, creating and showing a button. - + @param parent Parent window. Must not be @NULL. @param id @@ -58,8 +86,7 @@ public: @param pos Button position. @param size - Button size. If wxDefaultSize is specified then the button is - sized + Button size. If wxDefaultSize is specified then the button is sized appropriately for the bitmap. @param style Window style. See wxBitmapButton. @@ -67,17 +94,14 @@ public: Window validator. @param name Window name. - - @remarks The bitmap parameter is normally the only bitmap you need to - provide, and wxWidgets will draw the button correctly - in its different states. If you want more control, call - any of the functions SetBitmapSelected(), - SetBitmapFocus(), - SetBitmapDisabled(). - + + @remarks The bitmap parameter is normally the only bitmap you need to provide, + and wxWidgets will draw the button correctly in its different states. + If you want more control, call any of the functions SetBitmapSelected(), + SetBitmapFocus(), SetBitmapDisabled(). + @see Create(), wxValidator */ - wxBitmapButton(); wxBitmapButton(wxWindow* parent, wxWindowID id, const wxBitmap& bitmap, const wxPoint& pos = wxDefaultPosition, @@ -85,16 +109,15 @@ public: long style = wxBU_AUTODRAW, const wxValidator& validator = wxDefaultValidator, const wxString& name = "button"); - //@} /** Destructor, destroying the button. */ - ~wxBitmapButton(); + virtual ~wxBitmapButton(); /** - Button creation function for two-step creation. For more details, see - wxBitmapButton(). + Button creation function for two-step creation. + For more details, see wxBitmapButton(). */ bool Create(wxWindow* parent, wxWindowID id, const wxBitmap& bitmap, @@ -106,110 +129,111 @@ public: //@{ /** - Returns the bitmap for the disabled state, may be invalid. - + Returns the bitmap for the disabled state, which may be invalid. + @returns A reference to the disabled state bitmap. - + @see SetBitmapDisabled() */ - const wxBitmap GetBitmapDisabled(); - const wxBitmap& GetBitmapDisabled(); + const wxBitmap& GetBitmapDisabled() const; + wxBitmap& GetBitmapDisabled(); //@} //@{ /** - Returns the bitmap for the focused state, may be invalid. - + Returns the bitmap for the focused state, which may be invalid. + @returns A reference to the focused state bitmap. - + @see SetBitmapFocus() */ - const wxBitmap GetBitmapFocus(); - const wxBitmap& GetBitmapFocus(); + const wxBitmap& GetBitmapFocus() const; + wxBitmap& GetBitmapFocus(); //@} //@{ /** - Returns the bitmap used when the mouse is over the button, may be invalid. - + Returns the bitmap used when the mouse is over the button, which may be invalid. + @see SetBitmapHover() */ - const wxBitmap GetBitmapHover(); - const wxBitmap& GetBitmapHover(); + const wxBitmap& GetBitmapHover(); + wxBitmap& GetBitmapHover(); //@} //@{ /** Returns the label bitmap (the one passed to the constructor), always valid. - + @returns A reference to the button's label bitmap. - + @see SetBitmapLabel() */ - const wxBitmap GetBitmapLabel(); - const wxBitmap& GetBitmapLabel(); + const wxBitmap& GetBitmapLabel(); + wxBitmap& GetBitmapLabel(); //@} /** Returns the bitmap for the selected state. - + @returns A reference to the selected state bitmap. - + @see SetBitmapSelected() */ - wxBitmap GetBitmapSelected() const; + wxBitmap& GetBitmapSelected() const; /** Sets the bitmap for the disabled button appearance. - + @param bitmap The bitmap to set. - + @see GetBitmapDisabled(), SetBitmapLabel(), SetBitmapSelected(), SetBitmapFocus() */ - void SetBitmapDisabled(const wxBitmap& bitmap); + virtual void SetBitmapDisabled(const wxBitmap& bitmap); /** Sets the bitmap for the button appearance when it has the keyboard focus. - + @param bitmap The bitmap to set. - + @see GetBitmapFocus(), SetBitmapLabel(), SetBitmapSelected(), SetBitmapDisabled() */ - void SetBitmapFocus(const wxBitmap& bitmap); + virtual void SetBitmapFocus(const wxBitmap& bitmap); /** Sets the bitmap to be shown when the mouse is over the button. - - @wxsince{2.7.0} and the hover bitmap is - currently only supported in wxMSW. - + + @wxsince{2.7.0} + + The hover bitmap is currently only supported in wxMSW. + @see GetBitmapHover() */ - void SetBitmapHover(const wxBitmap& bitmap); + virtual void SetBitmapHover(const wxBitmap& bitmap); /** Sets the bitmap label for the button. - + @param bitmap The bitmap label to set. - + @remarks This is the bitmap used for the unselected state, and for all other states if no other bitmaps are provided. - + @see GetBitmapLabel() */ - void SetBitmapLabel(const wxBitmap& bitmap); + virtual void SetBitmapLabel(const wxBitmap& bitmap); /** Sets the bitmap for the selected (depressed) button appearance. - + @param bitmap The bitmap to set. */ - void SetBitmapSelected(const wxBitmap& bitmap); + virtual void SetBitmapSelected(const wxBitmap& bitmap); };