From 12370bd4f8246f72abe75fae90fdee452c7a8f58 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Mon, 17 Mar 2014 23:07:58 +0000 Subject: [PATCH] docs: Move to markdown We're removing docbook tags in favour of the markdown syntax. --- clutter/clutter-actor.c | 888 +++++++++++++++-------------- clutter/clutter-backend.c | 8 +- clutter/clutter-bin-layout.c | 34 +- clutter/clutter-bind-constraint.c | 31 +- clutter/clutter-binding-pool.c | 19 +- clutter/clutter-box-layout.c | 32 +- clutter/clutter-canvas.c | 9 +- clutter/clutter-child-meta.h | 9 +- clutter/clutter-clone.c | 6 +- clutter/clutter-color.c | 28 +- clutter/clutter-constraint.c | 207 +++---- clutter/clutter-deform-effect.c | 19 +- clutter/clutter-drag-action.c | 20 +- clutter/clutter-drop-action.c | 14 +- clutter/clutter-effect.c | 158 ++--- clutter/clutter-flow-layout.c | 35 +- clutter/clutter-gesture-action.c | 64 +-- clutter/clutter-image.c | 9 +- clutter/clutter-input-device.c | 20 +- clutter/clutter-layout-manager.c | 275 ++------- clutter/clutter-main.c | 140 ++--- clutter/clutter-model.c | 70 +-- clutter/clutter-offscreen-effect.c | 41 +- clutter/clutter-paint-volume.c | 64 ++- clutter/clutter-path.c | 67 +-- clutter/clutter-script.c | 10 +- clutter/clutter-scroll-actor.c | 9 +- clutter/clutter-settings.c | 24 +- clutter/clutter-shader-effect.c | 100 ++-- clutter/clutter-stage.c | 50 +- clutter/clutter-test-utils.c | 2 +- clutter/clutter-test-utils.h | 2 +- clutter/clutter-text.c | 4 +- clutter/clutter-timeline.c | 47 +- clutter/clutter-types.h | 4 +- clutter/clutter-units.c | 6 +- 36 files changed, 1048 insertions(+), 1477 deletions(-) diff --git a/clutter/clutter-actor.c b/clutter/clutter-actor.c index 2274c3ed8..fad7b0e8a 100644 --- a/clutter/clutter-actor.c +++ b/clutter/clutter-actor.c @@ -30,131 +30,121 @@ * and it encapsulates the position, size, and transformations of a node in * the graph. * - * - * Actor transformations - * Each actor can be transformed using methods like - * clutter_actor_set_scale() or clutter_actor_set_rotation(). The order - * in which the transformations are applied is decided by Clutter and it is - * the following: - * - * translation by the origin of the #ClutterActor:allocation; - * translation by the actor's #ClutterActor:depth; - * scaling by the #ClutterActor:scale-x and #ClutterActor:scale-y factors; - * rotation around the #ClutterActor:rotation-angle-x and #ClutterActor:rotation-center-x; - * rotation around the #ClutterActor:rotation-angle-y and #ClutterActor:rotation-center-y; - * rotation around the #ClutterActor:rotation-angle-z and #ClutterActor:rotation-center-z; - * negative translation by the #ClutterActor:anchor-x and #ClutterActor:anchor-y point. - * - * + * ## Actor transformations * - * - * Modifying an actor's geometry - * Each actor has a bounding box, called #ClutterActor:allocation - * which is either set by its parent or explicitly through the - * clutter_actor_set_position() and clutter_actor_set_size() methods. - * Each actor also has an implicit preferred size. - * An actor’s preferred size can be defined by any subclass by - * overriding the #ClutterActorClass.get_preferred_width() and the - * #ClutterActorClass.get_preferred_height() virtual functions, or it can - * be explicitly set by using clutter_actor_set_width() and - * clutter_actor_set_height(). - * An actor’s position can be set explicitly by using - * clutter_actor_set_x() and clutter_actor_set_y(); the coordinates are - * relative to the origin of the actor’s parent. - * + * Each actor can be transformed using methods like clutter_actor_set_scale() + * or clutter_actor_set_rotation(). The order in which the transformations are + * applied is decided by Clutter and it is the following: * - * - * Managing actor children - * Each actor can have multiple children, by calling - * clutter_actor_add_child() to add a new child actor, and - * clutter_actor_remove_child() to remove an existing child. #ClutterActor - * will hold a reference on each child actor, which will be released when - * the child is removed from its parent, or destroyed using - * clutter_actor_destroy(). - * + * 1. translation by the origin of the #ClutterActor:allocation property + * 2. translation by the actor's #ClutterActor:z-position property + * 3. translation by the actor's #ClutterActor:pivot-point property + * 4. scaling by the #ClutterActor:scale-x and #ClutterActor:scale-y factors + * 5. rotation around the #ClutterActor:rotation-angle-x and #ClutterActor:rotation-center-x + * 6. rotation around the #ClutterActor:rotation-angle-y and #ClutterActor:rotation-center-y + * 7. rotation around the #ClutterActor:rotation-angle-z and #ClutterActor:rotation-center-z + * 8. negative translation by the #ClutterActor:anchor-x and #ClutterActor:anchor-y point. + * 9. negative translation by the actor's #ClutterActor:pivot-point + * + * ## Modifying an actor's geometry + * + * Each actor has a bounding box, called #ClutterActor:allocation + * which is either set by its parent or explicitly through the + * clutter_actor_set_position() and clutter_actor_set_size() methods. + * Each actor also has an implicit preferred size. + * + * An actor’s preferred size can be defined by any subclass by + * overriding the #ClutterActorClass.get_preferred_width() and the + * #ClutterActorClass.get_preferred_height() virtual functions, or it can + * be explicitly set by using clutter_actor_set_width() and + * clutter_actor_set_height(). + * + * An actor’s position can be set explicitly by using + * clutter_actor_set_x() and clutter_actor_set_y(); the coordinates are + * relative to the origin of the actor’s parent. + * + * ## Managing actor children + * + * Each actor can have multiple children, by calling + * clutter_actor_add_child() to add a new child actor, and + * clutter_actor_remove_child() to remove an existing child. #ClutterActor + * will hold a reference on each child actor, which will be released when + * the child is removed from its parent, or destroyed using + * clutter_actor_destroy(). + * + * |[ * ClutterActor *actor = clutter_actor_new (); * - * /* set the bounding box of the actor */ + * // set the bounding box of the actor * clutter_actor_set_position (actor, 0, 0); * clutter_actor_set_size (actor, 480, 640); * - * /* set the background color of the actor */ + * // set the background color of the actor * clutter_actor_set_background_color (actor, CLUTTER_COLOR_Orange); * - * /* set the bounding box of the child, relative to the parent */ + * // set the bounding box of the child, relative to the parent * ClutterActor *child = clutter_actor_new (); * clutter_actor_set_position (child, 20, 20); * clutter_actor_set_size (child, 80, 240); * - * /* set the background color of the child */ + * // set the background color of the child * clutter_actor_set_background_color (child, CLUTTER_COLOR_Blue); * - * /* add the child to the actor */ + * // add the child to the actor * clutter_actor_add_child (actor, child); - * - * Children can be inserted at a given index, or above and below - * another child actor. The order of insertion determines the order of the - * children when iterating over them. Iterating over children is performed - * by using clutter_actor_get_first_child(), clutter_actor_get_previous_sibling(), - * clutter_actor_get_next_sibling(), and clutter_actor_get_last_child(). It is - * also possible to retrieve a list of children by using - * clutter_actor_get_children(), as well as retrieving a specific child at a - * given index by using clutter_actor_get_child_at_index(). - * If you need to track additions of children to a #ClutterActor, use - * the #ClutterContainer::actor-added signal; similarly, to track removals - * of children from a ClutterActor, use the #ClutterContainer::actor-removed - * signal. - * - * - * FIXME: MISSING XINCLUDE CONTENT - * - * - *
- * Actors - * - *
- * + * ]| * - * - * Painting an actor - * There are three ways to paint an actor: - * - * set a delegate #ClutterContent as the value for the - * #ClutterActor:content property of the actor; - * subclass #ClutterActor and override the - * #ClutterActorClass.paint_node() virtual function; - * subclass #ClutterActor and override the - * #ClutterActorClass.paint() virtual function. - * - * - * Setting the Content property - * A #ClutterContent is a delegate object that takes over the - * painting operation of one, or more actors. The #ClutterContent - * painting will be performed on top of the #ClutterActor:background-color - * of the actor, and before calling the #ClutterActorClass.paint_node() - * virtual function. - * + * Children can be inserted at a given index, or above and below + * another child actor. The order of insertion determines the order of the + * children when iterating over them. Iterating over children is performed + * by using clutter_actor_get_first_child(), clutter_actor_get_previous_sibling(), + * clutter_actor_get_next_sibling(), and clutter_actor_get_last_child(). It is + * also possible to retrieve a list of children by using + * clutter_actor_get_children(), as well as retrieving a specific child at a + * given index by using clutter_actor_get_child_at_index(). + * + * If you need to track additions of children to a #ClutterActor, use + * the #ClutterContainer::actor-added signal; similarly, to track removals + * of children from a ClutterActor, use the #ClutterContainer::actor-removed + * signal. + * + * See [basic-actor.c](https://git.gnome.org/browse/clutter/tree/examples/basic-actor.c?h=clutter-1.18). + * + * ## Painting an actor + * + * There are three ways to paint an actor: + * + * - set a delegate #ClutterContent as the value for the #ClutterActor:content property of the actor + * - subclass #ClutterActor and override the #ClutterActorClass.paint_node() virtual function + * - subclass #ClutterActor and override the #ClutterActorClass.paint() virtual function. + * + * A #ClutterContent is a delegate object that takes over the painting + * operations of one, or more actors. The #ClutterContent painting will + * be performed on top of the #ClutterActor:background-color of the actor, + * and before calling the actor's own implementation of the + * #ClutterActorClass.paint_node() virtual function. + * + * |[ * ClutterActor *actor = clutter_actor_new (); * - * /* set the bounding box */ + * // set the bounding box * clutter_actor_set_position (actor, 50, 50); * clutter_actor_set_size (actor, 100, 100); * - * /* set the content; the image_content variable is set elsewhere */ + * // set the content; the image_content variable is set elsewhere * clutter_actor_set_content (actor, image_content); - * - * - * - * Overriding the paint_node virtual function - * The #ClutterActorClass.paint_node() virtual function is invoked - * whenever an actor needs to be painted. The implementation of the - * virtual function must only paint the contents of the actor itself, - * and not the contents of its children, if the actor has any. - * The #ClutterPaintNode passed to the virtual function is the - * local root of the render tree; any node added to it will be - * rendered at the correct position, as defined by the actor's - * #ClutterActor:allocation. - * + * ]| + * + * The #ClutterActorClass.paint_node() virtual function is invoked whenever + * an actor needs to be painted. The implementation of the virtual function + * must only paint the contents of the actor itself, and not the contents of + * its children, if the actor has any. + * + * The #ClutterPaintNode passed to the virtual function is the local root of + * the render tree; any node added to it will be rendered at the correct + * position, as defined by the actor's #ClutterActor:allocation. + * + * |[ * static void * my_actor_paint_node (ClutterActor *actor, * ClutterPaintNode *root) @@ -162,112 +152,131 @@ * ClutterPaintNode *node; * ClutterActorBox box; * - * /* where the content of the actor should be painted */ + * // where the content of the actor should be painted * clutter_actor_get_allocation_box (actor, &box); * - * /* the cogl_texture variable is set elsewhere */ + * // the cogl_texture variable is set elsewhere * node = clutter_texture_node_new (cogl_texture, CLUTTER_COLOR_White, * CLUTTER_SCALING_FILTER_TRILINEAR, * CLUTTER_SCALING_FILTER_LINEAR); * - * /* paint the content of the node using the allocation */ + * // paint the content of the node using the allocation * clutter_paint_node_add_rectangle (node, &box); * - * /* add the node, and transfer ownership */ + * // add the node, and transfer ownership * clutter_paint_node_add_child (root, node); * clutter_paint_node_unref (node); * } - * - * - * - * Overriding the paint virtual function - * The #ClutterActorClass.paint() virtual function is invoked - * when the #ClutterActor::paint signal is emitted, and after the other - * signal handlers have been invoked. Overriding the paint virtual - * function gives total control to the paint sequence of the actor - * itself, including the children of the actor, if any. - * It is strongly discouraged to override the - * #ClutterActorClass.paint() virtual function, as well as connecting - * to the #ClutterActor::paint signal. These hooks into the paint - * sequence are considered legacy, and will be removed when the Clutter - * API changes. - * - * * - * - * Handling events on an actor - * A #ClutterActor can receive and handle input device events, for - * instance pointer events and key events, as long as its - * #ClutterActor:reactive property is set to %TRUE. - * Once an actor has been determined to be the source of an event, - * Clutter will traverse the scene graph from the top-level actor towards the - * event source, emitting the #ClutterActor::captured-event signal on each - * ancestor until it reaches the source; this phase is also called - * the capture phase. If the event propagation was not - * stopped, the graph is walked backwards, from the source actor to the - * top-level, and the #ClutterActor::event signal, along with other event - * signals if needed, is emitted; this phase is also called the - * bubble phase. At any point of the signal emission, signal - * handlers can stop the propagation through the scene graph by returning - * %CLUTTER_EVENT_STOP; otherwise, they can continue the propagation by - * returning %CLUTTER_EVENT_PROPAGATE. - * + * The #ClutterActorClass.paint() virtual function is invoked when the + * #ClutterActor::paint signal is emitted, and after the other signal + * handlers have been invoked. Overriding the paint virtual function + * gives total control to the paint sequence of the actor itself, + * including the children of the actor, if any. * - * - * Animation - * Animation is a core concept of modern user interfaces; Clutter - * provides a complete and powerful animation framework that automatically - * tweens the actor's state without requiring direct, frame by frame - * manipulation from your application code. - * - * Implicit animations - * The implicit animation model of Clutter assumes that all the - * changes in an actor state should be gradual and asynchronous; Clutter - * will automatically transition an actor's property change between the - * current state and the desired one without manual intervention, if the - * property is defined to be animatable in its documentation. - * By default, in the 1.0 API series, the transition happens - * with a duration of zero milliseconds, and the implicit animation is an - * opt in feature to retain backwards compatibility. - * Implicit animations depend on the current easing state; in order - * to use the default easing state for an actor you should call the - * clutter_actor_save_easing_state() function: - * - * /* assume that the actor is currently positioned at (100, 100) */ + * It is strongly discouraged to override the #ClutterActorClass.paint() + * virtual function, as well as connecting to the #ClutterActor::paint + * signal. These hooks into the paint sequence are considered legacy, and + * will be removed when the Clutter API changes. + * + * ## Handling events on an actor + * + * A #ClutterActor can receive and handle input device events, for + * instance pointer events and key events, as long as its + * #ClutterActor:reactive property is set to %TRUE. + * + * Once an actor has been determined to be the source of an event, + * Clutter will traverse the scene graph from the top-level actor towards the + * event source, emitting the #ClutterActor::captured-event signal on each + * ancestor until it reaches the source; this phase is also called + * the "capture" phase. If the event propagation was not stopped, the graph + * is walked backwards, from the source actor to the top-level, and the + * #ClutterActor::event signal is emitted, alongside eventual event-specific + * signals like #ClutterActor::button-press-event or #ClutterActor::motion-event; + * this phase is also called the "bubble" phase. + * + * At any point of the signal emission, signal handlers can stop the propagation + * through the scene graph by returning %CLUTTER_EVENT_STOP; otherwise, they can + * continue the propagation by returning %CLUTTER_EVENT_PROPAGATE. + * + * ## Animation + * + * Animation is a core concept of modern user interfaces; Clutter provides a + * complete and powerful animation framework that automatically tweens the + * actor's state without requiring direct, frame by frame manipulation from + * your application code. You have two models at your disposal: + * + * - an implicit animation model + * - an explicit animation model + * + * The implicit animation model of Clutter assumes that all the + * changes in an actor state should be gradual and asynchronous; Clutter + * will automatically transition an actor's property change between the + * current state and the desired one without manual intervention, if the + * property is defined to be animatable in its documentation. + * + * By default, in the 1.0 API series, the transition happens with a duration + * of zero milliseconds, and the implicit animation is an opt in feature to + * retain backwards compatibility. + * + * Implicit animations depend on the current easing state; in order to use + * the default easing state for an actor you should call the + * clutter_actor_save_easing_state() function: + * + * |[ + * // assume that the actor is currently positioned at (100, 100) + * + * // store the current easing state and reset the new easing state to + * // its default values * clutter_actor_save_easing_state (actor); + * + * // change the actor's position * clutter_actor_set_position (actor, 500, 500); + * + * // restore the previously saved easing state * clutter_actor_restore_easing_state (actor); - * - * The example above will trigger an implicit animation of the - * actor between its current position to a new position. - * It is possible to animate multiple properties of an actor - * at the same time, and you can animate multiple actors at the same - * time as well, for instance: - * - * /* animate the actor's opacity and depth */ + * ]| + * + * The example above will trigger an implicit animation of the + * actor between its current position to a new position. + * + * Implicit animations use a default duration of 250 milliseconds, + * and a default easing mode of %CLUTTER_EASE_OUT_CUBIC, unless you call + * clutter_actor_set_easing_mode() and clutter_actor_set_easing_duration() + * after changing the easing state of the actor. + * + * It is possible to animate multiple properties of an actor + * at the same time, and you can animate multiple actors at the same + * time as well, for instance: + * + * |[ * clutter_actor_save_easing_state (actor); + * + * // animate the actor's opacity and depth * clutter_actor_set_opacity (actor, 0); * clutter_actor_set_depth (actor, -100); + * * clutter_actor_restore_easing_state (actor); * - * /* animate another actor's opacity */ * clutter_actor_save_easing_state (another_actor); + * + * // animate another actor's opacity * clutter_actor_set_opacity (another_actor, 255); * clutter_actor_set_depth (another_actor, 100); + * * clutter_actor_restore_easing_state (another_actor); - * - * Implicit animations use a default duration of 250 milliseconds, - * and a default easing mode of %CLUTTER_EASE_OUT_CUBIC, unless you call - * clutter_actor_set_easing_mode() and clutter_actor_set_easing_duration() - * after changing the easing state of the actor. - * Changing the easing state will affect all the following property - * transitions, but will not affect existing transitions. - * It is important to note that if you modify the state on an - * animatable property while a transition is in flight, the transition's - * final value will be updated, as well as its duration and progress - * mode by using the current easing state; for instance, in the following - * example: - * + * ]| + * + * Changing the easing state will affect all the following property + * transitions, but will not affect existing transitions. + * + * It is important to note that if you modify the state on an + * animatable property while a transition is in flight, the transition's + * final value will be updated, as well as its duration and progress + * mode by using the current easing state; for instance, in the following + * example: + * + * |[ * clutter_actor_save_easing_state (actor); * clutter_actor_set_easing_duration (actor, 1000); * clutter_actor_set_x (actor, 200); @@ -277,23 +286,30 @@ * clutter_actor_set_easing_duration (actor, 500); * clutter_actor_set_x (actor, 100); * clutter_actor_restore_easing_state (actor); - * - * the first call to clutter_actor_set_x() will begin a transition - * of the #ClutterActor:x property from the current value to the value of - * 200 over a duration of one second; the second call to clutter_actor_set_x() - * will change the transition's final value to 100 and the duration to 500 - * milliseconds. - * It is possible to retrieve the #ClutterTransition used by the - * animatable properties by using clutter_actor_get_transition() and using - * the property name as the transition name. - * - * - * Explicit animations - * The explicit animation model supported by Clutter requires that - * you create a #ClutterTransition object, and set the initial and - * final values. The transition will not start unless you add it to the - * #ClutterActor. - * + * ]| + * + * the first call to clutter_actor_set_x() will begin a transition + * of the #ClutterActor:x property from the current value to the value of + * 200 over a duration of one second; the second call to clutter_actor_set_x() + * will change the transition's final value to 100 and the duration to 500 + * milliseconds. + * + * It is possible to receive a notification of the completion of an + * implicit transition by using the #ClutterActor::transition-stopped + * signal, decorated with the name of the property. In case you want to + * know when all the currently in flight transitions are complete, use + * the #ClutterActor::transitions-completed signal instead. + * + * It is possible to retrieve the #ClutterTransition used by the + * animatable properties by using clutter_actor_get_transition() and using + * the property name as the transition name. + * + * The explicit animation model supported by Clutter requires that + * you create a #ClutterTransition object, and optionally set the initial + * and final values. The transition will not start unless you add it to the + * #ClutterActor. + * + * |[ * ClutterTransition *transition; * * transition = clutter_property_transition_new ("opacity"); @@ -304,144 +320,144 @@ * clutter_transition_set_to (transition, G_TYPE_UINT, 0); * * clutter_actor_add_transition (actor, "animate-opacity", transition); - * - * The example above will animate the #ClutterActor:opacity property - * of an actor between fully opaque and fully transparent, and back, over - * a span of 3 seconds. The animation does not begin until it is added to - * the actor. - * The explicit animation API applies to all #GObject properties, - * as well as the custom properties defined through the #ClutterAnimatable - * interface, regardless of whether they are defined as implicitly - * animatable or not. - * The explicit animation API should also be used when using custom - * animatable properties for #ClutterAction, #ClutterConstraint, and - * #ClutterEffect instances associated to an actor; see the section on - * custom - * animatable properties below for an example. - * Finally, explicit animations are useful for creating animations - * that run continuously, for instance: - * - * /* this animation will pulse the actor's opacity continuously */ + * ]| + * + * The example above will animate the #ClutterActor:opacity property + * of an actor between fully opaque and fully transparent, and back, over + * a span of 3 seconds. The animation does not begin until it is added to + * the actor. + * + * The explicit animation API applies to all #GObject properties, + * as well as the custom properties defined through the #ClutterAnimatable + * interface, regardless of whether they are defined as implicitly + * animatable or not. + * + * The explicit animation API should also be used when using custom + * animatable properties for #ClutterAction, #ClutterConstraint, and + * #ClutterEffect instances associated to an actor; see the section on + * custom animatable properties below for an example. + * + * Finally, explicit animations are useful for creating animations + * that run continuously, for instance: + * + * |[ + * // this animation will pulse the actor's opacity continuously * ClutterTransition *transition; * ClutterInterval *interval; * * transition = clutter_property_transition_new ("opacity"); * - * /* we want to animate the opacity between 0 and 255 */ + * // we want to animate the opacity between 0 and 255 * clutter_transition_set_from (transition, G_TYPE_UINT, 0); * clutter_transition_set_to (transition, G_TYPE_UINT, 255); * - * /* over a one second duration, running an infinite amount of times */ + * // over a one second duration, running an infinite amount of times * clutter_timeline_set_duration (CLUTTER_TIMELINE (transition), 1000); * clutter_timeline_set_repeat_count (CLUTTER_TIMELINE (transition), -1); * - * /* we want to fade in and out, so we need to auto-reverse the transition */ + * // we want to fade in and out, so we need to auto-reverse the transition * clutter_timeline_set_auto_reverse (CLUTTER_TIMELINE (transition), TRUE); * - * /* and we want to use an easing function that eases both in and out */ + * // and we want to use an easing function that eases both in and out * clutter_timeline_set_progress_mode (CLUTTER_TIMELINE (transition), * CLUTTER_EASE_IN_OUT_CUBIC); * - * /* add the transition to the desired actor; this will - * * start the animation. - * */ + * // add the transition to the desired actor to start it * clutter_actor_add_transition (actor, "opacityAnimation", transition); - * - * - * + * ]| * - * - * Implementing an actor - * Careful consideration should be given when deciding to implement - * a #ClutterActor sub-class. It is generally recommended to implement a - * sub-class of #ClutterActor only for actors that should be used as leaf - * nodes of a scene graph. - * If your actor should be painted in a custom way, you should - * override the #ClutterActor::paint signal class handler. You can either - * opt to chain up to the parent class implementation or decide to fully - * override the default paint implementation; Clutter will set up the - * transformations and clip regions prior to emitting the #ClutterActor::paint - * signal. - * By overriding the #ClutterActorClass.get_preferred_width() and - * #ClutterActorClass.get_preferred_height() virtual functions it is - * possible to change or provide the preferred size of an actor; similarly, - * by overriding the #ClutterActorClass.allocate() virtual function it is - * possible to control the layout of the children of an actor. Make sure to - * always chain up to the parent implementation of the - * #ClutterActorClass.allocate() virtual function. - * In general, it is strongly encouraged to use delegation and - * composition instead of direct subclassing. - * + * ## Implementing an actor * - * - * ClutterActor custom properties for #ClutterScript - * #ClutterActor defines a custom "rotation" property which - * allows a short-hand description of the rotations to be applied - * to an actor. - * The syntax of the "rotation" property is the following: - * - * - * "rotation" : [ - * { "<axis>" : [ <angle>, [ <center> ] ] } - * ] - * - * - * where the axis is the name of an enumeration - * value of type #ClutterRotateAxis and angle is a - * floating point value representing the rotation angle on the given axis, - * in degrees. - * The center array is optional, and if present - * it must contain the center of rotation as described by two coordinates: - * Y and Z for "x-axis"; X and Z for "y-axis"; and X and Y for - * "z-axis". - * #ClutterActor also defines a scriptable "margin" property which - * follows the CSS "margin" shorthand. - * - * - * // 4 values - * "margin" : [ <top>, <right>, <bottom> <left> ] - * // 3 values - * "margin" : [ <top>, <left/right>, <bottom> ] - * // 2 values - * "margin" : [ <top/bottom>, <left/right> ] - * // 1 value - * "margin" : [ <top/right/bottom/left> ] - * - * - * - * #ClutterActor will also parse every positional and dimensional - * property defined as a string through clutter_units_from_string(); you - * should read the documentation for the #ClutterUnits parser format for - * the valid units and syntax. - * + * Careful consideration should be given when deciding to implement + * a #ClutterActor sub-class. It is generally recommended to implement a + * sub-class of #ClutterActor only for actors that should be used as leaf + * nodes of a scene graph. * - * - * Custom animatable properties - * #ClutterActor allows accessing properties of #ClutterAction, - * #ClutterEffect, and #ClutterConstraint instances associated to an actor - * instance for animation purposes. - * In order to access a specific #ClutterAction or a #ClutterConstraint - * property it is necessary to set the #ClutterActorMeta:name property on the - * given action or constraint. - * The property can be accessed using the following syntax: - * - * - * @<section>.<meta-name>.<property-name> - * - * - * The initial @ is mandatory. - * The section fragment can be one between - * "actions", "constraints" and "effects". - * The meta-name fragment is the name of the - * action or constraint, as specified by the #ClutterActorMeta:name - * property. - * The property-name fragment is the name of the - * action or constraint property to be animated. - * The example below animates a #ClutterBindConstraint applied to an - * actor using clutter_actor_animate(). The rect has - * a binding constraint for the origin actor, and in - * its initial state is overlapping the actor to which is bound to. - * + * If your actor should be painted in a custom way, you should + * override the #ClutterActor::paint signal class handler. You can either + * opt to chain up to the parent class implementation or decide to fully + * override the default paint implementation; Clutter will set up the + * transformations and clip regions prior to emitting the #ClutterActor::paint + * signal. + * + * By overriding the #ClutterActorClass.get_preferred_width() and + * #ClutterActorClass.get_preferred_height() virtual functions it is + * possible to change or provide the preferred size of an actor; similarly, + * by overriding the #ClutterActorClass.allocate() virtual function it is + * possible to control the layout of the children of an actor. Make sure to + * always chain up to the parent implementation of the + * #ClutterActorClass.allocate() virtual function. + * + * In general, it is strongly encouraged to use delegation and composition + * instead of direct subclassing. + * + * ## ClutterActor custom properties for ClutterScript + * + * #ClutterActor defines a custom "rotation" property which allows a short-hand + * description of the rotations to be applied to an actor. + * + * The syntax of the "rotation" property is the following: + * + * |[ + * "rotation" : [ { "" : [ , [ ] ] } ] + * ]| + * + * where: + * + * - axis is the name of an enumeration value of type #ClutterRotateAxis + * - angle is a floating point value representing the rotation angle on the given axis in degrees + * - center-point is an optional array, and if present it must contain the center of rotation as described by two coordinates: + * - Y and Z for "x-axis" + * - X and Z for "y-axis" + * - X and Y for "z-axis". + * + * #ClutterActor also defines a scriptable "margin" property which follows the CSS "margin" shorthand. + * + * |[ + * // 4 values + * "margin" : [ top, right, bottom, left ] + * // 3 values + * "margin" : [ top, left/right, bottom ] + * // 2 values + * "margin" : [ top/bottom, left/right ] + * // 1 value + * "margin" : [ top/right/bottom/left ] + * ]| + * + * #ClutterActor will also parse every positional and dimensional + * property defined as a string through clutter_units_from_string(); you + * should read the documentation for the #ClutterUnits parser format for + * the valid units and syntax. + * + * ## Custom animatable properties + * + * #ClutterActor allows accessing properties of #ClutterAction, + * #ClutterEffect, and #ClutterConstraint instances associated to an actor + * instance for animation purposes. + * + * In order to access a specific #ClutterAction or a #ClutterConstraint + * property it is necessary to set the #ClutterActorMeta:name property on the + * given action or constraint. + * + * The property can be accessed using the following syntax: + * + * |[ + * @
.. + * ]| + * + * - the initial `@` is mandatory + * - the `section` fragment can be one between "actions", "constraints" and "effects" + * - the `meta-name` fragment is the name of the action, effect, or constraint, as + * specified by the #ClutterActorMeta:name property of #ClutterActorMeta + * - the `property-name` fragment is the name of the action, effect, or constraint + * property to be animated. + * + * The example below animates a #ClutterBindConstraint applied to an actor + * using an explicit transition. The `rect` actor has a binding constraint + * on the `origin` actor, and in its initial state is overlapping the actor + * to which is bound to. + * + * |[ * constraint = clutter_bind_constraint_new (origin, CLUTTER_BIND_X, 0.0); * clutter_actor_meta_set_name (CLUTTER_ACTOR_META (constraint), "bind-x"); * clutter_actor_add_constraint (rect, constraint); @@ -455,11 +471,13 @@ * g_signal_connect (origin, "button-press-event", * G_CALLBACK (on_button_press), * rect); - * - * On button press, the rectangle "slides" from behind the actor to - * which is bound to, using the #ClutterBindConstraint:offset property to - * achieve the effect: - * + * ]| + * + * On button press, the rectangle "slides" from behind the actor to + * which is bound to, using the #ClutterBindConstraint:offset property to + * achieve the effect: + * + * |[ * gboolean * on_button_press (ClutterActor *origin, * ClutterEvent *event, @@ -467,43 +485,39 @@ * { * ClutterTransition *transition; * - * /* the offset that we want to apply; this will make the actor - * * slide in from behind the origin and rest at the right of - * * the origin, plus a padding value. - * */ + * // the offset that we want to apply; this will make the actor + * // slide in from behind the origin and rest at the right of + * // the origin, plus a padding value * float new_offset = clutter_actor_get_width (origin) + h_padding; * - * /* the property we wish to animate; the "@constraints" section - * * tells Clutter to check inside the constraints associated - * * with the actor; the "bind-x" section is the name of the - * * constraint; and the "offset" is the name of the property - * * on the constraint. - * */ + * // the property we wish to animate; the "@constraints" section + * // tells Clutter to check inside the constraints associated + * // with the actor; the "bind-x" section is the name of the + * // constraint; and the "offset" is the name of the property + * // on the constraint * const char *prop = "@constraints.bind-x.offset"; * - * /* create a new transition for the given property */ + * // create a new transition for the given property * transition = clutter_property_transition_new (prop); * - * /* set the easing mode and duration */ + * // set the easing mode and duration * clutter_timeline_set_progress_mode (CLUTTER_TIMELINE (transition), * CLUTTER_EASE_OUT_CUBIC); * clutter_timeline_set_duration (CLUTTER_TIMELINE (transition), 500); * - * /* create the interval with the initial and final values */ + * // create the interval with the initial and final values * clutter_transition_set_from (transition, G_TYPE_FLOAT, 0.f); * clutter_transition_set_to (transition, G_TYPE_FLOAT, new_offset); * - * /* add the transition to the actor; this causes the animation - * * to start. the name "offsetAnimation" can be used to retrieve - * * the transition later. - * */ + * // add the transition to the actor; this causes the animation + * // to start. the name "offsetAnimation" can be used to retrieve + * // the transition later * clutter_actor_add_transition (rect, "offsetAnimation", transition); * - * /* we handled the event */ + * // we handled the event * return CLUTTER_EVENT_STOP; * } - * - * + * ]| */ /** @@ -1595,11 +1609,11 @@ clutter_actor_real_unmap (ClutterActor *self) * When overriding #ClutterActorClass.unmap(), it is mandatory to * chain up to the parent implementation. * - * It is important to note that the implementation of the + * It is important to note that the implementation of the * #ClutterActorClass.unmap() virtual function may be called after * the #ClutterActorClass.destroy() or the #GObjectClass.dispose() * implementation, but it is guaranteed to be called before the - * #GObjectClass.finalize() implementation. + * #GObjectClass.finalize() implementation. * * Since: 1.0 */ @@ -2791,10 +2805,10 @@ clutter_actor_apply_transform_to_point (ClutterActor *self, * using cogl_set_modelview_matrix() for example then you would want a matrix * that transforms into eye coordinates. * - * This function explicitly initializes the given @matrix. If you just + * Note: This function explicitly initializes the given @matrix. If you just * want clutter to multiply a relative transformation with an existing matrix * you can use clutter_actor_apply_relative_transformation_matrix() - * instead. + * instead. * */ /* XXX: We should consider caching the stage relative modelview along with @@ -2846,12 +2860,11 @@ _clutter_actor_transform_and_project_box (ClutterActor *self, * Calculates the transformed coordinates of the four corners of the * actor in the plane of @ancestor. The returned vertices relate to * the #ClutterActorBox coordinates as follows: - * - * @verts[0] contains (x1, y1) - * @verts[1] contains (x2, y1) - * @verts[2] contains (x1, y2) - * @verts[3] contains (x2, y2) - * + * + * - @verts[0] contains (x1, y1) + * - @verts[1] contains (x2, y1) + * - @verts[2] contains (x1, y2) + * - @verts[3] contains (x2, y2) * * If @ancestor is %NULL the ancestor will be the #ClutterStage. In * this case, the coordinates returned will be the coordinates on @@ -2935,12 +2948,11 @@ clutter_actor_get_allocation_vertices (ClutterActor *self, * Calculates the transformed screen coordinates of the four corners of * the actor; the returned vertices relate to the #ClutterActorBox * coordinates as follows: - * - * v[0] contains (x1, y1) - * v[1] contains (x2, y1) - * v[2] contains (x1, y2) - * v[3] contains (x2, y2) - * + * + * - v[0] contains (x1, y1) + * - v[1] contains (x2, y1) + * - v[2] contains (x1, y2) + * - v[3] contains (x2, y2) * * Since: 0.4 */ @@ -3150,11 +3162,11 @@ _clutter_actor_apply_modelview_transform (ClutterActor *self, * using cogl_set_modelview_matrix() for example then you would want a matrix * that transforms into eye coordinates. * - * This function doesn't initialize the given @matrix, it simply + * This function doesn't initialize the given @matrix, it simply * multiplies the requested transformation matrix with the existing contents of * @matrix. You can use cogl_matrix_init_identity() to initialize the @matrix * before calling this function, or you can use - * clutter_actor_get_relative_transformation_matrix() instead. + * clutter_actor_get_relative_transformation_matrix() instead. */ void _clutter_actor_apply_relative_transformation_matrix (ClutterActor *self, @@ -6539,7 +6551,7 @@ clutter_actor_class_init (ClutterActorClass *klass) * * For instance: * - * |[ + * |[ * ClutterRequestMode mode; * gfloat natural_width, min_width; * gfloat natural_height, min_height; @@ -6548,20 +6560,20 @@ clutter_actor_class_init (ClutterActorClass *klass) * if (mode == CLUTTER_REQUEST_HEIGHT_FOR_WIDTH) * { * clutter_actor_get_preferred_width (child, -1, - * &min_width, - * &natural_width); + * &min_width, + * &natural_width); * clutter_actor_get_preferred_height (child, natural_width, - * &min_height, - * &natural_height); + * &min_height, + * &natural_height); * } * else * { * clutter_actor_get_preferred_height (child, -1, - * &min_height, - * &natural_height); + * &min_height, + * &natural_height); * clutter_actor_get_preferred_width (child, natural_height, - * &min_width, - * &natural_width); + * &min_width, + * &natural_width); * } * ]| * @@ -7087,14 +7099,14 @@ clutter_actor_class_init (ClutterActorClass *klass) * The X coordinate of an actor's anchor point, relative to * the actor coordinate space, in pixels. * - * It is highly recommended not to use #ClutterActor:anchor-x, + * It is highly recommended not to use #ClutterActor:anchor-x, * #ClutterActor:anchor-y, and #ClutterActor:anchor-gravity in newly * written code; the anchor point adds an additional translation that * will affect the actor's relative position with regards to its * parent, as well as the position of its children. This change needs * to always be taken into account when positioning the actor. It is * recommended to use the #ClutterActor:pivot-point property instead, - * as it will affect only the transformations. + * as it will affect only the transformations. * * Since: 0.8 * @@ -7116,14 +7128,14 @@ clutter_actor_class_init (ClutterActorClass *klass) * The Y coordinate of an actor's anchor point, relative to * the actor coordinate space, in pixels * - * It is highly recommended not to use #ClutterActor:anchor-x, + * It is highly recommended not to use #ClutterActor:anchor-x, * #ClutterActor:anchor-y, and #ClutterActor:anchor-gravity in newly * written code; the anchor point adds an additional translation that * will affect the actor's relative position with regards to its * parent, as well as the position of its children. This change needs * to always be taken into account when positioning the actor. It is * recommended to use the #ClutterActor:pivot-point property instead, - * as it will affect only the transformations. + * as it will affect only the transformations. * * Since: 0.8 * @@ -7144,14 +7156,14 @@ clutter_actor_class_init (ClutterActorClass *klass) * * The anchor point expressed as a #ClutterGravity * - * It is highly recommended not to use #ClutterActor:anchor-x, + * It is highly recommended not to use #ClutterActor:anchor-x, * #ClutterActor:anchor-y, and #ClutterActor:anchor-gravity in newly * written code; the anchor point adds an additional translation that * will affect the actor's relative position with regards to its * parent, as well as the position of its children. This change needs * to always be taken into account when positioning the actor. It is * recommended to use the #ClutterActor:pivot-point property instead, - * as it will affect only the transformations. + * as it will affect only the transformations. * * Since: 1.0 * @@ -7848,33 +7860,32 @@ clutter_actor_class_init (ClutterActorClass *klass) * GSignal API, redraw the UI and then call clutter_stage_ensure_redraw() * themselves, like: * - * |[ + * |[ * static void * on_redraw_complete (gpointer data) * { * ClutterStage *stage = data; * - * /* execute the Clutter drawing pipeline */ + * // execute the Clutter drawing pipeline * clutter_stage_ensure_redraw (stage); * } * * static void * on_stage_queue_redraw (ClutterStage *stage) * { - * /* this prevents the default handler to run */ + * // this prevents the default handler to run * g_signal_stop_emission_by_name (stage, "queue-redraw"); * - * /* queue a redraw with the host toolkit and call - * * a function when the redraw has been completed - * */ + * // queue a redraw with the host toolkit and call + * // a function when the redraw has been completed * queue_a_redraw (G_CALLBACK (on_redraw_complete), stage); * } * ]| * - * This signal is emitted before the Clutter paint + * Note: This signal is emitted before the Clutter paint * pipeline is executed. If you want to know when the pipeline has - * been completed you should connect to the ::paint signal on the - * Stage with g_signal_connect_after(). + * been completed you should use clutter_threads_add_repaint_func() + * or clutter_threads_add_repaint_func_full(). * * Since: 1.0 */ @@ -8189,12 +8200,12 @@ clutter_actor_class_init (ClutterActorClass *klass) * Subclasses of #ClutterActor should override the #ClutterActorClass.paint * virtual function paint themselves in that function. * - * It is strongly discouraged to connect a signal handler to + * It is strongly discouraged to connect a signal handler to * the #ClutterActor::paint signal; if you want to change the paint * sequence of an existing #ClutterActor instance, either create a new * #ClutterActor class and override the #ClutterActorClass.paint virtual * function, or use a #ClutterEffect. The #ClutterActor::paint signal - * will be removed in a future version of Clutter. + * will be removed in a future version of Clutter. * * Since: 0.8 * @@ -9548,9 +9559,9 @@ clutter_actor_get_preferred_height (ClutterActor *self, * An allocation does not incorporate the actor's scale or anchor point; * those transformations do not affect layout, only rendering. * - * Do not call any of the clutter_actor_get_allocation_*() family + * Do not call any of the clutter_actor_get_allocation_*() family * of functions inside the implementation of the get_preferred_width() - * or get_preferred_height() virtual functions. + * or get_preferred_height() virtual functions. * * Since: 0.8 */ @@ -9922,7 +9933,7 @@ clutter_actor_allocate (ClutterActor *self, * expected that the subclass will call clutter_layout_manager_allocate() * by itself. For instance, the following code: * - * |[ + * |[ * static void * my_actor_allocate (ClutterActor *actor, * const ClutterActorBox *allocation, @@ -9931,18 +9942,18 @@ clutter_actor_allocate (ClutterActor *self, * ClutterActorBox new_alloc; * ClutterAllocationFlags new_flags; * - * adjust_allocation (allocation, &new_alloc); + * adjust_allocation (allocation, &new_alloc); * * new_flags = flags | CLUTTER_DELEGATE_LAYOUT; * - * /* this will use the layout manager set on the actor */ - * clutter_actor_set_allocation (actor, &new_alloc, new_flags); + * // this will use the layout manager set on the actor + * clutter_actor_set_allocation (actor, &new_alloc, new_flags); * } * ]| * * is equivalent to this: * - * |[ + * |[ * static void * my_actor_allocate (ClutterActor *actor, * const ClutterActorBox *allocation, @@ -9951,14 +9962,14 @@ clutter_actor_allocate (ClutterActor *self, * ClutterLayoutManager *layout; * ClutterActorBox new_alloc; * - * adjust_allocation (allocation, &new_alloc); + * adjust_allocation (allocation, &new_alloc); * - * clutter_actor_set_allocation (actor, &new_alloc, flags); + * clutter_actor_set_allocation (actor, &new_alloc, flags); * * layout = clutter_actor_get_layout_manager (actor); * clutter_layout_manager_allocate (layout, * CLUTTER_CONTAINER (actor), - * &new_alloc, + * &new_alloc, * flags); * } * ]| @@ -10650,7 +10661,7 @@ clutter_actor_get_transformed_position (ClutterActor *self, * If you want the transformed allocation, see * clutter_actor_get_abs_allocation_vertices() instead. * - * When the actor (or one of its ancestors) is rotated around the + * When the actor (or one of its ancestors) is rotated around the * X or Y axis, it no longer appears as on the stage as a rectangle, but * as a generic quadrangle; in that case this function returns the size * of the smallest rectangle that encapsulates the entire quad. Please @@ -10658,7 +10669,7 @@ clutter_actor_get_transformed_position (ClutterActor *self, * position of this envelope to the absolute position of the actor, as * returned by clutter_actor_get_transformed_position(); if you need this * information, you need to use clutter_actor_get_abs_allocation_vertices() - * to get the coords of the actual quadrangle. + * to get the coords of the actual quadrangle. * * Since: 0.8 */ @@ -11945,11 +11956,10 @@ clutter_actor_get_depth (ClutterActor *self) * Sets the rotation angle of @self around the given axis. * * The rotation center coordinates used depend on the value of @axis: - * - * %CLUTTER_X_AXIS requires @y and @z - * %CLUTTER_Y_AXIS requires @x and @z - * %CLUTTER_Z_AXIS requires @x and @y - * + * + * - %CLUTTER_X_AXIS requires @y and @z + * - %CLUTTER_Y_AXIS requires @x and @z + * - %CLUTTER_Z_AXIS requires @x and @y * * The rotation coordinates are relative to the anchor point of the * actor, set using clutter_actor_set_anchor_point(). If no anchor @@ -14876,10 +14886,10 @@ clutter_animatable_iface_init (ClutterAnimatableIface *iface) * nature of the operation. In general the error grows when the skewing * of the actor rectangle on screen increases. * - * This function can be computationally intensive. + * This function can be computationally intensive. * - * This function only works when the allocation is up-to-date, - * i.e. inside of paint(). + * This function only works when the allocation is up-to-date, i.e. inside of + * the #ClutterActorClass.paint() implementation * * Return value: %TRUE if conversion was successful. * @@ -15130,7 +15140,7 @@ clutter_actor_get_stage (ClutterActor *actor) * actor's natural height * @flags: flags controlling the allocation * - * Allocates @self taking into account the #ClutterActor's + * Allocates @self taking into account the #ClutterActor's * preferred size, but limiting it to the maximum available width * and height provided. * @@ -15139,36 +15149,36 @@ clutter_actor_get_stage (ClutterActor *actor) * * The implementation of this function is equivalent to: * - * |[ + * |[ * if (request_mode == CLUTTER_REQUEST_HEIGHT_FOR_WIDTH) * { * clutter_actor_get_preferred_width (self, available_height, - * &min_width, - * &natural_width); + * &min_width, + * &natural_width); * width = CLAMP (natural_width, min_width, available_width); * * clutter_actor_get_preferred_height (self, width, - * &min_height, - * &natural_height); + * &min_height, + * &natural_height); * height = CLAMP (natural_height, min_height, available_height); * } * else * { * clutter_actor_get_preferred_height (self, available_width, - * &min_height, - * &natural_height); + * &min_height, + * &natural_height); * height = CLAMP (natural_height, min_height, available_height); * * clutter_actor_get_preferred_width (self, height, - * &min_width, - * &natural_width); + * &min_width, + * &natural_width); * width = CLAMP (natural_width, min_width, available_width); * } * * box.x1 = x; box.y1 = y; * box.x2 = box.x1 + available_width; * box.y2 = box.y1 + available_height; - * clutter_actor_allocate (self, &box, flags); + * clutter_actor_allocate (self, &box, flags); * ]| * * This function can be used by fluid layout managers to allocate @@ -16158,7 +16168,7 @@ clutter_actor_get_text_direction (ClutterActor *self) * Should be used by actors implementing the #ClutterContainer and with * internal children added through clutter_actor_set_parent(), for instance: * - * |[ + * |[ * static void * my_actor_init (MyActor *self) * { @@ -16166,25 +16176,23 @@ clutter_actor_get_text_direction (ClutterActor *self) * * clutter_actor_push_internal (CLUTTER_ACTOR (self)); * - * /* calling clutter_actor_set_parent() now will result in - * * the internal flag being set on a child of MyActor - * */ + * // calling clutter_actor_set_parent() now will result in + * // the internal flag being set on a child of MyActor * - * /* internal child - a background texture */ + * // internal child - a background texture * self->priv->background_tex = clutter_texture_new (); * clutter_actor_set_parent (self->priv->background_tex, * CLUTTER_ACTOR (self)); * - * /* internal child - a label */ + * // internal child - a label * self->priv->label = clutter_text_new (); * clutter_actor_set_parent (self->priv->label, * CLUTTER_ACTOR (self)); * * clutter_actor_pop_internal (CLUTTER_ACTOR (self)); * - * /* calling clutter_actor_set_parent() now will not result in - * * the internal flag being set on a child of MyActor - * */ + * // calling clutter_actor_set_parent() now will not result in + * // the internal flag being set on a child of MyActor * } * ]| * @@ -16368,7 +16376,7 @@ clutter_actor_add_action (ClutterActor *self, * * This function is the logical equivalent of: * - * |[ + * |[ * clutter_actor_meta_set_name (CLUTTER_ACTOR_META (action), name); * clutter_actor_add_action (self, action); * ]| @@ -16574,7 +16582,7 @@ clutter_actor_add_constraint (ClutterActor *self, * * This function is the logical equivalent of: * - * |[ + * |[ * clutter_actor_meta_set_name (CLUTTER_ACTOR_META (constraint), name); * clutter_actor_add_constraint (self, constraint); * ]| @@ -16824,7 +16832,7 @@ clutter_actor_add_effect (ClutterActor *self, * * This function is the logical equivalent of: * - * |[ + * |[ * clutter_actor_meta_set_name (CLUTTER_ACTOR_META (effect), name); * clutter_actor_add_effect (self, effect); * ]| @@ -17157,16 +17165,16 @@ _clutter_actor_get_paint_volume_mutable (ClutterActor *self) * The paint volume is defined as the 3D space occupied by an actor * when being painted. * - * This function will call the get_paint_volume() + * This function will call the #ClutterActorClass.get_paint_volume() * virtual function of the #ClutterActor class. Sub-classes of #ClutterActor * should not usually care about overriding the default implementation, * unless they are, for instance: painting outside their allocation, or * actors with a depth factor (not in terms of #ClutterActor:depth but real * 3D depth). * - * 2D actors overriding get_paint_volume() - * ensure their volume has a depth of 0. (This will be true so long as - * you don't call clutter_paint_volume_set_depth().) + * Note: 2D actors overriding #ClutterActorClass.get_paint_volume() + * should ensure that their volume has a depth of 0. (This will be true + * as long as you don't call clutter_paint_volume_set_depth().) * * Return value: (transfer none): a pointer to a #ClutterPaintVolume, * or %NULL if no volume could be determined. The returned pointer @@ -17296,7 +17304,7 @@ clutter_actor_get_paint_box (ClutterActor *self, * the opacity property. * * Custom actors can override the default response by implementing the - * #ClutterActor has_overlaps virtual function. See + * #ClutterActorClass.has_overlaps() virtual function. See * clutter_actor_set_offscreen_redirect() for more information. * * Return value: %TRUE if the actor may have overlapping primitives, and @@ -18337,14 +18345,14 @@ typedef struct _RealActorIter * Modifying the scene graph section that contains @root will invalidate * the iterator. * - * |[ + * |[ * ClutterActorIter iter; * ClutterActor *child; * * clutter_actor_iter_init (&iter, container); * while (clutter_actor_iter_next (&iter, &child)) * { - * /* do something with child */ + * // do something with child * } * ]| * @@ -19294,7 +19302,7 @@ clutter_actor_get_easing_delay (ClutterActor *self) * Transitions created for animatable properties use the name of the * property itself, for instance the code below: * - * |[ + * |[ * clutter_actor_set_easing_duration (actor, 1000); * clutter_actor_set_rotation (actor, CLUTTER_Y_AXIS, 360.0, x, y, z); * @@ -19304,8 +19312,8 @@ clutter_actor_get_easing_delay (ClutterActor *self) * actor); * ]| * - * will call the on_transition_stopped callback when - * the transition is finished. + * will call the `on_transition_stopped` callback when the transition + * is finished. * * If you just want to get notifications of the completion of a transition, * you should use the #ClutterActor::transition-stopped signal, using the diff --git a/clutter/clutter-backend.c b/clutter/clutter-backend.c index 0ceb2e27d..d255eee8b 100644 --- a/clutter/clutter-backend.c +++ b/clutter/clutter-backend.c @@ -1344,12 +1344,12 @@ _clutter_backend_remove_event_translator (ClutterBackend *backend, * @backend. A #CoglContext is required when using some of the * experimental 2.0 Cogl API. * - * Since CoglContext is itself experimental API this API should - * be considered experimental too. + * Since CoglContext is itself experimental API this API should + * be considered experimental too. * - * This API is not yet supported on OSX because OSX still + * This API is not yet supported on OSX because OSX still * uses the stub Cogl winsys and the Clutter backend doesn't - * explicitly create a CoglContext. + * explicitly create a CoglContext. * * Return value: (transfer none): The #CoglContext associated with @backend. * diff --git a/clutter/clutter-bin-layout.c b/clutter/clutter-bin-layout.c index adf235db2..2ee8012a8 100644 --- a/clutter/clutter-bin-layout.c +++ b/clutter/clutter-bin-layout.c @@ -29,34 +29,16 @@ * #ClutterBinLayout is a layout manager which implements the following * policy: * - * - * the preferred size is the maximum preferred size + * - the preferred size is the maximum preferred size * between all the children of the container using the - * layout; - * each child is allocated in "layers", on on top - * of the other; - * for each layer there are horizontal and vertical - * alignment policies. - * + * layout; + * - each child is allocated in "layers", on on top + * of the other; + * - for each layer there are horizontal and vertical + * alignment policies. * - *
- * Bin layout - * The image shows a #ClutterBinLayout with three layers: - * a background #ClutterCairoTexture, set to fill on both the X - * and Y axis; a #ClutterTexture, set to center on both the X and - * Y axis; and a #ClutterRectangle, set to %CLUTTER_BIN_ALIGNMENT_END - * on both the X and Y axis. - * - *
- * - * - * How to pack actors inside a BinLayout - * - * - * FIXME: MISSING XINCLUDE CONTENT - * - * - * + * The [bin-layout example](https://git.gnome.org/browse/clutter/tree/examples/bin-layout.c?h=clutter-1.18) + * shows how to pack actors inside a #ClutterBinLayout. * * #ClutterBinLayout is available since Clutter 1.2 */ diff --git a/clutter/clutter-bind-constraint.c b/clutter/clutter-bind-constraint.c index fa9490621..53cbbba8f 100644 --- a/clutter/clutter-bind-constraint.c +++ b/clutter/clutter-bind-constraint.c @@ -36,14 +36,14 @@ * can also be animated. For instance, the following code will set up three * actors to be bound to the same origin: * - * |[ - * /* source */ - * rect[0] = clutter_rectangle_new_with_color (&red_color); + * |[ + * // source + * rect[0] = clutter_rectangle_new_with_color (&red_color); * clutter_actor_set_position (rect[0], x_pos, y_pos); * clutter_actor_set_size (rect[0], 100, 100); * - * /* second rectangle */ - * rect[1] = clutter_rectangle_new_with_color (&green_color); + * // second rectangle + * rect[1] = clutter_rectangle_new_with_color (&green_color); * clutter_actor_set_size (rect[1], 100, 100); * clutter_actor_set_opacity (rect[1], 0); * @@ -52,8 +52,8 @@ * constraint = clutter_bind_constraint_new (rect[0], CLUTTER_BIND_Y, 0.0); * clutter_actor_add_constraint_with_name (rect[1], "green-y", constraint); * - * /* third rectangle */ - * rect[2] = clutter_rectangle_new_with_color (&blue_color); + * // third rectangle + * rect[2] = clutter_rectangle_new_with_color (&blue_color); * clutter_actor_set_size (rect[2], 100, 100); * clutter_actor_set_opacity (rect[2], 0); * @@ -66,7 +66,7 @@ * The following code animates the second and third rectangles to "expand" * them horizontally from underneath the first rectangle: * - * |[ + * |[ * clutter_actor_animate (rect[1], CLUTTER_EASE_OUT_CUBIC, 250, * "@constraints.green-x.offset", 100.0, * "opacity", 255, @@ -77,21 +77,6 @@ * NULL); * ]| * - * - * Animating the offset property of ClutterBindConstraint - * - * - * FIXME: MISSING XINCLUDE CONTENT - * - * - * The example above creates eight rectangles and binds them to a - * rectangle positioned in the center of the stage; when the user presses - * the center rectangle, the #ClutterBindConstraint:offset property is - * animated through the clutter_actor_animate() function to lay out the - * eight rectangles around the center one. Pressing one of the outer - * rectangles will animate the offset back to 0. - * - * * #ClutterBindConstraint is available since Clutter 1.4 */ diff --git a/clutter/clutter-binding-pool.c b/clutter/clutter-binding-pool.c index 6bce92334..66959c784 100644 --- a/clutter/clutter-binding-pool.c +++ b/clutter/clutter-binding-pool.c @@ -38,7 +38,7 @@ * inside their class initialization function and then install actions * like this: * - * |[ + * |[ * static void * foo_class_init (FooClass *klass) * { @@ -59,7 +59,7 @@ * * The callback has a signature of: * - * |[ + * |[ * gboolean (* callback) (GObject *instance, * const gchar *action_name, * guint key_val, @@ -71,19 +71,18 @@ * use clutter_binding_pool_activate() to match a #ClutterKeyEvent structure * to one of the actions: * - * |[ + * |[ * ClutterBindingPool *pool; * - * /* retrieve the binding pool for the type of the actor */ + * // retrieve the binding pool for the type of the actor * pool = clutter_binding_pool_find (G_OBJECT_TYPE_NAME (actor)); * - * /* activate any callback matching the key symbol and modifiers - * * mask of the key event. the returned value can be directly - * * used to signal that the actor has handled the event. - * */ + * // activate any callback matching the key symbol and modifiers + * // mask of the key event. the returned value can be directly + * // used to signal that the actor has handled the event. * return clutter_binding_pool_activate (pool, - * key_event->keyval, - * key_event->modifier_state, + * key_event->keyval, + * key_event->modifier_state, * G_OBJECT (actor)); * ]| * diff --git a/clutter/clutter-box-layout.c b/clutter/clutter-box-layout.c index 82ff6f05f..20b2628a1 100644 --- a/clutter/clutter-box-layout.c +++ b/clutter/clutter-box-layout.c @@ -31,30 +31,16 @@ * * The #ClutterBoxLayout is a #ClutterLayoutManager implementing the * following layout policy: - * - * all children are arranged on a single - * line; - * the axis used is controlled by the - * #ClutterBoxLayout:orientation property; - * the order of the packing is determined by the - * #ClutterBoxLayout:pack-start boolean property; - * each child will be allocated to its natural - * size or, if #ClutterActor:x-expand/#ClutterActor:y-expand - * is set, the available size; - * honours the #ClutterActor's #ClutterActor:x-align - * and #ClutterActor:y-align properties to fill the available - * size; - * if the #ClutterBoxLayout:homogeneous boolean property - * is set, then all widgets will get the same size, ignoring expand - * settings and the preferred sizes - * * - *
- * Box layout - * The image shows a #ClutterBoxLayout with the - * #ClutterBoxLayout:vertical property set to %FALSE. - * - *
+ * - all children are arranged on a single line + * - the axis used is controlled by the #ClutterBoxLayout:orientation property + * - the order of the packing is determined by the #ClutterBoxLayout:pack-start boolean property + * - each child will be allocated to its natural size or, if #ClutterActor:x-expand or + * #ClutterActor:y-expand are set, the available size + * - honours the #ClutterActor's #ClutterActor:x-align and #ClutterActor:y-align properties + * to fill the available size + * - if the #ClutterBoxLayout:homogeneous boolean propert is set, then all widgets will + * get the same size, ignoring expand settings and the preferred sizes * * It is possible to control the spacing between children of a * #ClutterBoxLayout by using clutter_box_layout_set_spacing(). diff --git a/clutter/clutter-canvas.c b/clutter/clutter-canvas.c index eb9eeb83d..82915165c 100644 --- a/clutter/clutter-canvas.c +++ b/clutter/clutter-canvas.c @@ -36,13 +36,8 @@ * that can be used to draw. #ClutterCanvas will emit the #ClutterCanvas::draw * signal when invalidated using clutter_content_invalidate(). * - * - * - * - * FIXME: MISSING XINCLUDE CONTENT - * - * - * + * See [canvas.c](https://git.gnome.org/browse/clutter/tree/examples/canvas.c?h=clutter-1.18) + * for an example of how to use #ClutterCanvas. * * #ClutterCanvas is available since Clutter 1.10. */ diff --git a/clutter/clutter-child-meta.h b/clutter/clutter-child-meta.h index df6246c6f..7e785a907 100644 --- a/clutter/clutter-child-meta.h +++ b/clutter/clutter-child-meta.h @@ -63,14 +63,14 @@ typedef struct _ClutterChildMetaClass ClutterChildMetaClass; * static void * my_container_iface_init (ClutterContainerIface *iface) * { - * /* set the rest of the #ClutterContainer vtable */ + * // set the rest of the #ClutterContainer vtable * * container_iface->child_meta_type = MY_TYPE_CHILD_META; * } * ]| * * This will automatically create a #ClutterChildMeta of type - * MY_TYPE_CHILD_META for every actor that is added to the container. + * `MY_TYPE_CHILD_META` for every actor that is added to the container. * * The child data for an actor can be retrieved using the * clutter_container_get_child_meta() function. @@ -81,9 +81,8 @@ typedef struct _ClutterChildMetaClass ClutterChildMetaClass; * * You can provide hooks for your own storage as well as control the * instantiation by overriding the #ClutterContainerIface virtual functions - * create_child_meta, - * destroy_child_meta, - * and get_child_meta. + * #ClutterContainerIface.create_child_meta(), #ClutterContainerIface.destroy_child_meta(), + * and #ClutterContainerIface.get_child_meta(). * * Since: 0.8 */ diff --git a/clutter/clutter-clone.c b/clutter/clutter-clone.c index 3de1c0505..3bcd0c387 100644 --- a/clutter/clutter-clone.c +++ b/clutter/clutter-clone.c @@ -30,9 +30,9 @@ * * #ClutterClone can be used to efficiently clone any other actor. * - * This is different from clutter_texture_new_from_actor() - * which requires support for FBOs in the underlying GL - * implementation. + * Unlike clutter_texture_new_from_actor(), #ClutterClone does not require + * the presence of support for FBOs in the underlying GL or GLES + * implementation. * * #ClutterClone is available since Clutter 1.0 */ diff --git a/clutter/clutter-color.c b/clutter/clutter-color.c index 04b1cfa5b..96dde9482 100644 --- a/clutter/clutter-color.c +++ b/clutter/clutter-color.c @@ -624,28 +624,12 @@ parse_hsla (ClutterColor *color, * * The format of @str can be either one of: * - * - * - * a standard name (as taken from the X11 rgb.txt file) - * - * - * an hexadecimal value in the form: #rgb, - * #rrggbb, #rgba or - * #rrggbbaa - * - * - * a RGB color in the form: rgb(r, g, b) - * - * - * a RGB color in the form: rgba(r, g, b, a) - * - * - * a HSL color in the form: hsl(h, s, l) - * - * - * a HSL color in the form: hsla(h, s, l, a) - * - * + * - a standard name (as taken from the X11 rgb.txt file) + * - an hexadecimal value in the form: `#rgb`, `#rrggbb`, `#rgba`, or `#rrggbbaa` + * - a RGB color in the form: `rgb(r, g, b)` + * - a RGB color in the form: `rgba(r, g, b, a)` + * - a HSL color in the form: `hsl(h, s, l)` + * -a HSL color in the form: `hsla(h, s, l, a)` * * where 'r', 'g', 'b' and 'a' are (respectively) the red, green, blue color * intensities and the opacity. The 'h', 's' and 'l' are (respectively) the diff --git a/clutter/clutter-constraint.c b/clutter/clutter-constraint.c index 9b481b572..8749ed962 100644 --- a/clutter/clutter-constraint.c +++ b/clutter/clutter-constraint.c @@ -13,126 +13,95 @@ * allocation of the actor to which they are applied by overriding the * #ClutterConstraintClass.update_allocation() virtual function. * - * - * Using Constraints - * Constraints can be used with fixed layout managers, like - * #ClutterFixedLayout, or with actors implicitly using a fixed layout - * manager, like #ClutterGroup and #ClutterStage. - * Constraints provide a way to build user interfaces by using - * relations between #ClutterActors, without explicit fixed - * positioning and sizing, similarly to how fluid layout managers like - * #ClutterBoxLayout and #ClutterTableLayout lay out their children. - * Constraints are attached to a #ClutterActor, and are available - * for inspection using clutter_actor_get_constraints(). - * Clutter provides different implementation of the #ClutterConstraint - * abstract class, for instance: - * - * - * #ClutterAlignConstraint - * this constraint can be used to align an actor - * to another one, on either the horizontal or the vertical axis; the - * #ClutterAlignConstraint uses a normalized offset between 0.0 (the - * top or the left of the source actor, depending on the axis) and - * 1.0 (the bottom or the right of the source actor, depending on the - * axis). - * - * - * #ClutterBindConstraint - * this constraint binds the X, Y, width or height - * of an actor to the corresponding position or size of a source - * actor; it can also apply an offset. - * - * - * #ClutterSnapConstraint - * this constraint "snaps" together the edges of - * two #ClutterActors; if an actor uses two constraints on - * both its horizontal or vertical edges then it can also expand to - * fit the empty space. - * - * - * - * Usage of constraints - * The example below uses various #ClutterConstraints to - * lay out three actors on a resizable stage. Only the central actor has - * an explicit size, and no actor has an explicit position. - * - * The #ClutterRectangle with #ClutterActor:name - * layerA is explicitly sized to 100 pixels by 25 - * pixels, and it's added to the #ClutterStage; - * two #ClutterAlignConstraints are used - * to anchor layerA to the center of the stage, - * by using 0.5 as the alignment #ClutterAlignConstraint:factor on - * both the X and Y axis. - * the #ClutterRectangle with #ClutterActor:name - * layerB is added to the #ClutterStage with - * no explicit size; - * the #ClutterActor:x and #ClutterActor:width - * of layerB are bound to the same properties - * of layerA using two #ClutterBindConstraint - * objects, thus keeping layerB aligned to - * layerA; - * the top edge of layerB is - * snapped together with the bottom edge of layerA; - * the bottom edge of layerB is also snapped - * together with the bottom edge of the #ClutterStage; an offset is - * given to the two #ClutterSnapConstraints to allow for some - * padding; since layerB is snapped between two - * different #ClutterActors, its height is stretched to match - * the gap; - * the #ClutterRectangle with #ClutterActor:name - * layerC mirrors layerB, - * snapping the top edge of the #ClutterStage to the top edge of - * layerC and the top edge of - * layerA to the bottom edge of - * layerC; - * - *
- * Constraints - * - *
- * - * - * FIXME: MISSING XINCLUDE CONTENT - * - * - * You can try resizing interactively the #ClutterStage and verify - * that the three #ClutterActors maintain the same position and - * size relative to each other, and to the #ClutterStage. - * - * It's important to note that Clutter does not avoid loops - * or competing constraints; if two or more #ClutterConstraints - * are operating on the same positional or dimensional attributes of an - * actor, or if the constraints on two different actors depend on each - * other, then the behavior is undefined. - * - * - * - * Implementing a ClutterConstraint - * Creating a sub-class of #ClutterConstraint requires the - * implementation of the update_allocation() - * virtual function. - * The update_allocation() virtual function - * is called during the allocation sequence of a #ClutterActor, and - * allows any #ClutterConstraint attached to that actor to modify the - * allocation before it is passed to the allocate() - * implementation. - * The #ClutterActorBox passed to the - * update_allocation() implementation contains the - * original allocation of the #ClutterActor, plus the eventual modifications - * applied by the other #ClutterConstraints. - * Constraints are queried in the same order as they were - * applied using clutter_actor_add_constraint() or - * clutter_actor_add_constraint_with_name(). - * It is not necessary for a #ClutterConstraint sub-class to chain - * up to the parent's implementation. - * If a #ClutterConstraint is parametrized - i.e. if it contains - * properties that affect the way the constraint is implemented - it should - * call clutter_actor_queue_relayout() on the actor to which it is attached - * to whenever any parameter is changed. The actor to which it is attached - * can be recovered at any point using clutter_actor_meta_get_actor(). - * - * * #ClutterConstraint is available since Clutter 1.4 + * + * ## Using Constraints + * + * Constraints can be used with fixed layout managers, like + * #ClutterFixedLayout, or with actors implicitly using a fixed layout + * manager, like #ClutterGroup and #ClutterStage. + * + * Constraints provide a way to build user interfaces by using + * relations between #ClutterActors, without explicit fixed + * positioning and sizing, similarly to how fluid layout managers like + * #ClutterBoxLayout and #ClutterTableLayout lay out their children. + * + * Constraints are attached to a #ClutterActor, and are available + * for inspection using clutter_actor_get_constraints(). + * + * Clutter provides different implementation of the #ClutterConstraint + * abstract class, for instance: + * + * - #ClutterAlignConstraint, a constraint that can be used to align + * an actor to another one on either the horizontal or the vertical + * axis, using a normalized value between 0 and 1. + * - #ClutterBindConstraint, a constraint binds the X, Y, width or height + * of an actor to the corresponding position or size of a source actor, + * with or without an offset. + * - #ClutterSnapConstraint, a constraint that "snaps" together the edges + * of two #ClutterActors; if an actor uses two constraints on both its + * horizontal or vertical edges then it can also expand to fit the empty + * space. + * + * The [constraints example](https://git.gnome.org/browse/clutter/tree/examples/constraints.c?h=clutter-1.18) + * uses various types of #ClutterConstraints to lay out three actors on a + * resizable stage. Only the central actor has an explicit size, and no + * actor has an explicit position. + * + * - The #ClutterActor with #ClutterActor:name `layerA` is explicitly + * sized to 100 pixels by 25 pixels, and it's added to the #ClutterStage + * - two #ClutterAlignConstraints are used to anchor `layerA` to the + * center of the stage, by using 0.5 as the alignment #ClutterAlignConstraint:factor on + * both the X and Y axis + * - the #ClutterActor with #ClutterActor:name `layerB` is added to the + * #ClutterStage with no explicit size + * - the #ClutterActor:x and #ClutterActor:width of `layerB` are bound + * to the same properties of `layerA` using two #ClutterBindConstraint + * objects, thus keeping `layerB` aligned to `layerA` + * - the top edge of `layerB` is snapped together with the bottom edge + * of `layerA`; the bottom edge of `layerB` is also snapped together with + * the bottom edge of the #ClutterStage; an offset is given to the two + * #ClutterSnapConstraintss to allow for some padding; since `layerB` is + * snapped between two different #ClutterActors, its height is stretched + * to match the gap + * - the #ClutterActor with #ClutterActor:name `layerC` mirrors `layerB`, + * snapping the top edge of the #ClutterStage to the top edge of `layerC` + * and the top edge of `layerA` to the bottom edge of `layerC` + * + * You can try resizing interactively the #ClutterStage and verify + * that the three #ClutterActors maintain the same position and + * size relative to each other, and to the #ClutterStage. + * + * It is important to note that Clutter does not avoid loops or + * competing constraints; if two or more #ClutterConstraints + * are operating on the same positional or dimensional attributes of an + * actor, or if the constraints on two different actors depend on each + * other, then the behavior is undefined. + * + * ## Implementing a ClutterConstraint + * + * Creating a sub-class of #ClutterConstraint requires the + * implementation of the #ClutterConstraintClass.update_allocation() + * virtual function. + * + * The `update_allocation()` virtual function is called during the + * allocation sequence of a #ClutterActor, and allows any #ClutterConstraint + * attached to that actor to modify the allocation before it is passed to + * the actor's #ClutterActorClass.allocate() implementation. + * + * The #ClutterActorBox passed to the `update_allocation()` implementation + * contains the original allocation of the #ClutterActor, plus the eventual + * modifications applied by the other #ClutterConstraints, in the same order + * the constraints have been applied to the actor. + * + * It is not necessary for a #ClutterConstraint sub-class to chain + * up to the parent's implementation. + * + * If a #ClutterConstraint is parametrized - i.e. if it contains + * properties that affect the way the constraint is implemented - it should + * call clutter_actor_queue_relayout() on the actor to which it is attached + * to whenever any parameter is changed. The actor to which it is attached + * can be recovered at any point using clutter_actor_meta_get_actor(). */ #ifdef HAVE_CONFIG_H diff --git a/clutter/clutter-deform-effect.c b/clutter/clutter-deform-effect.c index f619505bc..925866a85 100644 --- a/clutter/clutter-deform-effect.c +++ b/clutter/clutter-deform-effect.c @@ -39,17 +39,16 @@ * a #ClutterActor and then the Cogl vertex buffers API to submit the * geometry to the GPU. * - * - * Implementing ClutterDeformEffect - * Sub-classes of #ClutterDeformEffect should override the - * #ClutterDeformEffectClass.deform_vertex() virtual function; this function - * is called on every vertex that needs to be deformed by the effect. - * Each passed vertex is an in-out parameter that initially contains the - * position of the vertex and should be modified according to a specific - * deformation algorithm. - * - * * #ClutterDeformEffect is available since Clutter 1.4 + * + * ## Implementing ClutterDeformEffect + * + * Sub-classes of #ClutterDeformEffect should override the + * #ClutterDeformEffectClass.deform_vertex() virtual function; this function + * is called on every vertex that needs to be deformed by the effect. + * Each passed vertex is an in-out parameter that initially contains the + * position of the vertex and should be modified according to a specific + * deformation algorithm. */ #ifdef HAVE_CONFIG_H diff --git a/clutter/clutter-drag-action.c b/clutter/clutter-drag-action.c index c80545368..13145221e 100644 --- a/clutter/clutter-drag-action.c +++ b/clutter/clutter-drag-action.c @@ -34,7 +34,7 @@ * a #ClutterActor and setting it as reactive; for instance, the following * code: * - * |[ + * |[ * clutter_actor_add_action (actor, clutter_drag_action_new ()); * clutter_actor_set_reactive (actor, TRUE); * ]| @@ -54,19 +54,11 @@ * parented and exist between the emission of #ClutterDragAction::drag-begin * and #ClutterDragAction::drag-end. * - * - * A simple draggable actor - * - * - * FIXME: MISSING XINCLUDE CONTENT - * - * - * The example program above allows dragging the rectangle around - * the stage using a #ClutterDragAction. When pressing the - * Shift key the actor that is going to be dragged is a - * separate rectangle, and when the drag ends, the original rectangle will - * be animated to the final coordinates. - * + * The [drag-action example](https://git.gnome.org/browse/clutter/tree/examples/drag-action.c?h=clutter-1.18) + * allows dragging the rectangle around the stage using a #ClutterDragAction. + * When pressing the `Shift` key the actor that is being dragged will be a + * separate rectangle, and when the drag ends, the original rectangle will be + * animated to the final drop coordinates. * * #ClutterDragAction is available since Clutter 1.4 */ diff --git a/clutter/clutter-drop-action.c b/clutter/clutter-drop-action.c index 7f71ae3a1..a1a99fb5d 100644 --- a/clutter/clutter-drop-action.c +++ b/clutter/clutter-drop-action.c @@ -36,7 +36,7 @@ * #ClutterDropAction::drop signal and handling the drop from there, * for instance: * - * |[ + * |[ * ClutterAction *action = clutter_drop_action (); * * g_signal_connect (action, "drop", G_CALLBACK (on_drop), NULL); @@ -49,18 +49,12 @@ * cause the #ClutterDropAction::drop signal to be skipped when the input * device button is released. * - * - * Drop targets - * - * - * FIXME: MISSING XINCLUDE CONTENT - * - * - * - * * It's important to note that #ClutterDropAction will only work with * actors dragged using #ClutterDragAction. * + * See [drop-action.c](https://git.gnome.org/browse/clutter/tree/examples/drop-action.c?h=clutter-1.18) + * for an example of how to use #ClutterDropAction. + * * #ClutterDropAction is available since Clutter 1.8 */ diff --git a/clutter/clutter-effect.c b/clutter/clutter-effect.c index 8430a7616..33d8f1387 100644 --- a/clutter/clutter-effect.c +++ b/clutter/clutter-effect.c @@ -36,78 +36,50 @@ * actor without sub-classing the actor itself and overriding the * #ClutterActorClass.paint()_ virtual function. * - * - * Implementing a ClutterEffect - * - * Creating a sub-class of #ClutterEffect requires overriding the - * ‘paint’ method. The implementation of the function should look - * something like this: - * - * + * ## Implementing a ClutterEffect + * + * Creating a sub-class of #ClutterEffect requires overriding the + * #ClutterEffectClass.paint() method. The implementation of the function should look + * something like this: + * + * |[ * void effect_paint (ClutterEffect *effect, ClutterEffectPaintFlags flags) * { - * /* Set up initialisation of the paint such as binding a - * CoglOffscreen or other operations */ + * // Set up initialisation of the paint such as binding a + * // CoglOffscreen or other operations * - * /* Chain to the next item in the paint sequence. This will either call - * ‘paint’ on the next effect or just paint the actor if this is - * the last effect. */ + * // Chain to the next item in the paint sequence. This will either call + * // ‘paint’ on the next effect or just paint the actor if this is + * // the last effect. * ClutterActor *actor = * clutter_actor_meta_get_actor (CLUTTER_ACTOR_META (effect)); + * * clutter_actor_continue_paint (actor); * - * /* perform any cleanup of state, such as popping the - * CoglOffscreen */ + * // perform any cleanup of state, such as popping the CoglOffscreen * } - * - * - * The effect can optionally avoid calling - * clutter_actor_continue_paint() to skip any further stages of - * the paint sequence. This is useful for example if the effect - * contains a cached image of the actor. In that case it can - * optimise painting by avoiding the actor paint and instead - * painting the cached image. The %CLUTTER_EFFECT_PAINT_ACTOR_DIRTY - * flag is useful in this case. Clutter will set this flag when a - * redraw has been queued on the actor since it was last - * painted. The effect can use this information to decide if the - * cached image is still valid. - * - * - * The ‘paint’ virtual was added in Clutter 1.8. Prior to that there - * were two separate functions as follows. - * - * - * pre_paint(), which is called - * before painting the #ClutterActor. - * post_paint(), which is called - * after painting the #ClutterActor. - * - * The pre_paint() function was used to set - * up the #ClutterEffect right before the #ClutterActor's paint - * sequence. This function can fail, and return %FALSE; in that case, no - * post_paint() invocation will follow. - * The post_paint() function was called after the - * #ClutterActor's paint sequence. - * - * With these two functions it is not possible to skip the rest of - * the paint sequence. The default implementation of the ‘paint’ - * virtual calls #ClutterEffectClass.pre_paint(), clutter_actor_continue_paint() - * and then #ClutterEffectClass.post_paint() so that existing actors that aren't - * using the #ClutterEffectClass.paint() virtual will continue to work. New - * effects using the #ClutterEffectClass.paint() virtual do not need to implement - * pre or post paint. - * - * - * A simple ClutterEffect implementation - * The example below creates two rectangles: one will be - * painted "behind" the actor, while another will be painted "on - * top" of the actor. The #ClutterActorMetaClass.set_actor() - * implementation will create the two materials used for the two - * different rectangles; the #ClutterEffectClass.paint() implementation - * will paint the first material using cogl_rectangle(), before - * continuing and then it will paint paint the second material - * after. - * + * ]| + * + * The effect can optionally avoid calling clutter_actor_continue_paint() to skip any + * further stages of the paint sequence. This is useful for example if the effect + * contains a cached image of the actor. In that case it can optimise painting by + * avoiding the actor paint and instead painting the cached image. + * + * The %CLUTTER_EFFECT_PAINT_ACTOR_DIRTY flag is useful in this case. Clutter will set + * this flag when a redraw has been queued on the actor since it was last painted. The + * effect can use this information to decide if the cached image is still valid. + * + * ## A simple ClutterEffect implementation + * + * The example below creates two rectangles: one will be painted "behind" the actor, + * while another will be painted "on top" of the actor. + * + * The #ClutterActorMetaClass.set_actor() implementation will create the two materials + * used for the two different rectangles; the #ClutterEffectClass.paint() implementation + * will paint the first material using cogl_rectangle(), before continuing and then it + * will paint paint the second material after. + * + * |[ * typedef struct { * ClutterEffect parent_instance; * @@ -125,35 +97,33 @@ * { * MyEffect *self = MY_EFFECT (meta); * - * /* Clear the previous state */ - * if (self->rect_1) + * // Clear the previous state // + * if (self->rect_1) * { - * cogl_handle_unref (self->rect_1); - * self->rect_1 = NULL; + * cogl_handle_unref (self->rect_1); + * self->rect_1 = NULL; * } * - * if (self->rect_2) + * if (self->rect_2) * { - * cogl_handle_unref (self->rect_2); - * self->rect_2 = NULL; + * cogl_handle_unref (self->rect_2); + * self->rect_2 = NULL; * } * - * /* Maintain a pointer to the actor * - * self->actor = actor; + * // Maintain a pointer to the actor + * self->actor = actor; * - * /* If we've been detached by the actor then we should - * * just bail out here - * */ - * if (self->actor == NULL) + * // If we've been detached by the actor then we should just bail out here + * if (self->actor == NULL) * return; * - * /* Create a red material */ - * self->rect_1 = cogl_material_new (); - * cogl_material_set_color4f (self->rect_1, 1.0, 0.0, 0.0, 1.0); + * // Create a red material + * self->rect_1 = cogl_material_new (); + * cogl_material_set_color4f (self->rect_1, 1.0, 0.0, 0.0, 1.0); * - * /* Create a green material */ - * self->rect_2 = cogl_material_new (); - * cogl_material_set_color4f (self->rect_2, 0.0, 1.0, 0.0, 1.0); + * // Create a green material + * self->rect_2 = cogl_material_new (); + * cogl_material_set_color4f (self->rect_2, 0.0, 1.0, 0.0, 1.0); * } * * static gboolean @@ -162,17 +132,17 @@ * MyEffect *self = MY_EFFECT (effect); * gfloat width, height; * - * clutter_actor_get_size (self->actor, &width, &height); + * clutter_actor_get_size (self->actor, &width, &height); * - * /* Paint the first rectangle in the upper left quadrant */ - * cogl_set_source (self->rect_1); + * // Paint the first rectangle in the upper left quadrant + * cogl_set_source (self->rect_1); * cogl_rectangle (0, 0, width / 2, height / 2); * - * /* Continue to the rest of the paint sequence */ - * clutter_actor_continue_paint (self->actor); + * // Continue to the rest of the paint sequence + * clutter_actor_continue_paint (self->actor); * - * /* Paint the second rectangle in the lower right quadrant */ - * cogl_set_source (self->rect_2); + * // Paint the second rectangle in the lower right quadrant + * cogl_set_source (self->rect_2); * cogl_rectangle (width / 2, height / 2, width, height); * } * @@ -181,13 +151,11 @@ * { * ClutterActorMetaClas *meta_class = CLUTTER_ACTOR_META_CLASS (klass); * - * meta_class->set_actor = my_effect_set_actor; + * meta_class->set_actor = my_effect_set_actor; * - * klass->paint = my_effect_paint; + * klass->paint = my_effect_paint; * } - * - * - * + * ]| * * #ClutterEffect is available since Clutter 1.4 */ diff --git a/clutter/clutter-flow-layout.c b/clutter/clutter-flow-layout.c index eb23b53de..064566643 100644 --- a/clutter/clutter-flow-layout.c +++ b/clutter/clutter-flow-layout.c @@ -29,40 +29,25 @@ * #ClutterFlowLayout is a layout manager which implements the following * policy: * - * - * the preferred natural size depends on the value + * - the preferred natural size depends on the value * of the #ClutterFlowLayout:orientation property; the layout will try * to maintain all its children on a single row or - * column; - * if either the width or the height allocated are + * column; + * - if either the width or the height allocated are * smaller than the preferred ones, the layout will wrap; in this case, * the preferred height or width, respectively, will take into account - * the amount of columns and rows; - * each line (either column or row) in reflowing will + * the amount of columns and rows; + * - each line (either column or row) in reflowing will * have the size of the biggest cell on that line; if the * #ClutterFlowLayout:homogeneous property is set to %FALSE the actor * will be allocated within that area, and if set to %TRUE instead the - * actor will be given exactly that area; - * the size of the columns or rows can be controlled + * actor will be given exactly that area; + * - the size of the columns or rows can be controlled * for both minimum and maximum; the spacing can also be controlled - * in both columns and rows. - * + * in both columns and rows. * - *
- * Horizontal flow layout - * The image shows a #ClutterFlowLayout with the - * #ClutterFlowLayout:orientation propert set to - * %CLUTTER_FLOW_HORIZONTAL. - * - *
- * - * - * - * - * FIXME: MISSING XINCLUDE CONTENT - * - * - * + * The [flow-layout example](https://git.gnome.org/browse/clutter/tree/examples/flow-layout.c?h=clutter-1.18) + * shows how to use the #ClutterFlowLayout. * * #ClutterFlowLayout is available since Clutter 1.2 */ diff --git a/clutter/clutter-gesture-action.c b/clutter/clutter-gesture-action.c index 35019a791..179905e1a 100644 --- a/clutter/clutter-gesture-action.c +++ b/clutter/clutter-gesture-action.c @@ -38,7 +38,7 @@ * To use #ClutterGestureAction you just need to apply it to a #ClutterActor * using clutter_actor_add_action() and connect to the signals: * - * |[ + * |[ * ClutterAction *action = clutter_gesture_action_new (); * * clutter_actor_add_action (actor, action); @@ -48,37 +48,37 @@ * g_signal_connect (action, "gesture-end", G_CALLBACK (on_gesture_end), NULL); * ]| * - * - * Creating Gesture actions - * A #ClutterGestureAction provides four separate states that can be - * used to recognize or ignore gestures when writing a new action class: - * Cancel - Prepare -> Begin -> Cancel - Prepare -> Begin -> End - Prepare -> Begin -> Progress -> Cancel - Prepare -> Begin -> Progress -> End - * ]]> - * - * Each #ClutterGestureAction starts in the "prepare" state, and calls - * the #ClutterGestureActionClass.gesture_prepare() virtual function; this - * state can be used to reset the internal state of a #ClutterGestureAction - * subclass, but it can also immediately cancel a gesture without going - * through the rest of the states. - * The "begin" state follows the "prepare" state, and calls the - * #ClutterGestureActionClass.gesture_begin() virtual function. This state - * signals the start of a gesture recognizing process. From the "begin" state - * the gesture recognition process can successfully end, by going to the - * "end" state; it can continue in the "progress" state, in case of a - * continuous gesture; or it can be terminated, by moving to the "cancel" - * state. - * In case of continuous gestures, the #ClutterGestureAction will use - * the "progress" state, calling the #ClutterGestureActionClass.gesture_progress() - * virtual function; the "progress" state will continue until the end of the - * gesture, in which case the "end" state will be reached, or until the - * gesture is cancelled, in which case the "cancel" gesture will be used - * instead. - * + * ## Creating Gesture actions + * + * A #ClutterGestureAction provides four separate states that can be + * used to recognize or ignore gestures when writing a new action class: + * + * - Prepare -> Cancel + * - Prepare -> Begin -> Cancel + * - Prepare -> Begin -> End + * - Prepare -> Begin -> Progress -> Cancel + * - Prepare -> Begin -> Progress -> End + * + * Each #ClutterGestureAction starts in the "prepare" state, and calls + * the #ClutterGestureActionClass.gesture_prepare() virtual function; this + * state can be used to reset the internal state of a #ClutterGestureAction + * subclass, but it can also immediately cancel a gesture without going + * through the rest of the states. + * + * The "begin" state follows the "prepare" state, and calls the + * #ClutterGestureActionClass.gesture_begin() virtual function. This state + * signals the start of a gesture recognizing process. From the "begin" state + * the gesture recognition process can successfully end, by going to the + * "end" state; it can continue in the "progress" state, in case of a + * continuous gesture; or it can be terminated, by moving to the "cancel" + * state. + * + * In case of continuous gestures, the #ClutterGestureAction will use + * the "progress" state, calling the #ClutterGestureActionClass.gesture_progress() + * virtual function; the "progress" state will continue until the end of the + * gesture, in which case the "end" state will be reached, or until the + * gesture is cancelled, in which case the "cancel" gesture will be used + * instead. * * Since: 1.8 */ diff --git a/clutter/clutter-image.c b/clutter/clutter-image.c index 96dba913f..c494767c1 100644 --- a/clutter/clutter-image.c +++ b/clutter/clutter-image.c @@ -28,13 +28,10 @@ * @Short_Description: Image data content * * #ClutterImage is a #ClutterContent implementation that displays - * image data. + * image data inside a #ClutterActor. * - * - * - * FIXME: MISSING XINCLUDE CONTENT - * - * + * See [image.c](https://git.gnome.org/browse/clutter/tree/examples/image.c?h=clutter-1.18) + * for an example of how to use #ClutterImage. * * #ClutterImage is available since Clutter 1.10. */ diff --git a/clutter/clutter-input-device.c b/clutter/clutter-input-device.c index 6fe05b057..9b05453dc 100644 --- a/clutter/clutter-input-device.c +++ b/clutter/clutter-input-device.c @@ -1036,9 +1036,9 @@ clutter_input_device_get_device_mode (ClutterInputDevice *device) * |[ * ClutterEvent c_event; * - * translate_native_event_to_clutter (native_event, &c_event); + * translate_native_event_to_clutter (native_event, &c_event); * - * clutter_do_event (&c_event); + * clutter_do_event (&c_event); * ]| * * Before letting clutter_do_event() process the event, it is necessary to call @@ -1049,20 +1049,18 @@ clutter_input_device_get_device_mode (ClutterInputDevice *device) * ClutterDeviceManager *manager; * ClutterInputDevice *device; * - * translate_native_event_to_clutter (native_event, &c_event); + * translate_native_event_to_clutter (native_event, &c_event); * - * /* get the device manager */ + * // get the device manager * manager = clutter_device_manager_get_default (); * - * /* use the default Core Pointer that Clutter - * * backends register by default - * */ + * // use the default Core Pointer that Clutter backends register by default * device = clutter_device_manager_get_core_device (manager, %CLUTTER_POINTER_DEVICE); * - * /* update the state of the input device */ - * clutter_input_device_update_from_event (device, &c_event, FALSE); + * // update the state of the input device + * clutter_input_device_update_from_event (device, &c_event, FALSE); * - * clutter_do_event (&c_event); + * clutter_do_event (&c_event); * ]| * * The @update_stage boolean argument should be used when the input device @@ -1272,7 +1270,7 @@ clutter_input_device_get_axis (ClutterInputDevice *device, * * clutter_input_device_get_axis_value (device, axes, * CLUTTER_INPUT_AXIS_PRESSURE, - * &pressure_value); + * &pressure_value); * ]| * * Return value: %TRUE if the value was set, and %FALSE otherwise diff --git a/clutter/clutter-layout-manager.c b/clutter/clutter-layout-manager.c index e1bce2e3c..3b731c928 100644 --- a/clutter/clutter-layout-manager.c +++ b/clutter/clutter-layout-manager.c @@ -38,227 +38,36 @@ * Clutter provides some simple #ClutterLayoutManager sub-classes, like * #ClutterFlowLayout and #ClutterBinLayout. * - * - * Using a Layout Manager inside an Actor - * In order to use a #ClutterLayoutManager inside a #ClutterActor - * sub-class you should invoke clutter_layout_manager_get_preferred_width() - * inside the #ClutterActorClass.get_preferred_width() virtual function and - * clutter_layout_manager_get_preferred_height() inside the - * #ClutterActorClass.get_preferred_height() virtual functions implementation. - * You should also call clutter_layout_manager_allocate() inside the - * implementation of the #ClutterActorClass.allocate() virtual function. - * In order to receive notifications for changes in the layout - * manager policies you should also connect to the - * #ClutterLayoutManager::layout-changed signal and queue a relayout - * on your actor. The following code should be enough if the actor - * does not need to perform specific operations whenever a layout - * manager changes: - * - * g_signal_connect_swapped (layout_manager, - * "layout-changed", - * G_CALLBACK (clutter_actor_queue_relayout), - * actor); - * - * + * ## Implementing a ClutterLayoutManager + * The implementation of a layout manager does not differ from the + * implementation of the size requisition and allocation bits of + * #ClutterActor, so you should read the relative documentation + * forr subclassing #ClutterActor. * - * - * Implementing a ClutterLayoutManager - * The implementation of a layout manager does not differ from - * the implementation of the size requisition and allocation bits of - * #ClutterActor, so you should read the relative documentation - * for subclassing - * ClutterActor. - * The layout manager implementation can hold a back pointer - * to the #ClutterContainer by implementing the - * set_container() virtual function. The layout manager - * should not hold a real reference (i.e. call g_object_ref()) on the - * container actor, to avoid reference cycles. - * If a layout manager has properties affecting the layout - * policies then it should emit the #ClutterLayoutManager::layout-changed - * signal on itself by using the clutter_layout_manager_layout_changed() - * function whenever one of these properties changes. - * + * The layout manager implementation can hold a back pointer to the + * #ClutterContainer by implementing the #ClutterLayoutManagerClass.set_container() + * virtual function. The layout manager should not hold a real reference (i.e. + * call g_object_ref()) on the container actor, to avoid reference cycles. * - * - * Animating a ClutterLayoutManager - * A layout manager is used to let a #ClutterContainer take complete - * ownership over the layout (that is: the position and sizing) of its - * children; this means that using the Clutter animation API, like - * clutter_actor_animate(), to animate the position and sizing of a child of - * a layout manager it is not going to work properly, as the animation will - * automatically override any setting done by the layout manager - * itself. - * It is possible for a #ClutterLayoutManager sub-class to animate its - * children layout by using the base class animation support. The - * #ClutterLayoutManager animation support consists of three virtual - * functions: #ClutterLayoutManagerClass.begin_animation(), - * #ClutterLayoutManagerClass.get_animation_progress(), and - * #ClutterLayoutManagerClass.end_animation(). - * - * - * begin_animation (duration, easing) - * This virtual function is invoked when the layout - * manager should begin an animation. The implementation should set up - * the state for the animation and create the ancillary objects for - * animating the layout. The default implementation creates a - * #ClutterTimeline for the given duration and a #ClutterAlpha binding - * the timeline to the given easing mode. This function returns a - * #ClutterAlpha which should be used to control the animation from - * the caller perspective. - * - * - * get_animation_progress() - * This virtual function should be invoked when animating - * a layout manager. It returns the progress of the animation, using the - * same semantics as the #ClutterAlpha:alpha value. - * - * - * end_animation() - * This virtual function is invoked when the animation of - * a layout manager ends, and it is meant to be used for bookkeeping the - * objects created in the begin_animation() - * function. The default implementation will call it implicitly when the - * timeline is complete. - * - * - * The simplest way to animate a layout is to create a #ClutterTimeline - * inside the begin_animation() virtual function, along - * with a #ClutterAlpha, and for each #ClutterTimeline::new-frame signal - * emission call clutter_layout_manager_layout_changed(), which will cause a - * relayout. The #ClutterTimeline::completed signal emission should cause - * clutter_layout_manager_end_animation() to be called. The default - * implementation provided internally by #ClutterLayoutManager does exactly - * this, so most sub-classes should either not override any animation-related - * virtual function or simply override #ClutterLayoutManagerClass.begin_animation() - * and #ClutterLayoutManagerClass.end_animation() to set up ad hoc state, and then - * chain up to the parent's implementation. - * - * Animation of a Layout Manager - * The code below shows how a #ClutterLayoutManager sub-class should - * provide animating the allocation of its children from within the - * #ClutterLayoutManagerClass.allocate() virtual function implementation. The - * animation is computed between the last stable allocation performed - * before the animation started and the desired final allocation. - * The is_animating variable is stored inside the - * #ClutterLayoutManager sub-class and it is updated by overriding the - * #ClutterLayoutManagerClass.begin_animation() and the - * #ClutterLayoutManagerClass.end_animation() virtual functions and chaining up - * to the base class implementation. - * The last stable allocation is stored within a #ClutterLayoutMeta - * sub-class used by the implementation. - * - * static void - * my_layout_manager_allocate (ClutterLayoutManager *manager, - * ClutterContainer *container, - * const ClutterActorBox *allocation, - * ClutterAllocationFlags flags) - * { - * MyLayoutManager *self = MY_LAYOUT_MANAGER (manager); - * ClutterActor *child; + * If a layout manager has properties affecting the layout policies then it should + * emit the #ClutterLayoutManager::layout-changed signal on itself by using the + * clutter_layout_manager_layout_changed() function whenever one of these properties + * changes. * - * for (child = clutter_actor_get_first_child (CLUTTER_ACTOR (container)); - * child != NULL; - * child = clutter_actor_get_next_sibling (child)) - * { - * ClutterLayoutMeta *meta; - * MyLayoutMeta *my_meta; + * ## Layout Properties * - * /* retrieve the layout meta-object */ - * meta = clutter_layout_manager_get_child_meta (manager, - * container, - * child); - * my_meta = MY_LAYOUT_META (meta); + * If a layout manager has layout properties, that is properties that + * should exist only as the result of the presence of a specific (layout + * manager, container actor, child actor) combination, and it wishes to store + * those properties inside a #ClutterLayoutMeta, then it should override the + * #ClutterLayoutManagerClass.get_child_meta_type() virtual function to return + * the #GType of the #ClutterLayoutMeta sub-class used to store the layout + * properties; optionally, the #ClutterLayoutManager sub-class might also + * override the #ClutterLayoutManagerClass.create_child_meta() virtual function + * to control how the #ClutterLayoutMeta instance is created, otherwise the + * default implementation will be equivalent to: * - * /* compute the desired allocation for the child */ - * compute_allocation (self, my_meta, child, - * allocation, flags, - * &child_box); - * - * /* this is the additional code that deals with the animation - * * of the layout manager - * */ - * if (!self->is_animating) - * { - * /* store the last stable allocation for later use */ - * my_meta->last_alloc = clutter_actor_box_copy (&child_box); - * } - * else - * { - * ClutterActorBox end = { 0, }; - * gdouble p; - * - * /* get the progress of the animation */ - * p = clutter_layout_manager_get_animation_progress (manager); - * - * if (my_meta->last_alloc != NULL) - * { - * /* copy the desired allocation as the final state */ - * end = child_box; - * - * /* then interpolate the initial and final state - * * depending on the progress of the animation, - * * and put the result inside the box we will use - * * to allocate the child - * */ - * clutter_actor_box_interpolate (my_meta->last_alloc, - * &end, - * p, - * &child_box); - * } - * else - * { - * /* if there is no stable allocation then the child was - * * added while animating; one possible course of action - * * is to just bail out and fall through to the allocation - * * to position the child directly at its final state - * */ - * my_meta->last_alloc = - * clutter_actor_box_copy (&child_box); - * } - * } - * - * /* allocate the child */ - * clutter_actor_allocate (child, &child_box, flags); - * } - * } - * - * - * Sub-classes of #ClutterLayoutManager that support animations of the - * layout changes should call clutter_layout_manager_begin_animation() - * whenever a layout property changes value, e.g.: - * - * - * if (self->orientation != new_orientation) - * { - * ClutterLayoutManager *manager; - * - * self->orientation = new_orientation; - * - * manager = CLUTTER_LAYOUT_MANAGER (self); - * clutter_layout_manager_layout_changed (manager); - * clutter_layout_manager_begin_animation (manager, 500, CLUTTER_LINEAR); - * - * g_object_notify (G_OBJECT (self), "orientation"); - * } - * - * - * The code above will animate a change in the - * orientation layout property of a layout manager. - * - * - * - * Layout Properties - * If a layout manager has layout properties, that is properties that - * should exist only as the result of the presence of a specific (layout - * manager, container actor, child actor) combination, and it wishes to store - * those properties inside a #ClutterLayoutMeta, then it should override the - * #ClutterLayoutManagerClass.get_child_meta_type() virtual function to return - * the #GType of the #ClutterLayoutMeta sub-class used to store the layout - * properties; optionally, the #ClutterLayoutManager sub-class might also - * override the #ClutterLayoutManagerClass.create_child_meta() virtual function - * to control how the #ClutterLayoutMeta instance is created, otherwise the - * default implementation will be equivalent to: - * + * |[ * ClutterLayoutManagerClass *klass; * GType meta_type; * @@ -270,22 +79,23 @@ * "container", container, * "actor", actor, * NULL); - * - * Where manager is the #ClutterLayoutManager, - * container is the #ClutterContainer using the - * #ClutterLayoutManager and actor is the #ClutterActor - * child of the #ClutterContainer. - * + * ]| * - * - * Using ClutterLayoutManager with ClutterScript - * #ClutterLayoutManager instance can be created in the same way - * as other objects in #ClutterScript; properties can be set using the - * common syntax. - * Layout properties can be set on children of a container with - * a #ClutterLayoutManager using the layout:: - * modifier on the property name, for instance: - * + * Where `manager` is the #ClutterLayoutManager, `container` is the + * #ClutterContainer using the #ClutterLayoutManager, and `actor` is + * the #ClutterActor child of the #ClutterContainer. + * + * ## Using ClutterLayoutManager with ClutterScript + * + * #ClutterLayoutManager instances can be created in the same way + * as other objects in #ClutterScript; properties can be set using the + * common syntax. + * + * Layout properties can be set on children of a container with + * a #ClutterLayoutManager using the `layout::` modifier on the property + * name, for instance: + * + * |[ * { * "type" : "ClutterBox", * "layout-manager" : { "type" : "ClutterTableLayout" }, @@ -314,8 +124,7 @@ * } * ] * } - * - * + * ]| * * #ClutterLayoutManager is available since Clutter 1.2 */ diff --git a/clutter/clutter-main.c b/clutter/clutter-main.c index bfa1dd084..04834d36f 100644 --- a/clutter/clutter-main.c +++ b/clutter/clutter-main.c @@ -23,70 +23,28 @@ /** * SECTION:clutter-main - * @short_description: Various 'global' clutter functions. + * @short_description: Various 'global' Clutter functions. * * Functions to retrieve various global Clutter resources and other utility * functions for mainloops, events and threads * - * - * Threading Model - * Clutter is thread-aware: all operations - * performed by Clutter are assumed to be under the big Clutter lock, - * which is created when the threading is initialized through - * clutter_init(). - * - * Thread Initialization - * The code below shows how to correctly initialize Clutter - * in a multi-threaded environment. These operations are mandatory for - * applications that wish to use threads with Clutter. - * - * int - * main (int argc, char *argv[]) - * { - * /* initialize Clutter */ - * clutter_init (&argc, &argv); + * ## The Clutter Threading Model * - * /* program code */ + * Clutter is *thread-aware*: all operations performed by Clutter are assumed + * to be under the Big Clutter Lock, which is created when the threading is + * initialized through clutter_init(), and entered when calling user-related + * code during event handling and actor drawing. * - * /* acquire the main lock */ - * clutter_threads_enter (); + * The only safe and portable way to use the Clutter API in a multi-threaded + * environment is to only access the Clutter API from a thread that did called + * clutter_init() and clutter_main(). * - * /* start the main loop */ - * clutter_main (); + * The common pattern for using threads with Clutter is to use worker threads + * to perform blocking operations and then install idle or timeout sources with + * the result when the thread finishes, and update the UI from those callbacks. * - * /* release the main lock */ - * clutter_threads_leave (); - * - * /* clean up */ - * return 0; - * } - * - * - * This threading model has the caveat that it is only safe to call - * Clutter's API when the lock has been acquired — which happens - * between pairs of clutter_threads_enter() and clutter_threads_leave() - * calls. - * The only safe and portable way to use the Clutter API in a - * multi-threaded environment is to never access the API from a thread that - * did not call clutter_init() and clutter_main(). - * The common pattern for using threads with Clutter is to use worker - * threads to perform blocking operations and then install idle or timeout - * sources with the result when the thread finished. - * Clutter provides thread-aware variants of g_idle_add() and - * g_timeout_add() that acquire the Clutter lock before invoking the provided - * callback: clutter_threads_add_idle() and - * clutter_threads_add_timeout(). - * The example below shows how to use a worker thread to perform a - * blocking operation, and perform UI updates using the main loop. - * - * A worker thread example - * - * - * FIXME: MISSING XINCLUDE CONTENT - * - * - * - * + * For a working example of how to use a worker thread to update the UI, see + * [threads.c](https://git.gnome.org/browse/clutter/tree/examples/threads.c?h=clutter-1.18) */ #ifdef HAVE_CONFIG_H @@ -556,12 +514,10 @@ clutter_redraw (ClutterStage *stage) * all #ClutterStages managed by Clutter. * * If @enable is %FALSE the following events will not work: - * - * ClutterActor::motion-event, unless on the - * #ClutterStage - * ClutterActor::enter-event - * ClutterActor::leave-event - * + * + * - ClutterActor::motion-event, except on the #ClutterStage + * - ClutterActor::enter-event + * - ClutterActor::leave-event * * Since: 0.6 * @@ -1110,13 +1066,13 @@ _clutter_threads_dispatch_free (gpointer data) * SafeClosure *closure = data; * gboolean res = FALSE; * - * /* mark the critical section */ + * // mark the critical section // * * clutter_threads_enter(); * - * /* the callback does not need to acquire the Clutter - * * lock itself, as it is held by the this proxy handler - * */ + * // the callback does not need to acquire the Clutter + * / lock itself, as it is held by the this proxy handler + * // * res = closure->callback (closure->data); * * clutter_threads_leave(); @@ -1129,8 +1085,8 @@ _clutter_threads_dispatch_free (gpointer data) * { * SafeClosure *closure = g_new0 (SafeClosure, 1); * - * closure->callback = callback; - * closure->data = data; + * closure->callback = callback; + * closure->data = data; * * return g_idle_add_full (G_PRIORITY_DEFAULT_IDLE, * idle_safe_callback, @@ -1151,24 +1107,24 @@ _clutter_threads_dispatch_free (gpointer data) * { * SomeClosure *closure = data; * - * /* it is safe to call Clutter API from this function because - * * it is invoked from the same thread that started the main - * * loop and under the Clutter thread lock - * */ - * clutter_label_set_text (CLUTTER_LABEL (closure->label), - * closure->text); + * // it is safe to call Clutter API from this function because + * / it is invoked from the same thread that started the main + * / loop and under the Clutter thread lock + * // + * clutter_label_set_text (CLUTTER_LABEL (closure->label), + * closure->text); * - * g_object_unref (closure->label); + * g_object_unref (closure->label); * g_free (closure); * * return FALSE; * } * - * /* within another thread */ + * // within another thread // * closure = g_new0 (SomeClosure, 1); - * /* always take a reference on GObject instances */ - * closure->label = g_object_ref (my_application->label); - * closure->text = g_strdup (processed_text_to_update_the_label); + * // always take a reference on GObject instances // + * closure->label = g_object_ref (my_application->label); + * closure->text = g_strdup (processed_text_to_update_the_label); * * clutter_threads_add_idle_full (G_PRIORITY_HIGH_IDLE, * update_ui, @@ -1809,13 +1765,13 @@ post_parse_hook (GOptionContext *context, * * |[ * g_option_context_set_main_group (context, clutter_get_option_group ()); - * res = g_option_context_parse (context, &argc, &argc, NULL); + * res = g_option_context_parse (context, &argc, &argc, NULL); * ]| * * is functionally equivalent to: * * |[ - * clutter_init (&argc, &argv); + * clutter_init (&argc, &argv); * ]| * * After g_option_context_parse() on a #GOptionContext containing the @@ -1865,7 +1821,7 @@ clutter_get_option_group (void) * the #GOptionGroup returned by this function requires a subsequent explicit * call to clutter_init(); use this function when needing to set foreign * display connection with clutter_x11_set_display(), or with - * gtk_clutter_init(). + * `gtk_clutter_init()`. * * Return value: (transfer full): a #GOptionGroup for the commandline arguments * recognized by Clutter @@ -2050,12 +2006,12 @@ clutter_parse_args (int *argc, * * It is safe to call this function multiple times. * - * This function will not abort in case of errors during + * This function will not abort in case of errors during * initialization; clutter_init() will print out the error message on * stderr, and will return an error code. It is up to the application * code to handle this case. If you need to display the error message * yourself, you can use clutter_init_with_args(), which takes a #GError - * pointer. + * pointer. * * If this function fails, and returns an error code, any subsequent * Clutter API will have undefined behaviour - including segmentation @@ -2919,10 +2875,10 @@ on_grab_actor_destroy (ClutterActor *actor, * the event delivery chain. The source set in the event will be the actor * that would have received the event if the pointer grab was not in effect. * - * Grabs completely override the entire event delivery chain + * Grabs completely override the entire event delivery chain * done by Clutter. Pointer grabs should only be used as a last resource; * using the #ClutterActor::captured-event signal should always be the - * preferred way to intercept event delivery to reactive actors. + * preferred way to intercept event delivery to reactive actors. * * This function should rarely be used. * @@ -3878,20 +3834,20 @@ _clutter_context_get_motion_events_enabled (void) * windowing system; for instance: * * |[ - * #ifdef CLUTTER_WINDOWING_X11 + * #ifdef CLUTTER_WINDOWING_X11 * if (clutter_check_windowing_backend (CLUTTER_WINDOWING_X11)) * { - * /* it is safe to use the clutter_x11_* API */ + * // it is safe to use the clutter_x11_* API * } * else - * #endif - * #ifdef CLUTTER_WINDOWING_WIN32 + * #endif + * #ifdef CLUTTER_WINDOWING_WIN32 * if (clutter_check_windowing_backend (CLUTTER_WINDOWING_WIN32)) * { - * /* it is safe to use the clutter_win32_* API */ + * // it is safe to use the clutter_win32_* API * } * else - * #endif + * #endif * g_error ("Unknown Clutter backend."); * ]| * diff --git a/clutter/clutter-model.c b/clutter/clutter-model.c index f43c54515..28ed76874 100644 --- a/clutter/clutter-model.c +++ b/clutter/clutter-model.c @@ -37,8 +37,11 @@ * The #ClutterModel class is a list model which can accept most GObject * types as a column type. * - * Creating a simple clutter model: - * + * ## Creating a simple ClutterModel + * + * The example below shows how to create a simple list model. + * + * |[ * enum * { * COLUMN_INT, @@ -51,10 +54,10 @@ * ClutterModel *model; * gint i; * - * model = clutter_model_default_new (N_COLUMNS, - * /* column type, column title */ - * G_TYPE_INT, "my integers", - * G_TYPE_STRING, "my strings"); + * model = clutter_list_model_new (N_COLUMNS, + * // column type, title + * G_TYPE_INT, "my integers", + * G_TYPE_STRING, "my strings"); * for (i = 0; i < 10; i++) * { * gchar *string = g_strdup_printf ("String %d", i); @@ -67,7 +70,9 @@ * * * } - * + * ]| + * + * ## Iterating through a ClutterModel * * Iterating through the model consists of retrieving a new #ClutterModelIter * pointing to the starting row, and calling clutter_model_iter_next() or @@ -79,8 +84,7 @@ * after the last row. In an empty sequence, the first and last iterators are * the same. * - * Iterating a #ClutterModel: - * + * |[ * enum * { * COLUMN_INT, @@ -93,10 +97,10 @@ * ClutterModel *model; * ClutterModelIter *iter = NULL; * - * /* Fill the model */ + * // fill the model * model = populate_model (); * - * /* Get the first iter */ + * // get the iterator for the first row in the model * iter = clutter_model_get_first_iter (model); * while (!clutter_model_iter_is_last (iter)) * { @@ -105,32 +109,33 @@ * iter = clutter_model_iter_next (iter); * } * - * /* Make sure to unref the iter */ + * // Make sure to unref the iter * g_object_unref (iter); * } - * + * ]| * * #ClutterModel is an abstract class. Clutter provides a list model * implementation called #ClutterListModel which has been optimised * for insertion and look up in sorted lists. * - * - * ClutterModel custom properties for #ClutterScript - * #ClutterModel defines a custom property "columns" for #ClutterScript - * which allows defining the column names and types. It also defines a custom - * "rows" property which allows filling the #ClutterModel with some - * data. - * - * Example of the "columns" and "rows" custom properties - * The definition below will create a #ClutterListModel with three - * columns: the first one with name "Name" and containing strings; the - * second one with name "Score" and containing integers; the third one with - * name "Icon" and containing #ClutterTextures. The model is filled - * with three rows. A row can be defined either with an array that holds - * all columns of a row, or an object that holds "column-name" : - * "column-value" pairs. - * - * + * #ClutterModel is available since Clutter 0.6 + * + * ## ClutterModel custom properties for ClutterScript + * + * #ClutterModel defines a custom property "columns" for #ClutterScript + * which allows defining the column names and types. It also defines a custom + * "rows" property which allows filling the #ClutterModel with some + * data. + * + * The definition below will create a #ClutterListModel with three + * columns: the first one with name "Name" and containing strings; the + * second one with name "Score" and containing integers; the third one with + * name "Icon" and containing #ClutterTextures. The model is filled + * with three rows. A row can be defined either with an array that holds + * all columns of a row, or an object that holds "column-name" : + * "column-value" pairs. + * + * |[ * { * "type" : "ClutterListModel", * "id" : "teams-model", @@ -145,11 +150,6 @@ * { "Name" : "Team 3", "Icon" : "team3-icon-script-id" } * ] * } - * - * - * - * - * #ClutterModel is available since Clutter 0.6 */ diff --git a/clutter/clutter-offscreen-effect.c b/clutter/clutter-offscreen-effect.c index de7191294..c30811339 100644 --- a/clutter/clutter-offscreen-effect.c +++ b/clutter/clutter-offscreen-effect.c @@ -40,25 +40,26 @@ * offscreen framebuffer, the redirection and the final paint of the texture on * the desired stage. * - * - * Implementing a ClutterOffscreenEffect - * Creating a sub-class of #ClutterOffscreenEffect requires, in case - * of overriding the #ClutterEffect virtual functions, to chain up to the - * #ClutterOffscreenEffect's implementation. - * On top of the #ClutterEffect's virtual functions, - * #ClutterOffscreenEffect also provides a #ClutterOffscreenEffectClass.paint_target() - * function, which encapsulates the effective painting of the texture that - * contains the result of the offscreen redirection. - * The size of the target material is defined to be as big as the - * transformed size of the #ClutterActor using the offscreen effect. - * Sub-classes of #ClutterOffscreenEffect can change the texture creation - * code to provide bigger textures by overriding the - * #ClutterOffscreenEffectClass.create_texture() virtual function; no chain up - * to the #ClutterOffscreenEffect implementation is required in this - * case. - * - * * #ClutterOffscreenEffect is available since Clutter 1.4 + * + * ## Implementing a ClutterOffscreenEffect + * + * Creating a sub-class of #ClutterOffscreenEffect requires, in case + * of overriding the #ClutterEffect virtual functions, to chain up to the + * #ClutterOffscreenEffect's implementation. + * + * On top of the #ClutterEffect's virtual functions, + * #ClutterOffscreenEffect also provides a #ClutterOffscreenEffectClass.paint_target() + * function, which encapsulates the effective painting of the texture that + * contains the result of the offscreen redirection. + * + * The size of the target material is defined to be as big as the + * transformed size of the #ClutterActor using the offscreen effect. + * Sub-classes of #ClutterOffscreenEffect can change the texture creation + * code to provide bigger textures by overriding the + * #ClutterOffscreenEffectClass.create_texture() virtual function; no chain up + * to the #ClutterOffscreenEffect implementation is required in this + * case. */ #ifdef HAVE_CONFIG_H @@ -596,7 +597,7 @@ clutter_offscreen_effect_create_texture (ClutterOffscreenEffect *effect, * paint the actor to which it has been applied. * * This function should only be called by #ClutterOffscreenEffect - * implementations, from within the paint_target() + * implementations, from within the #ClutterOffscreenEffectClass.paint_target() * virtual function. * * Return value: %TRUE if the offscreen buffer has a valid size, @@ -638,7 +639,7 @@ clutter_offscreen_effect_get_target_size (ClutterOffscreenEffect *effect, * paint the actor to which it has been applied. * * This function should only be called by #ClutterOffscreenEffect - * implementations, from within the paint_target() + * implementations, from within the #ClutterOffscreenEffectClass.paint_target() * virtual function. * * Return value: %TRUE if the offscreen buffer has a valid rectangle, diff --git a/clutter/clutter-paint-volume.c b/clutter/clutter-paint-volume.c index 9eeee1e9b..184e18663 100644 --- a/clutter/clutter-paint-volume.c +++ b/clutter/clutter-paint-volume.c @@ -290,20 +290,21 @@ clutter_paint_volume_set_width (ClutterPaintVolume *pv, * around the volume. It returns the size of that bounding box as * measured along the x-axis. * - * If, for example, clutter_actor_get_transformed_paint_volume() + * If, for example, clutter_actor_get_transformed_paint_volume() * is used to transform a 2D child actor that is 100px wide, 100px * high and 0px deep into container coordinates then the width might * not simply be 100px if the child actor has a 3D rotation applied to - * it. - * Remember; after clutter_actor_get_transformed_paint_volume() is + * it. + * + * Remember: if clutter_actor_get_transformed_paint_volume() is * used then a transformed child volume will be defined relative to the - * ancestor container actor and so a 2D child actor - * can have a 3D bounding volume. + * ancestor container actor and so a 2D child actor can have a 3D + * bounding volume. * - * There are no accuracy guarantees for the reported width, - * except that it must always be >= to the true width. This is - * because actors may report simple, loose fitting paint-volumes - * for efficiency + * There are no accuracy guarantees for the reported width, + * except that it must always be greater than, or equal to, the + * actor's width. This is because actors may report simple, loose + * fitting paint volumes for efficiency. * Return value: the width, in units of @pv's local coordinate system. * @@ -381,20 +382,21 @@ clutter_paint_volume_set_height (ClutterPaintVolume *pv, * around the volume. It returns the size of that bounding box as * measured along the y-axis. * - * If, for example, clutter_actor_get_transformed_paint_volume() + * If, for example, clutter_actor_get_transformed_paint_volume() * is used to transform a 2D child actor that is 100px wide, 100px * high and 0px deep into container coordinates then the height might * not simply be 100px if the child actor has a 3D rotation applied to - * it. - * Remember; after clutter_actor_get_transformed_paint_volume() is + * it. + * + * Remember: if clutter_actor_get_transformed_paint_volume() is * used then a transformed child volume will be defined relative to the * ancestor container actor and so a 2D child actor - * can have a 3D bounding volume. + * can have a 3D bounding volume. * - * There are no accuracy guarantees for the reported height, - * except that it must always be >= to the true height. This is - * because actors may report simple, loose fitting paint-volumes - * for efficiency + * There are no accuracy guarantees for the reported height, + * except that it must always be greater than, or equal to, the actor's + * height. This is because actors may report simple, loose fitting paint + * volumes for efficiency. * * Return value: the height, in units of @pv's local coordinate system. * @@ -473,20 +475,21 @@ clutter_paint_volume_set_depth (ClutterPaintVolume *pv, * around the volume. It returns the size of that bounding box as * measured along the z-axis. * - * If, for example, clutter_actor_get_transformed_paint_volume() + * If, for example, clutter_actor_get_transformed_paint_volume() * is used to transform a 2D child actor that is 100px wide, 100px * high and 0px deep into container coordinates then the depth might * not simply be 0px if the child actor has a 3D rotation applied to - * it. - * Remember; after clutter_actor_get_transformed_paint_volume() is + * it. + * + * Remember: if clutter_actor_get_transformed_paint_volume() is * used then the transformed volume will be defined relative to the * container actor and in container coordinates a 2D child actor - * can have a 3D bounding volume. + * can have a 3D bounding volume. * - * There are no accuracy guarantees for the reported depth, - * except that it must always be >= to the true depth. This is - * because actors may report simple, loose fitting paint-volumes - * for efficiency. + * There are no accuracy guarantees for the reported depth, + * except that it must always be greater than, or equal to, the actor's + * depth. This is because actors may report simple, loose fitting paint + * volumes for efficiency. * * Return value: the depth, in units of @pv's local coordinate system. * @@ -521,8 +524,8 @@ clutter_paint_volume_get_depth (const ClutterPaintVolume *pv) * * Updates the geometry of @pv to encompass @pv and @another_pv. * - * There are no guarantees about how precisely the two volumes - * will be encompassed. + * There are no guarantees about how precisely the two volumes + * will be unioned. * * Since: 1.6 */ @@ -743,9 +746,10 @@ _clutter_paint_volume_complete (ClutterPaintVolume *pv) * the paint volume into window coordinates before getting * the 2D bounding box. * - * The coordinates of the returned box are not clamped to - * integer pixel values, if you need them to be clamped you can use - * clutter_actor_box_clamp_to_pixel() + * The coordinates of the returned box are not clamped to + * integer pixel values; if you need them to be rounded to the + * nearest integer pixel values, you can use the + * clutter_actor_box_clamp_to_pixel() function. * * Since: 1.6 */ diff --git a/clutter/clutter-path.c b/clutter/clutter-path.c index 23886fc88..0ff7a2182 100644 --- a/clutter/clutter-path.c +++ b/clutter/clutter-path.c @@ -33,32 +33,19 @@ * The path consists of a series of nodes. Each node is one of the * following four types: * - * - * %CLUTTER_PATH_MOVE_TO - * - * Changes the position of the path to the given pair of - * coordinates. This is usually used as the first node of a path to - * mark the start position. If it is used in the middle of a path then - * the path will be disjoint and the actor will appear to jump to the - * new position when animated. - * - * %CLUTTER_PATH_LINE_TO - * - * Creates a straight line from the previous point to the given point. - * - * %CLUTTER_PATH_CURVE_TO - * - * Creates a bezier curve. The end of the last node is used as the - * first control point and the three subsequent coordinates given in - * the node as used as the other three. - * - * %CLUTTER_PATH_CLOSE - * - * Creates a straight line from the last node to the last - * %CLUTTER_PATH_MOVE_TO node. This can be used to close a path so - * that it will appear as a loop when animated. - * - * + * - %CLUTTER_PATH_MOVE_TO, changes the position of the path to the + * given pair of coordinates. This is usually used as the first node + * of a path to mark the start position. If it is used in the middle + * of a path then the path will be disjoint and the actor will appear + * to jump to the new position when animated. + * - %CLUTTER_PATH_LINE_TO, creates a straight line from the previous + * point to the given point. + * - %CLUTTER_PATH_CURVE_TO, creates a bezier curve. The end of the + * last node is used as the first control point and the three + * subsequent coordinates given in the node as used as the other three. + * -%CLUTTER_PATH_CLOSE, creates a straight line from the last node to + * the last %CLUTTER_PATH_MOVE_TO node. This can be used to close a + * path so that it will appear as a loop when animated. * * The first three types have the corresponding relative versions * %CLUTTER_PATH_REL_MOVE_TO, %CLUTTER_PATH_REL_LINE_TO and @@ -711,24 +698,10 @@ clutter_path_add_nodes (ClutterPath *path, * coordinates. The coordinates can be separated by spaces or a * comma. The types are: * - * - * M - * - * Adds a %CLUTTER_PATH_MOVE_TO node. Takes one pair of coordinates. - * - * L - * - * Adds a %CLUTTER_PATH_LINE_TO node. Takes one pair of coordinates. - * - * C - * - * Adds a %CLUTTER_PATH_CURVE_TO node. Takes three pairs of coordinates. - * - * z - * - * Adds a %CLUTTER_PATH_CLOSE node. No coordinates are needed. - * - * + * - `M`: Adds a %CLUTTER_PATH_MOVE_TO node. Takes one pair of coordinates. + * - `L`: Adds a %CLUTTER_PATH_LINE_TO node. Takes one pair of coordinates. + * - `C`: Adds a %CLUTTER_PATH_CURVE_TO node. Takes three pairs of coordinates. + * - `z`: Adds a %CLUTTER_PATH_CLOSE node. No coordinates are needed. * * The M, L and C commands can also be specified in lower case which * means the coordinates are relative to the previous node. @@ -736,11 +709,9 @@ clutter_path_add_nodes (ClutterPath *path, * For example, to move an actor in a 100 by 100 pixel square centered * on the point 300,300 you could use the following path: * - * - * + * |[ * M 250,350 l 0 -100 L 350,250 l 0 100 z - * - * + * ]| * * If the path description isn't valid %FALSE will be returned and no * nodes will be added. diff --git a/clutter/clutter-script.c b/clutter/clutter-script.c index 4434b4d2a..8df91b2c7 100644 --- a/clutter/clutter-script.c +++ b/clutter/clutter-script.c @@ -756,15 +756,15 @@ clutter_script_get_objects_valist (ClutterScript *script, * names/return location pairs should be listed, with a %NULL pointer * ending the list, like: * - * + * |[ * GObject *my_label, *a_button, *main_timeline; * * clutter_script_get_objects (script, - * "my-label", &my_label, - * "a-button", &a_button, - * "main-timeline", &main_timeline, + * "my-label", &my_label, + * "a-button", &a_button, + * "main-timeline", &main_timeline, * NULL); - * + * ]| * * Note: This function does not increment the reference count of the * returned objects. diff --git a/clutter/clutter-scroll-actor.c b/clutter/clutter-scroll-actor.c index e1acc1e6e..49f73279b 100644 --- a/clutter/clutter-scroll-actor.c +++ b/clutter/clutter-scroll-actor.c @@ -36,13 +36,8 @@ * #ClutterScrollActor does not provide pointer or keyboard event handling, * nor does it provide visible scroll handles. * - * - * - * - * FIXME: MISSING XINCLUDE CONTENT - * - * - * + * See [scroll-actor.c](https://git.gnome.org/browse/clutter/tree/examples/scroll-actor.c?h=clutter-1.18) + * for an example of how to use #ClutterScrollActor. * * #ClutterScrollActor is available since Clutter 1.12. */ diff --git a/clutter/clutter-settings.c b/clutter/clutter-settings.c index f0e3ef0e1..7b0032978 100644 --- a/clutter/clutter-settings.c +++ b/clutter/clutter-settings.c @@ -600,12 +600,11 @@ clutter_settings_class_init (ClutterSettingsClass *klass) * * The style of the hinting used when rendering text. Valid values * are: - * - * hintnone - * hintslight - * hintmedium - * hintfull - * + * + * - hintnone + * - hintslight + * - hintmedium + * - hintfull * * Since: 1.4 */ @@ -621,13 +620,12 @@ clutter_settings_class_init (ClutterSettingsClass *klass) * * The type of sub-pixel antialiasing used when rendering text. Valid * values are: - * - * none - * rgb - * bgr - * vrgb - * vbgr - * + * + * - none + * - rgb + * - bgr + * - vrgb + * - vbgr * * Since: 1.4 */ diff --git a/clutter/clutter-shader-effect.c b/clutter/clutter-shader-effect.c index 95b7d6a7e..a5169782f 100644 --- a/clutter/clutter-shader-effect.c +++ b/clutter/clutter-shader-effect.c @@ -34,35 +34,43 @@ * GLSL shader (after checking whether the compilation and linking were * successfull) to the buffer before painting it on screen. * - * - * Implementing a ClutterShaderEffect - * Creating a sub-class of #ClutterShaderEffect requires the - * overriding of the #ClutterOffscreenEffectClass.paint_target() virtual - * function from the #ClutterOffscreenEffect class as well as the - * get_static_shader_source() virtual from the - * #ClutterShaderEffect class. - * The #ClutterShaderEffectClass.get_static_shader_source() - * function should return a copy of the shader source to use. This - * function is only called once per subclass of #ClutterShaderEffect - * regardless of how many instances of the effect are created. The - * source for the shader is typically stored in a static const - * string which is returned from this function via - * g_strdup(). - * The paint_target() should set the - * shader's uniforms if any. This is done by calling - * clutter_shader_effect_set_uniform_value() or - * clutter_shader_effect_set_uniform(). The sub-class should then - * chain up to the #ClutterShaderEffect implementation. - * - * Setting uniforms on a ClutterShaderEffect - * The example below shows a typical implementation of the - * get_static_shader_source() and - * paint_target() phases of a - * #ClutterShaderEffect sub-class. - * + * #ClutterShaderEffect is available since Clutter 1.4 + * + * ## Implementing a ClutterShaderEffect + * + * Creating a sub-class of #ClutterShaderEffect requires the + * overriding of the #ClutterOffscreenEffectClass.paint_target() virtual + * function from the #ClutterOffscreenEffect class. It is also convenient + * to implement the #ClutterShaderEffectClass.get_static_shader_source() + * virtual function in case you are planning to create more than one + * instance of the effect. + * + * The #ClutterShaderEffectClass.get_static_shader_source() + * function should return a copy of the shader source to use. This + * function is only called once per subclass of #ClutterShaderEffect + * regardless of how many instances of the effect are created. The + * source for the shader is typically stored in a static const + * string which is returned from this function via + * g_strdup(). + * + * The #ClutterOffscreenEffectClass.paint_target() should set the + * shader's uniforms if any. This is done by calling + * clutter_shader_effect_set_uniform_value() or + * clutter_shader_effect_set_uniform(). The sub-class should then + * chain up to the #ClutterShaderEffect implementation. + * + * ## Setting uniforms on a ClutterShaderEffect + * + * The example below shows a typical implementation of the + * #ClutterShaderEffectClass.get_static_shader_source() and + * #ClutterOffscreenEffectClass.paint_target() virtual functions + * for a #ClutterShaderEffect subclass. + * + * |[ * static gchar * * my_effect_get_static_shader_source (ClutterShaderEffect *effect) * { + * // shader_source is set elsewhere * return g_strdup (shader_source); * } * @@ -74,21 +82,19 @@ * ClutterEffectClass *parent_class; * gfloat component_r, component_g, component_b; * - * /* the "tex" uniform is declared in the shader as: - * * - * * uniform int tex; - * * - * * and it is passed a constant value of 0 - * */ + * // the "tex" uniform is declared in the shader as: + * // + * // uniform int tex; + * // + * // and it is passed a constant value of 0 * clutter_shader_effect_set_uniform (shader, "tex", G_TYPE_INT, 1, 0); * - * /* the "component" uniform is declared in the shader as: - * * - * * uniform vec3 component; - * * - * * and it's defined to contain the normalized components - * * of a #ClutterColor - * */ + * // the "component" uniform is declared in the shader as: + * // + * // uniform vec3 component; + * // + * // and it's defined to contain the normalized components + * // of a #ClutterColor * component_r = self->color.red / 255.0f; * component_g = self->color.green / 255.0f; * component_b = self->color.blue / 255.0f; @@ -98,15 +104,11 @@ * component_g, * component_b); * - * /* chain up to the parent's implementation */ + * // chain up to the parent's implementation * parent_class = CLUTTER_OFFSCREEN_EFFECT_CLASS (my_effect_parent_class); * return parent_class->paint_target (effect); * } - * - * - * - * - * #ClutterShaderEffect is available since Clutter 1.4 + * ]| */ #ifdef HAVE_CONFIG_H @@ -805,7 +807,7 @@ add_uniform: * argument, and by the @gtype argument. For instance, a uniform named * "sampler0" and containing a single integer value is set using: * - * |[ + * |[ * clutter_shader_effect_set_uniform (effect, "sampler0", * G_TYPE_INT, 1, * 0); @@ -814,7 +816,7 @@ add_uniform: * While a uniform named "components" and containing a 3-elements vector * of floating point values (a "vec3") can be set using: * - * |[ + * |[ * gfloat component_r, component_g, component_b; * * clutter_shader_effect_set_uniform (effect, "components", @@ -826,7 +828,7 @@ add_uniform: * * or can be set using: * - * |[ + * |[ * gfloat component_vec[3]; * * clutter_shader_effect_set_uniform (effect, "components", @@ -836,7 +838,7 @@ add_uniform: * * Finally, a uniform named "map" and containing a matrix can be set using: * - * |[ + * |[ * clutter_shader_effect_set_uniform (effect, "map", * CLUTTER_TYPE_SHADER_MATRIX, 1, * cogl_matrix_get_array (&matrix)); diff --git a/clutter/clutter-stage.c b/clutter/clutter-stage.c index d9a1c6766..24f675954 100644 --- a/clutter/clutter-stage.c +++ b/clutter/clutter-stage.c @@ -2179,9 +2179,9 @@ clutter_stage_class_init (ClutterStageClass *klass) * It is possible to override the default behaviour by connecting * a new handler and returning %TRUE there. * - * This signal is emitted only on Clutter backends that + * This signal is emitted only on Clutter backends that * embed #ClutterStage in native windows. It is not emitted for - * backends that use a static frame buffer. + * backends that use a static frame buffer. * * Since: 1.2 */ @@ -3194,29 +3194,29 @@ clutter_stage_set_use_fog (ClutterStage *stage, * ClutterColor stage_color = { 0, }; * CoglColor fog_color = { 0, }; * - * /* set the fog color to the stage background color */ - * clutter_stage_get_color (CLUTTER_STAGE (actor), &stage_color); - * cogl_color_init_from_4ub (&fog_color, + * // set the fog color to the stage background color + * clutter_stage_get_color (CLUTTER_STAGE (actor), &stage_color); + * cogl_color_init_from_4ub (&fog_color, * stage_color.red, * stage_color.green, * stage_color.blue, * stage_color.alpha); * - * /* enable fog */ - * cogl_set_fog (&fog_color, - * COGL_FOG_MODE_EXPONENTIAL, /* mode */ - * 0.5, /* density */ - * 5.0, 30.0); /* z_near and z_far */ + * // enable fog // + * cogl_set_fog (&fog_color, + * COGL_FOG_MODE_EXPONENTIAL, // mode + * 0.5, // density + * 5.0, 30.0); // z_near and z_far * } * ]| * - * The fogging functions only work correctly when the visible actors use + * The fogging functions only work correctly when the visible actors use * unmultiplied alpha colors. By default Cogl will premultiply textures and * cogl_set_source_color() will premultiply colors, so unless you explicitly * load your textures requesting an unmultiplied internal format and use * cogl_material_set_color() you can only use fogging with fully opaque actors. * Support for premultiplied colors will improve in the future when we can - * depend on fragment shaders. + * depend on fragment shaders. * * Since: 0.6 * @@ -3616,8 +3616,8 @@ clutter_stage_ensure_redraw (ClutterStage *stage) * * Queues a redraw for the passed stage. * - * Applications should call clutter_actor_queue_redraw() and not - * this function. + * Applications should call clutter_actor_queue_redraw() and not + * this function. * * Since: 0.8 * @@ -3925,12 +3925,12 @@ _clutter_stage_clear_update_time (ClutterStage *stage) * if the stage is always covered - for instance, in a full-screen * video player or in a game with a background texture. * - * This setting is a hint; Clutter might discard this - * hint depending on its internal state. + * This setting is a hint; Clutter might discard this hint + * depending on its internal state. * - * If parts of the stage are visible and you disable - * clearing you might end up with visual artifacts while painting the - * contents of the stage. + * If parts of the stage are visible and you disable clearing you + * might end up with visual artifacts while painting the contents of + * the stage. * * Since: 1.4 */ @@ -4232,14 +4232,12 @@ clutter_stage_get_accept_focus (ClutterStage *stage) * * The default is %TRUE. * - * If @enable is %FALSE the following events will not be delivered - * to the actors children of @stage. + * If @enable is %FALSE the following signals will not be emitted + * by the actors children of @stage: * - * - * #ClutterActor::motion-event - * #ClutterActor::enter-event - * #ClutterActor::leave-event - * + * - #ClutterActor::motion-event + * - #ClutterActor::enter-event + * - #ClutterActor::leave-event * * The events will still be delivered to the #ClutterStage. * diff --git a/clutter/clutter-test-utils.c b/clutter/clutter-test-utils.c index bf38be534..415e222e7 100644 --- a/clutter/clutter-test-utils.c +++ b/clutter/clutter-test-utils.c @@ -226,7 +226,7 @@ clutter_test_add_data_full (const char *test_path, * int * main (int argc, char *argv[]) * { - * clutter_test_init (&argc, &argv); + * clutter_test_init (&argc, &argv); * * clutter_test_add ("/unit/foo", unit_foo); * clutter_test_add ("/unit/bar", unit_bar); diff --git a/clutter/clutter-test-utils.h b/clutter/clutter-test-utils.h index d88727deb..81dad9737 100644 --- a/clutter/clutter-test-utils.h +++ b/clutter/clutter-test-utils.h @@ -64,7 +64,7 @@ G_BEGIN_DECLS * main (int argc, * char *argv[]) * { - * clutter_test_init (&argc, &argv); + * clutter_test_init (&argc, &argv); * * clutter_test_add ("/foobarize", foobarize); * clutter_test_add ("/bar-enabled", bar_enabled); diff --git a/clutter/clutter-text.c b/clutter/clutter-text.c index 2ce831916..bb4b3643d 100644 --- a/clutter/clutter-text.c +++ b/clutter/clutter-text.c @@ -3709,10 +3709,10 @@ clutter_text_class_init (ClutterTextClass *klass) * For more informations about the Pango markup format, see * pango_layout_set_markup() in the Pango documentation. * - * It is not possible to round-trip this property between + * It is not possible to round-trip this property between * %TRUE and %FALSE. Once a string with markup has been set on * a #ClutterText actor with :use-markup set to %TRUE, the markup - * is stripped from the string. + * is stripped from the string. * * Since: 1.0 */ diff --git a/clutter/clutter-timeline.c b/clutter/clutter-timeline.c index b830b3755..f64fd930f 100644 --- a/clutter/clutter-timeline.c +++ b/clutter/clutter-timeline.c @@ -19,8 +19,6 @@ * * You should have received a copy of the GNU Lesser General Public * License along with this library. If not, see . - * - * */ /** @@ -57,8 +55,8 @@ * its #ClutterTimeline:duration. * * It is possible to connect to specific points in the timeline progress by - * adding markers using clutter_timeline_add_marker_at_time() - * and connecting to the #ClutterTimeline::marker-reached signal. + * adding markers using clutter_timeline_add_marker_at_time() and connecting + * to the #ClutterTimeline::marker-reached signal. * * Timelines can be made to loop once they reach the end of their duration, by * using clutter_timeline_set_repeat_count(); a looping timeline will still @@ -75,13 +73,14 @@ * Timelines are used in the Clutter animation framework by classes like * #ClutterAnimation, #ClutterAnimator, and #ClutterState. * - * - * Defining Timelines in ClutterScript - * A #ClutterTimeline can be described in #ClutterScript like any - * other object. Additionally, it is possible to define markers directly - * inside the JSON definition by using the markers - * JSON object member, such as: - * - * + * ]| */ #ifdef HAVE_CONFIG_H @@ -1366,10 +1364,9 @@ clutter_timeline_skip (ClutterTimeline *timeline, * Advance timeline to the requested point. The point is given as a * time in milliseconds since the timeline started. * - * The @timeline will not emit the #ClutterTimeline::new-frame + * The @timeline will not emit the #ClutterTimeline::new-frame * signal for the given time. The first ::new-frame signal after the call to * clutter_timeline_advance() will be emit the skipped markers. - * */ void clutter_timeline_advance (ClutterTimeline *timeline, @@ -1423,15 +1420,15 @@ clutter_timeline_is_playing (ClutterTimeline *timeline) * Create a new #ClutterTimeline instance which has property values * matching that of supplied timeline. The cloned timeline will not * be started and will not be positioned to the current position of - * the original @timeline: you will have to start it with clutter_timeline_start(). + * the original @timeline: you will have to start it with + * clutter_timeline_start(). * - * The only cloned properties are: - * - * #ClutterTimeline:duration - * #ClutterTimeline:loop - * #ClutterTimeline:delay - * #ClutterTimeline:direction - * + * The only cloned properties are: + * + * - #ClutterTimeline:duration + * - #ClutterTimeline:loop + * - #ClutterTimeline:delay + * - #ClutterTimeline:direction * * Return value: (transfer full): a new #ClutterTimeline, cloned * from @timeline @@ -1934,10 +1931,10 @@ clutter_timeline_list_markers (ClutterTimeline *timeline, * * Advances @timeline to the time of the given @marker_name. * - * Like clutter_timeline_advance(), this function will not + * Like clutter_timeline_advance(), this function will not * emit the #ClutterTimeline::new-frame for the time where @marker_name * is set, nor it will emit #ClutterTimeline::marker-reached for - * @marker_name. + * @marker_name. * * Since: 0.8 */ diff --git a/clutter/clutter-types.h b/clutter/clutter-types.h index ad97a639a..10ef8dd7e 100644 --- a/clutter/clutter-types.h +++ b/clutter/clutter-types.h @@ -564,9 +564,9 @@ void clutter_actor_box_set_size (ClutterActorBox *box, * * The rectangle containing an actor's bounding box, measured in pixels. * - * You should not use #ClutterGeometry, or operate on its fields + * You should not use #ClutterGeometry, or operate on its fields * directly; you should use #cairo_rectangle_int_t or #ClutterRect if you - * need a rectangle type, depending on the precision required. + * need a rectangle type, depending on the precision required. * * Deprecated: 1.16 */ diff --git a/clutter/clutter-units.c b/clutter/clutter-units.c index f07f0f619..f49df9b99 100644 --- a/clutter/clutter-units.c +++ b/clutter/clutter-units.c @@ -466,7 +466,7 @@ clutter_units_to_pixels (ClutterUnits *units) * omg!1!ponies * ]| * - * If no unit is specified, pixels are assumed. + * If no unit is specified, pixels are assumed. * * Return value: %TRUE if the string was successfully parsed, * and %FALSE otherwise @@ -595,9 +595,9 @@ clutter_unit_type_name (ClutterUnitType unit_type) * See clutter_units_from_string() for the units syntax and for * examples of output * - * Fractional values are truncated to the second decimal + * Fractional values are truncated to the second decimal * position for em, mm and cm, and to the first decimal position for - * typographic points. Pixels are integers. + * typographic points. Pixels are integers. * * Return value: a newly allocated string containing the encoded * #ClutterUnits value. Use g_free() to free the string