gtk.Action
Prev | The gtk Class Reference | Next

## gtk.Action

gtk.Action — an action which can be triggered by a menu or toolbar item (new in PyGTK 2.4)

## Synopsis

    class gtk.Action(gobject.GObject):
        gtk.Action(name, label, tooltip, stock_id)
        def activate()
        def block_activate()
        def block_activate_from(proxy)
        def connect_accelerator()
        def connect_proxy(proxy)
        def create_icon(icon_size)
        def create_menu()
        def create_menu_item()
        def create_tool_item()
        def disconnect_accelerator()
        def disconnect_proxy(proxy)
        def get_accel_path()
        def get_gicon()
        def get_icon_name()
        def get_is_important()
        def get_label()
        def get_name()
        def get_proxies()
        def get_visible()
        def get_short_label()
        def get_sensitive()
        def get_stock_id()
        def get_tooltip()
        def get_visible_horizontal()
        def get_visible_vertical()
        def is_sensitive()
        def is_visible()
        def get_always_show_image()
        def set_always_show_image(always_show)
        def set_accel_group(accel_group)
        def set_accel_path(accel_path)
        def set_gicon(icon)
        def set_icon_name(icon_name)
        def set_is_important(is_important)
        def set_label(label)
        def set_menu_item_type(visible)
        def set_sensitive(sensitive)
        def set_short_label(short_label)
        def set_stock_id(stock_id)
        def set_tool_item_type(visible)
        def set_tooltip(tooltip)
        def set_visible_horizontal(visible_horizontal)
        def set_visible_vertical(visible_vertical)
        def set_visible(visible)
        def unblock_activate()
        def unblock_activate_from(proxy)

## Ancestry

    +-- gobject.GObject
      +-- gtk.Action

## Implemented Interfaces

`gtk.Action` implements `gtk.Buildable`

## gtk.Action Properties

"action-group" | Read-Write | The `gtk.ActionGroup` this `gtk.Action` is associated with, or `None` (for internal use).
"always-show-image" | Read-Write | If `True`, the action's menu item proxies will ignore the "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.
"hide-if-empty" | Read-Write | If `True`, empty menu proxies for this action are hidden.
"gicon" | Read-Write | The `gio.Icon` displayed in the `gtk.Action`. Note that the stock icon is preferred, if the "stock-id" property holds the id of an existing stock icon. This is an appearance property and thus only applies if "use-action-appearance" is `True`. This property is available in GTK+ 2.16 and above.
"icon-name" | Read-Write | The name of the icon from the icon theme. Note that the stock icon is preferred, if the "stock-id" property holds the id of an existing stock icon and the `gio.Icon` is preferred if the "gicon" property is set. This is an appearance property and thus only applies if "use-action-appearance" is `True`. This property is available in GTK+ 2.10 and above.
"is-important" | Read-Write | If `True`, `gtk.ToolItem` proxies for this action show text in `gtk.TOOLBAR_BOTH_HORIZ` mode.
"label" | Read-Write | The label used for menu items and buttons that activate this action.
"name" | Read-Write-Construct Only | A unique name for the action.
"sensitive" | Read-Write | If `True`, the action is enabled.
"short-label" | Read-Write | A shorter label that may be used on toolbar buttons.
"stock-id" | Read-Write | The stock icon displayed in widgets representing this action.
"tooltip" | Read-Write | A tooltip for this action.
"visible" | Read-Write | If `True`, the action is visible.
"visible-horizontal" | Read-Write | If `True`, the toolbar item is visible when the toolbar is in a horizontal orientation.
"visible-overflown" | Read-Write | If `True`, toolitem proxies for this action are represented in the toolbar overflow menu. This property is available in GTK+ 2.6 and above.
"visible-vertical" | Read-Write | If `True`, the toolbar item is visible when the toolbar is in a vertical orientation.

## gtk.Action Signal Prototypes

gobject.GObject Signal Prototypes

"activate" | `def callback(`action`, `user_param1`, `...`)`

## Description

### Note

This widget is available in PyGTK 2.4 and above.

A `gtk.Action` represents operations that the user can perform, along with some information how it should be presented in the interface. Each `gtk.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 the 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 and radio actions, where only one in a group can be in the "active" state. Other actions can be implemented as `gtk.Action` subclasses.

Each `gtk.Action` can have one or more proxy menu items, toolbar buttons or other proxy widgets. Proxies mirror the state of the action (text label, tooltip, icon, visible, sensitive, etc), and should change when the action's state changes. When the proxy is activated, it should activate its action.

## Constructor

        gtk.Action(name, label, tooltip, stock_id)

`name` : | a unique name for the `gtk.Action`
`label` : | the label displayed in menu items and on buttons
`tooltip` : | a tooltip for the action
`stock_id` : | the stock icon to display in widgets representing the action
Returns : | a new `gtk.Action`

### Note

This constructor is available in PyGTK 2.4 and above.

Creates a new `gtk.Action` object. To add the action to a `gtk.ActionGroup` and set the accelerator for the action, call the `gtk.ActionGroup.add_action_with_accel()`.

## Methods

### gtk.Action.block_activate

        def block_activate()

### Note

This method is available in PyGTK 2.16 and above.

The `block_activate`() method disable activation signals from the action

This is needed when updating the state of your proxy `gtk.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).

### gtk.Action.get_gicon

        def get_gicon()

Returns : | The action's `gio.Icon` if one is set.

### Note

This method is available in PyGTK 2.16 and above.

The `get_gicon`() method gets the `gio.Icon` of action.

### gtk.Action.get_icon_name

        def get_icon_name()

Returns : | the icon name.

### Note

This method is available in PyGTK 2.16 and above.

The `get_icon_name`() method gets the icon name of action.

### gtk.Action.get_is_important

        def get_is_important()

Returns : | whether action is important, returning `True` if it is.

### Note

This method is available in PyGTK 2.16 and above.

The `get_is_important`() method checks whether action is important or not.

### gtk.Action.get_label

        def get_label()

Returns : | the label text.

### Note

This method is available in PyGTK 2.16 and above.

The `get_label`() method gets the label text of action.

### gtk.Action.get_name

        def get_name()

Returns : | the name of the action.

### Note

This method is available in PyGTK 2.4 and above.

The `get_name`() method returns the value of the "name" property containing the name of the action.

### gtk.Action.get_short_label

        def get_short_label()

Returns : | the short label text.

### Note

This method is available in PyGTK 2.16 and above.

The `get_short_label`() method gets the short label text of action.

### gtk.Action.get_tooltip

        def get_tooltip()

Returns : | the tooltip text.

### Note

This method is available in PyGTK 2.16 and above.

The `get_tooltip`() method gets the tooltip text of action.

### gtk.Action.get_visible_horizontal

        def get_visible_horizontal()

Returns : | whether action is visible when horizontal.

### Note

This method is available in PyGTK 2.16 and above.

The `get_visible_horizontal`() method gets whether action is visible when horizontal

### gtk.Action.get_visible_vertical

        def get_visible_vertical()

Returns : | whether action is visible when vertical.

### Note

This method is available in PyGTK 2.16 and above.

The `get_visible_vertical`() method gets whether action is visible when vertical.

### gtk.Action.get_stock_id

        def get_stock_id()

Returns : | the stock id.

### Note

This method is available in PyGTK 2.16 and above.

The `get_stock_id`() method gets the stock id of action.

### gtk.Action.is_sensitive

        def is_sensitive()

Returns : | `True` if the action and its associated action group are both sensitive.

### Note

This method is available in PyGTK 2.4 and above.

The `is_sensitive`() method returns `True` if the action is effectively sensitive i.e. both the `gtk.Action` and its associated `gtk.ActionGroup` are sensitive.

### gtk.Action.get_sensitive

        def get_sensitive()

Returns : | `True` if the action itself is sensitive.

### Note

This method is available in PyGTK 2.4 and above.

The `get_sensitive`() method returns the value of the "sensitive" property. If "sensitive" is `True` the action itself is sensitive. Note that this doesn't necessarily mean effective sensitivity. See the `is_sensitive()` method for more information.

### gtk.Action.is_visible

        def is_visible()

Returns : | `True` if the action and its associated action group are both visible.

### Note

This method is available in PyGTK 2.4 and above.

The `is_visible`() method returns `True` if the action is effectively visible i.e. both the `gtk.Action` and its associated `gtk.ActionGroup` as visible.

### gtk.Action.get_visible

        def get_visible()

Returns : | `True` if the action itself is visible.

### Note

This method is available in PyGTK 2.4 and above.

The `get_visible`() method returns the value of the "visible" property. If "visible" is `True` the `gtk.Action` itself is visible. Note that this doesn't necessarily mean effective visibility. See the `is_visible()` method for more information.

### gtk.Action.activate

        def activate()

### Note

This method is available in PyGTK 2.4 and above.

The `activate`() method emits the "activate" signal on the `gtk.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.

### gtk.Action.create_icon

        def create_icon(icon_size)

`icon_size` : | the size of the icon that should be created.
Returns : | a widget that displays the icon for this action.

### Note

This method is available in PyGTK 2.4 and above.

The `create_icon`() method creates and returns a `gtk.Image` with the size specified by `size` from the icon contained in the "stock-id" property if it exists. The value of `size` must be one of:

- `gtk.ICON_SIZE_MENU`
- `gtk.ICON_SIZE_SMALL_TOOLBAR`
- `gtk.ICON_SIZE_LARGE_TOOLBAR`
- `gtk.ICON_SIZE_BUTTON`
- `gtk.ICON_SIZE_DND`
- `gtk.ICON_SIZE_DIALOG`

This method is intended for use by `gtk.Action` implementations to create icons displayed in the proxy widgets.

### gtk.Action.create_menu

        def create_menu()

Returns : | the menu item provided by the action, or `None`.

### Note

This method is available in PyGTK 2.12 and above.

If action provides a `gtk.Menu`. widget as a submenu for the menu item or the toolbar item it creates, `create_menu`() method returns an instance of that menu.

### gtk.Action.create_menu_item

        def create_menu_item()

Returns : | a menu item connected to the action.

### Note

This method is available in PyGTK 2.4 and above.

The `create_menu_item`() method creates and returns a menu item widget that proxies for the `gtk.Action`.

### gtk.Action.create_tool_item

        def create_tool_item()

Returns : | a tool item connected to the action.

### Note

This method is available in PyGTK 2.4 and above.

The `create_tool_item`() method creates and returns a tool item widget that proxies for the `gtk.Action`.

### gtk.Action.connect_proxy

        def connect_proxy(proxy)

`proxy` : | the proxy widget

### Note

This method is available in PyGTK 2.4 and above.

The `connect_proxy`() method connects the widget specified by `proxy` to the `gtk.Action` object as a proxy. This method synchronizes various properties of the `gtk.Action` with the widget (such as label text, icon, tooltip, etc), and attaches a callback so that the `gtk.Action` is activated when `proxy` is.

If `proxy` is already connected to another `gtk.Action`, it is disconnected first. The `gtk.Action` should be added to a `gtk.ActionGroup` before calling this method.

### gtk.Action.disconnect_proxy

        def disconnect_proxy(proxy)

`proxy` : | the proxy widget

### Note

This method is available in PyGTK 2.4 and above.

The `disconnect_proxy`() method disconnects the widget specified by `proxy` from the `gtk.Action`. This method does not destroy the widget. The `gtk.Action` should be added to a `gtk.ActionGroup` before calling this method.

### gtk.Action.get_proxies

        def get_proxies()

Returns : | a list of proxy widgets.

### Note

This method is available in PyGTK 2.4 and above.

The `get_proxies`() method returns a list containing the proxy widgets associated with the `gtk.Action`.

### gtk.Action.connect_accelerator

        def connect_accelerator()

### Note

This method is available in PyGTK 2.4 and above.

The `connect_accelerator`() method installs the accelerator for the `gtk.Action` if it has an associated accel path and `gtk.AccelGroup`. See the `set_accel_path()` and the `set_accel_group()` methods.

Since multiple proxies may independently trigger the installation of the accelerator, the `gtk.Action` counts the number of times this method has been called and doesn't remove the accelerator until `disconnect_accelerator()` has been called as many times.

### gtk.Action.disconnect_accelerator

        def disconnect_accelerator()

### Note

This method is available in PyGTK 2.4 and above.

The `disconnect_accelerator`() method undoes the effect of one call to the `connect_accelerator()` method.

### gtk.Action.block_activate_from

        def block_activate_from(proxy)

`proxy` : | a proxy widget

### Note

This method is available in PyGTK 2.4 and above.

The `block_activate_from`() method disables calls to the `activate()` method by signals on the widget specified by `proxy`. This is used to break notification loops for things like check or radio actions.

This method is intended for use by `gtk.Action` implementations.

### gtk.Action.unblock_activate_from

        def unblock_activate_from(proxy)

`proxy` : | a proxy widget

### Note

This method is available in PyGTK 2.4 and above.

The `unblock_activate_from`() method re-enables calls to the `activate()` method by signals on the widget specified by `proxy`. This undoes the blocking done by the `block_activate_from()` method.

This method is intended for use by `gtk.Action` implementations.

### gtk.Action.get_accel_path

        def get_accel_path()

Returns : | the accelerator path associated with the action or `None`

### Note

This method is available in PyGTK 2.6 and above.

The `get_accel_path`() method returns the accel path for the action or `None` if no accel path is set.

### gtk.Action.set_accel_path

        def set_accel_path(accel_path)

`accel_path` : | the accelerator path

### Note

This method is available in PyGTK 2.4 and above.

The `set_accel_path`() method sets the accel path for the action to the value of `accel_path`. All proxy widgets associated with the action will have this accel path, so that their accelerators are consistent.

### gtk.Action.get_always_show_image

        def get_always_show_image()

Returns : | Returns `True` if the action's menu item proxies always show their image, `False` otherwise

### Note

This method is available in PyGTK 2.22 and above.

The `get_always_show_image`() method returns whether the action's menu item proxies will ignore the "gtk-menu-images" setting and always show their image, if available.

### gtk.Action.set_always_show_image

        def set_always_show_image(always_show)

`always_show` : | If `True` the action's menu item proxies will always show their image

### Note

This method is available in PyGTK 2.22 and above.

The `set_always_show_image`() method sets whether the action's menu item proxies will ignore the "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.

### gtk.Action.set_accel_group

        def set_accel_group(accel_group)

`accel_group` : | a `gtk.AccelGroup` or `None`

### Note

This method is available in PyGTK 2.4 and above.

The `set_accel_group`() method sets the `gtk.AccelGroup` specified by `accel_group` as the accelerator group for the `gtk.Action`.

### gtk.Action.set_gicon

        def set_gicon(icon)

`icon` : | the `gio.Icon` to set .

### Note

This method is available in PyGTK 2.16 and above.

The `set_gicon`() method sets the icon of action.

### gtk.Action.set_icon_name

        def set_icon_name(icon_name)

`icon_name` : | the icon name to set.

### Note

This method is available in PyGTK 2.16 and above.

The `set_icon_name`() method sets the icon name on action.

### gtk.Action.set_is_important

        def set_is_important(is_important)

`is_important` : | `True` to make the action important

### Note

This method is available in PyGTK 2.16 and above.

The `set_is_important`() method sets whether the action is important, this attribute is used primarily by toolbar items to decide whether to show a label or not.

### gtk.Action.set_label

        def set_label(label)

`label` : | the label text to set.

### Note

This method is available in PyGTK 2.16 and above.

The `set_is_important`() method sets the label of action.

### gtk.Action.set_short_label

        def set_short_label(short_label)

`short_label` : | the short label text to set.

### Note

This method is available in PyGTK 2.16 and above.

The `set_short_label`() method sets the short label of action.

### gtk.Action.set_sensitive

        def set_sensitive(sensitive)

`sensitive` : | if `True` make the action sensitive

### Note

This method is available in PyGTK 2.6 and above.

The `set_sensitive`() method sets the "sensitive" property to the value of `sensitive`. Note that this doesn't necessarily set the effective sensitivity. See the `is_sensitive`() method for more information.

### gtk.Action.set_stock_id

        def set_stock_id(stock_id)

`stock_id` : | the stock id.

### Note

This method is available in PyGTK 2.16 and above.

The `set_stock_id`() method sets the stock id on action

### gtk.Action.set_tooltip

        def set_tooltip(tooltip)

`tooltip` : | the tooltip text.

### Note

This method is available in PyGTK 2.16 and above.

The `set_tooltip`() method sets the tooltip text on action.

### gtk.Action.set_visible

        def set_visible(visible)

`visible` : | if `True` make the action visible

### Note

This method is available in PyGTK 2.6 and above.

The `set_visible`() method sets the "visible" property to the value of `visible`. Note that this doesn't necessarily set the effective visibility. See the `is_visible`() method for more information.

### gtk.Action.set_visible_horizontal

        def set_visible_horizontal(visible_horizontal)

`visible_horizontal` : | whether the action is visible horizontally.

### Note

This method is available in PyGTK 2.16 and above.

The `set_visible_horizontal`() method sets whether action is visible when horizontal

### gtk.Action.set_visible_vertical

        def set_visible_vertical(visible_vertical)

`visible_vertical` : | whether the action is visible vertically.

### Note

This method is available in PyGTK 2.16 and above.

The `set_visible_vertical`() method sets whether action is visible when vertical

### gtk.Action.set_menu_item_type

        def set_menu_item_type(visible)

`type` : | the type of menuitem to be created for the action

### Note

This method is available in PyGTK 2.10 and above.

The `set_menu_item_type`() method is a classmethod that sets the type of menuitem to be created for the action to that specified by `type`. This is useful when using the `gtk.UIManager` and you would like to use something other than a `gtk.ImageMenuItem` (`gtk.Action`) or a `gtk.CheckMenuItem` (`gtk.ToogleAction` or `gtk.RadioAction`).

### gtk.Action.set_tool_item_type

        def set_tool_item_type(visible)

`type` : | the type of toolitem to be created for the action

### Note

This method is available in PyGTK 2.10 and above.

The `set_tool_item_type`() method is a classmethod that sets the type of toolitem to be created for the action to that specified by `type`. This is useful when using the `gtk.UIManager` and you would like to use something other than a `gtk.ToolButton` (`gtk.Action`) or a `gtk.ToggleToolButton` (`gtk.ToogleAction` or `gtk.RadioAction`).

For example, to use a `gtk.MenuToolButton` in a toolbar you would subclass `gtk.Action`:

        class MenuToolAction(gtk.Action):
            __gtype_name__ = "MenuToolAction"

        gobject.type_register(MenuToolAction)

and then call `set_tool_item_type`():

        MenuToolAction.set_tool_item_type(gtk.MenuToolButton)

You have to create, name and add an instance of `MenuToolAction` to your `gtk.ActionGroup`:

        actiongroup.add_action(MenuToolAction("my_menutoolaction", "_MTB_label",
                                              "do something", None))

The ui description should reference the `MenuToolAction` like:

        <toolitem action="my_menutoolaction"/>

After the `gtk.UIManager` creates the toolbar including the `gtk.MenuToolButton` proxy for the `MenuToolAction`, you would have to create and add a menu to the `gtk.MenuToolButton` instance.

This technique can be extended by subclassing `gtk.ToolItem` and adding custom widgets to it.

### gtk.Action.unblock_activate

        def unblock_activate()

### Note

This method is available in PyGTK 2.16 and above.

The `unblock_activate`() method reenables activation signals from the action.

## Signals

### The "activate" gtk.Action Signal

        def callback(action, user_param1, ...)

`action` : | the `gtk.Action` that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

### Note

This signal is available in PyGTK 2.4 and above.

The "activate" signal is emitted when `action` is activated.

Prev | Up | Next
gtk.Accessible | Home | gtk.ActionGroup