MxActorManager

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