gi-gtk-3.0.26: Gtk bindings

CopyrightWill Thompson Iñaki García Etxebarria and Jonas Platte
LicenseLGPL-2.1
MaintainerIñaki García Etxebarria (garetxe@gmail.com)
Safe HaskellNone
LanguageHaskell2010

GI.Gtk.Interfaces.Activatable

Contents

Description

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));

  ...
}
Synopsis

Exported types

newtype Activatable Source #

Memory-managed wrapper type.

class GObject o => IsActivatable o Source #

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

Instances
(GObject a, (UnknownAncestorError Activatable a :: Constraint)) => IsActivatable a Source # 
Instance details

Defined in GI.Gtk.Interfaces.Activatable

IsActivatable Activatable Source # 
Instance details

Defined in GI.Gtk.Interfaces.Activatable

IsActivatable Button Source # 
Instance details

Defined in GI.Gtk.Objects.Button

IsActivatable CheckButton Source # 
Instance details

Defined in GI.Gtk.Objects.CheckButton

IsActivatable CheckMenuItem Source # 
Instance details

Defined in GI.Gtk.Objects.CheckMenuItem

IsActivatable MenuItem Source # 
Instance details

Defined in GI.Gtk.Objects.MenuItem

IsActivatable RadioButton Source # 
Instance details

Defined in GI.Gtk.Objects.RadioButton

IsActivatable ScaleButton Source # 
Instance details

Defined in GI.Gtk.Objects.ScaleButton

IsActivatable ToggleButton Source # 
Instance details

Defined in GI.Gtk.Objects.ToggleButton

IsActivatable ToggleToolButton Source # 
Instance details

Defined in GI.Gtk.Objects.ToggleToolButton

IsActivatable ToolButton Source # 
Instance details

Defined in GI.Gtk.Objects.ToolButton

IsActivatable ToolItem Source # 
Instance details

Defined in GI.Gtk.Objects.ToolItem

IsActivatable VolumeButton Source # 
Instance details

Defined in GI.Gtk.Objects.VolumeButton

IsActivatable TearoffMenuItem Source # 
Instance details

Defined in GI.Gtk.Objects.TearoffMenuItem

IsActivatable Switch Source # 
Instance details

Defined in GI.Gtk.Objects.Switch

IsActivatable SeparatorToolItem Source # 
Instance details

Defined in GI.Gtk.Objects.SeparatorToolItem

IsActivatable SeparatorMenuItem Source # 
Instance details

Defined in GI.Gtk.Objects.SeparatorMenuItem

IsActivatable RecentChooserMenu Source # 
Instance details

Defined in GI.Gtk.Objects.RecentChooserMenu

IsActivatable RadioToolButton Source # 
Instance details

Defined in GI.Gtk.Objects.RadioToolButton

IsActivatable RadioMenuItem Source # 
Instance details

Defined in GI.Gtk.Objects.RadioMenuItem

IsActivatable ModelButton Source # 
Instance details

Defined in GI.Gtk.Objects.ModelButton

IsActivatable MenuToolButton Source # 
Instance details

Defined in GI.Gtk.Objects.MenuToolButton

IsActivatable MenuButton Source # 
Instance details

Defined in GI.Gtk.Objects.MenuButton

IsActivatable LockButton Source # 
Instance details

Defined in GI.Gtk.Objects.LockButton

IsActivatable LinkButton Source # 
Instance details

Defined in GI.Gtk.Objects.LinkButton

IsActivatable ImageMenuItem Source # 
Instance details

Defined in GI.Gtk.Objects.ImageMenuItem

IsActivatable FontButton Source # 
Instance details

Defined in GI.Gtk.Objects.FontButton

IsActivatable ColorButton Source # 
Instance details

Defined in GI.Gtk.Objects.ColorButton

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

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

Methods

doSetRelatedAction

activatableDoSetRelatedAction Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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) Source #

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 Source #

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 () Source #

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) Source #

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 Source #

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 () Source #

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

set activatable [ #useActionAppearance := value ]