Class (GI Class)

Clutter-18 ▶ Clutter ▶ Actor

The basic element of the scene graph

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.

Each actor can be transformed using methods like Actor.set_scale or Actor.set_rotation_angle. The order in which the transformations are applied is decided by Clutter and it is the following:

  1. translation by the origin of the Actor.allocation property
  2. translation by the actor's Actor.z_position property
  3. translation by the actor's Actor.pivot_point property
  4. scaling by the Actor.scale_x and Actor.scale_y factors
  5. rotation around the Actor.rotation_angle_x
  6. rotation around the Actor.rotation_angle_y
  7. rotation around the Actor.rotation_angle_z
  8. negative translation by the actor's Actor.pivot_point

Each actor has a bounding box, called Actor.allocation which is either set by its parent or explicitly through the Actor.set_position and 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 Actor.get_preferred_width and the Actor.get_preferred_height virtual functions, or it can be explicitly set by using Actor.set_width and Actor.set_height.

An actor’s position can be set explicitly by using Actor.set_x and Actor.set_y; the coordinates are relative to the origin of the actor’s parent.

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. Clutter.Actor 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.

 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, &COGL_COLOR_INIT (0xf5, 0x79, 0x00, 0xff));

 // 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, &COGL_COLOR_INIT (0x00, 0x00, 0xff, 0xff));

 // 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 Clutter.Actor, use the Clutter.Actor::child-added signal; similarly, to track removals of children from a ClutterActor, use the Clutter.Actor::child-removed signal.

There are three ways to paint an actor:

A Clutter.Content is a delegate object that takes over the painting operations of one, or more actors. The Clutter.Content painting will be performed on top of the Clutter.Actor.background_color of the actor, and before calling the actor's own implementation of the Clutter.Actor.paint_node virtual function.

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 Clutter.Actor.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 Clutter.PaintNode 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 Clutter.Actor.allocation.

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, &COGL_COLOR_INIT (255, 255, 255, 255),
                                   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 Clutter.Actor.paint virtual function 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 Clutter.Actor.paint virtual function and it will be removed when the Clutter API changes.

A Clutter.Actor can receive and handle input device events, for instance pointer events and key events, as long as its Clutter.Actor.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 Clutter.Actor::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 [signal@Clutter.Actor::event signal] is emitted, alongside eventual event-specific signals like Clutter.Actor::button-press-event or Clutter.Actor::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 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:

// 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.AnimationMode.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:

clutter_actor_save_easing_state (actor);

// animate the actor's opacity and depth
clutter_actor_set_opacity (actor, 0);
clutter_actor_set_z_position (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_z_position (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:

clutter_actor_save_easing_state (actor);
clutter_actor_set_easing_duration (actor, 1000);
clutter_actor_set_x (actor, 200);
clutter_actor_restore_easing_state (actor);

clutter_actor_save_easing_state (actor);
clutter_actor_set_easing_duration (actor, 500);
clutter_actor_set_x (actor, 100);
clutter_actor_restore_easing_state (actor);

the first call to Clutter.Actor.set_x will begin a transition of the Clutter.Actor.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 Clutter.Actor::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 Clutter.Actor::transitions-completed signal instead.

It is possible to retrieve the Clutter.Transition 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 Clutter.Transition object, and optionally set the initial and final values. The transition will not start unless you add it to the Clutter.Actor.

ClutterTransition *transition;

transition = clutter_property_transition_new_for_actor (actor, "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 Clutter.Actor.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.Object properties, as well as the custom properties defined through the Clutter.Animatable 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 Clutter.Action, Clutter.Constraint, and Clutter.Effect 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:

// this animation will pulse the actor's opacity continuously
ClutterTransition *transition;
ClutterInterval *interval;

transition = clutter_property_transition_new_for_actor (actor, "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);

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

By overriding the Clutter.Actor.get_preferred_width and Clutter.Actor.get_preferred_height virtual functions it is possible to change or provide the preferred size of an actor; similarly, by overriding the Clutter.Actor.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 Clutter.Actor.allocate virtual function.

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

Clutter.Actor allows accessing properties of Clutter.Action, Clutter.Effect, and Clutter.Constraint instances associated to an actor instance for animation purposes, as well as its Clutter.LayoutManager.

In order to access a specific Clutter.Action or a Clutter.Constraint property it is necessary to set the Clutter.ActorMeta.name property on the given action or constraint.

The property can be accessed using the following syntax:

  @<section>.<meta-name>.<property-name>
  • the initial @ is mandatory
  • the section fragment can be one between "actions", "constraints", "content", and "effects"
  • the meta-name fragment is the name of the action, effect, or constraint, as specified by the Clutter.ActorMeta.name property of Clutter.ActorMeta
  • the property-name fragment is the name of the action, effect, or constraint property to be animated.

The example below animates a Clutter.BindConstraint 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.

As the actor has only one Clutter.LayoutManager, the syntax for accessing its properties is simpler:

  `layout`.<property-name>

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 Clutter.BindConstraint.offset property to achieve the effect:

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_for_actor (rect, 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;
}

Type Parameters

Hierarchy (View Summary)

Implements

Index

Constructors

constructor

Properties

$signals flags $gtype

Accessors

accessible_name accessible_role accessibleName accessibleRole actions allocation background_color background_color_set backgroundColor backgroundColorSet child_transform child_transform_set childTransform childTransformSet clip_rect clip_to_allocation clipRect clipToAllocation color_state colorState constraints content content_box content_gravity content_repeat contentBox contentGravity contentRepeat context cursor_type cursorType effect first_child firstChild fixed_position_set fixed_x fixed_y fixedPositionSet fixedX fixedY has_clip has_pointer hasClip hasPointer height last_child lastChild layout_manager layoutManager magnification_filter magnificationFilter mapped margin_bottom margin_left margin_right margin_top marginBottom marginLeft marginRight marginTop min_height min_height_set min_width min_width_set minHeight minHeightSet minification_filter minificationFilter minWidth minWidthSet name natural_height natural_height_set natural_width natural_width_set naturalHeight naturalHeightSet naturalWidth naturalWidthSet offscreen_redirect offscreenRedirect opacity pivot_point pivot_point_z pivotPoint pivotPointZ position reactive realized request_mode requestMode rotation_angle_x rotation_angle_y rotation_angle_z rotationAngleX rotationAngleY rotationAngleZ scale_x scale_y scale_z scaleX scaleY scaleZ show_on_set_parent showOnSetParent size text_direction textDirection transform transform_set transformSet translation_x translation_y translation_z translationX translationY translationZ visible width x x_align x_expand xAlign xExpand y y_align y_expand yAlign yExpand z_position zPosition

Methods

_init add_accessible_state add_action add_action_full add_action_with_name add_child add_constraint add_constraint_with_name add_effect add_effect_with_name add_transition allocate allocate_align_fill allocate_available_size allocate_preferred_size apply_relative_transform_to_point apply_transform_to_point bind_model clear_actions clear_constraints clear_effects connect connect_after contains continue_paint continue_pick create_pango_context create_pango_layout create_texture_paint_node destroy destroy_all_children emit event find_property get_abs_allocation_vertices get_accessible get_accessible_name get_accessible_role get_action get_actions get_actor get_allocation_box get_background_color get_child_at_index get_child_transform get_children get_clip get_clip_to_allocation get_color_state get_constraint get_constraints get_content get_content_box get_content_gravity get_content_repeat get_content_scaling_filters get_context get_cursor_type get_easing_delay get_easing_duration get_easing_mode get_effect get_effects get_first_child get_fixed_position get_fixed_position_set get_height get_initial_state get_last_child get_layout_manager get_margin get_margin_bottom get_margin_left get_margin_right get_margin_top get_n_children get_name get_next_sibling get_offscreen_redirect get_opacity get_opacity_override get_paint_box get_paint_opacity get_paint_visibility get_paint_volume get_pango_context get_parent get_pivot_point get_pivot_point_z get_position get_preferred_height get_preferred_size get_preferred_width get_previous_sibling get_reactive get_request_mode get_resource_scale get_rotation_angle get_scale get_scale_z get_size get_stage get_text_direction get_transform get_transformed_extents get_transformed_paint_volume get_transformed_position get_transformed_size get_transition get_translation get_width get_x get_x_align get_x_expand get_y get_y_align get_y_expand get_z_position grab_key_focus has_actions has_allocation has_constraints has_effects has_key_focus has_mapped_clones has_overlaps hide inhibit_culling insert_child_above insert_child_at_index insert_child_below interpolate_value invalidate_paint_volume invalidate_transform is_in_clone_paint is_mapped is_no_layout is_realized is_rotated is_scaled is_visible map move_by needs_expand paint peek_stage_views pick pick_box queue_redraw queue_redraw_with_clip queue_relayout realize remove_accessible_state remove_action remove_action_by_name remove_all_children remove_all_transitions remove_child remove_clip remove_constraint remove_constraint_by_name remove_effect remove_effect_by_name remove_transition replace_child restore_easing_state save_easing_state set_accessible set_accessible_name set_accessible_role set_allocation set_background_color set_child_above_sibling set_child_at_index set_child_below_sibling set_child_transform set_clip set_clip_to_allocation set_color_state set_content set_content_gravity set_content_repeat set_content_scaling_filters set_cursor_type set_easing_delay set_easing_duration set_easing_mode set_final_state set_fixed_position_set set_height set_layout_manager set_margin set_margin_bottom set_margin_left set_margin_right set_margin_top set_name set_no_layout set_offscreen_redirect set_opacity set_opacity_override set_pivot_point set_pivot_point_z set_position set_reactive set_request_mode set_rotation_angle set_scale set_scale_z set_size set_text_direction set_transform set_translation set_width set_x set_x_align set_x_expand set_y set_y_align set_y_expand set_z_position should_pick show transform_stage_point uninhibit_culling unmap unrealize unset_color_state vfunc_allocate vfunc_apply_transform vfunc_button_press_event vfunc_button_release_event vfunc_calculate_resource_scale vfunc_captured_event vfunc_child_added vfunc_child_removed vfunc_destroy vfunc_enter_event vfunc_event vfunc_find_property vfunc_get_accessible vfunc_get_actor vfunc_get_initial_state vfunc_get_paint_volume vfunc_get_preferred_height vfunc_get_preferred_width vfunc_has_overlaps vfunc_hide vfunc_hide_all vfunc_interpolate_value vfunc_key_focus_in vfunc_key_focus_out vfunc_key_press_event vfunc_key_release_event vfunc_leave_event vfunc_map vfunc_motion_event vfunc_paint vfunc_paint_node vfunc_parent_set vfunc_pick vfunc_queue_relayout vfunc_realize vfunc_resource_scale_changed vfunc_scroll_event vfunc_set_final_state vfunc_show vfunc_touch_event vfunc_unmap vfunc_unrealize get_binding_pool get_layout_manager_type new set_layout_manager_type

Methods - Inherited from GObject

bind_property bind_property_full block_signal_handler disconnect force_floating freeze_notify get_data get_property get_qdata getv is_floating notify notify_by_pspec ref ref_sink run_dispose set set_data set_property steal_data steal_qdata stop_emission_by_name thaw_notify unblock_signal_handler unref vfunc_constructed vfunc_dispatch_properties_changed vfunc_dispose vfunc_finalize vfunc_get_property vfunc_notify vfunc_set_property watch_closure _classInit compat_control find_property install_properties install_property interface_find_property interface_install_property interface_list_properties list_properties newv override_property

Constructors

Properties

$signals: Clutter.Actor.SignalSignatures

Compile-time signal type information.

This instance property is generated only for TypeScript type checking. It is not defined at runtime and should not be accessed in JS code.

flags: number
$gtype: GType<Clutter.Actor<Clutter.LayoutManager, Clutter.Content>>

Accessors

  • get clip_to_allocation(): boolean

    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().

    Returns boolean

    false
  • set clip_to_allocation(val: boolean): void

    Parameters

    • val: boolean

    Returns void

  • get clipToAllocation(): boolean

    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().

    Returns boolean

    false
  • set clipToAllocation(val: boolean): void

    Parameters

    • val: boolean

    Returns void

content

Read-Onlycontent_box

content_gravity

content_repeat

  • get height(): number

    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 Clutter.Actor.height property is animatable.

    Returns number

    0
  • set height(val: number): void

    Parameters

    • val: number

    Returns void

  • get mapped(): boolean

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

    Returns boolean

    false
  • get margin_bottom(): number

    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 Clutter.Actor.margin_bottom property is animatable.

    Returns number

    0
  • set margin_bottom(val: number): void

    Parameters

    • val: number

    Returns void

  • get margin_left(): number

    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 Clutter.Actor.margin_left property is animatable.

    Returns number

    0
  • set margin_left(val: number): void

    Parameters

    • val: number

    Returns void

  • get margin_right(): number

    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 Clutter.Actor.margin_right property is animatable.

    Returns number

    0
  • set margin_right(val: number): void

    Parameters

    • val: number

    Returns void

  • get margin_top(): number

    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 Clutter.Actor.margin_top property is animatable.

    Returns number

    0
  • set margin_top(val: number): void

    Parameters

    • val: number

    Returns void

  • get marginBottom(): number

    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 Clutter.Actor.margin_bottom property is animatable.

    Returns number

    0
  • set marginBottom(val: number): void

    Parameters

    • val: number

    Returns void

  • get marginLeft(): number

    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 Clutter.Actor.margin_left property is animatable.

    Returns number

    0
  • set marginLeft(val: number): void

    Parameters

    • val: number

    Returns void

  • get marginRight(): number

    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 Clutter.Actor.margin_right property is animatable.

    Returns number

    0
  • set marginRight(val: number): void

    Parameters

    • val: number

    Returns void

  • get marginTop(): number

    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 Clutter.Actor.margin_top property is animatable.

    Returns number

    0
  • set marginTop(val: number): void

    Parameters

    • val: number

    Returns void

  • get request_mode(): Clutter.RequestMode

    Request mode for the Clutter.Actor. 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:

      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 Clutter.Actor "child".

    The Clutter.Actor.get_preferred_size function will implement this check for you.

    Returns Clutter.RequestMode

    Clutter.RequestMode.HEIGHT_FOR_WIDTH
  • set request_mode(val: Clutter.RequestMode): void

    Parameters

    Returns void

  • get requestMode(): Clutter.RequestMode

    Request mode for the Clutter.Actor. 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:

      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 Clutter.Actor "child".

    The Clutter.Actor.get_preferred_size function will implement this check for you.

    Returns Clutter.RequestMode

    Clutter.RequestMode.HEIGHT_FOR_WIDTH
  • set requestMode(val: Clutter.RequestMode): void

    Parameters

    Returns void

  • get show_on_set_parent(): boolean

    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.

    Returns boolean

    true
  • set show_on_set_parent(val: boolean): void

    Parameters

    • val: boolean

    Returns void

  • get showOnSetParent(): boolean

    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.

    Returns boolean

    true
  • set showOnSetParent(val: boolean): void

    Parameters

    • val: boolean

    Returns void

text_direction

  • get width(): number

    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 Clutter.Actor.width property is animatable.

    Returns number

    0
  • set width(val: number): void

    Parameters

    • val: number

    Returns void

  • get x(): number

    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 Clutter.Actor.x property is animatable.

    Returns number

    0
  • set x(val: number): void

    Parameters

    • val: number

    Returns void

  • get y(): number

    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 Clutter.Actor.y property is animatable.

    Returns number

    0
  • set y(val: number): void

    Parameters

    • val: number

    Returns void

  • get z_position(): number

    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 Clutter.Actor.z_position does not affect the paint or allocation order.

    The Clutter.Actor.z_position property is animatable.

    Returns number

    0
  • set z_position(val: number): void

    Parameters

    • val: number

    Returns void

  • get zPosition(): number

    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 Clutter.Actor.z_position does not affect the paint or allocation order.

    The Clutter.Actor.z_position property is animatable.

    Returns number

    0
  • set zPosition(val: number): void

    Parameters

    • val: number

    Returns void

Methods

_init

  • This method adds state as one of the accessible states for actor. The list of states of an actor describes the current state of user interface element actor and is provided so that assistive technologies know how to present actor to the user.

    Usually you will have no need to add accessible states for an object, as the accessible object can extract most of the states from the object itself. This method is only required when one cannot extract the information automatically from the object itself (i.e.: a generic container used as a toggle menu item will not automatically include the toggled state).

    Parameters

    Returns void

  • A convenience function for setting the name of a Clutter.Action while adding it to the list of actions applied to self

    This function is the logical equivalent of:

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

    Parameters

    Returns void

  • A convenience function for setting the name of a Clutter.Constraint while adding it to the list of constraints applied to self

    This function is the logical equivalent of:

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

    Parameters

    Returns void

  • A convenience function for setting the name of a Clutter.Effect while adding it to the list of effectss applied to self

    This function is the logical equivalent of:

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

    Parameters

    Returns void

  • Adds a transition to the Clutter.Actor's list of animations.

    The name string is a per-actor unique identifier of the transition: only one Clutter.Transition 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

    Returns void

  • 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 Clutter.ActorBox are not set to 0, the allocation will be offset by their value.

    This function takes into consideration the geometry request specified by the Clutter.Actor.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 Clutter.Actor.x_align and Clutter.Actor.y_align properties, instead, and just call Clutter.Actor.allocate inside their Clutter.Actor.allocate implementation.

    Parameters

    • box: ActorBox

      a Clutter.ActorBox, containing the available width and height

    • x_align: number

      the horizontal alignment, between 0 and 1

    • y_align: number

      the vertical alignment, between 0 and 1

    • x_fill: boolean

      whether the actor should fill horizontally

    • y_fill: boolean

      whether the actor should fill vertically

    Returns void

  • Allocates self taking into account the Clutter.Actor'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:

      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);

    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

    • x: number

      the actor's X coordinate

    • y: number

      the actor's Y coordinate

    • available_width: number

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

    • available_height: number

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

    Returns void

  • Allocates the natural size of self.

    This function is a utility call for Clutter.Actor 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 Clutter.Actor.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 Clutter.ActorClass.allocate virtual function.

    Parameters

    • x: number

      the actor's X coordinate

    • y: number

      the actor's Y coordinate

    Returns void

  • 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

    Returns boolean

    whether descendent is contained within self

  • Run the next stage of the paint sequence. This function should only be called within the implementation of the ‘run’ virtual of a Clutter.Effect. 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

    Returns void

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

    Parameters

    Returns void

  • Creates a new Pango.Layout from the same Pango.Context used by the Clutter.Actor. The Pango.Layout is already configured with the font map, resolution and font options, and the given text.

    If you want to keep around a Pango.Layout created by this function you will have to connect to the Clutter.Backend.SignalSignatures.font_changed | Clutter.Backend::font-changed and Clutter.Backend.SignalSignatures.resolution_changed | Clutter.Backend::resolution-changed signals, and call pango_layout_context_changed() in response to them.

    Parameters

    • text: string | null

      the text to set on the Pango.Layout, or null

    Returns Pango.Layout

    the newly created Pango.Layout. Use g_object_unref() when done

  • 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.

    Returns void

  • 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 Clutter.Actor::destroy signal is emitted on each child of the actor.

    By default, Clutter.Actor will emit the Clutter.Actor::destroy signal when its reference count drops to 0; the default handler of the Clutter.Actor::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.

    Returns void

  • 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

    Returns boolean

    the return value from the signal emission: true if the actor handled the event, or false if the event was not handled

  • Calculates the transformed screen coordinates of the four corners of the actor; the returned vertices relate to the Clutter.ActorBox coordinates as follows:

    • v[0] contains (x1, y1)
    • v[1] contains (x2, y1)
    • v[2] contains (x1, y2)
    • v[3] contains (x2, y2)

    Returns Point3D[]

  • Gets the accessible name for this widget. See clutter_actor_set_accessible_name() for more information.

    Returns string

    a character string representing the accessible name of the widget.

  • 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 translation; 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.

    Returns ActorBox

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

    Returns [number, number, number, number]

get_content

get_content_box

get_content_gravity

get_content_repeat

get_content_scaling_filters

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

    Returns number

    a delay, in milliseconds

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

    Returns number

    the duration of the tweening, in milliseconds

  • This function gets the fixed position of the actor, if set. If there is no fixed position set, this function returns false and doesn't set the x and y coordinates.

    Returns [boolean, number, number]

    true if the fixed position is set, false if it isn't

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

    Returns boolean

    true if the fixed position is set on the actor

  • Retrieves the height of a Clutter.Actor.

    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 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.

    Returns number

    the height of the actor, in pixels

  • Retrieves the current state of property_name and sets value with it

    Parameters

    • property_name: string

      the name of the animatable property to retrieve

    • value: any

      a GObject.Value initialized to the type of the property to retrieve

    Returns void

  • Retrieves the name of self.

    Returns string | null

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

  • 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().

    Returns number

    the opacity of the actor

  • See clutter_actor_set_opacity_override()

    Returns number

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

  • Retrieves the paint volume of the passed Clutter.Actor, 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.

    Returns [boolean, ActorBox]

    true if a 2D paint box could be determined, else false.

  • 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.

    Returns number

    The actor opacity value.

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

    This is by definition the same as clutter_actor_is_mapped.

    Returns boolean

    true if the actor is visible and will be painted.

  • 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.

    Returns [number, number]

  • 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 translation; those transformations do not affect layout, only rendering.

    Parameters

    • for_width: number

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

    Returns [number, number]

  • 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 Clutter.Actor.get_preferred_width and Clutter.Actor.get_preferred_height, and check the actor's preferred geometry management using the Clutter.Actor.request_mode property.

    Returns [number, number, number, number]

  • 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 scaleor translation; those transformations do not affect layout, only rendering.

    Parameters

    • for_height: number

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

    Returns [number, number]

  • Retrieves the resource scale for this actor.

    The resource scale refers to the scale the actor should use for its resources. For example if an actor draws a a picture of size 100 x 100 in the stage coordinate space, it should use a texture of twice the size (i.e. 200 x 200) if the resource scale is 2.

    The resource scale is determined by calculating the highest Clutter.StageView scale the actor will get painted on.

    Note that the scale returned by this function is only guaranteed to be correct when queried during the paint cycle, in all other cases this function will only return a best guess. If your implementation really needs to get a resource scale outside of the paint cycle, make sure to subscribe to the "resource-scale-changed" signal to get notified about the new, correct resource scale before painting.

    Also avoid getting the resource scale for actors that are not attached to a stage. There's no sane way for Clutter to guess which Clutter.StageView the actor is going to be painted on, so you'll probably end up receiving the "resource-scale-changed" signal and having to rebuild your resources.

    The best guess this function may return is usually just the last resource scale the actor got painted with. If this resource scale couldn't be found because the actor was never painted so far or Clutter was unable to determine its position and size, this function will return the resource scale of a parent.

    Returns number

    The resource scale the actor should use for its textures

  • 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.

    Returns [number, number]

get_text_direction

  • Gets the transformed bounding rect of an actor, in pixels relative to the stage. Using this outside of paint() may result in outdated results.

    The result can only be assumed valid inside a paint() method, or an allocate() function of an actor that explicitly gets allocated after self; anywhere else, it may be out-of-date.

    Returns Graphene.Rect

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

    Returns [number, number]

  • 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.

    Returns [number, number]

  • Retrieves the Clutter.Transition of a Clutter.Actor by using the transition name.

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

      clutter_actor_set_easing_duration (actor, 1000);
      clutter_actor_set_rotation_angle (actor, CLUTTER_Y_AXIS, 360.0);

      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 Clutter.Actor::transition-stopped signal, using the transition name as the signal detail.

    Parameters

    • name: string

      the name of the transition

    Returns Clutter.Transition | null

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

  • Retrieves the translation set using clutter_actor_set_translation().

    Returns [number, number, number]

  • Retrieves the width of a Clutter.Actor.

    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 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.

    Returns number

    the width of the actor, in pixels

  • Retrieves the X coordinate of a Clutter.Actor.

    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, this function will return that coordinate.

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

    Returns number

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

  • Retrieves the Y coordinate of a Clutter.Actor.

    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, this function will return that coordinate.

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

    Returns number

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

  • Returns whether the actor has any actions applied.

    Returns boolean

    true if the actor has any actions, false otherwise

  • 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.

    Returns boolean

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

  • Returns whether the actor has any constraints applied.

    Returns boolean

    true if the actor has any constraints, false otherwise

  • Returns whether the actor has any effects applied.

    Returns boolean

    true if the actor has any effects, false otherwise

  • Returns whether a Clutter.Actor or any parent actors have mapped clones that are clone-painting self.

    Returns boolean

    true if the actor has mapped clones, false otherwise

  • 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 Clutter.Actor.has_overlaps. See Clutter.Actor.set_offscreen_redirect for more information.

    Returns boolean

    true if the actor may have overlapping primitives, and false otherwise

  • Increases the culling inhibitor counter. Inhibiting culling forces the actor to be painted even when outside the visible bounds of the stage view.

    This is usually necessary when an actor is being painted on another paint context.

    Pair with clutter_actor_uninhibit_culling() when the actor doesn't need to be painted anymore.

    Returns void

  • 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 Clutter.Actor::child-added signal on self.

    Parameters

    Returns void

  • Asks a Clutter.Animatable implementation to interpolate a a named property between the initial and final values of a Clutter.Interval, using progress as the interpolation value, and store the result inside value.

    This function should be used for every property animation involving Clutter.Animatables.

    Parameters

    • property_name: string

      the name of the property to interpolate

    • interval: Clutter.Interval

      a Clutter.Interval with the animation range

    • progress: number

      the progress to use to interpolate between the initial and final values of the interval

    Returns [boolean, unknown]

    true if the interpolation was successful, and false otherwise

  • Invalidates the cached paint volume of self. This is needed for implementations overriding the Clutter.Actor.get_paint_volume virtual function and has to be called every time the paint volume returned by that function would change.

    Returns void

  • Invalidate the cached transformation matrix of self. This is needed for implementations overriding the apply_transform() vfunc and has to be called if the matrix returned by apply_transform() would change.

    Returns void

  • Checks whether actor is marked as no layout.

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

    Returns boolean

    true if the actor is marked as no layout

  • Checks whether any rotation is applied to the actor.

    Returns boolean

    true if the actor is rotated.

  • Checks whether the actor is scaled in either dimension.

    Returns boolean

    true if the actor is scaled.

  • 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 discouraged: the default implementation of Clutter.Actor.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.

    Returns void

  • 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 additional translation, using clutter_actor_set_translation().

    Parameters

    • dx: number

      Distance to move Actor on X axis.

    • dy: number

      Distance to move Actor on Y axis.

    Returns void

  • 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 call the Clutter.Actor.paint virtual function.

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

    Parameters

    Returns void

  • Retrieves the list of Clutter.StageViews the actor is being painted on.

    If this function is called during the paint cycle, the list is guaranteed to be up-to-date, if called outside the paint cycle, the list will contain the views the actor was painted on last.

    The list returned by this function is not updated when the actors visibility changes: If an actor gets hidden and is not being painted anymore, this function will return the list of views the actor was painted on last.

    If an actor is not attached to a stage (realized), this function will always return an empty list.

    Returns Clutter.StageView[]

    The list of Clutter.StageViews the actor is being painted on. The list and its contents are owned by the Clutter.Actor and the list may not be freed or modified.

  • Logs (does a virtual paint of) a rectangle for picking. Note that box is in the actor's own local coordinates, so is usually {0,0,width,height} to include the whole actor. That is unless the actor has a shaped input region in which case you may wish to log the (multiple) smaller rectangles that make up the input region.

    Parameters

    Returns void

  • 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.

    Returns void

  • 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

    • clip: Mtk.Rectangle | null

      a rectangular clip region, or null

    Returns void

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

    Queueing a new layout automatically queues a redraw as well.

    Returns void

  • 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.

    Returns void

  • Removes the Clutter.Action with the given name from the list of actions applied to self

    Parameters

    • name: string

      the name of the action to remove

    Returns void

  • 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().

    Returns void

  • Removes the Clutter.Constraint with the given name from the list of constraints applied to self

    Parameters

    • name: string

      the name of the constraint to remove

    Returns void

  • Removes the Clutter.Effect with the given name from the list of effects applied to self

    Parameters

    • name: string

      the name of the effect to remove

    Returns void

  • Removes the transition stored inside a Clutter.Actor 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 Clutter.Actor.

    Parameters

    • name: string

      the name of the transition to remove

    Returns void

  • 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.

    Returns void

  • This method allows to set a customly created accessible object to this widget

    NULL is a valid value for accessible. That contemplates the hypothetical case of not needing anymore a custom accessible object for the widget. Next call of Clutter.Actor.get_accessible would create and return a default accessible.

    It assumes that the call to atk_object_initialize that bound the gobject with the custom accessible object was already called, so not a responsibility of this method.

    Parameters

    Returns void

  • This method sets name as the accessible name for self.

    Usually you will have no need to set the accessible name for an object, as usually there is a label for most of the interface elements.

    Parameters

    • name: string | null

      a character string to be set as the accessible name

    Returns void

  • This method sets role as the accessible role for self. This role describes what kind of user interface element self is and is provided so that assistive technologies know how to present self to the user.

    Usually you will have no need to set the accessible role for an object, as this information is extracted from the context of the object (ie: a StButton has by default a push button role). This method is only required when you need to redefine the role currently associated with the widget, for instance if it is being used in an unusual way (ie: a StButton used as a togglebutton), or if a generic object is used directly (ie: a container as a menu item).

    If role is #ATK_ROLE_INVALID, the role will not be changed and the accessible's default role will be used instead.

    Parameters

    Returns void

  • Stores the allocation of self as defined by box.

    This function can only be called from within the implementation of the Clutter.Actor.allocate virtual function.

    The allocation box should have been adjusted to take into account constraints, alignment, and margin properties.

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

    Parameters

    Returns void

  • 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

    Returns void

  • Sets clip area for self. The clip area is always computed from the upper left corner of the actor.

    Parameters

    • xoff: number

      X offset of the clip rectangle

    • yoff: number

      Y offset of the clip rectangle

    • width: number

      Width of the clip rectangle

    • height: number

      Height of the clip rectangle

    Returns void

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

    Parameters

    • clip_set: boolean

      true to apply a clip tracking the allocation

    Returns void

set_content

set_content_gravity

set_content_repeat

set_content_scaling_filters

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

    Parameters

    • msecs: number

      the delay before the start of the tweening, in milliseconds

    Returns void

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

    Parameters

    • msecs: number

      the duration of the easing, or null

    Returns void

  • Sets the current state of property_name to value

    Parameters

    • property_name: string

      the name of the animatable property to set

    • value: any

      the value of the animatable property to set

    Returns void

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

    Parameters

    • is_set: boolean

      whether to use fixed position

    Returns void

  • 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

    • height: number

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

    Returns void

  • Sets the given name to self. The name can be used to identify a Clutter.Actor.

    Parameters

    • name: string | null

      Textual tag to apply to actor

    Returns void

  • 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.

    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.OffscreenRedirect.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

    Returns void

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

    The Clutter.Actor.opacity property is animatable.

    Parameters

    • opacity: number

      New opacity value for the actor.

    Returns void

  • 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 mimic those.

    In almost all cases this should not used by applications.

    Parameters

    • opacity: number

      the override opacity value, or -1 to reset

    Returns void

  • Sets the position of the Clutter.Actor.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

    • pivot_x: number

      the normalized X coordinate of the pivot point

    • pivot_y: number

      the normalized Y coordinate of the pivot point

    Returns void

  • Sets the component on the Z axis of the Clutter.Actor.pivot_point around which the scaling and rotation transformations occur.

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

    Parameters

    • pivot_z: number

      the Z coordinate of the actor's pivot point

    Returns void

  • 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

    • x: number

      New left position of actor in pixels.

    • y: number

      New top position of actor in pixels.

    Returns void

  • Sets actor as reactive. Reactive actors will receive events.

    Parameters

    • reactive: boolean

      whether the actor should be reactive to events

    Returns void

  • 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

    • width: number

      New width of actor in pixels, or -1

    • height: number

      New height of actor in pixels, or -1

    Returns void

set_text_direction

  • Sets an additional translation transformation on a Clutter.Actor, relative to the Clutter.Actor.pivot_point.

    Parameters

    • translate_x: number

      the translation along the X axis

    • translate_y: number

      the translation along the Y axis

    • translate_z: number

      the translation along the Z axis

    Returns void

  • 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

    • width: number

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

    Returns void

  • 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 Clutter.Actor.x property is animatable.

    Parameters

    • x: number

      the actor's position on the X axis

    Returns void

  • Sets whether a Clutter.Actor 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

    • expand: boolean

      whether the actor should expand horizontally

    Returns void

  • 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 Clutter.Actor.y property is animatable.

    Parameters

    • y: number

      the actor's position on the Y axis

    Returns void

  • Sets whether a Clutter.Actor 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

    • expand: boolean

      whether the actor should expand vertically

    Returns void

  • 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 Clutter.Actor.show_on_set_parent will be set to true as a side effect.

    Returns void

  • 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 Clutter.Actor.paint implementation

    Parameters

    • x: number

      x screen coordinate of the point to unproject

    • y: number

      y screen coordinate of the point to unproject

    Returns [boolean, number, number]

    true if conversion was successful.

  • Decreases the culling inhibitor counter. See clutter_actor_inhibit_culling() for when inhibit culling is necessary.

    Calling this function without a matching call to clutter_actor_inhibit_culling() is a programming error.

    Returns void

  • 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 Clutter.Actor implementation of Clutter.Actor.unmap will also unmap any eventual children by default when their parent is unmapped.

    When overriding Clutter.Actor.unmap, it is mandatory to chain up to the parent implementation.

    It is important to note that the implementation of the Clutter.Actor.unmap virtual function may be called after the Clutter.Actor.destroy or the GObject.Object.dispose implementation, but it is guaranteed to be called before the GObject.Object.finalize implementation.

    Returns void

  • 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.

    Returns void

  • virtual function, used when applying the transformations to an actor before painting it or when transforming coordinates or the allocation; if the transformation calculated by this function may have changed, the cached transformation must be invalidated by calling clutter_actor_invalidate_transform(); it must chain up to the parent's implementation

    Parameters

    Returns void

  • 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.

    Returns void

  • Retrieves the current state of property_name and sets value with it

    Parameters

    • property_name: string

      the name of the animatable property to retrieve

    • value: unknown

      a GObject.Value initialized to the type of the property to retrieve

    Returns void

  • 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 translation; those transformations do not affect layout, only rendering.

    Parameters

    • for_width: number

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

    Returns [number, number]

  • 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 scaleor translation; those transformations do not affect layout, only rendering.

    Parameters

    • for_height: number

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

    Returns [number, number]

  • 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 Clutter.Actor.has_overlaps. See Clutter.Actor.set_offscreen_redirect for more information.

    Returns boolean

  • 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 Clutter.Actor.show_on_set_parent property will be set to false as a side-effect.

    Returns void

  • 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.

    Returns void

  • 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 discouraged: the default implementation of Clutter.Actor.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.

    Returns void

  • 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 call the Clutter.Actor.paint virtual function.

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

    Parameters

    Returns void

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

    Queueing a new layout automatically queues a redraw as well.

    Returns void

  • 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.

    Returns void

  • Sets the current state of property_name to value

    Parameters

    • property_name: string

      the name of the animatable property to set

    • value: unknown

      the value of the animatable property to set

    Returns void

  • 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 Clutter.Actor.show_on_set_parent will be set to true as a side effect.

    Returns void

  • 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 Clutter.Actor implementation of Clutter.Actor.unmap will also unmap any eventual children by default when their parent is unmapped.

    When overriding Clutter.Actor.unmap, it is mandatory to chain up to the parent implementation.

    It is important to note that the implementation of the Clutter.Actor.unmap virtual function may be called after the Clutter.Actor.destroy or the GObject.Object.dispose implementation, but it is guaranteed to be called before the GObject.Object.finalize implementation.

    Returns void

  • 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.

    Returns void

Methods - Inherited from GObject

  • Creates a binding between source_property on source and target_property on target.

    Whenever the source_property is changed the target_property is updated using the same value. For instance:

      g_object_bind_property (action, "active", widget, "sensitive", 0);

    Will result in the "sensitive" property of the widget GObject.Object instance to be updated with the same value of the "active" property of the action GObject.Object instance.

    If flags contains GObject.BindingFlags.BIDIRECTIONAL then the binding will be mutual: if target_property on target changes then the source_property on source will be updated as well.

    The binding will automatically be removed when either the source or the target instances are finalized. To remove the binding without affecting the source and the target you can just call g_object_unref() on the returned GObject.Binding instance.

    Removing the binding by calling g_object_unref() on it must only be done if the binding, source and target are only used from a single thread and it is clear that both source and target outlive the binding. Especially it is not safe to rely on this if the binding, source or target can be finalized from different threads. Keep another reference to the binding and use g_binding_unbind() instead to be on the safe side.

    A GObject.Object can have multiple bindings.

    Parameters

    Returns GObject.Binding

    the GObject.Binding instance representing the binding between the two GObject.Object instances. The binding is released whenever the GObject.Binding reference count reaches zero.

  • Increases the freeze count on object. If the freeze count is non-zero, the emission of "notify" signals on object is stopped. The signals are queued until the freeze count is decreased to zero. Duplicate notifications are squashed so that at most one GObject.Object::notify signal is emitted for each property modified while the object is frozen.

    This is necessary for accessors that modify multiple properties to prevent premature notification while the object is still being modified.

    Returns void

  • Gets a property of an object.

    The value can be:

    • an empty GObject.Value initialized by G_VALUE_INIT, which will be automatically initialized with the expected type of the property (since GLib 2.60)
    • a GObject.Value initialized with the expected type of the property
    • a GObject.Value initialized with a type to which the expected type of the property can be transformed

    In general, a copy is made of the property contents and the caller is responsible for freeing the memory by calling GObject.Value.unset.

    Note that GObject.Object.get_property is really intended for language bindings, GObject.Object.get is much more convenient for C programming.

    Parameters

    • property_name: string

      The name of the property to get

    • value: any

      Return location for the property value. Can be an empty GObject.Value initialized by G_VALUE_INIT (auto-initialized with expected type since GLib 2.60), a GObject.Value initialized with the expected property type, or a GObject.Value initialized with a transformable type

    Returns any

  • Gets n_properties properties for an object. Obtained properties will be set to values. All properties must be valid. Warnings will be emitted and undefined behaviour may result if invalid properties are passed in.

    Parameters

    • names: string[]

      the names of each property to get

    • values: any[]

      the values of each property to get

    Returns void

  • Emits a "notify" signal for the property property_name on object.

    When possible, eg. when signaling a property change from within the class that registered the property, you should use g_object_notify_by_pspec() instead.

    Note that emission of the notify signal may be blocked with g_object_freeze_notify(). In this case, the signal emissions are queued and will be emitted (in reverse order) when g_object_thaw_notify() is called.

    Parameters

    • property_name: string

      the name of a property installed on the class of object.

    Returns void

  • Emits a "notify" signal for the property specified by pspec on object.

    This function omits the property name lookup, hence it is faster than g_object_notify().

    One way to avoid using g_object_notify() from within the class that registered the properties, and using g_object_notify_by_pspec() instead, is to store the GParamSpec used with g_object_class_install_property() inside a static array, e.g.:

      typedef enum
      {
        PROP_FOO = 1,
        PROP_LAST
      } MyObjectProperty;

      static GParamSpec *properties[PROP_LAST];

      static void
      my_object_class_init (MyObjectClass *klass)
      {
        properties[PROP_FOO] = g_param_spec_int ("foo", NULL, NULL,
                                                 0, 100,
                                                 50,
                                                 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
        g_object_class_install_property (gobject_class,
                                         PROP_FOO,
                                         properties[PROP_FOO]);
      }

    and then notify a change on the "foo" property with:

      g_object_notify_by_pspec (self, properties[PROP_FOO]);

    Parameters

    Returns void

  • Increase the reference count of object, and possibly remove the [floating][floating-ref] reference, if object has a floating reference.

    In other words, if the object is floating, then this call "assumes ownership" of the floating reference, converting it to a normal reference by clearing the floating flag while leaving the reference count unchanged. If the object is not floating, then this call adds a new normal reference increasing the reference count by one.

    Since GLib 2.56, the type of object will be propagated to the return type under the same conditions as for g_object_ref().

    Returns GObject.Object

    object

  • Sets multiple properties of an object at once. The properties argument should be a dictionary mapping property names to values.

    Parameters

    • properties: { [key: string]: any }

      Object containing the properties to set

    Returns void

  • Each object carries around a table of associations from strings to pointers. This function lets you set an association.

    If the object already had an association with that name, the old association will be destroyed.

    Internally, the key is converted to a GLib.Quark using g_quark_from_string(). This means a copy of key is kept permanently (even after object has been finalized) — so it is recommended to only use a small, bounded set of values for key in your program, to avoid the GLib.Quark storage growing unbounded.

    Parameters

    • key: string

      name of the key

    • data: any

      data to associate with that key

    Returns void

  • This function gets back user data pointers stored via g_object_set_qdata() and removes the data from object without invoking its destroy() function (if any was set). Usually, calling this function is only required to update user data pointers with a destroy notifier, for example:

    void
    object_add_to_user_list (GObject     *object,
                             const gchar *new_string)
    {
      // the quark, naming the object data
      GQuark quark_string_list = g_quark_from_static_string ("my-string-list");
      // retrieve the old string list
      GList *list = g_object_steal_qdata (object, quark_string_list);

      // prepend new string
      list = g_list_prepend (list, g_strdup (new_string));
      // this changed 'list', so we need to set it again
      g_object_set_qdata_full (object, quark_string_list, list, free_string_list);
    }
    static void
    free_string_list (gpointer data)
    {
      GList *node, *list = data;

      for (node = list; node; node = node->next)
        g_free (node->data);
      g_list_free (list);
    }

    Using g_object_get_qdata() in the above example, instead of g_object_steal_qdata() would have left the destroy function set, and thus the partial string list would have been freed upon g_object_set_qdata_full().

    Parameters

    • quark: number

      A GLib.Quark, naming the user data pointer

    Returns any

    The user data pointer set, or null

  • Reverts the effect of a previous call to g_object_freeze_notify(). The freeze count is decreased on object and when it reaches zero, queued "notify" signals are emitted.

    Duplicate notifications for each property are squashed so that at most one GObject.Object::notify signal is emitted for each property, in the reverse order in which they have been queued.

    It is an error to call this function when the freeze count is zero.

    Returns void

  • Decreases the reference count of object. When its reference count drops to 0, the object is finalized (i.e. its memory is freed).

    If the pointer to the GObject.Object may be reused in future (for example, if it is an instance variable of another object), it is recommended to clear the pointer to null rather than retain a dangling pointer to a potentially invalid GObject.Object instance. Use g_clear_object() for this.

    Returns void

  • the constructed function is called by g_object_new() as the final step of the object creation process. At the point of the call, all construction properties have been set on the object. The purpose of this call is to allow for object initialisation steps that can only be performed after construction properties have been set. constructed implementors should chain up to the constructed call of their parent class to allow it to complete its initialisation.

    Returns void

  • the dispose function is supposed to drop all references to other objects, but keep the instance otherwise intact, so that client method invocations still work. It may be run multiple times (due to reference loops). Before returning, dispose should chain up to the dispose method of the parent class.

    Returns void

  • Emits a "notify" signal for the property property_name on object.

    When possible, eg. when signaling a property change from within the class that registered the property, you should use g_object_notify_by_pspec() instead.

    Note that emission of the notify signal may be blocked with g_object_freeze_notify(). In this case, the signal emissions are queued and will be emitted (in reverse order) when g_object_thaw_notify() is called.

    Parameters

    Returns void

  • the generic setter for all properties of this type. Should be overridden for every type with properties. If implementations of set_property don't emit property change notification explicitly, this will be done implicitly by the type system. However, if the notify signal is emitted explicitly, the type system will not emit it a second time.

    Parameters

    Returns void

  • This function essentially limits the life time of the closure to the life time of the object. That is, when the object is finalized, the closure is invalidated by calling g_closure_invalidate() on it, in order to prevent invocations of the closure with a finalized (nonexisting) object. Also, g_object_ref() and g_object_unref() are added as marshal guards to the closure, to ensure that an extra reference count is held on object during invocation of the closure. Usually, this function will be called on closures that use this object as closure data.

    Parameters

    Returns void

Static_classInit

  • Add a property to an interface; this is only useful for interfaces that are added to GObject-derived types. Adding a property to an interface forces all objects classes with that interface to have a compatible property. The compatible property could be a newly created GObject.ParamSpec, but normally g_object_class_override_property() will be used so that the object class only needs to provide an implementation and inherits the property description, default value, bounds, and so forth from the interface property.

    This function is meant to be called from the interface's default vtable initialization function (the class_init member of GObject.TypeInfo.) It must not be called after after class_init has been called for any object types implementing this interface.

    If pspec is a floating reference, it will be consumed.

    Parameters

    Returns void

Interfaces

ConstructorProps
SignalSignatures