From 500d7482b6ba01e99b3b21665c42dd9847e3925a Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Sun, 1 Jul 2007 16:44:24 +0000 Subject: [PATCH] Documentation fixes Various fixes in the API reference build and text. --- clutter/clutter-actor.c | 18 +++---- clutter/clutter-actor.h | 63 +++++++++++++++++++++--- clutter/clutter-behaviour.c | 5 +- clutter/clutter-behaviour.h | 12 ++++- clutter/clutter-container.c | 2 +- clutter/clutter-event.c | 2 +- clutter/clutter-group.c | 51 +++++++++---------- clutter/clutter-layout.h | 5 +- clutter/clutter-stage.c | 9 ++-- clutter/clutter-timeline.c | 22 +++++++++ doc/reference/clutter-sections.txt | 78 +++++++++++++++++++++++++----- 11 files changed, 199 insertions(+), 68 deletions(-) diff --git a/clutter/clutter-actor.c b/clutter/clutter-actor.c index 33bf2bbbb..9dbe13004 100644 --- a/clutter/clutter-actor.c +++ b/clutter/clutter-actor.c @@ -367,7 +367,7 @@ clutter_actor_transform_point (ClutterActor *actor, cogl_pop_matrix(); } -/* Help macros to scale from OpenGL <-1,1> coordianta system to our +/* Help macros to scale from OpenGL <-1,1> coordinates system to our * X-window based <0,window-size> coordinates */ #define MTX_GL_SCALE_X(x,w,v1,v2) (CFX_MUL( \ @@ -390,8 +390,8 @@ clutter_actor_transform_point (ClutterActor *actor, * @y2: projected y coordinance * @z2: projected z coordinance * - * Transforms point [x,y,z] in coordinance relative to the actor - * into screen coordiances [x2,y2,z2] + * Transforms point (x, y, z) in coordinates relative to the actor + * into screen coordiances (x2, y2, z2) * * Since: 0.4 **/ @@ -508,16 +508,16 @@ clutter_actor_transform_vertices (ClutterActor * self, * the actor; the returned vertices relate to the ClutterActoBox * coordinances as follows: * - * v[0] ~ - * v[1] ~ - * v[2] ~ - * v[3] ~ . + * v[0] contains (x1, y1) + * v[1] contains (x2, y1) + * v[2] contains (x1, y2) + * v[3] contains (x2, y2) * * Since: 0.4 **/ void -clutter_actor_get_vertices (ClutterActor * self, - ClutterVertex verts[4]) +clutter_actor_get_vertices (ClutterActor *self, + ClutterVertex verts[4]) { ClutterFixed mtx_p[16]; ClutterFixed v[4]; diff --git a/clutter/clutter-actor.h b/clutter/clutter-actor.h index bbf2fa7b7..4d144a1e5 100644 --- a/clutter/clutter-actor.h +++ b/clutter/clutter-actor.h @@ -82,14 +82,18 @@ typedef struct _ClutterVertex ClutterVertex; typedef void (*ClutterCallback) (ClutterActor *actor, gpointer data); #define CLUTTER_CALLBACK(f) ((ClutterCallback) (f)) +/** + * ClutterGeometry: + * @x: X coordinate of the top left corner of an actor + * @y: Y coordinate of the top left corner of an actor + * @width: width of an actor + * @height: height of an actor + * + * Rectangle containing an actor. + */ struct _ClutterGeometry { - /* FIXME: - * It is likely gonna save a load of pain if we make - * x,y unsigned... - * - * No, no, no, usigned is evil; we should make width and height signed. - */ + /*< public >*/ gint x; gint y; guint width; @@ -98,16 +102,51 @@ struct _ClutterGeometry GType clutter_geometry_get_type (void) G_GNUC_CONST; +/** + * ClutterActorFlags: + * @CLUTTER_ACTOR_MAPPED: the actor has been painted + * @CLUTTER_ACTOR_REALIZED: the resources associated to the actor have been + * allocated + * + * Flags used to signal the state of an actor. + */ typedef enum { CLUTTER_ACTOR_MAPPED = 1 << 1, CLUTTER_ACTOR_REALIZED = 1 << 2 } ClutterActorFlags; -struct _ClutterActorBox { ClutterUnit x1, y1, x2, y2; }; +/** + * ClutterActorBox: + * @x1: X coordinate of the top left corner + * @y1: Y coordinate of the top left corner + * @x2: X coordinate of the bottom right corner + * @y2: Y coordinate of the bottom right corner + * + * Bounding box of an actor. The coordinates of the top left and right bottom + * corners of an actor. The coordinates of the two points are expressed in + * #ClutterUnits, that is are device-independent. If you want to obtain + * the box dimensions in pixels, use clutter_actor_get_geometry(). + */ +struct _ClutterActorBox { + ClutterUnit x1; + ClutterUnit y1; + ClutterUnit x2; + ClutterUnit y2; +}; GType clutter_actor_box_get_type (void) G_GNUC_CONST; +/** + * ClutterVertex: + * @x: X coordinate of the vertex + * @y: Y coordinate of the vertex + * @z: Z coordinate of the vertex + * + * Vertex of an actor in 3D space, expressed in device independent units. + * + * Since: 0.4 + */ struct _ClutterVertex { ClutterUnit x; @@ -117,10 +156,18 @@ struct _ClutterVertex GType clutter_vertices_get_type (void) G_GNUC_CONST; +/** + * ClutterActor: + * @flags: #ClutterActorFlags + * + * Base class for actors. + */ struct _ClutterActor { - /*< public >*/ + /*< private >*/ GObject parent_instance; + + /*< public >*/ guint32 flags; /*< private >*/ diff --git a/clutter/clutter-behaviour.c b/clutter/clutter-behaviour.c index f50373d2f..de961c921 100644 --- a/clutter/clutter-behaviour.c +++ b/clutter/clutter-behaviour.c @@ -257,13 +257,14 @@ clutter_behaviour_class_init (ClutterBehaviourClass *klass) klass->alpha_notify = clutter_behaviour_alpha_notify_unimplemented; /** - * ClutterBeavhour::apply: - * @behaviour: the #ClutterBehvaiour that received the signal + * ClutterBehaviour::apply: + * @behaviour: the #ClutterBehaviour that received the signal * @actor: the actor the behaviour was applied to. * * The ::apply signal is emitted each time the behaviour is applied * to an actor. * + * Since: 0.4 */ behave_signals[APPLY] = g_signal_new ("apply", diff --git a/clutter/clutter-behaviour.h b/clutter/clutter-behaviour.h index 889aaa21a..f6c60628e 100644 --- a/clutter/clutter-behaviour.h +++ b/clutter/clutter-behaviour.h @@ -37,9 +37,19 @@ G_BEGIN_DECLS typedef struct _ClutterKnot ClutterKnot; +/** + * ClutterKnot: + * @x: X coordinate of the knot + * @y: Y coordinate of the knot + * + * Point in a path behaviour. + * + * Since: 0.2 + */ struct _ClutterKnot { - gint x,y; + gint x; + gint y; }; GType clutter_knot_get_type (void) G_GNUC_CONST; diff --git a/clutter/clutter-container.c b/clutter/clutter-container.c index c277aca49..19d602f04 100644 --- a/clutter/clutter-container.c +++ b/clutter/clutter-container.c @@ -142,7 +142,7 @@ clutter_container_get_type (void) * clutter_container_add: * @container: a #ClutterContainer * @first_actor: the first #ClutterActor to add - * @Varargs: %NULL terminated list of actors to add + * @varargs: %NULL terminated list of actors to add * * Adds a list of #ClutterActors to @container. Each time and * actor is added, the "actor-added" signal is emitted. Each actor should diff --git a/clutter/clutter-event.c b/clutter/clutter-event.c index 187574702..483c68e2b 100644 --- a/clutter/clutter-event.c +++ b/clutter/clutter-event.c @@ -102,7 +102,7 @@ clutter_event_get_time (ClutterEvent *event) * * Retrieves the modifier state of the event. * - * Return value the modifier state parameter, or 0 + * Return value: the modifier state parameter, or 0 * * Since: 0.4 */ diff --git a/clutter/clutter-group.c b/clutter/clutter-group.c index 1597be301..a879f4fcf 100644 --- a/clutter/clutter-group.c +++ b/clutter/clutter-group.c @@ -369,7 +369,7 @@ clutter_group_new (void) /** * clutter_group_add: - * @self: A #ClutterGroup + * @group: A #ClutterGroup * @actor: A #ClutterActor * * Adds a new child #ClutterActor to the #ClutterGroup. @@ -378,17 +378,17 @@ clutter_group_new (void) * clutter_container_add_actor() instead. */ void -clutter_group_add (ClutterGroup *self, +clutter_group_add (ClutterGroup *group, ClutterActor *actor) { - clutter_container_add_actor (CLUTTER_CONTAINER (self), actor); + clutter_container_add_actor (CLUTTER_CONTAINER (group), actor); } /** * clutter_group_add_many_valist: - * @self: a #ClutterGroup + * @group: a #ClutterGroup * @first_actor: the #ClutterActor actor to add to the group - * @args: the actors to be added + * @var_args: the actors to be added * * Similar to clutter_group_add_many() but using a va_list. Use this * function inside bindings. @@ -397,16 +397,16 @@ clutter_group_add (ClutterGroup *self, * clutter_container_add_valist() instead. */ void -clutter_group_add_many_valist (ClutterGroup *self, +clutter_group_add_many_valist (ClutterGroup *group, ClutterActor *first_actor, - va_list args) + va_list var_args) { - clutter_container_add_valist (CLUTTER_CONTAINER (self), first_actor, args); + clutter_container_add_valist (CLUTTER_CONTAINER (group), first_actor, var_args); } /** * clutter_group_add_many: - * @self: A #ClutterGroup + * @group: A #ClutterGroup * @first_actor: the #ClutterActor actor to add to the group * @Varargs: additional actors to add to the group * @@ -417,56 +417,53 @@ clutter_group_add_many_valist (ClutterGroup *self, * instead. */ void -clutter_group_add_many (ClutterGroup *self, +clutter_group_add_many (ClutterGroup *group, ClutterActor *first_actor, ...) { va_list args; va_start (args, first_actor); - clutter_container_add_valist (CLUTTER_CONTAINER (self), first_actor, args); + clutter_container_add_valist (CLUTTER_CONTAINER (group), first_actor, args); va_end (args); } /** * clutter_group_remove - * @self: A #ClutterGroup + * @group: A #ClutterGroup * @actor: A #ClutterActor * - * Remove a child #ClutterActor from the #ClutterGroup. + * Removes a child #ClutterActor from the parent #ClutterGroup. * * @Deprecated: 0.4: This function is obsolete, use * clutter_container_remove_actor() instead. */ void -clutter_group_remove (ClutterGroup *self, +clutter_group_remove (ClutterGroup *group, ClutterActor *actor) { - clutter_container_remove_actor (CLUTTER_CONTAINER (self), actor); + clutter_container_remove_actor (CLUTTER_CONTAINER (group), actor); } /** * clutter_group_remove_all: - * @self: A #ClutterGroup + * @group: A #ClutterGroup * - * Remove all children actors from the #ClutterGroup. + * Removes all children actors from the #ClutterGroup. */ void -clutter_group_remove_all (ClutterGroup *self) +clutter_group_remove_all (ClutterGroup *group) { - GList *child_item, *next; + GList *l; - g_return_if_fail (CLUTTER_IS_GROUP (self)); + g_return_if_fail (CLUTTER_IS_GROUP (group)); - if ((child_item = self->priv->children) == NULL) - return; - - do + for (l = group->priv->children; l; l = l->next) { - next = g_list_next(child_item); - clutter_group_remove (self, CLUTTER_ACTOR (child_item->data)); + ClutterActor *child = l->data; + + clutter_container_remove_actor (CLUTTER_CONTAINER (group), child); } - while ((child_item = next) != NULL); } /** diff --git a/clutter/clutter-layout.h b/clutter/clutter-layout.h index d20c76432..e36ba0212 100644 --- a/clutter/clutter-layout.h +++ b/clutter/clutter-layout.h @@ -42,15 +42,14 @@ G_BEGIN_DECLS /** * ClutterLayoutFlags - * - * Type of layouts supported by an actor. - * * @CLUTTER_LAYOUT_NONE: No layout (default behaviour) * @CLUTTER_LAYOUT_WIDTH_FOR_HEIGHT: Width-for-height * @CLUTTER_LAYOUT_HEIGHT_FOR_WIDTH: Height-for-width * @CLUTTER_LAYOUT_NATURAL: Natural size request * @CLUTTER_LAYOUT_TUNABLE: Tunable size request * + * Type of layouts supported by an actor. + * * Since: 0.4 */ typedef enum { diff --git a/clutter/clutter-stage.c b/clutter/clutter-stage.c index 62b98ef07..39ebde354 100644 --- a/clutter/clutter-stage.c +++ b/clutter/clutter-stage.c @@ -749,11 +749,12 @@ clutter_stage_snapshot (ClutterStage *stage, /** * clutter_stage_get_actor_at_pos: - * @stage: - * @x: - * @y: + * @stage: a #ClutterStage + * @x: X coordinate to check + * @y: Y coordinate to check * - * FIXME + * Checks the scene at the coordinates @x and @y and returns a pointer + * to the #ClutterActor at those coordinates. * * Return value: the actor at the specified coordinates, if any */ diff --git a/clutter/clutter-timeline.c b/clutter/clutter-timeline.c index 6639a2cce..41bcd31ca 100644 --- a/clutter/clutter-timeline.c +++ b/clutter/clutter-timeline.c @@ -335,6 +335,13 @@ clutter_timeline_class_init (ClutterTimelineClass *klass) clutter_marshal_VOID__INT, G_TYPE_NONE, 1, G_TYPE_INT); + /** + * ClutterTimeline::completed: + * @timeline: the #ClutterTimeline which received the signal + * + * The ::completed signal is emitted when the timeline reaches the + * number of frames specified by the ClutterTimeline:num-frames property. + */ timeline_signals[COMPLETED] = g_signal_new ("completed", G_TYPE_FROM_CLASS (object_class), @@ -343,6 +350,15 @@ clutter_timeline_class_init (ClutterTimelineClass *klass) NULL, NULL, clutter_marshal_VOID__VOID, G_TYPE_NONE, 0); + /** + * ClutterTimeline::started: + * @timeline: the #ClutterTimeline which received the signal + * + * The ::started signal is emitted when the timeline starts its run. + * This might be as soon as clutter_timeline_start() is invoked or + * after the delay set in the ClutterTimeline:delay property has + * expired. + */ timeline_signals[STARTED] = g_signal_new ("started", G_TYPE_FROM_CLASS (object_class), @@ -351,6 +367,12 @@ clutter_timeline_class_init (ClutterTimelineClass *klass) NULL, NULL, clutter_marshal_VOID__VOID, G_TYPE_NONE, 0); + /** + * ClutterTimeline::paused: + * @timeline: the #ClutterTimeline which received the signal + * + * The ::paused signal is emitted when clutter_timeline_pause() is invoked. + */ timeline_signals[PAUSED] = g_signal_new ("paused", G_TYPE_FROM_CLASS (object_class), diff --git a/doc/reference/clutter-sections.txt b/doc/reference/clutter-sections.txt index 5e5812c4b..9422f57cf 100644 --- a/doc/reference/clutter-sections.txt +++ b/doc/reference/clutter-sections.txt @@ -27,6 +27,7 @@ clutter_media_get_type
clutter-units Unit conversion +ClutterUnit CLUTTER_UNITS_FROM_DEVICE CLUTTER_UNITS_FROM_FIXED CLUTTER_UNITS_FROM_FLOAT @@ -140,6 +141,10 @@ CLUTTER_ALPHA_SQUARE clutter_square_func CLUTTER_ALPHA_SMOOTHSTEP clutter_smoothstep_func +CLUTTER_ALPHA_SMOOTHSTEP_INC +clutter_smoothstep_inc_func +CLUTTER_ALPHA_SMOOTHSTEP_DEC +clutter_smoothstep_dec_func CLUTTER_ALPHA_EXP_INC clutter_exp_inc_func CLUTTER_ALPHA_EXP_DEC @@ -151,6 +156,7 @@ CLUTTER_TYPE_ALPHA CLUTTER_ALPHA_CLASS CLUTTER_IS_ALPHA_CLASS CLUTTER_ALPHA_GET_CLASS +CLUTTER_TYPE_SMOOTHSTEP ClutterAlphaPrivate clutter_alpha_get_type @@ -234,7 +240,6 @@ clutter_container_get_type
clutter-layout ClutterLayout -ClutterLayout ClutterLayoutIface ClutterLayoutFlags clutter_layout_get_layout_flags @@ -244,6 +249,7 @@ clutter_layout_natural_request clutter_layout_tune_request clutter_layout_width_for_height +ClutterLayout CLUTTER_TYPE_LAYOUT CLUTTER_LAYOUT CLUTTER_IS_LAYOUT @@ -279,6 +285,7 @@ clutter_rectangle_get_type
clutter-actor +ClutterActor CLUTTER_ACTOR_SET_FLAGS CLUTTER_ACTOR_UNSET_FLAGS CLUTTER_ACTOR_IS_MAPPED @@ -289,7 +296,6 @@ ClutterActorFlags ClutterGeometry CLUTTER_CALLBACK ClutterCallback -ClutterActor ClutterActor ClutterActorClass clutter_actor_show @@ -302,7 +308,7 @@ clutter_actor_paint clutter_actor_queue_redraw clutter_actor_destroy clutter_actor_request_coords -clutter_actor_allocate_coords +clutter_actor_query_coords clutter_actor_set_geometry clutter_actor_get_geometry clutter_actor_get_coords @@ -343,6 +349,18 @@ clutter_actor_set_scale clutter_actor_get_scalex clutter_actor_get_scale clutter_actor_get_abs_size +clutter_actor_apply_transform_to_point +clutter_actor_get_rxangx +clutter_actor_get_ryangx +clutter_actor_get_rzangx +ClutterVertex +clutter_actor_get_vertices +clutter_actor_pick +clutter_actor_rotate_xx +clutter_actor_rotate_yx +clutter_actor_rotate_zx +clutter_actor_set_scale_with_gravity +clutter_actor_set_scale_with_gravityx CLUTTER_TYPE_GEOMETRY CLUTTER_TYPE_ACTOR_BOX @@ -357,6 +375,7 @@ ClutterActorPrivate clutter_actor_get_type clutter_actor_box_get_type clutter_geometry_get_type +clutter_vertices_get_type
@@ -364,9 +383,11 @@ clutter_geometry_get_type ClutterTexture ClutterTexture ClutterTextureClass +ClutterTextureFlags clutter_texture_new_from_pixbuf clutter_texture_new -clutter_texture_set_from_data +clutter_texture_set_from_rgb_data +clutter_texture_set_from_yuv_data clutter_texture_set_pixbuf clutter_texture_get_pixbuf clutter_texture_get_base_size @@ -390,9 +411,9 @@ clutter_texture_get_type
clutter-stage +ClutterStage CLUTTER_STAGE_WIDTH CLUTTER_STAGE_HEIGHT -ClutterStage ClutterPerspective clutter_perspective_copy clutter_perspective_free @@ -408,6 +429,12 @@ clutter_stage_hide_cursor clutter_stage_get_actor_at_pos clutter_stage_snapshot clutter_stage_event +clutter_stage_set_perspective +clutter_stage_set_perspectivex +clutter_stage_get_perspective +clutter_stage_get_perspectivex +clutter_stage_set_title +clutter_stage_get_title CLUTTER_STAGE CLUTTER_IS_STAGE @@ -415,6 +442,7 @@ CLUTTER_TYPE_STAGE CLUTTER_STAGE_CLASS CLUTTER_IS_STAGE_CLASS CLUTTER_STAGE_GET_CLASS +CLUTTER_TYPE_PERSPECTIVE ClutterStagePrivate clutter_stage_get_type @@ -514,11 +542,13 @@ ClutterBehaviourRotateClass clutter_behaviour_rotate_new clutter_behaviour_rotate_newx clutter_behaviour_rotate_set_axis -clutter_behaviour_rotate_set_direction clutter_behaviour_rotate_get_axis +clutter_behaviour_rotate_set_direction +clutter_behaviour_rotate_get_direction +clutter_behaviour_rotate_set_bounds +clutter_behaviour_rotate_set_boundsx clutter_behaviour_rotate_get_bounds clutter_behaviour_rotate_get_boundsx -clutter_behaviour_rotate_get_direction CLUTTER_TYPE_BEHAVIOUR_ROTATE CLUTTER_BEHAVIOUR_ROTATE @@ -587,6 +617,7 @@ clutter_behaviour_bspline_get_type ClutterBehaviourEllipse ClutterBehaviourEllipseClass clutter_behaviour_ellipse_new +clutter_behaviour_ellipse_newx clutter_behaviour_ellipse_set_center clutter_behaviour_ellipse_get_center clutter_behaviour_ellipse_get_angle_begin @@ -639,6 +670,7 @@ CLUTTER_BACKEND_GET_CLASS CLUTTER_TYPE_BACKEND ClutterBackendClass +ClutterBackendPrivate clutter_backend_get_type
@@ -683,6 +715,8 @@ CFX_255 CFX_DIV CFX_INT CFX_MUL +CFX_HALF +CFX_QMUL CLUTTER_FIXED_TO_FLOAT CLUTTER_FIXED_TO_DOUBLE CLUTTER_FLOAT_TO_FIXED @@ -694,12 +728,21 @@ CLUTTER_FIXED_FLOOR CLUTTER_FIXED_CEIL CLUTTER_FIXED_MUL CLUTTER_FIXED_DIV +CLUTTER_ANGLE_FROM_DEG +CLUTTER_ANGLE_FROM_DEGF +CLUTTER_ANGLE_FROM_DEGX +CLUTTER_ANGLE_TO_DEGF clutter_cosi clutter_cosx clutter_sini clutter_sinx clutter_sqrti clutter_sqrtx +clutter_log2x +clutter_pow2x +clutter_powx +clutter_qmulx +clutter_tani
@@ -710,6 +753,7 @@ clutter_color_copy clutter_color_free clutter_color_parse clutter_color_from_hls +clutter_color_from_hlsx clutter_color_from_pixel clutter_color_add clutter_color_subtract @@ -719,6 +763,7 @@ clutter_color_darken clutter_color_shade clutter_color_shadex clutter_color_to_hls +clutter_color_to_hlsx clutter_color_to_pixel clutter_color_to_string @@ -732,8 +777,7 @@ clutter_color_get_type Events CLUTTER_CURRENT_TIME CLUTTER_PRIORITY_EVENTS -ClutterFilterFunc -ClutterFilterResponse +ClutterModifierType ClutterScrollDirection ClutterStageState ClutterEventType @@ -784,6 +828,8 @@ clutter_main_level clutter_redraw clutter_threads_enter clutter_threads_leave +clutter_base_init +clutter_get_timestamp clutter_init_error_quark
@@ -799,6 +845,8 @@ clutter_glx_get_stage_window clutter_glx_set_stage_foreign clutter_glx_trap_x_errors clutter_glx_untrap_x_errors +ClutterGLXFilterFunc +ClutterGLXFilterReturn
@@ -812,6 +860,8 @@ CLUTTER_VERSION_S CLUTTER_VERSION_HEX CLUTTER_CHECK_VERSION CLUTTER_FLAVOUR +CLUTTER_COGL +CLUTTER_NO_FPU
@@ -864,8 +914,10 @@ ClutterBox ClutterBoxClass clutter_box_set_spacing clutter_box_get_spacing +ClutterPackType clutter_box_pack_start clutter_box_pack_end +ClutterBoxChild clutter_box_query_child clutter_box_query_nth_child @@ -877,13 +929,13 @@ CLUTTER_IS_BOX_CLASS CLUTTER_BOX_GET_CLASS clutter_box_get_type +clutter_box_child_get_type
-clutter-effects -Clutter Effects +clutter-effect +Clutter Effects ClutterEffectTemplate -ClutterEffectTemplaceClass clutter_effect_template_new ClutterEffectCompleteFunc clutter_effect_fade @@ -896,7 +948,9 @@ CLUTTER_IS_EFFECT_TEMPLATE CLUTTER_EFFECT_TEMPLATE_CLASS CLUTTER_IS_EFFECT_TEMPLATE_CLASS CLUTTER_EFFECT_TEMPLATE_GET_CLASS +ClutterEffectTemplateClass +ClutterEffectTemplatePrivate clutter_effect_template_get_type