Next: , Previous: ClutterBoxLayout, Up: Top

13 Key Bindings

Pool for key bindings

13.1 Overview

<clutter-binding-pool> 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 <clutter-binding-pool> inside their class initialization function and then install actions like this: 

     
     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: 

     
        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 <clutter-key-event> structure to one of the actions: 

     
       ClutterBindingPool *pool;
     
       /&#x002A; retrieve the binding pool for the type of the actor &#x002A;/
       pool = clutter_binding_pool_find (G_OBJECT_TYPE_NAME (actor));
     
       /&#x002A; activate any callback matching the key symbol and modifiers
        &#x002A; mask of the key event. the returned value can be directly
        &#x002A; used to signal that the actor has handled the event.
        &#x002A;/
       return clutter_binding_pool_activate (pool,
                                             key_event->keyval,
                                             key_event->modifier_state,
                                             G_OBJECT (actor));

The clutter-binding-pool-activate function will return ‘#f’ 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 ‘#f’.

<clutter-binding-pool> is available since Clutter 1.0

13.2 Usage

— Function: clutter-binding-pool-new (name mchars) ⇒  (ret <clutter-binding-pool>)

Creates a new <clutter-binding-pool> 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
ret
the newly created binding pool with the given name. Use g-object-unref when done.

Since 1.0

— Function: clutter-binding-pool-get-for-class (klass <g-object-class>) ⇒  (ret <clutter-binding-pool>)

Retrieves the <clutter-binding-pool> 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 <clutter-binding-pool>.

A binding pool for a class can also be retrieved using clutter-binding-pool-find with the class type name: 

          
            pool = clutter_binding_pool_find (G_OBJECT_TYPE_NAME (instance));
klass
a <g-object-class> pointer
ret
the binding pool for the given class. The returned <clutter-binding-pool> is owned by Clutter and should not be freed directly.

Since 1.0

— Function: clutter-binding-pool-find (name mchars) ⇒  (ret <clutter-binding-pool>)

Finds the <clutter-binding-pool> with name.

name
the name of the binding pool to find
ret
a pointer to the <clutter-binding-pool>, or ‘#f’.

Since 1.0

— Function: clutter-binding-pool-find-action (self <clutter-binding-pool>) (key_val unsigned-int) (modifiers <clutter-modifier-type>) ⇒  (ret mchars)
— Method: find-action

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

pool
a <clutter-binding-pool>
key-val
a key symbol
modifiers
a bitmask for the modifiers
ret
the name of the action, if found, or ‘#f’. The returned string is owned by the binding pool and should never be modified or freed

Since 1.0

— Function: clutter-binding-pool-remove-action (self <clutter-binding-pool>) (key_val unsigned-int) (modifiers <clutter-modifier-type>)
— Method: remove-action

Removes the action matching the given key-val, modifiers pair, if any exists.

pool
a <clutter-binding-pool>
key-val
a key symbol
modifiers
a bitmask for the modifiers

Since 1.0

— Function: clutter-binding-pool-block-action (self <clutter-binding-pool>) (action_name mchars)
— Method: block-action

Blocks all the actions with name action-name inside pool.

pool
a <clutter-binding-pool>
action-name
an action name

Since 1.0

— Function: clutter-binding-pool-unblock-action (self <clutter-binding-pool>) (action_name mchars)
— Method: unblock-action

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 <clutter-binding-pool>
action-name
an action name

Since 1.0

— Function: clutter-binding-pool-activate (self <clutter-binding-pool>) (key_val unsigned-int) (modifiers <clutter-modifier-type>) (gobject <gobject>) ⇒  (ret bool)
— Method: activate

Activates the callback associated to the action that is bound to the key-val and modifiers pair.

The callback has the following signature: 

          
            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 ‘#f’.

pool
a <clutter-binding-pool>
key-val
the key symbol
modifiers
bitmask for the modifiers
gobject
a <gobject>
ret
‘#t’ if an action was found and was activated

Since 1.0