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.h | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'libindicate/indicator.h') 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; }; -- cgit v1.2.3 From 47c4b8e7c3f328da2ec23ddec762c47b329a44da Mon Sep 17 00:00:00 2001 From: Ted Gould Date: Thu, 30 Apr 2009 14:10:33 -0500 Subject: Typo --- libindicate/indicator.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'libindicate/indicator.h') diff --git a/libindicate/indicator.h b/libindicate/indicator.h index 4536cf5..138a48c 100644 --- a/libindicate/indicator.h +++ b/libindicate/indicator.h @@ -57,7 +57,7 @@ typedef struct _IndicateIndicator IndicateIndicator; typedef struct _IndicateIndicatorClass IndicateIndicatorClass; /** - IndicateInidcator: + IndicateIndicator: 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 -- cgit v1.2.3 From 877ac7aac626a3c8ce4bdd601eff9fb92fe64911 Mon Sep 17 00:00:00 2001 From: Ted Gould Date: Thu, 30 Apr 2009 14:29:40 -0500 Subject: Adding in IndicateIndicatorClass documentation. --- libindicate/indicator.h | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) (limited to 'libindicate/indicator.h') diff --git a/libindicate/indicator.h b/libindicate/indicator.h index 138a48c..dc057f4 100644 --- a/libindicate/indicator.h +++ b/libindicate/indicator.h @@ -68,6 +68,37 @@ struct _IndicateIndicator { GObject parent; }; +/** + IndicateIndicatorClass: + + All of the functions that are used to modify or change data that is + in the indicator. Typically gets subclassed by other types of + indicators, for example #IndicateIndicatorMessages. + + @hide: #IndicateIndicator::hide + + @show: #IndicateIndicator::show + + @user_display: #IndicateIndicator::user-display + + @modified: #IndicateIndicator::modified + + @get_type: Returns a constant string for the type of this indicator. + Typically gets overridden by subclasses and defines the type of + the indicator. + + @set_property: Called when #indicate_indicator_set_property is called + and should set the value. While typically it is overridden by + subclasses they usually handle special properties themselves and + then call the superclass for storage. + + @get_property: Called when #indicate_indicator_get_property is called + and should return the value requested. Many times this is left alone. + + @list_properties: Called when #indicate_indicator_list_properties is called + and returns a list of the properties available. Again this can be + overridden by subclasses to handle special properties. +*/ struct _IndicateIndicatorClass { GObjectClass parent_class; -- cgit v1.2.3 From 9201eb6ce3b2770038f0c71e89aadb3c55af6157 Mon Sep 17 00:00:00 2001 From: Ted Gould Date: Thu, 30 Apr 2009 14:35:30 -0500 Subject: Making it more like English and less like a pointer table. --- libindicate/indicator.h | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'libindicate/indicator.h') diff --git a/libindicate/indicator.h b/libindicate/indicator.h index dc057f4..61cc1d2 100644 --- a/libindicate/indicator.h +++ b/libindicate/indicator.h @@ -75,13 +75,13 @@ struct _IndicateIndicator { in the indicator. Typically gets subclassed by other types of indicators, for example #IndicateIndicatorMessages. - @hide: #IndicateIndicator::hide + @hide: Slot for #IndicateIndicator::hide. - @show: #IndicateIndicator::show + @show: Slot for #IndicateIndicator::show. - @user_display: #IndicateIndicator::user-display + @user_display: Slot for #IndicateIndicator::user-display. - @modified: #IndicateIndicator::modified + @modified: Slot for #IndicateIndicator::modified. @get_type: Returns a constant string for the type of this indicator. Typically gets overridden by subclasses and defines the type of -- cgit v1.2.3 From d73f65f28afe4fc11cec345e4baadf4d934c656d Mon Sep 17 00:00:00 2001 From: Ted Gould Date: Thu, 30 Apr 2009 15:12:37 -0500 Subject: Reformatting to make gtk-doc happy. --- libindicate/indicator.h | 26 ++++++++++---------------- 1 file changed, 10 insertions(+), 16 deletions(-) (limited to 'libindicate/indicator.h') diff --git a/libindicate/indicator.h b/libindicate/indicator.h index 61cc1d2..77ffb7d 100644 --- a/libindicate/indicator.h +++ b/libindicate/indicator.h @@ -70,34 +70,28 @@ struct _IndicateIndicator { /** IndicateIndicatorClass: - - All of the functions that are used to modify or change data that is - in the indicator. Typically gets subclassed by other types of - indicators, for example #IndicateIndicatorMessages. - + @parent_class: Parent class #GObjectClass. @hide: Slot for #IndicateIndicator::hide. - @show: Slot for #IndicateIndicator::show. - @user_display: Slot for #IndicateIndicator::user-display. - @modified: Slot for #IndicateIndicator::modified. - @get_type: Returns a constant string for the type of this indicator. Typically gets overridden by subclasses and defines the type of - the indicator. - - @set_property: Called when #indicate_indicator_set_property is called + the indicator. Is called by indicate_indicator_get_indicator_type(). + @set_property: Called when indicate_indicator_set_property() is called and should set the value. While typically it is overridden by subclasses they usually handle special properties themselves and then call the superclass for storage. - - @get_property: Called when #indicate_indicator_get_property is called + @get_property: Called when indicate_indicator_get_property() is called and should return the value requested. Many times this is left alone. - - @list_properties: Called when #indicate_indicator_list_properties is called + @list_properties: Called when indicate_indicator_list_properties() is called and returns a list of the properties available. Again this can be overridden by subclasses to handle special properties. + + All of the functions that are used to modify or change data that is + in the indicator. Typically gets subclassed by other types of + indicators, for example #IndicateIndicatorMessages. + */ struct _IndicateIndicatorClass { GObjectClass parent_class; -- cgit v1.2.3 From a77a8085c8993dfb3e27952e77c245d6bca86128 Mon Sep 17 00:00:00 2001 From: Ted Gould Date: Thu, 30 Apr 2009 15:40:06 -0500 Subject: Section information --- libindicate/indicator.h | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) (limited to 'libindicate/indicator.h') diff --git a/libindicate/indicator.h b/libindicate/indicator.h index 77ffb7d..3e2a803 100644 --- a/libindicate/indicator.h +++ b/libindicate/indicator.h @@ -133,6 +133,37 @@ void indicate_indicator_set_property_time (IndicateIndicator * indicator, const const gchar * indicate_indicator_get_property (IndicateIndicator * indicator, const gchar * key); GPtrArray * indicate_indicator_list_properties (IndicateIndicator * indicator); +/** + SECTION:indicator + @short_description: A representation of state for applications + @stability: Unstable + @include: libindicate/indicator.h + + An indicator is designed to represent a single instance of something + in your application. So this might be an IM or Email using #IndicateIndicatorMessage + or any other thing that is a small unit of information to pass on + to the user. + + Indicators make no promises about how they are preceived by the + user, it's up to the listener to represent them in an intutive and + visually appealling way. But, what we can do is provide information + on the indicator to provide enough information for the listener + to do that. + + Mostly this is done through properties. The only property that is + defined for the base indicator is the 'type' property. And this + is only available to set by creating a subclass of the + #IndicateIndicator object. It is assumed that you can look at the + definitions of the various subtypes to determine which properties + they support. + + It may be that some users don't want to create objects for every + indicator as it could be a lot of overhead if there are large numbers + and there is already a data structure representing them all. In that + case it is recommended that you ignore the #IndicateIndicator object + tree in general and move to subclassing #IndicateServer directly. +*/ + G_END_DECLS #endif /* INDICATE_INDICATOR_H_INCLUDED__ */ -- cgit v1.2.3