← Back to branch summary

~ubuntu-branches/ubuntu/vivid/clutter-1.0/vivid-proposed

« back to all changes in this revision

Viewing changes to doc/reference/clutter/xml/clutter-binding-pool.xml

  • Committer: Bazaar Package Importer
  • Author(s): Emilio Pozuelo Monfort
  • Date: 2010-07-18 17:21:49 UTC
  • mfrom: (1.2.1 upstream) (4.1.3 experimental)
  • Revision ID: james.westby@ubuntu.com-20100718172149-j6s9u4chocaoykme
Tags: 1.2.12-1
* New upstream release.
* debian/libclutter-1.0-0.symbols,
  debian/rules:
  - Add a symbols file.
* debian/rules,
  debian/source/format:
  - Switch to source format 3.0 (quilt).
* debian/control.in:
  - Standards-Version is 3.9.0, no changes needed.
* Upload to unstable.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/reference/clutter/xml/clutter-binding-pool.xml
1
 
<?xml version="1.0"?>
2
 
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3
 
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
4
 
<!ENTITY version "1.0.8">
5
 
]>
6
 
 
7
 
<refentry id="clutter-Key-Bindings">
8
 
<refmeta>
9
 
<refentrytitle role="top_of_page" id="clutter-Key-Bindings.top_of_page">Key Bindings</refentrytitle>
10
 
<manvolnum>3</manvolnum>
11
 
<refmiscinfo>CLUTTER Library</refmiscinfo>
12
 
</refmeta>
13
 
 
14
 
<refnamediv>
15
 
<refname>Key Bindings</refname>
16
 
<refpurpose>Pool for key bindings</refpurpose>
17
 
</refnamediv>
18
 
 
19
 
<refsynopsisdiv id="clutter-Key-Bindings.synopsis" role="synopsis">
20
 
<title role="synopsis.title">Synopsis</title>
21
 
<anchor id="ClutterBindingPool"/>
22
 
<synopsis>
23
 
                    <link linkend="ClutterBindingPool-struct">ClutterBindingPool</link>;
24
 
<link linkend="gboolean">gboolean</link>            (<link linkend="ClutterBindingActionFunc">*ClutterBindingActionFunc</link>)         (<link linkend="GObject">GObject</link> *gobject,
25
 
                                                         const <link linkend="gchar">gchar</link> *action_name,
26
 
                                                         <link linkend="guint">guint</link> key_val,
27
 
                                                         <link linkend="ClutterModifierType">ClutterModifierType</link> modifiers);
28
 
 
29
 
<link linkend="ClutterBindingPool">ClutterBindingPool</link> * <link linkend="clutter-binding-pool-new">clutter_binding_pool_new</link>           (const <link linkend="gchar">gchar</link> *name);
30
 
<link linkend="ClutterBindingPool">ClutterBindingPool</link> * <link linkend="clutter-binding-pool-get-for-class">clutter_binding_pool_get_for_class</link> (<link linkend="gpointer">gpointer</link> klass);
31
 
<link linkend="ClutterBindingPool">ClutterBindingPool</link> * <link linkend="clutter-binding-pool-find">clutter_binding_pool_find</link>          (const <link linkend="gchar">gchar</link> *name);
32
 
 
33
 
<link linkend="void">void</link>                <link linkend="clutter-binding-pool-install-action">clutter_binding_pool_install_action</link> (<link linkend="ClutterBindingPool">ClutterBindingPool</link> *pool,
34
 
                                                         const <link linkend="gchar">gchar</link> *action_name,
35
 
                                                         <link linkend="guint">guint</link> key_val,
36
 
                                                         <link linkend="ClutterModifierType">ClutterModifierType</link> modifiers,
37
 
                                                         <link linkend="GCallback">GCallback</link> callback,
38
 
                                                         <link linkend="gpointer">gpointer</link> data,
39
 
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> notify);
40
 
<link linkend="void">void</link>                <link linkend="clutter-binding-pool-install-closure">clutter_binding_pool_install_closure</link>
41
 
                                                        (<link linkend="ClutterBindingPool">ClutterBindingPool</link> *pool,
42
 
                                                         const <link linkend="gchar">gchar</link> *action_name,
43
 
                                                         <link linkend="guint">guint</link> key_val,
44
 
                                                         <link linkend="ClutterModifierType">ClutterModifierType</link> modifiers,
45
 
                                                         <link linkend="GClosure">GClosure</link> *closure);
46
 
<link linkend="void">void</link>                <link linkend="clutter-binding-pool-override-action">clutter_binding_pool_override_action</link>
47
 
                                                        (<link linkend="ClutterBindingPool">ClutterBindingPool</link> *pool,
48
 
                                                         <link linkend="guint">guint</link> key_val,
49
 
                                                         <link linkend="ClutterModifierType">ClutterModifierType</link> modifiers,
50
 
                                                         <link linkend="GCallback">GCallback</link> callback,
51
 
                                                         <link linkend="gpointer">gpointer</link> data,
52
 
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> notify);
53
 
<link linkend="void">void</link>                <link linkend="clutter-binding-pool-override-closure">clutter_binding_pool_override_closure</link>
54
 
                                                        (<link linkend="ClutterBindingPool">ClutterBindingPool</link> *pool,
55
 
                                                         <link linkend="guint">guint</link> key_val,
56
 
                                                         <link linkend="ClutterModifierType">ClutterModifierType</link> modifiers,
57
 
                                                         <link linkend="GClosure">GClosure</link> *closure);
58
 
const <link linkend="gchar">gchar</link> *       <link linkend="clutter-binding-pool-find-action">clutter_binding_pool_find_action</link>    (<link linkend="ClutterBindingPool">ClutterBindingPool</link> *pool,
59
 
                                                         <link linkend="guint">guint</link> key_val,
60
 
                                                         <link linkend="ClutterModifierType">ClutterModifierType</link> modifiers);
61
 
<link linkend="void">void</link>                <link linkend="clutter-binding-pool-remove-action">clutter_binding_pool_remove_action</link>  (<link linkend="ClutterBindingPool">ClutterBindingPool</link> *pool,
62
 
                                                         <link linkend="guint">guint</link> key_val,
63
 
                                                         <link linkend="ClutterModifierType">ClutterModifierType</link> modifiers);
64
 
<link linkend="void">void</link>                <link linkend="clutter-binding-pool-block-action">clutter_binding_pool_block_action</link>   (<link linkend="ClutterBindingPool">ClutterBindingPool</link> *pool,
65
 
                                                         const <link linkend="gchar">gchar</link> *action_name);
66
 
<link linkend="void">void</link>                <link linkend="clutter-binding-pool-unblock-action">clutter_binding_pool_unblock_action</link> (<link linkend="ClutterBindingPool">ClutterBindingPool</link> *pool,
67
 
                                                         const <link linkend="gchar">gchar</link> *action_name);
68
 
 
69
 
<link linkend="gboolean">gboolean</link>            <link linkend="clutter-binding-pool-activate">clutter_binding_pool_activate</link>       (<link linkend="ClutterBindingPool">ClutterBindingPool</link> *pool,
70
 
                                                         <link linkend="guint">guint</link> key_val,
71
 
                                                         <link linkend="ClutterModifierType">ClutterModifierType</link> modifiers,
72
 
                                                         <link linkend="GObject">GObject</link> *gobject);
73
 
</synopsis>
74
 
</refsynopsisdiv>
75
 
 
76
 
<refsect1 id="clutter-Key-Bindings.object-hierarchy" role="object_hierarchy">
77
 
<title role="object_hierarchy.title">Object Hierarchy</title>
78
 
<synopsis>
79
 
  <link linkend="GObject">GObject</link>
80
 
   +----ClutterBindingPool
81
 
</synopsis>
82
 
</refsect1>
83
 
 
84
 
 
85
 
 
86
 
 
87
 
 
88
 
 
89
 
 
90
 
 
91
 
<refsect1 id="clutter-Key-Bindings.description" role="desc">
92
 
<title role="desc.title">Description</title>
93
 
<para>
94
 
<link linkend="ClutterBindingPool"><type>ClutterBindingPool</type></link> is a data structure holding a set of key bindings.
95
 
Each key binding associates a key symbol (eventually with modifiers)
96
 
to an action. A callback function is associated to each action.
97
 
</para>
98
 
<para>
99
 
For a given key symbol and modifier mask combination there can be only one
100
 
action; for each action there can be only one callback. There can be
101
 
multiple actions with the same name, and the same callback can be used
102
 
to handle multiple key bindings.
103
 
</para>
104
 
<para>
105
 
Actors requiring key bindings should create a new <link linkend="ClutterBindingPool"><type>ClutterBindingPool</type></link>
106
 
inside their class initialization function and then install actions
107
 
like this:
108
 
</para>
109
 
<para>
110
 
<informalexample><programlisting>
111
 
static void
112
 
foo_class_init (FooClass *klass)
113
 
{
114
 
  ClutterBindingPool *binding_pool;
115
 
 
116
 
  binding_pool = clutter_binding_pool_get_for_class (klass);
117
 
 
118
 
  clutter_binding_pool_install_action (binding_pool, "move-up",
119
 
                                       CLUTTER_Up, 0,
120
 
                                       G_CALLBACK (foo_action_move_up),
121
 
                                       NULL, NULL);
122
 
  clutter_binding_pool_install_action (binding_pool, "move-up",
123
 
                                       CLUTTER_KP_Up, 0,
124
 
                                       G_CALLBACK (foo_action_move_up),
125
 
                                       NULL, NULL);
126
 
}
127
 
</programlisting></informalexample>
128
 
</para>
129
 
<para>
130
 
The callback has a signature of:
131
 
</para>
132
 
<para>
133
 
<informalexample><programlisting>
134
 
   gboolean (* callback) (GObject             *instance,
135
 
                          const gchar         *action_name,
136
 
                          guint                key_val,
137
 
                          ClutterModifierType  modifiers,
138
 
                          gpointer             user_data);
139
 
</programlisting></informalexample>
140
 
</para>
141
 
<para>
142
 
The actor should then override the <link linkend="ClutterActor-key-press-event"><type>"key-press-event"</type></link> and
143
 
use <link linkend="clutter-binding-pool-activate"><function>clutter_binding_pool_activate()</function></link> to match a <link linkend="ClutterKeyEvent"><type>ClutterKeyEvent</type></link> structure
144
 
to one of the actions:
145
 
</para>
146
 
<para>
147
 
<informalexample><programlisting>
148
 
  ClutterBindingPool *pool;
149
 
 
150
 
  /&ast; retrieve the binding pool for the type of the actor &ast;/
151
 
  pool = clutter_binding_pool_find (G_OBJECT_TYPE_NAME (actor));
152
 
 
153
 
  /&ast; activate any callback matching the key symbol and modifiers
154
 
   &ast; mask of the key event. the returned value can be directly
155
 
   &ast; used to signal that the actor has handled the event.
156
 
   &ast;/
157
 
  return clutter_binding_pool_activate (pool, G_OBJECT (actor),
158
 
                                        key_event-&gt;keyval,
159
 
                                        key_event-&gt;modifier_state);
160
 
</programlisting></informalexample>
161
 
</para>
162
 
<para>
163
 
The <link linkend="clutter-binding-pool-activate"><function>clutter_binding_pool_activate()</function></link> function will return <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if
164
 
no action for the given key binding was found, if the action was
165
 
blocked (using <link linkend="clutter-binding-pool-block-action"><function>clutter_binding_pool_block_action()</function></link>) or if the
166
 
key binding handler returned <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>.
167
 
</para>
168
 
<para>
169
 
<link linkend="ClutterBindingPool"><type>ClutterBindingPool</type></link> is available since Clutter 1.0</para>
170
 
<para>
171
 
</para>
172
 
</refsect1>
173
 
 
174
 
<refsect1 id="clutter-Key-Bindings.details" role="details">
175
 
<title role="details.title">Details</title>
176
 
<refsect2 id="ClutterBindingPool-struct" role="struct">
177
 
<title>ClutterBindingPool</title>
178
 
<indexterm zone="ClutterBindingPool-struct" role="1.0"><primary sortas="BindingPool">ClutterBindingPool</primary></indexterm><programlisting>typedef struct _ClutterBindingPool ClutterBindingPool;</programlisting>
179
 
<para>
180
 
Container of key bindings. The <link linkend="ClutterBindingPool"><type>ClutterBindingPool</type></link> struct is
181
 
private.</para>
182
 
<para>
183
 
</para><para role="since">Since 1.0</para></refsect2>
184
 
<refsect2 id="ClutterBindingActionFunc" role="function" condition="since:1.0">
185
 
<title>ClutterBindingActionFunc ()</title>
186
 
<indexterm zone="ClutterBindingActionFunc" role="1.0"><primary sortas="BindingActionFunc">ClutterBindingActionFunc</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            (*ClutterBindingActionFunc)         (<link linkend="GObject">GObject</link> *gobject,
187
 
                                                         const <link linkend="gchar">gchar</link> *action_name,
188
 
                                                         <link linkend="guint">guint</link> key_val,
189
 
                                                         <link linkend="ClutterModifierType">ClutterModifierType</link> modifiers);</programlisting>
190
 
<para>
191
 
The prototype for the callback function registered with
192
 
<link linkend="clutter-binding-pool-install-action"><function>clutter_binding_pool_install_action()</function></link> and invoked by
193
 
<link linkend="clutter-binding-pool-activate"><function>clutter_binding_pool_activate()</function></link>.</para>
194
 
<para>
195
 
</para><variablelist role="params">
196
 
<varlistentry><term><parameter>gobject</parameter>&#160;:</term>
197
 
<listitem><simpara> a <link linkend="GObject"><type>GObject</type></link>
198
 
</simpara></listitem></varlistentry>
199
 
<varlistentry><term><parameter>action_name</parameter>&#160;:</term>
200
 
<listitem><simpara> the name of the action
201
 
</simpara></listitem></varlistentry>
202
 
<varlistentry><term><parameter>key_val</parameter>&#160;:</term>
203
 
<listitem><simpara> the key symbol
204
 
</simpara></listitem></varlistentry>
205
 
<varlistentry><term><parameter>modifiers</parameter>&#160;:</term>
206
 
<listitem><simpara> bitmask of the modifier flags
207
 
</simpara></listitem></varlistentry>
208
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the function should return <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the key
209
 
  binding has been handled, and return <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> otherwise
210
 
 
211
 
</simpara></listitem></varlistentry>
212
 
</variablelist><para role="since">Since 1.0</para></refsect2>
213
 
<refsect2 id="clutter-binding-pool-new" role="function" condition="since:1.0">
214
 
<title>clutter_binding_pool_new ()</title>
215
 
<indexterm zone="clutter-binding-pool-new" role="1.0"><primary sortas="binding_pool_new">clutter_binding_pool_new</primary></indexterm><programlisting><link linkend="ClutterBindingPool">ClutterBindingPool</link> * clutter_binding_pool_new           (const <link linkend="gchar">gchar</link> *name);</programlisting>
216
 
<para>
217
 
Creates a new <link linkend="ClutterBindingPool"><type>ClutterBindingPool</type></link> that can be used to store
218
 
key bindings for an actor. The <parameter>name</parameter> must be a unique identifier
219
 
for the binding pool, so that <link linkend="clutter-binding-pool-find"><function>clutter_binding_pool_find()</function></link> will
220
 
be able to return the correct binding pool.</para>
221
 
<para>
222
 
</para><variablelist role="params">
223
 
<varlistentry><term><parameter>name</parameter>&#160;:</term>
224
 
<listitem><simpara> the name of the binding pool
225
 
</simpara></listitem></varlistentry>
226
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the newly created binding pool with the given
227
 
  name. Use <link linkend="g-object-unref"><function>g_object_unref()</function></link> when done.
228
 
 
229
 
</simpara></listitem></varlistentry>
230
 
</variablelist><para role="since">Since 1.0</para></refsect2>
231
 
<refsect2 id="clutter-binding-pool-get-for-class" role="function" condition="since:1.0">
232
 
<title>clutter_binding_pool_get_for_class ()</title>
233
 
<indexterm zone="clutter-binding-pool-get-for-class" role="1.0"><primary sortas="binding_pool_get_for_class">clutter_binding_pool_get_for_class</primary></indexterm><programlisting><link linkend="ClutterBindingPool">ClutterBindingPool</link> * clutter_binding_pool_get_for_class (<link linkend="gpointer">gpointer</link> klass);</programlisting>
234
 
<para>
235
 
Retrieves the <link linkend="ClutterBindingPool"><type>ClutterBindingPool</type></link> for the given <link linkend="GObject"><type>GObject</type></link> class
236
 
and, eventually, creates it. This function is a wrapper around
237
 
<link linkend="clutter-binding-pool-new"><function>clutter_binding_pool_new()</function></link> and uses the class type name as the
238
 
unique name for the binding pool.
239
 
</para>
240
 
<para>
241
 
Calling this function multiple times will return the same
242
 
<link linkend="ClutterBindingPool"><type>ClutterBindingPool</type></link>.
243
 
</para>
244
 
<para>
245
 
A binding pool for a class can also be retrieved using
246
 
<link linkend="clutter-binding-pool-find"><function>clutter_binding_pool_find()</function></link> with the class type name:
247
 
</para>
248
 
<para>
249
 
<informalexample><programlisting>
250
 
  pool = clutter_binding_pool_find (G_OBJECT_TYPE_NAME (instance));
251
 
</programlisting></informalexample></para>
252
 
<para>
253
 
</para><variablelist role="params">
254
 
<varlistentry><term><parameter>klass</parameter>&#160;:</term>
255
 
<listitem><simpara> a <link linkend="GObjectClass"><type>GObjectClass</type></link> pointer
256
 
</simpara></listitem></varlistentry>
257
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>transfer none. <acronym>transfer</acronym> none. </simpara></listitem></varlistentry>
258
 
</variablelist><para role="since">Since 1.0</para></refsect2>
259
 
<refsect2 id="clutter-binding-pool-find" role="function" condition="since:1.0">
260
 
<title>clutter_binding_pool_find ()</title>
261
 
<indexterm zone="clutter-binding-pool-find" role="1.0"><primary sortas="binding_pool_find">clutter_binding_pool_find</primary></indexterm><programlisting><link linkend="ClutterBindingPool">ClutterBindingPool</link> * clutter_binding_pool_find          (const <link linkend="gchar">gchar</link> *name);</programlisting>
262
 
<para>
263
 
Finds the <link linkend="ClutterBindingPool"><type>ClutterBindingPool</type></link> with <parameter>name</parameter>.</para>
264
 
<para>
265
 
</para><variablelist role="params">
266
 
<varlistentry><term><parameter>name</parameter>&#160;:</term>
267
 
<listitem><simpara> the name of the binding pool to find
268
 
</simpara></listitem></varlistentry>
269
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a pointer to the <link linkend="ClutterBindingPool"><type>ClutterBindingPool</type></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>. <acronym>transfer</acronym> none. </simpara></listitem></varlistentry>
270
 
</variablelist><para role="since">Since 1.0</para></refsect2>
271
 
<refsect2 id="clutter-binding-pool-install-action" role="function" condition="since:1.0">
272
 
<title>clutter_binding_pool_install_action ()</title>
273
 
<indexterm zone="clutter-binding-pool-install-action" role="1.0"><primary sortas="binding_pool_install_action">clutter_binding_pool_install_action</primary></indexterm><programlisting><link linkend="void">void</link>                clutter_binding_pool_install_action (<link linkend="ClutterBindingPool">ClutterBindingPool</link> *pool,
274
 
                                                         const <link linkend="gchar">gchar</link> *action_name,
275
 
                                                         <link linkend="guint">guint</link> key_val,
276
 
                                                         <link linkend="ClutterModifierType">ClutterModifierType</link> modifiers,
277
 
                                                         <link linkend="GCallback">GCallback</link> callback,
278
 
                                                         <link linkend="gpointer">gpointer</link> data,
279
 
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> notify);</programlisting>
280
 
<para>
281
 
Installs a new action inside a <link linkend="ClutterBindingPool"><type>ClutterBindingPool</type></link>. The action
282
 
is bound to <parameter>key_val</parameter> and <parameter>modifiers</parameter>.
283
 
</para>
284
 
<para>
285
 
The same action name can be used for multiple <parameter>key_val</parameter>, <parameter>modifiers</parameter>
286
 
pairs.
287
 
</para>
288
 
<para>
289
 
When an action has been activated using <link linkend="clutter-binding-pool-activate"><function>clutter_binding_pool_activate()</function></link>
290
 
the passed <parameter>callback</parameter> will be invoked (with <parameter>data</parameter>).
291
 
</para>
292
 
<para>
293
 
Actions can be blocked with <link linkend="clutter-binding-pool-block-action"><function>clutter_binding_pool_block_action()</function></link>
294
 
and then unblocked using <link linkend="clutter-binding-pool-unblock-action"><function>clutter_binding_pool_unblock_action()</function></link>.</para>
295
 
<para>
296
 
</para><variablelist role="params">
297
 
<varlistentry><term><parameter>pool</parameter>&#160;:</term>
298
 
<listitem><simpara> a <link linkend="ClutterBindingPool"><type>ClutterBindingPool</type></link>
299
 
</simpara></listitem></varlistentry>
300
 
<varlistentry><term><parameter>action_name</parameter>&#160;:</term>
301
 
<listitem><simpara> the name of the action
302
 
</simpara></listitem></varlistentry>
303
 
<varlistentry><term><parameter>key_val</parameter>&#160;:</term>
304
 
<listitem><simpara> key symbol
305
 
</simpara></listitem></varlistentry>
306
 
<varlistentry><term><parameter>modifiers</parameter>&#160;:</term>
307
 
<listitem><simpara> bitmask of modifiers
308
 
</simpara></listitem></varlistentry>
309
 
<varlistentry><term><parameter>callback</parameter>&#160;:</term>
310
 
<listitem><simpara> function to be called when the action is activated
311
 
</simpara></listitem></varlistentry>
312
 
<varlistentry><term><parameter>data</parameter>&#160;:</term>
313
 
<listitem><simpara> data to be passed to <parameter>callback</parameter>
314
 
</simpara></listitem></varlistentry>
315
 
<varlistentry><term><parameter>notify</parameter>&#160;:</term>
316
 
<listitem><simpara> function to be called when the action is removed
317
 
  from the pool
318
 
</simpara></listitem></varlistentry>
319
 
</variablelist><para role="since">Since 1.0</para></refsect2>
320
 
<refsect2 id="clutter-binding-pool-install-closure" role="function" condition="since:1.0">
321
 
<title>clutter_binding_pool_install_closure ()</title>
322
 
<indexterm zone="clutter-binding-pool-install-closure" role="1.0"><primary sortas="binding_pool_install_closure">clutter_binding_pool_install_closure</primary></indexterm><programlisting><link linkend="void">void</link>                clutter_binding_pool_install_closure
323
 
                                                        (<link linkend="ClutterBindingPool">ClutterBindingPool</link> *pool,
324
 
                                                         const <link linkend="gchar">gchar</link> *action_name,
325
 
                                                         <link linkend="guint">guint</link> key_val,
326
 
                                                         <link linkend="ClutterModifierType">ClutterModifierType</link> modifiers,
327
 
                                                         <link linkend="GClosure">GClosure</link> *closure);</programlisting>
328
 
<para>
329
 
A <link linkend="GClosure"><type>GClosure</type></link> variant of <link linkend="clutter-binding-pool-install-action"><function>clutter_binding_pool_install_action()</function></link>.
330
 
</para>
331
 
<para>
332
 
Installs a new action inside a <link linkend="ClutterBindingPool"><type>ClutterBindingPool</type></link>. The action
333
 
is bound to <parameter>key_val</parameter> and <parameter>modifiers</parameter>.
334
 
</para>
335
 
<para>
336
 
The same action name can be used for multiple <parameter>key_val</parameter>, <parameter>modifiers</parameter>
337
 
pairs.
338
 
</para>
339
 
<para>
340
 
When an action has been activated using <link linkend="clutter-binding-pool-activate"><function>clutter_binding_pool_activate()</function></link>
341
 
the passed <parameter>closure</parameter> will be invoked.
342
 
</para>
343
 
<para>
344
 
Actions can be blocked with <link linkend="clutter-binding-pool-block-action"><function>clutter_binding_pool_block_action()</function></link>
345
 
and then unblocked using <link linkend="clutter-binding-pool-unblock-action"><function>clutter_binding_pool_unblock_action()</function></link>.</para>
346
 
<para>
347
 
</para><variablelist role="params">
348
 
<varlistentry><term><parameter>pool</parameter>&#160;:</term>
349
 
<listitem><simpara> a <link linkend="ClutterBindingPool"><type>ClutterBindingPool</type></link>
350
 
</simpara></listitem></varlistentry>
351
 
<varlistentry><term><parameter>action_name</parameter>&#160;:</term>
352
 
<listitem><simpara> the name of the action
353
 
</simpara></listitem></varlistentry>
354
 
<varlistentry><term><parameter>key_val</parameter>&#160;:</term>
355
 
<listitem><simpara> key symbol
356
 
</simpara></listitem></varlistentry>
357
 
<varlistentry><term><parameter>modifiers</parameter>&#160;:</term>
358
 
<listitem><simpara> bitmask of modifiers
359
 
</simpara></listitem></varlistentry>
360
 
<varlistentry><term><parameter>closure</parameter>&#160;:</term>
361
 
<listitem><simpara> a <link linkend="GClosure"><type>GClosure</type></link>
362
 
</simpara></listitem></varlistentry>
363
 
</variablelist><para role="since">Since 1.0</para></refsect2>
364
 
<refsect2 id="clutter-binding-pool-override-action" role="function" condition="since:1.0">
365
 
<title>clutter_binding_pool_override_action ()</title>
366
 
<indexterm zone="clutter-binding-pool-override-action" role="1.0"><primary sortas="binding_pool_override_action">clutter_binding_pool_override_action</primary></indexterm><programlisting><link linkend="void">void</link>                clutter_binding_pool_override_action
367
 
                                                        (<link linkend="ClutterBindingPool">ClutterBindingPool</link> *pool,
368
 
                                                         <link linkend="guint">guint</link> key_val,
369
 
                                                         <link linkend="ClutterModifierType">ClutterModifierType</link> modifiers,
370
 
                                                         <link linkend="GCallback">GCallback</link> callback,
371
 
                                                         <link linkend="gpointer">gpointer</link> data,
372
 
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> notify);</programlisting>
373
 
<para>
374
 
Allows overriding the action for <parameter>key_val</parameter> and <parameter>modifiers</parameter> inside a
375
 
<link linkend="ClutterBindingPool"><type>ClutterBindingPool</type></link>. See <link linkend="clutter-binding-pool-install-action"><function>clutter_binding_pool_install_action()</function></link>.
376
 
</para>
377
 
<para>
378
 
When an action has been activated using <link linkend="clutter-binding-pool-activate"><function>clutter_binding_pool_activate()</function></link>
379
 
the passed <parameter>callback</parameter> will be invoked (with <parameter>data</parameter>).
380
 
</para>
381
 
<para>
382
 
Actions can be blocked with <link linkend="clutter-binding-pool-block-action"><function>clutter_binding_pool_block_action()</function></link>
383
 
and then unblocked using <link linkend="clutter-binding-pool-unblock-action"><function>clutter_binding_pool_unblock_action()</function></link>.</para>
384
 
<para>
385
 
</para><variablelist role="params">
386
 
<varlistentry><term><parameter>pool</parameter>&#160;:</term>
387
 
<listitem><simpara> a <link linkend="ClutterBindingPool"><type>ClutterBindingPool</type></link>
388
 
</simpara></listitem></varlistentry>
389
 
<varlistentry><term><parameter>key_val</parameter>&#160;:</term>
390
 
<listitem><simpara> key symbol
391
 
</simpara></listitem></varlistentry>
392
 
<varlistentry><term><parameter>modifiers</parameter>&#160;:</term>
393
 
<listitem><simpara> bitmask of modifiers
394
 
</simpara></listitem></varlistentry>
395
 
<varlistentry><term><parameter>callback</parameter>&#160;:</term>
396
 
<listitem><simpara> function to be called when the action is activated
397
 
</simpara></listitem></varlistentry>
398
 
<varlistentry><term><parameter>data</parameter>&#160;:</term>
399
 
<listitem><simpara> data to be passed to <parameter>callback</parameter>
400
 
</simpara></listitem></varlistentry>
401
 
<varlistentry><term><parameter>notify</parameter>&#160;:</term>
402
 
<listitem><simpara> function to be called when the action is removed
403
 
  from the pool
404
 
</simpara></listitem></varlistentry>
405
 
</variablelist><para role="since">Since 1.0</para></refsect2>
406
 
<refsect2 id="clutter-binding-pool-override-closure" role="function" condition="since:1.0">
407
 
<title>clutter_binding_pool_override_closure ()</title>
408
 
<indexterm zone="clutter-binding-pool-override-closure" role="1.0"><primary sortas="binding_pool_override_closure">clutter_binding_pool_override_closure</primary></indexterm><programlisting><link linkend="void">void</link>                clutter_binding_pool_override_closure
409
 
                                                        (<link linkend="ClutterBindingPool">ClutterBindingPool</link> *pool,
410
 
                                                         <link linkend="guint">guint</link> key_val,
411
 
                                                         <link linkend="ClutterModifierType">ClutterModifierType</link> modifiers,
412
 
                                                         <link linkend="GClosure">GClosure</link> *closure);</programlisting>
413
 
<para>
414
 
A <link linkend="GClosure"><type>GClosure</type></link> variant of <link linkend="clutter-binding-pool-override-action"><function>clutter_binding_pool_override_action()</function></link>.
415
 
</para>
416
 
<para>
417
 
Allows overriding the action for <parameter>key_val</parameter> and <parameter>modifiers</parameter> inside a
418
 
<link linkend="ClutterBindingPool"><type>ClutterBindingPool</type></link>. See <link linkend="clutter-binding-pool-install-closure"><function>clutter_binding_pool_install_closure()</function></link>.
419
 
</para>
420
 
<para>
421
 
When an action has been activated using <link linkend="clutter-binding-pool-activate"><function>clutter_binding_pool_activate()</function></link>
422
 
the passed <parameter>callback</parameter> will be invoked (with <parameter>data</parameter>).
423
 
</para>
424
 
<para>
425
 
Actions can be blocked with <link linkend="clutter-binding-pool-block-action"><function>clutter_binding_pool_block_action()</function></link>
426
 
and then unblocked using <link linkend="clutter-binding-pool-unblock-action"><function>clutter_binding_pool_unblock_action()</function></link>.</para>
427
 
<para>
428
 
</para><variablelist role="params">
429
 
<varlistentry><term><parameter>pool</parameter>&#160;:</term>
430
 
<listitem><simpara> a <link linkend="ClutterBindingPool"><type>ClutterBindingPool</type></link>
431
 
</simpara></listitem></varlistentry>
432
 
<varlistentry><term><parameter>key_val</parameter>&#160;:</term>
433
 
<listitem><simpara> key symbol
434
 
</simpara></listitem></varlistentry>
435
 
<varlistentry><term><parameter>modifiers</parameter>&#160;:</term>
436
 
<listitem><simpara> bitmask of modifiers
437
 
</simpara></listitem></varlistentry>
438
 
<varlistentry><term><parameter>closure</parameter>&#160;:</term>
439
 
<listitem><simpara> a <link linkend="GClosure"><type>GClosure</type></link>
440
 
</simpara></listitem></varlistentry>
441
 
</variablelist><para role="since">Since 1.0</para></refsect2>
442
 
<refsect2 id="clutter-binding-pool-find-action" role="function" condition="since:1.0">
443
 
<title>clutter_binding_pool_find_action ()</title>
444
 
<indexterm zone="clutter-binding-pool-find-action" role="1.0"><primary sortas="binding_pool_find_action">clutter_binding_pool_find_action</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link> *       clutter_binding_pool_find_action    (<link linkend="ClutterBindingPool">ClutterBindingPool</link> *pool,
445
 
                                                         <link linkend="guint">guint</link> key_val,
446
 
                                                         <link linkend="ClutterModifierType">ClutterModifierType</link> modifiers);</programlisting>
447
 
<para>
448
 
Retrieves the name of the action matching the given key symbol
449
 
and modifiers bitmask.</para>
450
 
<para>
451
 
</para><variablelist role="params">
452
 
<varlistentry><term><parameter>pool</parameter>&#160;:</term>
453
 
<listitem><simpara> a <link linkend="ClutterBindingPool"><type>ClutterBindingPool</type></link>
454
 
</simpara></listitem></varlistentry>
455
 
<varlistentry><term><parameter>key_val</parameter>&#160;:</term>
456
 
<listitem><simpara> a key symbol
457
 
</simpara></listitem></varlistentry>
458
 
<varlistentry><term><parameter>modifiers</parameter>&#160;:</term>
459
 
<listitem><simpara> a bitmask for the modifiers
460
 
</simpara></listitem></varlistentry>
461
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the name of the action, if found, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>. The
462
 
  returned string is owned by the binding pool and should never
463
 
  be modified or freed
464
 
 
465
 
</simpara></listitem></varlistentry>
466
 
</variablelist><para role="since">Since 1.0</para></refsect2>
467
 
<refsect2 id="clutter-binding-pool-remove-action" role="function" condition="since:1.0">
468
 
<title>clutter_binding_pool_remove_action ()</title>
469
 
<indexterm zone="clutter-binding-pool-remove-action" role="1.0"><primary sortas="binding_pool_remove_action">clutter_binding_pool_remove_action</primary></indexterm><programlisting><link linkend="void">void</link>                clutter_binding_pool_remove_action  (<link linkend="ClutterBindingPool">ClutterBindingPool</link> *pool,
470
 
                                                         <link linkend="guint">guint</link> key_val,
471
 
                                                         <link linkend="ClutterModifierType">ClutterModifierType</link> modifiers);</programlisting>
472
 
<para>
473
 
Removes the action matching the given <parameter>key_val</parameter>, <parameter>modifiers</parameter> pair,
474
 
if any exists.</para>
475
 
<para>
476
 
</para><variablelist role="params">
477
 
<varlistentry><term><parameter>pool</parameter>&#160;:</term>
478
 
<listitem><simpara> a <link linkend="ClutterBindingPool"><type>ClutterBindingPool</type></link>
479
 
</simpara></listitem></varlistentry>
480
 
<varlistentry><term><parameter>key_val</parameter>&#160;:</term>
481
 
<listitem><simpara> a key symbol
482
 
</simpara></listitem></varlistentry>
483
 
<varlistentry><term><parameter>modifiers</parameter>&#160;:</term>
484
 
<listitem><simpara> a bitmask for the modifiers
485
 
</simpara></listitem></varlistentry>
486
 
</variablelist><para role="since">Since 1.0</para></refsect2>
487
 
<refsect2 id="clutter-binding-pool-block-action" role="function" condition="since:1.0">
488
 
<title>clutter_binding_pool_block_action ()</title>
489
 
<indexterm zone="clutter-binding-pool-block-action" role="1.0"><primary sortas="binding_pool_block_action">clutter_binding_pool_block_action</primary></indexterm><programlisting><link linkend="void">void</link>                clutter_binding_pool_block_action   (<link linkend="ClutterBindingPool">ClutterBindingPool</link> *pool,
490
 
                                                         const <link linkend="gchar">gchar</link> *action_name);</programlisting>
491
 
<para>
492
 
Blocks all the actions with name <parameter>action_name</parameter> inside <parameter>pool</parameter>.</para>
493
 
<para>
494
 
</para><variablelist role="params">
495
 
<varlistentry><term><parameter>pool</parameter>&#160;:</term>
496
 
<listitem><simpara> a <link linkend="ClutterBindingPool"><type>ClutterBindingPool</type></link>
497
 
</simpara></listitem></varlistentry>
498
 
<varlistentry><term><parameter>action_name</parameter>&#160;:</term>
499
 
<listitem><simpara> an action name
500
 
</simpara></listitem></varlistentry>
501
 
</variablelist><para role="since">Since 1.0</para></refsect2>
502
 
<refsect2 id="clutter-binding-pool-unblock-action" role="function" condition="since:1.0">
503
 
<title>clutter_binding_pool_unblock_action ()</title>
504
 
<indexterm zone="clutter-binding-pool-unblock-action" role="1.0"><primary sortas="binding_pool_unblock_action">clutter_binding_pool_unblock_action</primary></indexterm><programlisting><link linkend="void">void</link>                clutter_binding_pool_unblock_action (<link linkend="ClutterBindingPool">ClutterBindingPool</link> *pool,
505
 
                                                         const <link linkend="gchar">gchar</link> *action_name);</programlisting>
506
 
<para>
507
 
Unblockes all the actions with name <parameter>action_name</parameter> inside <parameter>pool</parameter>.
508
 
</para>
509
 
<para>
510
 
Unblocking an action does not cause the callback bound to it to
511
 
be invoked in case <link linkend="clutter-binding-pool-activate"><function>clutter_binding_pool_activate()</function></link> was called on
512
 
an action previously blocked with <link linkend="clutter-binding-pool-block-action"><function>clutter_binding_pool_block_action()</function></link>.</para>
513
 
<para>
514
 
</para><variablelist role="params">
515
 
<varlistentry><term><parameter>pool</parameter>&#160;:</term>
516
 
<listitem><simpara> a <link linkend="ClutterBindingPool"><type>ClutterBindingPool</type></link>
517
 
</simpara></listitem></varlistentry>
518
 
<varlistentry><term><parameter>action_name</parameter>&#160;:</term>
519
 
<listitem><simpara> an action name
520
 
</simpara></listitem></varlistentry>
521
 
</variablelist><para role="since">Since 1.0</para></refsect2>
522
 
<refsect2 id="clutter-binding-pool-activate" role="function" condition="since:1.0">
523
 
<title>clutter_binding_pool_activate ()</title>
524
 
<indexterm zone="clutter-binding-pool-activate" role="1.0"><primary sortas="binding_pool_activate">clutter_binding_pool_activate</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            clutter_binding_pool_activate       (<link linkend="ClutterBindingPool">ClutterBindingPool</link> *pool,
525
 
                                                         <link linkend="guint">guint</link> key_val,
526
 
                                                         <link linkend="ClutterModifierType">ClutterModifierType</link> modifiers,
527
 
                                                         <link linkend="GObject">GObject</link> *gobject);</programlisting>
528
 
<para>
529
 
Activates the callback associated to the action that is
530
 
bound to the <parameter>key_val</parameter> and <parameter>modifiers</parameter> pair.
531
 
</para>
532
 
<para>
533
 
The callback has the following signature:
534
 
</para>
535
 
<para>
536
 
<informalexample><programlisting>
537
 
  void (* callback) (GObject             *gobject,
538
 
                     const gchar         *action_name,
539
 
                     guint                key_val,
540
 
                     ClutterModifierType  modifiers,
541
 
                     gpointer             user_data);
542
 
</programlisting></informalexample>
543
 
</para>
544
 
<para>
545
 
Where the <link linkend="GObject"><type>GObject</type></link> instance is <parameter>gobject</parameter> and the user data
546
 
is the one passed when installing the action with
547
 
<link linkend="clutter-binding-pool-install-action"><function>clutter_binding_pool_install_action()</function></link>.
548
 
</para>
549
 
<para>
550
 
If the action bound to the <parameter>key_val</parameter>, <parameter>modifiers</parameter> pair has been
551
 
blocked using <link linkend="clutter-binding-pool-block-action"><function>clutter_binding_pool_block_action()</function></link>, the callback
552
 
will not be invoked, and this function will return <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>.</para>
553
 
<para>
554
 
</para><variablelist role="params">
555
 
<varlistentry><term><parameter>pool</parameter>&#160;:</term>
556
 
<listitem><simpara> a <link linkend="ClutterBindingPool"><type>ClutterBindingPool</type></link>
557
 
</simpara></listitem></varlistentry>
558
 
<varlistentry><term><parameter>key_val</parameter>&#160;:</term>
559
 
<listitem><simpara> the key symbol
560
 
</simpara></listitem></varlistentry>
561
 
<varlistentry><term><parameter>modifiers</parameter>&#160;:</term>
562
 
<listitem><simpara> bitmask for the modifiers
563
 
</simpara></listitem></varlistentry>
564
 
<varlistentry><term><parameter>gobject</parameter>&#160;:</term>
565
 
<listitem><simpara> a <link linkend="GObject"><type>GObject</type></link>
566
 
</simpara></listitem></varlistentry>
567
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if an action was found and was activated
568
 
 
569
 
</simpara></listitem></varlistentry>
570
 
</variablelist><para role="since">Since 1.0</para></refsect2>
571
 
 
572
 
</refsect1>
573
 
 
574
 
 
575
 
 
576
 
 
577
 
</refentry>