/////////////////////////////////////////////////////////////////////////////
// Name: bmpbuttn.h
-// Purpose: documentation for wxBitmapButton class
+// Purpose: interface of wxBitmapButton
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
/**
@class wxBitmapButton
@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}:
+ @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.
- @style{wxBU_LEFT}:
- Left-justifies the bitmap label. WIN32 only.
- @style{wxBU_TOP}:
- Aligns the bitmap label to the top of the button. WIN32 only.
- @style{wxBU_RIGHT}:
- Right-justifies the bitmap label. WIN32 only.
- @style{wxBU_BOTTOM}:
- Aligns the bitmap label to the bottom of the button. WIN32 only.
+ all provided bitmaps. Has effect only under MS Windows.
+ @style{wxBU_LEFT}
+ Left-justifies the bitmap label. Has effect only under MS Windows.
+ @style{wxBU_TOP}
+ Aligns the bitmap label to the top of the button.
+ Has effect only under MS Windows.
+ @style{wxBU_RIGHT}
+ Right-justifies the bitmap label. Has effect only under MS Windows.
+ @style{wxBU_BOTTOM}
+ Aligns the bitmap label to the bottom of the button.
+ Has effect only under MS Windows.
@endStyleTable
-
- @beginEventTable
- @event{EVT_BUTTON(id\, func)}:
- Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is
- clicked.
+
+ 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{wxCommandEvent}
+ @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
+ <!-- @appearance{bitmapbutton.png} -->
+
+ @see wxButton
*/
class wxBitmapButton : public wxButton
{
public:
- //@{
/**
- Constructor, creating and showing a button.
-
- @param parent
- Parent window. Must not be @NULL.
-
- @param id
- Button identifier. The value wxID_ANY indicates a default value.
-
- @param bitmap
- Bitmap to be displayed.
-
- @param pos
- Button position.
-
- @param size
- Button size. If wxDefaultSize is specified then the button is sized
- appropriately for the bitmap.
-
- @param style
- Window style. See wxBitmapButton.
-
- @param 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
+ Default ctor.
*/
wxBitmapButton();
- wxBitmapButton(wxWindow* parent, wxWindowID id,
- const wxBitmap& bitmap,
- const wxPoint& pos = wxDefaultPosition,
- const wxSize& size = wxDefaultSize,
- long style = wxBU_AUTODRAW,
- const wxValidator& validator = wxDefaultValidator,
- const wxString& name = "button");
- //@}
+
+ /**
+ Constructor, creating and showing a button.
+
+ @param parent
+ Parent window. Must not be @NULL.
+ @param id
+ Button identifier. The value wxID_ANY indicates a default value.
+ @param bitmap
+ Bitmap to be displayed.
+ @param pos
+ Button position.
+ @param size
+ Button size. If wxDefaultSize is specified then the button is sized
+ appropriately for the bitmap.
+ @param style
+ Window style. See wxBitmapButton.
+ @param 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().
+
+ @see Create(), wxValidator
+ */
+ wxBitmapButton(wxWindow* parent, wxWindowID id,
+ const wxBitmap& bitmap,
+ const wxPoint& pos = wxDefaultPosition,
+ const wxSize& size = wxDefaultSize,
+ long style = wxBU_AUTODRAW,
+ const wxValidator& validator = wxDefaultValidator,
+ const wxString& name = wxButtonNameStr);
/**
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,
- const wxPoint& pos,
+ const wxPoint& pos = wxDefaultPosition,
const wxSize& size = wxDefaultSize,
- long style = 0,
- const wxValidator& validator,
- const wxString& name = "button");
+ long style = wxBU_AUTODRAW,
+ const wxValidator& validator = wxDefaultValidator,
+ const wxString& name = wxButtonNameStr);
//@{
/**
- Returns the bitmap for the disabled state, may be invalid.
-
- @returns A reference to the disabled state bitmap.
-
- @sa SetBitmapDisabled()
+ Returns the bitmap for the disabled state, which may be invalid.
+
+ @return A reference to the disabled state bitmap.
+
+ @see SetBitmapDisabled()
*/
- const wxBitmap GetBitmapDisabled();
- wxBitmap GetBitmapDisabled();
+ const wxBitmap& GetBitmapDisabled() const;
+ wxBitmap& GetBitmapDisabled();
//@}
//@{
/**
- Returns the bitmap for the focused state, may be invalid.
-
- @returns A reference to the focused state bitmap.
-
- @sa SetBitmapFocus()
+ Returns the bitmap for the focused state, which may be invalid.
+
+ @return A reference to the focused state bitmap.
+
+ @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()
+
+ @return A reference to the button's label bitmap.
+
+ @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()
+
+ @return 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.
-
- @sa GetBitmapDisabled(), SetBitmapLabel(),
- SetBitmapSelected(), SetBitmapFocus()
+
+ @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.
-
- @sa GetBitmapFocus(), SetBitmapLabel(),
- SetBitmapSelected(), SetBitmapDisabled()
+
+ @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.
-
- This function is new since wxWidgets version 2.7.0 and the hover bitmap is
- currently only supported in wxMSW.
-
- @sa GetBitmapHover()
+
+ @since 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.
-
+
+ @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.
-
- @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.
+
+ @param bitmap
+ The bitmap to set.
*/
- void SetBitmapSelected(const wxBitmap& bitmap);
+ virtual void SetBitmapSelected(const wxBitmap& bitmap);
};
+
projects / wxWidgets.git / blobdiff