From d7caae7f6a12c6831d81574827cd0b2c93898059 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Wed, 4 Jul 2007 14:00:41 +0000 Subject: [PATCH] 2007-07-04 Emmanuele Bassi * clutter/*: Loads of fixes for the API reference. --- ChangeLog | 4 ++ clutter/clutter-actor.h | 6 +-- clutter/clutter-backend.c | 14 ++++++ clutter/clutter-box.c | 44 ++++++++++++++++++ clutter/clutter-container.c | 12 ++--- clutter/clutter-container.h | 4 +- clutter/clutter-effect.c | 89 +++++++++++++++++++++++-------------- clutter/clutter-effect.h | 2 +- clutter/clutter-event.h | 12 +---- clutter/clutter-hbox.c | 9 ++++ clutter/clutter-main.c | 1 - clutter/clutter-stage.c | 21 ++++++--- clutter/clutter-stage.h | 57 ++++++++++++------------ clutter/clutter-texture.c | 6 ++- clutter/clutter-vbox.c | 9 ++++ configure.ac | 2 +- 16 files changed, 197 insertions(+), 95 deletions(-) diff --git a/ChangeLog b/ChangeLog index 123df4e3d..0f0da6b0b 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2007-07-04 Emmanuele Bassi + + * clutter/*: Loads of fixes for the API reference. + 2007-07-04 Emmanuele Bassi Merge from clutter/work diff --git a/clutter/clutter-actor.h b/clutter/clutter-actor.h index 2ea27aaa8..7513fb335 100644 --- a/clutter/clutter-actor.h +++ b/clutter/clutter-actor.h @@ -215,8 +215,8 @@ void clutter_actor_hide_all (ClutterActor *sel void clutter_actor_realize (ClutterActor *self); void clutter_actor_unrealize (ClutterActor *self); void clutter_actor_paint (ClutterActor *self); -void clutter_actor_pick (ClutterActor *actor, - const ClutterColor *color); +void clutter_actor_pick (ClutterActor *self, + const ClutterColor *color); void clutter_actor_queue_redraw (ClutterActor *self); void clutter_actor_destroy (ClutterActor *self); void clutter_actor_request_coords (ClutterActor *self, @@ -345,7 +345,7 @@ void clutter_actor_move_by (ClutterActor void clutter_actor_get_vertices (ClutterActor *self, ClutterVertex verts[4]); -void clutter_actor_apply_transform_to_point (ClutterActor *actor, +void clutter_actor_apply_transform_to_point (ClutterActor *self, ClutterVertex *point, ClutterVertex *vertex); diff --git a/clutter/clutter-backend.c b/clutter/clutter-backend.c index 025cbc1a9..9ac13e9e6 100644 --- a/clutter/clutter-backend.c +++ b/clutter/clutter-backend.c @@ -23,6 +23,20 @@ * Boston, MA 02111-1307, USA. */ +/** + * SECTION:clutter-backend + * @short_description: Backend abstraction + * + * Clutter can be compiled against different backends. Each backend + * has to implement a set of functions, in order to be used by Clutter. + * + * #ClutterBackend is the base class abstracting the various implementation; + * it provides a basic API to query the backend for generic information + * and settings. + * + * #ClutterBackend is available since Clutter 0.4 + */ + #ifndef HAVE_CONFIG_H #include "config.h" #endif diff --git a/clutter/clutter-box.c b/clutter/clutter-box.c index a3a832835..134dd48e3 100644 --- a/clutter/clutter-box.c +++ b/clutter/clutter-box.c @@ -343,6 +343,18 @@ clutter_box_pack_end (ClutterBox *box, clutter_actor_queue_redraw (CLUTTER_ACTOR (box)); } +/** + * clutter_box_query_child: + * @box: a #ClutterBox + * @actor: child to query + * @child: return location for a #ClutterBoxChild or %NULL + * + * Queries @box for the packing data of @actor. + * + * Return value: %TRUE if @actor is a child of @box + * + * Since: 0.4 + */ gboolean clutter_box_query_child (ClutterBox *box, ClutterActor *actor, @@ -372,6 +384,19 @@ clutter_box_query_child (ClutterBox *box, return FALSE; } +/** + * clutter_box_query_nth_child: + * @box: a #ClutterBox + * @index: position of the child + * @child: return value for a #ClutterBoxChild, or %NULL + * + * Queries the child of @box at @index and puts the packing informations + * inside @child. + * + * Return value: %TRUE if an actor was found at @index + * + * Since: 0.4 + */ gboolean clutter_box_query_nth_child (ClutterBox *box, gint index, @@ -395,6 +420,16 @@ clutter_box_query_nth_child (ClutterBox *box, return TRUE; } +/** + * clutter_box_get_spacing: + * @box: a #ClutterBox + * + * Gets the value set using clutter_box_set_spacing(). + * + * Return value: the spacing between children of the box + * + * Since: 0.4 + */ guint clutter_box_get_spacing (ClutterBox *box) { @@ -403,6 +438,15 @@ clutter_box_get_spacing (ClutterBox *box) return box->spacing; } +/** + * clutter_box_set_spacing: + * @box: a #ClutterBox + * @spacing: the spacing between children + * + * Sets the spacing, in pixels, between the children of @box. + * + * Since: 0.4 + */ void clutter_box_set_spacing (ClutterBox *box, guint spacing) diff --git a/clutter/clutter-container.c b/clutter/clutter-container.c index 19d602f04..ca1881081 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 @@ -156,14 +156,14 @@ clutter_container_add (ClutterContainer *container, ClutterActor *first_actor, ...) { - va_list var_args; + va_list args; g_return_if_fail (CLUTTER_IS_CONTAINER (container)); g_return_if_fail (CLUTTER_IS_ACTOR (first_actor)); - va_start (var_args, first_actor); - clutter_container_add_valist (container, first_actor, var_args); - va_end (var_args); + va_start (args, first_actor); + clutter_container_add_valist (container, first_actor, args); + va_end (args); } /** @@ -203,7 +203,7 @@ clutter_container_add_actor (ClutterContainer *container, } /** - * clutter_container_add: + * clutter_container_add_valist: * @container: a #ClutterContainer * @first_actor: the first #ClutterActor to add * @var_args: list of actors to add, followed by %NULL diff --git a/clutter/clutter-container.h b/clutter/clutter-container.h index 80a4adeb9..59502330c 100644 --- a/clutter/clutter-container.h +++ b/clutter/clutter-container.h @@ -69,7 +69,7 @@ void clutter_container_add_actor (ClutterContainer *container, ClutterActor *actor); void clutter_container_add_valist (ClutterContainer *container, ClutterActor *first_actor, - va_list varargs); + va_list var_args); void clutter_container_remove (ClutterContainer *container, ClutterActor *first_actor, ...) G_GNUC_NULL_TERMINATED; @@ -77,7 +77,7 @@ void clutter_container_remove_actor (ClutterContainer *container, ClutterActor *actor); void clutter_container_remove_valist (ClutterContainer *container, ClutterActor *first_actor, - va_list varargs); + va_list var_args); GList *clutter_container_get_children (ClutterContainer *container); void clutter_container_foreach (ClutterContainer *container, ClutterCallback callback, diff --git a/clutter/clutter-effect.c b/clutter/clutter-effect.c index 68eacda40..1a99c1b11 100644 --- a/clutter/clutter-effect.c +++ b/clutter/clutter-effect.c @@ -171,6 +171,13 @@ clutter_effect_template_class_init (ClutterEffectTemplateClass *klass) object_class->set_property = clutter_effect_template_set_property; object_class->get_property = clutter_effect_template_get_property; + /** + * ClutterEffectTemplate:alpha-func: + * + * #ClutterAlphaFunc to be used by the template + * + * Since: 0.4 + */ g_object_class_install_property (object_class, PROP_ALPHA_FUNC, @@ -179,7 +186,13 @@ clutter_effect_template_class_init (ClutterEffectTemplateClass *klass) "Alpha reference Function", G_PARAM_CONSTRUCT_ONLY | CLUTTER_PARAM_READWRITE)); - + /** + * ClutterEffectTemplate:timeline: + * + * #ClutterTimeline to be used by the template + * + * Since: 0.4 + */ g_object_class_install_property (object_class, PROP_TIMELINE, @@ -199,7 +212,6 @@ clutter_effect_template_init (ClutterEffectTemplate *self) /** * clutter_effect_template_new: - * * @timeline: A #ClutterTimeline for the template (will be cloned) * @alpha_func: An alpha func to use for the template. * @@ -209,7 +221,7 @@ clutter_effect_template_init (ClutterEffectTemplate *self) * * Since: 0.4 */ -ClutterEffectTemplate* +ClutterEffectTemplate * clutter_effect_template_new (ClutterTimeline *timeline, ClutterAlphaFunc alpha_func) { @@ -275,35 +287,38 @@ on_effect_complete (ClutterTimeline *timeline, /** * clutter_effect_fade: - * - * @template: A #ClutterEffectTemplate + * @template_: A #ClutterEffectTemplate * @actor: A #ClutterActor to apply the effect to. * @start_opacity: Initial opacity value to apply to actor * @end_opacity: Final opacity value to apply to actor - * @completed_func: A #ClutterEffectCompleteFunc to call on effect completion or NULL - * @completed_userdata: Data to pass to supplied #ClutterEffectCompleteFunc or NULL + * @completed_func: A #ClutterEffectCompleteFunc to call on effect + * completion or %NULL + * @completed_data: Data to pass to supplied #ClutterEffectCompleteFunc + * or %NULL + * + * Simple effect for fading a single #ClutterActor. * * Return value: a #ClutterTimeline for the effect. Will be unrefed by * the effect when completed. * * Since: 0.4 */ -ClutterTimeline* -clutter_effect_fade (ClutterEffectTemplate *template, +ClutterTimeline * +clutter_effect_fade (ClutterEffectTemplate *template_, ClutterActor *actor, guint8 start_opacity, guint8 end_opacity, ClutterEffectCompleteFunc completed_func, - gpointer completed_userdata) + gpointer completed_data) { ClutterEffectClosure *c; - c = clutter_effect_closure_new (template, + c = clutter_effect_closure_new (template_, actor, G_CALLBACK (on_effect_complete)); c->completed_func = completed_func; - c->completed_data = completed_userdata; + c->completed_data = completed_data; c->behave = clutter_behaviour_opacity_new (c->alpha, start_opacity, @@ -317,35 +332,38 @@ clutter_effect_fade (ClutterEffectTemplate *template, /** * clutter_effect_move: - * - * @template: A #ClutterEffectTemplate + * @template_: A #ClutterEffectTemplate * @actor: A #ClutterActor to apply the effect to. * @knots: An array of #ClutterKnots representing path for the actor * @n_knots: Number of #ClutterKnots in passed array. - * @completed_func: A #ClutterEffectCompleteFunc to call on effect completion or NULL - * @completed_userdata: Data to pass to supplied #ClutterEffectCompleteFunc or NULL + * @completed_func: A #ClutterEffectCompleteFunc to call on effect + * completion or %NULL + * @completed_data: Data to pass to supplied #ClutterEffectCompleteFunc + * or %NULL * - * Return value: a #ClutterTimeline for the effect. Will be unrefed by - * the effect when completed. + * Simple effect for moving a single #ClutterActor along a path. + * + * Return value: a #ClutterTimeline for the effect. Will be unreferenced by + * the effect when completed. * * Since: 0.4 */ -ClutterTimeline* -clutter_effect_move (ClutterEffectTemplate *template, +ClutterTimeline * +clutter_effect_move (ClutterEffectTemplate *template_, ClutterActor *actor, const ClutterKnot *knots, guint n_knots, ClutterEffectCompleteFunc completed_func, - gpointer completed_userdata) + gpointer completed_data) { ClutterEffectClosure *c; - c = clutter_effect_closure_new (template, + c = clutter_effect_closure_new (template_, actor, G_CALLBACK (on_effect_complete)); c->completed_func = completed_func; - c->completed_data = completed_userdata; + c->completed_data = completed_data; c->behave = clutter_behaviour_path_new (c->alpha, knots, n_knots); @@ -357,37 +375,40 @@ clutter_effect_move (ClutterEffectTemplate *template, /** * clutter_effect_scale: - * - * @template: A #ClutterEffectTemplate + * @template_: A #ClutterEffectTemplate * @actor: A #ClutterActor to apply the effect to. * @scale_begin: Initial scale factor to apply to actor * @scale_end: Final scale factor to apply to actor * @gravity: A #ClutterGravity for the scale. - * @completed_func: A #ClutterEffectCompleteFunc to call on effect completion or NULL - * @completed_userdata: Data to pass to supplied #ClutterEffectCompleteFunc or NULL + * @completed_func: A #ClutterEffectCompleteFunc to call on effect + * completion or NULL + * @completed_data: Data to pass to supplied #ClutterEffectCompleteFunc + * or NULL * - * Return value: a #ClutterTimeline for the effect. Will be unrefed by - * the effect when completed. + * Simple effect for scaling a single #ClutterActor. + * + * Return value: a #ClutterTimeline for the effect. Will be unreferenced by + * the effect when completed. * * Since: 0.4 */ -ClutterTimeline* -clutter_effect_scale (ClutterEffectTemplate *template, +ClutterTimeline * +clutter_effect_scale (ClutterEffectTemplate *template_, ClutterActor *actor, gdouble scale_begin, gdouble scale_end, ClutterGravity gravity, ClutterEffectCompleteFunc completed_func, - gpointer completed_userdata) + gpointer completed_data) { ClutterEffectClosure *c; - c = clutter_effect_closure_new (template, + c = clutter_effect_closure_new (template_, actor, G_CALLBACK (on_effect_complete)); c->completed_func = completed_func; - c->completed_data = completed_userdata; + c->completed_data = completed_data; c->behave = clutter_behaviour_scale_new (c->alpha, scale_begin, diff --git a/clutter/clutter-effect.h b/clutter/clutter-effect.h index f1bb6e09d..67c3278dc 100644 --- a/clutter/clutter-effect.h +++ b/clutter/clutter-effect.h @@ -111,7 +111,7 @@ ClutterTimeline *clutter_effect_scale (ClutterEffectTemplate *template_, gdouble scale_end, ClutterGravity gravity, ClutterEffectCompleteFunc completed_func, - gpointer completed_userdata); + gpointer completed_data); G_END_DECLS diff --git a/clutter/clutter-event.h b/clutter/clutter-event.h index 83f7ef9cc..c7ec194c5 100644 --- a/clutter/clutter-event.h +++ b/clutter/clutter-event.h @@ -84,13 +84,6 @@ typedef enum CLUTTER_STAGE_STATE_OFFSCREEN } ClutterStageState; -typedef enum -{ - CLUTTER_FILTER_CONTINUE, - CLUTTER_FILTER_TRANSLATE, - CLUTTER_FILTER_REMOVE -} ClutterFilterResponse; - typedef union _ClutterEvent ClutterEvent; typedef struct _ClutterAnyEvent ClutterAnyEvent; @@ -100,10 +93,7 @@ typedef struct _ClutterMotionEvent ClutterMotionEvent; typedef struct _ClutterScrollEvent ClutterScrollEvent; typedef struct _ClutterStageStateEvent ClutterStageStateEvent; -typedef struct _ClutterInputDevice ClutterInputDevice; - - -typedef ClutterFilterResponse (* ClutterFilterFunc) (ClutterEvent *event, gpointer data); +typedef struct _ClutterInputDevice ClutterInputDevice; struct _ClutterAnyEvent { diff --git a/clutter/clutter-hbox.c b/clutter/clutter-hbox.c index 3f1e56e2f..81d70f8fd 100644 --- a/clutter/clutter-hbox.c +++ b/clutter/clutter-hbox.c @@ -162,6 +162,15 @@ clutter_hbox_init (ClutterHBox *box) } +/** + * clutter_hbox_new: + * + * Creates a new horizontal layout box. + * + * Return value: the newly created #ClutterHBox + * + * Since: 0.4 + */ ClutterActor * clutter_hbox_new (void) { diff --git a/clutter/clutter-main.c b/clutter/clutter-main.c index 9fdba7125..011368bbd 100644 --- a/clutter/clutter-main.c +++ b/clutter/clutter-main.c @@ -97,7 +97,6 @@ void clutter_redraw (void) { ClutterMainContext *ctx; - ClutterColor stage_color; ClutterActor *stage; static GTimer *timer = NULL; static guint timer_n_frames = 0; diff --git a/clutter/clutter-stage.c b/clutter/clutter-stage.c index b4f3922e0..b17ba0a8c 100644 --- a/clutter/clutter-stage.c +++ b/clutter/clutter-stage.c @@ -589,7 +589,10 @@ clutter_stage_set_perspective (ClutterStage *stage, /** * clutter_stage_get_perspective * @stage: A #ClutterStage - * @perspective: return location for a #ClutterPerspective + * @fovy: FIXME + * @aspect: FIXME + * @z_near: FIXME + * @z_far: FIXME * * Retrieves the stage perspective. */ @@ -605,10 +608,18 @@ clutter_stage_get_perspective (ClutterStage *stage, g_return_if_fail (CLUTTER_IS_STAGE (stage)); priv = stage->priv; - *fovy = CLUTTER_FIXED_TO_FLOAT(priv->perspective.fovy); - *aspect = CLUTTER_FIXED_TO_FLOAT(priv->perspective.aspect); - *z_near = CLUTTER_FIXED_TO_FLOAT(priv->perspective.z_near); - *z_far = CLUTTER_FIXED_TO_FLOAT(priv->perspective.z_far); + + if (fovy) + *fovy = CLUTTER_FIXED_TO_FLOAT (priv->perspective.fovy); + + if (aspect) + *aspect = CLUTTER_FIXED_TO_FLOAT (priv->perspective.aspect); + + if (z_near) + *z_near = CLUTTER_FIXED_TO_FLOAT (priv->perspective.z_near); + + if (z_far) + *z_far = CLUTTER_FIXED_TO_FLOAT (priv->perspective.z_far); } /** diff --git a/clutter/clutter-stage.h b/clutter/clutter-stage.h index ac8d1589d..f16211f6d 100644 --- a/clutter/clutter-stage.h +++ b/clutter/clutter-stage.h @@ -132,46 +132,45 @@ struct _ClutterPerspective GType clutter_perspective_get_type (void) G_GNUC_CONST; ClutterPerspective *clutter_perspective_copy (const ClutterPerspective *perspective); void clutter_perspective_free (ClutterPerspective *perspective); -GType clutter_stage_get_type (void) G_GNUC_CONST; +GType clutter_stage_get_type (void) G_GNUC_CONST; -ClutterActor *clutter_stage_get_default (void); - -void clutter_stage_set_color (ClutterStage *stage, - const ClutterColor *color); -void clutter_stage_get_color (ClutterStage *stage, - ClutterColor *color); +ClutterActor *clutter_stage_get_default (void); +void clutter_stage_set_color (ClutterStage *stage, + const ClutterColor *color); +void clutter_stage_get_color (ClutterStage *stage, + ClutterColor *color); void clutter_stage_set_perspectivex (ClutterStage *stage, - ClutterPerspective *perspective); + ClutterPerspective *perspective); void clutter_stage_get_perspectivex (ClutterStage *stage, - ClutterPerspective *perspective); + ClutterPerspective *perspective); void clutter_stage_set_perspective (ClutterStage *stage, - gfloat fovy, - gfloat aspect, - gfloat z_near, - gfloat z_far); + gfloat fovy, + gfloat aspect, + gfloat z_near, + gfloat z_far); void clutter_stage_get_perspective (ClutterStage *stage, gfloat *fovy, gfloat *aspect, gfloat *z_near, gfloat *z_far); -void clutter_stage_fullscreen (ClutterStage *stage); -void clutter_stage_unfullscreen (ClutterStage *stage); -void clutter_stage_show_cursor (ClutterStage *stage); -void clutter_stage_hide_cursor (ClutterStage *stage); +void clutter_stage_fullscreen (ClutterStage *stage); +void clutter_stage_unfullscreen (ClutterStage *stage); +void clutter_stage_show_cursor (ClutterStage *stage); +void clutter_stage_hide_cursor (ClutterStage *stage); -ClutterActor *clutter_stage_get_actor_at_pos (ClutterStage *stage, - gint x, - gint y); -GdkPixbuf * clutter_stage_snapshot (ClutterStage *stage, - gint x, - gint y, - gint width, - gint height); -gboolean clutter_stage_event (ClutterStage *stage, - ClutterEvent *event); +ClutterActor *clutter_stage_get_actor_at_pos (ClutterStage *stage, + gint x, + gint y); +GdkPixbuf * clutter_stage_snapshot (ClutterStage *stage, + gint x, + gint y, + gint width, + gint height); +gboolean clutter_stage_event (ClutterStage *stage, + ClutterEvent *event); -void clutter_stage_set_title (ClutterStage *stage, - const gchar *title); +void clutter_stage_set_title (ClutterStage *stage, + const gchar *title); G_CONST_RETURN gchar *clutter_stage_get_title (ClutterStage *stage); G_END_DECLS diff --git a/clutter/clutter-texture.c b/clutter/clutter-texture.c index 15f1adf71..61b68cb6b 100644 --- a/clutter/clutter-texture.c +++ b/clutter/clutter-texture.c @@ -149,7 +149,8 @@ un_pre_multiply_alpha (const guchar *data, return ret; } -static guchar* +#ifndef HAVE_COGL_GL +static guchar * rgb_to_bgr (const guchar *data, gboolean has_alpha, gint width, @@ -182,6 +183,7 @@ rgb_to_bgr (const guchar *data, return ret; } +#endif /* !HAVE_COGL_GL */ static int tile_dimension (int to_fill, @@ -1262,7 +1264,7 @@ clutter_texture_set_from_rgb_data (ClutterTexture *texture, #else /* GLES has no BGR format*/ copy_data = rgb_to_bgr (data, has_alpha, width, height, rowstride); -#endif +#endif /* HAVE_COGL_GL */ } if (flags & CLUTTER_TEXTURE_RGB_FLAG_PREMULT) diff --git a/clutter/clutter-vbox.c b/clutter/clutter-vbox.c index 9be7ac447..3c6cef70b 100644 --- a/clutter/clutter-vbox.c +++ b/clutter/clutter-vbox.c @@ -162,6 +162,15 @@ clutter_vbox_init (ClutterVBox *box) } +/** + * clutter_vbox_new: + * + * Creates a new vertical layout box. + * + * Return value: the newly created #ClutterVBox + * + * Since: 0.4 + */ ClutterActor * clutter_vbox_new (void) { diff --git a/configure.ac b/configure.ac index 855b7662d..c4553f4a5 100644 --- a/configure.ac +++ b/configure.ac @@ -258,7 +258,7 @@ AC_SUBST(CLUTTER_DEBUG_CFLAGS) dnl = GTK Doc check ======================================================== -GTK_DOC_CHECK([1.4]) +GTK_DOC_CHECK([1.6]) dnl = Manual ===============================================================