Key Bindings

## Key Bindings Key Bindings — Pool for key bindings |

## Synopsis

                        ClutterBindingPool;
    gboolean            (*ClutterBindingActionFunc)         (GObject *gobject,
                                                             const gchar *action_name,
                                                             guint key_val,
                                                             ClutterModifierType modifiers);

    ClutterBindingPool * clutter_binding_pool_new           (const gchar *name);
    ClutterBindingPool * clutter_binding_pool_get_for_class (gpointer klass);
    ClutterBindingPool * clutter_binding_pool_find          (const gchar *name);

    void                clutter_binding_pool_install_action (ClutterBindingPool *pool,
                                                             const gchar *action_name,
                                                             guint key_val,
                                                             ClutterModifierType modifiers,
                                                             GCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify notify);
    void                clutter_binding_pool_install_closure
                                                            (ClutterBindingPool *pool,
                                                             const gchar *action_name,
                                                             guint key_val,
                                                             ClutterModifierType modifiers,
                                                             GClosure *closure);
    void                clutter_binding_pool_override_action
                                                            (ClutterBindingPool *pool,
                                                             guint key_val,
                                                             ClutterModifierType modifiers,
                                                             GCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify notify);
    void                clutter_binding_pool_override_closure
                                                            (ClutterBindingPool *pool,
                                                             guint key_val,
                                                             ClutterModifierType modifiers,
                                                             GClosure *closure);
    const gchar *       clutter_binding_pool_find_action    (ClutterBindingPool *pool,
                                                             guint key_val,
                                                             ClutterModifierType modifiers);
    void                clutter_binding_pool_remove_action  (ClutterBindingPool *pool,
                                                             guint key_val,
                                                             ClutterModifierType modifiers);
    void                clutter_binding_pool_block_action   (ClutterBindingPool *pool,
                                                             const gchar *action_name);
    void                clutter_binding_pool_unblock_action (ClutterBindingPool *pool,
                                                             const gchar *action_name);

    gboolean            clutter_binding_pool_activate       (ClutterBindingPool *pool,
                                                             guint key_val,
                                                             ClutterModifierType modifiers,
                                                             GObject *gobject);

## Object Hierarchy

      GObject
       +----ClutterBindingPool

## Properties

      "name"                     gchar*                : Read / Write / Construct Only

## Description

ClutterBindingPool is a data structure holding a set of key bindings. Each key binding associates a key symbol (eventually with modifiers) to an action. A callback function is associated to each action.

For a given key symbol and modifier mask combination there can be only one action; for each action there can be only one callback. There can be multiple actions with the same name, and the same callback can be used to handle multiple key bindings.

Actors requiring key bindings should create a new ClutterBindingPool inside their class initialization function and then install actions like this:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    static void
    foo_class_init (FooClass *klass)
    {
      ClutterBindingPool *binding_pool;

      binding_pool = clutter_binding_pool_get_for_class (klass);

      clutter_binding_pool_install_action (binding_pool, "move-up",
                                           CLUTTER_Up, 0,
                                           G_CALLBACK (foo_action_move_up),
                                           NULL, NULL);
      clutter_binding_pool_install_action (binding_pool, "move-up",
                                           CLUTTER_KP_Up, 0,
                                           G_CALLBACK (foo_action_move_up),
                                           NULL, NULL);
    }

The callback has a signature of:

    1
    2
    3
    4
    5
    gboolean (* callback) (GObject             *instance,
                           const gchar         *action_name,
                           guint                key_val,
                           ClutterModifierType  modifiers,
                           gpointer             user_data);

The actor should then override the "key-press-event" and use `clutter_binding_pool_activate()` to match a ClutterKeyEvent structure to one of the actions:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    ClutterBindingPool *pool;

    /* retrieve the binding pool for the type of the actor */
    pool = clutter_binding_pool_find (G_OBJECT_TYPE_NAME (actor));

    /* activate any callback matching the key symbol and modifiers
     * mask of the key event. the returned value can be directly
     * used to signal that the actor has handled the event.
     */
    return clutter_binding_pool_activate (pool,
                                          key_event->keyval,
                                          key_event->modifier_state,
                                          G_OBJECT (actor));

The `clutter_binding_pool_activate()` function will return `FALSE` if no action for the given key binding was found, if the action was blocked (using `clutter_binding_pool_block_action()`) or if the key binding handler returned `FALSE`.

ClutterBindingPool is available since Clutter 1.0

## Details

### ClutterBindingPool

    typedef struct _ClutterBindingPool ClutterBindingPool;

Container of key bindings. The ClutterBindingPool struct is private.

Since 1.0

### ClutterBindingActionFunc ()

    gboolean            (*ClutterBindingActionFunc)         (GObject *gobject,
                                                             const gchar *action_name,
                                                             guint key_val,
                                                             ClutterModifierType modifiers);

The prototype for the callback function registered with `clutter_binding_pool_install_action()` and invoked by `clutter_binding_pool_activate()`.

`gobject` : | a GObject
`action_name` : | the name of the action
`key_val` : | the key symbol
`modifiers` : | bitmask of the modifier flags
Returns : | the function should return `TRUE` if the key binding has been handled, and return `FALSE` otherwise

Since 1.0

### clutter_binding_pool_new ()

    ClutterBindingPool * clutter_binding_pool_new           (const gchar *name);

Creates a new ClutterBindingPool that can be used to store key bindings for an actor. The `name` must be a unique identifier for the binding pool, so that `clutter_binding_pool_find()` will be able to return the correct binding pool.

`name` : | the name of the binding pool
Returns : | the newly created binding pool with the given name. Use `g_object_unref()` when done.

Since 1.0

### clutter_binding_pool_get_for_class ()

    ClutterBindingPool * clutter_binding_pool_get_for_class (gpointer klass);

Retrieves the ClutterBindingPool for the given GObject class and, eventually, creates it. This function is a wrapper around `clutter_binding_pool_new()` and uses the class type name as the unique name for the binding pool.

Calling this function multiple times will return the same ClutterBindingPool.

A binding pool for a class can also be retrieved using `clutter_binding_pool_find()` with the class type name:

    1
    pool = clutter_binding_pool_find (G_OBJECT_TYPE_NAME (instance));

`klass` : | a GObjectClass pointer
Returns : | the binding pool for the given class. The returned ClutterBindingPool is owned by Clutter and should not be freed directly. [transfer none]

Since 1.0

### clutter_binding_pool_find ()

    ClutterBindingPool * clutter_binding_pool_find          (const gchar *name);

Finds the ClutterBindingPool with `name`.

`name` : | the name of the binding pool to find
Returns : | a pointer to the ClutterBindingPool, or `NULL`. [transfer none]

Since 1.0

### clutter_binding_pool_install_action ()

    void                clutter_binding_pool_install_action (ClutterBindingPool *pool,
                                                             const gchar *action_name,
                                                             guint key_val,
                                                             ClutterModifierType modifiers,
                                                             GCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify notify);

Installs a new action inside a ClutterBindingPool. The action is bound to `key_val` and `modifiers`.

The same action name can be used for multiple `key_val`, `modifiers` pairs.

When an action has been activated using `clutter_binding_pool_activate()` the passed `callback` will be invoked (with `data`).

Actions can be blocked with `clutter_binding_pool_block_action()` and then unblocked using `clutter_binding_pool_unblock_action()`.

`pool` : | a ClutterBindingPool
`action_name` : | the name of the action
`key_val` : | key symbol
`modifiers` : | bitmask of modifiers
`callback` : | function to be called when the action is activated
`data` : | data to be passed to `callback`
`notify` : | function to be called when the action is removed from the pool

Since 1.0

### clutter_binding_pool_install_closure ()

    void                clutter_binding_pool_install_closure
                                                            (ClutterBindingPool *pool,
                                                             const gchar *action_name,
                                                             guint key_val,
                                                             ClutterModifierType modifiers,
                                                             GClosure *closure);

A GClosure variant of `clutter_binding_pool_install_action()`.

Installs a new action inside a ClutterBindingPool. The action is bound to `key_val` and `modifiers`.

The same action name can be used for multiple `key_val`, `modifiers` pairs.

When an action has been activated using `clutter_binding_pool_activate()` the passed `closure` will be invoked.

Actions can be blocked with `clutter_binding_pool_block_action()` and then unblocked using `clutter_binding_pool_unblock_action()`.

`pool` : | a ClutterBindingPool
`action_name` : | the name of the action
`key_val` : | key symbol
`modifiers` : | bitmask of modifiers
`closure` : | a GClosure

Since 1.0

### clutter_binding_pool_override_action ()

    void                clutter_binding_pool_override_action
                                                            (ClutterBindingPool *pool,
                                                             guint key_val,
                                                             ClutterModifierType modifiers,
                                                             GCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify notify);

Allows overriding the action for `key_val` and `modifiers` inside a ClutterBindingPool. See `clutter_binding_pool_install_action()`.

When an action has been activated using `clutter_binding_pool_activate()` the passed `callback` will be invoked (with `data`).

Actions can be blocked with `clutter_binding_pool_block_action()` and then unblocked using `clutter_binding_pool_unblock_action()`.

`pool` : | a ClutterBindingPool
`key_val` : | key symbol
`modifiers` : | bitmask of modifiers
`callback` : | function to be called when the action is activated
`data` : | data to be passed to `callback`
`notify` : | function to be called when the action is removed from the pool

Since 1.0

### clutter_binding_pool_override_closure ()

    void                clutter_binding_pool_override_closure
                                                            (ClutterBindingPool *pool,
                                                             guint key_val,
                                                             ClutterModifierType modifiers,
                                                             GClosure *closure);

A GClosure variant of `clutter_binding_pool_override_action()`.

Allows overriding the action for `key_val` and `modifiers` inside a ClutterBindingPool. See `clutter_binding_pool_install_closure()`.

When an action has been activated using `clutter_binding_pool_activate()` the passed `callback` will be invoked (with `data`).

Actions can be blocked with `clutter_binding_pool_block_action()` and then unblocked using `clutter_binding_pool_unblock_action()`.

`pool` : | a ClutterBindingPool
`key_val` : | key symbol
`modifiers` : | bitmask of modifiers
`closure` : | a GClosure

Since 1.0

### clutter_binding_pool_find_action ()

    const gchar *       clutter_binding_pool_find_action    (ClutterBindingPool *pool,
                                                             guint key_val,
                                                             ClutterModifierType modifiers);

Retrieves the name of the action matching the given key symbol and modifiers bitmask.

`pool` : | a ClutterBindingPool
`key_val` : | a key symbol
`modifiers` : | a bitmask for the modifiers
Returns : | the name of the action, if found, or `NULL`. The returned string is owned by the binding pool and should never be modified or freed

Since 1.0

### clutter_binding_pool_remove_action ()

    void                clutter_binding_pool_remove_action  (ClutterBindingPool *pool,
                                                             guint key_val,
                                                             ClutterModifierType modifiers);

Removes the action matching the given `key_val`, `modifiers` pair, if any exists.

`pool` : | a ClutterBindingPool
`key_val` : | a key symbol
`modifiers` : | a bitmask for the modifiers

Since 1.0

### clutter_binding_pool_block_action ()

    void                clutter_binding_pool_block_action   (ClutterBindingPool *pool,
                                                             const gchar *action_name);

Blocks all the actions with name `action_name` inside `pool`.

`pool` : | a ClutterBindingPool
`action_name` : | an action name

Since 1.0

### clutter_binding_pool_unblock_action ()

    void                clutter_binding_pool_unblock_action (ClutterBindingPool *pool,
                                                             const gchar *action_name);

Unblockes all the actions with name `action_name` inside `pool`.

Unblocking an action does not cause the callback bound to it to be invoked in case `clutter_binding_pool_activate()` was called on an action previously blocked with `clutter_binding_pool_block_action()`.

`pool` : | a ClutterBindingPool
`action_name` : | an action name

Since 1.0

### clutter_binding_pool_activate ()

    gboolean            clutter_binding_pool_activate       (ClutterBindingPool *pool,
                                                             guint key_val,
                                                             ClutterModifierType modifiers,
                                                             GObject *gobject);

Activates the callback associated to the action that is bound to the `key_val` and `modifiers` pair.

The callback has the following signature:

    1
    2
    3
    4
    5
    void (* callback) (GObject             *gobject,
                       const gchar         *action_name,
                       guint                key_val,
                       ClutterModifierType  modifiers,
                       gpointer             user_data);

Where the GObject instance is `gobject` and the user data is the one passed when installing the action with `clutter_binding_pool_install_action()`.

If the action bound to the `key_val`, `modifiers` pair has been blocked using `clutter_binding_pool_block_action()`, the callback will not be invoked, and this function will return `FALSE`.

`pool` : | a ClutterBindingPool
`key_val` : | the key symbol
`modifiers` : | bitmask for the modifiers
`gobject` : | a GObject
Returns : | `TRUE` if an action was found and was activated

Since 1.0

## Property Details

### The `"name"` property

      "name"                     gchar*                : Read / Write / Construct Only

The unique name of the ClutterBindingPool.

Default value: NULL

Since 1.0