diff options
Diffstat (limited to 'libindicate/indicator.h')
| -rw-r--r-- | libindicate/indicator.h | 64 |
1 files changed, 64 insertions, 0 deletions
diff --git a/libindicate/indicator.h b/libindicate/indicator.h index 8af5568..3e2a803 100644 --- a/libindicate/indicator.h +++ b/libindicate/indicator.h @@ -56,10 +56,43 @@ G_BEGIN_DECLS typedef struct _IndicateIndicator IndicateIndicator; typedef struct _IndicateIndicatorClass IndicateIndicatorClass; +/** + 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 + a single system update. It should be accessed only through its + accessors. +*/ struct _IndicateIndicator { GObject parent; }; +/** + IndicateIndicatorClass: + @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. 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 + 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. + + 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; @@ -100,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__ */ |