clutter.Actor — clutter.Actor — Base abstract class for all visual stage actors.
gobject.GObject +--gobject.GInitiallyUnowned +-- clutter.Actor
|
def callback( | |
def callback( | |
def callback( | |
"destroy" | def callback( |
def callback( | |
"event" | def callback( |
"focus-in" | def callback( |
def callback( | |
def callback( | |
def callback( | |
def callback( | |
def callback( | |
def callback( | |
def callback( | |
"show" | def callback( |
"hide" | def callback( |
"paint" | def callback( |
"realize" | def callback( |
def callback( |
clutter.Actor is a base abstract class for all visual elements on the stage. Every object that must appear on the main clutter.Stage must also be a clutter.Actor, either by using one of the classes provided by Clutter, or by implementing a new clutter.Actor subclass.
def show()
Flags an actor to be displayed. An actor that isn't shown will not be rendered on the stage.
Actors are visible by default.
Calls show() on all children of an actor (if any).
def hide()Flags an actor to be hidden. A hidden actor will not be rendered on the stage.
Actors are visible by default
def realize()Creates any underlying graphics resources needed by the actor to be displayed.
def unrealize()Frees up any underlying graphics resources needed by the actor to be displayed.
def paint()Renders the actor to display.
This function should not be called directly by applications. Call
queue_redraw()
to queue paints, instead.
def queue_redraw()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.
def queue_relayout()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.
def destroy()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.
def event(event, capture)
| a clutter.Event |
| True if event in in capture phase, False otherwise. |
Returns : | the return value from the signal emission: True if the actor handled the event, or False if the event was not handled |
This function is used to emit an event on the main stage. You should rarely need to use this function, except for synthetising events.
def pick(color)
| a clutter.Color |
Renders a silhouette of the actor using the supplied color. Used internally for mapping pointer events to actors.
This function should never be called directly by applications. Use paint() instead.
Subclasses overiding the pick() method should call should_pick_paint() to decide whether to render their silhouette.
Containers should always recursively call paint for each child.
def set_geometry(geometry)
| a clutter.Geometry or a 4-tuple of integers |
Sets the actor's fixed position and forces its minimum and natural size,
in pixels. This means the untransformed actor will have the given geometry.
This is the same as calling
set_position() and
set_size().
def get_geometry(geometry)Returns : | a 4-tuple containing the actor's geometry |
Gets the size and position of an actor relative to its parent actor.
This is the same as calling
get_position() and
get_size().
It tries to "do what you mean" and get the requested size and position if the
actor's allocation is invalid
def set_size(width, height)
| the width in pixels |
| the height in pixels |
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
def get_size()Returns : | a 2-tuple containing the actor's width and height |
This function tries to "do what you mean" and return the size an actor will have. If the actor has a valid allocation, the allocation will be returned; otherwise, the actors natural size request will be returned.
If you care whether you get the request vs. the allocation, you should
probably call a different function like
get_allocation_coords() or
get_preferred_width()
def set_position(x, y)
| the X coordinate |
| the Y coordinate |
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.
def get_position()Returns : | a 2-tuple containing the actor's X and Y position |
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.
def set_x(x)
| the X coordinate |
Sets the actor's X coordinate, relative to its parent, in pixels.
Overrides any layout manager and forces a fixed position for the actor.
def get_x()Returns : | the X coordinate |
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
set_x(),
set_position()or
set_geometry(),
this function will return that coordinate.
If both the allocation and a fixed position are missing, this function will return 0.
def set_y(y)
| the Y coordinate |
Sets the actor's Y coordinate, relative to its parent, in pixels.
Overrides any layout manager and forces a fixed position for the actor.
def get_y()Returns : | the Y coordinate |
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
set_y(),
set_position()or
set_geometry(),
this function will return that coordinate.
If both the allocation and a fixed position are missing, this function will return 0.
def set_width(width)
| the width of the actor, in pixels |
Forces a width on an actor, causing the actor's preferred width and height (if any) to be ignored.
This function sets both the minimum and natural size of the actor.
def get_width()Returns : | the width of the actor, in pixels |
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
get_allocation_coords()
to retrieve the allocated size or
get_preferred_width()
to retrieve the preferred width.
If an actor has a fixed width, for instance a width that has been
assigned using
set_width(),
the width returned will be the same value.
def set_height(height)
| the height of the actor, in pixels |
Forces a height on an actor, causing the actor's preferred width and height (if any) to be ignored.
This function sets both the minimum and natural size of the actor.
def get_height()Returns : | the height of the actor, in pixels |
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
get_allocation_coords()
to retrieve the allocated size or
get_preferred_height()
to retrieve the preferred height.
If an actor has a fixed height, for instance a height that has been
assigned using
set_height(),
the height returned will be the same value.
def set_rotation(axis, angle, x, y, z)
| a clutter.RotateAxis |
| the rotation angle |
| X coordinate of the center of rotation, relative to the anchor point |
| Y coordinate of the center of rotation, relative to the anchor point |
| Z coordinate of the center of rotation, relative to the anchor point |
Sets the rotation angle of self around the given axis.
The rotation center coordinates used depend on the value of axis:
The rotation coordinates are relative to the anchor point of the actor,
set using
set_anchor_point().
If no anchor point is set, the upper left corner is assumed as the origin.
def get_rotation(axis)
| a clutter.RotateAxis |
Returns : | a 4-tuple containing the angle and the coordinates of the center of rotation on all three axes |
Retrieves the angle and center of rotation on the given axis.
The coordinates of the center returned by this function depend on the axis passed.
def set_opacity(opacity)
| the new opacity |
Sets the actor's opacity, with zero being completely transparent and 255 (0xff) being fully opaque.
def get_opacity()Returns : | the opacity of the actor |
Retrieves the opacity value of an actor, as set by set_opacity().
For retrieving the absolute opacity of the actor inside a paint virtual function, see get_paint_opacity().
def set_name(name)
| a string |
Sets the given name to self. The name can be used to identify a
clutter.Actor.
def set_clip(x_offset, y_offset, width, height)
| the X offset of the clip |
| the Y offset of the clip |
| the width of the clip |
| the height of the clip |
Sets clip area in pixels for self. The clip area is always computed from the upper left corner of the actor, even if the anchor point is set otherwise.
def has_clip()Returns : | a boolean value |
Determines whether the actor has a clip area set or not.
def get_clip()Returns : | a 4-tuple containing the X and Y offsets, and the width and height of the clip |
Gets the clip area for the actor, in pixels.
def set_parent(parent)
| a clutter.Actor |
Sets the parent of self to parent. The opposite function is
unparent().
This function should not be used by applications, but by custom container actor subclasses.
def reparent(new_parent)
| a clutter.Actor |
This function resets the parent actor of the actor. It is logically equivalent to
calling
unparent() and
set_parent().
def unparent()This function should not be used in applications. It should be called by implementations of container actors, to dissociate a child from the container.
def raise_actor(above=None)
| a clutter.Actor, or None |
Raises the actor above a sibling.
Both actors must have the same parent.
This function is the equivalent of
clutter.Container.raise_child().
def lower_actor(below=None)
| a clutter.Actor, or None |
Lowers the actor below a sibling
Both actors must have the same parent.
This function is the equivalent of
clutter.Container.lower_child().
def raise_top()Raises an actor to the top.
This function calls
raise()
def lower_bottom()Lowers an actor to the bottom.
This function calls
lower_actor()
def set_depth(depth)
| the Z coordinate of the actor |
Sets the Z co-ordinate of self to depth. The Units of which are dependant on the perspective setup.
def get_depth()Returns : | the Z coordinate of the actor, in pixels |
Retrieves the depth of self.
def set_scale(scale_x, scale_y)
| the scaling factor on the X axis |
| the scaling factor on the Y axis |
Scales an actor with the given factors. The scaling is always relative to the anchor point.
def get_scale()Returns : | a 2-tuple containing the scaling factors on the X and Y axes |
Retrieves an actors scale factors.
def move_by(dx, dy)
| a gint |
| a gint |
Moves an actor by the specified distance relative to its current position in
pixels. This function modifies the fixed position of an actor and thus removes
it from any layout management. Another way to move an actor is with an anchor
point, see
set_anchor_point()
def apply_transform_to_point(point, vertex)
| a clutter.Vertex |
| a clutter.Vertex |
Transforms point in coordinates relative to the actor into screen-relative coordinates with the current actor transformation (i.e. scale, rotation, etc)
def is_scaled()Returns : | a gboolean |
Checks whether the actor is scaled in either dimension.
def is_rotated()Returns : | a gboolean |
Checks whether any rotation is applied to the actor.
def apply_relative_transform_to_point(ancestor, point, vertex)
| a clutter.Actor |
| a clutter.Vertex |
| a clutter.Vertex |
Transforms point in coordinates relative to the actor into ancestor-relative coordinates using the relevant transform stack (i.e. scale, rotation, etc).
If ancestor is None the ancestor will be the
clutter.Stage.
In this case, the coordinates returned will be the coordinates on the stage
before the projection is applied. This is different from the behaviour of
apply_transform_to_point().
def set_reactive(reactive)
| a gboolean |
Sets the actor to be reactive. Reactive actors will receive events.
def get_reactive()Returns : | a gboolean |
Checks whether actor is marked as reactive.
def should_pick_paint()Returns : | a gboolean |
Utility call for subclasses overiding the pick method.
This function should never be called directly by applications.
def set_shader(shader)
| a clutter.Shader |
Returns : | a gboolean |
Sets the
clutter.Shader
to be used when rendering self. If shader is None it will unset any currently
set shader for the actor.
def get_shader()Returns : | a clutter.Shader |
Queries the currently set
clutter.Shader
on the actor.
def set_shader_param(param, value)
| a string |
| a float |
Sets the value for a named parameter of the shader applied to actor.
def set_anchor_point(anchor_x, anchor_y)
| a gint |
| a gint |
Sets an anchor point for the actor. The anchor point is a point in the coordinate space of an actor to which the actor position within its parent is relative; the default is (0, 0), i.e. the top-left corner of the actor.
def move_anchor_point(anchor_x, anchor_y)
| a gint |
| a gint |
Sets an anchor point for the actor, and adjusts the actor postion so that the relative position of the actor toward its parent remains the same.
def get_anchor_point()Returns the current anchor point of the actor in pixels.
def set_anchor_point_from_gravity(gravity)
| a ClutterGravity |
Sets an anchor point on the actor, based on the given gravity (this is a
convenience function wrapping
set_anchor_point()
def move_anchor_point_from_gravity(gravity)
| a ClutterGravity |
Sets an anchor point on the actor based on the given gravity, adjusting the actor postion so that its relative position within its parent remains unchanged.
def transform_stage_point(x, y, x_out, y_out)
| a gint32 |
| a gint32 |
| a gint32* |
| a gint32* |
Returns : | a gboolean |
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 is fairly computationally intensive.
This function only works when the allocation is up-to-date, i.e. inside of paint()
def get_preferred_width(for_height, min_width_p, natural_width_p)
| a gint32 |
| a gint32* |
| a gint32* |
Computes the requested minimum and natural widths for an actor, optionally depending on the specified height, or if they are already computed, returns the cached values.
An actor may not get its request - depending on the layout manager that's in effect.
A request should not incorporate the actor's scale or anchor point; those transformations do not affect layout, only rendering.
def get_preferred_height(for_width, min_height_p, natural_height_p)
| a gint32 |
| a gint32* |
| a gint32* |
Computes the requested minimum and natural heights for an actor, or if they are already computed, returns the cached values.
An actor may not get its request - depending on the layout manager that's in effect.
A request should not incorporate the actor's scale or anchor point; those transformations do not affect layout, only rendering.
def get_preferred_size(min_width_p, min_height_p, natural_width_p, natural_height_p)
| a gint32* |
| a gint32* |
| a gint32* |
| a gint32* |
Computes the preferred minimum and natural size of an actor, taking into account the actor's geometry management (either height-for-width or width-for-height).
The width and height used to compute the preferred height and preferred width are the actor's natural ones.
If you need to control the height for the preferred width, or the width for
the preferred height, you should use
get_preferred_width() and
get_preferred_height(),
and check the actor's preferred geometry management using the "request-mode" property.
def allocate(box, absolute_origin_changed)
| a clutter.ActorBox |
| a boolean |
Called by the parent of an actor to assign the actor its size. Should never be called by applications (except when implementing a container or layout manager).
Actors can know from their allocation box whether they have moved with respect to their parent actor. The absolute_origin_changed parameter additionally indicates whether the parent has moved with respect to the stage, for example because a grandparent's origin has moved.
def allocate_preferred_size(absolute_origin_changed)
| a gboolean |
Allocates the natural size of the actor.
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
allocate()
implementation to give each child exactly how much space it requires.
This function is not meant to be used by applications. It is also not meant
to be used outside the implementation of the
allocate()
virtual function.
def get_allocation_coords()
| a gint* |
| a gint* |
| a gint* |
| a gint* |
Gets the layout box an actor has been assigned. The allocation can only be assumed valid inside a paint() method; anywhere else, it may be out-of-date.
An allocation does not incorporate the actor's scale or anchor point; those transformations do not affect layout, only rendering.
The returned coordinates are in pixels.
def get_allocation_box(box)
| a clutter.ActorBox |
Gets the layout box an actor has been assigned. The allocation can only be assumed valid inside a paint() method; anywhere else, it may be out-of-date.
An allocation does not incorporate the actor's scale or anchor point; those transformations do not affect layout, only rendering.
def get_allocation_geometry(geom)
| a clutter.Geometry |
Gets the layout box an actor has been assigned. The allocation can only be assumed valid inside a paint() method; anywhere else, it may be out-of-date.
An allocation does not incorporate the actor's scale or anchor point; those transformations do not affect layout, only rendering.
The returned rectangle is in pixels.
def get_allocation_vertices(ancestor, verts[4])
| a clutter.Actor |
| a clutter.Vertex |
Calculates the transformed coordinates of the four corners of the actor in the
plane of ancestor. The returned vertices relate to the
clutter.ActorBox
coordinates as follows:
If ancestor is NONE the ancestor will be the
ClutterStage.
In this case, the coordinates returned will be the coordinates on the stage
before the projection is applied. This is different from the behaviour of
get_abs_allocation_vertices()
def get_transformed_size()Returns the absolute size of an actor taking into account any scaling factors
def get_transformed_position()Returns the absolute position of an actor, in pixels, relative to the stage.
def get_fixed_position_set()Returns : | a gboolean |
Checks whether an actor has a fixed position set (and will thus be unaffected by any layout manager).
def set_fixed_position_set(is_set)
| a gboolean |
Sets whether an actor has a fixed position set (and will thus be unaffected by any layout manager).
def get_paint_opacity()Returns : | a guint8 |
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.
def get_stage()Returns : | a clutter.Actor |
Retrieves the
ClutterStage
where the actor is contained.
def get_abs_allocation_vertices(verts[4])
| a clutter.Vertex |
Calculates the transformed screen coordinates of the four corners of the actor;
the returned vertices relate to the
clutter.ActorBox
coordinates as follows:
def callback(actor, event, user_param1, ...)
| the object which received the event |
| a clutter.ButtonEvent |
| the first user parameter (if any) specified with the connect() method |
| additional user parameters (if any) |
The "button-press-event" signal is emitted each time a mouse button is pressed on actor.
def callback(actor, event, user_param1, ...)
| the object which received the event |
| a clutter.ButtonEvent |
| the first user parameter (if any) specified with the connect() method |
| additional user parameters (if any) |
The "button-release-event" signal is emitted each time a mouse button is released on actor.
def callback(actor, event, user_param1, ...)
| the object which received the signal |
| a clutter.Event |
| the first user parameter (if any) specified with the connect() method |
| additional user parameters (if any) |
The "captured-event" signal is emitted when an event is captured by Clutter. This signal will be emitted starting from the top-level container (the clutter.Stage) to the actor which received the event going down the hierarchy. This signal can be used to intercept every event before the specialized events (like "button-press-event" or "
def callback(actor, user_param1, ...)
| the object which received the signal |
| the first user parameter (if any) specified with the connect() method |
| additional user parameters (if any) |
The "destroy" signal is emitted when an actor is destroyed, either by direct invocation of clutter.Actor.destroy() or when the clutter.Group that contains the actor is destroyed.
def callback(actor, event, user_param1, ...)
| the object which the pointer has entered |
| a clutter.CrossingEvent |
| the first user parameter (if any) specified with the connect() method |
| additional user parameters (if any) |
| True if the event has been handled by the actor, or False to continue the emission. |
The "event-event" signal is emitted when the pointer enters the actor.
def callback(actor, event, user_param1, ...)
| the object which received the event |
| a clutter.Event |
| the first user parameter (if any) specified with the connect() method |
| additional user parameters (if any) |
| True if the event has been handled by the actor, or False to continue the emission. |
The "event" signal is emitted each time an event is received by the actor. This signal will be emitted on every actor, following the hierarchy chain, until it reaches the top-level container (the clutter.Stage).
def callback(actor, user_param1, ...)
| the actor which now now has key focus |
| the first user parameter (if any) specified with the connect() method |
| additional user parameters (if any) |
The "focus-in" signal is emitted when actor recieves key focus.
def callback(actor, user_param1, ...)
| the actor which now now has key focus |
| the first user parameter (if any) specified with the connect() method |
| additional user parameters (if any) |
The "focus-out" signal is emitted when actor loses key focus.
def callback(actor, user_param1, ...)
| the object which received the signal |
| the first user parameter (if any) specified with the connect() method |
| additional user parameters (if any) |
The "hide" signal is emitted when an actor is no longer visible.
def callback(actor, event, user_param1, ...)
| the actor which received the event |
| a clutter.KeyEvent |
| the first user parameter (if any) specified with the connect() method |
| additional user parameters (if any) |
| True if the event has been handled by the actor, or False to continue the emission. |
The "key-press-event" signal is emitted each time a keyboard button is pressed on actor.
def callback(actor, event, user_param1, ...)
| the actor which received the event |
| a clutter.KeyEvent |
| the first user parameter (if any) specified with the connect() method |
| additional user parameters (if any) |
| True if the event has been handled by the actor, or False to continue the emission. |
The "key-press-event" signal is emitted each time a keyboard button is released on actor.
def callback(actor, event, user_param1, ...)
| the actor which the pointer has left |
| a clutter.CrossingEvent |
| the first user parameter (if any) specified with the connect() method |
| additional user parameters (if any) |
| True if the event has been handled by the actor, or False to continue the emission. |
The "leave-event" signal is emitted when the pointer leaves the actor.
def callback(actor, event, user_param1, ...)
| the actor which the pointer has moved on |
| a clutter.MotionEvent |
| the first user parameter (if any) specified with the connect() method |
| additional user parameters (if any) |
| True if the event has been handled by the actor, or False to continue the emission. |
The "motion-event" signal is emitted each time the mouse pointer is moved on actor.
def callback(actor, old_parent, user_param1, ...)
| the actor which received the signal |
| the previous parent of the actor, or None |
| the first user parameter (if any) specified with the connect() method |
| additional user parameters (if any) |
The "parent-set" signal is emitted when the parent of the actor changes.
def callback(actor, event, user_param1, ...)
| the actor which received the event |
| a clutter.ScrollEvent |
| the first user parameter (if any) specified with the connect() method |
| additional user parameters (if any) |
| True if the event has been handled by the actor, or False to continue the emission. |
The "scroll-event" signal is emitted each time the mouse is scrolled on actor.
def callback(actor, user_param1, ...)
| the actor which received the event |
| the first user parameter (if any) specified with the connect() method |
| additional user parameters (if any) |
The "show" signal is emitted when an actor becomes visible.
def callback(actor, user_param1, ...)
| the actor which received the event |
| the first user parameter (if any) specified with the connect() method |
| additional user parameters (if any) |
The "paint" signal is emitted when an actor is being painted.
def callback(actor, user_param1, ...)
| the actor which received the event |
| the first user parameter (if any) specified with the connect() method |
| additional user parameters (if any) |
The "realize" signal is emitted when an actor is being realized.
def callback(actor, user_param1, ...)
| the actor which received the event |
| the first user parameter (if any) specified with the connect() method |
| additional user parameters (if any) |
The "unrealize" signal is emitted when an actor is being unrealized.