ClutterActor

ClutterActor — The basic element of the scene graph

Functions

#define CLUTTER_ACTOR_SET_FLAGS()
#define CLUTTER_ACTOR_UNSET_FLAGS()
#define CLUTTER_ACTOR_IS_MAPPED()
#define CLUTTER_ACTOR_IS_REALIZED()
#define CLUTTER_ACTOR_IS_VISIBLE()
#define CLUTTER_ACTOR_IS_REACTIVE()
#define CLUTTER_CALLBACK()
void (*ClutterCallback) ()
ClutterActor * clutter_actor_new ()
void clutter_actor_set_flags ()
void clutter_actor_unset_flags ()
ClutterActorFlags clutter_actor_get_flags ()
void clutter_actor_set_name ()
const gchar * clutter_actor_get_name ()
guint32 clutter_actor_get_gid ()
void clutter_actor_show ()
void clutter_actor_show_all ()
void clutter_actor_hide ()
void clutter_actor_hide_all ()
gboolean clutter_actor_is_visible ()
void clutter_actor_realize ()
void clutter_actor_unrealize ()
gboolean clutter_actor_is_realized ()
void clutter_actor_paint ()
void clutter_actor_continue_paint ()
void clutter_actor_queue_redraw ()
void clutter_actor_queue_redraw_with_clip ()
void clutter_actor_queue_relayout ()
void clutter_actor_destroy ()
gboolean clutter_actor_event ()
gboolean clutter_actor_should_pick_paint ()
void clutter_actor_map ()
void clutter_actor_unmap ()
gboolean clutter_actor_is_mapped ()
gboolean clutter_actor_has_overlaps ()
gboolean clutter_actor_has_mapped_clones ()
void clutter_actor_allocate ()
void clutter_actor_allocate_preferred_size ()
void clutter_actor_allocate_available_size ()
void clutter_actor_allocate_align_fill ()
void clutter_actor_set_allocation ()
void clutter_actor_get_allocation_box ()
void clutter_actor_get_allocation_geometry ()
void clutter_actor_get_allocation_vertices ()
void clutter_actor_get_preferred_size ()
void clutter_actor_get_preferred_width ()
void clutter_actor_get_preferred_height ()
void clutter_actor_set_fixed_position_set ()
gboolean clutter_actor_get_fixed_position_set ()
void clutter_actor_set_request_mode ()
ClutterRequestMode clutter_actor_get_request_mode ()
gboolean clutter_actor_has_allocation ()
void clutter_actor_set_x_align ()
ClutterActorAlign clutter_actor_get_x_align ()
void clutter_actor_set_y_align ()
ClutterActorAlign clutter_actor_get_y_align ()
ClutterMargin * clutter_margin_copy ()
void clutter_margin_free ()
ClutterMargin * clutter_margin_new ()
void clutter_actor_set_margin ()
void clutter_actor_get_margin ()
void clutter_actor_set_margin_top ()
gfloat clutter_actor_get_margin_top ()
void clutter_actor_set_margin_right ()
gfloat clutter_actor_get_margin_right ()
void clutter_actor_set_margin_bottom ()
gfloat clutter_actor_get_margin_bottom ()
void clutter_actor_set_margin_left ()
gfloat clutter_actor_get_margin_left ()
void clutter_actor_set_x_expand ()
gboolean clutter_actor_get_x_expand ()
void clutter_actor_set_y_expand ()
gboolean clutter_actor_get_y_expand ()
gboolean clutter_actor_needs_expand ()
void clutter_actor_set_layout_manager ()
ClutterLayoutManager * clutter_actor_get_layout_manager ()
void clutter_actor_set_background_color ()
void clutter_actor_get_background_color ()
void clutter_actor_set_geometry ()
void clutter_actor_get_geometry ()
void clutter_actor_set_size ()
void clutter_actor_get_size ()
void clutter_actor_set_position ()
void clutter_actor_get_position ()
void clutter_actor_set_width ()
gfloat clutter_actor_get_width ()
void clutter_actor_set_height ()
gfloat clutter_actor_get_height ()
void clutter_actor_set_x ()
gfloat clutter_actor_get_x ()
void clutter_actor_set_y ()
gfloat clutter_actor_get_y ()
void clutter_actor_move_by ()
void clutter_actor_set_z_position ()
gfloat clutter_actor_get_z_position ()
void clutter_actor_set_pivot_point ()
void clutter_actor_get_pivot_point ()
void clutter_actor_set_pivot_point_z ()
gfloat clutter_actor_get_pivot_point_z ()
void clutter_actor_set_scale ()
void clutter_actor_get_scale ()
void clutter_actor_set_scale_z ()
gdouble clutter_actor_get_scale_z ()
gboolean clutter_actor_is_scaled ()
void clutter_actor_set_rotation_angle ()
gdouble clutter_actor_get_rotation_angle ()
gboolean clutter_actor_is_rotated ()
void clutter_actor_set_translation ()
void clutter_actor_get_translation ()
void clutter_actor_set_transform ()
void clutter_actor_get_transform ()
void clutter_actor_set_child_transform ()
void clutter_actor_get_child_transform ()
void clutter_actor_apply_transform_to_point ()
gboolean clutter_actor_transform_stage_point ()
void clutter_actor_apply_relative_transform_to_point ()
void clutter_actor_get_transformed_position ()
void clutter_actor_get_transformed_size ()
guint8 clutter_actor_get_paint_opacity ()
gboolean clutter_actor_get_paint_visibility ()
void clutter_actor_get_abs_allocation_vertices ()
const ClutterPaintVolume * clutter_actor_get_paint_volume ()
gboolean clutter_actor_get_paint_box ()
const ClutterPaintVolume * clutter_actor_get_transformed_paint_volume ()
const ClutterPaintVolume * clutter_actor_get_default_paint_volume ()
void clutter_actor_set_content ()
ClutterContent * clutter_actor_get_content ()
void clutter_actor_set_content_gravity ()
ClutterContentGravity clutter_actor_get_content_gravity ()
void clutter_actor_set_content_scaling_filters ()
void clutter_actor_get_content_scaling_filters ()
void clutter_actor_set_content_repeat ()
ClutterContentRepeat clutter_actor_get_content_repeat ()
void clutter_actor_get_content_box ()
void clutter_actor_set_clip ()
void clutter_actor_remove_clip ()
gboolean clutter_actor_has_clip ()
void clutter_actor_get_clip ()
void clutter_actor_set_clip_to_allocation ()
gboolean clutter_actor_get_clip_to_allocation ()
void clutter_actor_set_opacity ()
guint8 clutter_actor_get_opacity ()
void clutter_actor_set_opacity_override ()
gint clutter_actor_get_opacity_override ()
void clutter_actor_set_offscreen_redirect ()
ClutterOffscreenRedirect clutter_actor_get_offscreen_redirect ()
gboolean clutter_actor_is_in_clone_paint ()
void clutter_actor_add_child ()
void clutter_actor_insert_child_above ()
void clutter_actor_insert_child_at_index ()
void clutter_actor_insert_child_below ()
void clutter_actor_replace_child ()
void clutter_actor_remove_child ()
void clutter_actor_remove_all_children ()
void clutter_actor_destroy_all_children ()
ClutterActor * clutter_actor_get_first_child ()
ClutterActor * clutter_actor_get_next_sibling ()
ClutterActor * clutter_actor_get_previous_sibling ()
ClutterActor * clutter_actor_get_last_child ()
ClutterActor * clutter_actor_get_child_at_index ()
GList * clutter_actor_get_children ()
gint clutter_actor_get_n_children ()
ClutterActor * clutter_actor_get_parent ()
void clutter_actor_set_child_above_sibling ()
void clutter_actor_set_child_at_index ()
void clutter_actor_set_child_below_sibling ()
gboolean clutter_actor_contains ()
ClutterActor * clutter_actor_get_stage ()
void clutter_actor_iter_init ()
gboolean clutter_actor_iter_is_valid ()
gboolean clutter_actor_iter_next ()
gboolean clutter_actor_iter_prev ()
void clutter_actor_iter_remove ()
void clutter_actor_iter_destroy ()
ClutterActor * (*ClutterActorCreateChildFunc) ()
void clutter_actor_bind_model ()
void clutter_actor_bind_model_with_properties ()
void clutter_actor_save_easing_state ()
void clutter_actor_restore_easing_state ()
void clutter_actor_set_easing_duration ()
guint clutter_actor_get_easing_duration ()
void clutter_actor_set_easing_mode ()
ClutterAnimationMode clutter_actor_get_easing_mode ()
void clutter_actor_set_easing_delay ()
guint clutter_actor_get_easing_delay ()
ClutterTransition * clutter_actor_get_transition ()
void clutter_actor_add_transition ()
void clutter_actor_remove_transition ()
void clutter_actor_remove_all_transitions ()
void clutter_actor_set_reactive ()
gboolean clutter_actor_get_reactive ()
gboolean clutter_actor_has_key_focus ()
void clutter_actor_grab_key_focus ()
gboolean clutter_actor_has_pointer ()
PangoContext * clutter_actor_get_pango_context ()
PangoContext * clutter_actor_create_pango_context ()
PangoLayout * clutter_actor_create_pango_layout ()
void clutter_actor_set_text_direction ()
ClutterTextDirection clutter_actor_get_text_direction ()
AtkObject * clutter_actor_get_accessible ()
void clutter_actor_add_action ()
void clutter_actor_add_action_with_name ()
void clutter_actor_remove_action ()
void clutter_actor_remove_action_by_name ()
gboolean clutter_actor_has_actions ()
GList * clutter_actor_get_actions ()
ClutterAction * clutter_actor_get_action ()
void clutter_actor_clear_actions ()
void clutter_actor_add_constraint ()
void clutter_actor_add_constraint_with_name ()
void clutter_actor_remove_constraint ()
void clutter_actor_remove_constraint_by_name ()
gboolean clutter_actor_has_constraints ()
GList * clutter_actor_get_constraints ()
ClutterConstraint * clutter_actor_get_constraint ()
void clutter_actor_clear_constraints ()
void clutter_actor_add_effect ()
void clutter_actor_add_effect_with_name ()
void clutter_actor_remove_effect ()
void clutter_actor_remove_effect_by_name ()
gboolean clutter_actor_has_effects ()
GList * clutter_actor_get_effects ()
ClutterEffect * clutter_actor_get_effect ()
void clutter_actor_clear_effects ()
void clutter_actor_set_scale_full ()
void clutter_actor_set_scale_with_gravity ()
void clutter_actor_get_scale_center ()
ClutterGravity clutter_actor_get_scale_gravity ()
void clutter_actor_set_depth ()
gfloat clutter_actor_get_depth ()
void clutter_actor_push_internal ()
void clutter_actor_pop_internal ()
void clutter_actor_set_parent ()
void clutter_actor_reparent ()
void clutter_actor_unparent ()
void clutter_actor_raise ()
void clutter_actor_lower ()
void clutter_actor_raise_top ()
void clutter_actor_lower_bottom ()
gboolean clutter_actor_set_shader ()
ClutterShader * clutter_actor_get_shader ()
void clutter_actor_set_shader_param ()
void clutter_actor_set_shader_param_float ()
void clutter_actor_set_shader_param_int ()
void clutter_actor_set_anchor_point ()
void clutter_actor_get_anchor_point ()
void clutter_actor_set_anchor_point_from_gravity ()
ClutterGravity clutter_actor_get_anchor_point_gravity ()
void clutter_actor_move_anchor_point ()
void clutter_actor_move_anchor_point_from_gravity ()
void clutter_actor_set_rotation ()
gdouble clutter_actor_get_rotation ()
void clutter_actor_set_z_rotation_from_gravity ()
ClutterGravity clutter_actor_get_z_rotation_gravity ()
void clutter_actor_get_transformation_matrix ()

Properties

ClutterAction * actions Write
ClutterActorBox * allocation Read
ClutterGravity anchor-gravity Read / Write
gfloat anchor-x Read / Write
gfloat anchor-y Read / Write
ClutterColor * background-color Read / Write
gboolean background-color-set Read
ClutterMatrix * child-transform Read / Write
gboolean child-transform-set Read
ClutterGeometry * clip Read / Write
ClutterRect * clip-rect Read / Write
gboolean clip-to-allocation Read / Write
ClutterConstraint * constraints Write
ClutterContent * content Read / Write
ClutterActorBox * content-box Read
ClutterContentGravity content-gravity Read / Write
ClutterContentRepeat content-repeat Read / Write
gfloat depth Read / Write
ClutterEffect * effect Write
ClutterActor * first-child Read
gboolean fixed-position-set Read / Write
gfloat fixed-x Read / Write
gfloat fixed-y Read / Write
gboolean has-clip Read
gboolean has-pointer Read
gfloat height Read / Write
ClutterActor * last-child Read
ClutterLayoutManager * layout-manager Read / Write
ClutterScalingFilter magnification-filter Read / Write
gboolean mapped Read
gfloat margin-bottom Read / Write
gfloat margin-left Read / Write
gfloat margin-right Read / Write
gfloat margin-top Read / Write
gfloat min-height Read / Write
gboolean min-height-set Read / Write
gfloat min-width Read / Write
gboolean min-width-set Read / Write
ClutterScalingFilter minification-filter Read / Write
gchar * name Read / Write
gfloat natural-height Read / Write
gboolean natural-height-set Read / Write
gfloat natural-width Read / Write
gboolean natural-width-set Read / Write
ClutterOffscreenRedirect offscreen-redirect Read / Write
guint opacity Read / Write
ClutterPoint * pivot-point Read / Write
gfloat pivot-point-z Read / Write
ClutterPoint * position Read / Write
gboolean reactive Read / Write
gboolean realized Read
ClutterRequestMode request-mode Read / Write
gdouble rotation-angle-x Read / Write
gdouble rotation-angle-y Read / Write
gdouble rotation-angle-z Read / Write
ClutterVertex * rotation-center-x Read / Write
ClutterVertex * rotation-center-y Read / Write
ClutterVertex * rotation-center-z Read / Write
ClutterGravity rotation-center-z-gravity Read / Write
gfloat scale-center-x Read / Write
gfloat scale-center-y Read / Write
ClutterGravity scale-gravity Read / Write
gdouble scale-x Read / Write
gdouble scale-y Read / Write
gdouble scale-z Read / Write
gboolean show-on-set-parent Read / Write
ClutterSize * size Read / Write
ClutterTextDirection text-direction Read / Write
ClutterMatrix * transform Read / Write
gboolean transform-set Read
gfloat translation-x Read / Write
gfloat translation-y Read / Write
gfloat translation-z Read / Write
gboolean visible Read / Write
gfloat width Read / Write
gfloat x Read / Write
ClutterActorAlign x-align Read / Write
gboolean x-expand Read / Write
gfloat y Read / Write
ClutterActorAlign y-align Read / Write
gboolean y-expand Read / Write
gfloat z-position Read / Write

Signals

void allocation-changed Run Last
gboolean button-press-event Run Last
gboolean button-release-event Run Last
gboolean captured-event Run Last
void destroy No Hooks
gboolean enter-event Run Last
gboolean event Run Last
void hide Run First
void key-focus-in Run Last
void key-focus-out Run Last
gboolean key-press-event Run Last
gboolean key-release-event Run Last
gboolean leave-event Run Last
gboolean motion-event Run Last
void paint No Hooks
void parent-set Run Last
void pick Run Last
void queue-redraw No Hooks
void queue-relayout No Hooks
void realize Run Last
gboolean scroll-event Run Last
void show Run First
gboolean touch-event Run Last
void transition-stopped No Hooks
void transitions-completed Run Last
void unrealize Run Last

Object Hierarchy

    GBoxed
    ╰── ClutterMargin
    GObject
    ╰── GInitiallyUnowned
        ╰── ClutterActor
            ├── ClutterBox
            ├── ClutterTexture
            ├── ClutterClone
            ├── ClutterGroup
            ├── ClutterRectangle
            ├── ClutterScrollActor
            ╰── ClutterText

Implemented Interfaces

ClutterActor implements ClutterContainer, ClutterScriptable, ClutterAnimatable and AtkImplementorIface.

Description

The ClutterActor class is the basic element of the scene graph in Clutter, and it encapsulates the position, size, and transformations of a node in the graph.

Actor transformations

Each actor can be transformed using methods like clutter_actor_set_scale() or clutter_actor_set_rotation(). The order in which the transformations are applied is decided by Clutter and it is the following:

  1. translation by the origin of the “allocation” property

  2. translation by the actor's “z-position” property

  3. translation by the actor's “pivot-point” property

  4. scaling by the “scale-x” and “scale-y” factors

  5. rotation around the “rotation-angle-x” and “rotation-center-x”

  6. rotation around the “rotation-angle-y” and “rotation-center-y”

  7. rotation around the “rotation-angle-z” and “rotation-center-z”

  8. negative translation by the “anchor-x” and “anchor-y” point.

  9. negative translation by the actor's “pivot-point”

Modifying an actor's geometry

Each actor has a bounding box, called “allocation” which is either set by its parent or explicitly through the clutter_actor_set_position() and clutter_actor_set_size() methods. Each actor also has an implicit preferred size.

An actor’s preferred size can be defined by any subclass by overriding the ClutterActorClass.get_preferred_width() and the ClutterActorClass.get_preferred_height() virtual functions, or it can be explicitly set by using clutter_actor_set_width() and clutter_actor_set_height().

An actor’s position can be set explicitly by using clutter_actor_set_x() and clutter_actor_set_y(); the coordinates are relative to the origin of the actor’s parent.

Managing actor children

Each actor can have multiple children, by calling clutter_actor_add_child() to add a new child actor, and clutter_actor_remove_child() to remove an existing child. ClutterActor will hold a reference on each child actor, which will be released when the child is removed from its parent, or destroyed using clutter_actor_destroy().

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
ClutterActor *actor = clutter_actor_new ();

// set the bounding box of the actor
clutter_actor_set_position (actor, 0, 0);
clutter_actor_set_size (actor, 480, 640);

// set the background color of the actor
clutter_actor_set_background_color (actor, CLUTTER_COLOR_Orange);

// set the bounding box of the child, relative to the parent
ClutterActor *child = clutter_actor_new ();
clutter_actor_set_position (child, 20, 20);
clutter_actor_set_size (child, 80, 240);

// set the background color of the child
clutter_actor_set_background_color (child, CLUTTER_COLOR_Blue);

// add the child to the actor
clutter_actor_add_child (actor, child);

Children can be inserted at a given index, or above and below another child actor. The order of insertion determines the order of the children when iterating over them. Iterating over children is performed by using clutter_actor_get_first_child(), clutter_actor_get_previous_sibling(), clutter_actor_get_next_sibling(), and clutter_actor_get_last_child(). It is also possible to retrieve a list of children by using clutter_actor_get_children(), as well as retrieving a specific child at a given index by using clutter_actor_get_child_at_index().

If you need to track additions of children to a ClutterActor, use the “actor-added” signal; similarly, to track removals of children from a ClutterActor, use the “actor-removed” signal.

See basic-actor.c.

Painting an actor

There are three ways to paint an actor:

A ClutterContent is a delegate object that takes over the painting operations of one, or more actors. The ClutterContent painting will be performed on top of the “background-color” of the actor, and before calling the actor's own implementation of the ClutterActorClass.paint_node() virtual function.

1
2
3
4
5
6
7
8
ClutterActor *actor = clutter_actor_new ();

// set the bounding box
clutter_actor_set_position (actor, 50, 50);
clutter_actor_set_size (actor, 100, 100);

// set the content; the image_content variable is set elsewhere
clutter_actor_set_content (actor, image_content);

The ClutterActorClass.paint_node() virtual function is invoked whenever an actor needs to be painted. The implementation of the virtual function must only paint the contents of the actor itself, and not the contents of its children, if the actor has any.

The ClutterPaintNode passed to the virtual function is the local root of the render tree; any node added to it will be rendered at the correct position, as defined by the actor's “allocation”.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
static void
my_actor_paint_node (ClutterActor     *actor,
                     ClutterPaintNode *root)
{
  ClutterPaintNode *node;
  ClutterActorBox box;

  // where the content of the actor should be painted
  clutter_actor_get_allocation_box (actor, &box);

  // the cogl_texture variable is set elsewhere
  node = clutter_texture_node_new (cogl_texture, CLUTTER_COLOR_White,
                                   CLUTTER_SCALING_FILTER_TRILINEAR,
                                   CLUTTER_SCALING_FILTER_LINEAR);

  // paint the content of the node using the allocation
  clutter_paint_node_add_rectangle (node, &box);

  // add the node, and transfer ownership
  clutter_paint_node_add_child (root, node);
  clutter_paint_node_unref (node);
}

The #ClutterActorClass.paint() virtual function is invoked when the
#ClutterActor::paint signal is emitted, and after the other signal
handlers have been invoked. Overriding the paint virtual function
gives total control to the paint sequence of the actor itself,
including the children of the actor, if any.

It is strongly discouraged to override the #ClutterActorClass.paint()
virtual function, as well as connecting to the #ClutterActor::paint
signal. These hooks into the paint sequence are considered legacy, and
will be removed when the Clutter API changes.

Handling events on an actor

A ClutterActor can receive and handle input device events, for instance pointer events and key events, as long as its “reactive” property is set to TRUE.

Once an actor has been determined to be the source of an event, Clutter will traverse the scene graph from the top-level actor towards the event source, emitting the “captured-event” signal on each ancestor until it reaches the source; this phase is also called the "capture" phase. If the event propagation was not stopped, the graph is walked backwards, from the source actor to the top-level, and the “event” signal is emitted, alongside eventual event-specific signals like “button-press-event” or “motion-event”; this phase is also called the "bubble" phase.

At any point of the signal emission, signal handlers can stop the propagation through the scene graph by returning CLUTTER_EVENT_STOP; otherwise, they can continue the propagation by returning CLUTTER_EVENT_PROPAGATE.

Animation

Animation is a core concept of modern user interfaces; Clutter provides a complete and powerful animation framework that automatically tweens the actor's state without requiring direct, frame by frame manipulation from your application code. You have two models at your disposal:

  • an implicit animation model

  • an explicit animation model

The implicit animation model of Clutter assumes that all the changes in an actor state should be gradual and asynchronous; Clutter will automatically transition an actor's property change between the current state and the desired one without manual intervention, if the property is defined to be animatable in its documentation.

By default, in the 1.0 API series, the transition happens with a duration of zero milliseconds, and the implicit animation is an opt in feature to retain backwards compatibility.

Implicit animations depend on the current easing state; in order to use the default easing state for an actor you should call the clutter_actor_save_easing_state() function:

1
2
3
4
5
6
7
8
9
10
11
// assume that the actor is currently positioned at (100, 100)

// store the current easing state and reset the new easing state to
// its default values
clutter_actor_save_easing_state (actor);

// change the actor's position
clutter_actor_set_position (actor, 500, 500);

// restore the previously saved easing state
clutter_actor_restore_easing_state (actor);

The example above will trigger an implicit animation of the actor between its current position to a new position.

Implicit animations use a default duration of 250 milliseconds, and a default easing mode of CLUTTER_EASE_OUT_CUBIC, unless you call clutter_actor_set_easing_mode() and clutter_actor_set_easing_duration() after changing the easing state of the actor.

It is possible to animate multiple properties of an actor at the same time, and you can animate multiple actors at the same time as well, for instance:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
clutter_actor_save_easing_state (actor);

// animate the actor's opacity and depth
clutter_actor_set_opacity (actor, 0);
clutter_actor_set_depth (actor, -100);

clutter_actor_restore_easing_state (actor);

clutter_actor_save_easing_state (another_actor);

// animate another actor's opacity
clutter_actor_set_opacity (another_actor, 255);
clutter_actor_set_depth (another_actor, 100);

clutter_actor_restore_easing_state (another_actor);

Changing the easing state will affect all the following property transitions, but will not affect existing transitions.

It is important to note that if you modify the state on an animatable property while a transition is in flight, the transition's final value will be updated, as well as its duration and progress mode by using the current easing state; for instance, in the following example:

the first call to clutter_actor_set_x() will begin a transition of the “x” property from the current value to the value of 200 over a duration of one second; the second call to clutter_actor_set_x() will change the transition's final value to 100 and the duration to 500 milliseconds.

It is possible to receive a notification of the completion of an implicit transition by using the “transition-stopped” signal, decorated with the name of the property. In case you want to know when all the currently in flight transitions are complete, use the “transitions-completed” signal instead.

It is possible to retrieve the ClutterTransition used by the animatable properties by using clutter_actor_get_transition() and using the property name as the transition name.

The explicit animation model supported by Clutter requires that you create a ClutterTransition object, and optionally set the initial and final values. The transition will not start unless you add it to the ClutterActor.

1
2
3
4
5
6
7
8
9
10
ClutterTransition *transition;

transition = clutter_property_transition_new ("opacity");
clutter_timeline_set_duration (CLUTTER_TIMELINE (transition), 3000);
clutter_timeline_set_repeat_count (CLUTTER_TIMELINE (transition), 2);
clutter_timeline_set_auto_reverse (CLUTTER_TIMELINE (transition), TRUE);
clutter_transition_set_from (transition, G_TYPE_UINT, 255);
clutter_transition_set_to (transition, G_TYPE_UINT, 0);

clutter_actor_add_transition (actor, "animate-opacity", transition);

The example above will animate the “opacity” property of an actor between fully opaque and fully transparent, and back, over a span of 3 seconds. The animation does not begin until it is added to the actor.

The explicit animation API applies to all GObject properties, as well as the custom properties defined through the ClutterAnimatable interface, regardless of whether they are defined as implicitly animatable or not.

The explicit animation API should also be used when using custom animatable properties for ClutterAction, ClutterConstraint, and ClutterEffect instances associated to an actor; see the section on custom animatable properties below for an example.

Finally, explicit animations are useful for creating animations that run continuously, for instance:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// this animation will pulse the actor's opacity continuously
ClutterTransition *transition;
ClutterInterval *interval;

transition = clutter_property_transition_new ("opacity");

// we want to animate the opacity between 0 and 255
clutter_transition_set_from (transition, G_TYPE_UINT, 0);
clutter_transition_set_to (transition, G_TYPE_UINT, 255);

// over a one second duration, running an infinite amount of times
clutter_timeline_set_duration (CLUTTER_TIMELINE (transition), 1000);
clutter_timeline_set_repeat_count (CLUTTER_TIMELINE (transition), -1);

// we want to fade in and out, so we need to auto-reverse the transition
clutter_timeline_set_auto_reverse (CLUTTER_TIMELINE (transition), TRUE);

// and we want to use an easing function that eases both in and out
clutter_timeline_set_progress_mode (CLUTTER_TIMELINE (transition),
                                    CLUTTER_EASE_IN_OUT_CUBIC);

// add the transition to the desired actor to start it
clutter_actor_add_transition (actor, "opacityAnimation", transition);

Implementing an actor

Careful consideration should be given when deciding to implement a ClutterActor sub-class. It is generally recommended to implement a sub-class of ClutterActor only for actors that should be used as leaf nodes of a scene graph.

If your actor should be painted in a custom way, you should override the “paint” signal class handler. You can either opt to chain up to the parent class implementation or decide to fully override the default paint implementation; Clutter will set up the transformations and clip regions prior to emitting the “paint” signal.

By overriding the ClutterActorClass.get_preferred_width() and ClutterActorClass.get_preferred_height() virtual functions it is possible to change or provide the preferred size of an actor; similarly, by overriding the ClutterActorClass.allocate() virtual function it is possible to control the layout of the children of an actor. Make sure to always chain up to the parent implementation of the ClutterActorClass.allocate() virtual function.

In general, it is strongly encouraged to use delegation and composition instead of direct subclassing.

ClutterActor custom properties for ClutterScript

ClutterActor defines a custom "rotation" property which allows a short-hand description of the rotations to be applied to an actor.

The syntax of the "rotation" property is the following:

1
"rotation" : [ { "<axis>" : [ <angle>, [ <center-point> ] ] } ]

where:

  • axis is the name of an enumeration value of type ClutterRotateAxis

  • angle is a floating point value representing the rotation angle on the given axis in degrees

  • center-point is an optional array, and if present it must contain the center of rotation as described by two coordinates:

    • Y and Z for "x-axis"

    • X and Z for "y-axis"

    • X and Y for "z-axis".

ClutterActor also defines a scriptable "margin" property which follows the CSS "margin" shorthand.

1
2
3
4
5
6
7
8
// 4 values
"margin" : [ top, right, bottom, left ]
// 3 values
"margin" : [ top, left/right, bottom ]
// 2 values
"margin" : [ top/bottom, left/right ]
// 1 value
"margin" : [ top/right/bottom/left ]

ClutterActor will also parse every positional and dimensional property defined as a string through clutter_units_from_string(); you should read the documentation for the ClutterUnits parser format for the valid units and syntax.

Custom animatable properties

ClutterActor allows accessing properties of ClutterAction, ClutterEffect, and ClutterConstraint instances associated to an actor instance for animation purposes.

In order to access a specific ClutterAction or a ClutterConstraint property it is necessary to set the “name” property on the given action or constraint.

The property can be accessed using the following syntax:

1
@<section>.<meta-name>.<property-name>

  • the initial @ is mandatory

  • the section fragment can be one between "actions", "constraints" and "effects"

  • the meta-name fragment is the name of the action, effect, or constraint, as specified by the “name” property of ClutterActorMeta

  • the property-name fragment is the name of the action, effect, or constraint property to be animated.

The example below animates a ClutterBindConstraint applied to an actor using an explicit transition. The rect actor has a binding constraint on the origin actor, and in its initial state is overlapping the actor to which is bound to.

1
2
3
4
5
6
7
8
9
10
11
12
13
constraint = clutter_bind_constraint_new (origin, CLUTTER_BIND_X, 0.0);
clutter_actor_meta_set_name (CLUTTER_ACTOR_META (constraint), "bind-x");
clutter_actor_add_constraint (rect, constraint);

constraint = clutter_bind_constraint_new (origin, CLUTTER_BIND_Y, 0.0);
clutter_actor_meta_set_name (CLUTTER_ACTOR_META (constraint), "bind-y");
clutter_actor_add_constraint (rect, constraint);

clutter_actor_set_reactive (origin, TRUE);

g_signal_connect (origin, "button-press-event",
                  G_CALLBACK (on_button_press),
                  rect);

On button press, the rectangle "slides" from behind the actor to which is bound to, using the “offset” property to achieve the effect:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
gboolean
on_button_press (ClutterActor *origin,
                 ClutterEvent *event,
                 ClutterActor *rect)
{
  ClutterTransition *transition;

  // the offset that we want to apply; this will make the actor
  // slide in from behind the origin and rest at the right of
  // the origin, plus a padding value
  float new_offset = clutter_actor_get_width (origin) + h_padding;

  // the property we wish to animate; the "@constraints" section
  // tells Clutter to check inside the constraints associated
  // with the actor; the "bind-x" section is the name of the
  // constraint; and the "offset" is the name of the property
  // on the constraint
  const char *prop = "@constraints.bind-x.offset";

  // create a new transition for the given property
  transition = clutter_property_transition_new (prop);

  // set the easing mode and duration
  clutter_timeline_set_progress_mode (CLUTTER_TIMELINE (transition),
                                      CLUTTER_EASE_OUT_CUBIC);
  clutter_timeline_set_duration (CLUTTER_TIMELINE (transition), 500);

  // create the interval with the initial and final values
  clutter_transition_set_from (transition, G_TYPE_FLOAT, 0.f);
  clutter_transition_set_to (transition, G_TYPE_FLOAT, new_offset);

  // add the transition to the actor; this causes the animation
  // to start. the name "offsetAnimation" can be used to retrieve
  // the transition later
  clutter_actor_add_transition (rect, "offsetAnimation", transition);

  // we handled the event
  return CLUTTER_EVENT_STOP;
}

Functions

CLUTTER_ACTOR_SET_FLAGS()

#define             CLUTTER_ACTOR_SET_FLAGS(a,f)

CLUTTER_ACTOR_SET_FLAGS has been deprecated since version 1.24 and should not be used in newly-written code.

Changing flags directly is heavily discouraged in newly written code. ClutterActor will take care of setting the internal state.

Sets the given flags on a ClutterActor

Parameters

a

a ClutterActor

 

f

the ClutterActorFlags to set

 

CLUTTER_ACTOR_UNSET_FLAGS()

#define             CLUTTER_ACTOR_UNSET_FLAGS(a,f)

CLUTTER_ACTOR_UNSET_FLAGS has been deprecated since version 1.24 and should not be used in newly-written code.

Changing flags directly is heavily discouraged in newly written code. ClutterActor will take care of unsetting the internal state.

Unsets the given flags on a ClutterActor

Parameters

a

a ClutterActor

 

f

the ClutterActorFlags to unset

 

CLUTTER_ACTOR_IS_MAPPED()

#define             CLUTTER_ACTOR_IS_MAPPED(a)

CLUTTER_ACTOR_IS_MAPPED has been deprecated since version 1.24 and should not be used in newly-written code.

Use clutter_actor_is_mapped() or the “mapped” property instead of this macro.

Evaluates to TRUE if the CLUTTER_ACTOR_MAPPED flag is set.

The mapped state is set when the actor is visible and all its parents up to a top-level (e.g. a ClutterStage) are visible, realized, and mapped.

This check can be used to see if an actor is going to be painted, as only actors with the CLUTTER_ACTOR_MAPPED flag set are going to be painted.

The CLUTTER_ACTOR_MAPPED flag is managed by Clutter itself, and it should not be checked directly; instead, the recommended usage is to connect a handler on the “notify” signal for the “mapped” property of ClutterActor, and check the presence of the CLUTTER_ACTOR_MAPPED flag on state changes.

It is also important to note that Clutter may delay the changes of the CLUTTER_ACTOR_MAPPED flag on top-levels due to backend-specific limitations, or during the reparenting of an actor, to optimize unnecessary (and potentially expensive) state changes.

Parameters

a

a ClutterActor

 

Since: 0.2


CLUTTER_ACTOR_IS_REALIZED()

#define             CLUTTER_ACTOR_IS_REALIZED(a)

CLUTTER_ACTOR_IS_REALIZED has been deprecated since version 1.24 and should not be used in newly-written code.

Use clutter_actor_is_realized() or the “realized” property instead of this macro.

Evaluates to TRUE if the CLUTTER_ACTOR_REALIZED flag is set.

The realized state has an actor-dependant interpretation. If an actor wants to delay allocating resources until it is attached to a stage, it may use the realize state to do so. However it is perfectly acceptable for an actor to allocate Cogl resources before being realized because there is only one drawing context used by Clutter so any resources will work on any stage. If an actor is mapped it must also be realized, but an actor can be realized and unmapped (this is so hiding an actor temporarily doesn't do an expensive unrealize/realize).

To be realized an actor must be inside a stage, and all its parents must be realized.

Parameters

a

a ClutterActor

 

Since: 0.2


CLUTTER_ACTOR_IS_VISIBLE()

#define             CLUTTER_ACTOR_IS_VISIBLE(a)

CLUTTER_ACTOR_IS_VISIBLE has been deprecated since version 1.24 and should not be used in newly-written code.

Use clutter_actor_is_visible() or the “visible” property instead of this macro.

Evaluates to TRUE if the actor has been shown, FALSE if it's hidden. Equivalent to the ClutterActor::visible object property.

Note that an actor is only painted onscreen if it's mapped, which means it's visible, and all its parents are visible, and one of the parents is a toplevel stage; see also CLUTTER_ACTOR_IS_MAPPED.

Parameters

a

a ClutterActor

 

Since: 0.2


CLUTTER_ACTOR_IS_REACTIVE()

#define             CLUTTER_ACTOR_IS_REACTIVE(a)

CLUTTER_ACTOR_IS_REACTIVE has been deprecated since version 1.24 and should not be used in newly-written code.

Use clutter_actor_get_reactive() or the “reactive” property instead of this macro.

Evaluates to TRUE if the CLUTTER_ACTOR_REACTIVE flag is set.

Only reactive actors will receive event-related signals.

Parameters

a

a ClutterActor

 

Since: 0.6


CLUTTER_CALLBACK()

#define CLUTTER_CALLBACK(f)        ((ClutterCallback) (f))

Convenience macro to cast a function to ClutterCallback

Parameters

f

a function

 

ClutterCallback ()

void
(*ClutterCallback) (ClutterActor *actor,
                    gpointer data);

Generic callback

Parameters

actor

a ClutterActor

 

data

user data.

[closure]

clutter_actor_new ()

ClutterActor *
clutter_actor_new (void);

Creates a new ClutterActor.

A newly created actor has a floating reference, which will be sunk when it is added to another actor.

Returns

the newly created ClutterActor

Since: 1.10


clutter_actor_set_flags ()

void
clutter_actor_set_flags (ClutterActor *self,
                         ClutterActorFlags flags);

Sets flags on self

This function will emit notifications for the changed properties

Parameters

self

a ClutterActor

 

flags

the flags to set

 

Since: 1.0


clutter_actor_unset_flags ()

void
clutter_actor_unset_flags (ClutterActor *self,
                           ClutterActorFlags flags);

Unsets flags on self

This function will emit notifications for the changed properties

Parameters

self

a ClutterActor

 

flags

the flags to unset

 

Since: 1.0


clutter_actor_get_flags ()

ClutterActorFlags
clutter_actor_get_flags (ClutterActor *self);

Retrieves the flags set on self

Parameters

self

a ClutterActor

 

Returns

a bitwise or of ClutterActorFlags or 0

Since: 1.0


clutter_actor_set_name ()

void
clutter_actor_set_name (ClutterActor *self,
                        const gchar *name);

Sets the given name to self . The name can be used to identify a ClutterActor.

Parameters

self

A ClutterActor

 

name

Textual tag to apply to actor

 

clutter_actor_get_name ()

const gchar *
clutter_actor_get_name (ClutterActor *self);

Retrieves the name of self .

Parameters

self

A ClutterActor

 

Returns

the name of the actor, or NULL. The returned string is owned by the actor and should not be modified or freed.


clutter_actor_get_gid ()

guint32
clutter_actor_get_gid (ClutterActor *self);

clutter_actor_get_gid has been deprecated since version 1.8 and should not be used in newly-written code.

The id is not used any longer, and this function always returns 0.

Retrieves the unique id for self .

Parameters

self

A ClutterActor

 

Returns

Globally unique value for this object instance.

Since: 0.6


clutter_actor_show ()

void
clutter_actor_show (ClutterActor *self);

Flags an actor to be displayed. An actor that isn't shown will not be rendered on the stage.

Actors are visible by default.

If this function is called on an actor without a parent, the “show-on-set-parent” will be set to TRUE as a side effect.

Parameters

self

A ClutterActor

 

clutter_actor_show_all ()

void
clutter_actor_show_all (ClutterActor *self);

clutter_actor_show_all has been deprecated since version 1.10 and should not be used in newly-written code.

Actors are visible by default

Calls clutter_actor_show() on all children of an actor (if any).

Parameters

self

a ClutterActor

 

Since: 0.2


clutter_actor_hide ()

void
clutter_actor_hide (ClutterActor *self);

Flags an actor to be hidden. A hidden actor will not be rendered on the stage.

Actors are visible by default.

If this function is called on an actor without a parent, the “show-on-set-parent” property will be set to FALSE as a side-effect.

Parameters

self

A ClutterActor

 

clutter_actor_hide_all ()

void
clutter_actor_hide_all (ClutterActor *self);

clutter_actor_hide_all has been deprecated since version 1.10 and should not be used in newly-written code.

Using clutter_actor_hide() on the actor will prevent its children from being painted as well.

Calls clutter_actor_hide() on all child actors (if any).

Parameters

self

a ClutterActor

 

Since: 0.2


clutter_actor_is_visible ()

gboolean
clutter_actor_is_visible (ClutterActor *self);

Checks whether an actor is marked as visible.

See also CLUTTER_ACTOR_IS_VISIBLE and “visible”.

Parameters

self

a ClutterActor

 

Returns

TRUE if the actor visible

Since: 1.24


clutter_actor_realize ()

void
clutter_actor_realize (ClutterActor *self);

clutter_actor_realize has been deprecated since version 1.16 and should not be used in newly-written code.

Actors are automatically realized, and nothing requires explicit realization.

Realization informs the actor that it is attached to a stage. It can use this to allocate resources if it wanted to delay allocation until it would be rendered. However it is perfectly acceptable for an actor to create resources before being realized because Clutter only ever has a single rendering context so that actor is free to be moved from one stage to another.

This function does nothing if the actor is already realized.

Because a realized actor must have realized parent actors, calling clutter_actor_realize() will also realize all parents of the actor.

This function does not realize child actors, except in the special case that realizing the stage, when the stage is visible, will suddenly map (and thus realize) the children of the stage.

Parameters

self

A ClutterActor

 

clutter_actor_unrealize ()

void
clutter_actor_unrealize (ClutterActor *self);

clutter_actor_unrealize has been deprecated since version 1.16 and should not be used in newly-written code.

Actors are automatically unrealized, and nothing requires explicit realization.

Unrealization informs the actor that it may be being destroyed or moved to another stage. The actor may want to destroy any underlying graphics resources at this point. However it is perfectly acceptable for it to retain the resources until the actor is destroyed because Clutter only ever uses a single rendering context and all of the graphics resources are valid on any stage.

Because mapped actors must be realized, actors may not be unrealized if they are mapped. This function hides the actor to be sure it isn't mapped, an application-visible side effect that you may not be expecting.

This function should not be called by application code.

This function should not really be in the public API, because there isn't a good reason to call it. ClutterActor will already unrealize things for you when it's important to do so.

If you were using clutter_actor_unrealize() in a dispose implementation, then don't, just chain up to ClutterActor's dispose.

If you were using clutter_actor_unrealize() to implement unrealizing children of your container, then don't, ClutterActor will already take care of that.

Parameters

self

A ClutterActor

 

clutter_actor_is_realized ()

gboolean
clutter_actor_is_realized (ClutterActor *self);

Checks whether a ClutterActor is realized.

See also CLUTTER_ACTOR_IS_REALIZED and “realized”.

Parameters

self

a ClutterActor

 

Returns

TRUE if the actor is realized

Since: 1.24


clutter_actor_paint ()

void
clutter_actor_paint (ClutterActor *self);

Renders the actor to display.

This function should not be called directly by applications. Call clutter_actor_queue_redraw() to queue paints, instead.

This function is context-aware, and will either cause a regular paint or a pick paint.

This function will emit the “paint” signal or the “pick” signal, depending on the context.

This function does not paint the actor if the actor is set to 0, unless it is performing a pick paint.

Parameters

self

A ClutterActor

 

clutter_actor_continue_paint ()

void
clutter_actor_continue_paint (ClutterActor *self);

Run the next stage of the paint sequence. This function should only be called within the implementation of the ‘run’ virtual of a ClutterEffect. It will cause the run method of the next effect to be applied, or it will paint the actual actor if the current effect is the last effect in the chain.

Parameters

self

A ClutterActor

 

Since: 1.8


clutter_actor_queue_redraw ()

void
clutter_actor_queue_redraw (ClutterActor *self);

Queues up a redraw of an actor and any children. The redraw occurs once the main loop becomes idle (after the current batch of events has been processed, roughly).

Applications rarely need to call this, as redraws are handled automatically by modification functions.

This function will not do anything if self is not visible, or if the actor is inside an invisible part of the scenegraph.

Also be aware that painting is a NOP for actors with an opacity of 0

When you are implementing a custom actor you must queue a redraw whenever some private state changes that will affect painting or picking of your actor.

Parameters

self

A ClutterActor

 

clutter_actor_queue_redraw_with_clip ()

void
clutter_actor_queue_redraw_with_clip (ClutterActor *self,
                                      const cairo_rectangle_int_t *clip);

Queues a redraw on self limited to a specific, actor-relative rectangular area.

If clip is NULL this function is equivalent to clutter_actor_queue_redraw().

Parameters

self

a ClutterActor

 

clip

a rectangular clip region, or NULL.

[allow-none]

Since: 1.10


clutter_actor_queue_relayout ()

void
clutter_actor_queue_relayout (ClutterActor *self);

Indicates that the actor's size request or other layout-affecting properties may have changed. This function is used inside ClutterActor subclass implementations, not by applications directly.

Queueing a new layout automatically queues a redraw as well.

Parameters

self

A ClutterActor

 

Since: 0.8


clutter_actor_destroy ()

void
clutter_actor_destroy (ClutterActor *self);

Destroys an actor. When an actor is destroyed, it will break any references it holds to other objects. If the actor is inside a container, the actor will be removed.

When you destroy a container, its children will be destroyed as well.

Note: you cannot destroy the ClutterStage returned by clutter_stage_get_default().

Parameters

self

a ClutterActor

 

clutter_actor_event ()

gboolean
clutter_actor_event (ClutterActor *actor,
                     const ClutterEvent *event,
                     gboolean capture);

This function is used to emit an event on the main stage. You should rarely need to use this function, except for synthetising events.

Parameters

actor

a ClutterActor

 

event

a ClutterEvent

 

capture

TRUE if event in in capture phase, FALSE otherwise.

 

Returns

the return value from the signal emission: TRUE if the actor handled the event, or FALSE if the event was not handled

Since: 0.6


clutter_actor_should_pick_paint ()

gboolean
clutter_actor_should_pick_paint (ClutterActor *self);

Should be called inside the implementation of the “pick” virtual function in order to check whether the actor should paint itself in pick mode or not.

This function should never be called directly by applications.

Parameters

self

A ClutterActor

 

Returns

TRUE if the actor should paint its silhouette, FALSE otherwise


clutter_actor_map ()

void
clutter_actor_map (ClutterActor *self);

Sets the CLUTTER_ACTOR_MAPPED flag on the actor and possibly maps and realizes its children if they are visible. Does nothing if the actor is not visible.

Calling this function is strongly disencouraged: the default implementation of ClutterActorClass.map() will map all the children of an actor when mapping its parent.

When overriding map, it is mandatory to chain up to the parent implementation.

Parameters

self

A ClutterActor

 

Since: 1.0


clutter_actor_unmap ()

void
clutter_actor_unmap (ClutterActor *self);

Unsets the CLUTTER_ACTOR_MAPPED flag on the actor and possibly unmaps its children if they were mapped.

Calling this function is not encouraged: the default ClutterActor implementation of ClutterActorClass.unmap() will also unmap any eventual children by default when their parent is unmapped.

When overriding ClutterActorClass.unmap(), it is mandatory to chain up to the parent implementation.

It is important to note that the implementation of the ClutterActorClass.unmap() virtual function may be called after the ClutterActorClass.destroy() or the GObjectClass.dispose() implementation, but it is guaranteed to be called before the GObjectClass.finalize() implementation.

Parameters

self

A ClutterActor

 

Since: 1.0


clutter_actor_is_mapped ()

gboolean
clutter_actor_is_mapped (ClutterActor *self);

Checks whether a ClutterActor has been set as mapped.

See also CLUTTER_ACTOR_IS_MAPPED and “mapped”

Parameters

self

a ClutterActor

 

Returns

TRUE if the actor is mapped

Since: 1.24


clutter_actor_has_overlaps ()

gboolean
clutter_actor_has_overlaps (ClutterActor *self);

Asks the actor's implementation whether it may contain overlapping primitives.

For example; Clutter may use this to determine whether the painting should be redirected to an offscreen buffer to correctly implement the opacity property.

Custom actors can override the default response by implementing the ClutterActorClass.has_overlaps() virtual function. See clutter_actor_set_offscreen_redirect() for more information.

Parameters

self

A ClutterActor

 

Returns

TRUE if the actor may have overlapping primitives, and FALSE otherwise

Since: 1.8


clutter_actor_has_mapped_clones ()

gboolean
clutter_actor_has_mapped_clones (ClutterActor *self);

Returns whether a ClutterActor has any mapped clones.

Return: TRUE if the actor has mapped clones, and FALSE otherwise

Parameters

self

a ClutterActor

 

Since: 1.16


clutter_actor_allocate ()

void
clutter_actor_allocate (ClutterActor *self,
                        const ClutterActorBox *box,
                        ClutterAllocationFlags flags);

Assigns the size of a ClutterActor from the given box .

This function should only be called on the children of an actor when overriding the ClutterActorClass.allocate() virtual function.

This function will adjust the stored allocation to take into account the alignment flags set in the “x-align” and “y-align” properties, as well as the margin values set in the “margin-top”, “margin-right”, “margin-bottom”, and “margin-left” properties.

This function will respect the easing state of the ClutterActor and interpolate between the current allocation and the new one if the easing state duration is a positive value.

Actors can know from their allocation box whether they have moved with respect to their parent actor. The flags parameter describes additional information about the allocation, for instance whether the parent has moved with respect to the stage, for example because a grandparent's origin has moved.

Parameters

self

A ClutterActor

 

box

new allocation of the actor, in parent-relative coordinates

 

flags

flags that control the allocation

 

Since: 0.8


clutter_actor_allocate_preferred_size ()

void
clutter_actor_allocate_preferred_size (ClutterActor *self,
                                       ClutterAllocationFlags flags);

Allocates the natural size of self .

This function is a utility call for ClutterActor implementations that allocates the actor's preferred natural size. It can be used by fixed layout managers (like ClutterGroup or so called 'composite actors') inside the ClutterActor::allocate implementation to give each child exactly how much space it requires, regardless of the size of the parent.

This function is not meant to be used by applications. It is also not meant to be used outside the implementation of the ClutterActorClass.allocate virtual function.

Parameters

self

a ClutterActor

 

flags

flags controlling the allocation

 

Since: 0.8


clutter_actor_allocate_available_size ()

void
clutter_actor_allocate_available_size (ClutterActor *self,
                                       gfloat x,
                                       gfloat y,
                                       gfloat available_width,
                                       gfloat available_height,
                                       ClutterAllocationFlags flags);

Allocates self taking into account the ClutterActor's preferred size, but limiting it to the maximum available width and height provided.

This function will do the right thing when dealing with the actor's request mode.

The implementation of this function is equivalent to:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
if (request_mode == CLUTTER_REQUEST_HEIGHT_FOR_WIDTH)
  {
    clutter_actor_get_preferred_width (self, available_height,
                                       &min_width,
                                       &natural_width);
    width = CLAMP (natural_width, min_width, available_width);

    clutter_actor_get_preferred_height (self, width,
                                        &min_height,
                                        &natural_height);
    height = CLAMP (natural_height, min_height, available_height);
  }
else if (request_mode == CLUTTER_REQUEST_WIDTH_FOR_HEIGHT)
  {
    clutter_actor_get_preferred_height (self, available_width,
                                        &min_height,
                                        &natural_height);
    height = CLAMP (natural_height, min_height, available_height);

    clutter_actor_get_preferred_width (self, height,
                                       &min_width,
                                       &natural_width);
    width = CLAMP (natural_width, min_width, available_width);
  }
else if (request_mode == CLUTTER_REQUEST_CONTENT_SIZE)
  {
    clutter_content_get_preferred_size (content, &natural_width, &natural_height);

    width = CLAMP (natural_width, 0, available_width);
    height = CLAMP (natural_height, 0, available_height);
  }

box.x1 = x; box.y1 = y;
box.x2 = box.x1 + available_width;
box.y2 = box.y1 + available_height;
clutter_actor_allocate (self, &box, flags);

This function can be used by fluid layout managers to allocate an actor's preferred size without making it bigger than the area available for the container.

Parameters

self

a ClutterActor

 

x

the actor's X coordinate

 

y

the actor's Y coordinate

 

available_width

the maximum available width, or -1 to use the actor's natural width

 

available_height

the maximum available height, or -1 to use the actor's natural height

 

flags

flags controlling the allocation

 

Since: 1.0


clutter_actor_allocate_align_fill ()

void
clutter_actor_allocate_align_fill (ClutterActor *self,
                                   const ClutterActorBox *box,
                                   gdouble x_align,
                                   gdouble y_align,
                                   gboolean x_fill,
                                   gboolean y_fill,
                                   ClutterAllocationFlags flags);

Allocates self by taking into consideration the available allocation area; an alignment factor on either axis; and whether the actor should fill the allocation on either axis.

The box should contain the available allocation width and height; if the x1 and y1 members of ClutterActorBox are not set to 0, the allocation will be offset by their value.

This function takes into consideration the geometry request specified by the “request-mode” property, and the text direction.

This function is useful for fluid layout managers using legacy alignment flags. Newly written layout managers should use the “x-align” and “y-align” properties, instead, and just call clutter_actor_allocate() inside their ClutterActorClass.allocate() implementation.

Parameters

self

a ClutterActor

 

box

a ClutterActorBox, containing the available width and height

 

x_align

the horizontal alignment, between 0 and 1

 

y_align

the vertical alignment, between 0 and 1

 

x_fill

whether the actor should fill horizontally

 

y_fill

whether the actor should fill vertically

 

flags

allocation flags to be passed to clutter_actor_allocate()

 

Since: 1.4


clutter_actor_set_allocation ()

void
clutter_actor_set_allocation (ClutterActor *self,
                              const ClutterActorBox *box,
                              ClutterAllocationFlags flags);

Stores the allocation of self as defined by box .

This function can only be called from within the implementation of the ClutterActorClass.allocate() virtual function.

The allocation should have been adjusted to take into account constraints, alignment, and margin properties. If you are implementing a ClutterActor subclass that provides its own layout management policy for its children instead of using a ClutterLayoutManager delegate, you should not call this function on the children of self ; instead, you should call clutter_actor_allocate(), which will adjust the allocation box for you.

This function should only be used by subclasses of ClutterActor that wish to store their allocation but cannot chain up to the parent's implementation; the default implementation of the ClutterActorClass.allocate() virtual function will call this function.

It is important to note that, while chaining up was the recommended behaviour for ClutterActor subclasses prior to the introduction of this function, it is recommended to call clutter_actor_set_allocation() instead.

If the ClutterActor is using a ClutterLayoutManager delegate object to handle the allocation of its children, this function will call the clutter_layout_manager_allocate() function only if the CLUTTER_DELEGATE_LAYOUT flag is set on flags , otherwise it is expected that the subclass will call clutter_layout_manager_allocate() by itself. For instance, the following code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
static void
my_actor_allocate (ClutterActor *actor,
                   const ClutterActorBox *allocation,
                   ClutterAllocationFlags flags)
{
  ClutterActorBox new_alloc;
  ClutterAllocationFlags new_flags;

  adjust_allocation (allocation, &new_alloc);

  new_flags = flags | CLUTTER_DELEGATE_LAYOUT;

  // this will use the layout manager set on the actor
  clutter_actor_set_allocation (actor, &new_alloc, new_flags);
}

is equivalent to this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
static void
my_actor_allocate (ClutterActor *actor,
                   const ClutterActorBox *allocation,
                   ClutterAllocationFlags flags)
{
  ClutterLayoutManager *layout;
  ClutterActorBox new_alloc;

  adjust_allocation (allocation, &new_alloc);

  clutter_actor_set_allocation (actor, &new_alloc, flags);

  layout = clutter_actor_get_layout_manager (actor);
  clutter_layout_manager_allocate (layout,
                                   CLUTTER_CONTAINER (actor),
                                   &new_alloc,
                                   flags);
}

Parameters

self

a ClutterActor

 

box

a ClutterActorBox

 

flags

allocation flags

 

Since: 1.10


clutter_actor_get_allocation_box ()

void
clutter_actor_get_allocation_box (ClutterActor *self,
                                  ClutterActorBox *box);

Gets the layout box an actor has been assigned. The allocation can only be assumed valid inside a paint() method; anywhere else, it may be out-of-date.

An allocation does not incorporate the actor's scale or anchor point; those transformations do not affect layout, only rendering.

Do not call any of the clutter_actor_get_allocation_*() family of functions inside the implementation of the get_preferred_width() or get_preferred_height() virtual functions.

Parameters

self

A ClutterActor

 

box

the function fills this in with the actor's allocation.

[out]

Since: 0.8


clutter_actor_get_allocation_geometry ()

void
clutter_actor_get_allocation_geometry (ClutterActor *self,
                                       ClutterGeometry *geom);

clutter_actor_get_allocation_geometry has been deprecated since version 1.12 and should not be used in newly-written code.

Use clutter_actor_get_allocation_box() instead.

Gets the layout box an actor has been assigned. The allocation can only be assumed valid inside a paint() method; anywhere else, it may be out-of-date.

An allocation does not incorporate the actor's scale or anchor point; those transformations do not affect layout, only rendering.

The returned rectangle is in pixels.

Parameters

self

A ClutterActor

 

geom

allocation geometry in pixels.

[out]

Since: 0.8


clutter_actor_get_allocation_vertices ()

void
clutter_actor_get_allocation_vertices (ClutterActor *self,
                                       ClutterActor *ancestor,
                                       ClutterVertex verts[]);

Calculates the transformed coordinates of the four corners of the actor in the plane of ancestor . The returned vertices relate to the ClutterActorBox coordinates as follows:

  • verts [0] contains (x1, y1)

  • verts [1] contains (x2, y1)

  • verts [2] contains (x1, y2)

  • verts [3] contains (x2, y2)

If ancestor is NULL the ancestor will be the ClutterStage. In this case, the coordinates returned will be the coordinates on the stage before the projection is applied. This is different from the behaviour of clutter_actor_get_abs_allocation_vertices().

Parameters

self

A ClutterActor

 

ancestor

A ClutterActor to calculate the vertices against, or NULL to use the ClutterStage.

[allow-none]

verts

return location for an array of 4 ClutterVertex in which to store the result.

[out][array fixed-size=4][element-type Clutter.Vertex]

Since: 0.6


clutter_actor_get_preferred_size ()

void
clutter_actor_get_preferred_size (ClutterActor *self,
                                  gfloat *min_width_p,
                                  gfloat *min_height_p,
                                  gfloat *natural_width_p,
                                  gfloat *natural_height_p);

Computes the preferred minimum and natural size of an actor, taking into account the actor's geometry management (either height-for-width or width-for-height).

The width and height used to compute the preferred height and preferred width are the actor's natural ones.

If you need to control the height for the preferred width, or the width for the preferred height, you should use clutter_actor_get_preferred_width() and clutter_actor_get_preferred_height(), and check the actor's preferred geometry management using the “request-mode” property.

Parameters

self

a ClutterActor

 

min_width_p

return location for the minimum width, or NULL.

[out][allow-none]

min_height_p

return location for the minimum height, or NULL.

[out][allow-none]

natural_width_p

return location for the natural width, or NULL.

[out][allow-none]

natural_height_p

return location for the natural height, or NULL.

[out][allow-none]

Since: 0.8


clutter_actor_get_preferred_width ()

void
clutter_actor_get_preferred_width (ClutterActor *self,
                                   gfloat for_height,
                                   gfloat *min_width_p,
                                   gfloat *natural_width_p);

Computes the requested minimum and natural widths for an actor, optionally depending on the specified height, or if they are already computed, returns the cached values.

An actor may not get its request - depending on the layout manager that's in effect.

A request should not incorporate the actor's scale or anchor point; those transformations do not affect layout, only rendering.

Parameters

self

A ClutterActor

 

for_height

available height when computing the preferred width, or a negative value to indicate that no height is defined

 

min_width_p

return location for minimum width, or NULL.

[out][allow-none]

natural_width_p

return location for the natural width, or NULL.

[out][allow-none]

Since: 0.8


clutter_actor_get_preferred_height ()

void
clutter_actor_get_preferred_height (ClutterActor *self,
                                    gfloat for_width,
                                    gfloat *min_height_p,
                                    gfloat *natural_height_p);

Computes the requested minimum and natural heights for an actor, or if they are already computed, returns the cached values.

An actor may not get its request - depending on the layout manager that's in effect.

A request should not incorporate the actor's scale or anchor point; those transformations do not affect layout, only rendering.

Parameters

self

A ClutterActor

 

for_width

available width to assume in computing desired height, or a negative value to indicate that no width is defined

 

min_height_p

return location for minimum height, or NULL.

[out][allow-none]

natural_height_p

return location for natural height, or NULL.

[out][allow-none]

Since: 0.8


clutter_actor_set_fixed_position_set ()

void
clutter_actor_set_fixed_position_set (ClutterActor *self,
                                      gboolean is_set);

Sets whether an actor has a fixed position set (and will thus be unaffected by any layout manager).

Parameters

self

A ClutterActor

 

is_set

whether to use fixed position

 

Since: 0.8


clutter_actor_get_fixed_position_set ()

gboolean
clutter_actor_get_fixed_position_set (ClutterActor *self);

Checks whether an actor has a fixed position set (and will thus be unaffected by any layout manager).

Parameters

self

A ClutterActor

 

Returns

TRUE if the fixed position is set on the actor

Since: 0.8


clutter_actor_set_request_mode ()

void
clutter_actor_set_request_mode (ClutterActor *self,
                                ClutterRequestMode mode);

Sets the geometry request mode of self .

The mode determines the order for invoking clutter_actor_get_preferred_width() and clutter_actor_get_preferred_height()

Parameters

self

a ClutterActor

 

mode

the request mode

 

Since: 1.2


clutter_actor_get_request_mode ()

ClutterRequestMode
clutter_actor_get_request_mode (ClutterActor *self);

Retrieves the geometry request mode of self

Parameters

self

a ClutterActor

 

Returns

the request mode for the actor

Since: 1.2


clutter_actor_has_allocation ()

gboolean
clutter_actor_has_allocation (ClutterActor *self);

Checks if the actor has an up-to-date allocation assigned to it. This means that the actor should have an allocation: it's visible and has a parent. It also means that there is no outstanding relayout request in progress for the actor or its children (There might be other outstanding layout requests in progress that will cause the actor to get a new allocation when the stage is laid out, however).

If this function returns FALSE, then the actor will normally be allocated before it is next drawn on the screen.

Parameters

self

a ClutterActor

 

Returns

TRUE if the actor has an up-to-date allocation

Since: 1.4


clutter_actor_set_x_align ()

void
clutter_actor_set_x_align (ClutterActor *self,
                           ClutterActorAlign x_align);

Sets the horizontal alignment policy of a ClutterActor, in case the actor received extra horizontal space.

See also the “x-align” property.

Parameters

self

a ClutterActor

 

x_align

the horizontal alignment policy

 

Since: 1.10


clutter_actor_get_x_align ()

ClutterActorAlign
clutter_actor_get_x_align (ClutterActor *self);

Retrieves the horizontal alignment policy set using clutter_actor_set_x_align().

Parameters

self

a ClutterActor

 

Returns

the horizontal alignment policy.

Since: 1.10


clutter_actor_set_y_align ()

void
clutter_actor_set_y_align (ClutterActor *self,
                           ClutterActorAlign y_align);

Sets the vertical alignment policy of a ClutterActor, in case the actor received extra vertical space.

See also the “y-align” property.

Parameters

self

a ClutterActor

 

y_align

the vertical alignment policy

 

Since: 1.10


clutter_actor_get_y_align ()

ClutterActorAlign
clutter_actor_get_y_align (ClutterActor *self);

Retrieves the vertical alignment policy set using clutter_actor_set_y_align().

Parameters

self

a ClutterActor

 

Returns

the vertical alignment policy.

Since: 1.10


clutter_margin_copy ()

ClutterMargin *
clutter_margin_copy (const ClutterMargin *margin_);

Creates a new ClutterMargin and copies the contents of margin_ into the newly created structure.

Parameters

margin_

a ClutterMargin

 

Returns

a copy of the ClutterMargin.

[transfer full]

Since: 1.10


clutter_margin_free ()

void
clutter_margin_free (ClutterMargin *margin_);

Frees the resources allocated by clutter_margin_new() and clutter_margin_copy().

Parameters

margin_

a ClutterMargin

 

Since: 1.10


clutter_margin_new ()

ClutterMargin *
clutter_margin_new (void);

Creates a new ClutterMargin.

Returns

a newly allocated ClutterMargin. Use clutter_margin_free() to free the resources associated with it when done.

[transfer full]

Since: 1.10


clutter_actor_set_margin ()

void
clutter_actor_set_margin (ClutterActor *self,
                          const ClutterMargin *margin);

Sets all the components of the margin of a ClutterActor.

Parameters

self

a ClutterActor

 

margin

a ClutterMargin

 

Since: 1.10


clutter_actor_get_margin ()

void
clutter_actor_get_margin (ClutterActor *self,
                          ClutterMargin *margin);

Retrieves all the components of the margin of a ClutterActor.

Parameters

self

a ClutterActor

 

margin

return location for a ClutterMargin.

[out caller-allocates]

Since: 1.10


clutter_actor_set_margin_top ()

void
clutter_actor_set_margin_top (ClutterActor *self,
                              gfloat margin);

Sets the margin from the top of a ClutterActor.

The “margin-top” property is animatable.

Parameters

self

a ClutterActor

 

margin

the top margin

 

Since: 1.10


clutter_actor_get_margin_top ()

gfloat
clutter_actor_get_margin_top (ClutterActor *self);

Retrieves the top margin of a ClutterActor.

Parameters

self

a ClutterActor

 

Returns

the top margin

Since: 1.10


clutter_actor_set_margin_right ()

void
clutter_actor_set_margin_right (ClutterActor *self,
                                gfloat margin);

Sets the margin from the right of a ClutterActor.

The “margin-right” property is animatable.

Parameters

self

a ClutterActor

 

margin

the right margin

 

Since: 1.10


clutter_actor_get_margin_right ()

gfloat
clutter_actor_get_margin_right (ClutterActor *self);

Retrieves the right margin of a ClutterActor.

Parameters

self

a ClutterActor

 

Returns

the right margin

Since: 1.10


clutter_actor_set_margin_bottom ()

void
clutter_actor_set_margin_bottom (ClutterActor *self,
                                 gfloat margin);

Sets the margin from the bottom of a ClutterActor.

The “margin-bottom” property is animatable.

Parameters

self

a ClutterActor

 

margin

the bottom margin

 

Since: 1.10


clutter_actor_get_margin_bottom ()

gfloat
clutter_actor_get_margin_bottom (ClutterActor *self);

Retrieves the bottom margin of a ClutterActor.

Parameters

self

a ClutterActor

 

Returns

the bottom margin

Since: 1.10


clutter_actor_set_margin_left ()

void
clutter_actor_set_margin_left (ClutterActor *self,
                               gfloat margin);

Sets the margin from the left of a ClutterActor.

The “margin-left” property is animatable.

Parameters

self

a ClutterActor

 

margin

the left margin

 

Since: 1.10


clutter_actor_get_margin_left ()

gfloat
clutter_actor_get_margin_left (ClutterActor *self);

Retrieves the left margin of a ClutterActor.

Parameters

self

a ClutterActor

 

Returns

the left margin

Since: 1.10


clutter_actor_set_x_expand ()

void
clutter_actor_set_x_expand (ClutterActor *self,
                            gboolean expand);

Sets whether a ClutterActor should expand horizontally; this means that layout manager should allocate extra space for the actor, if possible.

Setting an actor to expand will also make all its parent expand, so that it's possible to build an actor tree and only set this flag on its leaves and not on every single actor.

Parameters

self

a ClutterActor

 

expand

whether the actor should expand horizontally

 

Since: 1.12


clutter_actor_get_x_expand ()

gboolean
clutter_actor_get_x_expand (ClutterActor *self);

Retrieves the value set with clutter_actor_set_x_expand().

See also: clutter_actor_needs_expand()

Parameters

self

a ClutterActor

 

Returns

TRUE if the actor has been set to expand

Since: 1.12


clutter_actor_set_y_expand ()

void
clutter_actor_set_y_expand (ClutterActor *self,
                            gboolean expand);

Sets whether a ClutterActor should expand horizontally; this means that layout manager should allocate extra space for the actor, if possible.

Setting an actor to expand will also make all its parent expand, so that it's possible to build an actor tree and only set this flag on its leaves and not on every single actor.

Parameters

self

a ClutterActor

 

expand

whether the actor should expand vertically

 

Since: 1.12


clutter_actor_get_y_expand ()

gboolean
clutter_actor_get_y_expand (ClutterActor *self);

Retrieves the value set with clutter_actor_set_y_expand().

See also: clutter_actor_needs_expand()

Parameters

self

a ClutterActor

 

Returns

TRUE if the actor has been set to expand

Since: 1.12


clutter_actor_needs_expand ()

gboolean
clutter_actor_needs_expand (ClutterActor *self,
                            ClutterOrientation orientation);

Checks whether an actor, or any of its children, is set to expand horizontally or vertically.

This function should only be called by layout managers that can assign extra space to their children.

If you want to know whether the actor was explicitly set to expand, use clutter_actor_get_x_expand() or clutter_actor_get_y_expand().

Parameters

self

a ClutterActor

 

orientation

the direction of expansion

 

Returns

TRUE if the actor should expand

Since: 1.12


clutter_actor_set_layout_manager ()

void
clutter_actor_set_layout_manager (ClutterActor *self,
                                  ClutterLayoutManager *manager);

Sets the ClutterLayoutManager delegate object that will be used to lay out the children of self .

The ClutterActor will take a reference on the passed manager which will be released either when the layout manager is removed, or when the actor is destroyed.

Parameters

self

a ClutterActor

 

manager

a ClutterLayoutManager, or NULL to unset it.

[allow-none]

Since: 1.10


clutter_actor_get_layout_manager ()

ClutterLayoutManager *
clutter_actor_get_layout_manager (ClutterActor *self);

Retrieves the ClutterLayoutManager used by self .

Parameters

self

a ClutterActor

 

Returns

a pointer to the ClutterLayoutManager, or NULL.

[transfer none]

Since: 1.10


clutter_actor_set_background_color ()

void
clutter_actor_set_background_color (ClutterActor *self,
                                    const ClutterColor *color);

Sets the background color of a ClutterActor.

The background color will be used to cover the whole allocation of the actor. The default background color of an actor is transparent.

To check whether an actor has a background color, you can use the “background-color-set” actor property.

The “background-color” property is animatable.

Parameters

self

a ClutterActor

 

color

a ClutterColor, or NULL to unset a previously set color.

[allow-none]

Since: 1.10


clutter_actor_get_background_color ()

void
clutter_actor_get_background_color (ClutterActor *self,
                                    ClutterColor *color);

Retrieves the color set using clutter_actor_set_background_color().

Parameters

self

a ClutterActor

 

color

return location for a ClutterColor.

[out caller-allocates]

Since: 1.10


clutter_actor_set_geometry ()

void
clutter_actor_set_geometry (ClutterActor *self,
                            const ClutterGeometry *geometry);

clutter_actor_set_geometry has been deprecated since version 1.10 and should not be used in newly-written code.

Use clutter_actor_set_position() and clutter_actor_set_size() instead.

Sets the actor's fixed position and forces its minimum and natural size, in pixels. This means the untransformed actor will have the given geometry. This is the same as calling clutter_actor_set_position() and clutter_actor_set_size().

Parameters

self

A ClutterActor

 

geometry

A ClutterGeometry

 

clutter_actor_get_geometry ()

void
clutter_actor_get_geometry (ClutterActor *self,
                            ClutterGeometry *geometry);

clutter_actor_get_geometry has been deprecated since version 1.10 and should not be used in newly-written code.

Use clutter_actor_get_position() and clutter_actor_get_size(), or clutter_actor_get_allocation_geometry() instead.

Gets the size and position of an actor relative to its parent actor. This is the same as calling clutter_actor_get_position() and clutter_actor_get_size(). It tries to "do what you mean" and get the requested size and position if the actor's allocation is invalid.

Parameters

self

A ClutterActor

 

geometry

A location to store actors ClutterGeometry.

[out caller-allocates]

clutter_actor_set_size ()

void
clutter_actor_set_size (ClutterActor *self,
                        gfloat width,
                        gfloat height);

Sets the actor's size request in pixels. This overrides any "normal" size request the actor would have. For example a text actor might normally request the size of the text; this function would force a specific size instead.

If width and/or height are -1 the actor will use its "normal" size request instead of overriding it, i.e. you can "unset" the size with -1.

This function sets or unsets both the minimum and natural size.

Parameters

self

A ClutterActor

 

width

New width of actor in pixels, or -1

 

height

New height of actor in pixels, or -1

 

clutter_actor_get_size ()

void
clutter_actor_get_size (ClutterActor *self,
                        gfloat *width,
                        gfloat *height);

This function tries to "do what you mean" and return the size an actor will have. If the actor has a valid allocation, the allocation will be returned; otherwise, the actors natural size request will be returned.

If you care whether you get the request vs. the allocation, you should probably call a different function like clutter_actor_get_allocation_box() or clutter_actor_get_preferred_width().

Parameters

self

A ClutterActor

 

width

return location for the width, or NULL.

[out][allow-none]

height

return location for the height, or NULL.

[out][allow-none]

Since: 0.2


clutter_actor_set_position ()

void
clutter_actor_set_position (ClutterActor *self,
                            gfloat x,
                            gfloat y);

Sets the actor's fixed position in pixels relative to any parent actor.

If a layout manager is in use, this position will override the layout manager and force a fixed position.

Parameters

self

A ClutterActor

 

x

New left position of actor in pixels.

 

y

New top position of actor in pixels.

 

clutter_actor_get_position ()

void
clutter_actor_get_position (ClutterActor *self,
                            gfloat *x,
                            gfloat *y);

This function tries to "do what you mean" and tell you where the actor is, prior to any transformations. Retrieves the fixed position of an actor in pixels, if one has been set; otherwise, if the allocation is valid, returns the actor's allocated position; otherwise, returns 0,0.

The returned position is in pixels.

Parameters

self

a ClutterActor

 

x

return location for the X coordinate, or NULL.

[out][allow-none]

y

return location for the Y coordinate, or NULL.

[out][allow-none]

Since: 0.6


clutter_actor_set_width ()

void
clutter_actor_set_width (ClutterActor *self,
                         gfloat width);

Forces a width on an actor, causing the actor's preferred width and height (if any) to be ignored.

If width is -1 the actor will use its preferred width request instead of overriding it, i.e. you can "unset" the width with -1.

This function sets both the minimum and natural size of the actor.

Parameters

self

A ClutterActor

 

width

Requested new width for the actor, in pixels, or -1

 

Since: 0.2


clutter_actor_get_width ()

gfloat
clutter_actor_get_width (ClutterActor *self);

Retrieves the width of a ClutterActor.

If the actor has a valid allocation, this function will return the width of the allocated area given to the actor.

If the actor does not have a valid allocation, this function will return the actor's natural width, that is the preferred width of the actor.

If you care whether you get the preferred width or the width that has been assigned to the actor, you should probably call a different function like clutter_actor_get_allocation_box() to retrieve the allocated size or clutter_actor_get_preferred_width() to retrieve the preferred width.

If an actor has a fixed width, for instance a width that has been assigned using clutter_actor_set_width(), the width returned will be the same value.

Parameters

self

A ClutterActor

 

Returns

the width of the actor, in pixels


clutter_actor_set_height ()

void
clutter_actor_set_height (ClutterActor *self,
                          gfloat height);

Forces a height on an actor, causing the actor's preferred width and height (if any) to be ignored.

If height is -1 the actor will use its preferred height instead of overriding it, i.e. you can "unset" the height with -1.

This function sets both the minimum and natural size of the actor.

Parameters

self

A ClutterActor

 

height

Requested new height for the actor, in pixels, or -1

 

Since: 0.2


clutter_actor_get_height ()

gfloat
clutter_actor_get_height (ClutterActor *self);

Retrieves the height of a ClutterActor.

If the actor has a valid allocation, this function will return the height of the allocated area given to the actor.

If the actor does not have a valid allocation, this function will return the actor's natural height, that is the preferred height of the actor.

If you care whether you get the preferred height or the height that has been assigned to the actor, you should probably call a different function like clutter_actor_get_allocation_box() to retrieve the allocated size or clutter_actor_get_preferred_height() to retrieve the preferred height.

If an actor has a fixed height, for instance a height that has been assigned using clutter_actor_set_height(), the height returned will be the same value.

Parameters

self

A ClutterActor

 

Returns

the height of the actor, in pixels


clutter_actor_set_x ()

void
clutter_actor_set_x (ClutterActor *self,
                     gfloat x);

Sets the actor's X coordinate, relative to its parent, in pixels.

Overrides any layout manager and forces a fixed position for the actor.

The “x” property is animatable.

Parameters

self

a ClutterActor

 

x

the actor's position on the X axis

 

Since: 0.6


clutter_actor_get_x ()

gfloat
clutter_actor_get_x (ClutterActor *self);

Retrieves the X coordinate of a ClutterActor.

This function tries to "do what you mean", by returning the correct value depending on the actor's state.

If the actor has a valid allocation, this function will return the X coordinate of the origin of the allocation box.

If the actor has any fixed coordinate set using clutter_actor_set_x(), clutter_actor_set_position() or clutter_actor_set_geometry(), this function will return that coordinate.

If both the allocation and a fixed position are missing, this function will return 0.

Parameters

self

A ClutterActor

 

Returns

the X coordinate, in pixels, ignoring any transformation (i.e. scaling, rotation)


clutter_actor_set_y ()

void
clutter_actor_set_y (ClutterActor *self,
                     gfloat y);

Sets the actor's Y coordinate, relative to its parent, in pixels.#

Overrides any layout manager and forces a fixed position for the actor.

The “y” property is animatable.

Parameters

self

a ClutterActor

 

y

the actor's position on the Y axis

 

Since: 0.6


clutter_actor_get_y ()

gfloat
clutter_actor_get_y (ClutterActor *self);

Retrieves the Y coordinate of a ClutterActor.

This function tries to "do what you mean", by returning the correct value depending on the actor's state.

If the actor has a valid allocation, this function will return the Y coordinate of the origin of the allocation box.

If the actor has any fixed coordinate set using clutter_actor_set_y(), clutter_actor_set_position() or clutter_actor_set_geometry(), this function will return that coordinate.

If both the allocation and a fixed position are missing, this function will return 0.

Parameters

self

A ClutterActor

 

Returns

the Y coordinate, in pixels, ignoring any transformation (i.e. scaling, rotation)


clutter_actor_move_by ()

void
clutter_actor_move_by (ClutterActor *self,
                       gfloat dx,
                       gfloat dy);

Moves an actor by the specified distance relative to its current position in pixels.

This function modifies the fixed position of an actor and thus removes it from any layout management. Another way to move an actor is with an anchor point, see clutter_actor_set_anchor_point(), or with an additional translation, using clutter_actor_set_translation().

Parameters

self

A ClutterActor

 

dx

Distance to move Actor on X axis.

 

dy

Distance to move Actor on Y axis.

 

Since: 0.2


clutter_actor_set_z_position ()

void
clutter_actor_set_z_position (ClutterActor *self,
                              gfloat z_position);

Sets the actor's position on the Z axis.

See “z-position”.

Parameters

self

a ClutterActor

 

z_position

the position on the Z axis

 

Since: 1.12


clutter_actor_get_z_position ()

gfloat
clutter_actor_get_z_position (ClutterActor *self);

Retrieves the actor's position on the Z axis.

Parameters

self

a ClutterActor

 

Returns

the position on the Z axis.

Since: 1.12


clutter_actor_set_pivot_point ()

void
clutter_actor_set_pivot_point (ClutterActor *self,
                               gfloat pivot_x,
                               gfloat pivot_y);

Sets the position of the “pivot-point” around which the scaling and rotation transformations occur.

The pivot point's coordinates are in normalized space, with the (0, 0) point being the top left corner of the actor, and the (1, 1) point being the bottom right corner.

Parameters

self

a ClutterActor

 

pivot_x

the normalized X coordinate of the pivot point

 

pivot_y

the normalized Y coordinate of the pivot point

 

Since: 1.12


clutter_actor_get_pivot_point ()

void
clutter_actor_get_pivot_point (ClutterActor *self,
                               gfloat *pivot_x,
                               gfloat *pivot_y);

Retrieves the coordinates of the “pivot-point”.

Parameters

self

a ClutterActor

 

pivot_x

return location for the normalized X coordinate of the pivot point, or NULL.

[out][allow-none]

pivot_y

return location for the normalized Y coordinate of the pivot point, or NULL.

[out][allow-none]

Since: 1.12


clutter_actor_set_pivot_point_z ()

void
clutter_actor_set_pivot_point_z (ClutterActor *self,
                                 gfloat pivot_z);

Sets the component on the Z axis of the “pivot-point” around which the scaling and rotation transformations occur.

The pivot_z value is expressed as a distance along the Z axis.

Parameters

self

a ClutterActor

 

pivot_z

the Z coordinate of the actor's pivot point

 

Since: 1.12


clutter_actor_get_pivot_point_z ()

gfloat
clutter_actor_get_pivot_point_z (ClutterActor *self);

Retrieves the Z component of the “pivot-point”.

Parameters

self

a ClutterActor

 

Since: 1.12


clutter_actor_set_scale ()

void
clutter_actor_set_scale (ClutterActor *self,
                         gdouble scale_x,
                         gdouble scale_y);

Scales an actor with the given factors.

The scale transformation is relative the the “pivot-point”.

The “scale-x” and “scale-y” properties are animatable.

Parameters

self

A ClutterActor

 

scale_x

double factor to scale actor by horizontally.

 

scale_y

double factor to scale actor by vertically.

 

Since: 0.2


clutter_actor_get_scale ()

void
clutter_actor_get_scale (ClutterActor *self,
                         gdouble *scale_x,
                         gdouble *scale_y);

Retrieves an actors scale factors.

Parameters

self

A ClutterActor

 

scale_x

Location to store horizonal scale factor, or NULL.

[out][allow-none]

scale_y

Location to store vertical scale factor, or NULL.

[out][allow-none]

Since: 0.2


clutter_actor_set_scale_z ()

void
clutter_actor_set_scale_z (ClutterActor *self,
                           gdouble scale_z);

Scales an actor on the Z axis by the given scale_z factor.

The scale transformation is relative the the “pivot-point”.

The “scale-z” property is animatable.

Parameters

self

a ClutterActor

 

scale_z

the scaling factor along the Z axis

 

Since: 1.12


clutter_actor_get_scale_z ()

gdouble
clutter_actor_get_scale_z (ClutterActor *self);

Retrieves the scaling factor along the Z axis, as set using clutter_actor_set_scale_z().

Parameters

self

A ClutterActor

 

Returns

the scaling factor along the Z axis

Since: 1.12


clutter_actor_is_scaled ()

gboolean
clutter_actor_is_scaled (ClutterActor *self);

Checks whether the actor is scaled in either dimension.

Parameters

self

a ClutterActor

 

Returns

TRUE if the actor is scaled.

Since: 0.6


clutter_actor_set_rotation_angle ()

void
clutter_actor_set_rotation_angle (ClutterActor *self,
                                  ClutterRotateAxis axis,
                                  gdouble angle);

Sets the angle of rotation of a ClutterActor on the given axis .

This function is a convenience for setting the rotation properties “rotation-angle-x”, “rotation-angle-y”, and “rotation-angle-z”.

The center of rotation is established by the “pivot-point” property.

Parameters

self

a ClutterActor

 

axis

the axis to set the angle one

 

angle

the angle of rotation, in degrees

 

Since: 1.12


clutter_actor_get_rotation_angle ()

gdouble
clutter_actor_get_rotation_angle (ClutterActor *self,
                                  ClutterRotateAxis axis);

Retrieves the angle of rotation set by clutter_actor_set_rotation_angle().

Parameters

self

a ClutterActor

 

axis

the axis of the rotation

 

Returns

the angle of rotation, in degrees

Since: 1.12


clutter_actor_is_rotated ()

gboolean
clutter_actor_is_rotated (ClutterActor *self);

Checks whether any rotation is applied to the actor.

Parameters

self

a ClutterActor

 

Returns

TRUE if the actor is rotated.

Since: 0.6


clutter_actor_set_translation ()

void
clutter_actor_set_translation (ClutterActor *self,
                               gfloat translate_x,
                               gfloat translate_y,
                               gfloat translate_z);

Sets an additional translation transformation on a ClutterActor, relative to the “pivot-point”.

Parameters

self

a ClutterActor

 

translate_x

the translation along the X axis

 

translate_y

the translation along the Y axis

 

translate_z

the translation along the Z axis

 

Since: 1.12


clutter_actor_get_translation ()

void
clutter_actor_get_translation (ClutterActor *self,
                               gfloat *translate_x,
                               gfloat *translate_y,
                               gfloat *translate_z);

Retrieves the translation set using clutter_actor_set_translation().

Parameters

self

a ClutterActor

 

translate_x

return location for the X component of the translation, or NULL.

[out][allow-none]

translate_y

return location for the Y component of the translation, or NULL.

[out][allow-none]

translate_z

return location for the Z component of the translation, or NULL.

[out][allow-none]

Since: 1.12


clutter_actor_set_transform ()

void
clutter_actor_set_transform (ClutterActor *self,
                             const ClutterMatrix *transform);

Overrides the transformations of a ClutterActor with a custom matrix, which will be applied relative to the origin of the actor's allocation and to the actor's pivot point.

The “transform” property is animatable.

Parameters

self

a ClutterActor

 

transform

a ClutterMatrix, or NULL to unset a custom transformation.

[allow-none]

Since: 1.12


clutter_actor_get_transform ()

void
clutter_actor_get_transform (ClutterActor *self,
                             ClutterMatrix *transform);

Retrieves the current transformation matrix of a ClutterActor.

Parameters

self

a ClutterActor

 

transform

a ClutterMatrix.

[out caller-allocates]

Since: 1.12


clutter_actor_set_child_transform ()

void
clutter_actor_set_child_transform (ClutterActor *self,
                                   const ClutterMatrix *transform);

Sets the transformation matrix to be applied to all the children of self prior to their own transformations. The default child transformation is the identity matrix.

If transform is NULL, the child transform will be unset.

The “child-transform” property is animatable.

Parameters

self

a ClutterActor

 

transform

a ClutterMatrix, or NULL.

[allow-none]

Since: 1.12


clutter_actor_get_child_transform ()

void
clutter_actor_get_child_transform (ClutterActor *self,
                                   ClutterMatrix *transform);

Retrieves the child transformation matrix set using clutter_actor_set_child_transform(); if none is currently set, the transform matrix will be initialized to the identity matrix.

Parameters

self

a ClutterActor

 

transform

a ClutterMatrix.

[out caller-allocates]

Since: 1.12


clutter_actor_apply_transform_to_point ()

void
clutter_actor_apply_transform_to_point
                               (ClutterActor *self,
                                const ClutterVertex *point,
                                ClutterVertex *vertex);

Transforms point in coordinates relative to the actor into screen-relative coordinates with the current actor transformation (i.e. scale, rotation, etc)

Parameters

self

A ClutterActor

 

point

A point as ClutterVertex

 

vertex

The translated ClutterVertex.

[out caller-allocates]

Since: 0.4


clutter_actor_transform_stage_point ()

gboolean
clutter_actor_transform_stage_point (ClutterActor *self,
                                     gfloat x,
                                     gfloat y,
                                     gfloat *x_out,
                                     gfloat *y_out);

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.

The conversion should not be expected to be pixel-perfect due to the nature of the operation. In general the error grows when the skewing of the actor rectangle on screen increases.

This function can be computationally intensive.

This function only works when the allocation is up-to-date, i.e. inside of the ClutterActorClass.paint() implementation

Parameters

self

A ClutterActor

 

x

x screen coordinate of the point to unproject.

[in]

y

y screen coordinate of the point to unproject.

[in]

x_out

return location for the unprojected x coordinance.

[out]

y_out

return location for the unprojected y coordinance.

[out]

Returns

TRUE if conversion was successful.

Since: 0.6


clutter_actor_apply_relative_transform_to_point ()

void
clutter_actor_apply_relative_transform_to_point
                               (ClutterActor *self,
                                ClutterActor *ancestor,
                                const ClutterVertex *point,
                                ClutterVertex *vertex);

Transforms point in coordinates relative to the actor into ancestor-relative coordinates using the relevant transform stack (i.e. scale, rotation, etc).

If ancestor is NULL the ancestor will be the ClutterStage. In this case, the coordinates returned will be the coordinates on the stage before the projection is applied. This is different from the behaviour of clutter_actor_apply_transform_to_point().

Parameters

self

A ClutterActor

 

ancestor

A ClutterActor ancestor, or NULL to use the default ClutterStage.

[allow-none]

point

A point as ClutterVertex

 

vertex

The translated ClutterVertex.

[out caller-allocates]

Since: 0.6


clutter_actor_get_transformed_position ()

void
clutter_actor_get_transformed_position
                               (ClutterActor *self,
                                gfloat *x,
                                gfloat *y);

Gets the absolute position of an actor, in pixels relative to the stage.

Parameters

self

A ClutterActor

 

x

return location for the X coordinate, or NULL.

[out][allow-none]

y

return location for the Y coordinate, or NULL.

[out][allow-none]

Since: 0.8


clutter_actor_get_transformed_size ()

void
clutter_actor_get_transformed_size (ClutterActor *self,
                                    gfloat *width,
                                    gfloat *height);

Gets the absolute size of an actor in pixels, taking into account the scaling factors.

If the actor has a valid allocation, the allocated size will be used. If the actor has not a valid allocation then the preferred size will be transformed and returned.

If you want the transformed allocation, see clutter_actor_get_abs_allocation_vertices() instead.

When the actor (or one of its ancestors) is rotated around the X or Y axis, it no longer appears as on the stage as a rectangle, but as a generic quadrangle; in that case this function returns the size of the smallest rectangle that encapsulates the entire quad. Please note that in this case no assumptions can be made about the relative position of this envelope to the absolute position of the actor, as returned by clutter_actor_get_transformed_position(); if you need this information, you need to use clutter_actor_get_abs_allocation_vertices() to get the coords of the actual quadrangle.

Parameters

self

A ClutterActor

 

width

return location for the width, or NULL.

[out][allow-none]

height

return location for the height, or NULL.

[out][allow-none]

Since: 0.8


clutter_actor_get_paint_opacity ()

guint8
clutter_actor_get_paint_opacity (ClutterActor *self);

Retrieves the absolute opacity of the actor, as it appears on the stage.

This function traverses the hierarchy chain and composites the opacity of the actor with that of its parents.

This function is intended for subclasses to use in the paint virtual function, to paint themselves with the correct opacity.

Parameters

self

A ClutterActor

 

Returns

The actor opacity value.

Since: 0.8


clutter_actor_get_paint_visibility ()

gboolean
clutter_actor_get_paint_visibility (ClutterActor *self);

Retrieves the 'paint' visibility of an actor recursively checking for non visible parents.

This is by definition the same as CLUTTER_ACTOR_IS_MAPPED.

Parameters

self

A ClutterActor

 

Returns

TRUE if the actor is visibile and will be painted.

Since: 0.8


clutter_actor_get_abs_allocation_vertices ()

void
clutter_actor_get_abs_allocation_vertices
                               (ClutterActor *self,
                                ClutterVertex verts[]);

Calculates the transformed screen coordinates of the four corners of the actor; the returned vertices relate to the ClutterActorBox coordinates as follows:

  • v[0] contains (x1, y1)

  • v[1] contains (x2, y1)

  • v[2] contains (x1, y2)

  • v[3] contains (x2, y2)

Parameters

self

A ClutterActor

 

verts

Pointer to a location of an array of 4 ClutterVertex where to store the result.

[out][array fixed-size=4]

Since: 0.4


clutter_actor_get_paint_volume ()

const ClutterPaintVolume *
clutter_actor_get_paint_volume (ClutterActor *self);

Retrieves the paint volume of the passed ClutterActor, or NULL when a paint volume can't be determined.

The paint volume is defined as the 3D space occupied by an actor when being painted.

This function will call the ClutterActorClass.get_paint_volume() virtual function of the ClutterActor class. Sub-classes of ClutterActor should not usually care about overriding the default implementation, unless they are, for instance: painting outside their allocation, or actors with a depth factor (not in terms of “depth” but real 3D depth).

Note: 2D actors overriding ClutterActorClass.get_paint_volume() should ensure that their volume has a depth of 0. (This will be true as long as you don't call clutter_paint_volume_set_depth().)

Parameters

self

a ClutterActor

 

Returns

a pointer to a ClutterPaintVolume, or NULL if no volume could be determined. The returned pointer is not guaranteed to be valid across multiple frames; if you want to keep it, you will need to copy it using clutter_paint_volume_copy().

[transfer none]

Since: 1.6


clutter_actor_get_paint_box ()

gboolean
clutter_actor_get_paint_box (ClutterActor *self,
                             ClutterActorBox *box);

Retrieves the paint volume of the passed ClutterActor, and transforms it into a 2D bounding box in stage coordinates.

This function is useful to determine the on screen area occupied by the actor. The box is only an approximation and may often be considerably larger due to the optimizations used to calculate the box. The box is never smaller though, so it can reliably be used for culling.

There are times when a 2D paint box can't be determined, e.g. because the actor isn't yet parented under a stage or because the actor is unable to determine a paint volume.

Parameters

self

a ClutterActor

 

box

return location for a ClutterActorBox.

[out]

Returns

TRUE if a 2D paint box could be determined, else FALSE.

Since: 1.6


clutter_actor_get_transformed_paint_volume ()

const ClutterPaintVolume *
clutter_actor_get_transformed_paint_volume
                               (ClutterActor *self,
                                ClutterActor *relative_to_ancestor);

Retrieves the 3D paint volume of an actor like clutter_actor_get_paint_volume() does (Please refer to the documentation of clutter_actor_get_paint_volume() for more details.) and it additionally transforms the paint volume into the coordinate space of relative_to_ancestor . (Or the stage if NULL is passed for relative_to_ancestor )

This can be used by containers that base their paint volume on the volume of their children. Such containers can query the transformed paint volume of all of its children and union them together using clutter_paint_volume_union().

Parameters

self

a ClutterActor

 

relative_to_ancestor

A ClutterActor that is an ancestor of self (or NULL for the stage)

 

Returns

a pointer to a ClutterPaintVolume, or NULL if no volume could be determined. The returned pointer is not guaranteed to be valid across multiple frames; if you wish to keep it, you will have to copy it using clutter_paint_volume_copy().

[transfer none]

Since: 1.6


clutter_actor_get_default_paint_volume ()

const ClutterPaintVolume *
clutter_actor_get_default_paint_volume
                               (ClutterActor *self);

Retrieves the default paint volume for self .

This function provides the same ClutterPaintVolume that would be computed by the default implementation inside ClutterActor of the ClutterActorClass.get_paint_volume() virtual function.

This function should only be used by ClutterActor subclasses that cannot chain up to the parent implementation when computing their paint volume.

Parameters

self

a ClutterActor

 

Returns

a pointer to the default ClutterPaintVolume, relative to the ClutterActor, or NULL if the actor could not compute a valid paint volume. The returned value is not guaranteed to be stable across multiple frames, so if you want to retain it, you will need to copy it using clutter_paint_volume_copy().

[transfer none]

Since: 1.10


clutter_actor_set_content ()

void
clutter_actor_set_content (ClutterActor *self,
                           ClutterContent *content);

Sets the contents of a ClutterActor.

Parameters

self

a ClutterActor

 

content

a ClutterContent, or NULL.

[allow-none]

Since: 1.10


clutter_actor_get_content ()

ClutterContent *
clutter_actor_get_content (ClutterActor *self);

Retrieves the contents of self .

Parameters

self

a ClutterActor

 

Returns

a pointer to the ClutterContent instance, or NULL if none was set.

[transfer none]

Since: 1.10


clutter_actor_set_content_gravity ()

void
clutter_actor_set_content_gravity (ClutterActor *self,
                                   ClutterContentGravity gravity);

Sets the gravity of the ClutterContent used by self .

See the description of the “content-gravity” property for more information.

The “content-gravity” property is animatable.

Parameters

self

a ClutterActor

 

gravity

the ClutterContentGravity

 

Since: 1.10


clutter_actor_get_content_gravity ()

ClutterContentGravity
clutter_actor_get_content_gravity (ClutterActor *self);

Retrieves the content gravity as set using clutter_actor_set_content_gravity().

Parameters

self

a ClutterActor

 

Returns

the content gravity

Since: 1.10


clutter_actor_set_content_scaling_filters ()

void
clutter_actor_set_content_scaling_filters
                               (ClutterActor *self,
                                ClutterScalingFilter min_filter,
                                ClutterScalingFilter mag_filter);

Sets the minification and magnification filter to be applied when scaling the “content” of a ClutterActor.

The “minification-filter” will be used when reducing the size of the content; the “magnification-filter” will be used when increasing the size of the content.

Parameters

self

a ClutterActor

 

min_filter

the minification filter for the content

 

mag_filter

the magnification filter for the content

 

Since: 1.10


clutter_actor_get_content_scaling_filters ()

void
clutter_actor_get_content_scaling_filters
                               (ClutterActor *self,
                                ClutterScalingFilter *min_filter,
                                ClutterScalingFilter *mag_filter);

Retrieves the values set using clutter_actor_set_content_scaling_filters().

Parameters

self

a ClutterActor

 

min_filter

return location for the minification filter, or NULL.

[out][allow-none]

mag_filter

return location for the magnification filter, or NULL.

[out][allow-none]

Since: 1.10


clutter_actor_set_content_repeat ()

void
clutter_actor_set_content_repeat (ClutterActor *self,
                                  ClutterContentRepeat repeat);

Sets the policy for repeating the “content” of a ClutterActor. The behaviour is deferred to the ClutterContent implementation.

Parameters

self

a ClutterActor

 

repeat

the repeat policy

 

Since: 1.12


clutter_actor_get_content_repeat ()

ClutterContentRepeat
clutter_actor_get_content_repeat (ClutterActor *self);

Retrieves the repeat policy for a ClutterActor set by clutter_actor_set_content_repeat().

Parameters

self

a ClutterActor

 

Returns

the content repeat policy

Since: 1.12


clutter_actor_get_content_box ()

void
clutter_actor_get_content_box (ClutterActor *self,
                               ClutterActorBox *box);

Retrieves the bounding box for the ClutterContent of self .

The bounding box is relative to the actor's allocation.

If no ClutterContent is set for self , or if self has not been allocated yet, then the result is undefined.

The content box is guaranteed to be, at most, as big as the allocation of the ClutterActor.

If the ClutterContent used by the actor has a preferred size, then it is possible to modify the content box by using the “content-gravity” property.

Parameters

self

a ClutterActor

 

box

the return location for the bounding box for the ClutterContent.

[out caller-allocates]

Since: 1.10


clutter_actor_set_clip ()

void
clutter_actor_set_clip (ClutterActor *self,
                        gfloat xoff,
                        gfloat yoff,
                        gfloat width,
                        gfloat height);

Sets clip area for self . The clip area is always computed from the upper left corner of the actor, even if the anchor point is set otherwise.

Parameters

self

A ClutterActor

 

xoff

X offset of the clip rectangle

 

yoff

Y offset of the clip rectangle

 

width

Width of the clip rectangle

 

height

Height of the clip rectangle

 

Since: 0.6


clutter_actor_remove_clip ()

void
clutter_actor_remove_clip (ClutterActor *self);

Removes clip area from self .

Parameters

self

A ClutterActor

 

clutter_actor_has_clip ()

gboolean
clutter_actor_has_clip (ClutterActor *self);

Determines whether the actor has a clip area set or not.

Parameters

self

a ClutterActor

 

Returns

TRUE if the actor has a clip area set.

Since: 0.2


clutter_actor_get_clip ()

void
clutter_actor_get_clip (ClutterActor *self,
                        gfloat *xoff,
                        gfloat *yoff,
                        gfloat *width,
                        gfloat *height);

Gets the clip area for self , if any is set.

Parameters

self

a ClutterActor

 

xoff

return location for the X offset of the clip rectangle, or NULL.

[out][allow-none]

yoff

return location for the Y offset of the clip rectangle, or NULL.

[out][allow-none]

width

return location for the width of the clip rectangle, or NULL.

[out][allow-none]

height

return location for the height of the clip rectangle, or NULL.

[out][allow-none]

Since: 0.6


clutter_actor_set_clip_to_allocation ()

void
clutter_actor_set_clip_to_allocation (ClutterActor *self,
                                      gboolean clip_set);

Sets whether self should be clipped to the same size as its allocation

Parameters

self

a ClutterActor

 

clip_set

TRUE to apply a clip tracking the allocation

 

Since: 1.4


clutter_actor_get_clip_to_allocation ()

gboolean
clutter_actor_get_clip_to_allocation (ClutterActor *self);

Retrieves the value set using clutter_actor_set_clip_to_allocation()

Parameters

self

a ClutterActor

 

Returns

TRUE if the ClutterActor is clipped to its allocation

Since: 1.4


clutter_actor_set_opacity ()

void
clutter_actor_set_opacity (ClutterActor *self,
                           guint8 opacity);

Sets the actor's opacity, with zero being completely transparent and 255 (0xff) being fully opaque.

The “opacity” property is animatable.

Parameters

self

A ClutterActor

 

opacity

New opacity value for the actor.

 

clutter_actor_get_opacity ()

guint8
clutter_actor_get_opacity (ClutterActor *self);

Retrieves the opacity value of an actor, as set by clutter_actor_set_opacity().

For retrieving the absolute opacity of the actor inside a paint virtual function, see clutter_actor_get_paint_opacity().

Parameters

self

a ClutterActor

 

Returns

the opacity of the actor


clutter_actor_set_opacity_override ()

void
clutter_actor_set_opacity_override (ClutterActor *self,
                                    gint opacity);

Allows overriding the calculated paint opacity (as returned by clutter_actor_get_paint_opacity()). This is used internally by ClutterClone and ClutterOffscreenEffect, and should be used by actors that need to mimick those.

In almost all cases this should not used by applications.

Parameters

self

a ClutterActor

 

opacity

the override opacity value, or -1 to reset

 

Stability Level: Unstable


clutter_actor_get_opacity_override ()

gint
clutter_actor_get_opacity_override (ClutterActor *self);

See clutter_actor_set_opacity_override()

Parameters

self

a ClutterActor

 

Returns

the override value for the actor's opacity, or -1 if no override is set.

Since: 1.22

Stability Level: Unstable


clutter_actor_set_offscreen_redirect ()

void
clutter_actor_set_offscreen_redirect (ClutterActor *self,
                                      ClutterOffscreenRedirect redirect);

Defines the circumstances where the actor should be redirected into an offscreen image. The offscreen image is used to flatten the actor into a single image while painting for two main reasons. Firstly, when the actor is painted a second time without any of its contents changing it can simply repaint the cached image without descending further down the actor hierarchy. Secondly, it will make the opacity look correct even if there are overlapping primitives in the actor.

Caching the actor could in some cases be a performance win and in some cases be a performance lose so it is important to determine which value is right for an actor before modifying this value. For example, there is never any reason to flatten an actor that is just a single texture (such as a ClutterTexture) because it is effectively already cached in an image so the offscreen would be redundant. Also if the actor contains primitives that are far apart with a large transparent area in the middle (such as a large CluterGroup with a small actor in the top left and a small actor in the bottom right) then the cached image will contain the entire image of the large area and the paint will waste time blending all of the transparent pixels in the middle.

The default method of implementing opacity on a container simply forwards on the opacity to all of the children. If the children are overlapping then it will appear as if they are two separate glassy objects and there will be a break in the color where they overlap. By redirecting to an offscreen buffer it will be as if the two opaque objects are combined into one and then made transparent which is usually what is expected.

The image below demonstrates the difference between redirecting and not. The image shows two Clutter groups, each containing a red and a green rectangle which overlap. The opacity on the group is set to 128 (which is 50%). When the offscreen redirect is not used, the red rectangle can be seen through the blue rectangle as if the two rectangles were separately transparent. When the redirect is used the group as a whole is transparent instead so the red rectangle is not visible where they overlap.

Figure 1. Sample of using an offscreen redirect for transparency

Sample of using an offscreen redirect for transparency


The default value for this property is 0, so we effectively will never redirect an actor offscreen by default. This means that there are times that transparent actors may look glassy as described above. The reason this is the default is because there is a performance trade off between quality and performance here. In many cases the default form of glassy opacity looks good enough, but if it's not you will need to set the CLUTTER_OFFSCREEN_REDIRECT_AUTOMATIC_FOR_OPACITY flag to enable redirection for opacity.

Custom actors that don't contain any overlapping primitives are recommended to override the has_overlaps() virtual to return FALSE for maximum efficiency.

Parameters

self

A ClutterActor

 

redirect

New offscreen redirect flags for the actor.

 

Since: 1.8


clutter_actor_get_offscreen_redirect ()

ClutterOffscreenRedirect
clutter_actor_get_offscreen_redirect (ClutterActor *self);

Retrieves whether to redirect the actor to an offscreen buffer, as set by clutter_actor_set_offscreen_redirect().

Parameters

self

a ClutterActor

 

Returns

the value of the offscreen-redirect property of the actor

Since: 1.8


clutter_actor_is_in_clone_paint ()

gboolean
clutter_actor_is_in_clone_paint (ClutterActor *self);

Checks whether self is being currently painted by a ClutterClone

This function is useful only inside the ::paint virtual function implementations or within handlers for the “paint” signal

This function should not be used by applications

Parameters

self

a ClutterActor

 

Returns

TRUE if the ClutterActor is currently being painted by a ClutterClone, and FALSE otherwise

Since: 1.0


clutter_actor_add_child ()

void
clutter_actor_add_child (ClutterActor *self,
                         ClutterActor *child);

Adds child to the children of self .

This function will acquire a reference on child that will only be released when calling clutter_actor_remove_child().

This function will take into consideration the “depth” of child , and will keep the list of children sorted.

This function will emit the “actor-added” signal on self .

Parameters

self

a ClutterActor

 

child

a ClutterActor

 

Since: 1.10


clutter_actor_insert_child_above ()

void
clutter_actor_insert_child_above (ClutterActor *self,
                                  ClutterActor *child,
                                  ClutterActor *sibling);

Inserts child into the list of children of self , above another child of self or, if sibling is NULL, above all the children of self .

This function will acquire a reference on child that will only be released when calling clutter_actor_remove_child().

This function will not take into consideration the “depth” of child .

This function will emit the “actor-added” signal on self .

Parameters

self

a ClutterActor

 

child

a ClutterActor

 

sibling

a child of self , or NULL.

[allow-none]

Since: 1.10


clutter_actor_insert_child_at_index ()

void
clutter_actor_insert_child_at_index (ClutterActor *self,
                                     ClutterActor *child,
                                     gint index_);

Inserts child into the list of children of self , using the given index_ . If index_ is greater than the number of children in self , or is less than 0, then the new child is added at the end.

This function will acquire a reference on child that will only be released when calling clutter_actor_remove_child().

This function will not take into consideration the “depth” of child .

This function will emit the “actor-added” signal on self .

Parameters

self

a ClutterActor

 

child

a ClutterActor

 

index_

the index

 

Since: 1.10


clutter_actor_insert_child_below ()

void
clutter_actor_insert_child_below (ClutterActor *self,
                                  ClutterActor *child,
                                  ClutterActor *sibling);

Inserts child into the list of children of self , below another child of self or, if sibling is NULL, below all the children of self .

This function will acquire a reference on child that will only be released when calling clutter_actor_remove_child().

This function will not take into consideration the “depth” of child .

This function will emit the “actor-added” signal on self .

Parameters

self

a ClutterActor

 

child

a ClutterActor

 

sibling

a child of self , or NULL.

[allow-none]

Since: 1.10


clutter_actor_replace_child ()

void
clutter_actor_replace_child (ClutterActor *self,
                             ClutterActor *old_child,
                             ClutterActor *new_child);

Replaces old_child with new_child in the list of children of self .

Parameters

self

a ClutterActor

 

old_child

the child of self to replace

 

new_child

the ClutterActor to replace old_child

 

Since: 1.10


clutter_actor_remove_child ()

void
clutter_actor_remove_child (ClutterActor *self,
                            ClutterActor *child);

Removes child from the children of self .

This function will release the reference added by clutter_actor_add_child(), so if you want to keep using child you will have to acquire a referenced on it before calling this function.

This function will emit the “actor-removed” signal on self .

Parameters

self

a ClutterActor

 

child

a ClutterActor

 

Since: 1.10


clutter_actor_remove_all_children ()

void
clutter_actor_remove_all_children (ClutterActor *self);

Removes all children of self .

This function releases the reference added by inserting a child actor in the list of children of self .

If the reference count of a child drops to zero, the child will be destroyed. If you want to ensure the destruction of all the children of self , use clutter_actor_destroy_all_children().

Parameters

self

a ClutterActor

 

Since: 1.10


clutter_actor_destroy_all_children ()

void
clutter_actor_destroy_all_children (ClutterActor *self);

Destroys all children of self .

This function releases the reference added by inserting a child actor in the list of children of self , and ensures that the “destroy” signal is emitted on each child of the actor.

By default, ClutterActor will emit the “destroy” signal when its reference count drops to 0; the default handler of the “destroy” signal will destroy all the children of an actor. This function ensures that all children are destroyed, instead of just removed from self , unlike clutter_actor_remove_all_children() which will merely release the reference and remove each child.

Unless you acquired an additional reference on each child of self prior to calling clutter_actor_remove_all_children() and want to reuse the actors, you should use clutter_actor_destroy_all_children() in order to make sure that children are destroyed and signal handlers are disconnected even in cases where circular references prevent this from automatically happening through reference counting alone.

Parameters

self

a ClutterActor

 

Since: 1.10


clutter_actor_get_first_child ()

ClutterActor *
clutter_actor_get_first_child (ClutterActor *self);

Retrieves the first child of self .

The returned pointer is only valid until the scene graph changes; it is not safe to modify the list of children of self while iterating it.

Parameters

self

a ClutterActor

 

Returns

a pointer to a ClutterActor, or NULL.

[transfer none]

Since: 1.10


clutter_actor_get_next_sibling ()

ClutterActor *
clutter_actor_get_next_sibling (ClutterActor *self);

Retrieves the sibling of self that comes after it in the list of children of self 's parent.

The returned pointer is only valid until the scene graph changes; it is not safe to modify the list of children of self while iterating it.

Parameters

self

a ClutterActor

 

Returns

a pointer to a ClutterActor, or NULL.

[transfer none]

Since: 1.10


clutter_actor_get_previous_sibling ()

ClutterActor *
clutter_actor_get_previous_sibling (ClutterActor *self);

Retrieves the sibling of self that comes before it in the list of children of self 's parent.

The returned pointer is only valid until the scene graph changes; it is not safe to modify the list of children of self while iterating it.

Parameters

self

a ClutterActor

 

Returns

a pointer to a ClutterActor, or NULL.

[transfer none]

Since: 1.10


clutter_actor_get_last_child ()

ClutterActor *
clutter_actor_get_last_child (ClutterActor *self);

Retrieves the last child of self .

The returned pointer is only valid until the scene graph changes; it is not safe to modify the list of children of self while iterating it.

Parameters

self

a ClutterActor

 

Returns

a pointer to a ClutterActor, or NULL.

[transfer none]

Since: 1.10


clutter_actor_get_child_at_index ()

ClutterActor *
clutter_actor_get_child_at_index (ClutterActor *self,
                                  gint index_);

Retrieves the actor at the given index_ inside the list of children of self .

Parameters

self

a ClutterActor

 

index_

the position in the list of children

 

Returns

a pointer to a ClutterActor, or NULL.

[transfer none]

Since: 1.10


clutter_actor_get_children ()

GList *
clutter_actor_get_children (ClutterActor *self);

Retrieves the list of children of self .

Parameters

self

a ClutterActor

 

Returns

A newly allocated GList of ClutterActors. Use g_list_free() when done.

[transfer container][element-type ClutterActor]

Since: 1.10


clutter_actor_get_n_children ()

gint
clutter_actor_get_n_children (ClutterActor *self);

Retrieves the number of children of self .

Parameters

self

a ClutterActor

 

Returns

the number of children of an actor

Since: 1.10


clutter_actor_get_parent ()

ClutterActor *
clutter_actor_get_parent (ClutterActor *self);

Retrieves the parent of self .

Parameters

self

A ClutterActor

 

Returns

The ClutterActor parent, or NULL if no parent is set.

[transfer none]


clutter_actor_set_child_above_sibling ()

void
clutter_actor_set_child_above_sibling (ClutterActor *self,
                                       ClutterActor *child,
                                       ClutterActor *sibling);

Sets child to be above sibling in the list of children of self .

If sibling is NULL, child will be the new last child of self .

This function is logically equivalent to removing child and using clutter_actor_insert_child_above(), but it will not emit signals or change state on child .

Parameters

self

a ClutterActor

 

child

a ClutterActor child of self

 

sibling

a ClutterActor child of self , or NULL.

[allow-none]

Since: 1.10


clutter_actor_set_child_at_index ()

void
clutter_actor_set_child_at_index (ClutterActor *self,
                                  ClutterActor *child,
                                  gint index_);

Changes the index of child in the list of children of self .

This function is logically equivalent to removing child and calling clutter_actor_insert_child_at_index(), but it will not emit signals or change state on child .

Parameters

self

a ClutterActor

 

child

a ClutterActor child of self

 

index_

the new index for child

 

Since: 1.10


clutter_actor_set_child_below_sibling ()

void
clutter_actor_set_child_below_sibling (ClutterActor *self,
                                       ClutterActor *child,
                                       ClutterActor *sibling);

Sets child to be below sibling in the list of children of self .

If sibling is NULL, child will be the new first child of self .

This function is logically equivalent to removing self and using clutter_actor_insert_child_below(), but it will not emit signals or change state on child .

Parameters

self

a ClutterActor

 

child

a ClutterActor child of self

 

sibling

a ClutterActor child of self , or NULL.

[allow-none]

Since: 1.10


clutter_actor_contains ()

gboolean
clutter_actor_contains (ClutterActor *self,
                        ClutterActor *descendant);

Determines if descendant is contained inside self (either as an immediate child, or as a deeper descendant). If self and descendant point to the same actor then it will also return TRUE.

Parameters

self

A ClutterActor

 

descendant

A ClutterActor, possibly contained in self

 

Returns

whether descendent is contained within self

Since: 1.4


clutter_actor_get_stage ()

ClutterActor *
clutter_actor_get_stage (ClutterActor *actor);

Retrieves the ClutterStage where actor is contained.

Parameters

actor

a ClutterActor

 

Returns

the stage containing the actor, or NULL.

[transfer none][type Clutter.Stage]

Since: 0.8


clutter_actor_iter_init ()

void
clutter_actor_iter_init (ClutterActorIter *iter,
                         ClutterActor *root);

Initializes a ClutterActorIter, which can then be used to iterate efficiently over a section of the scene graph, and associates it with root .

Modifying the scene graph section that contains root will invalidate the iterator.

1
2
3
4
5
6
7
8
ClutterActorIter iter;
ClutterActor *child;

clutter_actor_iter_init (&iter, container);
while (clutter_actor_iter_next (&iter, &child))
  {
    // do something with child
  }

Parameters

iter

a ClutterActorIter

 

root

a ClutterActor

 

Since: 1.10


clutter_actor_iter_is_valid ()

gboolean
clutter_actor_iter_is_valid (const ClutterActorIter *iter);

Checks whether a ClutterActorIter is still valid.

An iterator is considered valid if it has been initialized, and if the ClutterActor that it refers to hasn't been modified after the initialization.

Parameters

iter

a ClutterActorIter

 

Returns

TRUE if the iterator is valid, and FALSE otherwise

Since: 1.12


clutter_actor_iter_next ()

gboolean
clutter_actor_iter_next (ClutterActorIter *iter,
                         ClutterActor **child);

Advances the iter and retrieves the next child of the root ClutterActor that was used to initialize the ClutterActorIterator.

If the iterator can advance, this function returns TRUE and sets the child argument.

If the iterator cannot advance, this function returns FALSE, and the contents of child are undefined.

Parameters

iter

a ClutterActorIter

 

child

return location for a ClutterActor.

[out][transfer none]

Returns

TRUE if the iterator could advance, and FALSE otherwise.

Since: 1.10


clutter_actor_iter_prev ()

gboolean
clutter_actor_iter_prev (ClutterActorIter *iter,
                         ClutterActor **child);

Advances the iter and retrieves the previous child of the root ClutterActor that was used to initialize the ClutterActorIterator.

If the iterator can advance, this function returns TRUE and sets the child argument.

If the iterator cannot advance, this function returns FALSE, and the contents of child are undefined.

Parameters

iter

a ClutterActorIter

 

child

return location for a ClutterActor.

[out][transfer none]

Returns

TRUE if the iterator could advance, and FALSE otherwise.

Since: 1.10


clutter_actor_iter_remove ()

void
clutter_actor_iter_remove (ClutterActorIter *iter);

Safely removes the ClutterActor currently pointer to by the iterator from its parent.

This function can only be called after clutter_actor_iter_next() or clutter_actor_iter_prev() returned TRUE, and cannot be called more than once for the same actor.

This function will call clutter_actor_remove_child() internally.

Parameters

iter

a ClutterActorIter

 

Since: 1.10


clutter_actor_iter_destroy ()

void
clutter_actor_iter_destroy (ClutterActorIter *iter);

Safely destroys the ClutterActor currently pointer to by the iterator from its parent.

This function can only be called after clutter_actor_iter_next() or clutter_actor_iter_prev() returned TRUE, and cannot be called more than once for the same actor.

This function will call clutter_actor_destroy() internally.

Parameters

iter

a ClutterActorIter

 

Since: 1.10


ClutterActorCreateChildFunc ()

ClutterActor *
(*ClutterActorCreateChildFunc) (gpointer item,
                                gpointer user_data);

Creates a ClutterActor using the item in the model.

The usual way to implement this function is to create a ClutterActor instance and then bind the GObject properties to the actor properties of interest, using g_object_bind_property(). This way, when the item in the GListModel changes, the ClutterActor changes as well.

Parameters

item

the item in the model.

[type GObject]

user_data

Data passed to clutter_actor_bind_model()

 

Returns

The newly created child ClutterActor.

[transfer full]

Since: 1.24


clutter_actor_bind_model ()

void
clutter_actor_bind_model (ClutterActor *self,
                          GListModel *model,
                          ClutterActorCreateChildFunc create_child_func,
                          gpointer user_data,
                          GDestroyNotify notify);

Binds a GListModel to a ClutterActor.

If the ClutterActor was already bound to a GListModel, the previous binding is destroyed.

The existing children of ClutterActor are destroyed when setting a model, and new children are created and added, representing the contents of the model . The ClutterActor is updated whenever the model changes. If model is NULL, the ClutterActor is left empty.

When a ClutterActor is bound to a model, adding and removing children directly is undefined behaviour.

Parameters

self

a ClutterActor

 

model

a GListModel.

[nullable]

create_child_func

a function that creates ClutterActor instances from the contents of the model

 

user_data

user data passed to create_child_func

 

notify

function called when unsetting the model

 

Since: 1.24


clutter_actor_bind_model_with_properties ()

void
clutter_actor_bind_model_with_properties
                               (ClutterActor *self,
                                GListModel *model,
                                GType child_type,
                                const char *first_model_property,
                                ...);

Binds a GListModel to a ClutterActor.

Unlike clutter_actor_bind_model(), this function automatically creates a child ClutterActor of type child_type , and binds properties on the items inside the model to the corresponding properties on the child, for instance:

1
2
3
4
5
6
7
clutter_actor_bind_model_with_properties (actor, model,
                                          MY_TYPE_CHILD_VIEW,
                                          "label", "text", G_BINDING_DEFAULT | G_BINDING_SYNC_CREATE,
                                          "icon", "image", G_BINDING_DEFAULT | G_BINDING_SYNC_CREATE,
                                          "selected", "selected", G_BINDING_BIDIRECTIONAL,
                                          "active", "active", G_BINDING_BIDIRECTIONAL,
                                          NULL);

is the equivalent of calling clutter_actor_bind_model() with a ClutterActorCreateChildFunc of:

1
2
3
4
5
6
7
8
ClutterActor *res = g_object_new (MY_TYPE_CHILD_VIEW, NULL);

g_object_bind_property (item, "label", res, "text", G_BINDING_DEFAULT | G_BINDING_SYNC_CREATE);
g_object_bind_property (item, "icon", res, "image", G_BINDING_DEFAULT | G_BINDING_SYNC_CREATE);
g_object_bind_property (item, "selected", res, "selected", G_BINDING_BIDIRECTIONAL);
g_object_bind_property (item, "active", res, "active", G_BINDING_BIDIRECTIONAL);

return res;

If the ClutterActor was already bound to a GListModel, the previous binding is destroyed.

When a ClutterActor is bound to a model, adding and removing children directly is undefined behaviour.

See also: clutter_actor_bind_model()

Parameters

self

a ClutterActor

 

model

a GListModel

 

child_type

the type of ClutterActor to use when creating children mapping to items inside the model

 

first_model_property

the first property of model to bind

 

...

tuples of property names on the model , on the child, and the GBindingFlags used to bind them, terminated by NULL

 

Since: 1.24


clutter_actor_save_easing_state ()

void
clutter_actor_save_easing_state (ClutterActor *self);

Saves the current easing state for animatable properties, and creates a new state with the default values for easing mode and duration.

New transitions created after calling this function will inherit the duration, easing mode, and delay of the new easing state; this also applies to transitions modified in flight.

Parameters

self

a ClutterActor

 

Since: 1.10


clutter_actor_restore_easing_state ()

void
clutter_actor_restore_easing_state (ClutterActor *self);

Restores the easing state as it was prior to a call to clutter_actor_save_easing_state().

Parameters

self

a ClutterActor

 

Since: 1.10


clutter_actor_set_easing_duration ()

void
clutter_actor_set_easing_duration (ClutterActor *self,
                                   guint msecs);

Sets the duration of the tweening for animatable properties of self for the current easing state.

Parameters

self

a ClutterActor

 

msecs

the duration of the easing, or NULL

 

Since: 1.10


clutter_actor_get_easing_duration ()

guint
clutter_actor_get_easing_duration (ClutterActor *self);

Retrieves the duration of the tweening for animatable properties of self for the current easing state.

Parameters

self

a ClutterActor

 

Returns

the duration of the tweening, in milliseconds

Since: 1.10


clutter_actor_set_easing_mode ()

void
clutter_actor_set_easing_mode (ClutterActor *self,
                               ClutterAnimationMode mode);

Sets the easing mode for the tweening of animatable properties of self .

Parameters

self

a ClutterActor

 

mode

an easing mode, excluding CLUTTER_CUSTOM_MODE

 

Since: 1.10


clutter_actor_get_easing_mode ()

ClutterAnimationMode
clutter_actor_get_easing_mode (ClutterActor *self);

Retrieves the easing mode for the tweening of animatable properties of self for the current easing state.

Parameters

self

a ClutterActor

 

Returns

an easing mode

Since: 1.10


clutter_actor_set_easing_delay ()

void
clutter_actor_set_easing_delay (ClutterActor *self,
                                guint msecs);

Sets the delay that should be applied before tweening animatable properties.

Parameters

self

a ClutterActor

 

msecs

the delay before the start of the tweening, in milliseconds

 

Since: 1.10


clutter_actor_get_easing_delay ()

guint
clutter_actor_get_easing_delay (ClutterActor *self);

Retrieves the delay that should be applied when tweening animatable properties.

Parameters

self

a ClutterActor

 

Returns

a delay, in milliseconds

Since: 1.10


clutter_actor_get_transition ()

ClutterTransition *
clutter_actor_get_transition (ClutterActor *self,
                              const char *name);

Retrieves the ClutterTransition of a ClutterActor by using the transition name .

Transitions created for animatable properties use the name of the property itself, for instance the code below:

1
2
3
4
5
6
7
clutter_actor_set_easing_duration (actor, 1000);
clutter_actor_set_rotation (actor, CLUTTER_Y_AXIS, 360.0, x, y, z);

transition = clutter_actor_get_transition (actor, "rotation-angle-y");
g_signal_connect (transition, "stopped",
                  G_CALLBACK (on_transition_stopped),
                  actor);

will call the on_transition_stopped callback when the transition is finished.

If you just want to get notifications of the completion of a transition, you should use the “transition-stopped” signal, using the transition name as the signal detail.

Parameters

self

a ClutterActor

 

name

the name of the transition

 

Returns

a ClutterTransition, or NULL is none was found to match the passed name; the returned instance is owned by Clutter and it should not be freed.

[transfer none]

Since: 1.10


clutter_actor_add_transition ()

void
clutter_actor_add_transition (ClutterActor *self,
                              const char *name,
                              ClutterTransition *transition);

Adds a transition to the ClutterActor's list of animations.

The name string is a per-actor unique identifier of the transition : only one ClutterTransition can be associated to the specified name .

The transition will be started once added.

This function will take a reference on the transition .

This function is usually called implicitly when modifying an animatable property.

Parameters

self

a ClutterActor

 

name

the name of the transition to add

 

transition

the ClutterTransition to add

 

Since: 1.10


clutter_actor_remove_transition ()

void
clutter_actor_remove_transition (ClutterActor *self,
                                 const char *name);

Removes the transition stored inside a ClutterActor using name identifier.

If the transition is currently in progress, it will be stopped.

This function releases the reference acquired when the transition was added to the ClutterActor.

Parameters

self

a ClutterActor

 

name

the name of the transition to remove

 

Since: 1.10


clutter_actor_remove_all_transitions ()

void
clutter_actor_remove_all_transitions (ClutterActor *self);

Removes all transitions associated to self .

Parameters

self

a ClutterActor

 

Since: 1.10


clutter_actor_set_reactive ()

void
clutter_actor_set_reactive (ClutterActor *actor,
                            gboolean reactive);

Sets actor as reactive. Reactive actors will receive events.

Parameters

actor

a ClutterActor

 

reactive

whether the actor should be reactive to events

 

Since: 0.6


clutter_actor_get_reactive ()

gboolean
clutter_actor_get_reactive (ClutterActor *actor);

Checks whether actor is marked as reactive.

Parameters

actor

a ClutterActor

 

Returns

TRUE if the actor is reactive

Since: 0.6


clutter_actor_has_key_focus ()

gboolean
clutter_actor_has_key_focus (ClutterActor *self);

Checks whether self is the ClutterActor that has key focus

Parameters

self

a ClutterActor

 

Returns

TRUE if the actor has key focus, and FALSE otherwise

Since: 1.4


clutter_actor_grab_key_focus ()

void
clutter_actor_grab_key_focus (ClutterActor *self);

Sets the key focus of the ClutterStage including self to this ClutterActor.

Parameters

self

a ClutterActor

 

Since: 1.0


clutter_actor_has_pointer ()

gboolean
clutter_actor_has_pointer (ClutterActor *self);

Checks whether an actor contains the pointer of a ClutterInputDevice

Parameters

self

a ClutterActor

 

Returns

TRUE if the actor contains the pointer, and FALSE otherwise

Since: 1.2


clutter_actor_get_pango_context ()

PangoContext *
clutter_actor_get_pango_context (ClutterActor *self);

Retrieves the PangoContext for self . The actor's PangoContext is already configured using the appropriate font map, resolution and font options.

Unlike clutter_actor_create_pango_context(), this context is owend by the ClutterActor and it will be updated each time the options stored by the ClutterBackend change.

You can use the returned PangoContext to create a PangoLayout and render text using cogl_pango_render_layout() to reuse the glyphs cache also used by Clutter.

Parameters

self

a ClutterActor

 

Returns

the PangoContext for a ClutterActor. The returned PangoContext is owned by the actor and should not be unreferenced by the application code.

[transfer none]

Since: 1.0


clutter_actor_create_pango_context ()

PangoContext *
clutter_actor_create_pango_context (ClutterActor *self);

Creates a PangoContext for the given actor. The PangoContext is already configured using the appropriate font map, resolution and font options.

See also clutter_actor_get_pango_context().

Parameters

self

a ClutterActor

 

Returns

the newly created PangoContext. Use g_object_unref() on the returned value to deallocate its resources.

[transfer full]

Since: 1.0


clutter_actor_create_pango_layout ()

PangoLayout *
clutter_actor_create_pango_layout (ClutterActor *self,
                                   const gchar *text);

Creates a new PangoLayout from the same PangoContext used by the ClutterActor. The PangoLayout is already configured with the font map, resolution and font options, and the given text .

If you want to keep around a PangoLayout created by this function you will have to connect to the “font-changed” and “resolution-changed” signals, and call pango_layout_context_changed() in response to them.

Parameters

self

a ClutterActor

 

text

the text to set on the PangoLayout, or NULL.

[allow-none]

Returns

the newly created PangoLayout. Use g_object_unref() when done.

[transfer full]

Since: 1.0


clutter_actor_set_text_direction ()

void
clutter_actor_set_text_direction (ClutterActor *self,
                                  ClutterTextDirection text_dir);

Sets the ClutterTextDirection for an actor

The passed text direction must not be CLUTTER_TEXT_DIRECTION_DEFAULT

If self implements ClutterContainer then this function will recurse inside all the children of self (including the internal ones).

Composite actors not implementing ClutterContainer, or actors requiring special handling when the text direction changes, should connect to the “notify” signal for the “text-direction” property

Parameters

self

a ClutterActor

 

text_dir

the text direction for self

 

Since: 1.2


clutter_actor_get_text_direction ()

ClutterTextDirection
clutter_actor_get_text_direction (ClutterActor *self);

Retrieves the value set using clutter_actor_set_text_direction()

If no text direction has been previously set, the default text direction, as returned by clutter_get_default_text_direction(), will be returned instead

Parameters

self

a ClutterActor

 

Returns

the ClutterTextDirection for the actor

Since: 1.2


clutter_actor_get_accessible ()

AtkObject *
clutter_actor_get_accessible (ClutterActor *self);

Returns the accessible object that describes the actor to an assistive technology.

If no class-specific AtkObject implementation is available for the actor instance in question, it will inherit an AtkObject implementation from the first ancestor class for which such an implementation is defined.

The documentation of the ATK library contains more information about accessible objects and their uses.

Parameters

self

a ClutterActor

 

Returns

the AtkObject associated with actor .

[transfer none]


clutter_actor_add_action ()

void
clutter_actor_add_action (ClutterActor *self,
                          ClutterAction *action);

Adds action to the list of actions applied to self

A ClutterAction can only belong to one actor at a time

The ClutterActor will hold a reference on action until either clutter_actor_remove_action() or clutter_actor_clear_actions() is called

Parameters

self

a ClutterActor

 

action

a ClutterAction

 

Since: 1.4


clutter_actor_add_action_with_name ()

void
clutter_actor_add_action_with_name (ClutterActor *self,
                                    const gchar *name,
                                    ClutterAction *action);

A convenience function for setting the name of a ClutterAction while adding it to the list of actions applied to self

This function is the logical equivalent of:

1
2
clutter_actor_meta_set_name (CLUTTER_ACTOR_META (action), name);
clutter_actor_add_action (self, action);

Parameters

self

a ClutterActor

 

name

the name to set on the action

 

action

a ClutterAction

 

Since: 1.4


clutter_actor_remove_action ()

void
clutter_actor_remove_action (ClutterActor *self,
                             ClutterAction *action);

Removes action from the list of actions applied to self

The reference held by self on the ClutterAction will be released

Parameters

self

a ClutterActor

 

action

a ClutterAction

 

Since: 1.4


clutter_actor_remove_action_by_name ()

void
clutter_actor_remove_action_by_name (ClutterActor *self,
                                     const gchar *name);

Removes the ClutterAction with the given name from the list of actions applied to self

Parameters

self

a ClutterActor

 

name

the name of the action to remove

 

Since: 1.4


clutter_actor_has_actions ()

gboolean
clutter_actor_has_actions (ClutterActor *self);

Returns whether the actor has any actions applied.

Parameters

self

A ClutterActor

 

Returns

TRUE if the actor has any actions, FALSE otherwise

Since: 1.10


clutter_actor_get_actions ()

GList *
clutter_actor_get_actions (ClutterActor *self);

Retrieves the list of actions applied to self

Parameters

self

a ClutterActor

 

Returns

a copy of the list of ClutterActions. The contents of the list are owned by the ClutterActor. Use g_list_free() to free the resources allocated by the returned GList.

[transfer container][element-type Clutter.Action]

Since: 1.4


clutter_actor_get_action ()

ClutterAction *
clutter_actor_get_action (ClutterActor *self,
                          const gchar *name);

Retrieves the ClutterAction with the given name in the list of actions applied to self

Parameters

self

a ClutterActor

 

name

the name of the action to retrieve

 

Returns

a ClutterAction for the given name, or NULL. The returned ClutterAction is owned by the actor and it should not be unreferenced directly.

[transfer none]

Since: 1.4


clutter_actor_clear_actions ()

void
clutter_actor_clear_actions (ClutterActor *self);

Clears the list of actions applied to self

Parameters

self

a ClutterActor

 

Since: 1.4


clutter_actor_add_constraint ()

void
clutter_actor_add_constraint (ClutterActor *self,
                              ClutterConstraint *constraint);

Adds constraint to the list of ClutterConstraints applied to self

The ClutterActor will hold a reference on the constraint until either clutter_actor_remove_constraint() or clutter_actor_clear_constraints() is called.

Parameters

self

a ClutterActor

 

constraint

a ClutterConstraint

 

Since: 1.4


clutter_actor_add_constraint_with_name ()

void
clutter_actor_add_constraint_with_name
                               (ClutterActor *self,
                                const gchar *name,
                                ClutterConstraint *constraint);

A convenience function for setting the name of a ClutterConstraint while adding it to the list of constraints applied to self

This function is the logical equivalent of:

1
2
clutter_actor_meta_set_name (CLUTTER_ACTOR_META (constraint), name);
clutter_actor_add_constraint (self, constraint);

Parameters

self

a ClutterActor

 

name

the name to set on the constraint

 

constraint

a ClutterConstraint

 

Since: 1.4


clutter_actor_remove_constraint ()

void
clutter_actor_remove_constraint (ClutterActor *self,
                                 ClutterConstraint *constraint);

Removes constraint from the list of constraints applied to self

The reference held by self on the ClutterConstraint will be released

Parameters

self

a ClutterActor

 

constraint

a ClutterConstraint

 

Since: 1.4


clutter_actor_remove_constraint_by_name ()

void
clutter_actor_remove_constraint_by_name
                               (ClutterActor *self,
                                const gchar *name);

Removes the ClutterConstraint with the given name from the list of constraints applied to self

Parameters

self

a ClutterActor

 

name

the name of the constraint to remove

 

Since: 1.4


clutter_actor_has_constraints ()

gboolean
clutter_actor_has_constraints (ClutterActor *self);

Returns whether the actor has any constraints applied.

Parameters

self

A ClutterActor

 

Returns

TRUE if the actor has any constraints, FALSE otherwise

Since: 1.10


clutter_actor_get_constraints ()

GList *
clutter_actor_get_constraints (ClutterActor *self);

Retrieves the list of constraints applied to self

Parameters

self

a ClutterActor

 

Returns

a copy of the list of ClutterConstraints. The contents of the list are owned by the ClutterActor. Use g_list_free() to free the resources allocated by the returned GList.

[transfer container][element-type Clutter.Constraint]

Since: 1.4


clutter_actor_get_constraint ()

ClutterConstraint *
clutter_actor_get_constraint (ClutterActor *self,
                              const gchar *name);

Retrieves the ClutterConstraint with the given name in the list of constraints applied to self

Parameters

self

a ClutterActor

 

name

the name of the constraint to retrieve

 

Returns

a ClutterConstraint for the given name, or NULL. The returned ClutterConstraint is owned by the actor and it should not be unreferenced directly.

[transfer none]

Since: 1.4


clutter_actor_clear_constraints ()

void
clutter_actor_clear_constraints (ClutterActor *self);

Clears the list of constraints applied to self

Parameters

self

a ClutterActor

 

Since: 1.4


clutter_actor_add_effect ()

void
clutter_actor_add_effect (ClutterActor *self,
                          ClutterEffect *effect);

Adds effect to the list of ClutterEffects applied to self

The ClutterActor will hold a reference on the effect until either clutter_actor_remove_effect() or clutter_actor_clear_effects() is called.

Note that as ClutterEffect is initially unowned, clutter_actor_add_effect() will sink any floating reference on effect .

Parameters

self

a ClutterActor

 

effect

a ClutterEffect

 

Since: 1.4


clutter_actor_add_effect_with_name ()

void
clutter_actor_add_effect_with_name (ClutterActor *self,
                                    const gchar *name,
                                    ClutterEffect *effect);

A convenience function for setting the name of a ClutterEffect while adding it to the list of effects applied to self .

Note that as ClutterEffect is initially unowned, clutter_actor_add_effect_with_name() will sink any floating reference on effect .

This function is the logical equivalent of:

1
2
clutter_actor_meta_set_name (CLUTTER_ACTOR_META (effect), name);
clutter_actor_add_effect (self, effect);

Parameters

self

a ClutterActor

 

name

the name to set on the effect

 

effect

a ClutterEffect

 

Since: 1.4


clutter_actor_remove_effect ()

void
clutter_actor_remove_effect (ClutterActor *self,
                             ClutterEffect *effect);

Removes effect from the list of effects applied to self

The reference held by self on the ClutterEffect will be released

Parameters

self

a ClutterActor

 

effect

a ClutterEffect

 

Since: 1.4


clutter_actor_remove_effect_by_name ()

void
clutter_actor_remove_effect_by_name (ClutterActor *self,
                                     const gchar *name);

Removes the ClutterEffect with the given name from the list of effects applied to self

Parameters

self

a ClutterActor

 

name

the name of the effect to remove

 

Since: 1.4


clutter_actor_has_effects ()

gboolean
clutter_actor_has_effects (ClutterActor *self);

Returns whether the actor has any effects applied.

Parameters

self

A ClutterActor

 

Returns

TRUE if the actor has any effects, FALSE otherwise

Since: 1.10


clutter_actor_get_effects ()

GList *
clutter_actor_get_effects (ClutterActor *self);

Retrieves the ClutterEffects applied on self , if any

Parameters

self

a ClutterActor

 

Returns

a list of ClutterEffects, or NULL. The elements of the returned list are owned by Clutter and they should not be freed. You should free the returned list using g_list_free() when done.

[transfer container][element-type Clutter.Effect]

Since: 1.4


clutter_actor_get_effect ()

ClutterEffect *
clutter_actor_get_effect (ClutterActor *self,
                          const gchar *name);

Retrieves the ClutterEffect with the given name in the list of effects applied to self

Parameters

self

a ClutterActor

 

name

the name of the effect to retrieve

 

Returns

a ClutterEffect for the given name, or NULL. The returned ClutterEffect is owned by the actor and it should not be unreferenced directly.

[transfer none]

Since: 1.4


clutter_actor_clear_effects ()

void
clutter_actor_clear_effects (ClutterActor *self);

Clears the list of effects applied to self

Parameters

self

a ClutterActor

 

Since: 1.4


clutter_actor_set_scale_full ()

void
clutter_actor_set_scale_full (ClutterActor *self,
                              gdouble scale_x,
                              gdouble scale_y,
                              gfloat center_x,
                              gfloat center_y);

clutter_actor_set_scale_full has been deprecated since version 1.12 and should not be used in newly-written code.

Use clutter_actor_set_pivot_point() to control the scale center

Scales an actor with the given factors around the given center point. The center point is specified in pixels relative to the anchor point (usually the top left corner of the actor).

The “scale-x” and “scale-y” properties are animatable.

Parameters

self

A ClutterActor

 

scale_x

double factor to scale actor by horizontally.

 

scale_y

double factor to scale actor by vertically.

 

center_x

X coordinate of the center of the scaling

 

center_y

Y coordinate of the center of the scaling

 

Since: 1.0


clutter_actor_set_scale_with_gravity ()

void
clutter_actor_set_scale_with_gravity (ClutterActor *self,
                                      gdouble scale_x,
                                      gdouble scale_y,
                                      ClutterGravity gravity);

clutter_actor_set_scale_with_gravity has been deprecated since version 1.12 and should not be used in newly-written code.

Use clutter_actor_set_pivot_point() to set the scale center using normalized coordinates instead.

Scales an actor with the given factors around the given center point. The center point is specified as one of the compass directions in ClutterGravity. For example, setting it to north will cause the top of the actor to remain unchanged and the rest of the actor to expand left, right and downwards.

The “scale-x” and “scale-y” properties are animatable.

Parameters

self

A ClutterActor

 

scale_x

double factor to scale actor by horizontally.

 

scale_y

double factor to scale actor by vertically.

 

gravity

the location of the scale center expressed as a compass direction.

 

Since: 1.0


clutter_actor_get_scale_center ()

void
clutter_actor_get_scale_center (ClutterActor *self,
                                gfloat *center_x,
                                gfloat *center_y);

clutter_actor_get_scale_center has been deprecated since version 1.12 and should not be used in newly-written code.

Use clutter_actor_get_pivot_point() instead.

Retrieves the scale center coordinate in pixels relative to the top left corner of the actor. If the scale center was specified using a ClutterGravity this will calculate the pixel offset using the current size of the actor.

Parameters

self

A ClutterActor

 

center_x

Location to store the X position of the scale center, or NULL.

[out][allow-none]

center_y

Location to store the Y position of the scale center, or NULL.

[out][allow-none]

Since: 1.0


clutter_actor_get_scale_gravity ()

ClutterGravity
clutter_actor_get_scale_gravity (ClutterActor *self);

clutter_actor_get_scale_gravity has been deprecated since version 1.12 and should not be used in newly-written code.

Use clutter_actor_get_pivot_point() instead.

Retrieves the scale center as a compass direction. If the scale center was specified in pixels or units this will return CLUTTER_GRAVITY_NONE.

Parameters

self

A ClutterActor

 

Returns

the scale gravity

Since: 1.0


clutter_actor_set_depth ()

void
clutter_actor_set_depth (ClutterActor *self,
                         gfloat depth);

clutter_actor_set_depth has been deprecated since version 1.12 and should not be used in newly-written code.

Use clutter_actor_set_z_position() instead.

Sets the Z coordinate of self to depth .

The unit used by depth is dependant on the perspective setup. See also clutter_stage_set_perspective().

Parameters

self

a ClutterActor

 

depth

Z co-ord

 

clutter_actor_get_depth ()

gfloat
clutter_actor_get_depth (ClutterActor *self);

clutter_actor_get_depth has been deprecated since version 1.12 and should not be used in newly-written code.

Use clutter_actor_get_z_position() instead.

Retrieves the depth of self .

Parameters

self

a ClutterActor

 

Returns

the depth of the actor


clutter_actor_push_internal ()

void
clutter_actor_push_internal (ClutterActor *self);

clutter_actor_push_internal has been deprecated since version 1.10 and should not be used in newly-written code.

All children of an actor are accessible through the ClutterActor API, and ClutterActor implements the ClutterContainer interface, so this function is only useful for legacy containers overriding the default implementation.

Should be used by actors implementing the ClutterContainer and with internal children added through clutter_actor_set_parent(), for instance:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
static void
my_actor_init (MyActor *self)
{
  self->priv = my_actor_get_instance_private (self);

  clutter_actor_push_internal (CLUTTER_ACTOR (self));

  // calling clutter_actor_set_parent() now will result in
  // the internal flag being set on a child of MyActor

  // internal child - a background texture
  self->priv->background_tex = clutter_texture_new ();
  clutter_actor_set_parent (self->priv->background_tex,
                            CLUTTER_ACTOR (self));

  // internal child - a label
  self->priv->label = clutter_text_new ();
  clutter_actor_set_parent (self->priv->label,
                            CLUTTER_ACTOR (self));

  clutter_actor_pop_internal (CLUTTER_ACTOR (self));

  // calling clutter_actor_set_parent() now will not result in
  // the internal flag being set on a child of MyActor
}

This function will be used by Clutter to toggle an "internal child" flag whenever clutter_actor_set_parent() is called; internal children are handled differently by Clutter, specifically when destroying their parent.

Call clutter_actor_pop_internal() when you finished adding internal children.

Nested calls to clutter_actor_push_internal() are allowed, but each one must by followed by a clutter_actor_pop_internal() call.

Parameters

self

a ClutterActor

 

Since: 1.2


clutter_actor_pop_internal ()

void
clutter_actor_pop_internal (ClutterActor *self);

clutter_actor_pop_internal has been deprecated since version 1.10 and should not be used in newly-written code.

All children of an actor are accessible through the ClutterActor API. This function is only useful for legacy containers overriding the default implementation of the ClutterContainer interface.

Disables the effects of clutter_actor_push_internal().

Parameters

self

a ClutterActor

 

Since: 1.2


clutter_actor_set_parent ()

void
clutter_actor_set_parent (ClutterActor *self,
                          ClutterActor *parent);

clutter_actor_set_parent has been deprecated since version 1.10 and should not be used in newly-written code.

Use clutter_actor_add_child() instead.

Sets the parent of self to parent .

This function will result in parent acquiring a reference on self , eventually by sinking its floating reference first. The reference will be released by clutter_actor_unparent().

This function should only be called by legacy ClutterActors implementing the ClutterContainer interface.

Parameters

self

A ClutterActor

 

parent

A new ClutterActor parent

 

clutter_actor_reparent ()

void
clutter_actor_reparent (ClutterActor *self,
                        ClutterActor *new_parent);

clutter_actor_reparent has been deprecated since version 1.10 and should not be used in newly-written code.

Use clutter_actor_remove_child() and clutter_actor_add_child() instead; remember to take a reference on the actor being removed before calling clutter_actor_remove_child() to avoid the reference count dropping to zero and the actor being destroyed.

Resets the parent actor of self .

This function is logically equivalent to calling clutter_actor_unparent() and clutter_actor_set_parent(), but more efficiently implemented, as it ensures the child is not finalized when unparented, and emits the “parent-set” signal only once.

In reality, calling this function is less useful than it sounds, as some application code may rely on changes in the intermediate state between removal and addition of the actor from its old parent to the new_parent . Thus, it is strongly encouraged to avoid using this function in application code.

Parameters

self

a ClutterActor

 

new_parent

the new ClutterActor parent

 

Since: 0.2


clutter_actor_unparent ()

void
clutter_actor_unparent (ClutterActor *self);

clutter_actor_unparent has been deprecated since version 1.10 and should not be used in newly-written code.

Use clutter_actor_remove_child() instead.

Removes the parent of self .

This will cause the parent of self to release the reference acquired when calling clutter_actor_set_parent(), so if you want to keep self you will have to acquire a reference of your own, through g_object_ref().

This function should only be called by legacy ClutterActors implementing the ClutterContainer interface.

Parameters

self

a ClutterActor

 

Since: 0.2


clutter_actor_raise ()

void
clutter_actor_raise (ClutterActor *self,
                     ClutterActor *below);

clutter_actor_raise has been deprecated since version 1.10 and should not be used in newly-written code.

Use clutter_actor_set_child_above_sibling() instead.

Puts self above below .

Both actors must have the same parent, and the parent must implement the ClutterContainer interface

This function calls clutter_container_raise_child() internally.

Parameters

self

A ClutterActor

 

below

A ClutterActor to raise above.

[allow-none]

clutter_actor_lower ()

void
clutter_actor_lower (ClutterActor *self,
                     ClutterActor *above);

clutter_actor_lower has been deprecated since version 1.10 and should not be used in newly-written code.

Use clutter_actor_set_child_below_sibling() instead.

Puts self below above .

Both actors must have the same parent, and the parent must implement the ClutterContainer interface.

This function calls clutter_container_lower_child() internally.

Parameters

self

A ClutterActor

 

above

A ClutterActor to lower below.

[allow-none]

clutter_actor_raise_top ()

void
clutter_actor_raise_top (ClutterActor *self);

clutter_actor_raise_top has been deprecated since version 1.10 and should not be used in newly-written code.

Use clutter_actor_set_child_above_sibling() with a NULL sibling, instead.

Raises self to the top.

This function calls clutter_actor_raise() internally.

Parameters

self

A ClutterActor

 

clutter_actor_lower_bottom ()

void
clutter_actor_lower_bottom (ClutterActor *self);

clutter_actor_lower_bottom has been deprecated since version 1.10 and should not be used in newly-written code.

Use clutter_actor_set_child_below_sibling() with a NULL sibling, instead.

Lowers self to the bottom.

This function calls clutter_actor_lower() internally.

Parameters

self

A ClutterActor

 

clutter_actor_set_shader ()

gboolean
clutter_actor_set_shader (ClutterActor *self,
                          ClutterShader *shader);

clutter_actor_set_shader has been deprecated since version 1.8 and should not be used in newly-written code.

Use ClutterShaderEffect and clutter_actor_add_effect() instead.

Sets the ClutterShader to be used when rendering self .

If shader is NULL this function will unset any currently set shader for the actor.

Any ClutterEffect applied to self will take the precedence over the ClutterShader set using this function.

Parameters

self

a ClutterActor

 

shader

a ClutterShader or NULL to unset the shader.

[allow-none]

Returns

TRUE if the shader was successfully applied or removed

Since: 0.6


clutter_actor_get_shader ()

ClutterShader *
clutter_actor_get_shader (ClutterActor *self);

clutter_actor_get_shader has been deprecated since version 1.8 and should not be used in newly-written code.

Use clutter_actor_get_effect() instead.

Queries the currently set ClutterShader on self .

Parameters

self

a ClutterActor

 

Returns

The currently set ClutterShader or NULL if no shader is set.

[transfer none]

Since: 0.6


clutter_actor_set_shader_param ()

void
clutter_actor_set_shader_param (ClutterActor *self,
                                const gchar *param,
                                const GValue *value);

clutter_actor_set_shader_param has been deprecated since version 1.8 and should not be used in newly-written code.

Use clutter_shader_effect_set_uniform_value() instead

Sets the value for a named parameter of the shader applied to actor .

Parameters

self

a ClutterActor

 

param

the name of the parameter

 

value

the value of the parameter

 

Since: 1.0


clutter_actor_set_shader_param_float ()

void
clutter_actor_set_shader_param_float (ClutterActor *self,
                                      const gchar *param,
                                      gfloat value);

clutter_actor_set_shader_param_float has been deprecated since version 1.8 and should not be used in newly-written code.

Use clutter_shader_effect_set_uniform() instead

Sets the value for a named float parameter of the shader applied to actor .

Parameters

self

a ClutterActor

 

param

the name of the parameter

 

value

the value of the parameter

 

Since: 0.8


clutter_actor_set_shader_param_int ()

void
clutter_actor_set_shader_param_int (ClutterActor *self,
                                    const gchar *param,
                                    gint value);

clutter_actor_set_shader_param_int has been deprecated since version 1.8 and should not be used in newly-written code.

Use clutter_shader_effect_set_uniform() instead

Sets the value for a named int parameter of the shader applied to actor .

Parameters

self

a ClutterActor

 

param

the name of the parameter

 

value

the value of the parameter

 

Since: 0.8


clutter_actor_set_anchor_point ()

void
clutter_actor_set_anchor_point (ClutterActor *self,
                                gfloat anchor_x,
                                gfloat anchor_y);

clutter_actor_set_anchor_point has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” instead.

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.

Parameters

self

a ClutterActor

 

anchor_x

X coordinate of the anchor point

 

anchor_y

Y coordinate of the anchor point

 

Since: 0.6


clutter_actor_get_anchor_point ()

void
clutter_actor_get_anchor_point (ClutterActor *self,
                                gfloat *anchor_x,
                                gfloat *anchor_y);

clutter_actor_get_anchor_point has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” instead

Gets the current anchor point of the actor in pixels.

Parameters

self

a ClutterActor

 

anchor_x

return location for the X coordinate of the anchor point.

[out]

anchor_y

return location for the Y coordinate of the anchor point.

[out]

Since: 0.6


clutter_actor_set_anchor_point_from_gravity ()

void
clutter_actor_set_anchor_point_from_gravity
                               (ClutterActor *self,
                                ClutterGravity gravity);

clutter_actor_set_anchor_point_from_gravity has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” and clutter_actor_set_translation() instead. E.g. For CLUTTER_GRAVITY_CENTER set pivot_point to (0.5,0.5) and the translation to (width/2,height/2).

Sets an anchor point on the actor, based on the given gravity (this is a convenience function wrapping clutter_actor_set_anchor_point()).

Since version 1.0 the anchor point will be stored as a gravity so that if the actor changes size then the anchor point will move. For example, if you set the anchor point to CLUTTER_GRAVITY_SOUTH_EAST and later double the size of the actor, the anchor point will move to the bottom right.

Parameters

self

a ClutterActor

 

gravity

ClutterGravity.

 

Since: 0.6


clutter_actor_get_anchor_point_gravity ()

ClutterGravity
clutter_actor_get_anchor_point_gravity
                               (ClutterActor *self);

clutter_actor_get_anchor_point_gravity has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” instead.

Retrieves the anchor position expressed as a ClutterGravity. If the anchor point was specified using pixels or units this will return CLUTTER_GRAVITY_NONE.

Parameters

self

a ClutterActor

 

Returns

the ClutterGravity used by the anchor point

Since: 1.0


clutter_actor_move_anchor_point ()

void
clutter_actor_move_anchor_point (ClutterActor *self,
                                 gfloat anchor_x,
                                 gfloat anchor_y);

clutter_actor_move_anchor_point has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” and clutter_actor_set_translation() instead.

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.

Parameters

self

a ClutterActor

 

anchor_x

X coordinate of the anchor point

 

anchor_y

Y coordinate of the anchor point

 

Since: 0.6


clutter_actor_move_anchor_point_from_gravity ()

void
clutter_actor_move_anchor_point_from_gravity
                               (ClutterActor *self,
                                ClutterGravity gravity);

clutter_actor_move_anchor_point_from_gravity has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” and clutter_actor_set_translation() instead.

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 version 1.0 the anchor point will be stored as a gravity so that if the actor changes size then the anchor point will move. For example, if you set the anchor point to CLUTTER_GRAVITY_SOUTH_EAST and later double the size of the actor, the anchor point will move to the bottom right.

Parameters

self

a ClutterActor

 

gravity

ClutterGravity.

 

Since: 0.6


clutter_actor_set_rotation ()

void
clutter_actor_set_rotation (ClutterActor *self,
                            ClutterRotateAxis axis,
                            gdouble angle,
                            gfloat x,
                            gfloat y,
                            gfloat z);

clutter_actor_set_rotation has been deprecated since version 1.12 and should not be used in newly-written code.

Use clutter_actor_set_rotation_angle() and clutter_actor_set_pivot_point() instead.

Sets the rotation angle of self around the given axis.

The rotation center coordinates used depend on the value of axis :

The rotation coordinates are relative to the anchor point of the actor, set using clutter_actor_set_anchor_point(). If no anchor point is set, the upper left corner is assumed as the origin.

Parameters

self

a ClutterActor

 

axis

the axis of rotation

 

angle

the angle of rotation

 

x

X coordinate of the rotation center

 

y

Y coordinate of the rotation center

 

z

Z coordinate of the rotation center

 

Since: 0.8


clutter_actor_get_rotation ()

gdouble
clutter_actor_get_rotation (ClutterActor *self,
                            ClutterRotateAxis axis,
                            gfloat *x,
                            gfloat *y,
                            gfloat *z);

clutter_actor_get_rotation has been deprecated since version 1.12 and should not be used in newly-written code.

Use clutter_actor_get_rotation_angle() and clutter_actor_get_pivot_point() instead.

Retrieves the angle and center of rotation on the given axis, set using clutter_actor_set_rotation().

Parameters

self

a ClutterActor

 

axis

the axis of rotation

 

x

return value for the X coordinate of the center of rotation.

[out]

y

return value for the Y coordinate of the center of rotation.

[out]

z

return value for the Z coordinate of the center of rotation.

[out]

Returns

the angle of rotation

Since: 0.8


clutter_actor_set_z_rotation_from_gravity ()

void
clutter_actor_set_z_rotation_from_gravity
                               (ClutterActor *self,
                                gdouble angle,
                                ClutterGravity gravity);

clutter_actor_set_z_rotation_from_gravity has been deprecated since version 1.12 and should not be used in newly-written code.

Use clutter_actor_set_rotation_angle() and clutter_actor_set_pivot_point() instead.

Sets the rotation angle of self around the Z axis using the center point specified as a compass point. For example to rotate such that the center of the actor remains static you can use CLUTTER_GRAVITY_CENTER. If the actor changes size the center point will move accordingly.

Parameters

self

a ClutterActor

 

angle

the angle of rotation

 

gravity

the center point of the rotation

 

Since: 1.0


clutter_actor_get_z_rotation_gravity ()

ClutterGravity
clutter_actor_get_z_rotation_gravity (ClutterActor *self);

clutter_actor_get_z_rotation_gravity has been deprecated since version 1.12 and should not be used in newly-written code.

Use the “pivot-point” instead of a ClutterGravity

Retrieves the center for the rotation around the Z axis as a compass direction. If the center was specified in pixels or units this will return CLUTTER_GRAVITY_NONE.

Parameters

self

A ClutterActor

 

Returns

the Z rotation center

Since: 1.0


clutter_actor_get_transformation_matrix ()

void
clutter_actor_get_transformation_matrix
                               (ClutterActor *self,
                                ClutterMatrix *matrix);

clutter_actor_get_transformation_matrix has been deprecated since version 1.12 and should not be used in newly-written code.

Use clutter_actor_get_transform() instead

Retrieves the transformations applied to self relative to its parent.

Parameters

self

a ClutterActor

 

matrix

the return location for a ClutterMatrix.

[out caller-allocates]

Since: 1.0

Types and Values

enum ClutterActorFlags

Flags used to signal the state of an actor.

Members

CLUTTER_ACTOR_MAPPED

the actor will be painted (is visible, and inside a toplevel, and all parents visible)

 

CLUTTER_ACTOR_REALIZED

the resources associated to the actor have been allocated

 

CLUTTER_ACTOR_REACTIVE

the actor 'reacts' to mouse events emmitting event signals

 

CLUTTER_ACTOR_VISIBLE

the actor has been shown by the application program

 

CLUTTER_ACTOR_NO_LAYOUT

the actor provides an explicit layout management policy for its children; this flag will prevent Clutter from automatic queueing of relayout and will defer all layouting to the actor itself

 

enum ClutterRequestMode

Specifies the type of requests for a ClutterActor.

Members

CLUTTER_REQUEST_HEIGHT_FOR_WIDTH

Height for width requests

 

CLUTTER_REQUEST_WIDTH_FOR_HEIGHT

Width for height requests

 

CLUTTER_REQUEST_CONTENT_SIZE

Use the preferred size of the ClutterContent, if it has any (available since 1.22)

 

Since: 0.8


ClutterActor

typedef struct {
  guint32 flags;
} ClutterActor;

Base class for actors.

Members

guint32 flags;

ClutterActorFlags

 

struct ClutterActorClass

struct ClutterActorClass {
  void (* show)                 (ClutterActor          *self);
  void (* show_all)             (ClutterActor          *self);
  void (* hide)                 (ClutterActor          *self);
  void (* hide_all)             (ClutterActor          *self);
  void (* realize)              (ClutterActor          *self);
  void (* unrealize)            (ClutterActor          *self);
  void (* map)                  (ClutterActor          *self);
  void (* unmap)                (ClutterActor          *self);
  void (* paint)                (ClutterActor          *self);
  void (* parent_set)           (ClutterActor          *actor,
                                 ClutterActor          *old_parent);

  void (* destroy)              (ClutterActor          *self);
  void (* pick)                 (ClutterActor          *actor,
                                 const ClutterColor    *color);

  void (* queue_redraw)         (ClutterActor          *actor,
                                 ClutterActor          *leaf_that_queued);

  /* size negotiation */
  void (* get_preferred_width)  (ClutterActor           *self,
                                 gfloat                  for_height,
                                 gfloat                 *min_width_p,
                                 gfloat                 *natural_width_p);
  void (* get_preferred_height) (ClutterActor           *self,
                                 gfloat                  for_width,
                                 gfloat                 *min_height_p,
                                 gfloat                 *natural_height_p);
  void (* allocate)             (ClutterActor           *self,
                                 const ClutterActorBox  *box,
                                 ClutterAllocationFlags  flags);

  /* transformations */
  void (* apply_transform)      (ClutterActor           *actor,
                                 ClutterMatrix          *matrix);

  /* event signals */
  gboolean (* event)                (ClutterActor         *actor,
                                     ClutterEvent         *event);
  gboolean (* button_press_event)   (ClutterActor         *actor,
                                     ClutterButtonEvent   *event);
  gboolean (* button_release_event) (ClutterActor         *actor,
                                     ClutterButtonEvent   *event);
  gboolean (* scroll_event)         (ClutterActor         *actor,
                                     ClutterScrollEvent   *event);
  gboolean (* key_press_event)      (ClutterActor         *actor,
                                     ClutterKeyEvent      *event);
  gboolean (* key_release_event)    (ClutterActor         *actor,
                                     ClutterKeyEvent      *event);
  gboolean (* motion_event)         (ClutterActor         *actor,
                                     ClutterMotionEvent   *event);
  gboolean (* enter_event)          (ClutterActor         *actor,
                                     ClutterCrossingEvent *event);
  gboolean (* leave_event)          (ClutterActor         *actor,
                                     ClutterCrossingEvent *event);
  gboolean (* captured_event)       (ClutterActor         *actor,
                                     ClutterEvent         *event);
  void     (* key_focus_in)         (ClutterActor         *actor);
  void     (* key_focus_out)        (ClutterActor         *actor);

  void     (* queue_relayout)       (ClutterActor         *self);

  /* accessibility support */
  AtkObject * (* get_accessible)    (ClutterActor         *self);

  gboolean (* get_paint_volume)     (ClutterActor         *actor,
                                     ClutterPaintVolume   *volume);

  gboolean (* has_overlaps)         (ClutterActor         *self);

  void     (* paint_node)           (ClutterActor         *self,
                                     ClutterPaintNode     *root);

  gboolean (* touch_event)          (ClutterActor         *self,
                                     ClutterTouchEvent    *event);
};

Base class for actors.

Members

show ()

signal class handler for “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(). This virtual function is deprecated and it should not be overridden.

 

hide ()

signal class handler for “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 clutter_actor_hide(). This virtual function is deprecated and it should not be overridden.

 

realize ()

virtual function, used to allocate resources for the actor; it should chain up to the parent's implementation. This virtual function is deprecated and should not be overridden in newly written code.

 

unrealize ()

virtual function, used to deallocate resources allocated in ::realize; it should chain up to the parent's implementation. This function is deprecated and should not be overridden in newly written code.

 

map ()

virtual function for containers and composite actors, to map their children; it must chain up to the parent's implementation. Overriding this function is optional.

 

unmap ()

virtual function for containers and composite actors, to unmap their children; it must chain up to the parent's implementation. Overriding this function is optional.

 

paint ()

virtual function, used to paint the actor

 

parent_set ()

signal class handler for the “parent-set”

 

destroy ()

signal class handler for “destroy”. It must chain up to the parent's implementation

 

pick ()

virtual function, used to draw an outline of the actor with the given color

 

queue_redraw ()

class handler for “queue-redraw”

 

get_preferred_width ()

virtual function, used when querying the minimum and natural widths of an actor for a given height; it is used by clutter_actor_get_preferred_width()

 

get_preferred_height ()

virtual function, used when querying the minimum and natural heights of an actor for a given width; it is used by clutter_actor_get_preferred_height()

 

allocate ()

virtual function, used when settings the coordinates of an actor; it is used by clutter_actor_allocate(); it must chain up to the parent's implementation, or call clutter_actor_set_allocation()

 

apply_transform ()

virtual function, used when applying the transformations to an actor before painting it or when transforming coordinates or the allocation; it must chain up to the parent's implementation

 

event ()

class handler for “event”

 

button_press_event ()

class handler for “button-press-event”

 

button_release_event ()

class handler for “button-release-event”

 

scroll_event ()

signal class closure for “scroll-event”

 

key_press_event ()

signal class closure for “key-press-event”

 

key_release_event ()

signal class closure for “key-release-event”

 

motion_event ()

signal class closure for “motion-event”

 

enter_event ()

signal class closure for “enter-event”

 

leave_event ()

signal class closure for “leave-event”

 

captured_event ()

signal class closure for “captured-event”

 

key_focus_in ()

signal class closure for “key-focus-in”

 

key_focus_out ()

signal class closure for “key-focus-out”

 

queue_relayout ()

class handler for “queue-relayout”

 

get_accessible ()

virtual function, returns the accessible object that describes the actor to an assistive technology.

 

get_paint_volume ()

virtual function, for sub-classes to define their ClutterPaintVolume

 

has_overlaps ()

virtual function for sub-classes to advertise whether they need an offscreen redirect to get the correct opacity. See clutter_actor_set_offscreen_redirect() for details.

 

paint_node ()

virtual function for creating paint nodes and attaching them to the render tree

 

touch_event ()

signal class closure for “touch-event”

 

enum ClutterAllocationFlags

Flags passed to the ClutterActorClass.allocate() virtual function and to the clutter_actor_allocate() function.

Members

CLUTTER_ALLOCATION_NONE

No flag set

 

CLUTTER_ABSOLUTE_ORIGIN_CHANGED

Whether the absolute origin of the actor has changed; this implies that any ancestor of the actor has been moved.

 

CLUTTER_DELEGATE_LAYOUT

Whether the allocation should be delegated to the ClutterLayoutManager instance stored inside the “layout-manager” property of ClutterActor. This flag should only be used if you are subclassing ClutterActor and overriding the ClutterActorClass.allocate() virtual function, but you wish to use the default implementation of the virtual function inside ClutterActor. Added in Clutter 1.10.

 

Since: 1.0


enum ClutterActorAlign

Controls how a ClutterActor should align itself inside the extra space assigned to it during the allocation.

Alignment only matters if the allocated space given to an actor is bigger than its natural size; for example, when the “x-expand” or the “y-expand” properties of ClutterActor are set to TRUE.

Members

CLUTTER_ACTOR_ALIGN_FILL

Stretch to cover the whole allocated space

 

CLUTTER_ACTOR_ALIGN_START

Snap to left or top side, leaving space to the right or bottom. For horizontal layouts, in right-to-left locales this should be reversed.

 

CLUTTER_ACTOR_ALIGN_CENTER

Center the actor inside the allocation

 

CLUTTER_ACTOR_ALIGN_END

Snap to right or bottom side, leaving space to the left or top. For horizontal layouts, in right-to-left locales this should be reversed.

 

Since: 1.10


struct ClutterMargin

struct ClutterMargin {
  float left;
  float right;
  float top;
  float bottom;
};

A representation of the components of a margin.

Members

float left;

the margin from the left

 

float right;

the margin from the right

 

float top;

the margin from the top

 

float bottom;

the margin from the bottom

 

Since: 1.10


enum ClutterContentGravity

Controls the alignment of the ClutterContent inside a ClutterActor.

Members

CLUTTER_CONTENT_GRAVITY_TOP_LEFT

Align the content to the top left corner

 

CLUTTER_CONTENT_GRAVITY_TOP

Align the content to the top edge

 

CLUTTER_CONTENT_GRAVITY_TOP_RIGHT

Align the content to the top right corner

 

CLUTTER_CONTENT_GRAVITY_LEFT

Align the content to the left edge

 

CLUTTER_CONTENT_GRAVITY_CENTER

Align the content to the center

 

CLUTTER_CONTENT_GRAVITY_RIGHT

Align the content to the right edge

 

CLUTTER_CONTENT_GRAVITY_BOTTOM_LEFT

Align the content to the bottom left corner

 

CLUTTER_CONTENT_GRAVITY_BOTTOM

Align the content to the bottom edge

 

CLUTTER_CONTENT_GRAVITY_BOTTOM_RIGHT

Align the content to the bottom right corner

 

CLUTTER_CONTENT_GRAVITY_RESIZE_FILL

Resize the content to fill the allocation

 

CLUTTER_CONTENT_GRAVITY_RESIZE_ASPECT

Resize the content to remain within the allocation, while maintaining the aspect ratio

 

Since: 1.10


enum ClutterScalingFilter

The scaling filters to be used with the “minification-filter” and “magnification-filter” properties.

Members

CLUTTER_SCALING_FILTER_LINEAR

Linear interpolation filter

 

CLUTTER_SCALING_FILTER_NEAREST

Nearest neighbor interpolation filter

 

CLUTTER_SCALING_FILTER_TRILINEAR

Trilinear minification filter, with mipmap generation; this filter linearly interpolates on every axis, as well as between mipmap levels.

 

Since: 1.10


enum ClutterContentRepeat

Content repeat modes.

Members

CLUTTER_REPEAT_NONE

No repeat

 

CLUTTER_REPEAT_X_AXIS

Repeat the content on the X axis

 

CLUTTER_REPEAT_Y_AXIS

Repeat the content on the Y axis

 

CLUTTER_REPEAT_BOTH

Repeat the content on both axis

 

Since: 1.12


enum ClutterOffscreenRedirect

Possible flags to pass to clutter_actor_set_offscreen_redirect().

Members

CLUTTER_OFFSCREEN_REDIRECT_AUTOMATIC_FOR_OPACITY

Only redirect the actor if it is semi-transparent and its has_overlaps() virtual returns TRUE. This is the default.

 

CLUTTER_OFFSCREEN_REDIRECT_ALWAYS

Always redirect the actor to an offscreen buffer even if it is fully opaque.

 

Since: 1.8


ClutterActorIter

typedef struct {
} ClutterActorIter;

An iterator structure that allows to efficiently iterate over a section of the scene graph.

The contents of the ClutterActorIter structure are private and should only be accessed using the provided API.

Since: 1.10

Property Details

The “actions” property

  “actions”                  ClutterAction *

Adds a ClutterAction to the actor

Flags: Write

Since: 1.4


The “allocation” property

  “allocation”               ClutterActorBox *

The allocation for the actor, in pixels

This is property is read-only, but you might monitor it to know when an actor moves or resizes

Flags: Read

Since: 0.8


The “anchor-gravity” property

  “anchor-gravity”           ClutterGravity

The anchor point expressed as a ClutterGravity

It is highly recommended not to use “anchor-x”, “anchor-y”, and “anchor-gravity” in newly written code; the anchor point adds an additional translation that will affect the actor's relative position with regards to its parent, as well as the position of its children. This change needs to always be taken into account when positioning the actor. It is recommended to use the “pivot-point” property instead, as it will affect only the transformations.

ClutterActor:anchor-gravity has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” instead

Flags: Read / Write

Default value: CLUTTER_GRAVITY_NONE

Since: 1.0


The “anchor-x” property

  “anchor-x”                 gfloat

The X coordinate of an actor's anchor point, relative to the actor coordinate space, in pixels.

It is highly recommended not to use “anchor-x”, “anchor-y”, and “anchor-gravity” in newly written code; the anchor point adds an additional translation that will affect the actor's relative position with regards to its parent, as well as the position of its children. This change needs to always be taken into account when positioning the actor. It is recommended to use the “pivot-point” property instead, as it will affect only the transformations.

ClutterActor:anchor-x has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” instead

Flags: Read / Write

Default value: 0

Since: 0.8


The “anchor-y” property

  “anchor-y”                 gfloat

The Y coordinate of an actor's anchor point, relative to the actor coordinate space, in pixels

It is highly recommended not to use “anchor-x”, “anchor-y”, and “anchor-gravity” in newly written code; the anchor point adds an additional translation that will affect the actor's relative position with regards to its parent, as well as the position of its children. This change needs to always be taken into account when positioning the actor. It is recommended to use the “pivot-point” property instead, as it will affect only the transformations.

ClutterActor:anchor-y has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” instead

Flags: Read / Write

Default value: 0

Since: 0.8


The “background-color” property

  “background-color”         ClutterColor *

Paints a solid fill of the actor's allocation using the specified color.

The “background-color” property is animatable.

Flags: Read / Write

Since: 1.10


The “background-color-set” property

  “background-color-set”     gboolean

Whether the “background-color” property has been set.

Flags: Read

Default value: FALSE

Since: 1.10


The “child-transform” property

  “child-transform”          ClutterMatrix *

Applies a transformation matrix on each child of an actor.

Setting this property with a ClutterMatrix will set the “child-transform-set” property to TRUE as a side effect; setting this property with NULL will set the “child-transform-set” property to FALSE.

The “child-transform” property is animatable.

Flags: Read / Write

Since: 1.12


The “child-transform-set” property

  “child-transform-set”      gboolean

Whether the “child-transform” property is set.

Flags: Read

Default value: FALSE

Since: 1.12


The “clip” property

  “clip”                     ClutterGeometry *

The visible region of the actor, in actor-relative coordinates

ClutterActor:clip has been deprecated since version 1.12 and should not be used in newly-written code.

Use “clip-rect” instead.

Flags: Read / Write


The “clip-rect” property

  “clip-rect”                ClutterRect *

The visible region of the actor, in actor-relative coordinates, expressed as a ClutterRect.

Setting this property to NULL will unset the existing clip.

Setting this property will change the “has-clip” property as a side effect.

Flags: Read / Write

Since: 1.12


The “clip-to-allocation” property

  “clip-to-allocation”       gboolean

Whether the clip region should track the allocated area of the actor.

This property is ignored if a clip area has been explicitly set using clutter_actor_set_clip().

Flags: Read / Write

Default value: FALSE

Since: 1.0


The “constraints” property

  “constraints”              ClutterConstraint *

Adds a ClutterConstraint to the actor

Flags: Write

Since: 1.4


The “content” property

  “content”                  ClutterContent *

The ClutterContent implementation that controls the content of the actor.

Flags: Read / Write

Since: 1.10


The “content-box” property

  “content-box”              ClutterActorBox *

The bounding box for the ClutterContent used by the actor.

The value of this property is controlled by the “allocation” and “content-gravity” properties of ClutterActor.

The bounding box for the content is guaranteed to never exceed the allocation's of the actor.

Flags: Read

Since: 1.10


The “content-gravity” property

  “content-gravity”          ClutterContentGravity

The alignment that should be honoured by the ClutterContent set with the “content” property.

Changing the value of this property will change the bounding box of the content; you can use the “content-box” property to get the position and size of the content within the actor's allocation.

This property is meaningful only for ClutterContent implementations that have a preferred size, and if the preferred size is smaller than the actor's allocation.

The “content-gravity” property is animatable.

Flags: Read / Write

Default value: CLUTTER_CONTENT_GRAVITY_RESIZE_FILL

Since: 1.10


The “content-repeat” property

  “content-repeat”           ClutterContentRepeat

The repeat policy for the actor's “content”.

Flags: Read / Write

Since: 1.12


The “depth” property

  “depth”                    gfloat

The position of the actor on the Z axis.

The “depth” property is relative to the parent's modelview matrix.

Setting this property will call ClutterContainerIface.sort_depth_order() which is usually a no-op, and it's most likely not what you want.

The “depth” property is animatable.

ClutterActor:depth has been deprecated since version 1.12 and should not be used in newly-written code.

Use “z-position” instead.

Flags: Read / Write

Default value: 0

Since: 0.6


The “effect” property

  “effect”                   ClutterEffect *

Adds ClutterEffect to the list of effects be applied on a ClutterActor

Flags: Write

Since: 1.4


The “first-child” property

  “first-child”              ClutterActor *

The actor's first child.

Flags: Read

Since: 1.10


The “fixed-position-set” property

  “fixed-position-set”       gboolean

This flag controls whether the “fixed-x” and “fixed-y” properties are used

Flags: Read / Write

Default value: FALSE

Since: 0.8


The “fixed-x” property

  “fixed-x”                  gfloat

The fixed X position of the actor in pixels.

Writing this property sets “fixed-position-set” property as well, as a side effect

Flags: Read / Write

Default value: 0

Since: 0.8


The “fixed-y” property

  “fixed-y”                  gfloat

The fixed Y position of the actor in pixels.

Writing this property sets the “fixed-position-set” property as well, as a side effect

Flags: Read / Write

Default value: 0

Since: 0.8


The “has-clip” property

  “has-clip”                 gboolean

Whether the actor has the “clip” property set or not

Flags: Read

Default value: FALSE


The “has-pointer” property

  “has-pointer”              gboolean

Whether the actor contains the pointer of a ClutterInputDevice or not.

Flags: Read

Default value: FALSE

Since: 1.2


The “height” property

  “height”                   gfloat

Height of the actor (in pixels). If written, forces the minimum and natural size request of the actor to the given height. If read, returns the allocated height if available, otherwise the height request.

The “height” property is animatable.

Flags: Read / Write

Allowed values: >= 0

Default value: 0


The “last-child” property

  “last-child”               ClutterActor *

The actor's last child.

Flags: Read

Since: 1.10


The “layout-manager” property

  “layout-manager”           ClutterLayoutManager *

A delegate object for controlling the layout of the children of an actor.

Flags: Read / Write

Since: 1.10


The “magnification-filter” property

  “magnification-filter”     ClutterScalingFilter

The filter used when increasing the size of the content.

Flags: Read / Write

Default value: CLUTTER_SCALING_FILTER_LINEAR


The “mapped” property

  “mapped”                   gboolean

Whether the actor is mapped (will be painted when the stage to which it belongs is mapped)

Flags: Read

Default value: FALSE

Since: 1.0


The “margin-bottom” property

  “margin-bottom”            gfloat

The margin (in pixels) from the bottom of the actor.

This property adds a margin to the actor's preferred size; the margin will be automatically taken into account when allocating the actor.

The “margin-bottom” property is animatable.

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 1.10


The “margin-left” property

  “margin-left”              gfloat

The margin (in pixels) from the left of the actor.

This property adds a margin to the actor's preferred size; the margin will be automatically taken into account when allocating the actor.

The “margin-left” property is animatable.

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 1.10


The “margin-right” property

  “margin-right”             gfloat

The margin (in pixels) from the right of the actor.

This property adds a margin to the actor's preferred size; the margin will be automatically taken into account when allocating the actor.

The “margin-right” property is animatable.

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 1.10


The “margin-top” property

  “margin-top”               gfloat

The margin (in pixels) from the top of the actor.

This property adds a margin to the actor's preferred size; the margin will be automatically taken into account when allocating the actor.

The “margin-top” property is animatable.

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 1.10


The “min-height” property

  “min-height”               gfloat

A forced minimum height request for the actor, in pixels

Writing this property sets the “min-height-set” property as well, as a side effect. This property overrides the usual height request of the actor.

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 0.8


The “min-height-set” property

  “min-height-set”           gboolean

This flag controls whether the “min-height” property is used

Flags: Read / Write

Default value: FALSE

Since: 0.8


The “min-width” property

  “min-width”                gfloat

A forced minimum width request for the actor, in pixels

Writing this property sets the “min-width-set” property as well, as a side effect.

This property overrides the usual width request of the actor.

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 0.8


The “min-width-set” property

  “min-width-set”            gboolean

This flag controls whether the “min-width” property is used

Flags: Read / Write

Default value: FALSE

Since: 0.8


The “minification-filter” property

  “minification-filter”      ClutterScalingFilter

The filter used when reducing the size of the content.

Flags: Read / Write

Default value: CLUTTER_SCALING_FILTER_LINEAR


The “name” property

  “name”                     gchar *

The name of the actor

Flags: Read / Write

Default value: NULL

Since: 0.2


The “natural-height” property

  “natural-height”           gfloat

A forced natural height request for the actor, in pixels

Writing this property sets the “natural-height-set” property as well, as a side effect. This property overrides the usual height request of the actor

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 0.8


The “natural-height-set” property

  “natural-height-set”       gboolean

This flag controls whether the “natural-height” property is used

Flags: Read / Write

Default value: FALSE

Since: 0.8


The “natural-width” property

  “natural-width”            gfloat

A forced natural width request for the actor, in pixels

Writing this property sets the “natural-width-set” property as well, as a side effect. This property overrides the usual width request of the actor

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 0.8


The “natural-width-set” property

  “natural-width-set”        gboolean

This flag controls whether the “natural-width” property is used

Flags: Read / Write

Default value: FALSE

Since: 0.8


The “offscreen-redirect” property

  “offscreen-redirect”       ClutterOffscreenRedirect

Determines the conditions in which the actor will be redirected to an offscreen framebuffer while being painted. For example this can be used to cache an actor in a framebuffer or for improved handling of transparent actors. See clutter_actor_set_offscreen_redirect() for details.

Flags: Read / Write

Since: 1.8


The “opacity” property

  “opacity”                  guint

Opacity of an actor, between 0 (fully transparent) and 255 (fully opaque)

The “opacity” property is animatable.

Flags: Read / Write

Allowed values: <= 255

Default value: 255


The “pivot-point” property

  “pivot-point”              ClutterPoint *

The point around which the scaling and rotation transformations occur.

The pivot point is expressed in normalized coordinates space, with (0, 0) being the top left corner of the actor and (1, 1) the bottom right corner of the actor.

The default pivot point is located at (0, 0).

The “pivot-point” property is animatable.

Flags: Read / Write

Since: 1.12


The “pivot-point-z” property

  “pivot-point-z”            gfloat

The Z component of the “pivot-point”, expressed as a value along the Z axis.

The “pivot-point-z” property is animatable.

Flags: Read / Write

Default value: 0

Since: 1.12


The “position” property

  “position”                 ClutterPoint *

The position of the origin of the actor.

This property is a shorthand for setting and getting the “x” and “y” properties at the same time.

The “position” property is animatable.

Flags: Read / Write

Since: 1.12


The “reactive” property

  “reactive”                 gboolean

Whether the actor is reactive to events or not

Only reactive actors will emit event-related signals

Flags: Read / Write

Default value: FALSE

Since: 0.6


The “realized” property

  “realized”                 gboolean

Whether the actor has been realized

Flags: Read

Default value: FALSE

Since: 1.0


The “request-mode” property

  “request-mode”             ClutterRequestMode

Request mode for the ClutterActor. The request mode determines the type of geometry management used by the actor, either height for width (the default) or width for height.

For actors implementing height for width, the parent container should get the preferred width first, and then the preferred height for that width.

For actors implementing width for height, the parent container should get the preferred height first, and then the preferred width for that height.

For instance:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
ClutterRequestMode mode;
gfloat natural_width, min_width;
gfloat natural_height, min_height;

mode = clutter_actor_get_request_mode (child);
if (mode == CLUTTER_REQUEST_HEIGHT_FOR_WIDTH)
  {
    clutter_actor_get_preferred_width (child, -1,
                                       &min_width,
                                       &natural_width);
    clutter_actor_get_preferred_height (child, natural_width,
                                        &min_height,
                                        &natural_height);
  }
else if (mode == CLUTTER_REQUEST_WIDTH_FOR_HEIGHT)
  {
    clutter_actor_get_preferred_height (child, -1,
                                        &min_height,
                                        &natural_height);
    clutter_actor_get_preferred_width (child, natural_height,
                                       &min_width,
                                       &natural_width);
  }
else if (mode == CLUTTER_REQUEST_CONTENT_SIZE)
  {
    ClutterContent *content = clutter_actor_get_content (child);

    min_width, min_height = 0;
    natural_width = natural_height = 0;

    if (content != NULL)
      clutter_content_get_preferred_size (content, &natural_width, &natural_height);
  }

will retrieve the minimum and natural width and height depending on the preferred request mode of the ClutterActor "child".

The clutter_actor_get_preferred_size() function will implement this check for you.

Flags: Read / Write

Default value: CLUTTER_REQUEST_HEIGHT_FOR_WIDTH

Since: 0.8


The “rotation-angle-x” property

  “rotation-angle-x”         gdouble

The rotation angle on the X axis.

The “rotation-angle-x” property is animatable.

Flags: Read / Write

Default value: 0

Since: 0.6


The “rotation-angle-y” property

  “rotation-angle-y”         gdouble

The rotation angle on the Y axis

The “rotation-angle-y” property is animatable.

Flags: Read / Write

Default value: 0

Since: 0.6


The “rotation-angle-z” property

  “rotation-angle-z”         gdouble

The rotation angle on the Z axis

The “rotation-angle-z” property is animatable.

Flags: Read / Write

Default value: 0

Since: 0.6


The “rotation-center-x” property

  “rotation-center-x”        ClutterVertex *

The rotation center on the X axis.

ClutterActor:rotation-center-x has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” instead

Flags: Read / Write

Since: 0.6


The “rotation-center-y” property

  “rotation-center-y”        ClutterVertex *

The rotation center on the Y axis.

ClutterActor:rotation-center-y has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” instead

Flags: Read / Write

Since: 0.6


The “rotation-center-z” property

  “rotation-center-z”        ClutterVertex *

The rotation center on the Z axis.

ClutterActor:rotation-center-z has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” instead

Flags: Read / Write

Since: 0.6


The “rotation-center-z-gravity” property

  “rotation-center-z-gravity” ClutterGravity

The rotation center on the Z axis expressed as a ClutterGravity.

ClutterActor:rotation-center-z-gravity has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” instead

Flags: Read / Write

Default value: CLUTTER_GRAVITY_NONE

Since: 1.0


The “scale-center-x” property

  “scale-center-x”           gfloat

The horizontal center point for scaling

ClutterActor:scale-center-x has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” instead

Flags: Read / Write

Default value: 0

Since: 1.0


The “scale-center-y” property

  “scale-center-y”           gfloat

The vertical center point for scaling

ClutterActor:scale-center-y has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” instead

Flags: Read / Write

Default value: 0

Since: 1.0


The “scale-gravity” property

  “scale-gravity”            ClutterGravity

The center point for scaling expressed as a ClutterGravity

ClutterActor:scale-gravity has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” instead

Flags: Read / Write

Default value: CLUTTER_GRAVITY_NONE

Since: 1.0


The “scale-x” property

  “scale-x”                  gdouble

The horizontal scale of the actor.

The “scale-x” property is animatable.

Flags: Read / Write

Default value: 1

Since: 0.6


The “scale-y” property

  “scale-y”                  gdouble

The vertical scale of the actor.

The “scale-y” property is animatable.

Flags: Read / Write

Default value: 1

Since: 0.6


The “scale-z” property

  “scale-z”                  gdouble

The scale factor of the actor along the Z axis.

The “scale-y” property is animatable.

Flags: Read / Write

Default value: 1

Since: 1.12


The “show-on-set-parent” property

  “show-on-set-parent”       gboolean

If TRUE, the actor is automatically shown when parented.

Calling clutter_actor_hide() on an actor which has not been parented will set this property to FALSE as a side effect.

Flags: Read / Write

Default value: TRUE

Since: 0.8


The “size” property

  “size”                     ClutterSize *

The size of the actor.

This property is a shorthand for setting and getting the “width” and “height” at the same time.

The “size” property is animatable.

Flags: Read / Write

Since: 1.12


The “text-direction” property

  “text-direction”           ClutterTextDirection

The direction of the text inside a ClutterActor.

Flags: Read / Write

Default value: CLUTTER_TEXT_DIRECTION_LTR

Since: 1.0


The “transform” property

  “transform”                ClutterMatrix *

Overrides the transformations of a ClutterActor with a custom matrix.

The matrix specified by the “transform” property is applied to the actor and its children relative to the actor's “allocation” and “pivot-point”.

Application code should rarely need to use this function directly.

Setting this property with a ClutterMatrix will set the “transform-set” property to TRUE as a side effect; setting this property with NULL will set the “transform-set” property to FALSE.

The “transform” property is animatable.

Flags: Read / Write

Since: 1.12


The “transform-set” property

  “transform-set”            gboolean

Whether the “transform” property is set.

Flags: Read

Default value: FALSE

Since: 1.12


The “translation-x” property

  “translation-x”            gfloat

An additional translation applied along the X axis, relative to the actor's “pivot-point”.

The “translation-x” property is animatable.

Flags: Read / Write

Default value: 0

Since: 1.12


The “translation-y” property

  “translation-y”            gfloat

An additional translation applied along the Y axis, relative to the actor's “pivot-point”.

The “translation-y” property is animatable.

Flags: Read / Write

Default value: 0

Since: 1.12


The “translation-z” property

  “translation-z”            gfloat

An additional translation applied along the Z axis, relative to the actor's “pivot-point”.

The “translation-z” property is animatable.

Flags: Read / Write

Default value: 0

Since: 1.12


The “visible” property

  “visible”                  gboolean

Whether the actor is set to be visible or not

See also “mapped”

Flags: Read / Write

Default value: FALSE


The “width” property

  “width”                    gfloat

Width of the actor (in pixels). If written, forces the minimum and natural size request of the actor to the given width. If read, returns the allocated width if available, otherwise the width request.

The “width” property is animatable.

Flags: Read / Write

Allowed values: >= 0

Default value: 0


The “x” property

  “x”                        gfloat

X coordinate of the actor in pixels. If written, forces a fixed position for the actor. If read, returns the fixed position if any, otherwise the allocation if available, otherwise 0.

The “x” property is animatable.

Flags: Read / Write

Default value: 0


The “x-align” property

  “x-align”                  ClutterActorAlign

The alignment of an actor on the X axis, if the actor has been given extra space for its allocation. See also the “x-expand” property.

Flags: Read / Write

Default value: CLUTTER_ACTOR_ALIGN_FILL

Since: 1.10


The “x-expand” property

  “x-expand”                 gboolean

Whether a layout manager should assign more space to the actor on the X axis.

Flags: Read / Write

Default value: FALSE

Since: 1.12


The “y” property

  “y”                        gfloat

Y coordinate of the actor in pixels. If written, forces a fixed position for the actor. If read, returns the fixed position if any, otherwise the allocation if available, otherwise 0.

The “y” property is animatable.

Flags: Read / Write

Default value: 0


The “y-align” property

  “y-align”                  ClutterActorAlign

The alignment of an actor on the Y axis, if the actor has been given extra space for its allocation.

Flags: Read / Write

Default value: CLUTTER_ACTOR_ALIGN_FILL

Since: 1.10


The “y-expand” property

  “y-expand”                 gboolean

Whether a layout manager should assign more space to the actor on the Y axis.

Flags: Read / Write

Default value: FALSE

Since: 1.12


The “z-position” property

  “z-position”               gfloat

The actor's position on the Z axis, relative to the parent's transformations.

Positive values will bring the actor's position nearer to the user, whereas negative values will bring the actor's position farther from the user.

The “z-position” does not affect the paint or allocation order.

The “z-position” property is animatable.

Flags: Read / Write

Default value: 0

Since: 1.12

Signal Details

The “allocation-changed” signal

void
user_function (ClutterActor          *actor,
               ClutterActorBox       *box,
               ClutterAllocationFlags flags,
               gpointer               user_data)

The ::allocation-changed signal is emitted when the “allocation” property changes. Usually, application code should just use the notifications for the :allocation property but if you want to track the allocation flags as well, for instance to know whether the absolute origin of actor changed, then you might want use this signal instead.

Parameters

actor

the ClutterActor that emitted the signal

 

box

a ClutterActorBox with the new allocation

 

flags

ClutterAllocationFlags for the allocation

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 1.0


The “button-press-event” signal

gboolean
user_function (ClutterActor *actor,
               ClutterEvent *event,
               gpointer      user_data)

The ::button-press-event signal is emitted each time a mouse button is pressed on actor .

Parameters

actor

the actor which received the event

 

event

a ClutterButtonEvent.

[type ClutterButtonEvent]

user_data

user data set when the signal handler was connected.

 

Returns

TRUE if the event has been handled by the actor, or FALSE to continue the emission.

Flags: Run Last

Since: 0.6


The “button-release-event” signal

gboolean
user_function (ClutterActor *actor,
               ClutterEvent *event,
               gpointer      user_data)

The ::button-release-event signal is emitted each time a mouse button is released on actor .

Parameters

actor

the actor which received the event

 

event

a ClutterButtonEvent.

[type ClutterButtonEvent]

user_data

user data set when the signal handler was connected.

 

Returns

TRUE if the event has been handled by the actor, or FALSE to continue the emission.

Flags: Run Last

Since: 0.6


The “captured-event” signal

gboolean
user_function (ClutterActor *actor,
               ClutterEvent *event,
               gpointer      user_data)

The ::captured-event signal is emitted when an event is captured by Clutter. This signal will be emitted starting from the top-level container (the ClutterStage) to the actor which received the event going down the hierarchy. This signal can be used to intercept every event before the specialized events (like ClutterActor::button-press-event or ::key-released-event) are emitted.

Parameters

actor

the actor which received the signal

 

event

a ClutterEvent

 

user_data

user data set when the signal handler was connected.

 

Returns

TRUE if the event has been handled by the actor, or FALSE to continue the emission.

Flags: Run Last

Since: 0.6


The “destroy” signal

void
user_function (ClutterActor *actor,
               gpointer      user_data)

The ::destroy signal notifies that all references held on the actor which emitted it should be released.

The ::destroy signal should be used by all holders of a reference on actor .

This signal might result in the finalization of the ClutterActor if all references are released.

Composite actors and actors implementing the ClutterContainer interface should override the default implementation of the class handler of this signal and call clutter_actor_destroy() on their children. When overriding the default class handler, it is required to chain up to the parent's implementation.

Parameters

actor

the ClutterActor which emitted the signal

 

user_data

user data set when the signal handler was connected.

 

Flags: No Hooks

Since: 0.2


The “enter-event” signal

gboolean
user_function (ClutterActor *actor,
               ClutterEvent *event,
               gpointer      user_data)

The ::enter-event signal is emitted when the pointer enters the actor

Parameters

actor

the actor which the pointer has entered.

 

event

a ClutterCrossingEvent.

[type ClutterCrossingEvent]

user_data

user data set when the signal handler was connected.

 

Returns

TRUE if the event has been handled by the actor, or FALSE to continue the emission.

Flags: Run Last

Since: 0.6


The “event” signal

gboolean
user_function (ClutterActor *actor,
               ClutterEvent *event,
               gpointer      user_data)

The ::event signal is emitted each time an event is received by the actor . This signal will be emitted on every actor, following the hierarchy chain, until it reaches the top-level container (the ClutterStage).

Parameters

actor

the actor which received the event

 

event

a ClutterEvent

 

user_data

user data set when the signal handler was connected.

 

Returns

TRUE if the event has been handled by the actor, or FALSE to continue the emission.

Flags: Run Last

Since: 0.6


The “hide” signal

void
user_function (ClutterActor *actor,
               gpointer      user_data)

The ::hide signal is emitted when an actor is no longer rendered on the stage.

Parameters

actor

the object which received the signal

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First

Since: 0.2


The “key-focus-in” signal

void
user_function (ClutterActor *actor,
               gpointer      user_data)

The ::key-focus-in signal is emitted when actor receives key focus.

Parameters

actor

the actor which now has key focus

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 0.6


The “key-focus-out” signal

void
user_function (ClutterActor *actor,
               gpointer      user_data)

The ::key-focus-out signal is emitted when actor loses key focus.

Parameters

actor

the actor which now has key focus

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 0.6


The “key-press-event” signal

gboolean
user_function (ClutterActor *actor,
               ClutterEvent *event,
               gpointer      user_data)

The ::key-press-event signal is emitted each time a keyboard button is pressed while actor has key focus (see clutter_stage_set_key_focus()).

Parameters

actor

the actor which received the event

 

event

a ClutterKeyEvent.

[type ClutterKeyEvent]

user_data

user data set when the signal handler was connected.

 

Returns

TRUE if the event has been handled by the actor, or FALSE to continue the emission.

Flags: Run Last

Since: 0.6


The “key-release-event” signal

gboolean
user_function (ClutterActor *actor,
               ClutterEvent *event,
               gpointer      user_data)

The ::key-release-event signal is emitted each time a keyboard button is released while actor has key focus (see clutter_stage_set_key_focus()).

Parameters

actor

the actor which received the event

 

event

a ClutterKeyEvent.

[type ClutterKeyEvent]

user_data

user data set when the signal handler was connected.

 

Returns

TRUE if the event has been handled by the actor, or FALSE to continue the emission.

Flags: Run Last

Since: 0.6


The “leave-event” signal

gboolean
user_function (ClutterActor *actor,
               ClutterEvent *event,
               gpointer      user_data)

The ::leave-event signal is emitted when the pointer leaves the actor .

Parameters

actor

the actor which the pointer has left

 

event

a ClutterCrossingEvent.

[type ClutterCrossingEvent]

user_data

user data set when the signal handler was connected.

 

Returns

TRUE if the event has been handled by the actor, or FALSE to continue the emission.

Flags: Run Last

Since: 0.6


The “motion-event” signal

gboolean
user_function (ClutterActor *actor,
               ClutterEvent *event,
               gpointer      user_data)

The ::motion-event signal is emitted each time the mouse pointer is moved over actor .

Parameters

actor

the actor which received the event

 

event

a ClutterMotionEvent.

[type ClutterMotionEvent]

user_data

user data set when the signal handler was connected.

 

Returns

TRUE if the event has been handled by the actor, or FALSE to continue the emission.

Flags: Run Last

Since: 0.6


The “paint” signal

void
user_function (ClutterActor *actor,
               gpointer      user_data)

The ::paint signal is emitted each time an actor is being painted.

Subclasses of ClutterActor should override the ClutterActorClass.paint virtual function paint themselves in that function.

It is strongly discouraged to connect a signal handler to the “paint” signal; if you want to change the paint sequence of an existing ClutterActor instance, either create a new ClutterActor class and override the ClutterActorClass.paint virtual function, or use a ClutterEffect. The “paint” signal will be removed in a future version of Clutter.

ClutterActor::paint has been deprecated since version 1.12 and should not be used in newly-written code.

Override the ClutterActorClass.paint virtual function, use a ClutterContent implementation, or a ClutterEffect instead of connecting to this signal.

Parameters

actor

the ClutterActor that received the signal

 

user_data

user data set when the signal handler was connected.

 

Flags: No Hooks

Since: 0.8


The “parent-set” signal

void
user_function (ClutterActor *actor,
               ClutterActor *old_parent,
               gpointer      user_data)

This signal is emitted when the parent of the actor changes.

Parameters

actor

the object which received the signal

 

old_parent

the previous parent of the actor, or NULL.

[allow-none]

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 0.2


The “pick” signal

void
user_function (ClutterActor *actor,
               ClutterColor *color,
               gpointer      user_data)

The ::pick signal is emitted each time an actor is being painted in "pick mode". The pick mode is used to identify the actor during the event handling phase, or by clutter_stage_get_actor_at_pos(). The actor should paint its shape using the passed pick_color .

Subclasses of ClutterActor should override the class signal handler and paint themselves in that function.

It is possible to connect a handler to the ::pick signal in order to set up some custom aspect of a paint in pick mode.

ClutterActor::pick has been deprecated since version 1.12 and should not be used in newly-written code.

Override the ClutterActorClass.pick virtual function instead.

Parameters

actor

the ClutterActor that received the signal

 

color

the ClutterColor to be used when picking

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 1.0


The “queue-redraw” signal

void
user_function (ClutterActor *actor,
               ClutterActor *origin,
               gpointer      user_data)

The ::queue_redraw signal is emitted when clutter_actor_queue_redraw() is called on origin .

The default implementation for ClutterActor chains up to the parent actor and queues a redraw on the parent, thus "bubbling" the redraw queue up through the actor graph. The default implementation for ClutterStage queues a clutter_stage_ensure_redraw() in a main loop idle handler.

Note that the origin actor may be the stage, or a container; it does not have to be a leaf node in the actor graph.

Toolkits embedding a ClutterStage which require a redraw and relayout cycle can stop the emission of this signal using the GSignal API, redraw the UI and then call clutter_stage_ensure_redraw() themselves, like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
static void
on_redraw_complete (gpointer data)
{
  ClutterStage *stage = data;

  // execute the Clutter drawing pipeline
  clutter_stage_ensure_redraw (stage);
}

static void
on_stage_queue_redraw (ClutterStage *stage)
{
  // this prevents the default handler to run
  g_signal_stop_emission_by_name (stage, "queue-redraw");

  // queue a redraw with the host toolkit and call
  // a function when the redraw has been completed
  queue_a_redraw (G_CALLBACK (on_redraw_complete), stage);
}

Note: This signal is emitted before the Clutter paint pipeline is executed. If you want to know when the pipeline has been completed you should use clutter_threads_add_repaint_func() or clutter_threads_add_repaint_func_full().

Parameters

actor

the actor we're bubbling the redraw request through

 

origin

the actor which initiated the redraw request

 

user_data

user data set when the signal handler was connected.

 

Flags: No Hooks

Since: 1.0


The “queue-relayout” signal

void
user_function (ClutterActor *actor,
               gpointer      user_data)

The ::queue_layout signal is emitted when clutter_actor_queue_relayout() is called on an actor.

The default implementation for ClutterActor chains up to the parent actor and queues a relayout on the parent, thus "bubbling" the relayout queue up through the actor graph.

The main purpose of this signal is to allow relayout to be propagated properly in the presence of ClutterClone actors. Applications will not normally need to connect to this signal.

Parameters

actor

the actor being queued for relayout

 

user_data

user data set when the signal handler was connected.

 

Flags: No Hooks

Since: 1.2


The “realize” signal

void
user_function (ClutterActor *actor,
               gpointer      user_data)

The ::realize signal is emitted each time an actor is being realized.

ClutterActor::realize has been deprecated since version 1.16 and should not be used in newly-written code.

The signal should not be used in newly written code

Parameters

actor

the ClutterActor that received the signal

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 0.8


The “scroll-event” signal

gboolean
user_function (ClutterActor *actor,
               ClutterEvent *event,
               gpointer      user_data)

The ::scroll-event signal is emitted each time the mouse is scrolled on actor

Parameters

actor

the actor which received the event

 

event

a ClutterScrollEvent.

[type ClutterScrollEvent]

user_data

user data set when the signal handler was connected.

 

Returns

TRUE if the event has been handled by the actor, or FALSE to continue the emission.

Flags: Run Last

Since: 0.6


The “show” signal

void
user_function (ClutterActor *actor,
               gpointer      user_data)

The ::show signal is emitted when an actor is visible and rendered on the stage.

Parameters

actor

the object which received the signal

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First

Since: 0.2


The “touch-event” signal

gboolean
user_function (ClutterActor *actor,
               ClutterEvent *event,
               gpointer      user_data)

The ::touch-event signal is emitted each time a touch begin/end/update/cancel event.

Parameters

actor

a ClutterActor

 

event

a ClutterEvent

 

user_data

user data set when the signal handler was connected.

 

Returns

CLUTTER_EVENT_STOP if the event has been handled by the actor, or CLUTTER_EVENT_PROPAGATE to continue the emission.

Flags: Run Last

Since: 1.12


The “transition-stopped” signal

void
user_function (ClutterActor *actor,
               gchar        *name,
               gboolean      is_finished,
               gpointer      user_data)

The ::transition-stopped signal is emitted once a transition is stopped; a transition is stopped once it reached its total duration (including eventual repeats), it has been stopped using clutter_timeline_stop(), or it has been removed from the transitions applied on actor , using clutter_actor_remove_transition().

Parameters

actor

a ClutterActor

 

name

the name of the transition

 

is_finished

whether the transition was finished, or stopped

 

user_data

user data set when the signal handler was connected.

 

Flags: No Hooks

Since: 1.12


The “transitions-completed” signal

void
user_function (ClutterActor *actor,
               gpointer      user_data)

The ::transitions-completed signal is emitted once all transitions involving actor are complete.

Parameters

actor

a ClutterActor

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 1.10


The “unrealize” signal

void
user_function (ClutterActor *actor,
               gpointer      user_data)

The ::unrealize signal is emitted each time an actor is being unrealized.

ClutterActor::unrealize has been deprecated since version 1.16 and should not be used in newly-written code.

The signal should not be used in newly written code

Parameters

actor

the ClutterActor that received the signal

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 0.8