+2008-02-15 Chris Lord <chris@openedhand.com>
+
+ * clutter/clutter-actor.c:
+ * clutter/clutter-container.c:
+ * clutter/clutter-media.c:
+ * clutter/clutter-rectangle.c:
+ * clutter/clutter-stage.c: (clutter_stage_class_init):
+ * clutter/clutter-stage.h:
+ * clutter/clutter-texture.c:
+ * doc/reference/clutter-docs.sgml:
+ Fix more documentation
+
2008-02-15 Emmanuele Bassi <ebassi@openedhand.com>
* clutter/clutter-actor.[ch]:
* clutter_actor_show
* @self: A #ClutterActor
*
- * Flags an actor to be displayed. An actor not shown will not
+ * Flags an actor to be displayed. An actor that isn't shown will not
* be rendered on the stage.
*/
void
* clutter_actor_hide
* @self: A #ClutterActor
*
- * Flags an actor to be hidden. An actor not shown will not be
+ * Flags an actor to be hidden. A hidden actor will not be
* rendered on the stage.
*/
void
*
* Transforms @point in coordinates relative to the actor
* into screen-relative coordinates with the current actor
- * tranformation (i.e. scale, rotation etc)
+ * transformation (i.e. scale, rotation, etc)
*
* Since: 0.4
**/
* @x: New left position of actor in #ClutterUnit<!-- -->s
* @y: New top position of actor in #ClutterUnit<!-- -->s
*
- * Sets the actors position in #ClutterUnit<!-- -->s relative to any
+ * Sets the actor's position in #ClutterUnit<!-- -->s relative to any
* parent actor.
*
* Since: 0.6
* @dx: Distance to move Actor on X axis.
* @dy: Distance to move Actor on Y axis.
*
- * Moves an actor by the specified distance relative to
+ * Moves an actor by the specified distance relative to its
* current position in pixels.
*
* Since: 0.2
* @dx: Distance to move Actor on X axis, in #ClutterUnit<!-- -->s.
* @dy: Distance to move Actor on Y axis, in #ClutterUnit<!-- -->s.
*
- * Moves an actor by the specified distance relative to the current
+ * Moves an actor by the specified distance relative to its current
* position.
*
* Since: 0.6
* @width: New width of actor in #ClutterUnit<!-- -->s, or -1
* @height: New height of actor in #ClutterUnit<!-- -->s, or -1
*
- * Sets the actors size in #ClutterUnit<!-- -->s. If @width and/or @height
- * are -1 the actor will assume the same size of its bounding box.
+ * Sets the actor's size in #ClutterUnit<!-- -->s. If @width and/or @height
+ * are -1 the actor will assume the same size as its bounding box.
*
* Since: 0.6
*/
* @width: return location for the width, or %NULL.
* @height: return location for the height, or %NULL.
*
- * Gets the size of an actor in pixels ignoring any scaling factors.
+ * Gets the size of an actor in pixels, ignoring any scaling factors.
*
* Since: 0.2
*/
* @width: return location for the width, or %NULL
* @height: return location for the height, or %NULL
*
- * Gets the size of an actor in #ClutterUnit<!-- -->s ignoring any scaling
+ * Gets the size of an actor in #ClutterUnit<!-- -->s, ignoring any scaling
* factors.
*
* Since: 0.6
/**
* clutter_actor_set_heightu
* @self: A #ClutterActor
- * @height: Requested new height for actor, in #ClutterUnit<!-- -->s
+ * @height: Requested new height for the actor, in #ClutterUnit<!-- -->s
*
* Requests a new height for the actor
*
/**
* clutter_actor_set_xu:
* @self: a #ClutterActor
- * @x: the actor's position on the X axis in #ClutterUnit<!-- -->s
+ * @x: the actor's position on the X axis, in #ClutterUnit<!-- -->s
*
* Sets the actor's X coordinate, relative to its parent.
*
/**
* clutter_actor_set_yu:
* @self: a #ClutterActor
- * @y: the actor's position on the Y axis in #ClutterUnit<!-- -->s
+ * @y: the actor's position on the Y axis, in #ClutterUnit<!-- -->s
*
* Sets the actor's Y coordinate, relative to its parent.
*
* Retrieves the actor's X coordinate, relative to any parent.
*
* Return value: the X coordinate, in pixels, ignoring any
- * tranformation (i.e. scaling, rotation).
+ * transformation (i.e. scaling, rotation).
*/
gint
clutter_actor_get_x (ClutterActor *self)
* in #ClutterUnit<!-- -->s.
*
* Return value: the X coordinate, in #ClutterUnit<!-- -->s, ignoring
- * any tranformation (i.e. scaling, rotation).
+ * any transformation (i.e. scaling, rotation).
*
* Since: 0.6
*/
* Retrieves the actor's Y coordinate, relative to any parent.
*
* Return value: the Y coordinate, in pixels, ignoring any
- * tranformation (i.e. scaling, rotation).
+ * transformation (i.e. scaling, rotation).
*/
gint
clutter_actor_get_y (ClutterActor *self)
/**
* clutter_actor_set_opacity:
* @self: A #ClutterActor
- * @opacity: New opacity value for actor.
+ * @opacity: New opacity value for the actor.
*
- * Sets the actors opacity, with zero being completely transparent and
- * 255 (0xff) as fully opaque.
+ * Sets the actor's opacity, with zero being completely transparent and
+ * 255 (0xff) being fully opaque.
*/
void
clutter_actor_set_opacity (ClutterActor *self,
* clutter_actor_get_opacity:
* @self: A #ClutterActor
*
- * Retrieves the actors opacity.
+ * Retrieves the actor's opacity.
*
* Return value: The actor opacity value.
*/
*
* Retrieves the name of @self.
*
- * Return value: the name of the actor or %NULL. The returned string is
+ * Return value: the name of the actor, or %NULL. The returned string is
* owned by the actor and should not be modified or freed.
*/
G_CONST_RETURN gchar *
*
* Retrieves the unique id for @self.
*
- * Return value: Globally unique value for object instance.
+ * Return value: Globally unique value for this object instance.
*
* Since: 0.6
*/
/**
* clutter_actor_set_depthu:
* @self: a #ClutterActor
- * @depth: Z co-ord in #ClutterUnit
+ * @depth: Z co-ordinate, in #ClutterUnit<!-- -->s
*
- * Sets the Z co-ordinate of @self to @depth in #ClutterUnit, the Units of
- * which are dependant on the perspective setup.
+ * Sets the Z co-ordinate of @self to @depth in #ClutterUnit<!-- -->s, the
+ * units of which are dependant on the perspective setup.
*/
void
clutter_actor_set_depthu (ClutterActor *self,
*
* Retrieves the depth of @self.
*
- * Return value: the depth of a #ClutterActor
+ * Return value: the depth of the actor
*/
gint
clutter_actor_get_depth (ClutterActor *self)
*
* Retrieves the depth of @self.
*
- * Return value: the depth of a #ClutterActor in #ClutterUnit
+ * Return value: the depth of the actor, in #ClutterUnit<!-- -->s
*
* Since: 0.6
*/
* clutter_actor_remove_clip
* @self: A #ClutterActor
*
- * Removes clip area in pixels from @self.
+ * Removes clip area from @self.
*/
void
clutter_actor_remove_clip (ClutterActor *self)
* clutter_actor_has_clip:
* @self: a #ClutterActor
*
- * Gets whether the actor has a clip set or not.
+ * Determines whether the actor has a clip area set or not.
*
- * Return value: %TRUE if the actor has a clip set.
+ * Return value: %TRUE if the actor has a clip area set.
*
* Since: 0.1.1
*/
* Sets the parent of @self to @parent. The opposite function is
* clutter_actor_unparent().
*
- * This function should not be used by applications but by custom
- * 'composite' actor sub classes.
+ * This function should not be used by applications, but by custom
+ * 'composite' actor subclasses.
*/
void
clutter_actor_set_parent (ClutterActor *self,
* @new_parent: the new #ClutterActor parent
*
* This function resets the parent actor of @self. It is
- * logically equivalent to calling clutter_actory_unparent()
+ * logically equivalent to calling clutter_actor_unparent()
* and clutter_actor_set_parent().
*
* Since: 0.2
* @anchor_x: X coordinate of the anchor point, in #ClutterUnit<!-- -->s
* @anchor_y: Y coordinate of the anchor point, in #ClutterUnit<!-- -->s
*
- * Sets an anchor point for the @self. The anchor point is a point in the
+ * Sets an anchor point for @self. The anchor point is a point in the
* coordinate space of an actor to which the actor position within its
* parent is relative; the default is (0, 0), i.e. the top-left corner
* of the actor.
* @anchor_x: X coordinate of the anchor point
* @anchor_y: Y coordinate of the anchor point
*
- * Sets an anchor point for the @actor, and adjusts the actor postion so that
+ * Sets an anchor point for the actor, and adjusts the actor postion so that
* the relative position of the actor toward its parent remains the same.
*
* Since: 0.6
* @self: a #ClutterActor
* @gravity: #ClutterGravity.
*
- * Sets an anchor point of the actor based on the given gravity, adjusting the
- * actor postion so that its relative position within its parent remainst
+ * Sets an anchor point on the actor based on the given gravity, adjusting the
+ * actor postion so that its relative position within its parent remains
* unchanged.
*
* Since: 0.6
* @self: a #ClutterActor
* @gravity: #ClutterGravity.
*
- * Sets an anchor point the actor based on the given gravity (this is a
+ * Sets an anchor point on the actor, based on the given gravity (this is a
* convenience function wrapping clutter_actor_set_anchor_point()).
*
* Since: 0.6
* @y_out: return location for the unprojected y coordinance, in
* #ClutterUnit<!-- -->s
*
- * The function translates point with screen coordinates (@x, @y) to
- * coordinates relative to the actor, i.e. it can be used to translate
- * screen events from global screen coordinates into local coordinates.
+ * This function translates screen coordinates (@x, @y) to
+ * coordinates relative to the actor. For example, it can be used to translate
+ * screen events from global screen coordinates into actor-local coordinates.
*
* The conversion can fail, notably if the transform stack results in the
* actor being projected on the screen as a mere line.
*
* Sets the #ClutterShader to be used when rendering @self.
* If @shader is %NULL it will unset any currently set shader
- * for an actor.
+ * for the actor.
*
* Return value: %TRUE if the shader was successfully applied
*
* @actor: the first #ClutterActor to add
*
* Adds a #ClutterActor to @container. This function will emit the
- * "actor-added" signal is emitted. The actor should be parented to
+ * "actor-added" signal. The actor should be parented to
* @container. You cannot add a #ClutterActor to more than one
* #ClutterContainer.
*
* clutter_container_raise_child:
* @container: a #ClutterContainer
* @actor: the actor to raise
- * @sibling: the sibling to raise to, or %NULL to raise at the top
+ * @sibling: the sibling to raise to, or %NULL to raise to the top
*
- * Raises @actor at @sibling level, in the depth ordering.
+ * Raises @actor to @sibling level, in the depth ordering.
*
* Since: 0.6
*/
* clutter_container_lower_child:
* @container: a #ClutterContainer
* @actor: the actor to raise
- * @sibling: the sibling to lower to, or %NULL to lower at the bottom
+ * @sibling: the sibling to lower to, or %NULL to lower to the bottom
*
- * Lowers @actor at @sibling level, in the depth ordering.
+ * Lowers @actor to @sibling level, in the depth ordering.
*
* Since: 0.6
*/
* clutter_container_sort_depth_order:
* @container: a #ClutterContainer
*
- * Sorts a container children using their depth. This function should not
+ * Sorts a container's children using their depth. This function should not
* be normally used by applications.
*
* Since: 0.6
/**
* clutter_media_set_uri:
* @media: #ClutterMedia object
- * @uri: Uri
+ * @uri: URI
*
- * Sets the uri of @media to @uri.
+ * Sets the URI of @media to @uri.
*/
void
clutter_media_set_uri (ClutterMedia *media,
* clutter_media_get_playing:
* @media: A #ClutterMedia object
*
- * Retrieves the state of @media.
+ * Retrieves the playing status of @media.
*
- * Return value: TRUE if playing, FALSE if stopped.
+ * Return value: %TRUE if playing, %FALSE if stopped.
*/
gboolean
clutter_media_get_playing (ClutterMedia *media)
*
* Retrieves whether @media is seekable or not.
*
- * Return value: TRUE if @media can seek, FALSE otherwise.
+ * Return value: %TRUE if @media can seek, %FALSE otherwise.
*/
gboolean
clutter_media_get_can_seek (ClutterMedia *media)
* SECTION:clutter-rectangle
* @short_description: An actor that displays simple rectangles.
*
- * #ClutterRectangle is an Actor which draws simple filled rectangles.
+ * #ClutterRectangle is a #ClutterActor which draws simple filled rectangles.
*/
#ifdef HAVE_CONFIG_H
#include "config.h"
* @color: a #ClutterColor
*
* Creates a new #ClutterActor with a rectangular shape
- * and with @color.
+ * and of the given @color.
*
* Return value: a new #ClutterActor
*/
/**
* ClutterStage:user-resizable:
*
- * Whether the stage is able to be resized via user interaction.
+ * Whether the stage is resizable via user interaction.
*
* Since: 0.4
*/
/**
* ClutterStage:title:
*
- * The stages title - usually displayed in stage windows title decorations.
+ * The stage's title - usually displayed in stage windows title decorations.
*
* Since: 0.4
*/
/**
* ClutterStage:use-fog:
*
- * Whether the stage should use a linear GL "fog" for creating the
- * depth-cueing effect to enhance the perception of depth by fading
- * actors farther from the viewpoing.
+ * Whether the stage should use a linear GL "fog" in creating the
+ * depth-cueing effect, to enhance the perception of depth by fading
+ * actors farther from the viewpoint.
*
* Since: 0.6
*/
* ClutterStage::activate
* @stage: the stage which was activated
*
- * The ::activate signal is emitted when the stage recieves key focus
+ * The ::activate signal is emitted when the stage receives key focus
* from the underlying window system.
*
* Since: 0.6
* @stage: A #ClutterStage
* @perspective: A #ClutterPerspective
*
- * Set the stage perspective.
+ * Set the stage perspective. This is the fixed point version of
+ * clutter_stage_set_perspective().
**/
void
clutter_stage_set_perspectivex (ClutterStage *stage,
* @stage: A #ClutterStage
* @perspective: return location for a #ClutterPerspective
*
- * Retrieves the stage perspective.
+ * Retrieves the stage perspective. This is the fixed point version of
+ * clutter_stage_get_perspective().
*/
void
clutter_stage_get_perspectivex (ClutterStage *stage,
/**
* clutter_stage_set_user_resizable:
* @stage: a #ClutterStage
- * @resizable: whether if the stage should be user resizable.
+ * @resizable: whether the stage should be user resizable.
*
- * Sets if the stage is able to be resized by user interaction (i.e via
+ * Sets if the stage is resizable by user interaction (e.g. via
* window manager controls)
*
* Since: 0.4
*
* Retrieves the value set with clutter_stage_set_user_resizable().
*
- * Return value: %TRUE is the stage is resizable by the user.
+ * Return value: %TRUE if the stage is resizable by the user.
*
* Since: 0.4
*/
* @z_far: final distance from the viewer to the far clipping
* plane (always positive)
*
- * Fog settings used to create the depth cueing effect. #ClutterFox is
+ * Fog settings used to create the depth cueing effect. #ClutterFog is
* useful only when using the fixed point API.
*
* Since: 0.6
*
* The clutter_texture_set_from_rgb_data() and clutter_texture_set_pixbuf()
* functions are used to copy image data into texture memory and subsequently
- * realize the the texture.
+ * realize the texture.
*
* If texture reads are supported by underlying GL implementation,
* unrealizing/hiding frees image data from texture memory moving to main
/**
* clutter_texture_set_from_yuv_data:
* @texture: A #ClutterTexture
- * @data: Image data in RGB type colorspace.
+ * @data: Image data in YUV type colorspace.
* @width: Width in pixels of image data.
* @height: Height in pixels of image data
* @flags: #ClutterTextureFlags
* 'live' redirected output of the actors scene.
*
* Note this function is intented as a utility call for uniformly applying
- * shaders to groups and other potentail visual effects. It requires that
+ * shaders to groups and other potential visual effects. It requires that
* both %CLUTTER_FEATURE_TEXTURE_RECTANGLE and %CLUTTER_FEATURE_OFFSCREEN
* features are supported by the current backend and the target system.
*
* </listitem>
* <listitem>
* <para>The texture will automatically resize to contain a further
- * transformed source. The however involves overhead and can be
+ * transformed source. However, this involves overhead and can be
* avoided by placing the source actor in a bounding group
* sized large enough to contain any child tranformations.</para>
* </listitem>
* <listitem>
- * <para>Uploading pixel data to the text (e.g by #clutter_actor_set_pixbuf
- * will destroy the offscreen texture data and end redirection.</para>
+ * <para>Uploading pixel data to the texture (e.g by
+ * #clutter_actor_set_pixbuf) will destroy the offscreen texture data
+ * and end redirection.</para>
* </listitem>
* <listitem>
- * <para>#clutter_texture_get_pixbuf can used to read the offscreen
+ * <para>#clutter_texture_get_pixbuf can be used to read the offscreen
* texture pixels into a pixbuf.</para>
* </listitem>
* </itemizedlist>
*
- * Return value: A newly created #ClutterTexture object or %NULL on fail.
+ * Return value: A newly created #ClutterTexture object, or %NULL on failure.
*
* Since: 0.6
*/
+2008-02-15 Chris Lord <chris@openedhand.com>
+
+ reviewed by: <delete if not using a buddy>
+
+ * clutter-docs.sgml:
+
2008-02-15 Matthew Allum <mallum@openedhand.com>
* clutter-docs.sgml:
<para>
- Clutter wors by manipulating a scene graph of 2D surfaces (called actors)
+ Clutter works by manipulating a scene-graph of 2D surfaces, or 'actors',
inside a 3D space.
</para>
<para>
#ClutterActor is the base class for such surfaces. All
- #ClutterActors can we positioned and rotated in 3D space, scaled,
- clipped, have children, have there opacity and origin set.
- Tranforms applied to a parent actor also apply to any children.
+ #ClutterActor<!-- -->s can be positioned, scaled and rotated in 3D space.
+ In addition, other properties can be set, such as 2D clipping, children and
+ opacity. Tranforms applied to a parent actor also apply to any children.
Actors are also able to receive events.
</para>
<para>
Subclasses of #ClutterActor include #ClutterStage, #ClutterTexture,
- #ClutterLabel, #ClutterRectangle, #ClutterStage, #ClutterEntry and
- #ClutterGroup. #ClutterActors are added to a parent, transformed
- and the made visible.
+ #ClutterLabel, #ClutterRectangle, #ClutterEntry and
+ #ClutterGroup. #ClutterActor<!-- -->s are added to a parent, transformed
+ and then made visible.
</para>
<para>
#ClutterStage is the top level #ClutterActor - it's the representation
- of a window or framebuffer. It is created automatically when Clutter is
+ of a window, or framebuffer. It is created automatically when Clutter is
initialised. #ClutterStage is a #ClutterGroup, a class
implementing the #ClutterCointainer interface. Clutter currently
only supports a single stage.
</para>
<para>
- #ClutterTimeline's provide the basis for Clutters animation
- utilitys. Building on this include the #ClutterScore, for
- syncronising multiple timelines and the #ClutterBehaviour's and
- #ClutterEffect's for creating animation effects such as transitions.
+ #ClutterTimeline<!-- -->s provide the basis for Clutter's animation
+ utilities. Multiple timelines can be synchronised using #ClutterScore,
+ and #ClutterBehaviour and #ClutterEffect allow for the creation of
+ animation effects such as transitions.
</para>
<para>
- Clutter further contains a number of utilities including;
+ Clutter further contains a number of utilities, including;
#ClutterScript - for loading 'UI definition' files formatted in
JSON, #ClutterShader - a class for applying GPU shaders to actors,
#ClutterModel - a utility class for MVC list type implementations
- and #ClutterFixed - fixed point math utilitys
+ and #ClutterFixed - fixed point math utilities.
</para>
projects / profile / ivi / clutter.git / commitdiff