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 From f62b8365144946f97e7c6450dcc36c09d746ff31 Mon Sep 17 00:00:00 2001 From: Ted Gould Date: Thu, 30 Apr 2009 11:51:46 -0500 Subject: Dispaly typo --- libindicate/indicator.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'libindicate/indicator.c') diff --git a/libindicate/indicator.c b/libindicate/indicator.c index 87b11a7..b691357 100644 --- a/libindicate/indicator.c +++ b/libindicate/indicator.c @@ -76,7 +76,7 @@ indicate_indicator_class_init (IndicateIndicatorClass * class) gobj->finalize = indicate_indicator_finalize; - /** IndicateIndicator::dispaly: + /** IndicateIndicator::display: Emitted when the user has clicked on this indicator. In the messaging indicator this would be when someone clicks on the -- cgit v1.2.3 From 1c91e431be9a8e9bf706485735efccf0a0c54283 Mon Sep 17 00:00:00 2001 From: Ted Gould Date: Thu, 30 Apr 2009 13:07:29 -0500 Subject: Turns out that gtk-doc can't have the name of the function on the same line as the start of the comment. How stupid. --- libindicate/indicator.c | 44 ++++++++++++++++++++++++++++++-------------- 1 file changed, 30 insertions(+), 14 deletions(-) (limited to 'libindicate/indicator.c') diff --git a/libindicate/indicator.c b/libindicate/indicator.c index b691357..e40975a 100644 --- a/libindicate/indicator.c +++ b/libindicate/indicator.c @@ -76,7 +76,8 @@ indicate_indicator_class_init (IndicateIndicatorClass * class) gobj->finalize = indicate_indicator_finalize; - /** IndicateIndicator::display: + /** + IndicateIndicator::display: Emitted when the user has clicked on this indicator. In the messaging indicator this would be when someone clicks on the @@ -89,7 +90,8 @@ indicate_indicator_class_init (IndicateIndicatorClass * class) NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0); - /** IndicateIndicator::hide: + /** + IndicateIndicator::hide: Emitted every time this indicator is hidden. This is mostly used by #IndicateServer. @@ -101,7 +103,8 @@ indicate_indicator_class_init (IndicateIndicatorClass * class) NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0); - /** IndicateIndicator::hide: + /** + IndicateIndicator::hide: Emitted every time this indicator is shown. This is mostly used by #IndicateServer. @@ -113,7 +116,8 @@ indicate_indicator_class_init (IndicateIndicatorClass * class) NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0); - /** IndicateIndicator::modified: + /** + IndicateIndicator::modified: Emitted every time an indicator property is changed. This is mostly used by #IndicateServer. @@ -166,9 +170,12 @@ indicate_indicator_finalize (GObject * obj) return; } -/** indicate_indicator_new: +/** + indicate_indicator_new: Builds a new indicator object using #g_object_new. + + Return value: A pointer to a new #IndicateIndicator object. */ IndicateIndicator * indicate_indicator_new (void) @@ -177,7 +184,8 @@ indicate_indicator_new (void) return indicator; } -/** indicate_indicator_show: +/** + indicate_indicator_show: @indicator: a #IndicateIndicator to act on Shows this indicator on the bus. If the #IndicateServer that it's @@ -203,7 +211,8 @@ indicate_indicator_show (IndicateIndicator * indicator) return; } -/** indicate_indicator_hide: +/** + indicate_indicator_hide: @indicator: a #IndicateIndicator to act on Hides the indicator from the bus. Does not effect the @@ -224,7 +233,8 @@ indicate_indicator_hide (IndicateIndicator * indicator) return; } -/** indicate_indicator_is_visible: +/** + indicate_indicator_is_visible: @indicator: a #IndicateIndicator to act on Checkes the visibility status of @indicator. @@ -239,7 +249,8 @@ indicate_indicator_is_visible (IndicateIndicator * indicator) return priv->is_visible; } -/** indicate_indicator_get_id: +/** + indicate_indicator_get_id: @indicator: a #IndicateIndicator to act on Gets the ID value of the @indicator. @@ -255,7 +266,8 @@ indicate_indicator_get_id (IndicateIndicator * indicator) return priv->id; } -/** indicate_indicator_get_indicator_type: +/** + indicate_indicator_get_indicator_type: @indicator: a #IndicateIndicator to act on Returns the type of @indicator. This is largely set by the subclass @@ -276,7 +288,8 @@ indicate_indicator_get_indicator_type (IndicateIndicator * indicator) return NULL; } -/** indicate_indicator_user_display: +/** + indicate_indicator_user_display: @indicator: a #IndicateIndicator to act on Emits the #IndicateIndicator::user-display signal simliar to a user @@ -295,7 +308,8 @@ indicate_indicator_user_display (IndicateIndicator * indicator) return; } -/** indicate_indicator_set_property: +/** + indicate_indicator_set_property: @indicator: a #IndicateIndicator to act on @key: name of the property @data: value of the property @@ -317,7 +331,8 @@ indicate_indicator_set_property (IndicateIndicator * indicator, const gchar * ke return class->set_property(indicator, key, data); } -/** indicate_indicator_set_property_icon: +/** + indicate_indicator_set_property_icon: @indicator: a #IndicateIndicator to act on @key: name of the property @data: icon to set property with @@ -360,7 +375,8 @@ indicate_indicator_set_property_icon (IndicateIndicator * indicator, const gchar return; } -/** indicate_indicator_set_property_time: +/** + indicate_indicator_set_property_time: @indicator: a #IndicateIndicator to act on @key: name of the property @data: time to set property with -- cgit v1.2.3 From 43f575ee79e3f0bd6f69a6ce835d5298053073fb Mon Sep 17 00:00:00 2001 From: Ted Gould Date: Thu, 30 Apr 2009 14:06:45 -0500 Subject: Getting most of the indicator documentation in the pool. --- libindicate/indicator.c | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) (limited to 'libindicate/indicator.c') diff --git a/libindicate/indicator.c b/libindicate/indicator.c index e40975a..c867a9a 100644 --- a/libindicate/indicator.c +++ b/libindicate/indicator.c @@ -170,6 +170,14 @@ indicate_indicator_finalize (GObject * obj) return; } +/** + indicate_indicator_get_type: + + Gets a unique #GType for the #IndicateIndicator objects. + + Return value: A unique #GType value. +*/ + /** indicate_indicator_new: @@ -397,6 +405,16 @@ indicate_indicator_set_property_time (IndicateIndicator * indicator, const gchar return; } +/** + indicate_indicator_get_property: + @indicator: a #IndicateIndicator to act on + @key: name of the property + + Returns the value that is set for a property or %NULL if that + property is not set. + + Return value: A constant string or NULL. +*/ const gchar * indicate_indicator_get_property (IndicateIndicator * indicator, const gchar * key) { @@ -408,6 +426,17 @@ indicate_indicator_get_property (IndicateIndicator * indicator, const gchar * ke return class->get_property(indicator, key); } +/** + indicate_indicator_list_properties: + @indicator: a #IndicateIndicator to act on + + This function gets a list of all the properties that exist + on a @indicator. The array may have zero entries but almost + always at least has 'type' in it. + + Return value: An array of strings that is the keys of all + the properties on this indicator. +*/ GPtrArray * indicate_indicator_list_properties (IndicateIndicator * indicator) { -- cgit v1.2.3 From 933bcaaa5942e9990e07da32bcde392d0e9a7883 Mon Sep 17 00:00:00 2001 From: Ted Gould Date: Thu, 30 Apr 2009 16:57:51 -0500 Subject: Adding in message documentation and cleaning up some mistakes as I see them. --- libindicate/indicator.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'libindicate/indicator.c') diff --git a/libindicate/indicator.c b/libindicate/indicator.c index c867a9a..15788d4 100644 --- a/libindicate/indicator.c +++ b/libindicate/indicator.c @@ -181,7 +181,7 @@ indicate_indicator_finalize (GObject * obj) /** indicate_indicator_new: - Builds a new indicator object using #g_object_new. + Builds a new indicator object using g_object_new(). Return value: A pointer to a new #IndicateIndicator object. */ -- cgit v1.2.3 From 1595ee29749284d0606f4a5524aeefbc728498e4 Mon Sep 17 00:00:00 2001 From: Ted Gould Date: Thu, 30 Apr 2009 20:58:42 -0500 Subject: Adding in arguments for the signals --- libindicate/indicator.c | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) (limited to 'libindicate/indicator.c') diff --git a/libindicate/indicator.c b/libindicate/indicator.c index 15788d4..207d975 100644 --- a/libindicate/indicator.c +++ b/libindicate/indicator.c @@ -78,6 +78,7 @@ indicate_indicator_class_init (IndicateIndicatorClass * class) /** IndicateIndicator::display: + @arg0: The #IndicateIndicator object Emitted when the user has clicked on this indicator. In the messaging indicator this would be when someone clicks on the @@ -92,9 +93,12 @@ indicate_indicator_class_init (IndicateIndicatorClass * class) G_TYPE_NONE, 0); /** IndicateIndicator::hide: + @arg0: The #IndicateIndicator object Emitted every time this indicator is hidden. This is mostly used by #IndicateServer. + + Typically this results in an emition of #IndicateServer::indicator-removed. */ signals[HIDE] = g_signal_new(INDICATE_INDICATOR_SIGNAL_HIDE, G_TYPE_FROM_CLASS(class), @@ -104,10 +108,13 @@ indicate_indicator_class_init (IndicateIndicatorClass * class) g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0); /** - IndicateIndicator::hide: + IndicateIndicator::show: + @arg0: The #IndicateIndicator object Emitted every time this indicator is shown. This is mostly used by #IndicateServer. + + Typically this results in an emition of #IndicateServer::indicator-added. */ signals[SHOW] = g_signal_new(INDICATE_INDICATOR_SIGNAL_SHOW, G_TYPE_FROM_CLASS(class), @@ -118,9 +125,13 @@ indicate_indicator_class_init (IndicateIndicatorClass * class) G_TYPE_NONE, 0); /** IndicateIndicator::modified: + @arg0: The #IndicateIndicator object + @arg1: The name of the property that changed. Emitted every time an indicator property is changed. This is mostly used by #IndicateServer. + + Typically this results in an emition of #IndicateServer::indicator-modified. */ signals[MODIFIED] = g_signal_new(INDICATE_INDICATOR_SIGNAL_MODIFIED, G_TYPE_FROM_CLASS(class), -- cgit v1.2.3 From c027c7f3d30bc35937a5b900355bd593e2a12a04 Mon Sep 17 00:00:00 2001 From: Ted Gould Date: Thu, 30 Apr 2009 22:29:44 -0500 Subject: Fixing typo --- libindicate/indicator.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'libindicate/indicator.c') diff --git a/libindicate/indicator.c b/libindicate/indicator.c index 207d975..76eb616 100644 --- a/libindicate/indicator.c +++ b/libindicate/indicator.c @@ -398,7 +398,7 @@ indicate_indicator_set_property_icon (IndicateIndicator * indicator, const gchar indicate_indicator_set_property_time: @indicator: a #IndicateIndicator to act on @key: name of the property - @data: time to set property with + @time: 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 -- cgit v1.2.3