preparation work for implementing images support in wxButton: move wxBitmapButton methods to the base class (enhancing/completing them in the process); there are no functionality changes yet (hopefully)
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@61051 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Vadim Zeitlin
@@ -10,28 +10,12 @@
|
||||
@class wxBitmapButton
|
||||
|
||||
A bitmap button is a control that contains a bitmap.
|
||||
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 bitmapbutton_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.
|
||||
Notice that since wxWidgets 2.9.1 bitmap display is supported by the base
|
||||
wxButton class itself and the only tiny advantage of using this class is
|
||||
that it allows to specify the bitmap in its constructor, unlike wxButton.
|
||||
Please see the base class documentation for more information about images
|
||||
support in wxButton.
|
||||
|
||||
@beginStyleTable
|
||||
@style{wxBU_AUTODRAW}
|
||||
@@ -98,7 +82,7 @@ public:
|
||||
|
||||
@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(),
|
||||
If you want more control, call any of the functions SetBitmapPressed(),
|
||||
SetBitmapFocus(), SetBitmapDisabled().
|
||||
|
||||
@see Create(), wxValidator
|
||||
@@ -111,11 +95,6 @@ public:
|
||||
const wxValidator& validator = wxDefaultValidator,
|
||||
const wxString& name = wxButtonNameStr);
|
||||
|
||||
/**
|
||||
Destructor, destroying the button.
|
||||
*/
|
||||
virtual ~wxBitmapButton();
|
||||
|
||||
/**
|
||||
Button creation function for two-step creation.
|
||||
For more details, see wxBitmapButton().
|
||||
@@ -127,114 +106,5 @@ public:
|
||||
long style = wxBU_AUTODRAW,
|
||||
const wxValidator& validator = wxDefaultValidator,
|
||||
const wxString& name = wxButtonNameStr);
|
||||
|
||||
//@{
|
||||
/**
|
||||
Returns the bitmap for the disabled state, which may be invalid.
|
||||
|
||||
@return A reference to the disabled state bitmap.
|
||||
|
||||
@see SetBitmapDisabled()
|
||||
*/
|
||||
const wxBitmap& GetBitmapDisabled() const;
|
||||
wxBitmap& GetBitmapDisabled();
|
||||
//@}
|
||||
|
||||
//@{
|
||||
/**
|
||||
Returns the bitmap for the focused state, which may be invalid.
|
||||
|
||||
@return A reference to the focused state bitmap.
|
||||
|
||||
@see SetBitmapFocus()
|
||||
*/
|
||||
const wxBitmap& GetBitmapFocus() const;
|
||||
wxBitmap& GetBitmapFocus();
|
||||
//@}
|
||||
|
||||
//@{
|
||||
/**
|
||||
Returns the bitmap used when the mouse is over the button, which may be invalid.
|
||||
|
||||
@see SetBitmapHover()
|
||||
*/
|
||||
const wxBitmap& GetBitmapHover() const;
|
||||
wxBitmap& GetBitmapHover();
|
||||
//@}
|
||||
|
||||
//@{
|
||||
/**
|
||||
Returns the label bitmap (the one passed to the constructor), always valid.
|
||||
|
||||
@return A reference to the button's label bitmap.
|
||||
|
||||
@see SetBitmapLabel()
|
||||
*/
|
||||
const wxBitmap& GetBitmapLabel() const;
|
||||
wxBitmap& GetBitmapLabel();
|
||||
//@}
|
||||
|
||||
/**
|
||||
Returns the bitmap for the selected state.
|
||||
|
||||
@return A reference to the selected state bitmap.
|
||||
|
||||
@see SetBitmapSelected()
|
||||
*/
|
||||
const wxBitmap& GetBitmapSelected() const;
|
||||
|
||||
/**
|
||||
Sets the bitmap for the disabled button appearance.
|
||||
|
||||
@param bitmap
|
||||
The bitmap to set.
|
||||
|
||||
@see GetBitmapDisabled(), SetBitmapLabel(),
|
||||
SetBitmapSelected(), SetBitmapFocus()
|
||||
*/
|
||||
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()
|
||||
*/
|
||||
virtual void SetBitmapFocus(const wxBitmap& bitmap);
|
||||
|
||||
/**
|
||||
Sets the bitmap to be shown when the mouse is over the button.
|
||||
|
||||
@since 2.7.0
|
||||
|
||||
The hover bitmap is currently only supported in wxMSW.
|
||||
|
||||
@see GetBitmapHover()
|
||||
*/
|
||||
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()
|
||||
*/
|
||||
virtual void SetBitmapLabel(const wxBitmap& bitmap);
|
||||
|
||||
/**
|
||||
Sets the bitmap for the selected (depressed) button appearance.
|
||||
|
||||
@param bitmap
|
||||
The bitmap to set.
|
||||
*/
|
||||
virtual void SetBitmapSelected(const wxBitmap& bitmap);
|
||||
};
|
||||
|
||||
|
||||
@@ -36,6 +36,34 @@
|
||||
Process a 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
|
||||
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:
|
||||
@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
|
||||
keeps the mouse button pressed on it)
|
||||
@li @b focus: bitmap shown when the button has keyboard focus (but is not
|
||||
pressed as in this case the button is in the pressed state)
|
||||
@li @b current: bitmap shown when the mouse is over the button (but it is
|
||||
not pressed although it may have focus). Notice that if current 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.
|
||||
|
||||
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.
|
||||
|
||||
The position of the image inside the button be configured using
|
||||
SetBitmapPosition(). By default the image is on the left of the text.
|
||||
|
||||
@library{wxcore}
|
||||
@category{ctrl}
|
||||
@appearance{button.png}
|
||||
@@ -87,11 +115,6 @@ public:
|
||||
const wxValidator& validator = wxDefaultValidator,
|
||||
const wxString& name = wxButtonNameStr);
|
||||
|
||||
/**
|
||||
Destructor, destroying the button.
|
||||
*/
|
||||
virtual ~wxButton();
|
||||
|
||||
/**
|
||||
Button creation function for two-step creation.
|
||||
For more details, see wxButton().
|
||||
@@ -104,6 +127,69 @@ public:
|
||||
const wxValidator& validator = wxDefaultValidator,
|
||||
const wxString& name = wxButtonNameStr);
|
||||
|
||||
/**
|
||||
Return the bitmap shown by the button.
|
||||
|
||||
The returned bitmap may be invalid only if the button doesn't show any
|
||||
images.
|
||||
|
||||
@see SetBitmap()
|
||||
|
||||
@since 2.9.1
|
||||
*/
|
||||
wxBitmap GetBitmap() const;
|
||||
|
||||
/**
|
||||
Returns the bitmap used when the mouse is over the button, which may be
|
||||
invalid.
|
||||
|
||||
@see SetBitmapCurrent()
|
||||
|
||||
@since 2.9.1 (available as wxBitmapButton::GetBitmapHover() in previous
|
||||
versions)
|
||||
*/
|
||||
wxBitmap GetBitmapCurrent() const;
|
||||
|
||||
/**
|
||||
Returns the bitmap for the disabled state, which may be invalid.
|
||||
|
||||
@see SetBitmapDisabled()
|
||||
|
||||
@since 2.9.1 (available in wxBitmapButton only in previous versions)
|
||||
*/
|
||||
wxBitmap GetBitmapDisabled() const;
|
||||
|
||||
/**
|
||||
Returns the bitmap for the focused state, which may be invalid.
|
||||
|
||||
@see SetBitmapFocus()
|
||||
|
||||
@since 2.9.1 (available in wxBitmapButton only in previous versions)
|
||||
*/
|
||||
wxBitmap GetBitmapFocus() const;
|
||||
|
||||
/**
|
||||
Returns the bitmap for the normal state.
|
||||
|
||||
This is exactly the same as GetBitmap() but uses a name
|
||||
backwards-compatible with wxBitmapButton.
|
||||
|
||||
@see SetBitmap(), SetBitmapLabel()
|
||||
|
||||
@since 2.9.1 (available in wxBitmapButton only in previous versions)
|
||||
*/
|
||||
wxBitmap GetBitmapLabel() const;
|
||||
|
||||
/**
|
||||
Returns the bitmap for the pressed state, which may be invalid.
|
||||
|
||||
@see SetBitmapPressed()
|
||||
|
||||
@since 2.9.1 (available as wxBitmapButton::GetBitmapSelected() in
|
||||
previous versions)
|
||||
*/
|
||||
wxBitmap GetBitmapPressed() const;
|
||||
|
||||
/**
|
||||
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
|
||||
@@ -118,6 +204,109 @@ public:
|
||||
*/
|
||||
wxString GetLabel() const;
|
||||
|
||||
/**
|
||||
Sets the bitmap to display in the button.
|
||||
|
||||
The bitmap is displayed together with the button label. This method
|
||||
sets up a single bitmap which is used in all button states, use
|
||||
SetBitmapDisabled(), SetBitmapPressed(), SetBitmapCurrent() or
|
||||
SetBitmapFocus() to change the individual images used in different
|
||||
states.
|
||||
|
||||
@param bitmap
|
||||
The bitmap to display in the button. May be invalid to remove any
|
||||
currently displayed bitmap.
|
||||
@param dir
|
||||
The position of the bitmap inside the button. By default it is
|
||||
positioned to the left of the text, near to the left button border.
|
||||
Other possible values include wxRIGHT, wxTOP and wxBOTTOM.
|
||||
|
||||
@see SetBitmapPosition(), SetBitmapMargins()
|
||||
|
||||
@since 2.9.1
|
||||
*/
|
||||
void SetBitmap(const wxBitmap& bitmap, wxDirection dir = wxLEFT);
|
||||
|
||||
/**
|
||||
Sets the bitmap to be shown when the mouse is over the button.
|
||||
|
||||
@see GetBitmapCurrent()
|
||||
|
||||
@since 2.9.1 (available as wxBitmapButton::SetBitmapHover() in previous
|
||||
versions)
|
||||
*/
|
||||
void SetBitmapCurrent(const wxBitmap& bitmap);
|
||||
|
||||
/**
|
||||
Sets the bitmap for the disabled button appearance.
|
||||
|
||||
@see GetBitmapDisabled(), SetBitmapLabel(),
|
||||
SetBitmapPressed(), SetBitmapFocus()
|
||||
|
||||
@since 2.9.1 (available in wxBitmapButton only in previous versions)
|
||||
*/
|
||||
void SetBitmapDisabled(const wxBitmap& bitmap);
|
||||
|
||||
/**
|
||||
Sets the bitmap for the button appearance when it has the keyboard
|
||||
focus.
|
||||
|
||||
@see GetBitmapFocus(), SetBitmapLabel(),
|
||||
SetBitmapPressed(), SetBitmapDisabled()
|
||||
|
||||
@since 2.9.1 (available in wxBitmapButton only in previous versions)
|
||||
*/
|
||||
void SetBitmapFocus(const wxBitmap& bitmap);
|
||||
|
||||
/**
|
||||
Sets the bitmap label for the button.
|
||||
|
||||
@remarks This is the bitmap used for the unselected state, and for all
|
||||
other states if no other bitmaps are provided.
|
||||
|
||||
@see SetBitmap(), GetBitmapLabel()
|
||||
|
||||
@since 2.9.1 (available in wxBitmapButton only in previous versions)
|
||||
*/
|
||||
void SetBitmapLabel(const wxBitmap& bitmap);
|
||||
|
||||
/**
|
||||
Sets the bitmap for the selected (depressed) button appearance.
|
||||
|
||||
@since 2.9.1 (available as wxBitmapButton::SetBitmapSelected() in
|
||||
previous versions)
|
||||
*/
|
||||
void SetBitmapPressed(const wxBitmap& bitmap);
|
||||
|
||||
/**
|
||||
Set the margins between the bitmap and the text of the button.
|
||||
|
||||
This method is currently only implemented under MSW. If it is not
|
||||
called, default margin is used around the bitmap.
|
||||
|
||||
@see SetBitmap(), SetBitmapPosition()
|
||||
|
||||
@since 2.9.1
|
||||
*/
|
||||
//@{
|
||||
void SetBitmapMargins(wxCoord x, wxCoord y);
|
||||
void SetBitmapMargins(const wxSize& sz);
|
||||
//@}
|
||||
|
||||
/**
|
||||
Set the position at which the bitmap is displayed.
|
||||
|
||||
This method should only be called if the button does have an associated
|
||||
bitmap.
|
||||
|
||||
@since 2.9.1
|
||||
|
||||
@param dir
|
||||
Direction in which the bitmap should be positioned, one of wxLEFT,
|
||||
wxRIGHT, wxTOP or wxBOTTOM.
|
||||
*/
|
||||
void SetBitmapPosition(wxDirection dir);
|
||||
|
||||
/**
|
||||
This sets the button to be the default item in its top-level window
|
||||
(e.g. the panel or the dialog box containing it).
|
||||
|
||||
@@ -1119,6 +1119,29 @@ template <typename T> wxDELETEA(T*& array);
|
||||
*/
|
||||
#define wxDEPRECATED_INLINE(func, body)
|
||||
|
||||
/**
|
||||
A helper macro allowing to easily define a simple deprecated accessor.
|
||||
|
||||
Compared to wxDEPRECATED_INLINE() it saves a @c return statement and,
|
||||
especially, a strangely looking semicolon inside a macro.
|
||||
|
||||
Example of use
|
||||
@code
|
||||
class wxFoo
|
||||
{
|
||||
public:
|
||||
int GetValue() const { return m_value; }
|
||||
|
||||
// this one is deprecated because it was erroneously non-const
|
||||
wxDEPRECATED_ACCESSOR( int GetValue(), m_value )
|
||||
|
||||
private:
|
||||
int m_value;
|
||||
};
|
||||
@endcode
|
||||
*/
|
||||
#define wxDEPRECATED_ACCESSOR(func, what)
|
||||
|
||||
/**
|
||||
Combination of wxDEPRECATED_BUT_USED_INTERNALLY() and wxDEPRECATED_INLINE().
|
||||
|
||||
|
||||
Reference in New Issue
Block a user