GfPreferenceEngine

GfPreferenceEngine — GfPreferenceEngine Object API

Synopsis




enum        GfPreferenceType;
            GfPreference;
            GfPreferenceEngine;
void        gf_preference_engine_reload     (GfPreferenceEngine *engine);
void        gf_preference_engine_save       (const GfPreferenceEngine *engine);
void        gf_preference_engine_add_section
                                            (GfPreferenceEngine *engine,
                                             const gchar *path);
void        gf_preference_engine_add_string (GfPreferenceEngine *engine,
                                             const gchar *name,
                                             const gchar *def);
void        gf_preference_engine_set_string (GfPreferenceEngine *engine,
                                             const gchar *name,
                                             const gchar *value);
gchar*      gf_preference_engine_get_string (const GfPreferenceEngine *engine,
                                             const gchar *name);
void        gf_preference_engine_add_int    (GfPreferenceEngine *engine,
                                             const gchar *name,
                                             gint def);
void        gf_preference_engine_set_int    (GfPreferenceEngine *engine,
                                             const gchar *name,
                                             gint value);
gint        gf_preference_engine_get_int    (const GfPreferenceEngine *engine,
                                             const gchar *name);
void        gf_preference_engine_add_bool   (GfPreferenceEngine *engine,
                                             const gchar *name,
                                             gboolean def);
void        gf_preference_engine_set_bool   (GfPreferenceEngine *engine,
                                             const gchar *name,
                                             gboolean value);
gboolean    gf_preference_engine_get_bool   (const GfPreferenceEngine *engine,
                                             const gchar *name);
gboolean    gf_preference_engine_exists     (const GfPreferenceEngine *engine,
                                             const gchar *name);
gboolean    gf_preference_engine_rename     (GfPreferenceEngine *engine,
                                             const gchar *oldname,
                                             const gchar *newname);
gint        gf_preference_engine_remove     (GfPreferenceEngine *engine,
                                             const gchar *path);
GfPreference** gf_preference_engine_query   (const GfPreferenceEngine *engine,
                                             const gchar *path,
                                             guint *num_prefs);
GfPreferenceType gf_preference_engine_get_type
                                            (const GfPreferenceEngine *engine,
                                             const gchar *path);
#define     gf_preference_type_from_string  (str)
#define     gf_preference_type_to_string    (type, i18n)
GfPreference* gf_preference_copy            (const GfPreference *pref);
void        gf_preference_free              (GfPreference *pref);
void        gf_preference_freev             (GfPreference **prefs);
GfPreference* gf_preference_new             (const gchar *name,
                                             const gchar *path,
                                             GfPreferenceType type,
                                             const GValue *value);
void        gf_preference_set_name          (GfPreference *pref,
                                             const gchar *name);
const gchar* gf_preference_get_name         (const GfPreference *pref);
gchar*      gf_preference_get_full_name     (const GfPreference *pref);
void        gf_preference_set_path          (GfPreference *pref,
                                             const gchar *path);
const gchar* gf_preference_get_path         (const GfPreference *pref);
void        gf_preference_set_type          (GfPreference *pref,
                                             GfPreferenceType type);
GfPreferenceType gf_preference_get_type     (const GfPreference *pref);
void        gf_preference_set_string        (GfPreference *pref,
                                             const gchar *value);
const gchar* gf_preference_get_string       (const GfPreference *pref);
void        gf_preference_set_int           (GfPreference *pref,
                                             gint value);
gint        gf_preference_get_int           (const GfPreference *pref);
void        gf_preference_set_bool          (GfPreference *pref,
                                             gboolean value);
gboolean    gf_preference_get_bool          (const GfPreference *pref);

Object Hierarchy


  GObject
   +----GfObject
         +----GfNamedObject
               +----GfPreferenceEngine
                     +----GfPreferenceEngineXML

Signal Prototypes


"changed"   void        user_function      (GfPreferenceEngine *gfpreferenceengine,
                                            gchar *arg1,
                                            GfPreference *arg2,
                                            gpointer user_data);
"removed"   void        user_function      (GfPreferenceEngine *gfpreferenceengine,
                                            GfPreference *arg1,
                                            gpointer user_data);
"renamed"   void        user_function      (GfPreferenceEngine *gfpreferenceengine,
                                            gchar *arg1,
                                            GfPreference *arg2,
                                            gpointer user_data);

Description

GfPreferenceEngine is an abstract object the drives preferences. It is normally only created by the daemon, although it could be used anywhere. But probably wouldn't be too helpful. This has been built in a manner so that native engines can be written cleanly. Currently only one known subclass exists, GfPreferenceEngineXML. Although GConf, Windows Registry, and SQL backends could be implemented rather easily.

Details

enum GfPreferenceType

typedef enum _GfPreferenceType {
	GF_PREFERENCE_TYPE_UNKNOWN = -1,
	GF_PREFERENCE_TYPE_SECTION = 0,
	GF_PREFERENCE_TYPE_STRING,
	GF_PREFERENCE_TYPE_INT,
	GF_PREFERENCE_TYPE_BOOL,
	GF_PREFERENCE_TYPES
} GfPreferenceType;

The different valid types of a preference.

`GF_PREFERENCE_TYPE_UNKNOWN`	Unknown.
`GF_PREFERENCE_TYPE_SECTION`	Section.
`GF_PREFERENCE_TYPE_STRING`	String.
`GF_PREFERENCE_TYPE_INT`	Integer.
`GF_PREFERENCE_TYPE_BOOL`	Boolean.
`GF_PREFERENCE_TYPES`	Total Types.

GfPreference

typedef struct {
	gchar *name;
	gchar *path;
	GfPreferenceType type;
	GValue *value;
} GfPreference;

A Preference

gchar *`name`;	The name.
gchar *`path`;	The path.
GfPreferenceType `type`;	The GfPreferenceType.
GValue *`value`;	The value.

GfPreferenceEngine

typedef struct _GfPreferenceEngine GfPreferenceEngine;

GfPreferenceEngine is an opaque structure that should not be used directly.

gf_preference_engine_reload ()

void        gf_preference_engine_reload     (GfPreferenceEngine *engine);

Reloads all preference in engine.

engine : The GfPreferenceEngine instance.

gf_preference_engine_save ()

void        gf_preference_engine_save       (const GfPreferenceEngine *engine);

Forces an output/save of all preferences in engine.

engine : The GfPreferenceEngine instance.

gf_preference_engine_add_section ()

void        gf_preference_engine_add_section
                                            (GfPreferenceEngine *engine,
                                             const gchar *path);

Adds a new section to engine.

`engine` :	The GfPreferenceEngine instance.
`path` :	The path of the new section.

gf_preference_engine_add_string ()

void        gf_preference_engine_add_string (GfPreferenceEngine *engine,
                                             const gchar *name,
                                             const gchar *def);

Adds a string preference to engine with a default value of def.

`engine` :	The GfPreferenceEngine instance.
`name` :	The absolute name of the string preference.
`def` :	The default value of the string preference.

gf_preference_engine_set_string ()

void        gf_preference_engine_set_string (GfPreferenceEngine *engine,
                                             const gchar *name,
                                             const gchar *value);

Sets the string preference name to value in engine.

`engine` :	The GfPreferenceEngine instance.
`name` :	The absolute name of the string preference.
`value` :	The new value for the string preference.

gf_preference_engine_get_string ()

gchar*      gf_preference_engine_get_string (const GfPreferenceEngine *engine,
                                             const gchar *name);

Gets the value of name from engine.

Note: If the returned value is not NULL, it must be freed with #g_free().

`engine` :	The GfPreferenceEngine instance.
`name` :	The absolute name of the string preference.
Returns :	The value of `name`.

gf_preference_engine_add_int ()

void        gf_preference_engine_add_int    (GfPreferenceEngine *engine,
                                             const gchar *name,
                                             gint def);

Adds an integer prefer to engine with a default value of def.

`engine` :	The GfPreferenceEngine instance.
`name` :	The absolute name of the integer preference.
`def` :	The default value of the integer preference.

gf_preference_engine_set_int ()

void        gf_preference_engine_set_int    (GfPreferenceEngine *engine,
                                             const gchar *name,
                                             gint value);

Sets the integer preference name to value in engine.

`engine` :	The GfPreferenceEngine instance.
`name` :	The absolute name of the integer preferecen.
`value` :	The new value.

gf_preference_engine_get_int ()

gint        gf_preference_engine_get_int    (const GfPreferenceEngine *engine,
                                             const gchar *name);

Gets the value of the integer preference name from engine.

`engine` :	The GfPreferenceEngine instance.
`name` :	The absolute name of the integer preference.
Returns :	The value of `name`.

gf_preference_engine_add_bool ()

void        gf_preference_engine_add_bool   (GfPreferenceEngine *engine,
                                             const gchar *name,
                                             gboolean def);

Adds the boolean preference name to engine with a default value of def.

`engine` :	The GfPreferenceEngine instance.
`name` :	The absolute name of the boolean preference.
`def` :	The default vlaue of the boolean preference.

gf_preference_engine_set_bool ()

void        gf_preference_engine_set_bool   (GfPreferenceEngine *engine,
                                             const gchar *name,
                                             gboolean value);

Sets the boolean preference name to value in engine.

`engine` :	The GfPreferenceEngine instance.
`name` :	The absolute value of the boolean preference.
`value` :	The new value for the boolean preference.

gf_preference_engine_get_bool ()

gboolean    gf_preference_engine_get_bool   (const GfPreferenceEngine *engine,
                                             const gchar *name);

Gets the value of the boolean preference name from engine.

`engine` :	The GfPreferenceEngine instance.
`name` :	The absolute name of the boolean preference.
Returns :	The value of the boolean preference `name`.

gf_preference_engine_exists ()

gboolean    gf_preference_engine_exists     (const GfPreferenceEngine *engine,
                                             const gchar *name);

Checks whether or not a preference named name exists in engine.

`engine` :	The GfPreferenceEngine instance.
`name` :	The absolute name of the preference.
Returns :	TRUE if `name` exists in `engine`.

gf_preference_engine_rename ()

gboolean    gf_preference_engine_rename     (GfPreferenceEngine *engine,
                                             const gchar *oldname,
                                             const gchar *newname);

Renames the preference oldname to newname.

Note: Currently you can NOT rename sections.

`engine` :	The GfPreferenceEngine instance.
`oldname` :	The current absolute name of the preference.
`newname` :	The new absolute name to give the preferece.
Returns :	TRUE if renaming was successful.

gf_preference_engine_remove ()

gint        gf_preference_engine_remove     (GfPreferenceEngine *engine,
                                             const gchar *path);

Removes a path from engine.

`engine` :	The GfPreferenceEngine instance.
`path` :	The path to remove.
Returns :	The number of preferences removed from `engine`.

gf_preference_engine_query ()

GfPreference** gf_preference_engine_query   (const GfPreferenceEngine *engine,
                                             const gchar *path,
                                             guint *num_prefs);

Returns a newly allocated array of GfPreference's containing each preference under path.

`engine` :	The GfPreferenceEngine instance.
`path` :	The path to query.
`num_prefs` :	The return address for the number of returned preferences.
Returns :	A newly allocated array of GfPreference's containing each preference under `path` or NULL.

gf_preference_engine_get_type ()

GfPreferenceType gf_preference_engine_get_type
                                            (const GfPreferenceEngine *engine,
                                             const gchar *path);

Gets the GfPreferenceType of path.

`engine` :	The GfPreferenceEngine instance.
`path` :	The path of the preference.
Returns :	The GfPreferenceType of `path`.

gf_preference_type_from_string()

#define     gf_preference_type_from_string(str)

Gets a GfPreferenceType from a string.

Note: str MUST be the untranslated string!

`str` :	The string.
Returns :	The GfPreferenceType.

gf_preference_type_to_string()

#define     gf_preference_type_to_string(type, i18n)

Gets a string from a GfPreferenceType.

`type` :	The GfPreferenceType.
`i18n` :	TRUE for the translated version.
Returns :	`type` as a string.

gf_preference_copy ()

GfPreference* gf_preference_copy            (const GfPreference *pref);

Creates a copy of pref.

`pref` :	The GfPreference instance.
Returns :	A copy of `pref`.

gf_preference_free ()

void        gf_preference_free              (GfPreference *pref);

Frees pref.

pref : The GfPreference instance.

gf_preference_freev ()

void        gf_preference_freev             (GfPreference **prefs);

Frees an array of GfPreferences's.

prefs : An array of GfPreference's.

gf_preference_new ()

GfPreference* gf_preference_new             (const gchar *name,
                                             const gchar *path,
                                             GfPreferenceType type,
                                             const GValue *value);

Creates a new GfPreference.

`name` :	The name of the preference.
`path` :	The path of the preference.
`type` :	The GfPreferenceType of the preference.
`value` :	The value of the preference.
Returns :	The new GfPreference.

gf_preference_set_name ()

void        gf_preference_set_name          (GfPreference *pref,
                                             const gchar *name);

Sets the name for pref.

`pref` :	The GfPreference instance.
`name` :	The new name.

gf_preference_get_name ()

const gchar* gf_preference_get_name         (const GfPreference *pref);

Gets the name of pref.

`pref` :	The GfPreference instance.
Returns :	The name of `pref`.

gf_preference_get_full_name ()

gchar*      gf_preference_get_full_name     (const GfPreference *pref);

Gets the full name for a preference.

`pref` :	The GfPreference instance.
Returns :	The full absolute name of `pref`.

gf_preference_set_path ()

void        gf_preference_set_path          (GfPreference *pref,
                                             const gchar *path);

Sets the path for pref.

`pref` :	The GfPreference instance.
`path` :	The new path.

gf_preference_get_path ()

const gchar* gf_preference_get_path         (const GfPreference *pref);

Gets the path of pref.

`pref` :	The GfPreference instance.
Returns :	The path of `pref`.

gf_preference_set_type ()

void        gf_preference_set_type          (GfPreference *pref,
                                             GfPreferenceType type);

Sets the type of pref.

`pref` :	The GfPreference instance.
`type` :	The new type.

gf_preference_get_type ()

GfPreferenceType gf_preference_get_type     (const GfPreference *pref);

Gets the type of pref.

`pref` :	The GfPreference instance.
Returns :	The type of `pref`.

gf_preference_set_string ()

void        gf_preference_set_string        (GfPreference *pref,
                                             const gchar *value);

Sets the string value for pref.

`pref` :	The GfPreference instance.
`value` :	The new string value.

gf_preference_get_string ()

const gchar* gf_preference_get_string       (const GfPreference *pref);

Gets the string value for pref.

`pref` :	The GfPreference instance.
Returns :	The string value for `pref`.

gf_preference_set_int ()

void        gf_preference_set_int           (GfPreference *pref,
                                             gint value);

Sets the integer value of pref.

`pref` :	The GfPreference instance.
`value` :	The new integer value.

gf_preference_get_int ()

gint        gf_preference_get_int           (const GfPreference *pref);

Gets the integer value of pref.

`pref` :	The GfPreference instance.
Returns :	The integer value of `pref`.

gf_preference_set_bool ()

void        gf_preference_set_bool          (GfPreference *pref,
                                             gboolean value);

Sets the boolean value of pref.

`pref` :	The GfPreference instance.
`value` :	The new boolean value.

gf_preference_get_bool ()

gboolean    gf_preference_get_bool          (const GfPreference *pref);

Gets the boolean value of pref.

`pref` :	The GfPreference instance.
Returns :	The boolean value of `pref`.

Signals

The "changed" signal

void        user_function                  (GfPreferenceEngine *gfpreferenceengine,
                                            gchar *arg1,
                                            GfPreference *arg2,
                                            gpointer user_data);

`gfpreferenceengine` :	the object which received the signal.
`arg1` :	@: @: @: @: @: @: @: @: @: @: @: @: @: @: @: @: @: @: @: @: @: @: @: @: @: @: @: @: @: @: @: @:
`user_data` :	user data set when the signal handler was connected.

The "removed" signal

void        user_function                  (GfPreferenceEngine *gfpreferenceengine,
                                            GfPreference *arg1,
                                            gpointer user_data);

`gfpreferenceengine` :	the object which received the signal.
`arg1` :
`user_data` :	user data set when the signal handler was connected.

The "renamed" signal

void        user_function                  (GfPreferenceEngine *gfpreferenceengine,
                                            gchar *arg1,
                                            GfPreference *arg2,
                                            gpointer user_data);

`gfpreferenceengine` :	the object which received the signal.
`arg1` :
`arg2` :
`user_data` :	user data set when the signal handler was connected.