From 15720aae214633691ed4a940dd1b7dcb313ea0ca Mon Sep 17 00:00:00 2001 From: Ted Gould Date: Thu, 30 Apr 2009 20:37:52 -0500 Subject: Basic signals docs. --- libindicate/server.c | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) (limited to 'libindicate/server.c') diff --git a/libindicate/server.c b/libindicate/server.c index d42fe61..e8dad3f 100644 --- a/libindicate/server.c +++ b/libindicate/server.c @@ -163,6 +163,12 @@ indicate_server_class_init (IndicateServerClass * class) gobj->set_property = set_property; gobj->get_property = get_property; + /** + IndicateServer::indicator-added: + + Emitted every time that a new indicator is made visible to + the world. This results in a signal on DBus. + */ signals[INDICATOR_ADDED] = g_signal_new(INDICATE_SERVER_SIGNAL_INDICATOR_ADDED, G_TYPE_FROM_CLASS (class), G_SIGNAL_RUN_LAST, @@ -170,6 +176,12 @@ 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: + + Emitted every time that a new indicator is made invisible to + the world. This results in a signal on DBus. + */ signals[INDICATOR_REMOVED] = g_signal_new(INDICATE_SERVER_SIGNAL_INDICATOR_REMOVED, G_TYPE_FROM_CLASS (class), G_SIGNAL_RUN_LAST, @@ -177,6 +189,12 @@ 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: + + Emitted every time that a property on an indicator changes + and it is visible to the world. This results in a signal on DBus. + */ signals[INDICATOR_MODIFIED] = g_signal_new(INDICATE_SERVER_SIGNAL_INDICATOR_MODIFIED, G_TYPE_FROM_CLASS (class), G_SIGNAL_RUN_LAST, @@ -184,6 +202,13 @@ 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: + + 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 +216,12 @@ indicate_server_class_init (IndicateServerClass * class) NULL, NULL, g_cclosure_marshal_VOID__POINTER, G_TYPE_NONE, 1, G_TYPE_STRING); + /** + IndicateServer::server-hide: + + 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 +229,13 @@ indicate_server_class_init (IndicateServerClass * class) NULL, NULL, g_cclosure_marshal_VOID__POINTER, G_TYPE_NONE, 1, G_TYPE_STRING); + /** + IndicateServer::server-display: + + 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. + */ signals[SERVER_DISPLAY] = g_signal_new(INDICATE_SERVER_SIGNAL_SERVER_DISPLAY, G_TYPE_FROM_CLASS (class), G_SIGNAL_RUN_LAST, @@ -205,6 +243,12 @@ indicate_server_class_init (IndicateServerClass * class) NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0); + /** + IndicateServer::interest-added: + + 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 +256,12 @@ indicate_server_class_init (IndicateServerClass * class) NULL, NULL, g_cclosure_marshal_VOID__UINT, G_TYPE_NONE, 1, G_TYPE_UINT); + /** + IndicateServer::interest-removed: + + 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, -- cgit v1.2.3 From f64bd73788470bb55a2a1060b7fea815d769d0d4 Mon Sep 17 00:00:00 2001 From: Ted Gould Date: Thu, 30 Apr 2009 20:53:10 -0500 Subject: Adding in arguments on the signal docs. --- libindicate/server.c | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) (limited to 'libindicate/server.c') diff --git a/libindicate/server.c b/libindicate/server.c index e8dad3f..6cc6f34 100644 --- a/libindicate/server.c +++ b/libindicate/server.c @@ -165,9 +165,14 @@ indicate_server_class_init (IndicateServerClass * class) /** 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), @@ -178,9 +183,14 @@ indicate_server_class_init (IndicateServerClass * class) 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), @@ -191,9 +201,14 @@ indicate_server_class_init (IndicateServerClass * class) 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), @@ -204,6 +219,8 @@ indicate_server_class_init (IndicateServerClass * class) 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 @@ -218,6 +235,8 @@ indicate_server_class_init (IndicateServerClass * class) 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. @@ -231,10 +250,13 @@ indicate_server_class_init (IndicateServerClass * class) 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), @@ -245,6 +267,8 @@ indicate_server_class_init (IndicateServerClass * class) 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. @@ -258,6 +282,8 @@ indicate_server_class_init (IndicateServerClass * class) 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. -- cgit v1.2.3 From 51f63e11e0e39400d5be18a303a18989a7d67ea3 Mon Sep 17 00:00:00 2001 From: Ted Gould Date: Thu, 30 Apr 2009 21:42:39 -0500 Subject: Documenting most of the public visible functions --- libindicate/server.c | 134 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 133 insertions(+), 1 deletion(-) (limited to 'libindicate/server.c') diff --git a/libindicate/server.c b/libindicate/server.c index 6cc6f34..cec9bd2 100644 --- a/libindicate/server.c +++ b/libindicate/server.c @@ -442,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) { @@ -479,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) { @@ -686,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) { @@ -709,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) { @@ -739,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 + @type: 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) { @@ -749,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) { @@ -761,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) { @@ -775,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) { @@ -1179,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) { @@ -1283,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) { @@ -1297,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) { @@ -1306,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) { @@ -1315,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 + @proprerty: 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) { @@ -1324,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) { -- cgit v1.2.3 From 3810da4bb215f815f9528e9fa7145de9c99efbff Mon Sep 17 00:00:00 2001 From: Ted Gould Date: Thu, 30 Apr 2009 21:45:19 -0500 Subject: Fixing some documentation bugs. --- libindicate/indicator-message.h | 1 + libindicate/server.c | 4 ++-- libindicate/server.h | 2 +- 3 files changed, 4 insertions(+), 3 deletions(-) (limited to 'libindicate/server.c') diff --git a/libindicate/indicator-message.h b/libindicate/indicator-message.h index 62a41b7..76273c6 100644 --- a/libindicate/indicator-message.h +++ b/libindicate/indicator-message.h @@ -49,6 +49,7 @@ typedef struct _IndicateIndicatorMessageClass IndicateIndicatorMessageClass; /** IndicateIndicatorMessageClass: + @parent_class: Parent Class Subclass of #IndicateIndicator with no new functions or signals. */ diff --git a/libindicate/server.c b/libindicate/server.c index cec9bd2..cd8b33a 100644 --- a/libindicate/server.c +++ b/libindicate/server.c @@ -780,7 +780,7 @@ indicate_server_set_dbus_object (const gchar * obj) /** indicate_server_set_desktop_file: @server: The #IndicateServer to set the type of - @type: The new desktop file representing the server + @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 @@ -1435,7 +1435,7 @@ indicate_server_emit_indicator_removed (IndicateServer *server, guint id, const indicate_server_emit_indicator_modified: @server: The #IndicateServer being represented @id: The ID of the indicator with the modified property - @proprerty: The name of the property being modified + @property: The name of the property being modified This function emits the #IndicateServer::indicator-modified signal and is used by subclasses. diff --git a/libindicate/server.h b/libindicate/server.h index 820e641..2a300e2 100644 --- a/libindicate/server.h +++ b/libindicate/server.h @@ -85,7 +85,7 @@ struct _IndicateServer { @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_indciator_count_by_type: Returns the number of indicators that are + @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 -- cgit v1.2.3