gtk.Activatable
Prev | The gtk Class Reference | Next

## gtk.Activatable

gtk.Activatable — An interface for activatable widgets.

## Synopsis

    class gtk.Activatable(gobject.GInterface):
        def do_set_related_action(action)
        def get_related_action()
        def get_use_action_appearence()
        def set_related_action(action)
        def set_use_action_appearence(use_appearence)
        def sync_action_properties(action)

## Ancestry

    +-- gobject.GInterface
      +-- gtk.Activatable

## gtk.Activatable Properties

"related-action" | Read/Write | The action that this activatable will activate and receive updates from for various states and possibly appearance. Note: `gtk.Activatable` implementors need to handle the "related-action" property and call `gtk.Activatable.do_set_related_action`() when it changes. This property is available in GTK+ 2.16 and above.

"use-action-appearance"

Read/Write

Whether this activatable should reset its layout and appearance when setting the related action or when the action changes appearance. See the `gtk.Action` documentation directly to find which properties should be ignored by the `gtk.Activatable` when this property is `False`. Note: `gtk.Activatable` implementors need to handle the "related-action" property and call `gtk.Activatable.do_set_related_action`() when it changes. Default value: `True`. This property is available in GTK+ 2.16 and above.

## Known Implementation

`gtk.Activatable` is implementated by `gtk.TearoffMenuItem`, `gtk.OptionMenu`, `gtk.LinkButton`, `gtk.RadioButton`, `gtk.RadioToolButton`, `gtk.ToggleButton`, `gtk.SeparatorMenuItem`, `gtk.ImageMenuItem`, `gtk.CheckButton`, `gtk.RadioMenuItem`, `gtk.Button`, `gtk.MenuToolButton`, `gtk.MenuItem`, `gtk.RecentChooserMenu`, `gtk.ToolItem`, `gtk.SeparatorToolItem`, `gtk.CheckMenuItem`, `gtk.ToolButton`, `gtkFontButton.`, `gtk.ScaleButton`, `gtk.ToggleToolButton`, `gtk.VolumeButton`, `gtk.ColorButton`.

## Description

Activatable widgets can be connected to a `gtk.Action` and reflects the state of its action. A GtkActivatable can also provide feedback through its action, as they are responsible for activating their related actions.

When extending a class that is already `gtk.Activatable` it is only necessary to implement the `gtk.Activatable.do_sync_action_properties` and `gtk.Activatable.do_update`() class methods and chain up to the parent implementation, however when introducing a new `gtk.Activatable` class the "related-action" and "use-action-appearance" properties need to be handled by the implementor. Handling these properties is mostly a matter of installing the action pointer and boolean flag on your instance, and calling `gtk.Activatable.do_set_related_action`() and `gtk.Activatable.sync_action_properties`() at the appropriate times.

## Methods

### gtk.Activatable.do_set_related_action

        def do_set_related_action(action)

`action` : | the `gtk.Action` to set.

### Note

This method is available in PyGTK 2.16 and above.

The `do_set_related_action`() method is an utility function for `gtk.Activatable` implementors.

When implementing `gtk.Activatable` you must call this when handling changes of the "related-action", and you must also use this to break references in GObject->dispose().

This function adds a reference to the currently set related action for you, it also makes sure the GtkActivatable->update() method is called when the related `gtk.Action` properties change and registers to the action's proxy list.

### Note

Be careful to call this before setting the local copy of the `gtk.Action` property, since this function uses `gtk.Activatable.get_related_action`() to retrieve the previous action

### gtk.Activatable.get_related_action

        def get_related_action()

Returns : | the related `gtk.Action` if one is set.

### Note

This method is available in PyGTK 2.16 and above.

The `get_related_action`() method gets the related `gtk.Action` for activatable.

### gtk.Activatable.get_use_action_appearence

        def get_use_action_appearence()

Returns : | whether activatable uses its actions appearance.

### Note

This method is available in PyGTK 2.16 and above.

The `get_use_action_appearence`() method gets whether this activatable should reset its layout and appearance when setting the related action or when the action changes appearance.

### gtk.Activatable.set_related_action

        def set_related_action(action)

`action` : | the `gtk.Action` to set.

### Note

This method is available in PyGTK 2.16 and above.

### Note

`gtk.Activatable` implementors need to handle the "related-action" property and call `gtk.Activatable.do_set_related_action`() when it changes.

The `set_related_action`() method sets the related action on the activatable object.

### gtk.Activatable.set_use_action_appearence

        def set_use_action_appearence(use_appearence)

`use_appearence` : | whether to use the actions appearance.

### Note

This method is available in PyGTK 2.16 and above.

### Note

`gtk.Activatable` implementors need to handle the "related-action" property and call `gtk.Activatable.do_set_related_action`() when it changes.

The `set_use_action_appearence`() method sets whether this activatable should reset its layout and appearance when setting the related action or when the action changes appearance

### gtk.Activatable.sync_action_properties

        def sync_action_properties(action)

`action` : | the related `gtk.Action` or `None`

### Note

This method is available in PyGTK 2.16 and above.

The `set_use_action_appearence`() method is called to update the activatable completely, this is called internally when the "related-action" property is set or unset and by the implementing class when "use-action-appearance" changes.

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