MxActorManager

MxActorManager — An object that manages ClutterActor lifecycle

Functions

Properties

guint n-operations Read
ClutterStage * stage Read / Write / Construct Only
guint time-slice Read / Write

Signals

void actor-added Run Last
void actor-created Run Last
void actor-finished Run Last
void actor-removed Run Last
void operation-cancelled Run Last
void operation-completed Run Last
void operation-failed Run Last

Types and Values

Object Hierarchy

    GObject
    ╰── MxActorManager

Description

MxActorManager is an object that helps manage the creation, addition and removal of actors. It is bound to a particular stage, and spreads operations over time so as not to interrupt animations or interactivity.

Operations added to the MxActorManager will strictly be performed in the order in which they were added.

Functions

MxActorManagerCreateFunc ()

ClutterActor *
(*MxActorManagerCreateFunc) (MxActorManager *manager,
                             gpointer userdata);

mx_actor_manager_new ()

MxActorManager *
mx_actor_manager_new (ClutterStage *stage);

Creates a new MxActorManager, associated with the given stage.

A reference will not be taken on the stage, and when the stage is destroyed, the actor manager will lose a reference. The actor manager can be kept alive by taking a reference, but will no longer divide up events.

Parameters

stage

A ClutterStage

 

Returns

An MxActorManager, tied to the given ClutterStage.

[transfer none]

Since: 1.2


mx_actor_manager_get_for_stage ()

MxActorManager *
mx_actor_manager_get_for_stage (ClutterStage *stage);

Get the MxActorManager associated with a stage, or creates one if this is the first call to the function with the given ClutterStage.

This is a convenience function that allows for easy association of one MxActorManager to a ClutterStage.

Parameters

stage

A ClutterStage

 

Returns

An MxActorManager.

[transfer none]

Since: 1.2


mx_actor_manager_get_stage ()

ClutterStage *
mx_actor_manager_get_stage (MxActorManager *manager);

Gets the ClutterStage the actor manager is associated with.

Parameters

manager

A MxActorManager

 

Returns

The ClutterStage the actor is associated with.

[transfer none]

Since: 1.2


mx_actor_manager_create_actor ()

gulong
mx_actor_manager_create_actor (MxActorManager *manager,
                               MxActorManagerCreateFunc create_func,
                               gpointer userdata,
                               GDestroyNotify destroy_func);

Creates a ClutterActor. The actor may not be created immediately, or at all, if the operation is cancelled.

On successful completion, the “actor_created” signal will be fired.

Parameters

manager

A MxActorManager

 

create_func

A ClutterActor creation function

 

userdata

data to be passed to the function, or NULL

 

destroy_func

callback to invoke before the operation is removed

 

Returns

The ID for this operation.

Since: 1.2


mx_actor_manager_add_actor ()

gulong
mx_actor_manager_add_actor (MxActorManager *manager,
                            ClutterContainer *container,
                            ClutterActor *actor);

Adds actor to container . The actor may not be parented immediately, or at all, if the operation is cancelled.

On successful completion, the “actor_added” signal will be fired.

Parameters

manager

A MxActorManager

 

container

A ClutterContainer

 

actor

A ClutterActor

 

Returns

The ID for this operation.

Since: 1.2


mx_actor_manager_remove_actor ()

gulong
mx_actor_manager_remove_actor (MxActorManager *manager,
                               ClutterContainer *container,
                               ClutterActor *actor);

Removes actor from container .

On successful completion, the “actor_removed” signal will be fired.

The actor may not be removed immediately, and thus you may want to set the actor's opacity to 0 before calling this function.

Parameters

manager

A MxActorManager

 

container

A ClutterContainer

 

actor

A ClutterActor

 

Returns

The ID for this operation.

Since: 1.2


mx_actor_manager_remove_container ()

void
mx_actor_manager_remove_container (MxActorManager *manager,
                                   ClutterContainer *container);

Removes the container. This is a utility function that works by first removing all the children of the container, then the children itself. This effectively spreads the load of removing a large container. All prior operations associated with this container will be cancelled.

The container may not be removed immediately, and thus you may want to set the container's opacity to 0 before calling this function.

Parameters

manager

A MxActorManager

 

container

A ClutterContainer

 

Since: 1.2


mx_actor_manager_cancel_operation ()

void
mx_actor_manager_cancel_operation (MxActorManager *manager,
                                   gulong id);

Cancels the given operation, if it exists. The “operation_cancelled” signal is fired whenever an operation is cancelled.

Parameters

manager

A MxActorManager

 

id

An operation ID

 

Since: 1.2


mx_actor_manager_cancel_operations ()

void
mx_actor_manager_cancel_operations (MxActorManager *manager,
                                    ClutterActor *actor);

Cancels all operations associated with the given actor.

Parameters

manager

A MxActorManager

 

actor

A ClutterActor

 

Since: 1.2


mx_actor_manager_set_time_slice ()

void
mx_actor_manager_set_time_slice (MxActorManager *manager,
                                 guint msecs);

Sets the amount of time the actor manager will spend performing operations, before yielding to allow any necessary redrawing to occur.

Lower times will lead to smoother performance, but will increase the amount of time it takes for operations to complete.

Parameters

manager

A MxActorManager

 

msecs

A time, in milliseconds

 

Since: 1.2


mx_actor_manager_get_time_slice ()

guint
mx_actor_manager_get_time_slice (MxActorManager *manager);

Retrieves the current time slice being used for operations.

Parameters

manager

A MxActorManager

 

Returns

The time-slice being used, in milliseconds

Since: 1.2


mx_actor_manager_get_n_operations ()

guint
mx_actor_manager_get_n_operations (MxActorManager *manager);

Retrieves the amount of operations left in the queue.

Parameters

manager

A MxActorManager

 

Returns

Number of operations left to perform

Since: 1.2

Types and Values

enum MxActorManagerError

Members

MX_ACTOR_MANAGER_CONTAINER_DESTROYED

   

MX_ACTOR_MANAGER_ACTOR_DESTROYED

   

MX_ACTOR_MANAGER_CREATION_FAILED

   

MX_ACTOR_MANAGER_UNKNOWN_OPERATION

   

struct MxActorManager

struct MxActorManager;

struct MxActorManagerClass

struct MxActorManagerClass {
  GObjectClass parent_class;

  /* signals */
  void (*actor_created) (MxActorManager *manager,
                         gulong          id,
                         ClutterActor   *actor);
  void (*actor_added) (MxActorManager   *manager,
                       gulong            id,
                       ClutterContainer *container,
                       ClutterActor     *actor);
  void (*actor_removed) (MxActorManager   *manager,
                         gulong            id,
                         ClutterContainer *container,
                         ClutterActor     *actor);

  void (*actor_finished) (MxActorManager *manager,
                          ClutterActor   *actor);

  void (*operation_completed) (MxActorManager *manager,
                               gulong          id);
  void (*operation_cancelled) (MxActorManager *manager,
                               gulong          id);
  void (*operation_failed) (MxActorManager *manager,
                            gulong          id,
                            GError         *error);

  /* padding for future expansion */
  void (*_padding_0) (void);
  void (*_padding_1) (void);
  void (*_padding_2) (void);
  void (*_padding_3) (void);
  void (*_padding_4) (void);
};

Property Details

The “n-operations” property

  “n-operations”             guint

The amount of operations in the queue.

Flags: Read

Default value: 0


The “stage” property

  “stage”                    ClutterStage *

The stage that contains the managed actors.

Flags: Read / Write / Construct Only


The “time-slice” property

  “time-slice”               guint

The amount of time to spend performing operations, per frame, in ms.

Flags: Read / Write

Default value: 5

Signal Details

The “actor-added” signal

void
user_function (MxActorManager *manager,
               gulong          id,
               ClutterActor   *container,
               ClutterActor   *actor,
               gpointer        user_data)

Emitted when an actor add operation has completed.

Parameters

manager

the object that received the signal

 

id

The operation ID

 

container

The ClutterContainer the actor was added to

 

actor

The added ClutterActor

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 1.2


The “actor-created” signal

void
user_function (MxActorManager *manager,
               gulong          id,
               ClutterActor   *actor,
               gpointer        user_data)

Emitted when an actor creation operation has completed.

Parameters

manager

the object that received the signal

 

id

The operation ID

 

actor

The created ClutterActor

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 1.2


The “actor-finished” signal

void
user_function (MxActorManager *manager,
               ClutterActor   *actor,
               gpointer        user_data)

Emitted when all queued operations involving actor have completed.

Parameters

manager

the object that received the signal

 

actor

The ClutterActor to which the signal pertains

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 1.2


The “actor-removed” signal

void
user_function (MxActorManager *manager,
               gulong          id,
               ClutterActor   *container,
               ClutterActor   *actor,
               gpointer        user_data)

Emitted when an actor remove operation has completed.

Parameters

manager

the object that received the signal

 

id

The operation ID

 

container

The ClutterContainer the actor was removed from

 

actor

The removed ClutterActor

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 1.2


The “operation-cancelled” signal

void
user_function (MxActorManager *manager,
               gulong          id,
               gpointer        user_data)

Emitted when an operation has been cancelled.

Parameters

manager

the object that received the signal

 

id

The operation id

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 1.2


The “operation-completed” signal

void
user_function (MxActorManager *manager,
               gulong          id,
               gpointer        user_data)

Emitted when an operation has completed successfully.

Parameters

manager

the object that received the signal

 

id

The operation id

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 1.2


The “operation-failed” signal

void
user_function (MxActorManager *manager,
               gulong          id,
               GError         *error,
               gpointer        user_data)

Emitted when an operation has failed.

Parameters

manager

the object that received the signal

 

id

The operation id

 

error

A GError describing the reason of the failure

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 1.2