awn-config-client

awn-config-client — The configuration API for both Awn proper and Awn applets. include libawn/awn-config-client.h

Synopsis




                    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);

Description

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.

Details

AwnConfigClient

typedef struct _AwnConfigClient AwnConfigClient;

An opaque structure that facilitates having multiple configuration backends available to Awn.


AWN_CONFIG_CLIENT()

#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

AwnConfigClientNotifyEntry

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.

AwnConfigClientNotifyFunc ()

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().

AWN_CONFIG_CLIENT_DEFAULT_GROUP

#define AWN_CONFIG_CLIENT_DEFAULT_GROUP "DEFAULT"

In the GKeyFile backend, the group name with which "top-level" configuration entries are associated.


enum AwnConfigValueType

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.

AWN_CONFIG_VALUE_TYPE_NULL Indicates that the configuration value type is unknown.
AWN_CONFIG_VALUE_TYPE_BOOL Indicates that the configuration value type is boolean.
AWN_CONFIG_VALUE_TYPE_FLOAT Indicates that the configuration value type is float.
AWN_CONFIG_VALUE_TYPE_INT Indicates that the configuration value type is integer.
AWN_CONFIG_VALUE_TYPE_STRING Indicates that the configuration value type is string.
AWN_CONFIG_VALUE_TYPE_LIST_BOOL Indicates that the configuration value type is list whose items are booleans.
AWN_CONFIG_VALUE_TYPE_LIST_FLOAT Indicates that the configuration value type is list whose items are floats.
AWN_CONFIG_VALUE_TYPE_LIST_INT Indicates that the configuration value type is list whose items are integers.
AWN_CONFIG_VALUE_TYPE_LIST_STRING Indicates that the configuration value type is list whose items are strings.

enum AwnConfigListType

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".

AWN_CONFIG_CLIENT_LIST_TYPE_BOOL Indicates that the list value type is boolean.
AWN_CONFIG_CLIENT_LIST_TYPE_FLOAT Indicates that the list value type is float.
AWN_CONFIG_CLIENT_LIST_TYPE_INT Indicates that the list value type is integer.
AWN_CONFIG_CLIENT_LIST_TYPE_STRING Indicates that the list value type is string.

awn_config_client_new ()

AwnConfigClient*    awn_config_client_new               ();

Retrieves the configuration client for Awn proper. If none exists, one is created.

Returns : a singleton instance of AwnConfigClient.

awn_config_client_new_for_applet ()

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.

awn_config_client_clear ()

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.

awn_config_client_ensure_group ()

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.

awn_config_client_notify_add ()

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.

awn_config_client_entry_exists ()

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.

awn_config_client_get_bool ()

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.

awn_config_client_set_bool ()

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.

awn_config_client_get_float ()

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.

awn_config_client_set_float ()

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.

awn_config_client_get_int ()

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.

awn_config_client_set_int ()

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.

awn_config_client_get_string ()

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.

awn_config_client_set_string ()

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.

awn_config_client_get_list ()

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.

awn_config_client_set_list ()

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.