2008-01-18 Emmanuele Bassi <ebassi@openedhand.com>

* clutter/clutter-actor.h:
	* clutter/clutter-script.h:
	* clutter/clutter-stage.h:
	* clutter/clutter-units.h: Documentation fixes and additions.

ChangeLog

@@ -1,3 +1,10 @@
+2008-01-18  Emmanuele Bassi  <ebassi@openedhand.com>
+
+	* clutter/clutter-actor.h:
+	* clutter/clutter-script.h:
+	* clutter/clutter-stage.h:
+	* clutter/clutter-units.h: Documentation fixes and additions.
+
 2008-01-18  Emmanuele Bassi  <ebassi@openedhand.com>
 
 	* clutter.symbols: Add ClutterBehaviourOpacity accessors.

clutter/clutter-actor.h

@@ -138,12 +138,14 @@ struct _ClutterActor
 
 /**
  * ClutterActorClass:
- * @show: signal class handler for the ClutterActor::show signal
+ * @show: signal class handler for ClutterActor::show; it must chain
+ *   up to the parent's implementation
  * @show_all: virtual function for containers and composite actors, to
  *   determine which children should be shown when calling
  *   clutter_actor_show_all() on the actor. Defaults to calling
  *   clutter_actor_show().
- * @hide: signal class handler for the ClutterActor::hide signal
+ * @hide: signal class handler for ClutterActor::hide; it must chain
+ *   up to the parent's implementation
  * @hide_all: virtual function for containers and composite actors, to
  *   determine which children should be shown when calling
  *   clutter_actor_hide_all() on the actor. Defaults to calling
@@ -156,11 +158,26 @@ struct _ClutterActor
  * @request_coords: virtual function, used when setting the coordinates
  *   of an actor
  * @query_coords: virtual function, used when querying the actor for
- *   its coordinates
+ *   its coordinates; it must chain up to the parent's implementation
  * @parent_set: signal class closure for the ClutterActor::parent-set
- *   signal
+ * @destroy: signal class closure for ClutterActor::destroy
- * @destroy: signal class closure for the ClutterActor::destroy signal
+ * @pick: virtual functions, used to draw an outline of the actor with
- * @pick: virtual functions, used to draw an outline of the actor
+ *   the given colour
+ * @event: signal class closure for ClutterActor::event
+ * @button_press_event: signal class closure for
+ *   ClutterActor::button-press-event
+ * @button_release_event: signal class closure for
+ *   ClutterActor::button-release-event
+ * @scroll_event: signal class closure for ClutterActor::scroll-event
+ * @key_press_event: signal class closure for ClutterActor::key-press-event
+ * @key_release_event: signal class closure for
+ *   ClutterActor::key-release-event
+ * @motion_event: signal class closure for ClutterActor::motion-event
+ * @enter_event: signal class closure for ClutterActor::enter-event
+ * @leave_event: signal class closure for ClutterActor::leave-event
+ * @captured_event: signal class closure for ClutterActor::captured-event
+ * @focus_in: signal class closure for ClutterActor::focus-in
+ * @focus_out: signal class closure for ClutterActor::focus-out
  *
  * Base class for actors.
  */
@@ -212,10 +229,9 @@ struct _ClutterActorClass
   void     (* focus_in)             (ClutterActor         *actor);
   void     (* focus_out)            (ClutterActor         *actor);
 
-  gboolean shadable;
   /*< private >*/
   /* padding for future expansion */
-  gpointer _padding_dummy[31];
+  gpointer _padding_dummy[32];
 };
 
 GType                 clutter_actor_get_type         (void) G_GNUC_CONST;

clutter/clutter-script.h

@@ -68,6 +68,9 @@ typedef void (* ClutterScriptConnectFunc) (ClutterScript *script,
 
 /**
  * ClutterScriptError:
+ * @CLUTTER_SCRIPT_ERROR_INVALID_TYPE_FUNCTION: Type function not found
+ *   or invalid
+ * @CLUTTER_SCRIPT_ERROR_INVALID_PROPERTY: Property not found or invalid
  * @CLUTTER_SCRIPT_ERROR_INVALID_VALUE: Invalid value
  *
  * #ClutterScript error enumeration.

clutter/clutter-stage.h

@@ -57,11 +57,25 @@ G_BEGIN_DECLS
   (G_TYPE_INSTANCE_GET_CLASS ((obj), \
   CLUTTER_TYPE_STAGE, ClutterStageClass))
 
+/**
+ * CLUTTER_STAGE_WIDTH:
+ *
+ * Macro that evaluates to the current stage width
+ *
+ * Since: 0.2
+ */
 #define CLUTTER_STAGE_WIDTH() \
- clutter_actor_get_width (clutter_stage_get_default ())
+ (clutter_actor_get_width (clutter_stage_get_default ()))
 
+/**
+ * CLUTTER_STAGE_HEIGHT:
+ *
+ * Macro that evaluates to the current stage height
+ *
+ * Since: 0.2
+ */
 #define CLUTTER_STAGE_HEIGHT() \
- clutter_actor_get_height (clutter_stage_get_default ())
+ (clutter_actor_get_height (clutter_stage_get_default ()))
 
 typedef struct _ClutterPerspective  ClutterPerspective;
 typedef struct _ClutterFog          ClutterFog;

clutter/clutter-units.h

@@ -67,22 +67,56 @@ typedef gint32 ClutterUnit;
  * decide to change this relationship in the future.
  */
 
-#define CLUTTER_UNITS_FROM_DEVICE(x)     CLUTTER_UNITS_FROM_INT (x)
+#define CLUTTER_UNITS_FROM_INT(x)        CLUTTER_INT_TO_FIXED ((x))
-#define CLUTTER_UNITS_TO_DEVICE(x)       CLUTTER_UNITS_TO_INT (x)
+#define CLUTTER_UNITS_TO_INT(x)          CLUTTER_FIXED_TO_INT ((x))
 
-#define CLUTTER_UNITS_TMP_FROM_DEVICE(x) (x)
+#define CLUTTER_UNITS_FROM_FLOAT(x)      CLUTTER_FLOAT_TO_FIXED ((x))
-#define CLUTTER_UNITS_TMP_TO_DEVICE(x)   (x)
+#define CLUTTER_UNITS_TO_FLOAT(x)        CLUTTER_FIXED_TO_FLOAT ((x))
-
-#define CLUTTER_UNITS_FROM_INT(x)        CLUTTER_INT_TO_FIXED (x)
-#define CLUTTER_UNITS_TO_INT(x)          CFX_INT (x)
-
-#define CLUTTER_UNITS_FROM_FLOAT(x)      CLUTTER_FLOAT_TO_FIXED (x)
-#define CLUTTER_UNITS_TO_FLOAT(x)        CLUTTER_FIXED_TO_FLOAT (x)
 
 #define CLUTTER_UNITS_FROM_FIXED(x)      (x)
 #define CLUTTER_UNITS_TO_FIXED(x)        (x)
 
+/**
+ * CLUTTER_UNITS_FROM_DEVICE:
+ * @x: value in pixels
+ *
+ * Converts @x from pixels to #ClutterUnit<!-- -->s
+ *
+ * Since: 0.6
+ */
+#define CLUTTER_UNITS_FROM_DEVICE(x)     CLUTTER_UNITS_FROM_INT ((x))
+
+/**
+ * CLUTTER_UNITS_TO_DEVICE:
+ * @x: value in #ClutterUnit<!-- -->s
+ *
+ * Converts @x from #ClutterUnit<!-- -->s to pixels
+ *
+ * Since: 0.6
+ */
+#define CLUTTER_UNITS_TO_DEVICE(x)       CLUTTER_UNITS_TO_INT ((x))
+
+#define CLUTTER_UNITS_TMP_FROM_DEVICE(x) (x)
+#define CLUTTER_UNITS_TMP_TO_DEVICE(x)   (x)
+
+/**
+ * CLUTTER_UNITS_FROM_PANGO_UNIT:
+ * @x: value in Pango units
+ *
+ * Converts a value in Pango units to #ClutterUnit<!-- -->s
+ *
+ * Since: 0.6
+ */
 #define CLUTTER_UNITS_FROM_PANGO_UNIT(x) ((x) << 6)
+
+/**
+ * CLUTTER_UNITS_TO_PANGO_UNIT:
+ * @x: value in #ClutterUnit<!-- -->s
+ *
+ * Converts a value in #ClutterUnit<!-- -->s to Pango units
+ *
+ * Since: 0.6
+ */
 #define CLUTTER_UNITS_TO_PANGO_UNIT(x)   ((x) >> 6)
 
 #define CLUTTER_UNITS_FROM_STAGE_WIDTH_PERCENTAGE(x) \
@@ -97,12 +131,28 @@ typedef gint32 ClutterUnit;
 #define CLUTTER_UNITS_FROM_PARENT_HEIGHT_PERCENTAGE(a, x) \
   ((clutter_actor_get_heightu (clutter_actor_get_parent (a)) * x) / 100)
 
+/**
+ * CLUTTER_UNITS_FROM_MM:
+ * @x: a value in millimeters
+ *
+ * Converts a value in millimeters into #ClutterUnit<!-- -->s
+ *
+ * Since: 0.6
+ */
 #define CLUTTER_UNITS_FROM_MM(x) \
   (CLUTTER_UNITS_FROM_FLOAT ((((x) * clutter_stage_get_resolution ((ClutterStage *) clutter_stage_get_default ())) / 25.4)))
 
 #define CLUTTER_UNITS_FROM_MMX(x) \
   (CFX_DIV (CFX_MUL ((x), clutter_stage_get_resolutionx ((ClutterStage *) clutter_stage_get_default ())), 0x196666))
 
+/**
+ * CLUTTER_UNITS_FROM_POINTS:
+ * @x: a value in typographic points
+ *
+ * Converts a value in typographic points into #ClutterUnit<!-- -->s
+ *
+ * Since: 0.6
+ */
 #define CLUTTER_UNITS_FROM_POINTS(x) \
   CLUTTER_UNITS_FROM_FLOAT ((((x) * clutter_stage_get_resolution ((ClutterStage *) clutter_stage_get_default ())) / 72.0))