brl/mutter
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

2008-02-15 Emmanuele Bassi <ebassi@openedhand.com>

Browse Source 
* clutter/clutter-actor.[ch]:
	* clutter/clutter-types.h:
	* doc/reference/clutter-docs.sgml: Fix a lot of documentation.

2008-02-15  Matthew Allum  <mallum@openedhand.com>
This commit is contained in:
Emmanuele Bassi 2008-02-15 14:39:25 +00:00
parent 97b9cd92f0
commit 66f244b1cc
5 changed files with 229 additions and 202 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
ChangeLog
View File

@ -1,3 +1,9 @@
2008-02-15 Emmanuele Bassi <ebassi@openedhand.com>
* clutter/clutter-actor.[ch]:
* clutter/clutter-types.h:
* doc/reference/clutter-docs.sgml: Fix a lot of documentation.
2008-02-15 Matthew Allum <mallum@openedhand.com> 2008-02-15 Matthew Allum <mallum@openedhand.com>
* clutter/cogl/gles/cogl.c: (cogl_paint_init): * clutter/cogl/gles/cogl.c: (cogl_paint_init):

369
clutter/clutter-actor.c
View File

@ -40,20 +40,19 @@
* <graphic fileref="actor-box.png" format="PNG"/> * <graphic fileref="actor-box.png" format="PNG"/>
* </figure> * </figure>
* *
* The OpenGL modelview matrix for the actor is constructed from the actor * The OpenGL modelview matrix for the actor is constructed from
* settings by the following order of operations: * the actor settings by the following order of operations:
* <orderedlist> * <orderedlist>
* <listitem><para>Translation by actor x, y coords,</para></listitem> * <listitem><para>Translation by actor x, y coords,</para></listitem>
* <listitem><para>Scaling by scale_x, scale_y,</para></listitem> * <listitem><para>Scaling by scale_x, scale_y,</para></listitem>
* <listitem><para>Negative translation by anchor point x, y,</para> * <listitem><para>Negative translation by anchor point x,
* </listitem> * y,</para></listitem>
* <listitem><para>Rotation around z axis,</para></listitem> * <listitem><para>Rotation around z axis,</para></listitem>
* <listitem><para>Rotation around y axis,</para></listitem> * <listitem><para>Rotation around y axis,</para></listitem>
* <listitem><para>Rotation around x axis,</para></listitem> * <listitem><para>Rotation around x axis,</para></listitem>
* <listitem><para>Translation by actor depth (z),</para></listitem> * <listitem><para>Translation by actor depth (z),</para></listitem>
* <listitem><para>Clip stencil is applied (not an operation on the matrix * <listitem><para>Clip stencil is applied (not an operation on the matrix
* as such, but done as part of the transform set up).</para> * as such, but done as part of the transform set up).</para></listitem>
* </listitem>
* </orderedlist> * </orderedlist>
* *
* <note>The position of any children is referenced from the top-left corner of * <note>The position of any children is referenced from the top-left corner of
@ -76,12 +75,13 @@
* See clutter_set_motion_events_enabled() documentation for more * See clutter_set_motion_events_enabled() documentation for more
* information.</para></listitem> * information.</para></listitem>
* <listitem><para>Once emitted, an event emission chain has two * <listitem><para>Once emitted, an event emission chain has two
* phases: capture and bubble. A emitted event starts in the capture * phases: capture and bubble. An emitted event starts in the capture
* phase beginning at the stage and traversing every child actor until * phase (see ClutterActor::captured-event) beginning at the stage and
* the event source actor is reached. The emission then enters the bubble * traversing every child actor until the event source actor is reached.
* phase, traversing back up the chain via parents until it reaches the * The emission then enters the bubble phase, traversing back up the
* stage. Any event handler can abort this chain by returning * chain via parents until it reaches the stage. Any event handler can
* %TRUE (meaning "event handled").</para></listitem> * abort this chain by returning %TRUE (meaning "event handled").
* </para></listitem>
* <listitem><para>Pointer events will 'pass through' non reactive * <listitem><para>Pointer events will 'pass through' non reactive
* overlapping actors.</para></listitem> * overlapping actors.</para></listitem>
* </orderedlist> * </orderedlist>
@ -93,6 +93,10 @@
* *
* Every '?' box in the diagram above is an entry point for application * Every '?' box in the diagram above is an entry point for application
* code. * code.
*
* For implementing a new actor class, please read <link
* linkend="clutter-subclassing-ClutterActor">the corresponding section</link>
* of the API reference.
*/ */
/** /**
@ -131,26 +135,6 @@
* Since: 0.6 * 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 #ifdef HAVE_CONFIG_H
#include "config.h" #include "config.h"
#endif #endif
@ -328,9 +312,9 @@ clutter_actor_real_show (ClutterActor *self)
* clutter_actor_show * clutter_actor_show
* @self: A #ClutterActor * @self: A #ClutterActor
* *
* Flags a clutter actor to be displayed. An actor not shown will not * Flags an actor to be displayed. An actor not shown will not
* appear on the display. * be rendered on the stage.
**/ */
void void
clutter_actor_show (ClutterActor *self) clutter_actor_show (ClutterActor *self)
{ {
@ -349,7 +333,7 @@ clutter_actor_show (ClutterActor *self)
* clutter_actor_show_all: * clutter_actor_show_all:
* @self: a #ClutterActor * @self: a #ClutterActor
* *
* Call show() on all children of a actor (if any). * Call show() on all children of an actor (if any).
* *
* Since: 0.2 * Since: 0.2
*/ */
@ -384,9 +368,9 @@ clutter_actor_real_hide (ClutterActor *self)
* clutter_actor_hide * clutter_actor_hide
* @self: A #ClutterActor * @self: A #ClutterActor
* *
* Flags a clutter actor to be hidden. An actor not shown will not * Flags an actor to be hidden. An actor not shown will not be
* appear on the display. * rendered on the stage.
**/ */
void void
clutter_actor_hide (ClutterActor *self) clutter_actor_hide (ClutterActor *self)
{ {
@ -489,15 +473,15 @@ clutter_actor_real_pick (ClutterActor *self,
* @self: A #ClutterActor * @self: A #ClutterActor
* @color: A #ClutterColor * @color: A #ClutterColor
* *
* Renders a silhouette of the actor in supplied color. Used internally for * Renders a silhouette of the actor using the supplied color. Used
* mapping pointer events to actors. * internally for mapping pointer events to actors.
* *
* This function should not never be called directly by applications. * This function should never be called directly by applications.
* *
* Subclasses overiding this method should call * Subclasses overiding the ClutterActor::pick() method should call
* clutter_actor_should_pick_paint() to decide if to render there * clutter_actor_should_pick_paint() to decide whether to render their
* silhouette but in any case should still recursively call pick for * silhouette. Containers should always recursively call pick for
* any children. * each child.
* *
* Since 0.4 * Since 0.4
**/ **/
@ -517,7 +501,7 @@ clutter_actor_pick (ClutterActor *self,
* *
* Utility call for subclasses overiding the pick method. * Utility call for subclasses overiding the pick method.
* *
* This function should not never be called directly by applications. * This function should never be called directly by applications.
* *
* Return value: %TRUE if the actor should paint its silhouette, * Return value: %TRUE if the actor should paint its silhouette,
* %FALSE otherwise * %FALSE otherwise
@ -649,8 +633,9 @@ clutter_actor_transform_point (ClutterActor *actor,
* @point: A point as #ClutterVertex * @point: A point as #ClutterVertex
* @vertex: The translated #ClutterVertex * @vertex: The translated #ClutterVertex
* *
* Transforms point in coordinates relative to the actor into ancestor * Transforms @point in coordinates relative to the actor into
* coordiances using the relevant transform stack (i.e. scale, rotation etc) * ancestor-relative coordinates using the relevant transform
* stack (i.e. scale, rotation, etc)
* *
* Since: 0.6 * Since: 0.6
**/ **/
@ -687,9 +672,9 @@ clutter_actor_apply_relative_transform_to_point (ClutterActor *self,
* @point: A point as #ClutterVertex * @point: A point as #ClutterVertex
* @vertex: The translated #ClutterVertex * @vertex: The translated #ClutterVertex
* *
* Transforms point in coordinates relative to the actor * Transforms @point in coordinates relative to the actor
* into screen coordiances with the current actor tranform * into screen-relative coordinates with the current actor
* (i.e. scale, rotation etc) * tranformation (i.e. scale, rotation etc)
* *
* Since: 0.4 * Since: 0.4
**/ **/
@ -724,8 +709,8 @@ clutter_actor_apply_transform_to_point (ClutterActor *self,
* for all the vertices in one go). * for all the vertices in one go).
*/ */
static void static void
clutter_actor_transform_vertices_relative (ClutterActor * self, clutter_actor_transform_vertices_relative (ClutterActor *self,
ClutterActor * ancestor, ClutterActor *ancestor,
ClutterVertex verts[4], ClutterVertex verts[4],
ClutterFixed w[4]) ClutterFixed w[4])
{ {
@ -878,20 +863,21 @@ clutter_actor_transform_vertices (ClutterActor * self,
* clutter_actor_get_relative_vertices: * clutter_actor_get_relative_vertices:
* @self: A #ClutterActor * @self: A #ClutterActor
* @ancestor: A #ClutterActor to calculate the vertices against. * @ancestor: A #ClutterActor to calculate the vertices against.
* @verts: Pointer to a location of an array of 4 #ClutterVertex where to * @verts: return location for an array of 4 #ClutterVertex in which
* store the result. * to store the result.
* *
* Calculates the tranformed coordinates of the four corners of the actor * Calculates the transformed coordinates of the four corners of the
* in the plane of the ancestor. The returned vertices relate to the * actor in the plane of the ancestor. The returned vertices relate to
* ClutterActorBox coordinates as follows: * the #ClutterActorBox coordinates as follows:
* * <itemizedlist>
* v[0] contains (x1, y1) * <listitem><para>v[0] contains (x1, y1)</para></listitem>
* v[1] contains (x2, y1) * <listitem><para>v[1] contains (x2, y1)</para></listitem>
* v[2] contains (x1, y2) * <listitem><para>v[2] contains (x1, y2)</para></listitem>
* v[3] contains (x2, y2) * <listitem><para>v[3] contains (x2, y2)</para></listitem>
* </itemizedlist>
* *
* Since: 0.6 * Since: 0.6
**/ */
void void
clutter_actor_get_relative_vertices (ClutterActor *self, clutter_actor_get_relative_vertices (ClutterActor *self,
ClutterActor *ancestor, ClutterActor *ancestor,
@ -961,7 +947,7 @@ clutter_actor_get_relative_vertices (ClutterActor *self,
* @verts: Pointer to a location of an array of 4 #ClutterVertex where to * @verts: Pointer to a location of an array of 4 #ClutterVertex where to
* store the result. * store the result.
* *
* Calculates the tranformed screen coordinates of the four corners of * Calculates the transformed screen coordinates of the four corners of
* the actor; the returned vertices relate to the ClutterActorBox * the actor; the returned vertices relate to the ClutterActorBox
* coordinates as follows: * coordinates as follows:
* *
@ -1180,9 +1166,9 @@ _clutter_actor_apply_modelview_transform_recursive (ClutterActor * self,
* *
* Renders the actor to display. * Renders the actor to display.
* *
* This function should not be called directly by applications instead * This function should not be called directly by applications.
* #clutter_actor_queue_redraw should be used to queue paints. * Call clutter_actor_queue_redraw() to queue paints, instead.
**/ */
void void
clutter_actor_paint (ClutterActor *self) clutter_actor_paint (ClutterActor *self)
{ {
@ -1271,8 +1257,7 @@ clutter_actor_real_request_coords (ClutterActor *self,
* Note: Actors overriding the ClutterActor::request_coords() virtual * Note: Actors overriding the ClutterActor::request_coords() virtual
* function should always chain up to the parent class request_coords() * function should always chain up to the parent class request_coords()
* method. Actors should override this function only if they need to * method. Actors should override this function only if they need to
* recompute some internal state or need to reposition their evental * recompute some internal state or need to reposition their children.
* children.
*/ */
void void
clutter_actor_request_coords (ClutterActor *self, clutter_actor_request_coords (ClutterActor *self,
@ -1322,14 +1307,14 @@ clutter_actor_request_coords (ClutterActor *self,
/** /**
* clutter_actor_query_coords: * clutter_actor_query_coords:
* @self: A #ClutterActor * @self: A #ClutterActor
* @box: A location to store the actors #ClutterActorBox co-ordinates * @box: A location to store the actor's #ClutterActorBox
* *
* Requests the untransformed co-ordinates (in ClutterUnits) for the * Requests the untransformed co-ordinates (in #ClutterUnit<!-- -->s) for
* #ClutterActor relative to any parent. * the #ClutterActor, relative to any parent.
* *
* This function should not be called directly by applications instead * This function should not be called directly by applications.
* the various position/geometry methods should be used. * The various position/geometry methods should be used instead.
**/ */
void void
clutter_actor_query_coords (ClutterActor *self, clutter_actor_query_coords (ClutterActor *self,
ClutterActorBox *box) ClutterActorBox *box)
@ -1805,7 +1790,7 @@ clutter_actor_class_init (ClutterActorClass *klass)
PROP_SCALE_X, PROP_SCALE_X,
g_param_spec_double ("scale-x", g_param_spec_double ("scale-x",
"Scale-X", "Scale-X",
"Scale X", "Scale factor on the X axis",
0.0, 0.0,
G_MAXDOUBLE, G_MAXDOUBLE,
1.0, 1.0,
@ -1822,7 +1807,7 @@ clutter_actor_class_init (ClutterActorClass *klass)
PROP_SCALE_Y, PROP_SCALE_Y,
g_param_spec_double ("scale-y", g_param_spec_double ("scale-y",
"Scale-Y", "Scale-Y",
"Scale Y", "Scale factor on the Y axis",
0.0, 0.0,
G_MAXDOUBLE, G_MAXDOUBLE,
1.0, 1.0,
@ -1946,7 +1931,8 @@ clutter_actor_class_init (ClutterActorClass *klass)
* ClutterActor::show: * ClutterActor::show:
* @actor: the object which received the signal * @actor: the object which received the signal
* *
* The ::show signal is emitted when an actor becomes visible. * The ::show signal is emitted when an actor is visible and
* rendered on the stage.
* *
* Since: 0.2 * Since: 0.2
*/ */
@ -1962,7 +1948,8 @@ clutter_actor_class_init (ClutterActorClass *klass)
* ClutterActor::hide: * ClutterActor::hide:
* @actor: the object which received the signal * @actor: the object which received the signal
* *
* The ::hide signal is emitted when an actor is no longer visible. * The ::hide signal is emitted when an actor is no longer rendered
* on the stage.
* *
* Since: 0.2 * Since: 0.2
*/ */
@ -1998,7 +1985,7 @@ clutter_actor_class_init (ClutterActorClass *klass)
* @actor: the actor which received the event * @actor: the actor which received the event
* @event: a #ClutterEvent * @event: a #ClutterEvent
* *
* The ::event signal is emitted each time and event is received * The ::event signal is emitted each time an event is received
* by the @actor. This signal will be emitted on every actor, * by the @actor. This signal will be emitted on every actor,
* following the hierarchy chain, until it reaches the top-level * following the hierarchy chain, until it reaches the top-level
* container (the #ClutterStage). * container (the #ClutterStage).
@ -2066,7 +2053,7 @@ clutter_actor_class_init (ClutterActorClass *klass)
* @actor: the actor which received the event * @actor: the actor which received the event
* @event: a #ClutterScrollEvent * @event: a #ClutterScrollEvent
* *
* The ::scroll-event signal is emitted each time a the mouse is * The ::scroll-event signal is emitted each time the mouse is
* scrolled on @actor * scrolled on @actor
* *
* Return value: %TRUE if the event has been handled by the actor, * Return value: %TRUE if the event has been handled by the actor,
@ -2089,7 +2076,7 @@ clutter_actor_class_init (ClutterActorClass *klass)
* @event: a #ClutterKeyEvent * @event: a #ClutterKeyEvent
* *
* The ::key-press-event signal is emitted each time a keyboard button * The ::key-press-event signal is emitted each time a keyboard button
* is pressed on @actor. * is pressed while @actor has key focus (see clutter_stage_set_key_focus()).
* *
* Return value: %TRUE if the event has been handled by the actor, * Return value: %TRUE if the event has been handled by the actor,
* or %FALSE to continue the emission. * or %FALSE to continue the emission.
@ -2111,7 +2098,8 @@ clutter_actor_class_init (ClutterActorClass *klass)
* @event: a #ClutterKeyEvent * @event: a #ClutterKeyEvent
* *
* The ::key-release-event signal is emitted each time a keyboard button * The ::key-release-event signal is emitted each time a keyboard button
* is released on @actor. * is released while @actor has key focus (see
* clutter_stage_set_key_focus()).
* *
* Return value: %TRUE if the event has been handled by the actor, * Return value: %TRUE if the event has been handled by the actor,
* or %FALSE to continue the emission. * or %FALSE to continue the emission.
@ -2133,7 +2121,7 @@ clutter_actor_class_init (ClutterActorClass *klass)
* @event: a #ClutterMotionEvent * @event: a #ClutterMotionEvent
* *
* The ::motion-event signal is emitted each time the mouse pointer is * The ::motion-event signal is emitted each time the mouse pointer is
* moved on @actor. * moved over @actor.
* *
* Return value: %TRUE if the event has been handled by the actor, * Return value: %TRUE if the event has been handled by the actor,
* or %FALSE to continue the emission. * or %FALSE to continue the emission.
@ -2293,7 +2281,7 @@ clutter_actor_init (ClutterActor *self)
* references it holds to other objects. If the actor is inside a * references it holds to other objects. If the actor is inside a
* container, the actor will be removed. * container, the actor will be removed.
* *
* When you destroy a container its children will be destroyed as well. * When you destroy a container, its children will be destroyed as well.
* *
* Note: you cannot destroy the #ClutterStage returned by * Note: you cannot destroy the #ClutterStage returned by
* clutter_stage_get_default(). * clutter_stage_get_default().
@ -2342,8 +2330,8 @@ clutter_actor_destroy (ClutterActor *self)
* once the main loop becomes idle (after the current batch of events * once the main loop becomes idle (after the current batch of events
* has been processed, roughly). * has been processed, roughly).
* *
* Applications rarely need to call this as redraws are handled automatically * Applications rarely need to call this, as redraws are handled
* by modification functions. * automatically by modification functions.
*/ */
void void
clutter_actor_queue_redraw (ClutterActor *self) clutter_actor_queue_redraw (ClutterActor *self)
@ -2366,7 +2354,7 @@ clutter_actor_queue_redraw (ClutterActor *self)
* @self: A #ClutterActor * @self: A #ClutterActor
* @geometry: A #ClutterGeometry * @geometry: A #ClutterGeometry
* *
* Sets the actors untransformed geometry in pixels relative to any * Sets the actor's untransformed geometry in pixels relative to any
* parent actor. * parent actor.
*/ */
void void
@ -2388,7 +2376,7 @@ clutter_actor_set_geometry (ClutterActor *self,
* @self: A #ClutterActor * @self: A #ClutterActor
* @geometry: A location to store actors #ClutterGeometry * @geometry: A location to store actors #ClutterGeometry
* *
* Gets the actors untransformed geometry in pixels relative to any * Gets the actor's untransformed geometry in pixels relative to any
* parent actor. * parent actor.
*/ */
void void
@ -2415,7 +2403,7 @@ clutter_actor_get_geometry (ClutterActor *self,
* @x_2: A location to store actors right position, or %NULL. * @x_2: A location to store actors right position, or %NULL.
* @y_2: A location to store actors bottom position, or %NULL. * @y_2: A location to store actors bottom position, or %NULL.
* *
* Gets the actors untransformed bounding rectangle co-ordinates in pixels * Gets the actor's untransformed bounding rectangle coordinates in pixels
* relative to any parent actor. * relative to any parent actor.
*/ */
void void
@ -2450,7 +2438,7 @@ clutter_actor_get_coords (ClutterActor *self,
* @x: New left position of actor in pixels. * @x: New left position of actor in pixels.
* @y: New top position of actor in pixels. * @y: New top position of actor in pixels.
* *
* Sets the actors position in pixels relative to any parent actor. * Sets the actor's position in pixels relative to any parent actor.
*/ */
void void
clutter_actor_set_position (ClutterActor *self, clutter_actor_set_position (ClutterActor *self,
@ -2475,10 +2463,10 @@ clutter_actor_set_position (ClutterActor *self,
/** /**
* clutter_actor_set_positionu * clutter_actor_set_positionu
* @self: A #ClutterActor * @self: A #ClutterActor
* @x: New left position of actor in #ClutterUnit * @x: New left position of actor in #ClutterUnit<!-- -->s
* @y: New top position of actor in #ClutterUnit * @y: New top position of actor in #ClutterUnit<!-- -->s
* *
* Sets the actors position in #ClutterUnit relative to any * Sets the actors position in #ClutterUnit<!-- -->s relative to any
* parent actor. * parent actor.
* *
* Since: 0.6 * Since: 0.6
@ -2509,7 +2497,7 @@ clutter_actor_set_positionu (ClutterActor *self,
* @dx: Distance to move Actor on X axis. * @dx: Distance to move Actor on X axis.
* @dy: Distance to move Actor on Y axis. * @dy: Distance to move Actor on Y axis.
* *
* Moves an actor by specified distance relative to * Moves an actor by the specified distance relative to
* current position in pixels. * current position in pixels.
* *
* Since: 0.2 * Since: 0.2
@ -2532,7 +2520,8 @@ clutter_actor_move_by (ClutterActor *self,
* @dx: Distance to move Actor on X axis, in #ClutterUnit<!-- -->s. * @dx: Distance to move Actor on X axis, in #ClutterUnit<!-- -->s.
* @dy: Distance to move Actor on Y axis, in #ClutterUnit<!-- -->s. * @dy: Distance to move Actor on Y axis, in #ClutterUnit<!-- -->s.
* *
* Moves an actor by specified distance relative to the current position. * Moves an actor by the specified distance relative to the current
* position.
* *
* Since: 0.6 * Since: 0.6
*/ */
@ -2605,7 +2594,7 @@ clutter_actor_set_size_internalu (ClutterActor *self,
* @width: New width of actor in pixels, or -1 * @width: New width of actor in pixels, or -1
* @height: New height of actor in pixels, or -1 * @height: New height of actor in pixels, or -1
* *
* Sets the actors size in pixels. * Sets the actor's size in pixels.
* *
* If @width and/or @height are -1 the actor will assume the same size * If @width and/or @height are -1 the actor will assume the same size
* of its bounding box. * of its bounding box.
@ -2629,11 +2618,11 @@ clutter_actor_set_size (ClutterActor *self,
/** /**
* clutter_actor_set_sizeu * clutter_actor_set_sizeu
* @self: A #ClutterActor * @self: A #ClutterActor
* @width: New width of actor in #ClutterUnit, or -1 * @width: New width of actor in #ClutterUnit<!-- -->s, or -1
* @height: New height of actor in #ClutterUnit, or -1 * @height: New height of actor in #ClutterUnit<!-- -->s, or -1
* *
* Sets the actors size in #ClutterUnit. If @width and/or @height are -1 the * Sets the actors size in #ClutterUnit<!-- -->s. If @width and/or @height
* actor will assume the same size of its bounding box. * are -1 the actor will assume the same size of its bounding box.
* *
* Since: 0.6 * Since: 0.6
*/ */
@ -2650,8 +2639,8 @@ clutter_actor_set_sizeu (ClutterActor *self,
/** /**
* clutter_actor_get_size: * clutter_actor_get_size:
* @self: A #ClutterActor * @self: A #ClutterActor
* @width: Location to store width if non NULL. * @width: return location for the width, or %NULL.
* @height: Location to store height if non 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.
* *
@ -2678,8 +2667,8 @@ clutter_actor_get_size (ClutterActor *self,
/** /**
* clutter_actor_get_sizeu: * clutter_actor_get_sizeu:
* @self: A #ClutterActor * @self: A #ClutterActor
* @width: Location to store width if non NULL. * @width: return location for the width, or %NULL
* @height: Location to store height if non 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. * factors.
@ -2763,11 +2752,11 @@ clutter_actor_get_positionu (ClutterActor *self,
/* /*
* clutter_actor_get_abs_position_units * clutter_actor_get_abs_position_units
* @self: A #ClutterActor * @self: A #ClutterActor
* @x: Location to store x position if non NULL. * @x: return location for the X coordinate, or %NULL
* @y: Location to store y position if non NULL. * @y: return location for the Y coordinate, or %NULL
* *
* Gets the absolute position of an actor in clutter units relative * Gets the absolute position of an actor, in #ClutterUnit<!-- -->s,
* to the stage. * relative to the stage.
* *
* Since: 0.4 * Since: 0.4
*/ */
@ -2793,10 +2782,10 @@ clutter_actor_get_abs_position_units (ClutterActor *self,
/** /**
* clutter_actor_get_abs_position * clutter_actor_get_abs_position
* @self: A #ClutterActor * @self: A #ClutterActor
* @x: Location to store x position if non NULL. * @x: return location for the X coordinate, or %NULL
* @y: Location to store y position if non NULL. * @y: return location for the Y coordinate, or %NULL
* *
* Gets the absolute position of an actor in pixels relative * Gets the absolute position of an actor, in pixels, relative
* to the stage. * to the stage.
*/ */
void void
@ -2820,21 +2809,21 @@ clutter_actor_get_abs_position (ClutterActor *self,
/* /*
* clutter_actor_get_abs_size_units: * clutter_actor_get_abs_size_units:
* @self: A #ClutterActor * @self: A #ClutterActor
* @width: Location to store width if non NULL. * @width: return location for the width, or %NULL
* @height: Location to store height if non NULL. * @height: return location for the height, or %NULL
* *
* Gets the absolute size of an actor in clutter units taking into account * Gets the absolute size of an actor in #ClutterUnits<!-- -->s, taking
* an scaling factors. * into account the scaling factors.
* *
* Note: When the actor (or one of its ancestors) is rotated around the x or y * <note>When the actor (or one of its ancestors) is rotated around the
* axis, it no longer appears as on the stage as a rectangle, but as a generic * X or Y axis, it no longer appears as on the stage as a rectangle, but
* quadrangle; in that case this function returns the size of the smallest * as a generic quadrangle; in that case this function returns the size
* rectangle that encapsulates the entire quad. Please note that in this case * of the smallest rectangle that encapsulates the entire quad. Please
* no assumptions can be made about the relative position of this envelope to * note that in this case no assumptions can be made about the relative
* the absolute position of the actor, as returned by * position of this envelope to the absolute position of the actor, as
* clutter_actor_get_abs_position() - if you need this information, you need * returned by clutter_actor_get_abs_position(); if you need this
* to use clutter_actor_get_vertices() to get the coords of the actual * information, you need to use clutter_actor_get_vertices() to get the
* quadrangle. * coords of the actual quadrangle.
* *
* Since: 0.4 * Since: 0.4
*/ */
@ -2874,8 +2863,8 @@ clutter_actor_get_abs_size_units (ClutterActor *self,
/** /**
* clutter_actor_get_abs_size: * clutter_actor_get_abs_size:
* @self: A #ClutterActor * @self: A #ClutterActor
* @width: Location to store width if non NULL. * @width: return location for the width, or %NULL
* @height: Location to store height if non NULL. * @height: return location for the height, or %NULL
* *
* Gets the absolute size of an actor taking into account * Gets the absolute size of an actor taking into account
* an scaling factors * an scaling factors
@ -2897,9 +2886,9 @@ clutter_actor_get_abs_size (ClutterActor *self,
* clutter_actor_get_width * clutter_actor_get_width
* @self: A #ClutterActor * @self: A #ClutterActor
* *
* Retrieves the actors width ignoring any scaling factors. * Retrieves the actor's width ignoring any scaling factors.
* *
* Return value: The actor width in pixels * Return value: the width in pixels
**/ **/
guint guint
clutter_actor_get_width (ClutterActor *self) clutter_actor_get_width (ClutterActor *self)
@ -2917,9 +2906,9 @@ clutter_actor_get_width (ClutterActor *self)
* clutter_actor_get_widthu * clutter_actor_get_widthu
* @self: A #ClutterActor * @self: A #ClutterActor
* *
* Retrieves the actors width ignoring any scaling factors. * Retrieves the actor's width ignoring any scaling factors.
* *
* Return value: The actor width in #ClutterUnit * Return value: the width in #ClutterUnit<!-- -->s
* *
* since: 0.6 * since: 0.6
**/ **/
@ -2939,9 +2928,9 @@ clutter_actor_get_widthu (ClutterActor *self)
* clutter_actor_get_height * clutter_actor_get_height
* @self: A #ClutterActor * @self: A #ClutterActor
* *
* Retrieves the actors height ignoring any scaling factors. * Retrieves the actor's height ignoring any scaling factors.
* *
* Return value: The actor height in pixels * Return value: the height in pixels
**/ **/
guint guint
clutter_actor_get_height (ClutterActor *self) clutter_actor_get_height (ClutterActor *self)
@ -2959,9 +2948,9 @@ clutter_actor_get_height (ClutterActor *self)
* clutter_actor_get_heightu * clutter_actor_get_heightu
* @self: A #ClutterActor * @self: A #ClutterActor
* *
* Retrieves the actors height ignoring any scaling factors. * Retrieves the actor's height ignoring any scaling factors.
* *
* Return value: The actor height in #ClutterUnit * Return value: the height in #ClutterUnit<!-- -->s
* *
* since: 0.6 * since: 0.6
**/ **/
@ -2980,9 +2969,9 @@ clutter_actor_get_heightu (ClutterActor *self)
/** /**
* clutter_actor_set_width * clutter_actor_set_width
* @self: A #ClutterActor * @self: A #ClutterActor
* @width: Requested new width for actor * @width: Requested new width for the actor, in pixels
* *
* Requests a new width for actor * Requests a new width for the actor
* *
* since: 0.2 * since: 0.2
**/ **/
@ -2998,9 +2987,9 @@ clutter_actor_set_width (ClutterActor *self,
/** /**
* clutter_actor_set_widthu * clutter_actor_set_widthu
* @self: A #ClutterActor * @self: A #ClutterActor
* @width: Requested new width for actor in #ClutterUnit * @width: Requested new width for the actor, in #ClutterUnit<!-- -->s
* *
* Requests a new width for actor * Requests a new width for the actor
* *
* since: 0.6 * since: 0.6
**/ **/
@ -3016,9 +3005,9 @@ clutter_actor_set_widthu (ClutterActor *self,
/** /**
* clutter_actor_set_height * clutter_actor_set_height
* @self: A #ClutterActor * @self: A #ClutterActor
* @height: Requested new height for actor * @height: Requested new height for the actor, in pixels
* *
* Requests a new height for actor * Requests a new height for the actor
* *
* since: 0.2 * since: 0.2
**/ **/
@ -3034,9 +3023,9 @@ clutter_actor_set_height (ClutterActor *self,
/** /**
* clutter_actor_set_heightu * clutter_actor_set_heightu
* @self: A #ClutterActor * @self: A #ClutterActor
* @height: Requested new height for actor in #ClutterUnit * @height: Requested new height for actor, in #ClutterUnit<!-- -->s
* *
* Requests a new height for actor * Requests a new height for the actor
* *
* since: 0.6 * since: 0.6
**/ **/
@ -3052,9 +3041,9 @@ clutter_actor_set_heightu (ClutterActor *self,
/** /**
* clutter_actor_set_x: * clutter_actor_set_x:
* @self: a #ClutterActor * @self: a #ClutterActor
* @x: the actors position on the X axis * @x: the actor's position on the X axis
* *
* Sets the actor's x position relative to its parent. * Sets the actor's X coordinate, relative to its parent.
* *
* Since: 0.6 * Since: 0.6
*/ */
@ -3072,9 +3061,9 @@ clutter_actor_set_x (ClutterActor *self,
/** /**
* clutter_actor_set_xu: * clutter_actor_set_xu:
* @self: a #ClutterActor * @self: a #ClutterActor
* @x: the actors position on the X axis in #ClutterUnit * @x: the actor's position on the X axis in #ClutterUnit<!-- -->s
* *
* Sets the actor's x position relative to its parent. * Sets the actor's X coordinate, relative to its parent.
* *
* Since: 0.6 * Since: 0.6
*/ */
@ -3092,9 +3081,9 @@ clutter_actor_set_xu (ClutterActor *self,
/** /**
* clutter_actor_set_y: * clutter_actor_set_y:
* @self: a #ClutterActor * @self: a #ClutterActor
* @y: the actors position on the Y axis * @y: the actor's position on the Y axis
* *
* Sets the actor's y position relative to its parent. * Sets the actor's Y coordinate, relative to its parent.
* *
* Since: 0.6 * Since: 0.6
*/ */
@ -3112,9 +3101,9 @@ clutter_actor_set_y (ClutterActor *self,
/** /**
* clutter_actor_set_yu: * clutter_actor_set_yu:
* @self: a #ClutterActor * @self: a #ClutterActor
* @y: the actors position on the Y axis in #ClutterUnit * @y: the actor's position on the Y axis in #ClutterUnit<!-- -->s
* *
* Sets the actor's y position relative to its parent. * Sets the actor's Y coordinate, relative to its parent.
* *
* Since: 0.6 * Since: 0.6
*/ */
@ -3133,11 +3122,11 @@ clutter_actor_set_yu (ClutterActor *self,
* clutter_actor_get_x * clutter_actor_get_x
* @self: A #ClutterActor * @self: A #ClutterActor
* *
* Retrieves the actors x position relative to any parent. * Retrieves the actor's X coordinate, relative to any parent.
* *
* Return value: The actor x position in pixels ignoring any tranforms * Return value: the X coordinate, in pixels, ignoring any
* (i.e scaling, rotation). * tranformation (i.e. scaling, rotation).
**/ */
gint gint
clutter_actor_get_x (ClutterActor *self) clutter_actor_get_x (ClutterActor *self)
{ {
@ -3154,13 +3143,14 @@ clutter_actor_get_x (ClutterActor *self)
* clutter_actor_get_xu * clutter_actor_get_xu
* @self: A #ClutterActor * @self: A #ClutterActor
* *
* Retrieves the actors x position relative to any parent, in #ClutterUnit * Retrieves the actor's X coordinate, relative to any parent,
* in #ClutterUnit<!-- -->s.
* *
* Return value: The actor x position in #ClutterUnit ignoring any tranforms * Return value: the X coordinate, in #ClutterUnit<!-- -->s, ignoring
* (i.e scaling, rotation). * any tranformation (i.e. scaling, rotation).
* *
* Since: 0.6 * Since: 0.6
**/ */
ClutterUnit ClutterUnit
clutter_actor_get_xu (ClutterActor *self) clutter_actor_get_xu (ClutterActor *self)
{ {
@ -3177,11 +3167,11 @@ clutter_actor_get_xu (ClutterActor *self)
* clutter_actor_get_y: * clutter_actor_get_y:
* @self: A #ClutterActor * @self: A #ClutterActor
* *
* Retrieves the actors y position relative to any parent. * Retrieves the actor's Y coordinate, relative to any parent.
* *
* Return value: The actor y position in pixels ignoring any tranforms * Return value: the Y coordinate, in pixels, ignoring any
* (i.e scaling, rotation). * tranformation (i.e. scaling, rotation).
**/ */
gint gint
clutter_actor_get_y (ClutterActor *self) clutter_actor_get_y (ClutterActor *self)
{ {
@ -3198,11 +3188,12 @@ clutter_actor_get_y (ClutterActor *self)
* clutter_actor_get_yu: * clutter_actor_get_yu:
* @self: A #ClutterActor * @self: A #ClutterActor
* *
* Retrieves the actors y position relative to any parent, in #ClutterUnit * Retrieves the actor's Y coordinate, relative to any parent,
* in #ClutterUnit<!-- -->s.
* *
* Return value: The actor y position in #ClutterUnit ignoring any tranforms * Return value: the Y coordinate, in #ClutterUnit<!-- -->s, ignoring any
* (i.e scaling, rotation). * transformation (i.e. scaling, rotation).
**/ */
ClutterUnit ClutterUnit
clutter_actor_get_yu (ClutterActor *self) clutter_actor_get_yu (ClutterActor *self)
{ {
@ -3221,7 +3212,10 @@ clutter_actor_get_yu (ClutterActor *self)
* @scale_x: #ClutterFixed factor to scale actor by horizontally. * @scale_x: #ClutterFixed factor to scale actor by horizontally.
* @scale_y: #ClutterFixed factor to scale actor by vertically. * @scale_y: #ClutterFixed factor to scale actor by vertically.
* *
* Scales an actor with fixed point parameters. * Fixed point version of clutter_actor_set_scale().
*
* Scales an actor with the given factors. The scaling is always
* relative to the anchor point.
*/ */
void void
clutter_actor_set_scalex (ClutterActor *self, clutter_actor_set_scalex (ClutterActor *self,
@ -3252,7 +3246,8 @@ clutter_actor_set_scalex (ClutterActor *self,
* @scale_x: double factor to scale actor by horizontally. * @scale_x: double factor to scale actor by horizontally.
* @scale_y: double factor to scale actor by vertically. * @scale_y: double factor to scale actor by vertically.
* *
* Scales an actor with floating point parameters. * Scales an actor with the given factors. The scaling is always
* relative to the anchor point.
* *
* Since: 0.2 * Since: 0.2
*/ */
@ -3271,10 +3266,12 @@ clutter_actor_set_scale (ClutterActor *self,
/** /**
* clutter_actor_get_scalex: * clutter_actor_get_scalex:
* @self: A #ClutterActor * @self: A #ClutterActor
* @scale_x: Location to store horizonal fixed scale factor if non NULL. * @scale_x: Location to store horizonal scale factor, or %NULL.
* @scale_y: Location to store vertical fixed scale factor if non NULL. * @scale_y: Location to store vertical scale factor, or %NULL.
* *
* Retrieves an actors scale in fixed point. * Fixed point version of clutter_actor_get_scale().
*
* Retrieves the scale factors of an actor.
* *
* Since: 0.2 * Since: 0.2
*/ */
@ -3293,8 +3290,8 @@ clutter_actor_get_scalex (ClutterActor *self,
/** /**
* clutter_actor_get_scale: * clutter_actor_get_scale:
* @self: A #ClutterActor * @self: A #ClutterActor
* @scale_x: Location to store horizonal float scale factor if non NULL. * @scale_x: Location to store horizonal float scale factor, or %NULL.
* @scale_y: Location to store vertical float scale factor if non NULL. * @scale_y: Location to store vertical float scale factor, or %NULL.
* *
* Retrieves an actors scale in floating point. * Retrieves an actors scale in floating point.
* *
@ -3361,7 +3358,8 @@ clutter_actor_get_opacity (ClutterActor *self)
* @self: A #ClutterActor * @self: A #ClutterActor
* @name: Textual tag to apply to actor * @name: Textual tag to apply to actor
* *
* Sets a textual tag to the actor. * Sets the given name to @self. The name can be used to identify
* a #ClutterActor.
*/ */
void void
clutter_actor_set_name (ClutterActor *self, clutter_actor_set_name (ClutterActor *self,
@ -3386,9 +3384,8 @@ clutter_actor_set_name (ClutterActor *self,
* *
* Retrieves the name of @self. * Retrieves the name of @self.
* *
* Return value: pointer to textual tag for the actor. The * Return value: the name of the actor or %NULL. The returned string is
* returned string is owned by the actor and should not * owned by the actor and should not be modified or freed.
* be modified or freed.
*/ */
G_CONST_RETURN gchar * G_CONST_RETURN gchar *
clutter_actor_get_name (ClutterActor *self) clutter_actor_get_name (ClutterActor *self)
@ -3952,7 +3949,7 @@ clutter_actor_set_parent (ClutterActor *self,
* *
* Retrieves the parent of @self. * Retrieves the parent of @self.
* *
* Return Value: The #ClutterActor parent or NULL * Return Value: The #ClutterActor parent, or %NULL if no parent is set
*/ */
ClutterActor * ClutterActor *
clutter_actor_get_parent (ClutterActor *self) clutter_actor_get_parent (ClutterActor *self)
@ -4346,8 +4343,9 @@ clutter_actor_set_anchor_point (ClutterActor *self,
* @anchor_x: X coordinate of the anchor point * @anchor_x: X coordinate of the anchor point
* @anchor_y: Y 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
* the relative position of the actor toward its parent remains the same. * that the relative position of the actor toward its parent remains the
* same.
* *
* Since: 0.6 * Since: 0.6
*/ */
@ -5354,8 +5352,9 @@ clutter_actor_get_shader (ClutterActor *self)
* @self: a #ClutterActor * @self: a #ClutterActor
* @shader: a #ClutterShader or %NULL to unset the shader. * @shader: a #ClutterShader or %NULL to unset the shader.
* *
* Sets the #ClutterShader to be used when rendering @self, pass in NULL * Sets the #ClutterShader to be used when rendering @self.
* to unset a currently set shader for an actor. * If @shader is %NULL it will unset any currently set shader
* for an actor.
* *
* Return value: %TRUE if the shader was successfully applied * Return value: %TRUE if the shader was successfully applied
* *

30
clutter/clutter-actor.h
View File

@ -52,8 +52,23 @@ G_BEGIN_DECLS
#define CLUTTER_ACTOR_GET_CLASS(obj) \ #define CLUTTER_ACTOR_GET_CLASS(obj) \
(G_TYPE_INSTANCE_GET_CLASS ((obj), CLUTTER_TYPE_ACTOR, ClutterActorClass)) (G_TYPE_INSTANCE_GET_CLASS ((obj), CLUTTER_TYPE_ACTOR, ClutterActorClass))
#define CLUTTER_ACTOR_SET_FLAGS(e,f) (((ClutterActor*)(e))->flags |= (f)) /**
#define CLUTTER_ACTOR_UNSET_FLAGS(e,f) (((ClutterActor*)(e))->flags &= ~(f)) * CLUTTER_ACTOR_SET_FLAGS:
* @a: a #ClutterActor
* @f: the #ClutterActorFlags to set
*
* Sets the given flags on a #ClutterActor
*/
#define CLUTTER_ACTOR_SET_FLAGS(a,f) (((ClutterActor*)(a))->flags |= (f))
/**
* CLUTTER_ACTOR_UNSET_FLAGS:
* @a: a #ClutterActor
* @f: the #ClutterActorFlags to unset
*
* Unsets the given flags on a #ClutterActor
*/
#define CLUTTER_ACTOR_UNSET_FLAGS(a,f) (((ClutterActor*)(a))->flags &= ~(f))
#define CLUTTER_ACTOR_IS_MAPPED(e) (((ClutterActor*)(e))->flags & CLUTTER_ACTOR_MAPPED) #define CLUTTER_ACTOR_IS_MAPPED(e) (((ClutterActor*)(e))->flags & CLUTTER_ACTOR_MAPPED)
#define CLUTTER_ACTOR_IS_REALIZED(e) (((ClutterActor*)(e))->flags & CLUTTER_ACTOR_REALIZED) #define CLUTTER_ACTOR_IS_REALIZED(e) (((ClutterActor*)(e))->flags & CLUTTER_ACTOR_REALIZED)
@ -72,6 +87,13 @@ typedef struct _ClutterActorPrivate ClutterActorPrivate;
* Generic callback * Generic callback
*/ */
typedef void (*ClutterCallback) (ClutterActor *actor, gpointer data); typedef void (*ClutterCallback) (ClutterActor *actor, gpointer data);
/**
* CLUTTER_CALLBACK
* @f: a function
*
* Convenience macro to cast a function to #ClutterCallback
*/
#define CLUTTER_CALLBACK(f) ((ClutterCallback) (f)) #define CLUTTER_CALLBACK(f) ((ClutterCallback) (f))
/** /**
@ -146,7 +168,7 @@ struct _ClutterActor
* @hide_all: virtual function for containers and composite actors, to * @hide_all: virtual function for containers and composite actors, to
* determine which children should be shown when calling * determine which children should be shown when calling
* clutter_actor_hide_all() on the actor. Defaults to calling * clutter_actor_hide_all() on the actor. Defaults to calling
* clutter_actor_show(). * clutter_actor_hide().
* @realize: virtual function, used to allocate resources for the actor; * @realize: virtual function, used to allocate resources for the actor;
* it should chain up to the parent's implementation * it should chain up to the parent's implementation
* @unrealize: virtual function, used to deallocate resources allocated * @unrealize: virtual function, used to deallocate resources allocated
@ -158,7 +180,7 @@ struct _ClutterActor
* its coordinates; it must chain up to the parent's implementation * its coordinates; it must chain up to the parent's implementation
* @parent_set: signal class closure for the ClutterActor::parent-set * @parent_set: signal class closure for the ClutterActor::parent-set
* @destroy: signal class closure for ClutterActor::destroy * @destroy: signal class closure for ClutterActor::destroy
* @pick: virtual functions, used to draw an outline of the actor with * @pick: virtual function, used to draw an outline of the actor with
* the given colour * the given colour
* @event: signal class closure for ClutterActor::event * @event: signal class closure for ClutterActor::event
* @button_press_event: signal class closure for * @button_press_event: signal class closure for

2
clutter/clutter-types.h
View File

@ -83,7 +83,7 @@ typedef struct _ClutterVertex ClutterVertex;
* @width: width of an actor * @width: width of an actor
* @height: height of an actor * @height: height of an actor
* *
* Rectangle containing an actor. * The rectangle containing an actor's bounding box, measured in pixels.
*/ */
struct _ClutterGeometry struct _ClutterGeometry
{ {

14
doc/reference/clutter-docs.sgml
View File

@ -48,14 +48,14 @@
<para> <para>
Clutter is a GObject based library for creating fast, visually Clutter is a GObject based library for creating fast, visually
rich graphical user interfaces. rich, graphical user interfaces.
</para> </para>
<para> <para>
Clutter essentially works by manipulating a scene graph of 2D Clutter wors by manipulating a scene graph of 2D surfaces (called actors)
surfaces (actors) in 3D space. inside a 3D space.
</para> </para>
<para> <para>
@ -69,7 +69,7 @@
</para> </para>
<para> <para>
Sub classes of #ClutterActor include #ClutterStage, #ClutterTexture, Subclasses of #ClutterActor include #ClutterStage, #ClutterTexture,
#ClutterLabel, #ClutterRectangle, #ClutterStage, #ClutterEntry and #ClutterLabel, #ClutterRectangle, #ClutterStage, #ClutterEntry and
#ClutterGroup. #ClutterActors are added to a parent, transformed #ClutterGroup. #ClutterActors are added to a parent, transformed
and the made visible. and the made visible.
@ -77,8 +77,8 @@
</para> </para>
<para> <para>
#ClutterStage is the top level #ClutterActor - its essentially a #ClutterStage is the top level #ClutterActor - it's the representation
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 initialised. #ClutterStage is a #ClutterGroup, a class
implementing the #ClutterCointainer interface. Clutter currently implementing the #ClutterCointainer interface. Clutter currently
only supports a single stage. only supports a single stage.
@ -136,7 +136,7 @@
<varlistentry> <varlistentry>
<term>Pango</term> <term>Pango</term>
<listitem> <listitem>
<para>Pango is a library for laying out and rendering of <para>Pango is a library for laying out and rendering
text, with an emphasis on internationalization.</para> text, with an emphasis on internationalization.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>