diff options
| -rw-r--r-- | docs/reference/Makefile.am | 2 | ||||
| -rw-r--r-- | docs/reference/libindicate-docs.sgml | 34 | ||||
| -rw-r--r-- | docs/reference/libindicate-sections.txt | 154 | ||||
| -rw-r--r-- | docs/reference/tmpl/libindicate-unused.sgml | 187 | ||||
| -rw-r--r-- | libindicate/indicator-message.c | 7 | ||||
| -rw-r--r-- | libindicate/indicator-message.h | 39 | ||||
| -rw-r--r-- | libindicate/indicator.c | 155 | ||||
| -rw-r--r-- | libindicate/indicator.h | 64 | ||||
| -rw-r--r-- | libindicate/server.c | 208 | ||||
| -rw-r--r-- | libindicate/server.h | 81 |
10 files changed, 607 insertions, 324 deletions
diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am index 759465e..2589179 100644 --- a/docs/reference/Makefile.am +++ b/docs/reference/Makefile.am @@ -47,7 +47,7 @@ CFILE_GLOB=$(top_srcdir)/libindicate/*.c # Header files to ignore when scanning. # e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h -IGNORE_HFILES= +IGNORE_HFILES=dbus-indicate-client.h dbus-indicate-server.h dbus-listener-client.h dbus-listener-server.h listener-marshal.h # Images to copy into HTML directory. # e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png diff --git a/docs/reference/libindicate-docs.sgml b/docs/reference/libindicate-docs.sgml index 0f1ccd1..c3038d3 100644 --- a/docs/reference/libindicate-docs.sgml +++ b/docs/reference/libindicate-docs.sgml @@ -1,24 +1,32 @@ <?xml version="1.0"?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> -<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude"> +<book id="libindicatebook" xmlns:xi="http://www.w3.org/2003/XInclude"> + <bookinfo> <title>libindicate Reference Manual</title> - <releaseinfo> - for libindicate [VERSION] - The latest version of this documentation can be found on-line at - <ulink role="online-location" url="http://[SERVER]/libindicate/index.html">http://[SERVER]/libindicate/</ulink>. - </releaseinfo> </bookinfo> - <chapter> - <title>[Insert title here]</title> - </chapter> +<part id="base"> + <title>Base Classes for Applications</title> + <xi:include href="xml/indicator.xml" /> + <xi:include href="xml/server.xml" /> +</part> + +<part id="subclass"> + <title>Subclasses for specific indicators</title> + <xi:include href="xml/indicator-message.xml" /> +</part> - <chapter> - <title>libindicate Indicator</title> - <xi:include href="xml/indicator.xml" /> - </chapter> +<part id="listeners"> + <title>Classes for Listeners</title> + <xi:include href="xml/listener.xml" /> +</part> +<part id="index"> + <index> + <title>Index of all Symbols</title> + </index> +</part> </book> diff --git a/docs/reference/libindicate-sections.txt b/docs/reference/libindicate-sections.txt index f5f3290..6e2a8cd 100644 --- a/docs/reference/libindicate-sections.txt +++ b/docs/reference/libindicate-sections.txt @@ -2,148 +2,62 @@ <SECTION> <FILE>indicator</FILE> -<TITLE>Everything</TITLE> - -INDICATE_INDICATOR -INDICATE_INDICATOR_CLASS -INDICATE_INDICATOR_GET_CLASS -INDICATE_INDICATOR_MESSAGE -INDICATE_INDICATOR_MESSAGE_CLASS -INDICATE_INDICATOR_MESSAGE_GET_CLASS -INDICATE_INDICATOR_SIGNAL_DISPLAY -INDICATE_INDICATOR_SIGNAL_HIDE -INDICATE_INDICATOR_SIGNAL_MODIFIED -INDICATE_INDICATOR_SIGNAL_SHOW -INDICATE_IS_INDICATOR -INDICATE_IS_INDICATOR_CLASS -INDICATE_IS_INDICATOR_MESSAGE -INDICATE_IS_INDICATOR_MESSAGE_CLASS -INDICATE_IS_LISTENER -INDICATE_IS_LISTENER_CLASS -INDICATE_IS_SERVER -INDICATE_IS_SERVER_CLASS -INDICATE_LISTENER -INDICATE_LISTENER_CLASS -INDICATE_LISTENER_GET_CLASS -INDICATE_LISTENER_INDICATOR_ID -INDICATE_LISTENER_SERVER_DBUS_NAME -INDICATE_LISTENER_SIGNAL_INDICATOR_ADDED -INDICATE_LISTENER_SIGNAL_INDICATOR_MODIFIED -INDICATE_LISTENER_SIGNAL_INDICATOR_REMOVED -INDICATE_LISTENER_SIGNAL_SERVER_ADDED -INDICATE_LISTENER_SIGNAL_SERVER_REMOVED -INDICATE_SERVER -INDICATE_SERVER_CLASS -INDICATE_SERVER_GET_CLASS -INDICATE_TYPE_INDICATOR -INDICATE_TYPE_INDICATOR_MESSAGE -INDICATE_TYPE_LISTENER -INDICATE_TYPE_SERVER +<TITLE>IndicateIndicator</TITLE> IndicateIndicator IndicateIndicatorClass -IndicateIndicatorMessage -IndicateIndicatorMessageClass -IndicateListener -IndicateListenerClass -IndicateListenerIndicator -IndicateListenerServer -IndicateServer -IndicateServerClass -dbus_g_proxy_begin_call -dbus_glib_marshal_indicate_server_BOOLEAN__POINTER_POINTER -dbus_glib_marshal_indicate_server_BOOLEAN__STRING_POINTER_POINTER -dbus_glib_marshal_indicate_server_BOOLEAN__UINT_BOXED_POINTER_POINTER -dbus_glib_marshal_indicate_server_BOOLEAN__UINT_POINTER -dbus_glib_marshal_indicate_server_BOOLEAN__UINT_POINTER_POINTER -dbus_glib_marshal_indicate_server_BOOLEAN__UINT_STRING_POINTER_POINTER -g_marshal_value_peek_boolean -g_marshal_value_peek_boxed -g_marshal_value_peek_char -g_marshal_value_peek_double -g_marshal_value_peek_enum -g_marshal_value_peek_flags -g_marshal_value_peek_float -g_marshal_value_peek_int -g_marshal_value_peek_int64 -g_marshal_value_peek_long -g_marshal_value_peek_object -g_marshal_value_peek_param -g_marshal_value_peek_pointer -g_marshal_value_peek_string -g_marshal_value_peek_uchar -g_marshal_value_peek_uint -g_marshal_value_peek_uint64 -g_marshal_value_peek_ulong indicate_indicator_get_id indicate_indicator_get_indicator_type indicate_indicator_get_property -indicate_indicator_get_type indicate_indicator_hide indicate_indicator_is_visible indicate_indicator_list_properties -indicate_indicator_message_get_type -indicate_indicator_message_new indicate_indicator_new indicate_indicator_set_property +indicate_indicator_set_property_icon +indicate_indicator_set_property_time indicate_indicator_show indicate_indicator_user_display -indicate_listener_display -indicate_listener_get_property -indicate_listener_get_property_cb -indicate_listener_get_type -indicate_listener_marshal_VOID__POINTER_POINTER_STRING -indicate_listener_marshal_VOID__POINTER_POINTER_STRING_STRING -indicate_listener_marshal_VOID__UINT_STRING -indicate_listener_new +</SECTION> + +<SECTION> +<FILE>indicator-message</FILE> +<TITLE>IndicateIndicatorMessage</TITLE> +IndicateIndicatorMessage +IndicateIndicatorMessageClass +indicate_indicator_message_new +</SECTION> + +<SECTION> +<FILE>server</FILE> +<TITLE>IndicateServer</TITLE> +IndicateServer +IndicateServerClass indicate_server_add_indicator +indicate_server_check_interest indicate_server_emit_indicator_added indicate_server_emit_indicator_modified indicate_server_emit_indicator_removed -indicate_server_get_desktop -indicate_server_get_indicator_count -indicate_server_get_indicator_count_by_type -indicate_server_get_indicator_list -indicate_server_get_indicator_list_by_type -indicate_server_get_indicator_properties -indicate_server_get_indicator_property -indicate_server_get_indicator_property_group +indicate_server_emit_server_display indicate_server_get_next_id -indicate_server_get_type indicate_server_hide -indicate_server_new indicate_server_ref_default indicate_server_remove_indicator -indicate_server_set_dbus_object indicate_server_set_default indicate_server_set_desktop_file +indicate_server_set_type indicate_server_show -indicate_server_show_indicator_to_user -org_freedesktop_indicator_get_desktop -org_freedesktop_indicator_get_desktop_async -org_freedesktop_indicator_get_desktop_reply -org_freedesktop_indicator_get_indicator_count -org_freedesktop_indicator_get_indicator_count_async -org_freedesktop_indicator_get_indicator_count_by_type -org_freedesktop_indicator_get_indicator_count_by_type_async -org_freedesktop_indicator_get_indicator_count_by_type_reply -org_freedesktop_indicator_get_indicator_count_reply -org_freedesktop_indicator_get_indicator_list -org_freedesktop_indicator_get_indicator_list_async -org_freedesktop_indicator_get_indicator_list_by_type -org_freedesktop_indicator_get_indicator_list_by_type_async -org_freedesktop_indicator_get_indicator_list_by_type_reply -org_freedesktop_indicator_get_indicator_list_reply -org_freedesktop_indicator_get_indicator_properties -org_freedesktop_indicator_get_indicator_properties_async -org_freedesktop_indicator_get_indicator_properties_reply -org_freedesktop_indicator_get_indicator_property -org_freedesktop_indicator_get_indicator_property_async -org_freedesktop_indicator_get_indicator_property_group -org_freedesktop_indicator_get_indicator_property_group_async -org_freedesktop_indicator_get_indicator_property_group_reply -org_freedesktop_indicator_get_indicator_property_reply -org_freedesktop_indicator_show_indicator_to_user -org_freedesktop_indicator_show_indicator_to_user_async -org_freedesktop_indicator_show_indicator_to_user_reply +</SECTION> +<SECTION> +<FILE>listener</FILE> +<TITLE>IndicateListener</TITLE> +IndicateListener +IndicateListenerClass +IndicateListenerIndicator +IndicateListenerServer +indicate_listener_display +indicate_listener_get_property +indicate_listener_get_property_cb +indicate_listener_new </SECTION> + diff --git a/docs/reference/tmpl/libindicate-unused.sgml b/docs/reference/tmpl/libindicate-unused.sgml index d4e3767..c3152b1 100644 --- a/docs/reference/tmpl/libindicate-unused.sgml +++ b/docs/reference/tmpl/libindicate-unused.sgml @@ -1,195 +1,14 @@ -<!-- ##### FUNCTION dbus_glib_marshal_indicate_server_BOOLEAN__POINTER_POINTER ##### --> +<!-- ##### FUNCTION indicate_server_new ##### --> <para> </para> -@closure: -@return_value: -@n_param_values: -@param_values: -@invocation_hint: -@marshal_data: - -<!-- ##### FUNCTION dbus_glib_marshal_indicate_server_BOOLEAN__STRING_POINTER_POINTER ##### --> -<para> - -</para> - -@closure: -@return_value: -@n_param_values: -@param_values: -@invocation_hint: -@marshal_data: - -<!-- ##### FUNCTION dbus_glib_marshal_indicate_server_BOOLEAN__UINT_BOXED_POINTER_POINTER ##### --> -<para> - -</para> - -@closure: -@return_value: -@n_param_values: -@param_values: -@invocation_hint: -@marshal_data: - -<!-- ##### FUNCTION dbus_glib_marshal_indicate_server_BOOLEAN__UINT_POINTER ##### --> -<para> - -</para> - -@closure: -@return_value: -@n_param_values: -@param_values: -@invocation_hint: -@marshal_data: - -<!-- ##### FUNCTION dbus_glib_marshal_indicate_server_BOOLEAN__UINT_POINTER_POINTER ##### --> -<para> - -</para> - -@closure: -@return_value: -@n_param_values: -@param_values: -@invocation_hint: -@marshal_data: - -<!-- ##### FUNCTION dbus_glib_marshal_indicate_server_BOOLEAN__UINT_STRING_POINTER_POINTER ##### --> -<para> - -</para> - -@closure: -@return_value: -@n_param_values: -@param_values: -@invocation_hint: -@marshal_data: - -<!-- ##### FUNCTION indicate_listener_marshal_VOID__POINTER_POINTER_STRING ##### --> -<para> - -</para> - -@closure: -@return_value: -@n_param_values: -@param_values: -@invocation_hint: -@marshal_data: - -<!-- ##### FUNCTION indicate_listener_marshal_VOID__POINTER_POINTER_STRING_STRING ##### --> -<para> - -</para> - -@closure: -@return_value: -@n_param_values: -@param_values: -@invocation_hint: -@marshal_data: - -<!-- ##### FUNCTION indicate_listener_marshal_VOID__UINT_STRING ##### --> -<para> - -</para> - -@closure: -@return_value: -@n_param_values: -@param_values: -@invocation_hint: -@marshal_data: - -<!-- ##### FUNCTION indicate_server_get_indicator_count ##### --> -<para> - -</para> - -@server: -@count: -@error: @Returns: -<!-- ##### FUNCTION indicate_server_get_indicator_count_by_type ##### --> +<!-- ##### FUNCTION indicate_server_set_dbus_object ##### --> <para> </para> -@server: -@type: -@count: -@error: -@Returns: - -<!-- ##### FUNCTION indicate_server_get_indicator_list ##### --> -<para> - -</para> - -@server: -@indicators: -@error: -@Returns: - -<!-- ##### FUNCTION indicate_server_get_indicator_list_by_type ##### --> -<para> - -</para> - -@server: -@type: -@indicators: -@error: -@Returns: - -<!-- ##### FUNCTION indicate_server_get_indicator_properties ##### --> -<para> - -</para> - -@server: -@id: -@properties: -@error: -@Returns: - -<!-- ##### FUNCTION indicate_server_get_indicator_property ##### --> -<para> - -</para> - -@server: -@id: -@property: -@value: -@error: -@Returns: - -<!-- ##### FUNCTION indicate_server_get_indicator_property_group ##### --> -<para> - -</para> - -@server: -@id: -@properties: -@value: -@error: -@Returns: - -<!-- ##### FUNCTION indicate_server_show_indicator_to_user ##### --> -<para> - -</para> - -@server: -@id: -@error: -@Returns: +@obj: diff --git a/libindicate/indicator-message.c b/libindicate/indicator-message.c index 4e8ef30..9cd735a 100644 --- a/libindicate/indicator-message.c +++ b/libindicate/indicator-message.c @@ -85,6 +85,13 @@ indicate_indicator_message_finalize (GObject *object) G_OBJECT_CLASS (indicate_indicator_message_parent_class)->finalize (object); } +/** + indicate_indicator_message_new: + + Builds a new indicator message object using #g_object_new. + + Return value: A pointer to a new #IndicateIndicatorMessage object. +*/ static const gchar * get_indicator_type (IndicateIndicator * indicator) { diff --git a/libindicate/indicator-message.h b/libindicate/indicator-message.h index 0910477..76273c6 100644 --- a/libindicate/indicator-message.h +++ b/libindicate/indicator-message.h @@ -47,19 +47,46 @@ G_BEGIN_DECLS typedef struct _IndicateIndicatorMessage IndicateIndicatorMessage; typedef struct _IndicateIndicatorMessageClass IndicateIndicatorMessageClass; -struct _IndicateIndicatorMessageClass -{ -IndicateIndicatorClass parent_class; +/** + IndicateIndicatorMessageClass: + @parent_class: Parent Class + + Subclass of #IndicateIndicator with no new functions or signals. +*/ +struct _IndicateIndicatorMessageClass { + IndicateIndicatorClass parent_class; }; -struct _IndicateIndicatorMessage -{ -IndicateIndicator parent; +/** + IndicateIndicatorMessage: + + A class to represent indicators who's 'type' is "message". These + are basically indicators that represent messages from humans to + humans via computers. Things like instance messages, micro blogging + entries or e-mails. All of these qualify as messages. + + TODO: This should include a list of properties that are supported. +*/ +struct _IndicateIndicatorMessage { + IndicateIndicator parent; }; GType indicate_indicator_message_get_type (void); IndicateIndicatorMessage * indicate_indicator_message_new (void); +/** + SECTION:indicator-message + @short_description: A representation of human generated messages + @stability: Unstable + @include: libindicate/indicator-message.h + + The message indicators represent messages that come from humans + to humans using computers. They come in all different forms with + various different interaction protocols, but they all want the human + at the computer to interact back with the human that sent the + message. +*/ + G_END_DECLS #endif diff --git a/libindicate/indicator.c b/libindicate/indicator.c index dfcba67..76eb616 100644 --- a/libindicate/indicator.c +++ b/libindicate/indicator.c @@ -76,6 +76,14 @@ indicate_indicator_class_init (IndicateIndicatorClass * class) gobj->finalize = indicate_indicator_finalize; + /** + 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 + 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 +91,15 @@ indicate_indicator_class_init (IndicateIndicatorClass * class) NULL, NULL, g_cclosure_marshal_VOID__VOID, 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), G_SIGNAL_RUN_LAST, @@ -90,6 +107,15 @@ indicate_indicator_class_init (IndicateIndicatorClass * class) NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0); + /** + 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), G_SIGNAL_RUN_LAST, @@ -97,6 +123,16 @@ indicate_indicator_class_init (IndicateIndicatorClass * class) NULL, NULL, g_cclosure_marshal_VOID__VOID, 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), G_SIGNAL_RUN_LAST, @@ -145,6 +181,21 @@ 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: + + Builds a new indicator object using g_object_new(). + + Return value: A pointer to a new #IndicateIndicator object. +*/ IndicateIndicator * indicate_indicator_new (void) { @@ -152,6 +203,14 @@ 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 +230,13 @@ 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 +252,14 @@ 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 +268,15 @@ 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 +285,15 @@ 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 +307,14 @@ 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 +327,18 @@ 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 +350,17 @@ 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 +394,17 @@ 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 + @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 + 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) { @@ -282,6 +416,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) { @@ -293,6 +437,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) { 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__ */ diff --git a/libindicate/server.c b/libindicate/server.c index d42fe61..cd8b33a 100644 --- a/libindicate/server.c +++ b/libindicate/server.c @@ -163,6 +163,17 @@ indicate_server_class_init (IndicateServerClass * class) gobj->set_property = set_property; gobj->get_property = get_property; + /** + IndicateServer::indicator-added: + @arg0: The #IndicateServer object + @arg1: The #IndicateIndicator ID number + @arg2: The type of the indicator + + Emitted every time that a new indicator is made visible to + the world. This results in a signal on DBus. + + Can be emitted by subclasses using indicate_server_emit_indicator_added() + */ signals[INDICATOR_ADDED] = g_signal_new(INDICATE_SERVER_SIGNAL_INDICATOR_ADDED, G_TYPE_FROM_CLASS (class), G_SIGNAL_RUN_LAST, @@ -170,6 +181,17 @@ indicate_server_class_init (IndicateServerClass * class) NULL, NULL, g_cclosure_marshal_VOID__UINT_POINTER, G_TYPE_NONE, 2, G_TYPE_UINT, G_TYPE_STRING); + /** + IndicateServer::indicator-removed: + @arg0: The #IndicateServer object + @arg1: The #IndicateIndicator ID number + @arg2: The type of the indicator + + Emitted every time that a new indicator is made invisible to + the world. This results in a signal on DBus. + + Can be emitted by subclasses using indicate_server_emit_indicator_removed() + */ signals[INDICATOR_REMOVED] = g_signal_new(INDICATE_SERVER_SIGNAL_INDICATOR_REMOVED, G_TYPE_FROM_CLASS (class), G_SIGNAL_RUN_LAST, @@ -177,6 +199,17 @@ indicate_server_class_init (IndicateServerClass * class) NULL, NULL, g_cclosure_marshal_VOID__UINT_POINTER, G_TYPE_NONE, 2, G_TYPE_UINT, G_TYPE_STRING); + /** + IndicateServer::indicator-modified: + @arg0: The #IndicateServer object + @arg1: The #IndicateIndicator ID number + @arg2: The name of the property modified + + Emitted every time that a property on an indicator changes + and it is visible to the world. This results in a signal on DBus. + + Can be emitted by subclasses using indicate_server_emit_indicator_modified() + */ signals[INDICATOR_MODIFIED] = g_signal_new(INDICATE_SERVER_SIGNAL_INDICATOR_MODIFIED, G_TYPE_FROM_CLASS (class), G_SIGNAL_RUN_LAST, @@ -184,6 +217,15 @@ indicate_server_class_init (IndicateServerClass * class) NULL, NULL, g_cclosure_marshal_VOID__UINT_POINTER, G_TYPE_NONE, 2, G_TYPE_UINT, G_TYPE_STRING); + /** + IndicateServer::server-show: + @arg0: The #IndicateServer object + @arg1: The type of the server + + Emitted when a server comes onto DBus by being shown. This + is typically when listeners start reacting to the application's + indicators. This results in a signal on DBus. + */ signals[SERVER_SHOW] = g_signal_new(INDICATE_SERVER_SIGNAL_SERVER_SHOW, G_TYPE_FROM_CLASS (class), G_SIGNAL_RUN_LAST, @@ -191,6 +233,14 @@ indicate_server_class_init (IndicateServerClass * class) NULL, NULL, g_cclosure_marshal_VOID__POINTER, G_TYPE_NONE, 1, G_TYPE_STRING); + /** + IndicateServer::server-hide: + @arg0: The #IndicateServer object + @arg1: The type of the server + + Emitted when a server removes itself from DBus. This results + in a signal on DBus. + */ signals[SERVER_HIDE] = g_signal_new(INDICATE_SERVER_SIGNAL_SERVER_HIDE, G_TYPE_FROM_CLASS (class), G_SIGNAL_RUN_LAST, @@ -198,6 +248,16 @@ indicate_server_class_init (IndicateServerClass * class) NULL, NULL, g_cclosure_marshal_VOID__POINTER, G_TYPE_NONE, 1, G_TYPE_STRING); + /** + IndicateServer::server-display: + @arg0: The #IndicateServer object + + Emitted when a listener signals that the server itself should be + displayed. This signal is caused by a user clicking on the application + item in the Messaging Menu. This signal is emitted by DBus. + + Can be emitted by subclasses using indicate_server_emit_server_display() + */ signals[SERVER_DISPLAY] = g_signal_new(INDICATE_SERVER_SIGNAL_SERVER_DISPLAY, G_TYPE_FROM_CLASS (class), G_SIGNAL_RUN_LAST, @@ -205,6 +265,14 @@ indicate_server_class_init (IndicateServerClass * class) NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0); + /** + IndicateServer::interest-added: + @arg0: The #IndicateServer object + @arg1: The interest that was added from #IndicateInterests + + Emitted when a listener signals that they are interested in + this server for a particular reason. This signal is emitted by DBus. + */ signals[INTEREST_ADDED] = g_signal_new(INDICATE_SERVER_SIGNAL_INTEREST_ADDED, G_TYPE_FROM_CLASS (class), G_SIGNAL_RUN_LAST, @@ -212,6 +280,14 @@ indicate_server_class_init (IndicateServerClass * class) NULL, NULL, g_cclosure_marshal_VOID__UINT, G_TYPE_NONE, 1, G_TYPE_UINT); + /** + IndicateServer::interest-removed: + @arg0: The #IndicateServer object + @arg1: The interest that was removed from #IndicateInterests + + Emitted when a listener signals that they are no longer interested in + this server for a particular reason. This signal is emitted by DBus. + */ signals[INTEREST_REMOVED] = g_signal_new(INDICATE_SERVER_SIGNAL_INTEREST_REMOVED, G_TYPE_FROM_CLASS (class), G_SIGNAL_RUN_LAST, @@ -366,7 +442,17 @@ indicate_server_error_quark (void) return quark; } +/** + indicate_server_show: + @server: The #IndicateServer to be shown + This function exports the object onto DBus and shows it + to the world. This will be the start of it receiving external + signals from DBus. It is likely that, if there are listeners + running, there will several #IndicateServer::interest-added + signals coming shortly after this function. This function + emits the #IndicateServer::server-added signal across the bus. +*/ void indicate_server_show (IndicateServer * server) { @@ -403,6 +489,16 @@ indicate_server_show (IndicateServer * server) return; } +/** + indicate_server_hide: + @server: The #IndicateServer to hide. + + This function hides the server from DBus so that it does + not get signals anymore. This causes the signal #IndicateServer::server-hide + to be sent across the bus for all listeners. Also internally + it will signal #IndicateServer::interest-removed for all the + interests that were currently set for this server. +*/ void indicate_server_hide (IndicateServer * server) { @@ -610,6 +706,16 @@ indicator_modified_cb (IndicateIndicator * indicator, gchar * property, Indicate g_signal_emit(server, signals[INDICATOR_MODIFIED], 0, indicate_indicator_get_id(indicator), property, TRUE); } +/** + indicate_server_add_indicator: + @server: The #IndicateServer to add the #IndicateIndictor to. + @indicator: The #IndicateIndicator to add. + + This function adds an indicator @indicator to the list that are + watched by the server @server. This means that signals that are + emitted by the indicator will be picked up and passed via DBus onto + listeners of the application. +*/ void indicate_server_add_indicator (IndicateServer * server, IndicateIndicator * indicator) { @@ -633,6 +739,14 @@ indicate_server_add_indicator (IndicateServer * server, IndicateIndicator * indi return; } +/** + indicate_server_remove_indicator: + @server: The #IndicateServer to remove the #IndicateIndictor from. + @indicator: The #IndicateIndicator to remove. + + Removes an indicator @indicator from being watched by the server @server + so it's signals are no longer watched and set over DBus. +*/ void indicate_server_remove_indicator (IndicateServer * server, IndicateIndicator * indicator) { @@ -663,6 +777,15 @@ indicate_server_set_dbus_object (const gchar * obj) return; } +/** + indicate_server_set_desktop_file: + @server: The #IndicateServer to set the type of + @path: The new desktop file representing the server + + This is a convience function to set the #IndicateServer:desktop + property of the @server object. The property can also be set + via traditional means, but this one is easier to read. +*/ void indicate_server_set_desktop_file (IndicateServer * server, const gchar * path) { @@ -673,6 +796,15 @@ indicate_server_set_desktop_file (IndicateServer * server, const gchar * path) return; } +/** + indicate_server_set_type: + @server: The #IndicateServer to set the type of + @type: The new type of the server + + This is a convience function to set the #IndicateServer:type + property of the @server object. The property can also be set + via traditional means, but this one is easier to read. +*/ void indicate_server_set_type (IndicateServer * server, const gchar * type) { @@ -685,6 +817,17 @@ indicate_server_set_type (IndicateServer * server, const gchar * type) static IndicateServer * default_indicate_server = NULL; +/** + indicate_server_ref_default: + + This function will return a reference to the default #IndicateServer + reference if there is one, or it will create one if one had not + previously been created. It is recommended that all applications + use this function to create a #IndicateServer as it ensure that there + is only one per application. + + Return value: A reference to the default #IndicateServer instance. +*/ IndicateServer * indicate_server_ref_default (void) { @@ -699,6 +842,16 @@ indicate_server_ref_default (void) return default_indicate_server; } +/** + indicate_server_set_default: + @server: The #IndicateServer that should be used + + This function is used to set the default #IndicateServer that will + be used when creating #IndicateIndicators or for anyone else that + calls indicate_server_ref_default(). Typically this is just an + instance of #IndicateServer but applications that create a subclass + of #IndicateServer should set this as well. +*/ void indicate_server_set_default (IndicateServer * server) { @@ -1103,6 +1256,15 @@ _indicate_server_show_indicator_to_user (IndicateServer * server, guint id, GErr return TRUE; } +/** + indicate_server_get_next_id: + @server: The #IndicateServer the ID will be on + + Returns the next available unused ID that an indicator + can have. + + Return value: A valid indicator ID. +*/ guint indicate_server_get_next_id (IndicateServer * server) { @@ -1207,6 +1369,17 @@ _indicate_server_remove_interest (IndicateServer * server, gchar * interest, DBu return FALSE; } +/** + indicate_server_check_interest: + @server: The #IndicateServer being checked + @interest: Which interest type we're checking for + + This function looks at all the interest that various listeners + have specified that they have for this server and returns whether + there is a listener that has the interest specified in @interest. + + Return value: %TRUE if a listener as the interest otherwise %FALSE +*/ gboolean indicate_server_check_interest (IndicateServer * server, IndicateInterests interest) { @@ -1221,6 +1394,16 @@ indicate_server_check_interest (IndicateServer * server, IndicateInterests inter } /* Signal emission functions for sub-classes of the server */ + +/** + indicate_server_emit_indicator_added: + @server: The #IndicateServer being represented + @id: The ID of the indicator being added + @type: The type of the indicator + + This function emits the #IndicateServer::indicator-added signal and is + used by subclasses. +*/ void indicate_server_emit_indicator_added (IndicateServer *server, guint id, const gchar *type) { @@ -1230,6 +1413,15 @@ indicate_server_emit_indicator_added (IndicateServer *server, guint id, const gc g_signal_emit(server, signals[INDICATOR_ADDED], 0, id, type); } +/** + indicate_server_emit_indicator_removed: + @server: The #IndicateServer being represented + @id: The ID of the indicator being removed + @type: The type of the indicator + + This function emits the #IndicateServer::indicator-removed signal and is + used by subclasses. +*/ void indicate_server_emit_indicator_removed (IndicateServer *server, guint id, const gchar *type) { @@ -1239,6 +1431,15 @@ indicate_server_emit_indicator_removed (IndicateServer *server, guint id, const g_signal_emit(server, signals[INDICATOR_REMOVED], 0, id, type); } +/** + indicate_server_emit_indicator_modified: + @server: The #IndicateServer being represented + @id: The ID of the indicator with the modified property + @property: The name of the property being modified + + This function emits the #IndicateServer::indicator-modified signal and is + used by subclasses. +*/ void indicate_server_emit_indicator_modified (IndicateServer *server, guint id, const gchar *property) { @@ -1248,6 +1449,13 @@ indicate_server_emit_indicator_modified (IndicateServer *server, guint id, const g_signal_emit(server, signals[INDICATOR_MODIFIED], 0, id, property); } +/** + indicate_server_emit_server_display: + @server: The #IndicateServer being displayed + + This function emits the #IndicateServer::server-display signal and is + used by subclasses. +*/ void indicate_server_emit_server_display (IndicateServer *server) { diff --git a/libindicate/server.h b/libindicate/server.h index cfb4334..2a300e2 100644 --- a/libindicate/server.h +++ b/libindicate/server.h @@ -57,11 +57,63 @@ G_BEGIN_DECLS #define INDICATE_SERVER_SIGNAL_INTEREST_ADDED "interest-added" #define INDICATE_SERVER_SIGNAL_INTEREST_REMOVED "interest-removed" +/** + IndicateServer: + + This is the object that represents the overall connection + between this application and DBus. It acts as the proxy for + incomming DBus calls and also sends the appropriate signals + on DBus for events happening on other objects locally. It + provides some settings that effection how the application as + a whole is perceived by listeners of the indicator protocol. +*/ typedef struct _IndicateServer IndicateServer; struct _IndicateServer { GObject parent; }; +/** + IndicateServerClass: + @parent: Parent Class + @indicator_added: Slot for #IndicateServer::indicator-added. + @indicator_removed: Slot for #IndicateServer::indicator-removed. + @indicator_modified: Slot for #IndicateServer::indicator-modified. + @server_show: Slot for #IndicateServer::server-show. + @server_hide: Slot for #IndicateServer::server-hide. + @server_display: Slot for #IndicateServer::server-display. + @interest_added: Slot for #IndicateServer::interest-added. + @interest_removed: Slot for #IndicateServer::interest-removed. + @get_indicator_count: Returns the number of indicators that are visible + on the bus. Hidden indicators should not be counted. + @get_indicator_count_by_type: Returns the number of indicators that are + of a given type and visible on the bus. + @get_indicator_list: List all of the indicators that are visible. + @get_indicator_list_by_type: List all of the indicators of a given + type that are visible. + @get_indicator_property: Get a property from a particular indicator. + @get_indicator_property_group: Get the values for a set of properties + as an array of entries, returning an array as well. + @get_indicator_properties: Get a list of all the properties that are + on a particular indicator. + @show_indicator_to_user: Respond to someone on the bus asking to show + a particular indicator to the user. + @get_next_id: Get the next unused indicator ID. + @show_interest: React to someone signifying that they are interested + in this server. + @remove_interest: Someone on the bus is no longer interest in this + server, remove it's interest. + @check_interest: Check to see if anyone on the bus is interested in this + server for a particular feature. + @indicate_server_reserved1: Reserved for future use + @indicate_server_reserved2: Reserved for future use + @indicate_server_reserved3: Reserved for future use + @indicate_server_reserved4: Reserved for future use + + All of the functions and signals that make up the server class + including those that are public API to the application and those + that are public API to all of DBus. Subclasses may need to + implement a large portion of these. +*/ typedef struct _IndicateServerClass IndicateServerClass; struct _IndicateServerClass { GObjectClass parent; @@ -134,6 +186,35 @@ void indicate_server_emit_indicator_removed (IndicateServer *server, guint id, c void indicate_server_emit_indicator_modified (IndicateServer *server, guint id, const gchar *property); void indicate_server_emit_server_display (IndicateServer *server); +/** + SECTION:server + @short_description: The representation of the application on DBus. + @stability: Unstable + @include: libindicate/server.h + + The server object is the object that provides the functions on + to DBus for other applications to call. It does this by implementing + the DBus indicator spec, but it also allows for subclassing so that + subclasses don't have to worry about the DBus-isms as much as + the functionality that they're trying to express. + + For simple applications there is limited need to set anything + more than the desktop file and the type of the server using + indicate_server_set_desktop_file() and indicate_server_set_type(). + Each of these function sets the respective value and expresses + it in a way that other applications on the bus can read it. + + More advanced applications might find the need to subclass the + #IndicateServer object and make their own. This is likely the + case where applications have complex data stores that they don't + want to turn into a large set of #GObjects that can take up a + significant amount of memory in the program. + + In general, it is recommended that application authors go with + the high memory path first, and then optimize by implementing + their server on a second pass. +*/ + G_END_DECLS #endif /* INDICATE_SERVER_H_INCLUDED__ */ |