gtkmm  3.3.20
Public Member Functions | Protected Member Functions | Related Functions
Gtk::Button Class Reference

A widget that creates a signal when clicked on. More...

Inheritance diagram for Gtk::Button:
Inheritance graph
[legend]

List of all members.

Public Member Functions

virtual ~Button ()
GtkButton* gobj ()
 Provides access to the underlying C GtkObject.
const GtkButton* gobj () const
 Provides access to the underlying C GtkObject.
 Button ()
 Create an empty button.
 Button (const Glib::ustring& label, bool mnemonic=false)
 Simple Push Button with label.
 Button (const StockID& stock_id)
 Creates a new Button containing the image and text from a stock item.
void clicked ()
 Emits a Gtk::Button::signal_clicked() signal to the given Gtk::Button.
void set_relief (ReliefStyle newstyle)
 Sets the relief style of the edges of the given Gtk::Button widget.
ReliefStyle get_relief () const
 Returns the current relief style of the given Gtk::Button.
void set_label (const Glib::ustring& label)
 Sets the text of the label of the button to str.
Glib::ustring get_label () const
 Fetches the text from the label of the button, as set by set_label().
void set_use_underline (bool use_underline=true)
 If true, an underline in the text of the button label indicates the next character should be used for the mnemonic accelerator key.
bool get_use_underline () const
 Returns whether an embedded underline in the button label indicates a mnemonic.
void set_use_stock (bool use_stock=true)
 If true, the label set on the button is used as a stock id to select the stock item for the button.
bool get_use_stock () const
 Returns whether the button label is a stock item.
void set_focus_on_click (bool focus_on_click=true)
 Sets whether the button will grab focus when it is clicked with the mouse.
bool get_focus_on_click () const
 Returns whether the button grabs focus when it is clicked with the mouse.
void set_alignment (float xalign, float yalign)
 Sets the alignment of the child.
void get_alignment (float& xalign, float& yalign)
 Gets the alignment of the child in the button.
void set_image (Widget& image)
 Set the image of button to the given widget.
Widgetget_image ()
 Gets the widget that is currenty set as the image of button.
const Widgetget_image () const
 Gets the widget that is currenty set as the image of button.
void set_image_position (PositionType position)
 Sets the position of the image relative to the text inside the button.
PositionType get_image_position () const
 Gets the position of the image relative to the text inside the button.
Glib::RefPtr< Gdk::Windowget_event_window ()
 Returns the button's event window if it is realized, 0 otherwise.
Glib::RefPtr< const Gdk::Windowget_event_window () const
 Returns the button's event window if it is realized, 0 otherwise.
Glib::SignalProxy0< void > signal_pressed ()
Glib::SignalProxy0< void > signal_released ()
Glib::SignalProxy0< void > signal_clicked ()
Glib::SignalProxy0< void > signal_enter ()
Glib::SignalProxy0< void > signal_leave ()
Glib::SignalProxy0< void > signal_activate ()
Glib::PropertyProxy
< Glib::ustring
property_label ()
 Text of the label widget inside the button, if the button contains a label widget.
Glib::PropertyProxy_ReadOnly
< Glib::ustring
property_label () const
 Text of the label widget inside the button, if the button contains a label widget.
Glib::PropertyProxy< ReliefStyleproperty_relief ()
 The border relief style.
Glib::PropertyProxy_ReadOnly
< ReliefStyle
property_relief () const
 The border relief style.
Glib::PropertyProxy< bool > property_use_underline ()
 If set, an underline in the text indicates the next character should be used for the mnemonic accelerator key.
Glib::PropertyProxy_ReadOnly
< bool > 
property_use_underline () const
 If set, an underline in the text indicates the next character should be used for the mnemonic accelerator key.
Glib::PropertyProxy< bool > property_use_stock ()
 If set, the label is used to pick a stock item instead of being displayed.
Glib::PropertyProxy_ReadOnly
< bool > 
property_use_stock () const
 If set, the label is used to pick a stock item instead of being displayed.
Glib::PropertyProxy< bool > property_focus_on_click ()
 Whether the button grabs focus when it is clicked with the mouse.
Glib::PropertyProxy_ReadOnly
< bool > 
property_focus_on_click () const
 Whether the button grabs focus when it is clicked with the mouse.
Glib::PropertyProxy< float > property_xalign ()
 Horizontal position of child in available space.
Glib::PropertyProxy_ReadOnly
< float > 
property_xalign () const
 Horizontal position of child in available space.
Glib::PropertyProxy< float > property_yalign ()
 Vertical position of child in available space.
Glib::PropertyProxy_ReadOnly
< float > 
property_yalign () const
 Vertical position of child in available space.
Glib::PropertyProxy
< Gtk::Widget* > 
property_image ()
 Child widget to appear next to the button text.
Glib::PropertyProxy_ReadOnly
< Gtk::Widget* > 
property_image () const
 Child widget to appear next to the button text.
Glib::PropertyProxy< PositionTypeproperty_image_position ()
 The position of the image relative to the text.
Glib::PropertyProxy_ReadOnly
< PositionType
property_image_position () const
 The position of the image relative to the text.

Protected Member Functions

virtual void on_pressed ()
 This is a default handler for the signal signal_pressed().
virtual void on_released ()
 This is a default handler for the signal signal_released().
virtual void on_clicked ()
 This is a default handler for the signal signal_clicked().
virtual void on_enter ()
 This is a default handler for the signal signal_enter().
virtual void on_leave ()
 This is a default handler for the signal signal_leave().
virtual void on_activate ()
 This is a default handler for the signal signal_activate().

Related Functions

(Note that these are not member functions.)

Gtk::Buttonwrap (GtkButton* object, bool take_copy=false)
 A Glib::wrap() method for this object.

Detailed Description

A widget that creates a signal when clicked on.

This widget is generally used with a signal handler that is called when the button is pressed. It can hold any valid child widget. The most commonly used child is the Gtk::Label.

The Button widget looks like this:

button2.png

Constructor & Destructor Documentation

virtual Gtk::Button::~Button ( ) [virtual]

Create an empty button.

With an empty button, you can Gtk::Button::add() a widget such as a Gtk::Image or Gtk::Box.

If you just wish to add a Gtk::Label, you may want to use the Gtk::Button(const Glib::ustring& label) ctor directly instead.

Gtk::Button::Button ( const Glib::ustring label,
bool  mnemonic = false 
) [explicit]

Simple Push Button with label.

Create a button with the given label inside. You won't be able to add a widget in this button since it already has a Gtk::Label in it

Gtk::Button::Button ( const StockID stock_id) [explicit]

Creates a new Button containing the image and text from a stock item.

Stock ids have identifiers like Gtk::Stock::OK and Gtk::Stock::APPLY.

Parameters:
stock_idThe stock item.

Member Function Documentation

Emits a Gtk::Button::signal_clicked() signal to the given Gtk::Button.

void Gtk::Button::get_alignment ( float &  xalign,
float &  yalign 
)

Gets the alignment of the child in the button.

Since gtkmm 2.4:
Parameters:
xalignReturn location for horizontal alignment.
yalignReturn location for vertical alignment.

Returns the button's event window if it is realized, 0 otherwise.

This function should be rarely needed.

Since gtkmm 2.22:
Returns:
button's event window.

Returns the button's event window if it is realized, 0 otherwise.

This function should be rarely needed.

Since gtkmm 2.22:
Returns:
button's event window.

Returns whether the button grabs focus when it is clicked with the mouse.

See set_focus_on_click().

Since gtkmm 2.4:
Returns:
true if the button grabs focus when it is clicked with the mouse.

Gets the widget that is currenty set as the image of button.

This may have been explicitly set by set_image() or specified as a stock item to the constructor.

Since gtkmm 2.6:
const Widget* Gtk::Button::get_image ( ) const

Gets the widget that is currenty set as the image of button.

This may have been explicitly set by set_image() or specified as a stock item to the constructor.

Since gtkmm 2.6:

Gets the position of the image relative to the text inside the button.

Since gtkmm 2.10:
Returns:
The position.

Fetches the text from the label of the button, as set by set_label().

If the label text has not been set the return value will be 0. This will be the case if you create an empty button with new() to use as a container.

Returns:
The text of the label widget. This string is owned by the widget and must not be modified or freed.

Returns the current relief style of the given Gtk::Button.

Returns:
The current Gtk::ReliefStyle.

Returns whether the button label is a stock item.

Returns:
true if the button label is used to select a stock item instead of being used directly as the label text.

Returns whether an embedded underline in the button label indicates a mnemonic.

See set_use_underline().

Returns:
true if an embedded underline in the button label indicates the mnemonic accelerator keys.
GtkButton* Gtk::Button::gobj ( ) [inline]

Provides access to the underlying C GtkObject.

Reimplemented from Gtk::Activatable.

Reimplemented in Gtk::LinkButton, Gtk::ScaleButton, Gtk::ColorButton, Gtk::FontButton, Gtk::CheckButton, Gtk::RadioButton, Gtk::VolumeButton, and Gtk::ToggleButton.

const GtkButton* Gtk::Button::gobj ( ) const [inline]

Provides access to the underlying C GtkObject.

Reimplemented from Gtk::Activatable.

Reimplemented in Gtk::LinkButton, Gtk::ScaleButton, Gtk::ColorButton, Gtk::FontButton, Gtk::CheckButton, Gtk::RadioButton, Gtk::VolumeButton, and Gtk::ToggleButton.

virtual void Gtk::Button::on_activate ( ) [protected, virtual]

This is a default handler for the signal signal_activate().

virtual void Gtk::Button::on_clicked ( ) [protected, virtual]

This is a default handler for the signal signal_clicked().

virtual void Gtk::Button::on_enter ( ) [protected, virtual]

This is a default handler for the signal signal_enter().

virtual void Gtk::Button::on_leave ( ) [protected, virtual]

This is a default handler for the signal signal_leave().

virtual void Gtk::Button::on_pressed ( ) [protected, virtual]

This is a default handler for the signal signal_pressed().

virtual void Gtk::Button::on_released ( ) [protected, virtual]

This is a default handler for the signal signal_released().

Whether the button grabs focus when it is clicked with the mouse.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Whether the button grabs focus when it is clicked with the mouse.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Child widget to appear next to the button text.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Child widget to appear next to the button text.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

The position of the image relative to the text.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

The position of the image relative to the text.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Text of the label widget inside the button, if the button contains a label widget.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Text of the label widget inside the button, if the button contains a label widget.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

The border relief style.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

The border relief style.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

If set, the label is used to pick a stock item instead of being displayed.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

If set, the label is used to pick a stock item instead of being displayed.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

If set, an underline in the text indicates the next character should be used for the mnemonic accelerator key.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

If set, an underline in the text indicates the next character should be used for the mnemonic accelerator key.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Horizontal position of child in available space.

0.0 is left aligned, 1.0 is right aligned.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Horizontal position of child in available space.

0.0 is left aligned, 1.0 is right aligned.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Vertical position of child in available space.

0.0 is top aligned, 1.0 is bottom aligned.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Vertical position of child in available space.

0.0 is top aligned, 1.0 is bottom aligned.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.
void Gtk::Button::set_alignment ( float  xalign,
float  yalign 
)

Sets the alignment of the child.

This property has no effect unless the child is a Gtk::Misc or a Gtk::Alignment.

Since gtkmm 2.4:
Parameters:
xalignThe horizontal position of the child, 0.0 is left aligned, 1.0 is right aligned.
yalignThe vertical position of the child, 0.0 is top aligned, 1.0 is bottom aligned.
void Gtk::Button::set_focus_on_click ( bool  focus_on_click = true)

Sets whether the button will grab focus when it is clicked with the mouse.

Making mouse clicks not grab focus is useful in places like toolbars where you don't want the keyboard focus removed from the main area of the application.

Since gtkmm 2.4:
Parameters:
focus_on_clickWhether the button grabs focus when clicked with the mouse.
void Gtk::Button::set_image ( Widget image)

Set the image of button to the given widget.

Note that it depends on the Gtk::Settings::property_gtk_button_images() setting whether the image will be displayed or not, you don't have to call Gtk::Widget::show() on image yourself.

Since gtkmm 2.6:
Parameters:
imageA widget to set as the image for the button.

Sets the position of the image relative to the text inside the button.

Since gtkmm 2.10:
Parameters:
positionThe position.
void Gtk::Button::set_label ( const Glib::ustring label)

Sets the text of the label of the button to str.

This text is also used to select the stock item if set_use_stock() is used.

This will also clear any previously set labels.

Parameters:
labelA string.

Sets the relief style of the edges of the given Gtk::Button widget.

Three styles exist, GTK_RELIEF_NORMAL, GTK_RELIEF_HALF, GTK_RELIEF_NONE. The default style is, as one can guess, GTK_RELIEF_NORMAL.

Parameters:
newstyleThe GtkReliefStyle as described above.
void Gtk::Button::set_use_stock ( bool  use_stock = true)

If true, the label set on the button is used as a stock id to select the stock item for the button.

Parameters:
use_stocktrue if the button should use a stock item.
void Gtk::Button::set_use_underline ( bool  use_underline = true)

If true, an underline in the text of the button label indicates the next character should be used for the mnemonic accelerator key.

Parameters:
use_underlinetrue if underlines in the text indicate mnemonics.
Slot Prototype:
void on_my_activate()

The signal_activate() signal on GtkButton is an action signal and emitting it causes the button to animate press then release. Applications should never connect to this signal, but use the Gtk::Button::signal_clicked() signal.

Deprecated:
Use signal_clicked() instead.
Slot Prototype:
void on_my_clicked()

Emitted when the button has been activated (pressed and released).

Slot Prototype:
void on_my_enter()

Emitted when the pointer enters the button.

Deprecated: 2.8: Use the Gtk::Widget::signal_enter_notify_event() signal.

Deprecated:
Use Widget::signal_enter_notify_event() instead.
Slot Prototype:
void on_my_leave()

Emitted when the pointer leaves the button.

Deprecated: 2.8: Use the Gtk::Widget::signal_leave_notify_event() signal.

Deprecated:
Use Widget::signal_leave_notify_event() instead.
Slot Prototype:
void on_my_pressed()

Emitted when the button is pressed.

Deprecated: 2.8: Use the Gtk::Widget::signal_button_press_event() signal.

Deprecated:
Use Widget::signal_button_press_event() instead.
Slot Prototype:
void on_my_released()

Emitted when the button is released.

Deprecated: 2.8: Use the Gtk::Widget::signal_button_release_event() signal.

Deprecated:
Use Widget::signal_button_release_event() instead.

Friends And Related Function Documentation

Gtk::Button* wrap ( GtkButton *  object,
bool  take_copy = false 
) [related]

A Glib::wrap() method for this object.

Parameters:
objectThe C instance.
take_copyFalse if the result should take ownership of the C instance. True if it should take a new copy or ref.
Returns:
A C++ instance that wraps this C instance.

The documentation for this class was generated from the following file: