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

Eq Activatable

Defined in GI.Gtk.Interfaces.Activatable

Methods

(==) :: Activatable -> Activatable -> Bool

(/=) :: Activatable -> Activatable -> Bool

IsGValue Activatable

Convert Activatable to and from GValue with toGValue and fromGValue.

Defined in GI.Gtk.Interfaces.Activatable

Methods

toGValue :: Activatable -> IO GValue

fromGValue :: GValue -> IO Activatable

ManagedPtrNewtype Activatable

Defined in GI.Gtk.Interfaces.Activatable

Methods

toManagedPtr :: Activatable -> ManagedPtr Activatable

TypedObject Activatable

Defined in GI.Gtk.Interfaces.Activatable

Methods

glibType :: IO GType

GObject Activatable

Defined in GI.Gtk.Interfaces.Activatable

HasParentTypes Activatable

Defined in GI.Gtk.Interfaces.Activatable

type ParentTypes Activatable

Defined in GI.Gtk.Interfaces.Activatable

type ParentTypes Activatable = '[Object]

class (GObject o, IsDescendantOf Activatable o) => IsActivatable o

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

Instances

(GObject o, IsDescendantOf Activatable o) => IsActivatable o

Defined in GI.Gtk.Interfaces.Activatable

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

Overloaded 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 t'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.

t'GI.Gtk.Interfaces.Activatable.Activatable' implementors need to handle the t'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

t'GI.Gtk.Interfaces.Activatable.Activatable' implementors need to handle the
t'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.

t'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, MonadIO m, IsAction a) => a -> m (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.

t'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, MonadIO m) => Bool -> m (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 ]