Gtk.Action - Classes - Gtk 3.0 (original) (raw)

g GObject.GInterface GObject.GInterface Gtk.Buildable Gtk.Buildable GObject.GInterface->Gtk.Buildable GObject.Object GObject.Object Gtk.Action Gtk.Action GObject.Object->Gtk.Action Gtk.Buildable->Gtk.Action

Subclasses:

Gtk.RecentAction, Gtk.ToggleAction

Methods¶

Inherited:

GObject.Object (37), Gtk.Buildable (10)

Structs:

GObject.ObjectClass (5)

Virtual Methods¶

Inherited:

GObject.Object (7), Gtk.Buildable (10)

Properties¶

Signals¶

Inherited:

GObject.Object (1)

Fields¶

Inherited:

GObject.Object (1)

Class Details¶

class Gtk.Action(*args, **kwargs)¶

Bases:

GObject.Object, Gtk.Buildable

Abstract:

No

Structure:

Gtk.ActionClass

In GTK+ 3.10, Gtk.Action has been deprecated. Use Gio.Actioninstead, and associate actions with Gtk.Actionable widgets. UseGio.MenuModel for creating menus with Gtk.Menu.new_from_model().

Actions represent operations that the user can be perform, along with some information how it should be presented in the interface. Each action provides methods to create icons, menu items and toolbar items representing itself.

As well as the callback that is called when the action gets activated, the following also gets associated with the action:

• a name (not translated, for path lookup)
• a label (translated, for display)
• an accelerator
• whether label indicates a stock id
• a tooltip (optional, translated)
• a toolbar label (optional, shorter than label)

The action will also have some state information:

• visible (shown/hidden)
• sensitive (enabled/disabled)

Apart from regular actions, there are toggle actions, which can be toggled between two states andradio actions, of which only one in a group can be in the “active” state. Other actions can be implemented as Gtk.Actionsubclasses.

Each action can have one or more proxy widgets. To act as an action proxy, widget needs to implement Gtk.Activatable interface. Proxies mirror the state of the action and should change when the action’s state changes. Properties that are always mirrored by proxies are Gtk.Action :sensitive andGtk.Action :visible. Gtk.Action :gicon, Gtk.Action :icon-name, Gtk.Action :label,Gtk.Action :short-label and Gtk.Action :stock-id properties are only mirorred if proxy widget has Gtk.Activatable :use-action-appearance property set toTrue.

When the proxy is activated, it should activate its action.

classmethod new(name, label, tooltip, stock_id)[source]¶

Parameters:

• name (str) – A unique name for the action
• label (str or None) – the label displayed in menu items and on buttons, or None
• tooltip (str or None) – a tooltip for the action, or None
• stock_id (str or None) – the stock icon to display in widgets representing the action, or None

Returns:

a new Gtk.Action

Return type:

Gtk.Action

Creates a new Gtk.Action object. To add the action to aGtk.ActionGroup and set the accelerator for the action, call Gtk.ActionGroup.add_action_with_accel(). See the UI Definition section for information on allowed action names.

New in version 2.4.

activate()[source]¶

Emits the “activate” signal on the specified action, if it isn’t insensitive. This gets called by the proxy widgets when they get activated.

It can also be used to manually activate an action.

New in version 2.4.

block_activate()[source]¶

Disable activation signals from the action

This is needed when updating the state of your proxyGtk.Activatable widget could result in calling Gtk.Action.activate(), this is a convenience function to avoid recursing in those cases (updating toggle state for instance).

New in version 2.16.

connect_accelerator()[source]¶

Installs the accelerator for self if self has an accel path and group. See Gtk.Action.set_accel_path() andGtk.Action.set_accel_group()

Since multiple proxies may independently trigger the installation of the accelerator, the self counts the number of times this function has been called and doesn’t remove the accelerator untilGtk.Action.disconnect_accelerator() has been called as many times.

New in version 2.4.

Deprecated since version 3.10: Use Gio.Action and the accelerator group on an associated Gtk.Menu instead

create_icon(icon_size)[source]¶

Parameters:

icon_size (int) – the size of the icon (Gtk.IconSize) that should be created.

Returns:

a widget that displays the icon for this action.

Return type:

Gtk.Widget

This function is intended for use by action implementations to create icons displayed in the proxy widgets.

New in version 2.4.

Returns:

the menu item provided by the action, or None.

Return type:

Gtk.Widget

If self provides a Gtk.Menu widget as a submenu for the menu item or the toolbar item it creates, this function returns an instance of that menu.

New in version 2.12.

Returns:

a menu item connected to the action.

Return type:

Gtk.Widget

Creates a menu item widget that proxies for the given action.

New in version 2.4.

create_tool_item()[source]¶

Returns:

a toolbar item connected to the action.

Return type:

Gtk.Widget

Creates a toolbar item widget that proxies for the given action.

New in version 2.4.

disconnect_accelerator()[source]¶

Undoes the effect of one call to Gtk.Action.connect_accelerator().

New in version 2.4.

Deprecated since version 3.10: Use Gio.Action and the accelerator group on an associated Gtk.Menu instead

get_accel_closure()[source]¶

Returns:

the accel closure for this action. The returned closure is owned by GTK+ and must not be unreffed or modified.

Return type:

GObject.Closure

Returns the accel closure for this action.

New in version 2.8.

Deprecated since version 3.10: Use Gio.Action and Gtk.Menu instead, which have no equivalent for getting the accel closure

get_accel_path()[source]¶

Returns:

the accel path for this action, or Noneif none is set. The returned string is owned by GTK+ and must not be freed or modified.

Return type:

str

Returns the accel path for this action.

New in version 2.6.

Deprecated since version 3.10: Use Gio.Action and the accelerator path on an associated Gtk.Menu instead

get_always_show_image()[source]¶

Returns:

True if the menu item proxies will always show their image

Return type:

bool

Returns whether self's menu item proxies will always show their image, if available.

New in version 2.20.

get_gicon()[source]¶

Returns:

The action’s Gio.Icon if one is set.

Return type:

Gio.Icon

Gets the gicon of self.

New in version 2.16.

get_icon_name()[source]¶

Returns:

the icon name

Return type:

str

Gets the icon name of self.

New in version 2.16.

get_is_important()[source]¶

Returns:

whether self is important

Return type:

bool

Checks whether self is important or not

New in version 2.16.

Deprecated since version 3.10: Use Gio.Action instead, and control and monitor whether labels are shown directly

get_label()[source]¶

Returns:

the label text

Return type:

str

Gets the label text of self.

New in version 2.16.

get_name()[source]¶

Returns:

the name of the action. The string belongs to GTK+ and should not be freed.

Return type:

str

Returns the name of the action.

New in version 2.4.

get_proxies()[source]¶

Returns:

a GLib.SList of proxy widgets. The list is owned by GTK+ and must not be modified.

Return type:

[Gtk.Widget]

Returns the proxy widgets for an action. See also Gtk.Activatable.get_related_action().

New in version 2.4.

Deprecated since version 3.10.

get_sensitive()[source]¶

Returns:

True if the action itself is sensitive.

Return type:

bool

Returns whether the action itself is sensitive. Note that this doesn’t necessarily mean effective sensitivity. See Gtk.Action.is_sensitive() for that.

New in version 2.4.

get_short_label()[source]¶

Returns:

the short label text.

Return type:

str

Gets the short label text of self.

New in version 2.16.

Deprecated since version 3.10: Use Gio.Action instead, which has no equivalent of short labels

get_stock_id()[source]¶

Returns:

the stock id

Return type:

str

Gets the stock id of self.

New in version 2.16.

Deprecated since version 3.10: Use Gio.Action instead, which has no equivalent of stock items

get_tooltip()[source]¶

Returns:

the tooltip text

Return type:

str

Gets the tooltip text of self.

New in version 2.16.

get_visible()[source]¶

Returns:

True if the action itself is visible.

Return type:

bool

Returns whether the action itself is visible. Note that this doesn’t necessarily mean effective visibility. See Gtk.Action.is_sensitive() for that.

New in version 2.4.

Deprecated since version 3.10: Use Gio.Action instead, and control and monitor the state of Gtk.Actionable widgets directly

get_visible_horizontal()[source]¶

Returns:

whether self is visible when horizontal

Return type:

bool

Checks whether self is visible when horizontal

New in version 2.16.

Deprecated since version 3.10: Use Gio.Action instead, and control and monitor the visibility of associated widgets and menu items directly

get_visible_vertical()[source]¶

Returns:

whether self is visible when horizontal

Return type:

bool

Checks whether self is visible when horizontal

New in version 2.16.

Deprecated since version 3.10: Use Gio.Action instead, and control and monitor the visibility of associated widgets and menu items directly

is_sensitive()[source]¶

Returns:

True if the action and its associated action group are both sensitive.

Return type:

bool

Returns whether the action is effectively sensitive.

New in version 2.4.

is_visible()[source]¶

Returns:

True if the action and its associated action group are both visible.

Return type:

bool

Returns whether the action is effectively visible.

New in version 2.4.

Deprecated since version 3.10: Use Gio.Action instead, and control and monitor the state of Gtk.Actionable widgets directly

set_accel_group(accel_group)[source]¶

Parameters:

accel_group (Gtk.AccelGroup or None) – a Gtk.AccelGroup or None

Sets the Gtk.AccelGroup in which the accelerator for this action will be installed.

New in version 2.4.

Deprecated since version 3.10: Use Gio.Action and the accelerator group on an associated Gtk.Menu instead

set_accel_path(accel_path)[source]¶

Parameters:

accel_path (str) – the accelerator path

Sets the accel path for this action. All proxy widgets associated with the action will have this accel path, so that their accelerators are consistent.

Note that accel_path string will be stored in a #GQuark. Therefore, if you pass a static string, you can save some memory by interning it first withGLib.intern_static_string().

New in version 2.4.

Deprecated since version 3.10: Use Gio.Action and the accelerator path on an associated Gtk.Menu instead

set_always_show_image(always_show)[source]¶

Parameters:

always_show (bool) – True if menuitem proxies should always show their image

Sets whether self's menu item proxies will ignore theGtk.Settings :gtk-menu-images setting and always show their image, if available.

Use this if the menu item would be useless or hard to use without their image.

New in version 2.20.

set_gicon(icon)[source]¶

Parameters:

icon (Gio.Icon) – the Gio.Icon to set

Sets the icon of self.

New in version 2.16.

set_icon_name(icon_name)[source]¶

Parameters:

icon_name (str) – the icon name to set

Sets the icon name on self

New in version 2.16.

set_is_important(is_important)[source]¶

Parameters:

is_important (bool) – True to make the action important

Sets whether the action is important, this attribute is used primarily by toolbar items to decide whether to show a label or not.

New in version 2.16.

Deprecated since version 3.10: Use Gio.Action instead, and control and monitor whether labels are shown directly

set_label(label)[source]¶

Parameters:

label (str) – the label text to set

Sets the label of self.

New in version 2.16.

Deprecated since version 3.10: Use Gio.Action instead, and set a label on a menu item with Gio.MenuItem.set_label(). For Gtk.Actionable widgets, use the widget-specific API to set a label

set_sensitive(sensitive)[source]¶

Parameters:

sensitive (bool) – True to make the action sensitive

Sets the :sensitive property of the action to sensitive. Note that this doesn’t necessarily mean effective sensitivity. SeeGtk.Action.is_sensitive() for that.

New in version 2.6.

set_short_label(short_label)[source]¶

Parameters:

short_label (str) – the label text to set

Sets a shorter label text on self.

New in version 2.16.

Deprecated since version 3.10: Use Gio.Action instead, which has no equivalent of short labels

set_stock_id(stock_id)[source]¶

Parameters:

stock_id (str) – the stock id

Sets the stock id on self

New in version 2.16.

Deprecated since version 3.10: Use Gio.Action instead, which has no equivalent of stock items

set_tooltip(tooltip)[source]¶

Parameters:

tooltip (str) – the tooltip text

Sets the tooltip text on self

New in version 2.16.

set_visible(visible)[source]¶

Parameters:

visible (bool) – True to make the action visible

Sets the :visible property of the action to visible. Note that this doesn’t necessarily mean effective visibility. SeeGtk.Action.is_visible() for that.

New in version 2.6.

Deprecated since version 3.10: Use Gio.Action instead, and control and monitor the state of Gtk.Actionable widgets directly

set_visible_horizontal(visible_horizontal)[source]¶

Parameters:

visible_horizontal (bool) – whether the action is visible horizontally

Sets whether self is visible when horizontal

New in version 2.16.

Deprecated since version 3.10: Use Gio.Action instead, and control and monitor the visibility of associated widgets and menu items directly

set_visible_vertical(visible_vertical)[source]¶

Parameters:

visible_vertical (bool) – whether the action is visible vertically

Sets whether self is visible when vertical

New in version 2.16.

Deprecated since version 3.10: Use Gio.Action instead, and control and monitor the visibility of associated widgets and menu items directly

unblock_activate()[source]¶

Reenable activation signals from the action

New in version 2.16.

do_activate() virtual¶

Emits the “activate” signal on the specified action, if it isn’t insensitive. This gets called by the proxy widgets when they get activated.

It can also be used to manually activate an action.

New in version 2.4.

do_connect_proxy(proxy) virtual¶

Parameters:

proxy (Gtk.Widget) –

Returns:

the menu item provided by the action, or None.

Return type:

Gtk.Widget

If action provides a Gtk.Menu widget as a submenu for the menu item or the toolbar item it creates, this function returns an instance of that menu.

New in version 2.12.

Returns:

a menu item connected to the action.

Return type:

Gtk.Widget

Creates a menu item widget that proxies for the given action.

New in version 2.4.

do_create_tool_item() virtual¶

Returns:

a toolbar item connected to the action.

Return type:

Gtk.Widget

Creates a toolbar item widget that proxies for the given action.

New in version 2.4.

do_disconnect_proxy(proxy) virtual¶

Parameters:

proxy (Gtk.Widget) –

Signal Details¶

Gtk.Action.signals.activate(action)¶

Signal Name:

activate

Flags:

RUN_FIRST, NO_RECURSE

Parameters:

action (Gtk.Action) – The object which received the signal

The “activate” signal is emitted when the action is activated.

New in version 2.4.

Property Details¶

Gtk.Action.props.action_group¶

Name:

action-group

Type:

Gtk.ActionGroup

Default Value:

None

Flags:

READABLE, WRITABLE

The Gtk.ActionGroup this Gtk.Action is associated with, or None(for internal use).

Gtk.Action.props.always_show_image¶

Name:

always-show-image

Type:

bool

Default Value:

False

Flags:

READABLE, WRITABLE, CONSTRUCT

If True, the action’s menu item proxies will ignore the Gtk.Settings :gtk-menu-imagessetting and always show their image, if available.

Use this property if the menu item would be useless or hard to use without their image.

New in version 2.20.

Deprecated since version 3.10: There is no corresponding replacement when using Gio.Action

Gtk.Action.props.gicon¶

Name:

gicon

Type:

Gio.Icon

Default Value:

None

Flags:

READABLE, WRITABLE

The Gio.Icon displayed in the Gtk.Action.

Note that the stock icon is preferred, if the Gtk.Action :stock-idproperty holds the id of an existing stock icon.

This is an appearance property and thus only applies ifGtk.Activatable :use-action-appearance is True.

New in version 2.16.

Deprecated since version 3.10: Use the “icon” attribute on a Gio.MenuItem instead

Gtk.Action.props.hide_if_empty¶

Name:

hide-if-empty

Type:

bool

Default Value:

True

Flags:

READABLE, WRITABLE

When True, empty menu proxies for this action are hidden.

Deprecated since version 3.10: There is no corresponding replacement when using Gio.Action

Gtk.Action.props.icon_name¶

Name:

icon-name

Type:

str

Default Value:

None

Flags:

READABLE, WRITABLE

The name of the icon from the icon theme.

Note that the stock icon is preferred, if the Gtk.Action :stock-idproperty holds the id of an existing stock icon, and the Gio.Icon is preferred if the Gtk.Action :gicon property is set.

This is an appearance property and thus only applies ifGtk.Activatable :use-action-appearance is True.

New in version 2.10.

Deprecated since version 3.10: Use the “icon” attribute on a Gio.MenuItem instead

Gtk.Action.props.is_important¶

Name:

is-important

Type:

bool

Default Value:

False

Flags:

READABLE, WRITABLE

Whether the action is considered important. When True, toolitem proxies for this action show text in Gtk.ToolbarStyle.BOTH_HORIZ mode.

Deprecated since version 3.10: There is no corresponding replacement when using Gio.Action

Gtk.Action.props.label¶

Name:

label

Type:

str

Default Value:

None

Flags:

READABLE, WRITABLE

The label used for menu items and buttons that activate this action. If the label is None, GTK+ uses the stock label specified via the stock-id property.

This is an appearance property and thus only applies ifGtk.Activatable :use-action-appearance is True.

Deprecated since version 3.10: Use the “label” attribute on Gio.MenuItem instead

Gtk.Action.props.name¶

Name:

name

Type:

str

Default Value:

None

Flags:

READABLE, WRITABLE, CONSTRUCT_ONLY

A unique name for the action.

Gtk.Action.props.sensitive¶

Name:

sensitive

Type:

bool

Default Value:

True

Flags:

READABLE, WRITABLE

Whether the action is enabled.

Gtk.Action.props.short_label¶

Name:

short-label

Type:

str

Default Value:

None

Flags:

READABLE, WRITABLE

A shorter label that may be used on toolbar buttons.

This is an appearance property and thus only applies ifGtk.Activatable :use-action-appearance is True.

Deprecated since version 3.10: There is no corresponding replacement when using Gio.Action

Gtk.Action.props.stock_id¶

Name:

stock-id

Type:

str

Default Value:

None

Flags:

READABLE, WRITABLE

The stock icon displayed in widgets representing this action.

This is an appearance property and thus only applies ifGtk.Activatable :use-action-appearance is True.

Deprecated since version 3.10: There is no corresponding replacement when using Gio.Action

Gtk.Action.props.tooltip¶

Name:

tooltip

Type:

str

Default Value:

None

Flags:

READABLE, WRITABLE

A tooltip for this action.

Gtk.Action.props.visible¶

Name:

visible

Type:

bool

Default Value:

True

Flags:

READABLE, WRITABLE

Whether the action is visible.

Deprecated since version 3.10: There is no corresponding replacement when using Gio.Action

Gtk.Action.props.visible_horizontal¶

Name:

visible-horizontal

Type:

bool

Default Value:

True

Flags:

READABLE, WRITABLE

Whether the toolbar item is visible when the toolbar is in a horizontal orientation.

Deprecated since version 3.10: There is no corresponding replacement when using Gio.Action

Gtk.Action.props.visible_overflown¶

Name:

visible-overflown

Type:

bool

Default Value:

True

Flags:

READABLE, WRITABLE

When True, toolitem proxies for this action are represented in the toolbar overflow menu.

New in version 2.6.

Deprecated since version 3.10: There is no corresponding replacement when using Gio.Action

Gtk.Action.props.visible_vertical¶

Name:

visible-vertical

Type:

bool

Default Value:

True

Flags:

READABLE, WRITABLE

Whether the toolbar item is visible when the toolbar is in a vertical orientation.

Deprecated since version 3.10: There is no corresponding replacement when using Gio.Action