aboutsummaryrefslogtreecommitdiff
path: root/libindicate/indicator.h
diff options
context:
space:
mode:
authorTed Gould <ted@canonical.com>2009-05-05 16:43:20 +0100
committerTed Gould <ted@canonical.com>2009-05-05 16:43:20 +0100
commit7926d56f4dc89d8f30b0f6759119b8dd1507d666 (patch)
treee05e941faacc39a1585fc004637eae0ae888434b /libindicate/indicator.h
parent0ed074906ff7c3344fe866852baf64c3fbdbf13d (diff)
parent1b3fd9245f98ac5b13c44f4f9e8ca30ef76ac526 (diff)
downloadlibayatana-indicator-7926d56f4dc89d8f30b0f6759119b8dd1507d666.tar.gz
libayatana-indicator-7926d56f4dc89d8f30b0f6759119b8dd1507d666.tar.bz2
libayatana-indicator-7926d56f4dc89d8f30b0f6759119b8dd1507d666.zip
Merging in the documentation branch.
Diffstat (limited to 'libindicate/indicator.h')
-rw-r--r--libindicate/indicator.h64
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__ */