aboutsummaryrefslogtreecommitdiffstats
path: root/e-util
diff options
context:
space:
mode:
authorMatthew Barnes <mbarnes@redhat.com>2013-04-25 06:19:25 +0800
committerMatthew Barnes <mbarnes@redhat.com>2013-04-25 23:42:04 +0800
commitd0a0a397987684334c5fd41b364218782bc9bcfd (patch)
tree019a1ec598d2e817523888bd38858b23ff8e19e3 /e-util
parent3573cab310cf9e74a28163e5b8ee1f82b3884af6 (diff)
downloadgsoc2013-evolution-d0a0a397987684334c5fd41b364218782bc9bcfd.tar.gz
gsoc2013-evolution-d0a0a397987684334c5fd41b364218782bc9bcfd.tar.zst
gsoc2013-evolution-d0a0a397987684334c5fd41b364218782bc9bcfd.zip
Document EActivity.
Diffstat (limited to 'e-util')
-rw-r--r--e-util/e-activity.c186
1 files changed, 183 insertions, 3 deletions
diff --git a/e-util/e-activity.c b/e-util/e-activity.c
index 5eefb652b0..e4c121308b 100644
--- a/e-util/e-activity.c
+++ b/e-util/e-activity.c
@@ -14,11 +14,20 @@
* You should have received a copy of the GNU Lesser General Public
* License along with the program; if not, see <http://www.gnu.org/licenses/>
*
- *
- * Copyright (C) 1999-2008 Novell, Inc. (www.novell.com)
- *
*/
+/**
+ * SECTION: e-activity
+ * @include: e-util/e-util.h
+ * @short_description: Describe activities in progress
+ *
+ * #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.
+ **/
+
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
@@ -360,12 +369,31 @@ e_activity_init (EActivity *activity)
activity->priv->warn_bogus_percent = TRUE;
}
+/**
+ * e_activity_new:
+ *
+ * Creates a new #EActivity.
+ *
+ * Returns: an #EActivity
+ **/
EActivity *
e_activity_new (void)
{
return g_object_new (E_TYPE_ACTIVITY, NULL);
}
+/**
+ * e_activity_describe:
+ * @activity: an #EActivity
+ *
+ * Returns a description of the current state of the @activity based on
+ * the #EActivity:text, #EActivity:percent and #EActivity:state properties.
+ * Suitable for displaying in a status bar or similar widget.
+ *
+ * Free the returned string with g_free() when finished with it.
+ *
+ * Returns: a description of @activity
+ **/
gchar *
e_activity_describe (EActivity *activity)
{
@@ -379,6 +407,19 @@ e_activity_describe (EActivity *activity)
return class->describe (activity);
}
+/**
+ * e_activity_get_alert_sink:
+ * @activity: an #EActivity
+ *
+ * Returns the #EAlertSink for @activity, if one was provided.
+ *
+ * The #EActivity:alert-sink property is convenient for when the user
+ * should be alerted about a failed asynchronous operation. Generally
+ * an #EActivity:alert-sink is set prior to dispatching the operation,
+ * and retrieved by a callback function when the operation completes.
+ *
+ * Returns: an #EAlertSink, or %NULL
+ **/
EAlertSink *
e_activity_get_alert_sink (EActivity *activity)
{
@@ -387,6 +428,18 @@ e_activity_get_alert_sink (EActivity *activity)
return activity->priv->alert_sink;
}
+/**
+ * e_activity_set_alert_sink:
+ * @activity: an #EActivity
+ * @alert_sink: an #EAlertSink, or %NULL
+ *
+ * Sets (or clears) the #EAlertSink for @activity.
+ *
+ * The #EActivity:alert-sink property is convenient for when the user
+ * should be alerted about a failed asynchronous operation. Generally
+ * an #EActivity:alert-sink is set prior to dispatching the operation,
+ * and retrieved by a callback function when the operation completes.
+ **/
void
e_activity_set_alert_sink (EActivity *activity,
EAlertSink *alert_sink)
@@ -409,6 +462,18 @@ e_activity_set_alert_sink (EActivity *activity,
g_object_notify (G_OBJECT (activity), "alert-sink");
}
+/**
+ * e_activity_get_cancellable:
+ * @activity: an #EActivity
+ *
+ * Returns the #GCancellable for @activity, if one was provided.
+ *
+ * Generally the @activity's #EActivity:cancellable property holds the same
+ * #GCancellable instance passed to a cancellable function, so widgets like
+ * #EActivityBar can bind the #GCancellable to a cancel button.
+ *
+ * Returns: a #GCancellable, or %NULL
+ **/
GCancellable *
e_activity_get_cancellable (EActivity *activity)
{
@@ -417,6 +482,17 @@ e_activity_get_cancellable (EActivity *activity)
return activity->priv->cancellable;
}
+/**
+ * e_activity_set_cancellable:
+ * @activity: an #EActivity
+ * @cancellable: a #GCancellable, or %NULL
+ *
+ * Sets (or clears) the #GCancellable for @activity.
+ *
+ * Generally the @activity's #EActivity:cancellable property holds the same
+ * #GCancellable instance passed to a cancellable function, so widgets like
+ * #EActivityBar can bind the #GCancellable to a cancel button.
+ **/
void
e_activity_set_cancellable (EActivity *activity,
GCancellable *cancellable)
@@ -450,6 +526,19 @@ e_activity_set_cancellable (EActivity *activity,
g_object_notify (G_OBJECT (activity), "cancellable");
}
+/**
+ * e_activity_get_icon_name:
+ * @activity: an #EActivity
+ *
+ * Returns the themed icon name for @activity, if one was provided.
+ *
+ * Generally widgets like #EActivityBar will honor the #EActivity:icon-name
+ * property while the @activity's #EActivity:state is @E_ACTIVITY_RUNNING or
+ * @E_ACTIVITY_WAITING, but will override the icon for @E_ACTIVITY_CANCELLED
+ * and @E_ACTIVITY_COMPLETED.
+ *
+ * Returns: a themed icon name, or %NULL
+ **/
const gchar *
e_activity_get_icon_name (EActivity *activity)
{
@@ -458,6 +547,18 @@ e_activity_get_icon_name (EActivity *activity)
return activity->priv->icon_name;
}
+/**
+ * e_activity_set_icon_name:
+ * @activity: an #EActivity
+ * @icon_name: a themed icon name, or %NULL
+ *
+ * Sets (or clears) the themed icon name for @activity.
+ *
+ * Generally widgets like #EActivityBar will honor the #EActivity:icon-name
+ * property while the @activity's #EActivity: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)
@@ -473,6 +574,18 @@ e_activity_set_icon_name (EActivity *activity,
g_object_notify (G_OBJECT (activity), "icon-name");
}
+/**
+ * e_activity_get_percent:
+ * @activity: an #EActivity
+ *
+ * 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.
+ *
+ * Returns: the percent complete, or a negative value if unknown
+ **/
gdouble
e_activity_get_percent (EActivity *activity)
{
@@ -481,6 +594,17 @@ e_activity_get_percent (EActivity *activity)
return activity->priv->percent;
}
+/**
+ * e_activity_set_percent:
+ * @activity: an #EActivity
+ * @percent: the percent complete, or a negative value if unknown
+ *
+ * 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.
+ **/
void
e_activity_set_percent (EActivity *activity,
gdouble percent)
@@ -495,6 +619,19 @@ e_activity_set_percent (EActivity *activity,
g_object_notify (G_OBJECT (activity), "percent");
}
+/**
+ * e_activity_get_state:
+ * @activity: an #EActivity
+ *
+ * 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.
+ *
+ * Returns: an #EActivityState
+ **/
EActivityState
e_activity_get_state (EActivity *activity)
{
@@ -503,6 +640,18 @@ e_activity_get_state (EActivity *activity)
return activity->priv->state;
}
+/**
+ * e_activity_set_state:
+ * @activity: an #EActivity
+ * @state: an #EActivityState
+ *
+ * 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.
+ **/
void
e_activity_set_state (EActivity *activity,
EActivityState state)
@@ -517,6 +666,17 @@ e_activity_set_state (EActivity *activity,
g_object_notify (G_OBJECT (activity), "state");
}
+/**
+ * e_activity_get_text:
+ * @activity: an #EActivity
+ *
+ * Returns a message describing what @activity is doing.
+ *
+ * Generally widgets like #EActivityBar will display the message by way of
+ * e_activity_describe().
+ *
+ * Returns: a descriptive message
+ **/
const gchar *
e_activity_get_text (EActivity *activity)
{
@@ -525,6 +685,16 @@ e_activity_get_text (EActivity *activity)
return activity->priv->text;
}
+/**
+ * e_activity_set_text:
+ * @activity: an #EActivity
+ * @text: a descriptive message, or %NULL
+ *
+ * Sets (or clears) a message describing what @activity is doing.
+ *
+ * Generally widgets like #EActivityBar will display the message by way of
+ * e_activity_describe().
+ **/
void
e_activity_set_text (EActivity *activity,
const gchar *text)
@@ -540,6 +710,16 @@ e_activity_set_text (EActivity *activity,
g_object_notify (G_OBJECT (activity), "text");
}
+/**
+ * e_activity_handle_cancellation:
+ * @activity: an #EActivity
+ * @error: a #GError, or %NULL
+ *
+ * Convenience function sets @activity's #EActivity:state to
+ * @E_ACTIVITY_CANCELLED if @error is @G_IO_ERROR_CANCELLED.
+ *
+ * Returns: %TRUE if @activity was set to @E_ACTIVITY_CANCELLED
+ **/
gboolean
e_activity_handle_cancellation (EActivity *activity,
const GError *error)