GtkToolButton

GtkToolButton — A GtkToolItem subclass that displays buttons

Properties

char * icon-name Read / Write
GtkWidget * icon-widget Read / Write
char * label Read / Write
GtkWidget * label-widget Read / Write
char * stock-id Read / Write
gboolean use-underline Read / Write

Style Properties

int icon-spacing Read / Write

Signals

void clicked Action

Types and Values

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkWidget
            ╰── GtkContainer
                ╰── GtkBin
                    ╰── GtkToolItem
                        ╰── GtkToolButton
                            ├── GtkMenuToolButton
                            ╰── GtkToggleToolButton

Implemented Interfaces

GtkToolButton implements AtkImplementorIface, GtkBuildable, GtkActivatable and GtkActionable.

Includes

#include <gtk/gtk.h>

Description

GtkToolButtons are GtkToolItems containing buttons.

Use gtk_tool_button_new() to create a new GtkToolButton.

The label of a GtkToolButton is determined by the properties “label-widget”, “label”, and “stock-id”. If “label-widget” is non-NULL, then that widget is used as the label. Otherwise, if “label” is non-NULL, that string is used as the label. Otherwise, if “stock-id” is non-NULL, the label is determined by the stock item. Otherwise, the button does not have a label.

The icon of a GtkToolButton is determined by the properties “icon-widget” and “stock-id”. If “icon-widget” is non-NULL, then that widget is used as the icon. Otherwise, if “stock-id” is non-NULL, the icon is determined by the stock item. Otherwise, the button does not have a icon.

CSS nodes

GtkToolButton has a single CSS node with name toolbutton.

Functions

gtk_tool_button_new ()

GtkToolItem *
gtk_tool_button_new (GtkWidget *icon_widget,
                     const gchar *label);

Creates a new GtkToolButton using icon_widget as contents and label as label.

Parameters

label

a string that will be used as label, or NULL.

[allow-none]

icon_widget

a widget that will be used as the button contents, or NULL.

[allow-none]

Returns

A new GtkToolButton

Since: 2.4

gtk_tool_button_new_from_stock ()

GtkToolItem *
gtk_tool_button_new_from_stock (const gchar *stock_id);

gtk_tool_button_new_from_stock has been deprecated since version 3.10 and should not be used in newly-written code.

Use gtk_tool_button_new() together with gtk_image_new_from_icon_name() instead.

Creates a new GtkToolButton containing the image and text from a stock item. Some stock ids have preprocessor macros like GTK_STOCK_OK and GTK_STOCK_APPLY.

It is an error if stock_id is not a name of a stock item.

Parameters

stock_id

the name of the stock item

Returns

A new GtkToolButton

Since: 2.4

gtk_tool_button_set_label ()

void
gtk_tool_button_set_label (GtkToolButton *button,
                           const gchar *label);

Sets label as the label used for the tool button. The “label” property only has an effect if not overridden by a non-NULL “label-widget” property. If both the “label-widget” and “label” properties are NULL, the label is determined by the “stock-id” property. If the “stock-id” property is also NULL, button will not have a label.

Parameters

button

a GtkToolButton

label

a string that will be used as label, or NULL.

[allow-none]

Since: 2.4

gtk_tool_button_get_label ()

const gchar *
gtk_tool_button_get_label (GtkToolButton *button);

Returns the label used by the tool button, or NULL if the tool button doesn’t have a label. or uses a the label from a stock item. The returned string is owned by GTK+, and must not be modified or freed.

Parameters

button

a GtkToolButton

Returns

The label, or NULL.

[nullable]

Since: 2.4

gtk_tool_button_set_use_underline ()

void
gtk_tool_button_set_use_underline (GtkToolButton *button,
                                   gboolean use_underline);

If set, an underline in the label property indicates that the next character should be used for the mnemonic accelerator key in the overflow menu. For example, if the label property is “_Open” and use_underline is TRUE, the label on the tool button will be “Open” and the item on the overflow menu will have an underlined “O”.

Labels shown on tool buttons never have mnemonics on them; this property only affects the menu item on the overflow menu.

Parameters

button

a GtkToolButton

use_underline

whether the button label has the form “_Open”

Since: 2.4

gtk_tool_button_get_use_underline ()

gboolean
gtk_tool_button_get_use_underline (GtkToolButton *button);

Returns whether underscores in the label property are used as mnemonics on menu items on the overflow menu. See gtk_tool_button_set_use_underline().

Parameters

button

a GtkToolButton

Returns

TRUE if underscores in the label property are used as mnemonics on menu items on the overflow menu.

Since: 2.4

gtk_tool_button_set_stock_id ()

void
gtk_tool_button_set_stock_id (GtkToolButton *button,
                              const gchar *stock_id);

gtk_tool_button_set_stock_id has been deprecated since version 3.10 and should not be used in newly-written code.

Use gtk_tool_button_set_icon_name() instead.

Sets the name of the stock item. See gtk_tool_button_new_from_stock(). The stock_id property only has an effect if not overridden by non-NULL “label-widget” and “icon-widget” properties.

Parameters

button

a GtkToolButton

stock_id

a name of a stock item, or NULL.

[allow-none]

Since: 2.4

gtk_tool_button_get_stock_id ()

const gchar *
gtk_tool_button_get_stock_id (GtkToolButton *button);

gtk_tool_button_get_stock_id has been deprecated since version 3.10 and should not be used in newly-written code.

Use gtk_tool_button_get_icon_name() instead.

Returns the name of the stock item. See gtk_tool_button_set_stock_id(). The returned string is owned by GTK+ and must not be freed or modifed.

Parameters

button

a GtkToolButton

Returns

the name of the stock item for button .

Since: 2.4

gtk_tool_button_set_icon_name ()

void
gtk_tool_button_set_icon_name (GtkToolButton *button,
                               const gchar *icon_name);

Sets the icon for the tool button from a named themed icon. See the docs for GtkIconTheme for more details. The “icon-name” property only has an effect if not overridden by non-NULL “label-widget”, “icon-widget” and “stock-id” properties.

Parameters

button

a GtkToolButton

icon_name

the name of the themed icon.

[allow-none]

Since: 2.8

gtk_tool_button_get_icon_name ()

const gchar *
gtk_tool_button_get_icon_name (GtkToolButton *button);

Returns the name of the themed icon for the tool button, see gtk_tool_button_set_icon_name().

Parameters

button

a GtkToolButton

Returns

the icon name or NULL if the tool button has no themed icon.

[nullable]

Since: 2.8

gtk_tool_button_set_icon_widget ()

void
gtk_tool_button_set_icon_widget (GtkToolButton *button,
                                 GtkWidget *icon_widget);

Sets icon as the widget used as icon on button . If icon_widget is NULL the icon is determined by the “stock-id” property. If the “stock-id” property is also NULL, button will not have an icon.

Parameters

button

a GtkToolButton

icon_widget

the widget used as icon, or NULL.

[allow-none]

Since: 2.4

gtk_tool_button_get_icon_widget ()

GtkWidget *
gtk_tool_button_get_icon_widget (GtkToolButton *button);

Return the widget used as icon widget on button . See gtk_tool_button_set_icon_widget().

Parameters

button

a GtkToolButton

Returns

The widget used as icon on button , or NULL.

[nullable][transfer none]

Since: 2.4

gtk_tool_button_set_label_widget ()

void
gtk_tool_button_set_label_widget (GtkToolButton *button,
                                  GtkWidget *label_widget);

Sets label_widget as the widget that will be used as the label for button . If label_widget is NULL the “label” property is used as label. If “label” is also NULL, the label in the stock item determined by the “stock-id” property is used as label. If “stock-id” is also NULL, button does not have a label.

Parameters

button

a GtkToolButton

label_widget

the widget used as label, or NULL.

[allow-none]

Since: 2.4

gtk_tool_button_get_label_widget ()

GtkWidget *
gtk_tool_button_get_label_widget (GtkToolButton *button);

Returns the widget used as label on button . See gtk_tool_button_set_label_widget().

Parameters

button

a GtkToolButton

Returns

The widget used as label on button , or NULL.

[nullable][transfer none]

Since: 2.4

Types and Values

struct GtkToolButton

struct GtkToolButton;

struct GtkToolButtonClass

struct GtkToolButtonClass {
  GtkToolItemClass parent_class;

  GType button_type;

  /* signal */
  void       (* clicked)             (GtkToolButton    *tool_item);
};

Members

GType button_type;

clicked ()

Signal emitted when the tool button is clicked with the mouse or activated with the keyboard.

Property Details

The “icon-name” property

  “icon-name”                char *

The name of the themed icon displayed on the item. This property only has an effect if not overridden by “label-widget”, “icon-widget” or “stock-id” properties.

Owner: GtkToolButton

Flags: Read / Write

Default value: NULL

Since: 2.8

The “icon-widget” property

  “icon-widget”              GtkWidget *

Icon widget to display in the item.

Owner: GtkToolButton

Flags: Read / Write

The “label” property

  “label”                    char *

Text to show in the item.

Owner: GtkToolButton

Flags: Read / Write

Default value: NULL

The “label-widget” property

  “label-widget”             GtkWidget *

Widget to use as the item label.

Owner: GtkToolButton

Flags: Read / Write

The “stock-id” property

  “stock-id”                 char *

The stock icon displayed on the item.

GtkToolButton:stock-id has been deprecated since version 3.10 and should not be used in newly-written code.

Use “icon-name” instead.

Owner: GtkToolButton

Flags: Read / Write

Default value: NULL

The “use-underline” property

  “use-underline”            gboolean

If set, an underline in the label property indicates that the next character should be used for the mnemonic accelerator key in the overflow menu.

Owner: GtkToolButton

Flags: Read / Write

Default value: FALSE

Style Property Details

The “icon-spacing” style property

  “icon-spacing”             int

Spacing in pixels between the icon and label.

Owner: GtkToolButton

Flags: Read / Write

Allowed values: >= 0

Default value: 3

Signal Details

The “clicked” signal

void
user_function (GtkToolButton *toolbutton,
               gpointer       user_data)

This signal is emitted when the tool button is clicked with the mouse or activated with the keyboard.

Parameters

toolbutton

the object that emitted the signal

user_data

user data set when the signal handler was connected.

Flags: Action

© 2005–2020 The GNOME Project
Licensed under the GNU Lesser General Public License version 2.1 or later.
https://developer.gnome.org/gtk3/3.24/GtkToolButton.html