From 0b76ba332d270e327d8094c25d1b2197e5b89ac6 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Thu, 19 Apr 2012 16:00:23 +0100 Subject: [PATCH] Fixes for the API reference Typos, missing symbols, and missing documentation. --- clutter/clutter-animatable.c | 14 +++--- clutter/clutter-cairo.c | 29 +++++++++++++ clutter/clutter-constraint.c | 2 +- clutter/clutter-deform-effect.c | 2 +- clutter/clutter-effect.c | 15 ++++--- clutter/clutter-enums.h | 2 +- clutter/clutter-gesture-action.c | 2 +- clutter/clutter-gesture-action.h | 2 +- clutter/clutter-layout-manager.c | 41 ++++++++--------- clutter/clutter-offscreen-effect.c | 4 +- clutter/clutter-paint-node.h | 9 ++++ clutter/clutter-shader-effect.c | 4 +- clutter/clutter-types.h | 70 +++++++++++++++++++++++++++++- clutter/clutter-units.c | 4 +- clutter/wayland/clutter-wayland-surface.c | 31 ++++++++++++- doc/reference/clutter/clutter-sections.txt | 27 +++++++++--- 16 files changed, 204 insertions(+), 54 deletions(-) diff --git a/clutter/clutter-animatable.c b/clutter/clutter-animatable.c index 359995e..2291db9 100644 --- a/clutter/clutter-animatable.c +++ b/clutter/clutter-animatable.c @@ -30,16 +30,16 @@ * to control how a #ClutterAnimation will animate a property. * * Each #ClutterAnimatable should implement the - * animate_property virtual function of the interface - * to compute the animation state between two values of an interval depending - * on a progress factor, expressed as a floating point value. + * #ClutterAnimatableIface.interpolate_property() virtual function of the + * interface to compute the animation state between two values of an interval + * depending on a progress factor, expressed as a floating point value. * * If a #ClutterAnimatable is animated by a #ClutterAnimation * instance, the #ClutterAnimation will call - * clutter_animatable_animate_property() passing the name of the - * currently animated property; the initial and final values of - * the animation interval; the progress factor. The #ClutterAnimatable - * implementation should return the computed value for the animated + * clutter_animatable_interpolate_property() passing the name of the + * currently animated property; the values interval; and the progress factor. + * The #ClutterAnimatable implementation should return the computed value for + * the animated * property. * * #ClutterAnimatable is available since Clutter 1.0 diff --git a/clutter/clutter-cairo.c b/clutter/clutter-cairo.c index 985999b..fac7c18 100644 --- a/clutter/clutter-cairo.c +++ b/clutter/clutter-cairo.c @@ -1,3 +1,32 @@ +/* + * Clutter. + * + * An OpenGL based 'interactive canvas' library. + * + * Copyright (C) 2012 Intel Corporation + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library. If not, see . + */ + +/** + * SECTION:clutter-cairo + * @Title: Cairo integration + * @Short_Description: Functions for interoperating with Cairo + * + * Clutter provides some utility functions for using Cairo. + */ + #ifdef HAVE_CONFIG_H #include "config.h" #endif diff --git a/clutter/clutter-constraint.c b/clutter/clutter-constraint.c index b68794d..61f6fc6 100644 --- a/clutter/clutter-constraint.c +++ b/clutter/clutter-constraint.c @@ -11,7 +11,7 @@ * the position or size of the #ClutterActor to which it is applied, by * updating the actor's allocation. Each #ClutterConstraint can change the * allocation of the actor to which they are applied by overriding the - * update_allocation() virtual function. + * #ClutterConstraintClass.update_allocation() virtual function. * * * Using Constraints diff --git a/clutter/clutter-deform-effect.c b/clutter/clutter-deform-effect.c index cc5e256..5c302b9 100644 --- a/clutter/clutter-deform-effect.c +++ b/clutter/clutter-deform-effect.c @@ -42,7 +42,7 @@ * * Implementing ClutterDeformEffect * Sub-classes of #ClutterDeformEffect should override the - * deform_vertex() virtual function; this function + * #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 diff --git a/clutter/clutter-effect.c b/clutter/clutter-effect.c index d83b181..8430a76 100644 --- a/clutter/clutter-effect.c +++ b/clutter/clutter-effect.c @@ -34,7 +34,7 @@ * * Effects should be the preferred way to affect the paint sequence of an * actor without sub-classing the actor itself and overriding the - * #ClutterActor::paint virtual function. + * #ClutterActorClass.paint()_ virtual function. * * * Implementing a ClutterEffect @@ -91,18 +91,19 @@ * * With these two functions it is not possible to skip the rest of * the paint sequence. The default implementation of the ‘paint’ - * virtual calls pre_paint(), clutter_actor_continue_paint() and - * then post_paint() so that existing actors that aren't using the - * paint virtual will continue to work. New actors using the paint - * virtual do not need to implement pre or post 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 set_actor() + * top" of the actor. The #ClutterActorMetaClass.set_actor() * implementation will create the two materials used for the two - * different rectangles; the paint() function + * 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. diff --git a/clutter/clutter-enums.h b/clutter/clutter-enums.h index b020a7c..845e700 100644 --- a/clutter/clutter-enums.h +++ b/clutter/clutter-enums.h @@ -541,7 +541,7 @@ typedef enum { * @CLUTTER_LONG_PRESS_ACTIVATE: Activates the action on a long press * @CLUTTER_LONG_PRESS_CANCEL: The long press was cancelled * - * The states for the #ClutterClikAction::long-press signal. + * The states for the #ClutterClickAction::long-press signal. * * Since: 1.8 */ diff --git a/clutter/clutter-gesture-action.c b/clutter/clutter-gesture-action.c index 15da745..e7b0892 100644 --- a/clutter/clutter-gesture-action.c +++ b/clutter/clutter-gesture-action.c @@ -32,7 +32,7 @@ * the logic for recognizing gesture gestures. It listens for low level events * such as #ClutterButtonEvent and #ClutterMotionEvent on the stage to raise * the #ClutterGestureAction::gesture-begin, #ClutterGestureAction::gesture-progress, - * and * #ClutterGestureAction::gesture-end signals. + * and #ClutterGestureAction::gesture-end signals. * * To use #ClutterGestureAction you just need to apply it to a #ClutterActor * using clutter_actor_add_action() and connect to the signals: diff --git a/clutter/clutter-gesture-action.h b/clutter/clutter-gesture-action.h index 02af94b..f7a9c04 100644 --- a/clutter/clutter-gesture-action.h +++ b/clutter/clutter-gesture-action.h @@ -64,7 +64,7 @@ struct _ClutterGestureAction /** * ClutterGestureActionClass: * @gesture_begin: class handler for the #ClutterGestureAction::gesture-begin signal - * @gesture_progress: class handler for the #ClutterGestureAction::gesture-progres signal + * @gesture_progress: class handler for the #ClutterGestureAction::gesture-progress signal * @gesture_end: class handler for the #ClutterGestureAction::gesture-end signal * @gesture_cancel: class handler for the #ClutterGestureAction::gesture-cancel signal * diff --git a/clutter/clutter-layout-manager.c b/clutter/clutter-layout-manager.c index 8f244ca..e51b3da 100644 --- a/clutter/clutter-layout-manager.c +++ b/clutter/clutter-layout-manager.c @@ -42,13 +42,11 @@ * 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 ClutterActor::get_preferred_width() - * virtual function and clutter_layout_manager_get_preferred_height() - * inside the ClutterActor::get_preferred_height() - * virtual function implementations. You should also call - * clutter_layout_manager_allocate() inside the implementation of the - * ClutterActor::allocate() virtual - * function. + * 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 @@ -93,9 +91,9 @@ * 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: begin_animation(), - * get_animation_progress() and - * end_animation(). + * functions: #ClutterLayoutManagerClass.begin_animation(), + * #ClutterLayoutManagerClass.get_animation_progress(), and + * #ClutterLayoutManagerClass.end_animation(). * * * begin_animation (duration, easing) @@ -131,20 +129,20 @@ * 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 begin_animation() - * and end_animation() to set up ad hoc state, and then + * 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 - * allocate() virtual function implementation. 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 - * begin_animation() and - * end_animation() virtual functions and chaining up + * #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. @@ -254,13 +252,12 @@ * 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 - * ClutterLayoutManager::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 - * ClutterLayoutManager::create_child_meta() virtual - * function to control how the #ClutterLayoutMeta instance is created, - * otherwise the default implementation will be equivalent to: + * #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; diff --git a/clutter/clutter-offscreen-effect.c b/clutter/clutter-offscreen-effect.c index 09443dc..d58227f 100644 --- a/clutter/clutter-offscreen-effect.c +++ b/clutter/clutter-offscreen-effect.c @@ -46,14 +46,14 @@ * 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 paint_target() + * #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 - * create_texture() virtual function; no chain up + * #ClutterOffscreenEffectClass.create_texture() virtual function; no chain up * to the #ClutterOffscreenEffect implementation is required in this * case. * diff --git a/clutter/clutter-paint-node.h b/clutter/clutter-paint-node.h index 29674bf..9d3ffb6 100644 --- a/clutter/clutter-paint-node.h +++ b/clutter/clutter-paint-node.h @@ -75,6 +75,15 @@ void clutter_paint_node_add_primitive (Clutter CoglPrimitive *primitive); #endif /* COGL_ENABLE_EXPERIMENTAL_2_0_API && CLUTTER_ENABLE_EXPERIMENTAL_API */ +/** + * CLUTTER_VALUE_HOLDS_PAINT_NODE: + * @value: a #GValue + * + * Evaluates to %TRUE if the @value has been initialized to hold + * a #ClutterPaintNode. + * + * Since: 1.10 + */ #define CLUTTER_VALUE_HOLDS_PAINT_NODE(value) (G_VALUE_HOLDS (value, CLUTTER_TYPE_PAINT_NODE)) CLUTTER_AVAILABLE_IN_1_10 diff --git a/clutter/clutter-shader-effect.c b/clutter/clutter-shader-effect.c index 0655887..fbc10ca 100644 --- a/clutter/clutter-shader-effect.c +++ b/clutter/clutter-shader-effect.c @@ -37,11 +37,11 @@ * * Implementing a ClutterShaderEffect * Creating a sub-class of #ClutterShaderEffect requires the - * overriding of the paint_target() virtual + * 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 get_static_shader_source() + * 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 diff --git a/clutter/clutter-types.h b/clutter/clutter-types.h index 08c8288..fe65671 100644 --- a/clutter/clutter-types.h +++ b/clutter/clutter-types.h @@ -132,7 +132,29 @@ struct _ClutterPoint float y; }; +/** + * CLUTTER_POINT_INIT: + * @x: X coordinate + * @y: Y coordinate + * + * A simple macro for initializing a #ClutterPoint when declaring it, e.g.: + * + * |[ + * ClutterPoint p = CLUTTER_POINT_INIT (100, 100); + * ]| + * + * Since: 1.12 + */ #define CLUTTER_POINT_INIT(x,y) { (x), (y) } + +/** + * CLUTTER_POINT_INIT_ZERO: + * + * A simple macro for initializing a #ClutterPoint to (0, 0) when + * declaring it. + * + * Since: 1.12 + */ #define CLUTTER_POINT_INIT_ZERO CLUTTER_POINT_INIT (0.f, 0.f) CLUTTER_AVAILABLE_IN_1_12 @@ -172,7 +194,29 @@ struct _ClutterSize float height; }; +/** + * CLUTTER_SIZE_INIT: + * @width: the width + * @height: the height + * + * A simple macro for initializing a #ClutterSize when declaring it, e.g.: + * + * |[ + * ClutterSize s = CLUTTER_SIZE_INIT (200, 200); + * ]| + * + * Since: 1.12 + */ #define CLUTTER_SIZE_INIT(width,height) { (width), (height) } + +/** + * CLUTTER_SIZE_INIT_ZERO: + * + * A simple macro for initializing a #ClutterSize to (0, 0) when + * declaring it. + * + * Since: 1.12 + */ #define CLUTTER_SIZE_INIT_ZERO CLUTTER_SIZE_INIT (0.f, 0.f) CLUTTER_AVAILABLE_IN_1_12 @@ -219,7 +263,31 @@ struct _ClutterRect ClutterSize size; }; +/** + * CLUTTER_RECT_INIT: + * @x: the X coordinate + * @y: the Y coordinate + * @width: the width + * @height: the height + * + * A simple macro for initializing a #ClutterRect when declaring it, e.g.: + * + * |[ + * ClutterRect r = CLUTTER_RECT_INIT (100, 100, 200, 200); + * ]| + * + * Since: 1.12 + */ #define CLUTTER_RECT_INIT(x,y,width,height) { { (x), (y) }, { (width), (height) } } + +/** + * CLUTTER_RECT_INIT_ZERO: + * + * A simple macro for initializing a #ClutterRect to (0, 0, 0, 0) when + * declaring it. + * + * Since: 1.12 + */ #define CLUTTER_RECT_INIT_ZERO CLUTTER_RECT_INIT (0.f, 0.f, 0.f, 0.f) CLUTTER_AVAILABLE_IN_1_12 @@ -305,7 +373,7 @@ struct _ClutterVertex * A simple macro for initializing a #ClutterVertex when declaring it, e.g.: * * |[ - * ClutterVertext v = CLUTTER_VERTEX_INIT (x, y, z); + * ClutterVertex v = CLUTTER_VERTEX_INIT (x, y, z); * ]| * * Since: 1.10 diff --git a/clutter/clutter-units.c b/clutter/clutter-units.c index 808f830..f07f0f6 100644 --- a/clutter/clutter-units.c +++ b/clutter/clutter-units.c @@ -33,8 +33,8 @@ * its type, expressed as a value of the #ClutterUnitType enumeration. It is * possible to use #ClutterUnits to store a position or a size in units * different than pixels, and convert them whenever needed (for instance - * inside the #ClutterActor::allocate() virtual function, or inside the - * #ClutterActor::get_preferred_width() and #ClutterActor::get_preferred_height() + * inside the #ClutterActorClass.allocate() virtual function, or inside the + * #ClutterActorClass.get_preferred_width() and #ClutterActorClass.get_preferred_height() * virtual functions. * * In order to register a #ClutterUnits property, the #ClutterParamSpecUnits diff --git a/clutter/wayland/clutter-wayland-surface.c b/clutter/wayland/clutter-wayland-surface.c index b128782..becd917 100644 --- a/clutter/wayland/clutter-wayland-surface.c +++ b/clutter/wayland/clutter-wayland-surface.c @@ -217,6 +217,16 @@ set_size (ClutterWaylandSurface *self, clutter_actor_set_size (CLUTTER_ACTOR (self), priv->width, priv->height); } +/** + * clutter_wayland_surface_get_surface: + * @self: a #ClutterWaylandSurface + * + * Retrieves a point to the Wayland surface used by the actor. + * + * Return value: (transfer none): a wl_surface pointer, or %NULL + * + * Since: 1.10 + */ struct wl_surface * clutter_wayland_surface_get_surface (ClutterWaylandSurface *self) { @@ -224,6 +234,15 @@ clutter_wayland_surface_get_surface (ClutterWaylandSurface *self) return priv->surface; } +/** + * clutter_wayland_surface_set_surface: + * @self: a #ClutterWaylandSurface + * @surface: a Wayland wl_surface pointer + * + * Sets the Wayland surface to be used by the actor. + * + * Since: 1.10 + */ void clutter_wayland_surface_set_surface (ClutterWaylandSurface *self, struct wl_surface *surface) @@ -435,7 +454,7 @@ clutter_wayland_surface_class_init (ClutterWaylandSurfaceClass *klass) g_object_class_install_property (object_class, PROP_COGL_TEXTURE, pspec); /** - * ClutterWaylandSurface::queue-damage-redraw + * ClutterWaylandSurface::queue-damage-redraw: * @texture: the object which received the signal * @x: The top left x position of the damage region * @y: The top left y position of the damage region @@ -613,6 +632,16 @@ clutter_wayland_surface_damage_buffer (ClutterWaylandSurface *self, x, y, width, height); } +/** + * clutter_wayland_surface_get_cogl_texture: + * @self: a #ClutterWaylandSurface + * + * Retrieves the Cogl texture with the contents of the Wayland surface. + * + * Return value: (transfer none): a Cogl texture, or %NULL + * + * Since: 1.10 + */ CoglTexture * clutter_wayland_surface_get_cogl_texture (ClutterWaylandSurface *self) { diff --git a/doc/reference/clutter/clutter-sections.txt b/doc/reference/clutter/clutter-sections.txt index e407336..7b49e24 100644 --- a/doc/reference/clutter/clutter-sections.txt +++ b/doc/reference/clutter/clutter-sections.txt @@ -992,8 +992,11 @@ clutter_feature_get_all
clutter-color Colors +CLUTTER_COLOR_INIT ClutterColor clutter_color_new +clutter_color_alloc +clutter_color_init clutter_color_copy clutter_color_free clutter_color_equal @@ -1076,6 +1079,9 @@ clutter_event_set_flags clutter_event_get_flags clutter_event_get_axes clutter_event_get_event_sequence +clutter_event_get_angle +clutter_event_get_distance +clutter_event_get_position clutter_event_get @@ -1452,6 +1458,7 @@ CLUTTER_VERSION_1_4 CLUTTER_VERSION_1_6 CLUTTER_VERSION_1_8 CLUTTER_VERSION_1_10 +CLUTTER_VERSION_1_12 CLUTTER_VERSION_MAX_ALLOWED CLUTTER_VERSION_MIN_REQUIRED @@ -1470,6 +1477,7 @@ CLUTTER_AVAILABLE_IN_1_4 CLUTTER_AVAILABLE_IN_1_6 CLUTTER_AVAILABLE_IN_1_8 CLUTTER_AVAILABLE_IN_1_10 +CLUTTER_AVAILABLE_IN_1_12 CLUTTER_DEPRECATED_IN_1_0 CLUTTER_DEPRECATED_IN_1_0_FOR CLUTTER_DEPRECATED_IN_1_2 @@ -1482,6 +1490,8 @@ CLUTTER_DEPRECATED_IN_1_8 CLUTTER_DEPRECATED_IN_1_8_FOR CLUTTER_DEPRECATED_IN_1_10 CLUTTER_DEPRECATED_IN_1_10_FOR +CLUTTER_DEPRECATED_IN_1_12 +CLUTTER_DEPRECATED_IN_1_12_FOR CLUTTER_UNAVAILABLE
@@ -1871,9 +1881,15 @@ clutter_interval_get_type
+clutter-cairo +CLUTTER_CAIRO_FORMAT_ARGB32 +clutter_cairo_clear +clutter_cairo_set_source_color +
+ +
clutter-cairo-texture ClutterCairoTexture -CLUTTER_CAIRO_FORMAT_ARGB32 ClutterCairoTexture ClutterCairoTextureClass clutter_cairo_texture_new @@ -1891,9 +1907,6 @@ clutter_cairo_texture_invalidate_rectangle clutter_cairo_texture_invalidate clutter_cairo_texture_clear - -clutter_cairo_set_source_color - CLUTTER_TYPE_CAIRO_TEXTURE CLUTTER_CAIRO_TEXTURE @@ -2897,6 +2910,10 @@ clutter_drop_action_get_type clutter-transition ClutterTransition ClutterTransitionClass +clutter_transition_set_from +clutter_transition_set_from_value +clutter_transition_set_to +clutter_transition_set_to_value clutter_transition_set_interval clutter_transition_get_interval clutter_transition_set_animatable @@ -3237,7 +3254,7 @@ clutter_keyframe_transition_get_n_key_frames clutter_keyframe_transition_set_key_frame clutter_keyframe_transition_get_key_frame clutter_keyframe_transition_clear -
+ CLUTTER_TYPE_KEYFRAME_TRANSITION CLUTTER_KEYFRAME_TRANSITION CLUTTER_KEYFRAME_TRANSITION_CLASS -- 2.7.4