/////////////////////////////////////////////////////////////////////////////
// Name: bmpbuttn.h
-// Purpose: documentation for wxBitmapButton class
+// Purpose: interface of wxBitmapButton
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
@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,
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,
//@{
/**
- 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);
};
+
projects / wxWidgets.git / blobdiff