![]() |
![]() |
![]() |
libawn Reference Manual | ![]() |
---|---|---|---|---|
awn-config-clientawn-config-client — The configuration API for both Awn proper and
Awn applets.
|
AwnConfigClient; #define AWN_CONFIG_CLIENT (obj) AwnConfigClientNotifyEntry; void (*AwnConfigClientNotifyFunc) (AwnConfigClientNotifyEntry *entry, gpointer data); #define AWN_CONFIG_CLIENT_DEFAULT_GROUP enum AwnConfigValueType; enum AwnConfigListType; AwnConfigClient* awn_config_client_new (); AwnConfigClient* awn_config_client_new_for_applet (gchar *name, gchar *uid); void awn_config_client_clear (AwnConfigClient *client, GError **err); void awn_config_client_ensure_group (AwnConfigClient *client, const gchar *group); void awn_config_client_notify_add (AwnConfigClient *client, const gchar *group, const gchar *key, AwnConfigClientNotifyFunc callback, gpointer data); gboolean awn_config_client_entry_exists (AwnConfigClient *client, const gchar *group, const gchar *key); gboolean awn_config_client_get_bool (AwnConfigClient *client, const gchar *group, const gchar *key, GError **err); void awn_config_client_set_bool (AwnConfigClient *client, const gchar *group, const gchar *key, gboolean value, GError **err); gfloat awn_config_client_get_float (AwnConfigClient *client, const gchar *group, const gchar *key, GError **err); void awn_config_client_set_float (AwnConfigClient *client, const gchar *group, const gchar *key, gfloat value, GError **err); gint awn_config_client_get_int (AwnConfigClient *client, const gchar *group, const gchar *key, GError **err); void awn_config_client_set_int (AwnConfigClient *client, const gchar *group, const gchar *key, gint value, GError **err); gchar* awn_config_client_get_string (AwnConfigClient *client, const gchar *group, const gchar *key, GError **err); void awn_config_client_set_string (AwnConfigClient *client, const gchar *group, const gchar *key, gchar *value, GError **err); GSList* awn_config_client_get_list (AwnConfigClient *client, const gchar *group, const gchar *key, AwnConfigListType list_type, GError **err); void awn_config_client_set_list (AwnConfigClient *client, const gchar *group, const gchar *key, AwnConfigListType list_type, GSList *value, GError **err);
A configuration wrapper API that supports both a GConf backend, as well as a GKeyFile-based backend. Used for both Awn proper and its applets.
typedef struct _AwnConfigClient AwnConfigClient;
An opaque structure that facilitates having multiple configuration backends available to Awn.
#define AWN_CONFIG_CLIENT(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), AWN_TYPE_CONFIG_CLIENT, AwnConfigClient))
Casts a variable/value to be an AwnConfigClient.
obj : |
The variable/value to cast |
typedef struct { AwnConfigClient *client; gchar *group; gchar *key; AwnConfigClientValue value; } AwnConfigClientNotifyEntry;
The structure used to transport data to the notification functions of a configuration entry.
AwnConfigClient *client ; |
The client associated with the entry. |
gchar *group ; |
The group name of the entry. |
gchar *key ; |
The key name of the entry. |
AwnConfigClientValue value ; |
The new value of the entry. |
void (*AwnConfigClientNotifyFunc) (AwnConfigClientNotifyEntry *entry, gpointer data);
The callback template for configuration change notification functions.
entry : |
The metadata about the new entry value. |
data : |
Extra data passed to the callback, as defined in the call
to awn_config_client_notify_add() .
|
#define AWN_CONFIG_CLIENT_DEFAULT_GROUP "DEFAULT"
In the GKeyFile backend, the group name with which "top-level" configuration entries are associated.
typedef enum { AWN_CONFIG_VALUE_TYPE_NULL = -1, AWN_CONFIG_VALUE_TYPE_BOOL, AWN_CONFIG_VALUE_TYPE_FLOAT, AWN_CONFIG_VALUE_TYPE_INT, AWN_CONFIG_VALUE_TYPE_STRING, AWN_CONFIG_VALUE_TYPE_LIST_BOOL, AWN_CONFIG_VALUE_TYPE_LIST_FLOAT, AWN_CONFIG_VALUE_TYPE_LIST_INT, AWN_CONFIG_VALUE_TYPE_LIST_STRING } AwnConfigValueType;
Indicates the value type of a particular configuration entry.
typedef enum { AWN_CONFIG_CLIENT_LIST_TYPE_BOOL, AWN_CONFIG_CLIENT_LIST_TYPE_FLOAT, AWN_CONFIG_CLIENT_LIST_TYPE_INT, AWN_CONFIG_CLIENT_LIST_TYPE_STRING } AwnConfigListType;
Indicates the value type of every item in a configuration entry of type "list".
AwnConfigClient* awn_config_client_new ();
Retrieves the configuration client for Awn proper. If none exists, one is created.
Returns : | a singleton instance of AwnConfigClient. |
AwnConfigClient* awn_config_client_new_for_applet (gchar *name, gchar *uid);
Creates a configuration client for the applet named in the parameter. If
uid
is not defined, it is implied that the applet is a singleton.
name : |
The name of the applet. |
uid : |
The unique identifier for the applet (used for positioning on the
dock). Optional value (i.e., may be NULL ).
|
Returns : | an instance of AwnConfigClient for the specified applet. |
void awn_config_client_clear (AwnConfigClient *client, GError **err);
Removes all of the configuration entries from the client.
client : |
The configuration client that is to be used. |
err : |
The pointer to the GError structure that contains an error message on failure. |
void awn_config_client_ensure_group (AwnConfigClient *client, const gchar *group);
Ensures that the group
named has been created in the configuration backend.
client : |
The configuration client to be queried. |
group : |
The name of the group. |
void awn_config_client_notify_add (AwnConfigClient *client, const gchar *group, const gchar *key, AwnConfigClientNotifyFunc callback, gpointer data);
Associates a callback function with a group and a key, which is called when that key's value has been modified in some way.
client : |
The configuration client that is to be used. |
group : |
The name of the group. |
key : |
The name of the key. |
callback : |
The function that is called when the key value has been modified. |
data : |
Extra data that is passed to the callback. |
gboolean awn_config_client_entry_exists (AwnConfigClient *client, const gchar *group, const gchar *key);
Determines whether the group and key exists in the configuration backend.
client : |
The configuration client that is to be queried. |
group : |
The name of the group. |
key : |
The name of the key. |
Returns : | TRUE on success, FALSE otherwise.
|
gboolean awn_config_client_get_bool (AwnConfigClient *client, const gchar *group, const gchar *key, GError **err);
Retrieves the value (as a boolean) of the specified group and key.
client : |
The configuration client that is to be queried. |
group : |
The name of the group. |
key : |
The name of the key. |
err : |
A pointer to a GError structure, which contains an error message if the function fails. |
Returns : | a boolean value. |
void awn_config_client_set_bool (AwnConfigClient *client, const gchar *group, const gchar *key, gboolean value, GError **err);
Changes the value (as a boolean) of the specified group and key.
client : |
The configuration client that is to be used. |
group : |
The name of the group. |
key : |
The name of the key. |
value : |
The new value of the key. |
err : |
A pointer to a GError structure, which contains an error message if the function fails. |
gfloat awn_config_client_get_float (AwnConfigClient *client, const gchar *group, const gchar *key, GError **err);
Retrieves the value (as a float) of the specified group and key.
client : |
The configuration client that is to be queried. |
group : |
The name of the group. |
key : |
The name of the key. |
err : |
A pointer to a GError structure, which contains an error message if the function fails. |
Returns : | a float value. |
void awn_config_client_set_float (AwnConfigClient *client, const gchar *group, const gchar *key, gfloat value, GError **err);
Changes the value (as a float) of the specified group and key. If you need double precision, use a string.
client : |
The configuration client that is to be used. |
group : |
The name of the group. |
key : |
The name of the key. |
value : |
The new value of the key. |
err : |
A pointer to a GError structure, which contains an error message if the function fails. |
gint awn_config_client_get_int (AwnConfigClient *client, const gchar *group, const gchar *key, GError **err);
Retrieves the value (as an integer) of the specified group and key.
client : |
The configuration client that is to be queried. |
group : |
The name of the group. |
key : |
The name of the key. |
err : |
A pointer to a GError structure, which contains an error message if the function fails. |
Returns : | an integer value. |
void awn_config_client_set_int (AwnConfigClient *client, const gchar *group, const gchar *key, gint value, GError **err);
Changes the value (as an integer) of the specified group and key.
client : |
The configuration client that is to be used. |
group : |
The name of the group. |
key : |
The name of the key. |
value : |
The new value of the key. |
err : |
A pointer to a GError structure, which contains an error message if the function fails. |
gchar* awn_config_client_get_string (AwnConfigClient *client, const gchar *group, const gchar *key, GError **err);
Retrieves the value (as a string) of the specified group and key.
client : |
The configuration client that is to be queried. |
group : |
The name of the group. |
key : |
The name of the key. |
err : |
A pointer to a GError structure, which contains an error message if the function fails. |
Returns : | a newly allocated string value. The caller is responsible for freeing the memory. |
void awn_config_client_set_string (AwnConfigClient *client, const gchar *group, const gchar *key, gchar *value, GError **err);
Changes the value (as a string) of the specified group and key.
client : |
The configuration client that is to be used. |
group : |
The name of the group. |
key : |
The name of the key. |
value : |
The new value of the key. |
err : |
A pointer to a GError structure, which contains an error message if the function fails. |
GSList* awn_config_client_get_list (AwnConfigClient *client, const gchar *group, const gchar *key, AwnConfigListType list_type, GError **err);
Retrieves the value (as a GSList) of the specified group and key.
client : |
The configuration client that is to be queried. |
group : |
The name of the group. |
key : |
The name of the key. |
list_type : |
The value type of every item in the list. |
err : |
A pointer to a GError structure, which contains an error message if the function fails. |
Returns : | a newly allocated list value. The caller is responsible for freeing the memory. |
void awn_config_client_set_list (AwnConfigClient *client, const gchar *group, const gchar *key, AwnConfigListType list_type, GSList *value, GError **err);
Changes the value (as a list of values) of the specified group and key.
client : |
The configuration client that is to be used. |
group : |
The name of the group. |
key : |
The name of the key. |
list_type : |
The value type of every item in the list. |
value : |
The new value of the key. |
err : |
A pointer to a GError structure, which contains an error message if the function fails. |