diff --git a/doc/cookbook/actors.xml b/doc/cookbook/actors.xml index 74f970826..570009b1d 100644 --- a/doc/cookbook/actors.xml +++ b/doc/cookbook/actors.xml @@ -23,7 +23,7 @@ with the others: it can be the parent of another actor, or a child of another actor. - The Stage is an actor that can have children but cannot have + The stage is an actor that can have children but cannot have any parent. Actors have different attributes: a position, a size, a @@ -38,7 +38,7 @@
- Knowing when an actor position or size change + Knowing when an actor's position or size changes
Problem @@ -112,7 +112,9 @@ on_allocation_changed (ClutterActor *actor, Any change the position and size of an actor will cause a change in the allocation of the actor itself. This will update the - values of the :x, :y, :width and :height properties as well. + values of the x, y, + width and height + properties as well. The first technique allows a greater deal of granularity, allowing you to know what exactly changed. Inside the callback @@ -159,12 +161,13 @@ on_allocation_changed (ClutterActor *actor, All actors will update these properties when their size or position change. - Note that the Stage, on the other hand, will not notify on - position changes, so it is not possible to use the :x and :y + Note that the stage, on the other hand, will not notify on + position changes, so it is not possible to use the + x and y properties to know that the platform-specific window embedding the stage has been moved — if the platform supports a windowing system. In order to achieve that you will have to use backend-specific - API to extract the surface used by the Stage and then platform-specific + API to extract the surface used by the stage and then platform-specific API to retrieve its coordinates.
@@ -218,12 +221,12 @@ void on_paint (ClutterActor *actor, gpointer user_data); Discussion The paint cycle in Clutter works its way recursively from the - Stage through every child. + stage through every child. Whenever an Actor is going to be painted it will be positioned in a new frame of reference according to the list of transformations - (scaling, rotation and additional traslations). After that, the "paint" - signal will be emitted. + (scaling, rotation and additional translations). After that, the "paint" + signal will be emitted.d The "paint" signal is defined as run-last, that is the signal handlers connected to it using @@ -255,4 +258,3 @@ on_paint (ClutterActor *actor)
- diff --git a/doc/cookbook/clutter-cookbook.xml.in b/doc/cookbook/clutter-cookbook.xml.in index f6d858387..655b72f57 100644 --- a/doc/cookbook/clutter-cookbook.xml.in +++ b/doc/cookbook/clutter-cookbook.xml.in @@ -49,9 +49,60 @@ Contributing to this document - This document is written in Docbook XML. The source file for this - document is located in the subdirectory "doc/cookbook" of the source - directory of Clutter. + This document is written in + Docbook XML. The source files + for this document are located in the subdirectory + doc/cookbook inside the Clutter source directory. + + To maintain some degree of consistency, try to stick to the + following broad guidelines about how to write Docbook for this + cookbook: + + + + If adding a new recipe, use the + recipe-template.xml XML file as a basis. + You can find it in the <clutter_source>/doc/cookbook/ + directory. + + + Try to indent your XML sensibly using 2 spaces per level + (we're not too strict, but some indentation helps reading + the source). + + + Stick to a column width of around 80 characters. + + + Use the <filename> element for file + and directory names. + + + Use the <property> element for property names + (e.g. GObject properties). + + + Use the <type> element for GObject class + names. + + + Use the <constant> element for C defines. + + + Use the <keycap> element for keys, where + you are referring to what's actually printed on the key, e.g. + Shift. If you're referring to the key some + other way (e.g. "the Control key"), don't use + <keycap>. + + + Use the <function> element for functions; + the style adopted is to give the function name followed by + empty brackets, e.g. clutter_actor_set_size(). + + + + diff --git a/doc/cookbook/events.xml b/doc/cookbook/events.xml index b3fc2f9d4..16744ace9 100644 --- a/doc/cookbook/events.xml +++ b/doc/cookbook/events.xml @@ -70,8 +70,8 @@ Solution 2: Use an actor's - ClutterBindingPool to declaratively assign actions to specific - key and modifier combinations. + ClutterBindingPool to declaratively assign + actions to specific key and modifier combinations. @@ -80,12 +80,13 @@
Solution 1 - Connect the key-press-event signal for an actor to a callback; - then examine the event in the callback to determine which key and - modifiers were pressed. + Connect the key-press-event + signal for an actor to a callback; then examine the event + in the callback to determine which key and modifiers were + pressed. - First, connect an actor's key-press-event signal - to a callback: + First, connect an actor's + key-press-event signal to a callback: @@ -96,7 +97,8 @@ g_signal_connect (actor, "key-press-event", G_CALLBACK (_key_press_cb), NULL); Then, in the callback, check which key was pressed and which modifiers were down at the same time. For example, this callback checks for a press on the up arrow key and whether - the Shift and/or Control key were down: + the Shift and/or Ctrl + key were down: @@ -110,26 +112,26 @@ _key_press_cb (ClutterActor *actor, if (CLUTTER_Up == keyval) { ClutterModifierType modifiers = clutter_event_get_state (event); - + switch (modifiers) { case CLUTTER_SHIFT_MASK: g_debug ("Up and shift pressed"); break; - + case CLUTTER_SHIFT_MASK + CLUTTER_CONTROL_MASK: g_debug ("Up and shift and control pressed"); break; - + default: g_debug ("Up pressed"); break; } - + /* The event was handled, and the emission should stop */ return TRUE; } - + /* The event was not handled, and the emission should continue */ return FALSE; } @@ -137,33 +139,38 @@ _key_press_cb (ClutterActor *actor, Note that Clutter provides a range of key value definitions - (like CLUTTER_Up, used above). These are generated from the list in the + (like CLUTTER_Up, used above). These are + generated from the list in the X.Org source code (replace "XK" with "CLUTTER" in the definitions there to get the - CLUTTER equivalents; alternatively, look at the clutter-keysyms.h - header file for the list). + CLUTTER equivalents; alternatively, look at the + clutter-keysyms.h header file for the + list). - CLUTTER_SHIFT_MASK, CLUTTER_CONTROL_MASK and other modifiers are - defined in the ClutterModifierType enum. + CLUTTER_SHIFT_MASK, + CLUTTER_CONTROL_MASK and other modifiers are + defined in the ClutterModifierType enum.
Solution 2 - Assign actions to an actor's ClutterBindingPool. + Assign actions to an actor's ClutterBindingPool. A binding pool stores mappings from a key press (either a single key or a key plus modifiers) to actions; an action is simply a callback function with a specific signature. While this approach is trickier to implement, it is more flexible and removes the drudgery of writing branching code to - handle different key presses. See the Discussion section for - more details. + handle different key presses. See the + Discussion + section for more details. To use this approach with an actor which will receive key press events, first get that actor's binding pool. In the example below, - we're using the binding pool for the default ClutterStage: + we're using the binding pool for the default + ClutterStage: @@ -176,8 +183,9 @@ binding_pool = clutter_binding_pool_get_for_class (stage_class); Next, install actions into the binding pool. For example, to - install an action bound to the up arrow key, which calls the _move_up - function when that key is pressed, you would do: + install an action bound to the up arrow key, which calls the + _move_up() function when that key is pressed, + you would do: @@ -191,8 +199,10 @@ clutter_binding_pool_install_action (binding_pool, - Another example, binding up + Shift + Control to an action which - calls _move_up_shift_control when activated: + Another example, binding up arrow + + Shift + Ctrl to an action + which calls _move_up_shift_control() when + activated: @@ -206,8 +216,8 @@ clutter_binding_pool_install_action (binding_pool, - The function called when an action is activated looks like this - (for _move_up): + The function called when an action is activated looks + like this (for _move_up()): @@ -223,8 +233,8 @@ _move_up (GObject *instance, - Then bind the key-press-event for the actor (in our case, - the stage) to a callback: + Then bind the key-press-event signal + for the actor (in our case, the stage) to a callback: @@ -258,13 +268,13 @@ _key_press_cb (ClutterActor *actor, - Now, when a key plus modifiers that has been bound to an action - is pressed on the actor, the appropriate action is activated. + Now, when a key + modifiers that have been bound to an action + are pressed on the actor, the appropriate action is activated.
-
+
Discussion
@@ -285,9 +295,10 @@ _key_press_cb (ClutterActor *actor, In addition, Solution 2 lets you write a single callback to handle all key press events for all actors. This callback could then - use clutter_binding_pool_find (as in the example code) to determine - which binding pool to activate (depending on which actor received the - key press event). + use clutter_binding_pool_find() + (as in the example code) to determine which binding pool to + activate (depending on which actor received the key press + event). Finally, a binding pool allows you to block and unblock actions. This means you can make the response to a key press event conditional @@ -305,17 +316,19 @@ _key_press_cb (ClutterActor *actor, - A ClutterKeyEvent contains only a single - key value, plus possibly one or more modifier keys (like Shift, - Control, Alt etc.). There are no functions in the - Clutter API which return events for tracking near-simultaneous - presses on multiple keys. + A ClutterKeyEvent contains only a + single key value, plus possibly one + or more modifier keys (like Shift, + Ctrl, Alt etc.). + There are no functions in the Clutter API which return + events for tracking near-simultaneous presses on multiple + keys. By default, the stage receives all key events. To make another actor receive key events, use - clutter_stage_set_key_focus: + clutter_stage_set_key_focus(): diff --git a/doc/cookbook/textures.xml b/doc/cookbook/textures.xml index 57ed0a0d3..33903d8ce 100644 --- a/doc/cookbook/textures.xml +++ b/doc/cookbook/textures.xml @@ -27,8 +27,8 @@
Solution - Create a ClutterCairoTexture, then draw onto the Cairo context - it wraps using the Cairo API: + Create a ClutterCairoTexture, then draw onto + the Cairo context it wraps using the Cairo API: @@ -64,9 +64,11 @@ cairo_destroy (cr);
Discussion - A ClutterCairoTexture is a standard ClutterActor, so it can be - added to ClutterContainers (e.g. a ClutterStage or ClutterGroup), - animated, resized etc. in the usual ways. + A ClutterCairoTexture is a standard + ClutterActor, so it can be added to a + ClutterContainer (e.g. a ClutterStage + or ClutterGroup), animated, resized etc. in the + usual ways. Other useful operations: @@ -74,24 +76,24 @@ cairo_destroy (cr); To draw on part of the texture: - use clutter_cairo_texture_create_region to + use clutter_cairo_texture_create_region() to retrieve a Cairo context for the region you want to draw on. To clear existing content from a texture: - use clutter_cairo_texture_clear. + use clutter_cairo_texture_clear(). You may need to do this as the texture reuses the same Cairo context each time you call - clutter_cairo_texture_create or - clutter_cairo_texture_create_region. + clutter_cairo_texture_create() or + clutter_cairo_texture_create_region(). To resize the Cairo context wrapped by a texture, use - clutter_cairo_texture_set_surface_size. + clutter_cairo_texture_set_surface_size(). @@ -145,10 +147,11 @@ cairo_destroy (cr); Note that if the page is larger than the Cairo context, - some of it might not be visible. Similarly, if the ClutterCairoTexture - is larger than the stage, some of that might not be visible. So you - may need to do some work to make the ClutterCairoTexture fit - inside the stage properly (e.g. resize the stage), and/or some work + some of it might not be visible. Similarly, if the + ClutterCairoTexture is larger than the stage, + some of that might not be visible. So you + may need to do some work to make the ClutterCairoTexture + fit inside the stage properly (e.g. resize the stage), and/or some work to make the PDF page sit inside the Cairo context (e.g. scale the PDF page or put it inside a scrollable actor). @@ -174,8 +177,8 @@ cairo_destroy (cr); Set the texture to keep the aspect ratio of the underlying image (so it doesn't distort when it's scaled); use - the actor's request-mode property to set the correct - geometry management (see the discussion section); then + the actor's request-mode property to set + the correct geometry management (see the discussion section); then resize the texture along one dimension (height or width). Now, when an image is loaded into the texture, the image is scaled to fit the set height or width; the other dimension @@ -210,20 +213,20 @@ clutter_texture_set_from_file (CLUTTER_TEXTURE (texture),
Discussion - The request mode for an actor determines how - geometry requisition is performed; in this case, this + The request-mode for an actor + determines how geometry requisition is performed; in this case, this includes how scaling is applied if you change the actor's width or height. There are two possible values for request-mode: - If set to CLUTTER_REQUEST_HEIGHT_FOR_WIDTH + If set to CLUTTER_REQUEST_HEIGHT_FOR_WIDTH (the default), changing the width causes the height to be scaled by the same factor as the width. - If set to CLUTTER_REQUEST_WIDTH_FOR_HEIGHT, + If set to CLUTTER_REQUEST_WIDTH_FOR_HEIGHT, changing the height causes the width to be scaled by the same factor as the height. @@ -231,21 +234,22 @@ clutter_texture_set_from_file (CLUTTER_TEXTURE (texture), In the example above, the texture is set to keep its aspect ratio then fixed to a width of 300 pixels; the - request-mode is set to CLUTTER_REQUEST_HEIGHT_FOR_WIDTH. If a - standard, photo-sized image in landscape orientation were + request-mode is set to CLUTTER_REQUEST_HEIGHT_FOR_WIDTH. + If a standard, photo-sized image in landscape orientation were loaded into it (2848 pixels wide x 2136 high), it would be scaled down to 300 pixels wide; then, its height would be scaled by the same factor as the width (i.e. scaled down to 225 pixels). - With request-mode set to CLUTTER_REQUEST_WIDTH_FOR_HEIGHT, + With request-mode set to + CLUTTER_REQUEST_WIDTH_FOR_HEIGHT, you would get the same effect by setting the height first; then, computation of the width for the scaled image would be based on the scaling factor applied to its height instead. You can work out which side of the source image is longest using - clutter_texture_base_size() to get its width and height. This can - be useful when trying to scale images with different orientations - to fit into uniform rows or columns: + clutter_texture_base_size() to get its + width and height. This can be useful when trying to scale images + with different orientations to fit into uniform rows or columns: @@ -259,8 +263,9 @@ clutter_texture_get_base_size (CLUTTER_TEXTURE (texture), &width, &height); If you explicitly set the size (both width and height) - of a texture with clutter_actor_set_size() (or - with clutter_actor_set_width() and clutter_actor_set_height()), any + of a texture with clutter_actor_set_size() (or + with clutter_actor_set_width() and + clutter_actor_set_height()), any image loaded into the texture is automatically stretched/shrunk to fit the texture. This is the case regardless of any other settings (like whether to keep aspect ratio). @@ -285,7 +290,8 @@ clutter_texture_get_base_size (CLUTTER_TEXTURE (texture), &width, &height);
Solution - Create a ClutterTexture directly from an image file: + Create a ClutterTexture directly from an + image file: @@ -378,11 +384,12 @@ if (error != NULL) - Call g_thread_init() (from the GLib library) prior - to calling clutter_init(), so that a local thread is used - to load the file, rather than the main loop. (Note that - this is not necessary if you're using GLib version >= 2.24, - since GObject initializes threading with the type system.) + Call g_thread_init() (from the + GLib library) prior to calling clutter_init(), + so that a local thread is used to load the file, rather + than the main loop. (Note that this is not necessary if + you're using GLib version >= 2.24, since GObject + initializes threading with the type system.) Set the texture to load data asynchronously. @@ -462,16 +469,18 @@ main (int argc, char *argv[]) - Various GNOME libraries provide image data in GdkPixbuf - structures; clutter-gtk has functions for - creating or setting a texture from a GdkPixbuf: - gtk_clutter_texture_new_from_pixbuf() - and gtk_clutter_texture_set_from_pixbuf() respectively. + Various GNOME libraries provide image data in + GdkPixbuf structures; clutter-gtk has + functions for creating or setting a texture from a + GdkPixbuf: + gtk_clutter_texture_new_from_pixbuf() + and gtk_clutter_texture_set_from_pixbuf() + respectively. - If you have raw RGB pixel data, ClutterTexture also has - the clutter_texture_set_from_rgb_data() method for loading - it. + If you have raw RGB pixel data, ClutterTexture + also has a clutter_texture_set_from_rgb_data() + function for loading it.