wxButton Class Reference
[Controls]

#include <wx/button.h>

Inheritance diagram for wxButton:
Inheritance graph
[legend]

Detailed Description

A button is a control that contains a text string, and is one of the most common elements of a GUI.

It may be placed on a dialog box or on a wxPanel panel, or indeed on almost any other window.

Styles

This class supports the following styles:

By default, i.e. if none of the alignment styles are specified, the label is centered both horizontally and vertically. If the button has both a label and a bitmap, the alignment styles above specify the location of the rectangle combining both the label and the bitmap and the bitmap position set with wxButton::SetBitmapPosition() defines the relative position of the bitmap with respect to the label (however currently non-default alignment combinations are not implemented on all platforms).

Events emitted by this class

The following event handler macros redirect the events to member function handlers 'func' with prototypes like:

void handlerFuncName(wxCommandEvent& event)

Event macros for events emitted by this class:

Since version 2.9.1 wxButton supports showing both text and an image (currently only when using wxMSW, wxGTK or wxOSX/Cocoa ports), 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 (different images are not currently supported under OS X where the normal image is used for all states):

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:  Controls

Appearance:
wxMSW appearancewxGTK appearancewxMac appearance
wxMSW appearancewxGTK appearancewxMac appearance
See also:
wxBitmapButton

Public Member Functions

 wxButton ()
 Default ctor.
 wxButton (wxWindow *parent, wxWindowID id, const wxString &label=wxEmptyString, const wxPoint &pos=wxDefaultPosition, const wxSize &size=wxDefaultSize, long style=0, const wxValidator &validator=wxDefaultValidator, const wxString &name=wxButtonNameStr)
 Constructor, creating and showing a button.
bool Create (wxWindow *parent, wxWindowID id, const wxString &label=wxEmptyString, const wxPoint &pos=wxDefaultPosition, const wxSize &size=wxDefaultSize, long style=0, const wxValidator &validator=wxDefaultValidator, const wxString &name=wxButtonNameStr)
 Button creation function for two-step creation.
wxBitmap GetBitmap () const
 Return the bitmap shown by the button.
wxBitmap GetBitmapCurrent () const
 Returns the bitmap used when the mouse is over the button, which may be invalid.
wxBitmap GetBitmapDisabled () const
 Returns the bitmap for the disabled state, which may be invalid.
wxBitmap GetBitmapFocus () const
 Returns the bitmap for the focused state, which may be invalid.
wxBitmap GetBitmapLabel () const
 Returns the bitmap for the normal state.
wxBitmap GetBitmapPressed () const
 Returns the bitmap for the pressed state, which may be invalid.
wxString GetLabel () const
 Returns the string label for the button.
void SetBitmap (const wxBitmap &bitmap, wxDirection dir=wxLEFT)
 Sets the bitmap to display in the button.
void SetBitmapCurrent (const wxBitmap &bitmap)
 Sets the bitmap to be shown when the mouse is over the button.
void SetBitmapDisabled (const wxBitmap &bitmap)
 Sets the bitmap for the disabled button appearance.
void SetBitmapFocus (const wxBitmap &bitmap)
 Sets the bitmap for the button appearance when it has the keyboard focus.
void SetBitmapLabel (const wxBitmap &bitmap)
 Sets the bitmap label for the button.
void SetBitmapPressed (const wxBitmap &bitmap)
 Sets the bitmap for the selected (depressed) button appearance.
void SetBitmapPosition (wxDirection dir)
 Set the position at which the bitmap is displayed.
virtual wxWindowSetDefault ()
 This sets the button to be the default item in its top-level window (e.g.
void SetLabel (const wxString &label)
 Sets the string label for the button.



void SetBitmapMargins (wxCoord x, wxCoord y)
 Set the margins between the bitmap and the text of the button.
void SetBitmapMargins (const wxSize &sz)
 Set the margins between the bitmap and the text of the button.

Static Public Member Functions

static wxSize GetDefaultSize ()
 Returns the default size for the buttons.

List of all members.


Constructor & Destructor Documentation

wxButton::wxButton (  ) 

Default ctor.

wxButton::wxButton ( wxWindow parent,
wxWindowID  id,
const wxString label = wxEmptyString,
const wxPoint pos = wxDefaultPosition,
const wxSize size = wxDefaultSize,
long  style = 0,
const wxValidator validator = wxDefaultValidator,
const wxString name = wxButtonNameStr 
)

Constructor, creating and showing a button.

The preferred way to create standard buttons is to use default value of label. If no label is supplied and id is one of standard IDs from this list, a standard label will be used.

In addition to that, the button will be decorated with stock icons under GTK+ 2.

Parameters:
parent Parent window. Must not be NULL.
id Button identifier. A value of wxID_ANY indicates a default value.
label Text to be displayed on the button.
pos Button position.
size Button size. If the default size is specified then the button is sized appropriately for the text.
style Window style. See wxButton class description.
validator Window validator.
name Window name.
See also:
Create(), wxValidator

Member Function Documentation

bool wxButton::Create ( wxWindow parent,
wxWindowID  id,
const wxString label = wxEmptyString,
const wxPoint pos = wxDefaultPosition,
const wxSize size = wxDefaultSize,
long  style = 0,
const wxValidator validator = wxDefaultValidator,
const wxString name = wxButtonNameStr 
)

Button creation function for two-step creation.

For more details, see wxButton().

wxBitmap wxButton::GetBitmap (  )  const

Return the bitmap shown by the button.

The returned bitmap may be invalid only if the button doesn't show any images.

See also:
SetBitmap()
Since:
2.9.1
wxBitmap wxButton::GetBitmapCurrent (  )  const

Returns the bitmap used when the mouse is over the button, which may be invalid.

See also:
SetBitmapCurrent()
Since:
2.9.1 (available as wxBitmapButton::GetBitmapHover() in previous versions)
wxBitmap wxButton::GetBitmapDisabled (  )  const

Returns the bitmap for the disabled state, which may be invalid.

See also:
SetBitmapDisabled()
Since:
2.9.1 (available in wxBitmapButton only in previous versions)
wxBitmap wxButton::GetBitmapFocus (  )  const

Returns the bitmap for the focused state, which may be invalid.

See also:
SetBitmapFocus()
Since:
2.9.1 (available in wxBitmapButton only in previous versions)
wxBitmap wxButton::GetBitmapLabel (  )  const

Returns the bitmap for the normal state.

This is exactly the same as GetBitmap() but uses a name backwards-compatible with wxBitmapButton.

See also:
SetBitmap(), SetBitmapLabel()
Since:
2.9.1 (available in wxBitmapButton only in previous versions)
wxBitmap wxButton::GetBitmapPressed (  )  const

Returns the bitmap for the pressed state, which may be invalid.

See also:
SetBitmapPressed()
Since:
2.9.1 (available as wxBitmapButton::GetBitmapSelected() in previous versions)
static wxSize wxButton::GetDefaultSize (  )  [static]

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 current font dependent size) which should be the best suited for this.

wxString wxButton::GetLabel (  )  const [virtual]

Returns the string label for the button.

See also:
SetLabel()

Reimplemented from wxControl.

void wxButton::SetBitmap ( const wxBitmap bitmap,
wxDirection  dir = wxLEFT 
)

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.

Parameters:
bitmap The bitmap to display in the button. May be invalid to remove any currently displayed bitmap.
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 also:
SetBitmapPosition(), SetBitmapMargins()
Since:
2.9.1
void wxButton::SetBitmapCurrent ( const wxBitmap bitmap  ) 

Sets the bitmap to be shown when the mouse is over the button.

See also:
GetBitmapCurrent()
Since:
2.9.1 (available as wxBitmapButton::SetBitmapHover() in previous versions)
void wxButton::SetBitmapDisabled ( const wxBitmap bitmap  ) 

Sets the bitmap for the disabled button appearance.

See also:
GetBitmapDisabled(), SetBitmapLabel(), SetBitmapPressed(), SetBitmapFocus()
Since:
2.9.1 (available in wxBitmapButton only in previous versions)
void wxButton::SetBitmapFocus ( const wxBitmap bitmap  ) 

Sets the bitmap for the button appearance when it has the keyboard focus.

See also:
GetBitmapFocus(), SetBitmapLabel(), SetBitmapPressed(), SetBitmapDisabled()
Since:
2.9.1 (available in wxBitmapButton only in previous versions)
void wxButton::SetBitmapLabel ( 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 also:
SetBitmap(), GetBitmapLabel()
Since:
2.9.1 (available in wxBitmapButton only in previous versions)
void wxButton::SetBitmapMargins ( const wxSize sz  ) 

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 also:
SetBitmap(), SetBitmapPosition()
Since:
2.9.1
void wxButton::SetBitmapMargins ( wxCoord  x,
wxCoord  y 
)

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 also:
SetBitmap(), SetBitmapPosition()
Since:
2.9.1
void wxButton::SetBitmapPosition ( wxDirection  dir  ) 

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
Parameters:
dir Direction in which the bitmap should be positioned, one of wxLEFT, wxRIGHT, wxTOP or wxBOTTOM.
void wxButton::SetBitmapPressed ( const wxBitmap bitmap  ) 

Sets the bitmap for the selected (depressed) button appearance.

Since:
2.9.1 (available as wxBitmapButton::SetBitmapSelected() in previous versions)
virtual wxWindow* wxButton::SetDefault (  )  [virtual]

This sets the button to be the default item in its top-level window (e.g.

the panel or the dialog box containing it).

As normal, pressing return causes the default button to be depressed when the return key is pressed.

See also wxWindow::SetFocus() which sets the keyboard focus for windows and text panel items, and wxTopLevelWindow::SetDefaultItem().

Remarks:
Under Windows, only dialog box buttons respond to this function.
Returns:
the old default item (possibly NULL)
void wxButton::SetLabel ( const wxString label  )  [virtual]

Sets the string label for the button.

Parameters:
label The label to set.

Reimplemented from wxControl.

 All Classes Files Functions Variables Typedefs Enumerations Enumerator Friends Defines



wxWidgets logo

[ top ]