MxActorManager

MxActorManager — An object that manages ClutterActor lifecycle

Synopsis

ClutterActor *      (*MxActorManagerCreateFunc)         (MxActorManager *manager,
                                                         gpointer userdata);
enum                MxActorManagerError;
struct              MxActorManager;
struct              MxActorManagerClass;
MxActorManager *    mx_actor_manager_new                (ClutterStage *stage);
MxActorManager *    mx_actor_manager_get_for_stage      (ClutterStage *stage);
ClutterStage *      mx_actor_manager_get_stage          (MxActorManager *manager);
gulong              mx_actor_manager_create_actor       (MxActorManager *manager,
                                                         MxActorManagerCreateFunc create_func,
                                                         gpointer userdata,
                                                         GDestroyNotify destroy_func);
gulong              mx_actor_manager_add_actor          (MxActorManager *manager,
                                                         ClutterContainer *container,
                                                         ClutterActor *actor);
gulong              mx_actor_manager_remove_actor       (MxActorManager *manager,
                                                         ClutterContainer *container,
                                                         ClutterActor *actor);
void                mx_actor_manager_remove_container   (MxActorManager *manager,
                                                         ClutterContainer *container);
void                mx_actor_manager_cancel_operation   (MxActorManager *manager,
                                                         gulong id);
void                mx_actor_manager_cancel_operations  (MxActorManager *manager,
                                                         ClutterActor *actor);
void                mx_actor_manager_set_time_slice     (MxActorManager *manager,
                                                         guint msecs);
guint               mx_actor_manager_get_time_slice     (MxActorManager *manager);
guint               mx_actor_manager_get_n_operations   (MxActorManager *manager);

Object Hierarchy

  GObject
   +----MxActorManager

Properties

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

Signals

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

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.

Details

MxActorManagerCreateFunc ()

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

enum MxActorManagerError

typedef enum {
  MX_ACTOR_MANAGER_CONTAINER_DESTROYED,
  MX_ACTOR_MANAGER_ACTOR_DESTROYED,
  MX_ACTOR_MANAGER_CREATION_FAILED,
  MX_ACTOR_MANAGER_UNKNOWN_OPERATION
} MxActorManagerError;

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

mx_actor_manager_new ()

MxActorManager *    mx_actor_manager_new                (ClutterStage *stage);

Creates a new MxActorManager, associated with the given stage.

Note

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.

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.

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.

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.

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.

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.

Note

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

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.

Note

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

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.

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.

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.

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.

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.

manager :

A MxActorManager

Returns :

Number of operations left to perform

Since 1.2

Property Details

The "n-operations" property

  "n-operations"             guint                 : Read

The amount of operations in the queue.

Default value: 0


The "stage" property

  "stage"                    ClutterStage*         : Read / Write / Construct Only

The stage that contains the managed actors.


The "time-slice" property

  "time-slice"               guint                 : Read / Write

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

Default value: 5

Signal Details

The "actor-added" signal

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

Emitted when an actor add operation has completed.

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.

Since 1.2


The "actor-created" signal

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

Emitted when an actor creation operation has completed.

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.

Since 1.2


The "actor-finished" signal

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

Emitted when all queued operations involving actor have completed.

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.

Since 1.2


The "actor-removed" signal

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

Emitted when an actor remove operation has completed.

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.

Since 1.2


The "operation-cancelled" signal

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

Emitted when an operation has been cancelled.

manager :

the object that received the signal

id :

The operation id

user_data :

user data set when the signal handler was connected.

Since 1.2


The "operation-completed" signal

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

Emitted when an operation has completed successfully.

manager :

the object that received the signal

id :

The operation id

user_data :

user data set when the signal handler was connected.

Since 1.2


The "operation-failed" signal

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

Emitted when an operation has failed.

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.

Since 1.2