brl/mutter
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs/cookbook: Mention the event control macros

Browse Source 
Now that we have symbolic names for event propagation values for signal
handlers, we ought to mention them in the cookbook.
This commit is contained in:
Emmanuele Bassi 2012-01-03 12:10:28 +00:00
parent 6184bf1b6e
commit fd1196c7b5
1 changed files with 16 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
doc/cookbook/events.xml
View File

@ -44,9 +44,15 @@
</orderedlist> </orderedlist>
<para>At any point during the event emission sequence a handler of either <para>At any point during the event emission sequence a handler of either
the captured-event or the event signals can stop it, by returning a value the captured-event or the event signals can stop it, by returning a boolean
of TRUE, which means that the event has been handled. If an event hasn't value of <emphasis>true</emphasis>, which means that the event has been
been handled, FALSE should be returned instead.</para> handled. If an event hasn't been handled, a boolean value of
<emphasis>false</emphasis> should be returned instead.</para>
<note><para>Clutter provides two useful macros to avoid remembering which
boolean value should be used in an event signal handler:
CLUTTER_EVENT_PROPAGATE, equivalent to FALSE; and CLUTTER_EVENT_STOP,
equivalent to TRUE.</para></note>
</section> </section>
<section id="events-handling-key-events"> <section id="events-handling-key-events">
@ -124,11 +130,11 @@ _key_press_cb (ClutterActor *actor,
g_debug ("Up pressed"); g_debug ("Up pressed");
/* The event was handled, and the emission should stop */ /* The event was handled, and the emission should stop */
return TRUE; return CLUTTER_EVENT_STOP;
} }
/* The event was not handled, and the emission should continue */ /* The event was not handled, and the emission should continue */
return FALSE; return CLUTTER_EVENT_PROPAGATE;
} }
]]> ]]>
</programlisting> </programlisting>
@ -406,7 +412,7 @@ _scroll_event_cb (ClutterActor *actor,
break; break;
} }
return TRUE; /* event has been handled */ return CLUTTER_EVENT_STOP; /* event has been handled */
} }
]]> ]]>
</programlisting> </programlisting>
@ -578,7 +584,7 @@ _scroll_event_cb (ClutterActor *viewport,
/* no need to scroll if the scrollable is shorter than the viewport */ /* no need to scroll if the scrollable is shorter than the viewport */
if (scrollable_height < viewport_height) if (scrollable_height < viewport_height)
return TRUE; return CLUTTER_EVENT_STOP;
gfloat y = clutter_actor_get_y (scrollable); gfloat y = clutter_actor_get_y (scrollable);
@ -619,7 +625,7 @@ _scroll_event_cb (ClutterActor *viewport,
"y", y, "y", y,
NULL); NULL);
return TRUE; return CLUTTER_EVENT_STOP;
} }
]]> ]]>
</programlisting> </programlisting>
@ -802,7 +808,7 @@ _pointer_enter_cb (ClutterActor *actor,
stage_x, stage_y, stage_x, stage_y,
actor_x, actor_y); actor_x, actor_y);
return TRUE; return CLUTTER_EVENT_STOP;
} }
]]> ]]>
</programlisting> </programlisting>
@ -1150,7 +1156,7 @@ button_event_cb (ClutterActor *actor,
ctrl_pressed, ctrl_pressed,
click_count); click_count);
return TRUE; return CLUTTER_EVENT_STOP;
} }
</programlisting> </programlisting>
</informalexample> </informalexample>