From c73af692f9bd4cab185206ab90b592469e659d77 Mon Sep 17 00:00:00 2001 From: Ted Gould Date: Thu, 30 Apr 2009 11:40:56 -0500 Subject: First pass at trying to create some function documentation for Indicator --- libindicate/indicator.c | 99 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) (limited to 'libindicate/indicator.c') 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) { -- cgit v1.2.3