|
|
|
libindicate Reference Manual | |
|---|---|---|---|---|
| Top | Description | Object Hierarchy | Properties | Signals | ||||
#include <libindicate/server.h> struct IndicateServer; struct IndicateServerClass; void indicate_server_add_indicator (IndicateServer *server,IndicateIndicator *indicator); gboolean indicate_server_check_interest (IndicateServer *server,IndicateInterests interest); guint indicate_server_get_next_id (IndicateServer *server); void indicate_server_hide (IndicateServer *server); IndicateServer * indicate_server_ref_default (void); void indicate_server_remove_indicator (IndicateServer *server,IndicateIndicator *indicator); void indicate_server_set_default (IndicateServer *server); void indicate_server_set_desktop_file (IndicateServer *server,const gchar *path); void indicate_server_set_type (IndicateServer *server,const gchar *type); void indicate_server_show (IndicateServer *server);
"count" guint : Read / Write "desktop" gchar* : Read / Write "icon-theme" gchar* : Read / Write "menu" gchar* : Read "path" gchar* : Read / Write / Construct Only "type" gchar* : Read / Write
"indicator-delete" :Run Last"indicator-modified" :Run Last"indicator-new" :Run Last"interest-added" :Run Last"interest-removed" :Run Last"max-indicators-changed" :Run Last"server-count-changed" :Run Last"server-display" :Run Last"server-hide" :Run Last"server-show" :Run Last
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.
struct 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.
struct IndicateServerClass {
GObjectClass parent;
/* Signals */
void (* indicator_added) (IndicateServer * server, guint id);
void (* indicator_removed) (IndicateServer * server, guint id);
void (* indicator_modified) (IndicateServer * server, guint id, gchar * property);
void (* server_show) (IndicateServer * server, gchar * type);
void (* server_hide) (IndicateServer * server, gchar * type);
void (* server_display) (IndicateServer * server, guint timestamp);
void (* interest_added) (IndicateServer * server, IndicateInterests interest);
void (* interest_removed) (IndicateServer * server, IndicateInterests interest);
void (* max_indicators_changed) (IndicateServer * server, gint max);
void (* server_count_changed) (IndicateServer * server, guint count);
/* Virtual Functions */
gboolean (*get_indicator_count) (IndicateServer * server, guint * count, GError **error);
indicate_server_get_indicator_list_slot_t get_indicator_list;
gboolean (*get_indicator_property) (IndicateServer * server, guint id, gchar * property, GVariant ** value, GError **error);
indicate_server_get_indicator_property_group_slot_t get_indicator_property_group;
indicate_server_get_indicator_properties_slot_t get_indicator_properties;
gboolean (*show_indicator_to_user) (IndicateServer * server, guint id, guint timestamp, GError ** error);
gboolean (*indicator_displayed) (IndicateServer * server, const gchar * sender, guint id, gboolean displayed, GError ** error);
guint (*get_next_id) (IndicateServer * server);
gboolean (*show_interest) (IndicateServer * server, const gchar * sender, IndicateInterests interest);
gboolean (*remove_interest) (IndicateServer * server, const gchar * sender, IndicateInterests interest);
gboolean (*check_interest) (IndicateServer * server, IndicateInterests interest);
gboolean (*max_indicators_set) (IndicateServer * server, const gchar * sender, gint max);
gint (*max_indicators_get) (IndicateServer * server);
/* Reserver for future use */
void (*indicate_server_reserved1)(void);
void (*indicate_server_reserved2)(void);
void (*indicate_server_reserved3)(void);
void (*indicate_server_reserved4)(void);
};
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.
| Parent Class | |
| Slot for "indicator-added". | |
| Slot for "indicator-removed". | |
| Slot for "indicator-modified". | |
| Slot for "server-show". | |
| Slot for "server-hide". | |
| Slot for "server-display". | |
| Slot for "interest-added". | |
| Slot for "interest-removed". | |
| Slot for "max-indicators-changed". | |
| Slot for "server-count-changed". | |
| Returns the number of indicators that are visible on the bus. Hidden indicators should not be counted. | |
indicate_server_get_indicator_list_slot_t |
List all of the indicators that are visible. |
| Get a property from a particular indicator. | |
indicate_server_get_indicator_property_group_slot_t |
Get the values for a set of properties as an array of entries, returning an array as well. |
indicate_server_get_indicator_properties_slot_t |
Get a list of all the properties that are on a particular indicator. |
| Respond to someone on the bus asking to show a particular indicator to the user. | |
| An indicator has been visualized by the listener or it hasn't. This function tracks that. | |
| Get the next unused indicator ID. | |
| React to someone signifying that they are interested in this server. | |
| Someone on the bus is no longer interest in this server, remove it's interest. | |
| Check to see if anyone on the bus is interested in this server for a particular feature. | |
| Set the maximum number of indicators that a given listener can display. | |
| Gets the maximum number of indicators from all listeners that care about this server. | |
| Reserved for future use | |
| Reserved for future use | |
| Reserved for future use | |
| Reserved for future use |
void indicate_server_add_indicator (IndicateServer *server,IndicateIndicator *indicator);
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.
|
The IndicateServer to add the IndicateIndictor to. |
|
The IndicateIndicator to add. |
gboolean indicate_server_check_interest (IndicateServer *server,IndicateInterests interest);
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.
|
The IndicateServer being checked |
|
Which interest type we're checking for |
Returns : |
TRUE if a listener as the interest otherwise FALSE
|
guint indicate_server_get_next_id (IndicateServer *server);
Returns the next available unused ID that an indicator can have.
|
The IndicateServer the ID will be on |
Returns : |
A valid indicator ID. |
void indicate_server_hide (IndicateServer *server);
This function hides the server from DBus so that it does not get signals anymore. This causes the signal "server-hide" to be sent across the bus for all listeners. Also internally it will signal "interest-removed" for all the interests that were currently set for this server.
|
The IndicateServer to hide. |
IndicateServer * indicate_server_ref_default (void);
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.
Returns : |
A reference to the default IndicateServer instance. [transfer full] |
void indicate_server_remove_indicator (IndicateServer *server,IndicateIndicator *indicator);
Removes an indicator indicator from being watched by the server server
so it's signals are no longer watched and set over DBus.
|
The IndicateServer to remove the IndicateIndictor from. |
|
The IndicateIndicator to remove. |
void indicate_server_set_default (IndicateServer *server);
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.
|
The IndicateServer that should be used |
void indicate_server_set_desktop_file (IndicateServer *server,const gchar *path);
This is a convience function to set the "desktop"
property of the server object. The property can also be set
via traditional means, but this one is easier to read.
|
The IndicateServer to set the type of |
|
The new desktop file representing the server |
void indicate_server_set_type (IndicateServer *server,const gchar *type);
This is a convience function to set the "type"
property of the server object. The property can also be set
via traditional means, but this one is easier to read.
|
The IndicateServer to set the type of |
|
The new type of the server |
void indicate_server_show (IndicateServer *server);
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 "interest-added" signals coming shortly after this function. This function emits the "server-added" signal across the bus.
|
The IndicateServer to be shown |
"count" property "count" guint : Read / Write
A number reprsenting the number of items in a server.
Default value: 0
"desktop" property "desktop" gchar* : Read / Write
The desktop file representing this server.
Default value: ""
"icon-theme" property "icon-theme" gchar* : Read / Write
The Custom Icon Theme Name to use when displaying this Server.
Default value: ""
"menu" property "menu" gchar* : Read
The DBus Object path to an object with a dbusmenu interface on it.
Default value: ""
"path" property "path" gchar* : Read / Write / Construct Only
DBus path for the server object.
Default value: "/com/canonical/indicate"
"indicator-delete" signalvoid user_function (IndicateServer *indicateserver,
guint arg1,
gpointer user_data) : Run Last
|
the object which received the signal. |
|
user data set when the signal handler was connected. |
"indicator-modified" signalvoid user_function (IndicateServer *arg0,
guint arg1,
gchar *arg2,
gpointer user_data) : Run Last
Emitted every time that a property on an indicator changes and it is visible to the world. This results in a signal on DBus.
|
The IndicateServer object |
|
The IndicateIndicator ID number |
|
The name of the property modified |
|
user data set when the signal handler was connected. |
"indicator-new" signalvoid user_function (IndicateServer *indicateserver,
guint arg1,
gpointer user_data) : Run Last
|
the object which received the signal. |
|
user data set when the signal handler was connected. |
"interest-added" signalvoid user_function (IndicateServer *arg0,
guint arg1,
gpointer user_data) : Run Last
Emitted when a listener signals that they are interested in this server for a particular reason. This signal is emitted by DBus.
|
The IndicateServer object |
|
The interest that was added from IndicateInterests |
|
user data set when the signal handler was connected. |
"interest-removed" signalvoid user_function (IndicateServer *arg0,
guint arg1,
gpointer user_data) : Run Last
Emitted when a listener signals that they are no longer interested in this server for a particular reason. This signal is emitted by DBus.
note This signal is also emitted after a timeout when the object
is created with arg1 set to INDICATOR_INTREST_NONE if no one has
shown any interest in the server.
|
The IndicateServer object |
|
The interest that was removed from IndicateInterests |
|
user data set when the signal handler was connected. |
"max-indicators-changed" signalvoid user_function (IndicateServer *arg0,
gint arg1,
gpointer user_data) : Run Last
Emitted when a listener either specifies their max number to be higher, or at all. The default is -1 or infinite.
|
The IndicateServer object |
|
The new max number of indicators |
|
user data set when the signal handler was connected. |
"server-count-changed" signalvoid user_function (IndicateServer *arg0,
guint arg1,
gpointer user_data) : Run Last
Emitted when the count property of the server changes to a new value.
|
The IndicateServer object |
|
The count variable on the server changed. |
|
user data set when the signal handler was connected. |
"server-display" signalvoid user_function (IndicateServer *arg0,
guint arg1,
gpointer user_data) : Run Last
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.
|
The IndicateServer object |
|
Timestamp of the show event |
|
user data set when the signal handler was connected. |
"server-hide" signalvoid user_function (IndicateServer *arg0,
gchar *arg1,
gpointer user_data) : Run Last
Emitted when a server removes itself from DBus. This results in a signal on DBus.
|
The IndicateServer object |
|
The type of the server |
|
user data set when the signal handler was connected. |
"server-show" signalvoid user_function (IndicateServer *arg0,
gchar *arg1,
gpointer user_data) : Run Last
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.
|
The IndicateServer object |
|
The type of the server |
|
user data set when the signal handler was connected. |