aboutsummaryrefslogtreecommitdiff
path: root/libindicate
diff options
context:
space:
mode:
authorTed Gould <ted@canonical.com>2009-04-30 11:40:56 -0500
committerTed Gould <ted@canonical.com>2009-04-30 11:40:56 -0500
commitc73af692f9bd4cab185206ab90b592469e659d77 (patch)
tree7fc28ef9b7f65f9bedd5591610fe2083faf66ac9 /libindicate
parent0ed074906ff7c3344fe866852baf64c3fbdbf13d (diff)
downloadlibayatana-indicator-c73af692f9bd4cab185206ab90b592469e659d77.tar.gz
libayatana-indicator-c73af692f9bd4cab185206ab90b592469e659d77.tar.bz2
libayatana-indicator-c73af692f9bd4cab185206ab90b592469e659d77.zip
First pass at trying to create some function documentation for Indicator
Diffstat (limited to 'libindicate')
-rw-r--r--libindicate/indicator.c99
-rw-r--r--libindicate/indicator.h8
2 files changed, 107 insertions, 0 deletions
diff --git a/libindicate/indicator.c b/libindicate/indicator.c
index dfcba67..87b11a7 100644
--- a/libindicate/indicator.c
+++ b/libindicate/indicator.c
@@ -76,6 +76,12 @@ indicate_indicator_class_init (IndicateIndicatorClass * class)
gobj->finalize = indicate_indicator_finalize;
+ /** IndicateIndicator::dispaly:
+
+ Emitted when the user has clicked on this indicator. In the
+ messaging indicator this would be when someone clicks on the
+ menu item for the indicator.
+ */
signals[USER_DISPLAY] = g_signal_new(INDICATE_INDICATOR_SIGNAL_DISPLAY,
G_TYPE_FROM_CLASS(class),
G_SIGNAL_RUN_LAST,
@@ -83,6 +89,11 @@ indicate_indicator_class_init (IndicateIndicatorClass * class)
NULL, NULL,
g_cclosure_marshal_VOID__VOID,
G_TYPE_NONE, 0);
+ /** IndicateIndicator::hide:
+
+ Emitted every time this indicator is hidden. This
+ is mostly used by #IndicateServer.
+ */
signals[HIDE] = g_signal_new(INDICATE_INDICATOR_SIGNAL_HIDE,
G_TYPE_FROM_CLASS(class),
G_SIGNAL_RUN_LAST,
@@ -90,6 +101,11 @@ indicate_indicator_class_init (IndicateIndicatorClass * class)
NULL, NULL,
g_cclosure_marshal_VOID__VOID,
G_TYPE_NONE, 0);
+ /** IndicateIndicator::hide:
+
+ Emitted every time this indicator is shown. This
+ is mostly used by #IndicateServer.
+ */
signals[SHOW] = g_signal_new(INDICATE_INDICATOR_SIGNAL_SHOW,
G_TYPE_FROM_CLASS(class),
G_SIGNAL_RUN_LAST,
@@ -97,6 +113,11 @@ indicate_indicator_class_init (IndicateIndicatorClass * class)
NULL, NULL,
g_cclosure_marshal_VOID__VOID,
G_TYPE_NONE, 0);
+ /** IndicateIndicator::modified:
+
+ Emitted every time an indicator property is changed.
+ This is mostly used by #IndicateServer.
+ */
signals[MODIFIED] = g_signal_new(INDICATE_INDICATOR_SIGNAL_MODIFIED,
G_TYPE_FROM_CLASS(class),
G_SIGNAL_RUN_LAST,
@@ -145,6 +166,10 @@ indicate_indicator_finalize (GObject * obj)
return;
}
+/** indicate_indicator_new:
+
+ Builds a new indicator object using #g_object_new.
+*/
IndicateIndicator *
indicate_indicator_new (void)
{
@@ -152,6 +177,13 @@ indicate_indicator_new (void)
return indicator;
}
+/** indicate_indicator_show:
+ @indicator: a #IndicateIndicator to act on
+
+ Shows this indicator on the bus. If the #IndicateServer that it's
+ connected to is not shown itself this function will show the server
+ as well using #indicate_server_show.
+*/
void
indicate_indicator_show (IndicateIndicator * indicator)
{
@@ -171,6 +203,12 @@ indicate_indicator_show (IndicateIndicator * indicator)
return;
}
+/** indicate_indicator_hide:
+ @indicator: a #IndicateIndicator to act on
+
+ Hides the indicator from the bus. Does not effect the
+ indicator's #IndicateServer in any way.
+*/
void
indicate_indicator_hide (IndicateIndicator * indicator)
{
@@ -186,6 +224,13 @@ indicate_indicator_hide (IndicateIndicator * indicator)
return;
}
+/** indicate_indicator_is_visible:
+ @indicator: a #IndicateIndicator to act on
+
+ Checkes the visibility status of @indicator.
+
+ Return value: %TRUE if the indicator is visible else %FALSE.
+*/
gboolean
indicate_indicator_is_visible (IndicateIndicator * indicator)
{
@@ -194,6 +239,14 @@ indicate_indicator_is_visible (IndicateIndicator * indicator)
return priv->is_visible;
}
+/** indicate_indicator_get_id:
+ @indicator: a #IndicateIndicator to act on
+
+ Gets the ID value of the @indicator.
+
+ Return value: The ID of the indicator. Can not be zero.
+ Zero represents an error.
+*/
guint
indicate_indicator_get_id (IndicateIndicator * indicator)
{
@@ -202,6 +255,14 @@ indicate_indicator_get_id (IndicateIndicator * indicator)
return priv->id;
}
+/** indicate_indicator_get_indicator_type:
+ @indicator: a #IndicateIndicator to act on
+
+ Returns the type of @indicator. This is largely set by the subclass
+ that the indicator was built with and should not be free'd.
+
+ Return value: A string defining the type or NULL for no type.
+*/
const gchar *
indicate_indicator_get_indicator_type (IndicateIndicator * indicator)
{
@@ -215,6 +276,13 @@ indicate_indicator_get_indicator_type (IndicateIndicator * indicator)
return NULL;
}
+/** indicate_indicator_user_display:
+ @indicator: a #IndicateIndicator to act on
+
+ Emits the #IndicateIndicator::user-display signal simliar to a user
+ clicking on @indicator over the bus. Signal will not be sent if the
+ @indicator is not visible.
+*/
void
indicate_indicator_user_display (IndicateIndicator * indicator)
{
@@ -227,6 +295,17 @@ indicate_indicator_user_display (IndicateIndicator * indicator)
return;
}
+/** indicate_indicator_set_property:
+ @indicator: a #IndicateIndicator to act on
+ @key: name of the property
+ @data: value of the property
+
+ Sets a simple string property on @indicator. If the property
+ had previously been set it will replace it with the new value,
+ otherwise it will create the property. This will include an
+ emition of #IndicateIndicator::modified if the property value
+ was changed.
+*/
void
indicate_indicator_set_property (IndicateIndicator * indicator, const gchar * key, const gchar * data)
{
@@ -238,6 +317,16 @@ indicate_indicator_set_property (IndicateIndicator * indicator, const gchar * ke
return class->set_property(indicator, key, data);
}
+/** indicate_indicator_set_property_icon:
+ @indicator: a #IndicateIndicator to act on
+ @key: name of the property
+ @data: icon to set property with
+
+ This is a helper function that wraps around #indicate_indicator_set_property
+ but takes an #GdkPixbuf parameter. It then takes the @data
+ parameter, turns it into a PNG, base64 encodes it and then
+ uses that data to call #indicate_indicator_set_property.
+*/
void
indicate_indicator_set_property_icon (IndicateIndicator * indicator, const gchar * key, const GdkPixbuf * data)
{
@@ -271,6 +360,16 @@ indicate_indicator_set_property_icon (IndicateIndicator * indicator, const gchar
return;
}
+/** indicate_indicator_set_property_time:
+ @indicator: a #IndicateIndicator to act on
+ @key: name of the property
+ @data: time to set property with
+
+ This is a helper function that wraps around #indicate_indicator_set_property
+ but takes an #GTimeVal parameter. It then takes the @data
+ parameter converts it to an ISO 8601 time string and
+ uses that data to call #indicate_indicator_set_property.
+*/
void
indicate_indicator_set_property_time (IndicateIndicator * indicator, const gchar * key, GTimeVal * time)
{
diff --git a/libindicate/indicator.h b/libindicate/indicator.h
index 8af5568..4536cf5 100644
--- a/libindicate/indicator.h
+++ b/libindicate/indicator.h
@@ -56,6 +56,14 @@ G_BEGIN_DECLS
typedef struct _IndicateIndicator IndicateIndicator;
typedef struct _IndicateIndicatorClass IndicateIndicatorClass;
+/**
+ IndicateInidcator:
+
+ The indicator object represents a single item that is shared over the
+ indicator bus. This could be something like one IM, one e-mail or
+ a single system update. It should be accessed only through its
+ accessors.
+*/
struct _IndicateIndicator {
GObject parent;
};