Xfce Foundation Classes
Main Page | Index | Namespace List | Alphabetical List | Class List | File List

# Xfc::Gtk::Button Class Reference

A GtkButton C++ wrapper class. More...

`#include <xfc/gtk/button.hh>`

Inheritance diagram for Xfc::Gtk::Button:

List of all members.

## Signal Prototypes

- const PressedSignalType pressed_signal
    Pressed signal (see signal_pressed()).
- const ReleasedSignalType released_signal
    Released signal (see signal_released()).
- const ClickedSignalType clicked_signal
    Clicked signal (see signal_clicked()).
- const EnterSignalType enter_signal
    Enter signal (see signal_enter()).
- const LeaveSignalType leave_signal
    Leave signal (see signal_leave()).
- const ActivateSignalType activate_signal
    Activate signal (see signal_activate()).

## Public Member Functions

Constructors

- Button ()
    Constructs an empty Button widget.
- Button (Widget &image)
    Constructs a Button widget that contains an Image.
- Button (const String &label, bool use_underline=false)
    Constructs a Button widget with a Label child containing the given label.
- Button (Widget &image, const String &label, bool use_underline=false)
    Constructs a Button widget that contains an image and a label.
- Button (const StockId &stock_id)
    Constructs a new Button containing the image and text from a stock item.
- virtual ~Button ()
    Destructor.

Accessors

- GtkButton * gtk_button () const
    Get a pointer to the GtkButton structure.
- operator GtkButton * () const
    Conversion operator; safely converts a Button to a GtkButton pointer.
- ReliefStyle get_relief () const
    Returns the current relief style of the Button.
- String get_label () const
    Fetches the text from the label of the button, as set by set_label().
- bool get_use_underline () const
    Returns true if an embedded underline in the button label indicates a mnemonic (see set_use_underline()).
- bool get_use_stock () const
    Returns whether the button label is a stock item.
- bool get_focus_on_click () const
    Determines whether the button grabs focus when it is clicked with the mouse.
- void get_alignment (float *xalign, float *yalign)
    Gets the alignment of the child in the button.
- Widget * get_image () const
    Gets the widget that is currenty set as the image of the button.

Methods

- void pressed ()
    Emits a Button::pressed_signal to the calling Button.
- void released ()
    Emits a Button::released_signal to the calling Button.
- void clicked ()
    Emits a Button::clicked_signal to the calling Button.
- void enter ()
    Emits a Button::enter_signal to the calling Button.
- void leave ()
    Emits a Button::leave_signal to the calling Button.
- void set_relief (ReliefStyle newstyle)
    Sets the relief style of the edges of the Button.
- void set_label (const String &label)
    Sets the text of the label of the button to label.
- void set_stock_id (const StockId &stock_id)
    Sets the button image and text from a stock item.
- void set_use_underline (bool use_underline)
    Sets whether an underline in the text of the button label indicates the next character should be used for the mnemonic accelerator key.
- void set_use_stock (bool use_stock)
    Sets whether the label set on the button is used as a stock id to select the stock item for the button.
- void set_image (Widget &image)
    Set the image of the button to the given widget.
- void set_image (Widget &image, const String &label, bool use_underline=false)
    Set the image of the button to the given widget, and the label to label.
- void set_focus_on_click (bool focus_on_click)
    Sets whether the button will grab focus when it is clicked with the mouse.
- void set_alignment (float xalign, float yalign)
    Sets the alignment of the child.

Signal Proxies

- const PressedSignalProxy signal_pressed ()
    Connect to the pressed_signal; emitted when the button is initially pressed.
- const ReleasedSignalProxy signal_released ()
    Connect to the released_signal; emitted when a button which is pressed is released, no matter where the mouse cursor is.
- const ClickedSignalProxy signal_clicked ()
    Connect to the clicked_signal; emitted when a button clicked on by the mouse and the cursor stays on the button.
- const EnterSignalProxy signal_enter ()
    Connect to the enter_signal; emitted when the mouse cursor enters the region of the button.
- const LeaveSignalProxy signal_leave ()
    Connect to the leave_signal; emitted when the mouse cursor leaves the region of the button.
- const ActivateSignalProxy signal_activate ()
    Connect to the activate_signal; emitted when the button is activated.

## Protected Member Functions

Constructors

- Button (GtkButton *button, bool owns_reference=false)
    Construct a new Button from an existing GtkButton.

## Detailed Description

A GtkButton C++ wrapper class.

The Button widget is generally used to attach a function to that is called when the button is pressed. The Button widget can hold any valid child widget. That is it can hold most any other standard Widget. The most commonly used child is the Label.

See also: the Button Widget HOWTOs and examples.

## Constructor & Destructor Documentation

Xfc::Gtk::Button::Button | ( | GtkButton * | button,
|  | bool | owns_reference = `false`
| ) | `[explicit, protected]`

Construct a new Button from an existing GtkButton.

Parameters:

  | button | A pointer to a GtkButton.
  | owns_reference | Set false if the initial reference count is floating, set true if it's not.

The button can be a newly created GtkButton or an existing GtkButton. (see G::Object::Object).

Xfc::Gtk::Button::Button | ( | Widget & | image | ) | `[explicit]`

Constructs a Button widget that contains an Image.

Parameters:

  | image | The image you want the Button to contain.

Xfc::Gtk::Button::Button | ( | const String & | label,
|  | bool | use_underline = `false`
| ) | `[explicit]`

Constructs a Button widget with a Label child containing the given label.

Parameters:

  | label | The text you want the Label to hold.
  | use_underline | Set true if label contains a mnemonic character.

If characters in label are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use '__' (two underscores). The first underlined character represents a keyboard accelerator called a mnemonic. Pressing Alt and that key activates the button.

Xfc::Gtk::Button::Button | ( | Widget & | image,
|  | const String & | label,
|  | bool | use_underline = `false`
| ) |

Constructs a Button widget that contains an image and a label.

Parameters:

  | image | The image widget you want the button to display.
  | label | The text you want the button to display.
  | use_underline | Set true if an underline in the label indicates a mnemonic.

This constructor lets you display an image and a label inside a button, like a toolbar button does. If horizontal is true the label is displayed beside the image. If horizontal is false the label is displayed underneath the image.

Xfc::Gtk::Button::Button | ( | const StockId & | stock_id | ) | `[explicit]`

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

Parameters:

  | stock_id | The stock ID for a stock item.

Some stock IDs are pre-registered like Gtk::StockId::OK and Gtk::StockId::APPLY. If stock_id is unknown, then it will be treated as a mnemonic label.

## Member Function Documentation

void Xfc::Gtk::Button::get_alignment | ( | float * | xalign,
|  | float * | yalign
| ) |

Gets the alignment of the child in the button.

Parameters:

  | xalign | The return location for horizontal alignment.
  | yalign | The return location for vertical alignment.

bool Xfc::Gtk::Button::get_focus_on_click | ( |  | ) | const

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

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

Widget* Xfc::Gtk::Button::get_image | ( |  | ) | const

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

Returns:
  The image widget.

This may have been explicitly set by set_image() or constructed from as stock image.

String Xfc::Gtk::Button::get_label | ( |  | ) | const

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

Returns:
  The text of the label widget.

If the label text has not been set the return value will be a null String. This will be the case if you create an empty button to use as a container.

bool Xfc::Gtk::Button::get_use_stock | ( |  | ) | const

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.

void Xfc::Gtk::Button::set_alignment | ( | float | xalign,
|  | float | yalign
| ) |

Sets the alignment of the child.

Parameters:

  | xalign | The horizontal position of the child, 0.0 is left aligned, 1.0 is right aligned.
  | yalign | The vertical position of the child, 0.0 is top aligned, 1.0 is bottom aligned.

This method has no effect unless the child is of type GTK_TYPE_MISC or GTK_TYPE_ALIGNMENT.

void Xfc::Gtk::Button::set_focus_on_click | ( | bool | focus_on_click | ) |

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

Parameters:

  | focus_on_click | Whether the button grabs the focus when 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.

void Xfc::Gtk::Button::set_image | ( | Widget & | image,
|  | const String & | label,
|  | bool | use_underline = `false`
| ) |

Set the image of the button to the given widget, and the label to label.

Parameters:

  | image | The Image you want the button to display.
  | label | The text you want the button to display.
  | use_underline | Set true if an underline in the label indicates a mnemonic.

void Xfc::Gtk::Button::set_image | ( | Widget & | image | ) |

Set the image of the button to the given widget.

Parameters:

  | image | The Image you want the button to display.

For this method to work the button label must be set first.

void Xfc::Gtk::Button::set_label | ( | const String & | label | ) |

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

Parameters:

  | label | A String.

This method will clear any previously set label. The text is also used to select the stock item if set_use_stock() is used.

void Xfc::Gtk::Button::set_relief | ( | ReliefStyle | newstyle | ) |

Sets the relief style of the edges of the Button.

Parameters:

  | newstyle | The ReliefStyle to set.

Three styles exist, RELIEF_NORMAL, RELIEF_HALF, RELIEF_NONE. The default style is, as one can guess, RELIEF_NORMAL.

void Xfc::Gtk::Button::set_stock_id | ( | const StockId & | stock_id | ) |

Sets the button image and text from a stock item.

Parameters:

  | stock_id | The stock ID for a stock item.

This is a convenience method for setting a stock item and is equivalent to calling set_label(), set_use_stock() and set_use_underline(). Some stock IDs are pre-registered like Gtk::StockId::OK and Gtk::StockId::APPLY. If stock_id is unknown, then it will be treated as a mnemonic label.

void Xfc::Gtk::Button::set_use_stock | ( | bool | use_stock | ) |

Sets whether the label set on the button is used as a stock id to select the stock item for the button.

Parameters:

  | use_stock | Set true if the button should use a stock item.

void Xfc::Gtk::Button::set_use_underline | ( | bool | use_underline | ) |

Sets whether an underline in the text of the button label indicates the next character should be used for the mnemonic accelerator key.

Parameters:

  | use_underline | Set true if an underline in the text indicates a mnemonic.

const ClickedSignalProxy Xfc::Gtk::Button::signal_clicked | ( |  | ) |

| Connect to the clicked_signal; emitted when a button clicked on by the mouse and the cursor stays on the button. If the cursor is not on the button when the mouse button is released, the signal is not emitted.

## Member Data Documentation

const ActivateSignalType Xfc::Gtk::Button::activate_signal `[static, protected]`

Activate signal (see signal_activate()).

Calls a slot with the signature:

                 void function();

const ClickedSignalType Xfc::Gtk::Button::clicked_signal `[static, protected]`

Clicked signal (see signal_clicked()).

Calls a slot with the signature:

                 void function();

const EnterSignalType Xfc::Gtk::Button::enter_signal `[static, protected]`

Enter signal (see signal_enter()).

Calls a slot with the signature:

                 void function();

const LeaveSignalType Xfc::Gtk::Button::leave_signal `[static, protected]`

Leave signal (see signal_leave()).

Calls a slot with the signature:

                 void function();

const PressedSignalType Xfc::Gtk::Button::pressed_signal `[static, protected]`

Pressed signal (see signal_pressed()).

Calls a slot with the signature:

                 void function();

const ReleasedSignalType Xfc::Gtk::Button::released_signal `[static, protected]`

Released signal (see signal_released()).

Calls a slot with the signature:

                 void function();

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

- button.hh

Xfce Foundation Classes

Copyright © 2004-2005 The XFC Development Team | XFC 4.3