GI.Gtk.Interfaces.Activatable

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

Implementing GtkActivatable

When extending a class that is already Activatable; it is only necessary to implement the Activatable->sync_action_properties() and Activatable->update() methods and chain up to the parent implementation, however when introducing a new Activatable class; the Activatable:related-action and Activatable: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 activatableDoSetRelatedAction and activatableSyncActionProperties at the appropriate times.

## A class fragment implementing Activatable

C code

enum {
...

PROP_ACTIVATABLE_RELATED_ACTION,
PROP_ACTIVATABLE_USE_ACTION_APPEARANCE
}

struct _FooBarPrivate
{

  ...

  GtkAction      *action;
  gboolean        use_action_appearance;
};

...

static void foo_bar_activatable_interface_init         (GtkActivatableIface  *iface);
static void foo_bar_activatable_update                 (GtkActivatable       *activatable,
						           GtkAction            *action,
						           const gchar          *property_name);
static void foo_bar_activatable_sync_action_properties (GtkActivatable       *activatable,
						           GtkAction            *action);
...


static void
foo_bar_class_init (FooBarClass *klass)
{

  ...

  g_object_class_override_property (gobject_class, PROP_ACTIVATABLE_RELATED_ACTION, "related-action");
  g_object_class_override_property (gobject_class, PROP_ACTIVATABLE_USE_ACTION_APPEARANCE, "use-action-appearance");

  ...
}


static void
foo_bar_activatable_interface_init (GtkActivatableIface  *iface)
{
  iface->update = foo_bar_activatable_update;
  iface->sync_action_properties = foo_bar_activatable_sync_action_properties;
}

... Break the reference using gtk_activatable_do_set_related_action()...

static void
foo_bar_dispose (GObject *object)
{
  FooBar *bar = FOO_BAR (object);
  FooBarPrivate *priv = FOO_BAR_GET_PRIVATE (bar);

  ...

  if (priv->action)
    {
      gtk_activatable_do_set_related_action (GTK_ACTIVATABLE (bar), NULL);
      priv->action = NULL;
    }
  G_OBJECT_CLASS (foo_bar_parent_class)->dispose (object);
}

... Handle the “related-action” and “use-action-appearance” properties ...

static void
foo_bar_set_property (GObject         *object,
                      guint            prop_id,
                      const GValue    *value,
                      GParamSpec      *pspec)
{
  FooBar *bar = FOO_BAR (object);
  FooBarPrivate *priv = FOO_BAR_GET_PRIVATE (bar);

  switch (prop_id)
    {

      ...

    case PROP_ACTIVATABLE_RELATED_ACTION:
      foo_bar_set_related_action (bar, g_value_get_object (value));
      break;
    case PROP_ACTIVATABLE_USE_ACTION_APPEARANCE:
      foo_bar_set_use_action_appearance (bar, g_value_get_boolean (value));
      break;
    default:
      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
      break;
    }
}

static void
foo_bar_get_property (GObject         *object,
                         guint            prop_id,
                         GValue          *value,
                         GParamSpec      *pspec)
{
  FooBar *bar = FOO_BAR (object);
  FooBarPrivate *priv = FOO_BAR_GET_PRIVATE (bar);

  switch (prop_id)
    {

      ...

    case PROP_ACTIVATABLE_RELATED_ACTION:
      g_value_set_object (value, priv->action);
      break;
    case PROP_ACTIVATABLE_USE_ACTION_APPEARANCE:
      g_value_set_boolean (value, priv->use_action_appearance);
      break;
    default:
      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
      break;
    }
}


static void
foo_bar_set_use_action_appearance (FooBar   *bar,
				   gboolean  use_appearance)
{
  FooBarPrivate *priv = FOO_BAR_GET_PRIVATE (bar);

  if (priv->use_action_appearance != use_appearance)
    {
      priv->use_action_appearance = use_appearance;
      
      gtk_activatable_sync_action_properties (GTK_ACTIVATABLE (bar), priv->action);
    }
}

... call gtk_activatable_do_set_related_action() and then assign the action pointer,
no need to reference the action here since gtk_activatable_do_set_related_action() already
holds a reference here for you...
static void
foo_bar_set_related_action (FooBar    *bar,
			    GtkAction *action)
{
  FooBarPrivate *priv = FOO_BAR_GET_PRIVATE (bar);

  if (priv->action == action)
    return;

  gtk_activatable_do_set_related_action (GTK_ACTIVATABLE (bar), action);

  priv->action = action;
}

... Selectively reset and update activatable depending on the use-action-appearance property ...
static void
gtk_button_activatable_sync_action_properties (GtkActivatable       *activatable,
		                                  GtkAction            *action)
{
  GtkButtonPrivate *priv = GTK_BUTTON_GET_PRIVATE (activatable);

  if (!action)
    return;

  if (gtk_action_is_visible (action))
    gtk_widget_show (GTK_WIDGET (activatable));
  else
    gtk_widget_hide (GTK_WIDGET (activatable));
  
  gtk_widget_set_sensitive (GTK_WIDGET (activatable), gtk_action_is_sensitive (action));

  ...
  
  if (priv->use_action_appearance)
    {
      if (gtk_action_get_stock_id (action))
	foo_bar_set_stock (button, gtk_action_get_stock_id (action));
      else if (gtk_action_get_label (action))
	foo_bar_set_label (button, gtk_action_get_label (action));

      ...

    }
}

static void
foo_bar_activatable_update (GtkActivatable       *activatable,
			       GtkAction            *action,
			       const gchar          *property_name)
{
  FooBarPrivate *priv = FOO_BAR_GET_PRIVATE (activatable);

  if (strcmp (property_name, "visible") == 0)
    {
      if (gtk_action_is_visible (action))
	gtk_widget_show (GTK_WIDGET (activatable));
      else
	gtk_widget_hide (GTK_WIDGET (activatable));
    }
  else if (strcmp (property_name, "sensitive") == 0)
    gtk_widget_set_sensitive (GTK_WIDGET (activatable), gtk_action_is_sensitive (action));

  ...

  if (!priv->use_action_appearance)
    return;

  if (strcmp (property_name, "stock-id") == 0)
    foo_bar_set_stock (button, gtk_action_get_stock_id (action));
  else if (strcmp (property_name, "label") == 0)
    foo_bar_set_label (button, gtk_action_get_label (action));

  ...
}

Exported types

newtype Activatable

Memory-managed wrapper type.

Constructors

Activatable (ManagedPtr Activatable)

Instances

GObject Activatable

Defined in GI.Gtk.Interfaces.Activatable

Methods

gobjectType :: Activatable -> IO GType

IsObject Activatable

Defined in GI.Gtk.Interfaces.Activatable

IsActivatable Activatable

Defined in GI.Gtk.Interfaces.Activatable

noActivatable :: Maybe Activatable

A convenience alias for Nothing :: Maybe Activatable.

class GObject o => IsActivatable o

Type class for types which can be safely cast to Activatable, for instance with toActivatable.

Instances

(GObject a, (UnknownAncestorError Activatable a :: Constraint)) => IsActivatable a

Defined in GI.Gtk.Interfaces.Activatable

IsActivatable Activatable

Defined in GI.Gtk.Interfaces.Activatable

IsActivatable Button

Defined in GI.Gtk.Objects.Button

IsActivatable CheckButton

Defined in GI.Gtk.Objects.CheckButton

IsActivatable CheckMenuItem

Defined in GI.Gtk.Objects.CheckMenuItem

IsActivatable MenuItem

Defined in GI.Gtk.Objects.MenuItem

IsActivatable RadioButton

Defined in GI.Gtk.Objects.RadioButton

IsActivatable ScaleButton

Defined in GI.Gtk.Objects.ScaleButton

IsActivatable ToggleButton

Defined in GI.Gtk.Objects.ToggleButton

IsActivatable ToggleToolButton

Defined in GI.Gtk.Objects.ToggleToolButton

IsActivatable ToolButton

Defined in GI.Gtk.Objects.ToolButton

IsActivatable ToolItem

Defined in GI.Gtk.Objects.ToolItem

IsActivatable VolumeButton

Defined in GI.Gtk.Objects.VolumeButton

IsActivatable TearoffMenuItem

Defined in GI.Gtk.Objects.TearoffMenuItem

IsActivatable Switch

Defined in GI.Gtk.Objects.Switch

IsActivatable SeparatorToolItem

Defined in GI.Gtk.Objects.SeparatorToolItem

IsActivatable SeparatorMenuItem

Defined in GI.Gtk.Objects.SeparatorMenuItem

IsActivatable RecentChooserMenu

Defined in GI.Gtk.Objects.RecentChooserMenu

IsActivatable RadioToolButton

Defined in GI.Gtk.Objects.RadioToolButton

IsActivatable RadioMenuItem

Defined in GI.Gtk.Objects.RadioMenuItem

IsActivatable ModelButton

Defined in GI.Gtk.Objects.ModelButton

IsActivatable MenuToolButton

Defined in GI.Gtk.Objects.MenuToolButton

IsActivatable MenuButton

Defined in GI.Gtk.Objects.MenuButton

IsActivatable LockButton

Defined in GI.Gtk.Objects.LockButton

IsActivatable LinkButton

Defined in GI.Gtk.Objects.LinkButton

IsActivatable ImageMenuItem

Defined in GI.Gtk.Objects.ImageMenuItem

IsActivatable FontButton

Defined in GI.Gtk.Objects.FontButton

IsActivatable ColorButton

Defined in GI.Gtk.Objects.ColorButton

toActivatable :: (MonadIO m, IsActivatable o) => o -> m Activatable

Cast to Activatable, for types for which this is known to be safe. For general casts, use castTo.

Methods

doSetRelatedAction

activatableDoSetRelatedAction

Arguments

:: (HasCallStack, MonadIO m, IsActivatable a, IsAction b)

=> a

activatable: a Activatable

-> b

action: the Action to set

-> m ()

Deprecated: (Since version 3.10)

This is a utility function for Activatable implementors.

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

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

Be careful to call this before setting the local
copy of the 'GI.Gtk.Objects.Action.Action' property, since this function uses
'GI.Gtk.Interfaces.Activatable.activatableGetRelatedAction' to retrieve the
previous action.

Since: 2.16

getRelatedAction

activatableGetRelatedAction

Arguments

:: (HasCallStack, MonadIO m, IsActivatable a)

=> a

activatable: a Activatable

-> m Action

Returns: the related Action if one is set.

Deprecated: (Since version 3.10)

Gets the related Action for activatable.

Since: 2.16

getUseActionAppearance

activatableGetUseActionAppearance

Arguments

:: (HasCallStack, MonadIO m, IsActivatable a)

=> a

activatable: a Activatable

-> m Bool

Returns: whether activatable uses its actions appearance.

Deprecated: (Since version 3.10)

Gets whether this activatable should reset its layout and appearance when setting the related action or when the action changes appearance.

Since: 2.16

setRelatedAction

activatableSetRelatedAction

Arguments

:: (HasCallStack, MonadIO m, IsActivatable a, IsAction b)

=> a

activatable: a Activatable

-> b

action: the Action to set

-> m ()

Deprecated: (Since version 3.10)

Sets the related action on the activatable object.

'GI.Gtk.Interfaces.Activatable.Activatable' implementors need to handle the 'GI.Gtk.Interfaces.Activatable.Activatable':@/related-action/@
property and call 'GI.Gtk.Interfaces.Activatable.activatableDoSetRelatedAction' when it changes.

Since: 2.16

setUseActionAppearance

activatableSetUseActionAppearance

Arguments

:: (HasCallStack, MonadIO m, IsActivatable a)

=> a

activatable: a Activatable

-> Bool

useAppearance: whether to use the actions appearance

-> m ()

Deprecated: (Since version 3.10)

Sets whether this activatable should reset its layout and appearance when setting the related action or when the action changes appearance

'GI.Gtk.Interfaces.Activatable.Activatable' implementors need to handle the
'GI.Gtk.Interfaces.Activatable.Activatable':@/use-action-appearance/@ property and call
'GI.Gtk.Interfaces.Activatable.activatableSyncActionProperties' to update /@activatable@/
if needed.

Since: 2.16

syncActionProperties

activatableSyncActionProperties

Arguments

:: (HasCallStack, MonadIO m, IsActivatable a, IsAction b)

=> a

activatable: a Activatable

-> Maybe b

action: the related Action or Nothing

-> m ()

Deprecated: (Since version 3.10)

This is called to update the activatable completely, this is called internally when the Activatable:related-action property is set or unset and by the implementing class when Activatable:use-action-appearance changes.

Since: 2.16

Properties

relatedAction

The action that this activatable will activate and receive updates from for various states and possibly appearance.

'GI.Gtk.Interfaces.Activatable.Activatable' implementors need to handle the this property and
call 'GI.Gtk.Interfaces.Activatable.activatableDoSetRelatedAction' when it changes.

Since: 2.16

constructActivatableRelatedAction :: (IsActivatable o, IsAction a) => a -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “related-action” property. This is rarely needed directly, but it is used by new.

getActivatableRelatedAction :: (MonadIO m, IsActivatable o) => o -> m Action

Get the value of the “related-action” property. When overloading is enabled, this is equivalent to

get activatable #relatedAction

setActivatableRelatedAction :: (MonadIO m, IsActivatable o, IsAction a) => o -> a -> m ()

Set the value of the “related-action” property. When overloading is enabled, this is equivalent to

set activatable [ #relatedAction := value ]

useActionAppearance

Whether this activatable should reset its layout and appearance when setting the related action or when the action changes appearance.

See the Action documentation directly to find which properties should be ignored by the Activatable when this property is False.

'GI.Gtk.Interfaces.Activatable.Activatable' implementors need to handle this property
and call 'GI.Gtk.Interfaces.Activatable.activatableSyncActionProperties' on the activatable
widget when it changes.

Since: 2.16

constructActivatableUseActionAppearance :: IsActivatable o => Bool -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “use-action-appearance” property. This is rarely needed directly, but it is used by new.

getActivatableUseActionAppearance :: (MonadIO m, IsActivatable o) => o -> m Bool

Get the value of the “use-action-appearance” property. When overloading is enabled, this is equivalent to

get activatable #useActionAppearance

setActivatableUseActionAppearance :: (MonadIO m, IsActivatable o) => o -> Bool -> m ()

Set the value of the “use-action-appearance” property. When overloading is enabled, this is equivalent to

set activatable [ #useActionAppearance := value ]