## EActivity EActivity — Describe activities in progress |

## Synopsis

    #include <e-util/e-util.h>

    struct              EActivity;
    EActivity *         e_activity_new                      (void);
    void                e_activity_cancel                   (EActivity *activity);
    gchar *             e_activity_describe                 (EActivity *activity);
    EAlertSink *        e_activity_get_alert_sink           (EActivity *activity);
    void                e_activity_set_alert_sink           (EActivity *activity,
                                                             EAlertSink *alert_sink);
    GCancellable *      e_activity_get_cancellable          (EActivity *activity);
    void                e_activity_set_cancellable          (EActivity *activity,
                                                             GCancellable *cancellable);
    const gchar *       e_activity_get_icon_name            (EActivity *activity);
    void                e_activity_set_icon_name            (EActivity *activity,
                                                             const gchar *icon_name);
    gdouble             e_activity_get_percent              (EActivity *activity);
    void                e_activity_set_percent              (EActivity *activity,
                                                             gdouble percent);
    enum                EActivityState;
    EActivityState      e_activity_get_state                (EActivity *activity);
    void                e_activity_set_state                (EActivity *activity,
                                                             EActivityState state);
    const gchar *       e_activity_get_text                 (EActivity *activity);
    void                e_activity_set_text                 (EActivity *activity,
                                                             const gchar *text);
    const gchar *       e_activity_get_last_known_text      (EActivity *activity);
    gboolean            e_activity_handle_cancellation      (EActivity *activity,
                                                             const GError *error);

## Object Hierarchy

      GObject
       +----EActivity

## Properties

      "alert-sink"               EAlertSink*           : Read / Write / Construct
      "cancellable"              GCancellable*         : Read / Write / Construct
      "icon-name"                gchar*                : Read / Write / Construct
      "percent"                  gdouble               : Read / Write / Construct
      "state"                    EActivityState        : Read / Write / Construct
      "text"                     gchar*                : Read / Write / Construct

## Description

EActivity is used to track and describe application activities in progress. An EActivity usually manifests in a user interface as a status bar message (see EActivityProxy) or information bar message (see EActivityBar), with optional progress indication and a cancel button which is linked to a GCancellable.

## Details

### struct EActivity

    struct EActivity;

### e_activity_new ()

    EActivity *         e_activity_new                      (void);

Creates a new EActivity.

Returns : | an EActivity

### e_activity_cancel ()

    void                e_activity_cancel                   (EActivity *activity);

Convenience function cancels `activity`'s "cancellable".

### Note

This function will not set `activity`'s "state" to `E_ACTIVITY_CANCELLED`. It merely requests that the associated operation be cancelled. Only after the operation finishes with a `G_IO_ERROR_CANCELLED` should the `activity`'s "state" be changed (see `e_activity_handle_cancellation()`). During this interim period `e_activity_describe()` will indicate the activity is "cancelling".

`activity` : | an EActivity

### e_activity_describe ()

    gchar *             e_activity_describe                 (EActivity *activity);

Returns a description of the current state of the `activity` based on the "text", "percent" and "state" properties. Suitable for displaying in a status bar or similar widget.

Free the returned string with `g_free()` when finished with it.

`activity` : | an EActivity
Returns : | a description of `activity`

### e_activity_get_alert_sink ()

    EAlertSink *        e_activity_get_alert_sink           (EActivity *activity);

Returns the EAlertSink for `activity`, if one was provided.

The "alert-sink" property is convenient for when the user should be alerted about a failed asynchronous operation. Generally an "alert-sink" is set prior to dispatching the operation, and retrieved by a callback function when the operation completes.

`activity` : | an EActivity
Returns : | an EAlertSink, or `NULL`

### e_activity_set_alert_sink ()

    void                e_activity_set_alert_sink           (EActivity *activity,
                                                             EAlertSink *alert_sink);

Sets (or clears) the EAlertSink for `activity`.

The "alert-sink" property is convenient for when the user should be alerted about a failed asynchronous operation. Generally an "alert-sink" is set prior to dispatching the operation, and retrieved by a callback function when the operation completes.

`activity` : | an EActivity
`alert_sink` : | an EAlertSink, or `NULL`

### e_activity_get_cancellable ()

    GCancellable *      e_activity_get_cancellable          (EActivity *activity);

Returns the GCancellable for `activity`, if one was provided.

Generally the `activity`'s "cancellable" property holds the same GCancellable instance passed to a cancellable function, so widgets like EActivityBar can bind the GCancellable to a cancel button.

`activity` : | an EActivity
Returns : | a GCancellable, or `NULL`

### e_activity_set_cancellable ()

    void                e_activity_set_cancellable          (EActivity *activity,
                                                             GCancellable *cancellable);

Sets (or clears) the GCancellable for `activity`.

Generally the `activity`'s "cancellable" property holds the same GCancellable instance passed to a cancellable function, so widgets like EActivityBar can bind the GCancellable to a cancel button.

`activity` : | an EActivity
`cancellable` : | a GCancellable, or `NULL`

### e_activity_get_icon_name ()

    const gchar *       e_activity_get_icon_name            (EActivity *activity);

Returns the themed icon name for `activity`, if one was provided.

Generally widgets like EActivityBar will honor the "icon-name" property while the `activity`'s "state" is `E_ACTIVITY_RUNNING` or `E_ACTIVITY_WAITING`, but will override the icon for `E_ACTIVITY_CANCELLED` and `E_ACTIVITY_COMPLETED`.

`activity` : | an EActivity
Returns : | a themed icon name, or `NULL`

### e_activity_set_icon_name ()

    void                e_activity_set_icon_name            (EActivity *activity,
                                                             const gchar *icon_name);

Sets (or clears) the themed icon name for `activity`.

Generally widgets like EActivityBar will honor the "icon-name" property while the `activity`'s "state" is `E_ACTIVITY_RUNNING` or `E_ACTIVITY_WAITING`, but will override the icon for `E_ACTIVITY_CANCELLED` and `E_ACTIVITY_COMPLETED`.

`activity` : | an EActivity
`icon_name` : | a themed icon name, or `NULL`

### e_activity_get_percent ()

    gdouble             e_activity_get_percent              (EActivity *activity);

Returns the percent complete for `activity` as a value between 0 and 100, or a negative value if the percent complete is unknown.

Generally widgets like EActivityBar will display the percent complete by way of `e_activity_describe()`, but only if the value is between 0 and 100.

`activity` : | an EActivity
Returns : | the percent complete, or a negative value if unknown

### e_activity_set_percent ()

    void                e_activity_set_percent              (EActivity *activity,
                                                             gdouble percent);

Sets the percent complete for `activity`. The value should be between 0 and 100, or negative if the percent complete is unknown.

Generally widgets like EActivityBar will display the percent complete by way of `e_activity_describe()`, but only if the value is between 0 and 100.

`activity` : | an EActivity
`percent` : | the percent complete, or a negative value if unknown

### enum EActivityState

    typedef enum {
    	E_ACTIVITY_RUNNING,
    	E_ACTIVITY_WAITING,
    	E_ACTIVITY_CANCELLED,
    	E_ACTIVITY_COMPLETED
    } EActivityState;

Various states of an EActivity.

`E_ACTIVITY_RUNNING` | The EActivity is running.
`E_ACTIVITY_WAITING` | The EActivity is waiting to be run.
`E_ACTIVITY_CANCELLED` | The EActivity has been cancelled.
`E_ACTIVITY_COMPLETED` | The EActivity has completed.

### e_activity_get_state ()

    EActivityState      e_activity_get_state                (EActivity *activity);

Returns the state of `activity`.

Generally widgets like EActivityBar will display the activity state by way of `e_activity_describe()` and possibly an icon. The activity state is `E_ACTIVITY_RUNNING` by default, and is usually only changed once when the associated operation is finished.

`activity` : | an EActivity
Returns : | an EActivityState

### e_activity_set_state ()

    void                e_activity_set_state                (EActivity *activity,
                                                             EActivityState state);

Sets the state of `activity`.

Generally widgets like EActivityBar will display the activity state by way of `e_activity_describe()` and possibly an icon. The activity state is `E_ACTIVITY_RUNNING` by default, and is usually only changed once when the associated operation is finished.

`activity` : | an EActivity
`state` : | an EActivityState

### e_activity_get_text ()

    const gchar *       e_activity_get_text                 (EActivity *activity);

Returns a message describing what `activity` is doing.

Generally widgets like EActivityBar will display the message by way of `e_activity_describe()`.

`activity` : | an EActivity
Returns : | a descriptive message

### e_activity_set_text ()

    void                e_activity_set_text                 (EActivity *activity,
                                                             const gchar *text);

Sets (or clears) a message describing what `activity` is doing.

Generally widgets like EActivityBar will display the message by way of `e_activity_describe()`.

`activity` : | an EActivity
`text` : | a descriptive message, or `NULL`

### e_activity_get_last_known_text ()

    const gchar *       e_activity_get_last_known_text      (EActivity *activity);

Returns the last non-empty "text" value, so it's possible to identify what the `activity` was doing even if it currently has no description.

Mostly useful for debugging.

`activity` : | an EActivity
Returns : | a descriptive message, or `NULL`

### e_activity_handle_cancellation ()

    gboolean            e_activity_handle_cancellation      (EActivity *activity,
                                                             const GError *error);

Convenience function sets `activity`'s "state" to `E_ACTIVITY_CANCELLED` if `error` is `G_IO_ERROR_CANCELLED`.

`activity` : | an EActivity
`error` : | a GError, or `NULL`
Returns : | `TRUE` if `activity` was set to `E_ACTIVITY_CANCELLED`

## Property Details

### The `"alert-sink"` property

      "alert-sink"               EAlertSink*           : Read / Write / Construct

### The `"cancellable"` property

      "cancellable"              GCancellable*         : Read / Write / Construct

### The `"icon-name"` property

      "icon-name"                gchar*                : Read / Write / Construct

Default value: NULL

### The `"percent"` property

      "percent"                  gdouble               : Read / Write / Construct

Default value: -1

### The `"state"` property

      "state"                    EActivityState        : Read / Write / Construct

Default value: E_ACTIVITY_RUNNING

### The `"text"` property

      "text"                     gchar*                : Read / Write / Construct

Default value: NULL