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

cookbook: Cleaning up grammar and wording in mouse scroll recipe

Browse Source
This commit is contained in:
Elliot Smith 2010-08-12 10:16:56 +01:00
parent 8db96675d4
commit 1ed5d5cab0
1 changed files with 45 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

86
doc/cookbook/events.xml
View File

@ -347,13 +347,14 @@ clutter_stage_set_key_focus (stage, actor);
</section>
<section id="events-mouse-scroll">
<title>Detecting mouse wheel scrolling on an actor</title>
<title>Detecting mouse scrolling on an actor</title>
<section>
<title>Problem</title>
<para>You want to detect when the mouse wheel is scrolled on an
actor.</para>
<para>You want to detect when the mouse is scrolled on an
actor (e.g. the pointer is over an actor when a mouse
wheel is scrolled).</para>
</section>
<section>
@ -373,21 +374,7 @@ clutter_actor_set_reactive (actor, TRUE);
</programlisting>
</informalexample>
<para>Next, connect a callback handler to the
<code>scroll-event</code> signal of the actor:</para>
<informalexample>
<programlisting>
<![CDATA[
g_signal_connect (actor,
"scroll-event",
G_CALLBACK (_scroll_event_cb),
NULL);
]]>
</programlisting>
</informalexample>
<para>Finally, create a callback handler to examine the scroll
<para>Next, create a callback handler to examine the scroll
event and respond to it:</para>
<informalexample>
@ -398,7 +385,7 @@ _scroll_event_cb (ClutterActor *actor,
ClutterEvent *event,
gpointer user_data)
{
/* determine the direction the mouse wheel was scrolled */
/* determine the direction the mouse was scrolled */
ClutterScrollDirection direction;
direction = clutter_event_get_scroll_direction (event);
@ -424,6 +411,21 @@ _scroll_event_cb (ClutterActor *actor,
]]>
</programlisting>
</informalexample>
<para>Finally, connect the callback handler to the
<code>scroll-event</code> signal of the actor:</para>
<informalexample>
<programlisting>
<![CDATA[
g_signal_connect (actor,
"scroll-event",
G_CALLBACK (_scroll_event_cb),
NULL);
]]>
</programlisting>
</informalexample>
</section>
<section>
@ -431,8 +433,8 @@ _scroll_event_cb (ClutterActor *actor,
<para>A standard mouse wheel will only return up and
down movements; but in cases where the mouse has left and
right scrolling (e.g. a trackball mouse), left and right scroll
events may also be emitted.</para>
right scrolling (e.g. a trackball mouse or trackpad), left and
right scroll events may also be emitted.</para>
<section>
<title>Creating a scrolling viewport for an actor</title>
@ -475,7 +477,7 @@ _scroll_event_cb (ClutterActor *actor,
<orderedlist>
<listitem>
<para>Create the scrollable actor; it should be larger
than the scrollview. This example uses a <type>ClutterTexture</type>,
than the viewport. This example uses a <type>ClutterTexture</type>,
but any <type>ClutterActor</type> will work:</para>
<informalexample>
<programlisting>
@ -488,14 +490,15 @@ clutter_texture_set_keep_aspect_ratio (CLUTTER_TEXTURE (texture),
/*
* set the texture's height so it's as tall as the stage
* (STAGE_HEIGHT is define'd at the top of the file);
* see <link linkend="textures-aspect-ratio">this recipe</link>
* for more about loading images into textures
* (STAGE_HEIGHT is define'd at the top of the file)
*/
clutter_actor_set_request_mode (texture, CLUTTER_REQUEST_WIDTH_FOR_HEIGHT);
clutter_actor_set_height (texture, STAGE_HEIGHT);
/* load the image file */
/*
* load the image file;
* see <link linkend="textures-aspect-ratio">this recipe</link> for more about loading images into textures
*/
clutter_texture_set_from_file (CLUTTER_TEXTURE (texture),
image_file_path,
NULL);
@ -533,17 +536,17 @@ clutter_actor_set_clip_to_allocation (viewport, TRUE);
<para>The key here is calling
<code>clutter_actor_set_clip_to_allocation (viewport, TRUE)</code>.
This configures the <varname>viewport</varname> group so
that any of its children are clipped: i.e. only the area of
the children which fits inside the group is visible. This
that any of its children are clipped: i.e. only parts of
its children which fit inside its allocation are visible. This
in turn requires setting an explicit size on the group,
rather than allowing it to size itself to fit its
children (the default).</para>
children (the latter is the default).</para>
</listitem>
<listitem>
<para>Put the scrollable actor into the scroll view and
the scroll view into its container (in this case,
<para>Put the scrollable actor into the viewport; and
the viewport into its container (in this case,
the default stage):</para>
<informalexample>
@ -557,8 +560,8 @@ clutter_container_add_actor (CLUTTER_CONTAINER (stage), viewport);
</listitem>
<listitem>
<para>Create a callback handler for scroll event signals
emitted by the viewport:</para>
<para>Create a callback handler for <code>scroll-event</code>
signals emitted by the viewport:</para>
<informalexample>
<programlisting>
@ -625,15 +628,15 @@ _scroll_event_cb (ClutterActor *viewport,
<para>The approach taken here is to move the scrollable
actor up, relative to the viewport. Initially, the
scrollable will have a <code>y</code> coordinate value
of <code>0.0</code> (it is aligned to the top of the viewport).
Scrolling up subtracts from the
of <code>0.0</code> (aligned to the top of the viewport).
Scrolling up decrements the
<code>y</code> coordinate (down to a minumum of
<code>viewport_height - scrollable_height</code>). This moves
the top of the scrollable "outside" the clip area of the
the top of the scrollable actor "outside" the clip area of the
viewport; simultaneously, more of the bottom part of the
scrollable moves into the clip area, becoming visible.</para>
<para>Scrolling down adds to the <code>y</code> coordinate
<para>Scrolling down increments the <code>y</code> coordinate
(but only up to a maximum value of <code>0.0</code>).</para>
<para>To see how this works in practice, look at
@ -642,16 +645,17 @@ _scroll_event_cb (ClutterActor *viewport,
set to <code>300</code> and the height of the viewport to
<code>150</code>. This means that the <code>y</code>
coordinate value for the scrollable actor will vary between
<code>-150.0</code> (<code>150 - 300</code>), making
its base visible and clipping the top; and
<code>-150.0</code>: <code>150</code> (the viewport's height)
<code>- 300</code> (the scrollable actor's height), making
its base visible and clipping its top; and
<code>0.0</code>, where its top is visible and its base
clipped.</para>
</listitem>
<listitem>
<para>Connect the callback handler to the signal; note
that we pass the scrollable (the texture) to the callback,
as we're moving the texture inside the viewport to
that we pass the scrollable actor (the texture) to the callback,
as we're moving the texture relative to the viewport to
create the scrolling effect:</para>
<informalexample>