diff --git a/doc/cookbook/events.xml b/doc/cookbook/events.xml index 77784e0dc..a15c57625 100644 --- a/doc/cookbook/events.xml +++ b/doc/cookbook/events.xml @@ -347,13 +347,14 @@ clutter_stage_set_key_focus (stage, actor);
- Detecting mouse wheel scrolling on an actor + Detecting mouse scrolling on an actor
Problem - You want to detect when the mouse wheel is scrolled on an - actor. + 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).
@@ -373,21 +374,7 @@ clutter_actor_set_reactive (actor, TRUE); - Next, connect a callback handler to the - scroll-event signal of the actor: - - - - - - - - Finally, create a callback handler to examine the scroll + Next, create a callback handler to examine the scroll event and respond to it: @@ -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, ]]> + + Finally, connect the callback handler to the + scroll-event signal of the actor: + + + + + + +
@@ -431,8 +433,8 @@ _scroll_event_cb (ClutterActor *actor, 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. + right scrolling (e.g. a trackball mouse or trackpad), left and + right scroll events may also be emitted.
Creating a scrolling viewport for an actor @@ -475,7 +477,7 @@ _scroll_event_cb (ClutterActor *actor, Create the scrollable actor; it should be larger - than the scrollview. This example uses a ClutterTexture, + than the viewport. This example uses a ClutterTexture, but any ClutterActor will work: @@ -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 this recipe - * 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 this recipe 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); The key here is calling clutter_actor_set_clip_to_allocation (viewport, TRUE). This configures the viewport 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). + children (the latter is the default). - Put the scrollable actor into the scroll view and - the scroll view into its container (in this case, + Put the scrollable actor into the viewport; and + the viewport into its container (in this case, the default stage): @@ -557,8 +560,8 @@ clutter_container_add_actor (CLUTTER_CONTAINER (stage), viewport); - Create a callback handler for scroll event signals - emitted by the viewport: + Create a callback handler for scroll-event + signals emitted by the viewport: @@ -625,15 +628,15 @@ _scroll_event_cb (ClutterActor *viewport, The approach taken here is to move the scrollable actor up, relative to the viewport. Initially, the scrollable will have a y coordinate value - of 0.0 (it is aligned to the top of the viewport). - Scrolling up subtracts from the + of 0.0 (aligned to the top of the viewport). + Scrolling up decrements the y coordinate (down to a minumum of viewport_height - scrollable_height). 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. - Scrolling down adds to the y coordinate + Scrolling down increments the y coordinate (but only up to a maximum value of 0.0). To see how this works in practice, look at @@ -642,16 +645,17 @@ _scroll_event_cb (ClutterActor *viewport, set to 300 and the height of the viewport to 150. This means that the y coordinate value for the scrollable actor will vary between - -150.0 (150 - 300), making - its base visible and clipping the top; and + -150.0: 150 (the viewport's height) + - 300 (the scrollable actor's height), making + its base visible and clipping its top; and 0.0, where its top is visible and its base clipped. 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: