
@c %start of fragment

@node Key Bindings
@chapter Key Bindings
Pool for key bindings

@section Overview
@code{<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
@code{<clutter-binding-pool>} inside their class initialization function
and then install actions like this:

@example 

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);
@}
@end example

The callback has a signature of:

@example 

   gboolean (* callback) (GObject             *instance,
                          const gchar         *action_name,
                          guint                key_val,
                          ClutterModifierType  modifiers,
                          gpointer             user_data);
@end example

The actor should then override the @code{<"key-press-event">} and use
@code{clutter-binding-pool-activate} to match a
@code{<clutter-key-event>} structure to one of the actions:

@example 

  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));
@end example

The @code{clutter-binding-pool-activate} function will return
@samp{@code{#f}} if no action for the given key binding was found, if
the action was blocked (using @code{clutter-binding-pool-block-action})
or if the key binding handler returned @samp{@code{#f}}.

@code{<clutter-binding-pool>} is available since Clutter 1.0

@section Usage
@include defuns-clutter-binding-pool.xml.texi

@c %end of fragment
