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

The callback template for configuration change notification functions.

entry :

The metadata about the new entry value.

user_data :


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

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