gi-gtk-3.0.43: Gtk bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | None
Language | Haskell2010

GI.Gtk.Interfaces.Activatable

Contents

- Exported types
- Methods
  - doSetRelatedAction
  - getRelatedAction
  - getUseActionAppearance
  - setRelatedAction
  - setUseActionAppearance
  - syncActionProperties
- Properties
  - relatedAction
  - useActionAppearance

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:relatedAction and Activatable:useActionAppearance 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

- newtype Activatable = Activatable (ManagedPtr Activatable)
- class (GObject o, IsDescendantOf Activatable o) => IsActivatable o
- toActivatable :: (MonadIO m, IsActivatable o) => o -> m Activatable
- activatableDoSetRelatedAction :: (HasCallStack, MonadIO m, IsActivatable a, IsAction b) => a -> b -> m ()
- activatableGetRelatedAction :: (HasCallStack, MonadIO m, IsActivatable a) => a -> m Action
- activatableGetUseActionAppearance :: (HasCallStack, MonadIO m, IsActivatable a) => a -> m Bool
- activatableSetRelatedAction :: (HasCallStack, MonadIO m, IsActivatable a, IsAction b) => a -> b -> m ()
- activatableSetUseActionAppearance :: (HasCallStack, MonadIO m, IsActivatable a) => a -> Bool -> m ()
- activatableSyncActionProperties :: (HasCallStack, MonadIO m, IsActivatable a, IsAction b) => a -> Maybe b -> m ()
- constructActivatableRelatedAction :: (IsActivatable o, MonadIO m, IsAction a) => a -> m (GValueConstruct o)
- getActivatableRelatedAction :: (MonadIO m, IsActivatable o) => o -> m Action
- setActivatableRelatedAction :: (MonadIO m, IsActivatable o, IsAction a) => o -> a -> m ()
- constructActivatableUseActionAppearance :: (IsActivatable o, MonadIO m) => Bool -> m (GValueConstruct o)
- getActivatableUseActionAppearance :: (MonadIO m, IsActivatable o) => o -> m Bool
- setActivatableUseActionAppearance :: (MonadIO m, IsActivatable o) => o -> Bool -> m ()

# Exported types

newtype Activatable Source #

Memory-managed wrapper type.

Constructors

Activatable (ManagedPtr Activatable) |

#### Instances

Instances details

Eq Activatable Source # |
Instance details Defined in GI.Gtk.Interfaces.Activatable Methods (==) :: Activatable -> Activatable -> Bool Source # (/=) :: Activatable -> Activatable -> Bool Source #
GObject Activatable Source # |
Instance details Defined in GI.Gtk.Interfaces.Activatable
ManagedPtrNewtype Activatable Source # |
Instance details Defined in GI.Gtk.Interfaces.Activatable Methods toManagedPtr :: Activatable -> ManagedPtr Activatable Source #
TypedObject Activatable Source # |
Instance details Defined in GI.Gtk.Interfaces.Activatable Methods glibType :: IO GType Source #
HasParentTypes Activatable Source # |
Instance details Defined in GI.Gtk.Interfaces.Activatable
IsGValue (Maybe Activatable) Source # | Convert `Activatable` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.Gtk.Interfaces.Activatable Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> Maybe Activatable -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe Activatable) Source #
type ParentTypes Activatable Source # |
Instance details Defined in GI.Gtk.Interfaces.Activatable type ParentTypes Activatable = '[Object]

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

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

#### Instances

Instances details

(GObject o, IsDescendantOf Activatable o) => IsActivatable o Source # |
Instance details Defined in GI.Gtk.Interfaces.Activatable

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

### Click to display all available methods, including inherited ones

Expand

#### Methods

bindProperty, bindPropertyFull, doSetRelatedAction, forceFloating, freezeNotify, getv, isFloating, notify, notifyByPspec, ref, refSink, runDispose, stealData, stealQdata, syncActionProperties, thawNotify, unref, watchClosure.

#### Getters

getData, getProperty, getQdata, getRelatedAction, getUseActionAppearance.

#### Setters

setData, setDataFull, setProperty, setRelatedAction, setUseActionAppearance.

## 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:relatedAction, 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 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.

    t'GI.Gtk.Interfaces.Activatable.Activatable' implementors need to handle the [Activatable:relatedAction]("GI.Gtk.Interfaces.Activatable#g:attr:relatedAction")
    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

    t'GI.Gtk.Interfaces.Activatable.Activatable' implementors need to handle the
    [Activatable:useActionAppearance]("GI.Gtk.Interfaces.Activatable#g:attr:useActionAppearance") 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:relatedAction property is set or unset and by the implementing class when Activatable:useActionAppearance 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) 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`.

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