|  |  |  | Evolution Utilities Reference Manual |  | 
|---|---|---|---|---|
| Top | Description | Object Hierarchy | Properties | ||||
#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);
"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
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.
EActivity *         e_activity_new                      (void);
Creates a new EActivity.
| Returns : | an EActivity | 
void                e_activity_cancel                   (EActivity *activity);
Convenience function cancels activity's "cancellable".
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".
  
| 
 | an EActivity | 
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.
| 
 | an EActivity | 
| Returns : | a description of activity | 
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.
| 
 | an EActivity | 
| Returns : | an EAlertSink, or NULL | 
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.
| 
 | an EActivity | 
| 
 | an EAlertSink, or NULL | 
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.
| 
 | an EActivity | 
| Returns : | a GCancellable, or NULL | 
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.
| 
 | an EActivity | 
| 
 | a GCancellable, or NULL | 
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.
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.
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.
| 
 | an EActivity | 
| Returns : | the percent complete, or a negative value if unknown | 
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.
| 
 | an EActivity | 
| 
 | the percent complete, or a negative value if unknown | 
typedef enum {
	E_ACTIVITY_RUNNING,
	E_ACTIVITY_WAITING,
	E_ACTIVITY_CANCELLED,
	E_ACTIVITY_COMPLETED
} EActivityState;
Various states of an EActivity.
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.
| 
 | an EActivity | 
| Returns : | an EActivityState | 
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.
| 
 | an EActivity | 
| 
 | an EActivityState | 
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().
| 
 | an EActivity | 
| Returns : | a descriptive message | 
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().
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.
"state" property"state" EActivityState : Read / Write / Construct
Default value: E_ACTIVITY_RUNNING