2007-11-23 Emmanuele Bassi <ebassi@openedhand.com>

* clutter/clutter-actor.c:
	* clutter/clutter-alpha.c:
	* clutter/clutter-effect.c:
	* clutter/clutter-event.c:
	* clutter/clutter-event.h:
	* clutter/clutter-group.h:
	* clutter/clutter-model.c:,
	* clutter/clutter-script.c:
	* clutter/clutter-scriptable.h:
	* clutter/clutter-stage.c: Documentation fixes.

	* clutter/clutter-score.c: Fix implementation.

ChangeLog

@@ -1,3 +1,18 @@
+2007-11-23  Emmanuele Bassi  <ebassi@openedhand.com>
+
+	* clutter/clutter-actor.c:
+	* clutter/clutter-alpha.c:
+	* clutter/clutter-effect.c:
+	* clutter/clutter-event.c:
+	* clutter/clutter-event.h:
+	* clutter/clutter-group.h:
+	* clutter/clutter-model.c:,
+	* clutter/clutter-script.c:
+	* clutter/clutter-scriptable.h:
+	* clutter/clutter-stage.c: Documentation fixes.
+
+	* clutter/clutter-score.c: Fix implementation.
+
 2007-11-23  Emmanuele Bassi  <ebassi@openedhand.com>
 
 	* clutter/x11/clutter-stage-x11.c: Chain up the hide and show

clutter/clutter-actor.c

@@ -62,6 +62,62 @@
  * </orderedlist>
  */
 
+/**
+ * CLUTTER_ACTOR_IS_MAPPED:
+ * @e: a #ClutterActor
+ *
+ * Evaluates to %TRUE if the %CLUTTER_ACTOR_MAPPED flag is set.
+ *
+ * Since: 0.2
+ */
+
+/**
+ * CLUTTER_ACTOR_IS_REALIZED:
+ * @e: a #ClutterActor
+ *
+ * Evaluates to %TRUE if the %CLUTTER_ACTOR_REALIZED flag is set.
+ *
+ * Since: 0.2
+ */
+
+/**
+ * CLUTTER_ACTOR_IS_VISIBLE:
+ * @e: a #ClutterActor
+ *
+ * Evaluates to %TRUE if the actor is both realized and mapped.
+ *
+ * Since: 0.2
+ */
+
+/**
+ * CLUTTER_ACTOR_IS_REACTIVE:
+ * @e: a #ClutterActor
+ *
+ * Evaluates to %TRUE if the %CLUTTER_ACTOR_REACTIVE flag is set.
+ *
+ * Since: 0.6
+ */
+
+/**
+ * CLUTTER_ACTOR_SET_FLAGS:
+ * @e: a #ClutterActor
+ * @f: the flags to set
+ *
+ * Sets flags on the given #ClutterActor
+ *
+ * Since: 0.2
+ */
+
+/**
+ * CLUTTER_ACTOR_UNSET_FLAGS:
+ * @e: a #ClutterActor
+ * @f: the flags to unset
+ *
+ * Unsets flags on the given #ClutterActor
+ *
+ * Since: 0.2
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif

clutter/clutter-alpha.c

@@ -397,6 +397,14 @@ clutter_alpha_new_full (ClutterTimeline  *timeline,
   return retval;
 }
 
+/**
+ * CLUTTER_ALPHA_RAMP_INC:
+ *
+ * Convenience symbol for clutter_ramp_inc_func().
+ *
+ * Since: 0.2
+ */
+
 /**
  * clutter_ramp_inc_func:
  * @alpha: a #ClutterAlpha
@@ -424,6 +432,14 @@ clutter_ramp_inc_func (ClutterAlpha *alpha,
   return (current_frame_num * CLUTTER_ALPHA_MAX_ALPHA) / n_frames;
 }
 
+/**
+ * CLUTTER_ALPHA_RAMP_DEC:
+ *
+ * Convenience symbol for clutter_ramp_dec_func().
+ *
+ * Since: 0.2
+ */
+
 /**
  * clutter_ramp_dec_func:
  * @alpha: a #ClutterAlpha
@@ -453,6 +469,14 @@ clutter_ramp_dec_func (ClutterAlpha *alpha,
          / n_frames;
 }
 
+/**
+ * CLUTTER_ALPHA_RAMP:
+ *
+ * Convenience symbol for clutter_ramp_func().
+ *
+ * Since: 0.2
+ */
+
 /**
  * clutter_ramp_func:
  * @alpha: a #ClutterAlpha
@@ -574,6 +598,14 @@ sinc_func (ClutterAlpha *alpha,
 }
 #endif
 
+/**
+ * CLUTTER_ALPHA_SINE:
+ *
+ * Convenience symbol for clutter_sine_func().
+ *
+ * Since: 0.2
+ */
+
 /**
  * clutter_sine_func:
  * @alpha: a #ClutterAlpha
@@ -598,6 +630,14 @@ clutter_sine_func (ClutterAlpha *alpha,
 #endif
 }
 
+/**
+ * CLUTTER_ALPHA_SINE_INC:
+ *
+ * Convenience symbol for clutter_sine_inc_func().
+ *
+ * Since: 0.2
+ */
+
 /**
  * clutter_sine_inc_func:
  * @alpha: a #ClutterAlpha
@@ -632,6 +672,14 @@ clutter_sine_inc_func (ClutterAlpha *alpha,
   return ((guint32)sine) >> CFX_Q;
 }
 
+/**
+ * CLUTTER_ALPHA_SINE_DEC:
+ *
+ * Convenience symbol for clutter_sine_dec_func().
+ *
+ * Since: 0.2
+ */
+
 /**
  * clutter_sine_dec_func:
  * @alpha: a #ClutterAlpha
@@ -666,6 +714,14 @@ clutter_sine_dec_func (ClutterAlpha *alpha,
   return ((guint32)sine) >> CFX_Q;
 }
 
+/**
+ * CLUTTER_ALPHA_SINE_HALF:
+ *
+ * Convenience symbol for clutter_sine_half_func().
+ *
+ * Since: 0.4
+ */
+
 /**
  * clutter_sine_half_func:
  * @alpha: a #ClutterAlpha
@@ -700,6 +756,14 @@ clutter_sine_half_func (ClutterAlpha *alpha,
   return ((guint32)sine) >> CFX_Q;
 }
 
+/**
+ * CLUTTER_ALPHA_SQUARE:
+ *
+ * Convenience symbol for clutter_square_func().
+ *
+ * Since: 0.4
+ */
+
 /**
  * clutter_square_func:
  * @alpha: a #ClutterAlpha
@@ -728,6 +792,13 @@ clutter_square_func (ClutterAlpha *alpha,
                                               : 0;
 }
 
+/**
+ * CLUTTER_ALPHA_SMOOTHSTEP_INC:
+ *
+ * Convenience symbol for clutter_smoothstep_inc_func().
+ *
+ * Since: 0.4
+ */
 
 /**
  * clutter_smoothstep_inc_func:
@@ -776,6 +847,14 @@ clutter_smoothstep_inc_func (ClutterAlpha  *alpha,
   return CFX_INT (r * CLUTTER_ALPHA_MAX_ALPHA);
 }
 
+/**
+ * CLUTTER_ALPHA_SMOOTHSTEP_DEC:
+ *
+ * Convenience symbol for clutter_smoothstep_dec_func().
+ *
+ * Since: 0.4
+ */
+
 /**
  * clutter_smoothstep_dec_func:
  * @alpha: a #ClutterAlpha
@@ -795,6 +874,14 @@ clutter_smoothstep_dec_func (ClutterAlpha  *alpha,
   return CLUTTER_ALPHA_MAX_ALPHA - clutter_smoothstep_inc_func (alpha, dummy);
 }
 
+/**
+ * CLUTTER_ALPHA_EXP_INC:
+ *
+ * Convenience symbol for clutter_exp_inc_func()
+ *
+ * Since: 0.4
+ */
+
 /**
  * clutter_exp_inc_func:
  * @alpha: a #ClutterAlpha
@@ -838,6 +925,13 @@ clutter_exp_inc_func (ClutterAlpha *alpha,
   return result;
 }
 
+/**
+ * CLUTTER_ALPHA_EXP_DEC:
+ *
+ * Convenience symbold for clutter_exp_dec_func().
+ *
+ * Since: 0.4
+ */
 
 /**
  * clutter_exp_dec_func:

clutter/clutter-effect.c

@@ -753,7 +753,7 @@ clutter_effect_scale (ClutterEffectTemplate     *template_,
  * @actor: a #ClutterActor to apply the effect to.
  * @axis: axis of rotation
  * @angle: final angle to apply to actor
- * @center_z: position on Z axis to rotate about.
+ * @center_x: position on X axis to rotate about.
  * @center_y: position on Y axis to rotate about.
  * @center_z: position on Z axis to rotate about.
  * @direction: a #ClutterRotateDirection for the rotation.

clutter/clutter-event.c

@@ -168,6 +168,8 @@ clutter_event_get_coords (ClutterEvent *event,
  * Retrieves the source #ClutterActor the event originated from, or
  * NULL if the event has no source.
  *
+ * Return value: a #ClutterActor
+ *
  * Since: 0.6
  */
 ClutterActor*

clutter/clutter-event.h

@@ -30,7 +30,23 @@
 #include <clutter/clutter-types.h>
 
 #define CLUTTER_TYPE_EVENT	(clutter_event_get_type ())
+
+/**
+ * CLUTTER_PRIORITY_EVENTS:
+ *
+ * Priority for event handling.
+ *
+ * Since: 0.4
+ */
 #define CLUTTER_PRIORITY_EVENTS (G_PRIORITY_DEFAULT)
+
+/**
+ * CLUTTER_CURRENT_TIME:
+ *
+ * Default value for "now".
+ *
+ * Since: 0.4
+ */
 #define CLUTTER_CURRENT_TIME    0L
 
 G_BEGIN_DECLS

clutter/clutter-group.h

@@ -102,8 +102,6 @@ void          clutter_group_add_many_valist  (ClutterGroup    *group,
                                               va_list          var_args);
 void          clutter_group_remove           (ClutterGroup    *group,
                                               ClutterActor    *actor);
-ClutterActor *clutter_group_find_child_by_id (ClutterGroup    *self,
-					      guint            id);
 void          clutter_group_raise            (ClutterGroup    *self,
 					      ClutterActor    *actor, 
 					      ClutterActor    *sibling);

clutter/clutter-model.c

@@ -916,8 +916,10 @@ clutter_model_get_last_iter (ClutterModel *model)
  * clutter_model_get_n_rows:
  * @model: a #ClutterModel
  *
- * Return value: The length of the @model. If there is a filter set, then the
+ * Retrieves the number of rows inside @model.
- * length of the filtered @model is returned.
+ *
+ * Return value: The length of the @model. If there is a filter set, then
+ *   thelength of the filtered @model is returned.
  *
  * Since 0.6
  */
@@ -974,6 +976,7 @@ clutter_model_set_sorting_column (ClutterModel *model,
       g_warning ("%s: Invalid column id value %d\n", G_STRLOC, column);
       return;
     }
+
   priv->sort_column = column;
 
   _model_sort (model);
@@ -984,19 +987,18 @@ clutter_model_set_sorting_column (ClutterModel *model,
  * clutter_model_get_sorting_column:
  * @model: a #ClutterModelIter
  *
- * Return value: The column number that the @model sorts.
+ * Retrieves the number of column used for sorting the @model.
+ *
+ * Return value: a column number
  *
  * Since 0.6
  */
 guint              
 clutter_model_get_sorting_column (ClutterModel *model)
 {
-  ClutterModelPrivate *priv;
-
   g_return_val_if_fail (CLUTTER_IS_MODEL_ITER (model), 0);
-  priv = model->priv;
 
-  return priv->sort_column;
+  return model->priv->sort_column;
 }
 
 /**
@@ -1925,7 +1927,10 @@ clutter_model_iter_set_value (ClutterModelIter *iter,
  * clutter_model_iter_is_first:
  * @iter: a #ClutterModelIter
  *
- * Return value: #TRUE if @iter is the first iter in the filtered model.
+ * Gets whether the current iterator is at the beginning of the model
+ * to which it belongs.
+ *
+ * Return value: #TRUE if @iter is the first iter in the filtered model
  *
  * Since 0.6
  */
@@ -1946,6 +1951,9 @@ clutter_model_iter_is_first (ClutterModelIter *iter)
  * clutter_model_iter_is_last:
  * @iter: a #ClutterModelIter
  * 
+ * Gets whether the iterator is at the end of the model to which it
+ * belongs.
+ *
  * Return value: #TRUE if @iter is the last iter in the filtered model.
  *
  * Since 0.6

clutter/clutter-score.c

@@ -35,7 +35,7 @@
  *   {
  *     Timeline *base;
  *     GList    *next_timelines; - to start on completion of base,
- *                                 (points to score entrys)
+ *                                 (points to score entries)
  *     Callback  id;
  *     delay
  *   }
@@ -48,6 +48,8 @@
  * @short_description: Sequencing multiple #ClutterTimelines in order
  *
  * #ClutterScore is a base class for sequencing multiple timelines in order.
+ *
+ * #ClutterScore is available since Clutter 0.6
  */
 
 #ifdef HAVE_CONFIG_H
@@ -150,6 +152,9 @@ clutter_score_get_property (GObject    *object,
 static void
 clutter_score_finalize (GObject *object)
 {
+  ClutterScorePrivate *priv = CLUTTER_SCORE (object)->priv;
+
+  g_hash_table_destroy (priv->running_timelines);
   G_OBJECT_CLASS (clutter_score_parent_class)->finalize (object);
 }
 
@@ -161,11 +166,6 @@ clutter_score_dispose (GObject *object)
 
   priv = self->priv;
 
-  if (priv != NULL)
-    {
-
-    }
-
   G_OBJECT_CLASS (clutter_score_parent_class)->dispose (object);
 }
 
@@ -254,12 +254,9 @@ clutter_score_set_loop (ClutterScore *score,
 
   if (score->priv->loop != loop)
     {
-      g_object_ref (score);
-
       score->priv->loop = loop;
 
       g_object_notify (G_OBJECT (score), "loop");
-      g_object_unref (score);
     }
 }
 
@@ -361,9 +358,9 @@ on_foreach_running_timeline_start (gpointer key,
  * clutter_score_start:
  * @score: A #ClutterScore
  *
- * Query state of a #ClutterScore instance.
+ * Starts the score.
  *
- * Return Value: TRUE if score is currently playing, FALSE if not.
+ * Since: 0.6
  */
 void
 clutter_score_start (ClutterScore *score)
@@ -536,7 +533,6 @@ clutter_score_append (ClutterScore    *score,
  * @timeline: A #ClutterTimeline
  *
  * Adds a new initial timeline to start when the score is started.
- *
  */
 void
 clutter_score_add (ClutterScore    *score,
@@ -559,11 +555,11 @@ clutter_score_add (ClutterScore    *score,
 }
 
 static void
-remove_entrys (GSList *list)
+remove_entries (GSList *list)
 {
   GSList *item;
 
-  if (list == NULL)
+  if (!list)
     return;
 
   for (item = list; item != NULL; item = item->next)
@@ -573,7 +569,7 @@ remove_entrys (GSList *list)
       g_object_unref (entry->timeline);
 
       if (entry->child_entries)
-	remove_entrys (entry->child_entries);
+	remove_entries (entry->child_entries);
 
       g_slist_free (entry->child_entries);
       g_free(entry);
@@ -588,22 +584,32 @@ clutter_score_remove (ClutterScore    *score,
 
 }
 
+/**
+ * clutter_score_remove_all:
+ * @score: a #ClutterScore
+ *
+ * Removes all the timelines inside @score.
+ *
+ * Since: 0.6
+ */
 void
 clutter_score_remove_all (ClutterScore *score)
 {
   clutter_score_stop (score);
-  remove_entrys (score->priv->entries);
+  remove_entries (score->priv->entries);
 }
 
 /**
  * clutter_score_new:
  *
- * Create a new #ClutterScore instance.
+ * Creates a new #ClutterScore.
  *
- * Return Value: a new #ClutterScore
+ * Return value: the newly created #ClutterScore
+ *
+ * Since: 0.6
  */
 ClutterScore *
-clutter_score_new ()
+clutter_score_new (void)
 {
   return g_object_new (CLUTTER_TYPE_SCORE,  NULL);
 }

clutter/clutter-script.c

@@ -1815,7 +1815,7 @@ clutter_script_unmerge_objects (ClutterScript *script,
 }
 
 /**
- * clutter_script_ensure_object:
+ * clutter_script_ensure_objects:
  * @script: a #ClutterScript
  *
  * Ensure that every object defined inside @script is correctly

clutter/clutter-scriptable.h

@@ -57,8 +57,10 @@ typedef struct _ClutterScriptableIface          ClutterScriptableIface;
  */
 struct _ClutterScriptableIface
 {
+  /*< private >*/
   GTypeInterface g_iface;
 
+  /*< public >*/
   void         (* set_id)              (ClutterScriptable *scriptable,
                                         const gchar       *name);
   const gchar *(* get_id)              (ClutterScriptable *scriptable);

clutter/clutter-stage.c

@@ -971,6 +971,17 @@ on_key_focused_weak_notify (gpointer data,
   clutter_stage_set_key_focus (stage, NULL);
 }
 
+/**
+ * clutter_stage_set_key_focus:
+ * @stage: the #ClutterStage
+ * @actor: the actor to set key focus to, or %NULL
+ *
+ * Sets the key focus on @actor. An actor with key focus will receive
+ * all the key events. If @actor is %NULL, the stage will receive
+ * focus.
+ *
+ * Since: 0.6
+ */
 void
 clutter_stage_set_key_focus (ClutterStage *stage,
 			     ClutterActor *actor)
@@ -1010,6 +1021,16 @@ clutter_stage_set_key_focus (ClutterStage *stage,
     g_signal_emit_by_name (stage, "focus-in");
 }
 
+/**
+ * clutter_stage_get_key_focus:
+ * @stage: the #ClutterStage
+ *
+ * Retrieves the actor that is currently under key focus.
+ *
+ * Return value: the actor with key focus, or the stage
+ *
+ * Since: 0.6
+ */
 ClutterActor *
 clutter_stage_get_key_focus (ClutterStage *stage)
 {

doc/reference/ChangeLog

@@ -1,3 +1,7 @@
+2007-11-23  Emmanuele Bassi  <ebassi@openedhand.com>
+
+	* clutter-sections.txt: Add unused API.
+
 2007-11-21  Emmanuele Bassi  <ebassi@openedhand.com>
 
 	* clutter-sections.txt: Add the new ClutterStage fog API.

doc/reference/clutter-sections.txt

@@ -197,7 +197,6 @@ clutter_group_get_nth_child
 clutter_group_raise
 clutter_group_lower
 clutter_group_sort_depth_order
-clutter_group_find_child_by_id
 <SUBSECTION Standard>
 CLUTTER_GROUP
 CLUTTER_IS_GROUP
@@ -489,6 +488,7 @@ CLUTTER_STAGE_CLASS
 CLUTTER_IS_STAGE_CLASS
 CLUTTER_STAGE_GET_CLASS
 CLUTTER_TYPE_PERSPECTIVE
+CLUTTER_TYPE_FOG
 <SUBSECTION Private>
 ClutterStagePrivate
 clutter_stage_get_type
@@ -1070,11 +1070,10 @@ clutter_effect_template_set_timeline_clone
 ClutterEffectCompleteFunc
 clutter_effect_fade
 clutter_effect_move
+clutter_effect_path
 clutter_effect_scale
 clutter_effect_depth
-clutter_effect_rotate_x
+clutter_effect_rotate
-clutter_effect_rotate_y
-clutter_effect_rotate_z
 
 <SUBSECTION Standard>
 CLUTTER_TYPE_EFFECT_TEMPLATE

tests/test-events.c

@@ -20,12 +20,16 @@ blue_button_cb (ClutterActor    *actor,
 
   stage = clutter_stage_get_default ();
 
+#if 0
   if (IsFullScreen)
     IsFullScreen = FALSE;
   else
     IsFullScreen = TRUE;
 
   g_object_set (stage, "fullscreen", IsFullScreen, NULL);
+#endif
+
+  clutter_actor_hide (stage);
 
   return FALSE;
 }
@@ -168,6 +172,7 @@ main (int argc, char *argv[])
 
 
   stage = clutter_stage_get_default ();
+  clutter_stage_fullscreen (stage);
   g_signal_connect (stage, "event", G_CALLBACK (input_cb), "stage");
 
   g_signal_connect (stage, "fullscreen",