gtk.Action

gtk.Action
Prev	The gtk Class Reference	Next

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 get_name()
    def is_sensitive()
    def get_sensitive()
    def is_visible()
    def get_visible()
    def activate()
    def create_icon(icon_size)
    def create_menu_item()
    def create_tool_item()
    def connect_proxy(proxy)
    def disconnect_proxy(proxy)
    def get_proxies()
    def connect_accelerator()
    def disconnect_accelerator()
    def block_activate_from(proxy)
    def unblock_activate_from(proxy)
    def get_accel_path()
    def set_accel_path(accel_path)
    def set_accel_group(accel_group)
    def set_sensitive(sensitive)
    def set_visible(visible)

Ancestry

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

gtk.Action Properties

"action-group"	Read-Write	The `gtk.ActionGroup` this `gtk.Action` is associated with, or `None` (for internal use).
"hide-if-empty"	Read-Write	If `TRUE`, empty menu proxies for this action are hidden.
"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-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.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.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_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.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_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_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.

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.