Top | ![]() |
![]() |
![]() |
![]() |
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 |
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
gboolean (*ClutterBindingActionFunc) (GObject *gobject
,const gchar *action_name
,guint key_val
,ClutterModifierType modifiers
,gpointer user_data
);
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 |
|
user_data |
data passed to the function |
the function should return TRUE
if the key
binding has been handled, and return FALSE
otherwise
Since: 1.0
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.
Since: 1.0
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)); |
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
ClutterBindingPool *
clutter_binding_pool_find (const gchar *name
);
Finds the ClutterBindingPool with name
.
Since: 1.0
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 |
||
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. |
[type Clutter.BindingActionFunc] |
data |
data to be passed to |
|
notify |
function to be called when the action is removed from the pool |
Since: 1.0
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 |
||
action_name |
the name of the action |
|
key_val |
key symbol |
|
modifiers |
bitmask of modifiers |
|
closure |
a GClosure |
Since: 1.0
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 |
||
key_val |
key symbol |
|
modifiers |
bitmask of modifiers |
|
callback |
function to be called when the action is activated. |
[type Clutter.BindingActionFunc] |
data |
data to be passed to |
|
notify |
function to be called when the action is removed from the pool |
Since: 1.0
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()
.
Since: 1.0
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.
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
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.
Since: 1.0
void clutter_binding_pool_block_action (ClutterBindingPool *pool
,const gchar *action_name
);
Blocks all the actions with name action_name
inside pool
.
Since: 1.0
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()
.
Since: 1.0
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
.
Since: 1.0
typedef struct _ClutterBindingPool ClutterBindingPool;
Container of key bindings. The ClutterBindingPool struct is private.
Since: 1.0
“name”
property “name” char *
The unique name of the ClutterBindingPool.
Owner: ClutterBindingPool
Flags: Read / Write / Construct Only
Default value: NULL
Since: 1.0