EActivity: Evolution Utilities Reference Manual

## EActivity EActivity — Describe activities in progress |

## Functions

EActivity * | e_activity_new ()
void | e_activity_cancel ()
gchar * | e_activity_describe ()
EAlertSink * | e_activity_get_alert_sink ()
void | e_activity_set_alert_sink ()
GCancellable * | e_activity_get_cancellable ()
void | e_activity_set_cancellable ()
const gchar * | e_activity_get_icon_name ()
void | e_activity_set_icon_name ()
gdouble | e_activity_get_percent ()
void | e_activity_set_percent ()
EActivityState | e_activity_get_state ()
void | e_activity_set_state ()
const gchar * | e_activity_get_text ()
void | e_activity_set_text ()
const gchar * | e_activity_get_last_known_text ()
gboolean | e_activity_handle_cancellation ()

## Properties

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

## Types and Values

struct | EActivity
enum | EActivityState

## Object Hierarchy

        GObject
        ╰── EActivity

## Includes

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

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

## Functions

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

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".

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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` .

#### Parameters

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` .

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

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

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

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` .

#### Parameters

activity | an EActivity |
error | a GError, or `NULL` |

#### Returns

`TRUE` if `activity` was set to `E_ACTIVITY_CANCELLED`

## Types and Values

### struct EActivity

    struct EActivity;

### enum EActivityState

Various states of an EActivity.

#### Members

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

## Property Details

### The `“alert-sink”` property

      “alert-sink”               EAlertSink *

Flags: Read / Write / Construct

### The `“cancellable”` property

      “cancellable”              GCancellable *

Flags: Read / Write / Construct

### The `“icon-name”` property

      “icon-name”                gchar *

Flags: Read / Write / Construct

Default value: NULL

### The `“percent”` property

      “percent”                  gdouble

Flags: Read / Write / Construct

Default value: -1

### The `“state”` property

      “state”                    EActivityState

Flags: Read / Write / Construct

Default value: E_ACTIVITY_RUNNING

### The `“text”` property

      “text”                     gchar *

Flags: Read / Write / Construct

Default value: NULL