X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7c913512a4c9f36e11e07ea707002fab1608d324..e333075415c35d2e869ea585fa41f01a2c938897:/interface/bmpbuttn.h diff --git a/interface/bmpbuttn.h b/interface/bmpbuttn.h index 783cb848de..76df95492e 100644 --- a/interface/bmpbuttn.h +++ b/interface/bmpbuttn.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: bmpbuttn.h -// Purpose: documentation for wxBitmapButton class +// Purpose: interface of wxBitmapButton // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -11,81 +11,97 @@ @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. + @event{EVT_BUTTON(id, func)}: + Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is clicked. @endEventTable @library{wxcore} @category{ctrl} @appearance{bitmapbutton.png} - @seealso - wxButton + @see wxButton */ class wxBitmapButton : public wxButton { public: - //@{ + /** + Default ctor. + */ + wxBitmapButton(); + /** Constructor, creating and showing a button. - + @param parent - Parent window. Must not be @NULL. - + Parent window. Must not be @NULL. @param id - Button identifier. The value wxID_ANY indicates a default value. - + Button identifier. The value wxID_ANY indicates a default value. @param bitmap - Bitmap to be displayed. - + Bitmap to be displayed. @param pos - Button position. - + Button position. @param size - Button size. If wxDefaultSize is specified then the button is sized - appropriately for the bitmap. - + Button size. If wxDefaultSize is specified then the button is sized + appropriately for the bitmap. @param style - Window style. See wxBitmapButton. - + Window style. See wxBitmapButton. @param validator - Window validator. - + 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(). - - @sa Create(), wxValidator + 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(). + + @see Create(), wxValidator */ - wxBitmapButton(); wxBitmapButton(wxWindow* parent, wxWindowID id, const wxBitmap& bitmap, const wxPoint& pos = wxDefaultPosition, @@ -93,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, @@ -114,109 +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. - - @sa SetBitmapDisabled() + + @see SetBitmapDisabled() */ - const wxBitmap GetBitmapDisabled(); - 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. - - @sa SetBitmapFocus() + + @see SetBitmapFocus() */ - const wxBitmap GetBitmapFocus(); - wxBitmap GetBitmapFocus(); + const wxBitmap& GetBitmapFocus() const; + wxBitmap& GetBitmapFocus(); //@} //@{ /** - Returns the bitmap used when the mouse is over the button, may be invalid. - - @sa SetBitmapHover() + Returns the bitmap used when the mouse is over the button, which may be invalid. + + @see SetBitmapHover() */ - const wxBitmap GetBitmapHover(); - 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. - - @sa SetBitmapLabel() + + @see SetBitmapLabel() */ - const wxBitmap GetBitmapLabel(); - wxBitmap GetBitmapLabel(); + const wxBitmap& GetBitmapLabel(); + wxBitmap& GetBitmapLabel(); //@} /** Returns the bitmap for the selected state. - + @returns A reference to the selected state bitmap. - - @sa SetBitmapSelected() + + @see SetBitmapSelected() */ - wxBitmap GetBitmapSelected(); + wxBitmap& GetBitmapSelected() const; /** Sets the bitmap for the disabled button appearance. - + @param bitmap - The bitmap to set. - - @sa GetBitmapDisabled(), SetBitmapLabel(), - SetBitmapSelected(), SetBitmapFocus() + 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. - - @sa GetBitmapFocus(), SetBitmapLabel(), - SetBitmapSelected(), SetBitmapDisabled() + 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. - - This function is new since wxWidgets version 2.7.0 and the hover bitmap is - currently only supported in wxMSW. - - @sa GetBitmapHover() + + @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. - + 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. - - @sa GetBitmapLabel() + 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. + The bitmap to set. */ - void SetBitmapSelected(const wxBitmap& bitmap); + virtual void SetBitmapSelected(const wxBitmap& bitmap); }; +