aboutsummaryrefslogtreecommitdiff
path: root/libindicate
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
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')
-rw-r--r--libindicate/indicator-message.c7
-rw-r--r--libindicate/indicator-message.h39
-rw-r--r--libindicate/indicator.c155
-rw-r--r--libindicate/indicator.h64
-rw-r--r--libindicate/server.c208
-rw-r--r--libindicate/server.h81
6 files changed, 548 insertions, 6 deletions
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__ */