GConf Utilities
[GLib]

---

Detailed Description

The API in this file is designed to make it easy to use the GConf system from within Gnucash. GConf is a shared key/value storage system.

The main benefits of these routines are that they

1. maintain a GConfClient object,
2. convert gnucash internal section names into full gconf pathnames, and
3. optionally take care of error checking on return values.

Files
file	gnc-gconf-utils.h
	GConf helper routines.
GConf Miscellaneous Functions
const gchar *	gnc_enum_to_nick (GType type, gint value)
gint	gnc_enum_from_nick (GType type, const gchar *name, gint default_value)
char *	gnc_gconf_section_name (const char *name)
char *	gnc_gconf_schema_section_name (const char *name)
void	gnc_gconf_suggest_sync (void)
GConf "General" Section Convenience Functions
void	gnc_gconf_general_register_cb (const gchar *key, GncGconfGeneralCb func, gpointer user_data)
void	gnc_gconf_general_remove_cb (const gchar *key, GncGconfGeneralCb func, gpointer user_data)
void	gnc_gconf_general_register_any_cb (GncGconfGeneralAnyCb func, gpointer user_data)
void	gnc_gconf_general_remove_any_cb (GncGconfGeneralAnyCb func, gpointer user_data)
GConf Get Functions
gboolean	gnc_gconf_get_bool (const gchar *section, const gchar *name, GError **error)
gboolean	gnc_gconf_get_bool_no_error (const gchar *section, const gchar *name)
gint	gnc_gconf_get_int (const gchar *section, const gchar *name, GError **error)
gdouble	gnc_gconf_get_float (const gchar *section, const gchar *name, GError **error)
char *	gnc_gconf_get_string (const gchar *section, const gchar *name, GError **error)
GSList *	gnc_gconf_get_list (const gchar *section, const gchar *name, GConfValueType list_type, GError **error)
GConfSchema *	gnc_gconf_get_schema (const gchar *section, const gchar *name, GError **caller_error)
GConf Set/Unset Functions
void	gnc_gconf_set_bool (const gchar *section, const gchar *name, const gboolean value, GError **error)
void	gnc_gconf_set_int (const gchar *section, const gchar *name, const gint value, GError **error)
void	gnc_gconf_set_float (const gchar *section, const gchar *name, const gdouble value, GError **error)
void	gnc_gconf_set_string (const gchar *section, const gchar *name, const gchar *value, GError **error)
void	gnc_gconf_set_list (const gchar *section, const gchar *name, GConfValueType list_type, GSList *value, GError **error)
void	gnc_gconf_unset (const gchar *section, const gchar *name, GError **error)
void	gnc_gconf_unset_dir (const gchar *section, GError **error)
GConf Notification Functions
void	gnc_gconf_add_notification (GObject *object, const gchar *section, GConfClientNotifyFunc callback, const gchar *whoami)
guint	gnc_gconf_add_anon_notification (const gchar *section, GConfClientNotifyFunc callback, gpointer data)
void	gnc_gconf_remove_notification (GObject *object, const gchar *section, const gchar *whoami)
void	gnc_gconf_remove_anon_notification (const gchar *section, guint cnxn_id)
GSList *	gnc_gconf_client_all_entries (const gchar *section)
gboolean	gnc_gconf_schemas_found (void)
GConf One Liners
#define	DESTKOP_TEAROFF_MENUS   "/desktop/gnome/interface/menus_have_tearoff"
#define	DESTKOP_MENUBAR_DETACHABLE   "/desktop/gnome/interface/menubar_detachable"
#define	DESTKOP_TOOLBAR_DETACHABLE   "/desktop/gnome/interface/toolbar_detachable"
Defines
#define	GCONF_GENERAL   "general"
#define	GCONF_GENERAL_REGISTER   "general/register"
#define	GCONF_GENERAL_REPORT   "general/report"
#define	GCONF_WARNINGS   "general/warnings"
#define	GCONF_WARNINGS_TEMP   "general/warnings/temporary"
#define	GCONF_WARNINGS_PERM   "general/warnings/permanent"
#define	DESKTOP_GNOME_INTERFACE   "/desktop/gnome/interface"
#define	KEY_TOOLBAR_STYLE   "toolbar_style"
#define	KEY_SAVE_GEOMETRY   "save_window_geometry"
#define	KEY_LAST_PATH   "last_path"
#define	KEY_USE_NEW   "use_new_window"
#define	KEY_ACCOUNTING_LABELS   "use_accounting_labels"
#define	KEY_ACCOUNT_SEPARATOR   "account_separator"
#define	KEY_NEGATIVE_IN_RED   "negative_in_red"
#define	KEY_NUMBER_OF_ROWS   "number_of_rows"
#define	KEY_ENABLE_EURO   "enable_euro"
#define	KEY_DATE_FORMAT   "date_format"
#define	KEY_SHOW_LEAF_ACCOUNT_NAMES   "show_leaf_account_names"
Typedefs
typedef void(*)	GncGconfGeneralCb (GConfEntry *entry, gpointer user_data)
typedef void(*)	GncGconfGeneralAnyCb (gpointer user_data)

---

Function Documentation

gint gnc_enum_from_nick	(	GType	type,
		const gchar *	name,
		gint	default_value
	)

This function takes an enum nickname and returns its value.

Parameters:

	type	The value defining the enum class. For example, GTK_TYPE_SORT_TYPE or GTK_TYPE_ARROW_TYPE.
	name	The textual name for one of the items in the enum. For example, "ascending".
	default_value	A value contained in the enum. This value will be returned if the supplied nickname is invalid. For example, GTK_SORT_ASCENDING.

Returns:

A pointer to the textual "nickname" for this enum.

Definition at line 65 of file gnc-gconf-utils.c.

{
  GEnumClass   *enum_class;
  GEnumValue   *enum_value;
  gchar        *alt_name, *ptr;

  if (name == NULL)
    return default_value;

  /* Lookup the enum class in the glib type system */
  enum_class = g_type_class_ref (type);
  if (!enum_class) {
    /* g_type_class_ref has already printed a warning. */
    return default_value;
  }

  /* Lookup the specified enum in the class */
  enum_value = g_enum_get_value_by_nick(enum_class, name);
  if (enum_value)
    return enum_value->value;

  /* Flip '-' and '_' and try again */
  alt_name = g_strdup(name);
  if ((ptr = strchr(alt_name, '-')) != NULL) {
    do {
      *ptr++ = '_';
    } while ((ptr = strchr(ptr, '-')) != NULL);
  } else  if ((ptr = strchr(alt_name, '_')) != NULL) {
    do {
      *ptr++ = '-';
    } while ((ptr = strchr(ptr, '_')) != NULL);
  } else {
    g_free(alt_name);
    return default_value;
  }

  /* Lookup the specified enum in the class */
  enum_value = g_enum_get_value_by_nick(enum_class, alt_name);
  g_free(alt_name);
  if (enum_value)
    return enum_value->value;
  return default_value;
}

const gchar* gnc_enum_to_nick	(	GType	type,
		gint	value
	)

This function takes an enum value and returns its nickname.

Parameters:

	type	The value defining the enum class. For example, GTK_TYPE_SORT_TYPE.
	value	A value contained in the enum. For example, GTK_SORT_ASCENDING.

Returns:

A pointer to the textual "nickname" for this enum. Tor example, "ascending".

Definition at line 43 of file gnc-gconf-utils.c.

{
  GEnumClass        *enum_class;
  GEnumValue        *enum_value;

  /* Lookup the enum in the glib type system */
  enum_class = g_type_class_ref (type);
  if (!enum_class) {
    /* g_type_class_ref has already printed a warning. */
    return NULL;
  }

  enum_value = g_enum_get_value (enum_class, value);
  if (!enum_value) {
    /* Use the first item in the enum */
    enum_value = g_enum_get_value (enum_class, 0);
  }
  return enum_value->value_nick;
}

guint gnc_gconf_add_anon_notification	(	const gchar *	section,
		GConfClientNotifyFunc	callback,
		gpointer	data
	)

An alternative function for adding a notification callback to GConf.

Add a function that will be called whenever a value within the specified section of the GConf tree changes. The section name provided as an argument is combined with the standard gnucash key prefix to produce a fully qualified key name. This name may be a fully qualified key path name, in which case it is used as is, without the standard gnucash prefix. This allows the object to respond to keys like standard desktop settings.

Parameters:

	section	This string provides a grouping of keys within the GnuCash section of the gconf database. It can be a simple string as in "history" for settings that are common to many areas of gnucash, or it can be a partial path name as in "dialogs/business/invoice" for setting that only apply to one specific area of the program. Any key changes within this section will invoke the notification function.
	callback	The function to call when a value changes. This function will receive the key/value pair as one argument, and the 'object' argument to this function as another of its arguments.
	data	This pointer will be provided to the callback function when it is invoked.

Returns:

This function returns an identification number that must be passed to the gnc_gconf_remove_anon_notification() function to reverse the actions of this function.

Definition at line 801 of file gnc-gconf-utils.c.

{
        GConfClient *client;
        GError *error = NULL;
        gchar *path;
        guint id;

        g_return_val_if_fail(callback != NULL, 0);

        client = gconf_client_get_default();
        path = gnc_gconf_section_name(section);


        /*
         * First we have to add the directory...
         */
        gconf_client_add_dir(client, path, GCONF_CLIENT_PRELOAD_ONELEVEL, &error);
        if (error != NULL) {
            printf("Failed to add history section to watched directories in gconf: %s", error->message);
            g_error_free(error);
            g_object_unref(client);
            g_free(path);
            return 0;
        }

        /*
         * Then we can add the notification callback.
         */
        id = gconf_client_notify_add(client, path, callback,
                                     data, NULL, &error);
        if (error != NULL) {
              printf("Failed to set gconf notify for history section: %s", error->message);
              gconf_client_remove_dir(client, path, NULL);
              g_error_free(error);
              g_object_unref(client);
              g_free(path);
              return 0;
        }
        g_free(path);
        return id;
}

void gnc_gconf_add_notification	(	GObject *	object,
		const gchar *	section,
		GConfClientNotifyFunc	callback,
		const gchar *	whoami
	)

Add a notification callback to GConf.

Add a function that will be called whenever a value within the specified section of the GConf tree changes. The section name provided as an argument is combined with the standard gnucash key prefix to produce a fully qualified key name. This name may be a fully qualified key path name, in which case it is used as is, without the standard gnucash prefix. This allows the object to respond to keys like standard desktop settings.

Parameters:

	object	This is a pointer to a GObject derivative. This object will be provided to the callback function when it is invoked. Several values will also be attached to this object that are used by the gnc_gconf_remove_notification() function.
	section	This string provides a grouping of keys within the GnuCash section of the gconf database. It can be a simple string as in "history" for settings that are common to many areas of gnucash, or it can be a partial path name as in "dialogs/business/invoice" for setting that only apply to one specific area of the program. Any key changes within this section will invoke the notification function.
	callback	The function to call when a value changes. This function will receive the key/value pair as one argument, and the 'object' argument to this function as another of its arguments.
	whoami	A magic value that must match up this call to the corresponding call to gnc_gconf_remove_notification(). The pair of section and whoami should be unique across all callers.

Definition at line 744 of file gnc-gconf-utils.c.

{
        GConfClient *client;
        GError *error = NULL;
        gchar *path, *client_tag, *notify_tag;
        guint id;

        g_return_if_fail(G_IS_OBJECT(object));
        g_return_if_fail(callback != NULL);
        g_return_if_fail(whoami != NULL);

        client = gconf_client_get_default();
        path = gnc_gconf_section_name(section);

        /*
         * First we have to add the directory...
         */
        gconf_client_add_dir(client, path, GCONF_CLIENT_PRELOAD_ONELEVEL, &error);
        if (error != NULL) {
            printf("Failed to add history section to watched directories in gconf: %s", error->message);
            g_error_free(error);
            g_object_unref(client);
            g_free(path);
            return;
        }

        /*
         * Then we can add the notification callback.
         */
        id = gconf_client_notify_add(client, path, callback,
                                     object, NULL, &error);
        if (error != NULL) {
              printf("Failed to set gconf notify for history section: %s", error->message);
              gconf_client_remove_dir(client, path, NULL);
              g_error_free(error);
              g_object_unref(client);
              g_free(path);
              return;
        }
        
        /*
         * Save the values needed to undo this later.
         */
        client_tag = g_strdup_printf(CLIENT_TAG, section ? section:"", whoami);
        notify_tag = g_strdup_printf(NOTIFY_TAG, section ? section:"", whoami);
        g_object_set_data(object, client_tag, client);
        g_object_set_data(object, notify_tag, GUINT_TO_POINTER(id));
        g_free(notify_tag);
        g_free(client_tag);
        g_free(path);
}

GSList* gnc_gconf_client_all_entries

(

const gchar *

section

)

Retrieve a list of all key/value pairs in the specified GConf section. The section name provided as an argument is combined with the standard gnucash key prefix to produce a fully qualified section name.

Parameters:

section

This string provides a grouping of keys within the GnuCash section of the gconf database. It can be a simple string as in "history" for settings that are common to many areas of gnucash, or it can be a partial path name as in "dialogs/business/invoice" for setting that only apply to one specific area of the program.

Returns:

This function returns a list of all key/value pairs stored in this section of the gconf database. These are GConfEntry objects. It is the callers responsibility to free any memory returned by this function. This include the list itself, and any entries contained in the list. See gconf_client_all_entries in the gconf documentation.

Definition at line 640 of file gnc-gconf-utils.c.

{
  GError *error = NULL;
  GSList *value;
  gchar *section;

  if (our_client == NULL)
    our_client = gconf_client_get_default();

  section = gnc_gconf_section_name(name);
  value = gconf_client_all_entries(our_client, section, &error);
  if (error != NULL) {
    printf("Failed to get list of all gconf keys: %s", error->message);
    g_error_free(error);
  }

  return value;
}

void gnc_gconf_general_register_any_cb	(	GncGconfGeneralAnyCb	func,
		gpointer	user_data
	)

Register a callback for when any key in the general section of Gnucash's gconf data is changed. Any time the value of a key in this section chagnes, the routine will be invoked and will be passed the specified user data.

Parameters:

	func	This is a pointer to the function to call when the key changes.
	user_data	This pointer will be passed to the callback function.

Definition at line 217 of file gnc-gconf-utils.c.

{
  GHook *hook;

  g_once(&gcb_init_once, gcb_init, NULL);
  hook = g_hook_find_func_data(gcb_final_hook_list, TRUE, func, user_data);
  if (hook != NULL)
    return;

  hook = g_hook_alloc(gcb_final_hook_list);
  hook->func = func;
  hook->data = user_data;
  g_hook_append(gcb_final_hook_list, hook);
}

void gnc_gconf_general_register_cb	(	const gchar *	key,
		GncGconfGeneralCb	func,
		gpointer	user_data
	)

Register a callback for when a specific key in the general section of Gnucash's gconf data is changed. Any time the key's value changes, the routine will be invoked and will be passed both the changes gconf entry and the user data passed to this function.

Parameters:

	key	This value contains the name of the key within the "general" section to watch.
	func	This is a pointer to the function to call when the key changes.
	user_data	This pointer will be passed to the callback function.

Definition at line 165 of file gnc-gconf-utils.c.

{
  GHookList *hook_list;
  GHook *hook;

  g_once(&gcb_init_once, gcb_init, NULL);
  hook_list = g_hash_table_lookup(gcb_callback_hash, key);
  if (hook_list == NULL) {
    hook_list = g_malloc(sizeof(GHookList));
    g_hook_list_init(hook_list, sizeof(GHook));
    g_hash_table_insert(gcb_callback_hash, (gpointer)key, hook_list);
  }

  hook = g_hook_find_func_data(hook_list, TRUE, func, user_data);
  if (hook != NULL) {
    return;
  }

  hook = g_hook_alloc(hook_list);
  hook->func = func;
  hook->data = user_data;
  g_hook_append(hook_list, hook);
}

void gnc_gconf_general_remove_any_cb	(	GncGconfGeneralAnyCb	func,
		gpointer	user_data
	)

Remove a function that was registered for a callback when any key in the general section of Gnucash's gconf data changed. Both the func and user_data arguments are used to match up the callback to remove.

Parameters:

	func	This is a pointer to the function to call when a key changes.
	user_data	This pointer will be passed to the callback function.

Definition at line 235 of file gnc-gconf-utils.c.

{
  GHook *hook;

  g_once(&gcb_init_once, gcb_init, NULL);
  hook = g_hook_find_func_data(gcb_final_hook_list, TRUE, func, user_data);
  if (hook == NULL)
    return;

  g_hook_unref(gcb_final_hook_list, hook);
}

void gnc_gconf_general_remove_cb	(	const gchar *	key,
		GncGconfGeneralCb	func,
		gpointer	user_data
	)

Remove a function that was registered for a callback when a specific key in the general section of Gnucash's gconf data changed. Both the func and user_data arguments are used to match up the callback to remove.

Parameters:

	key	This value contains the name of the key within the "general" section to watch.
	func	This is a pointer to the function to call when the key changes.
	user_data	This pointer will be passed to the callback function.

Definition at line 193 of file gnc-gconf-utils.c.

{
  GHookList *hook_list;
  GHook *hook;

  g_once(&gcb_init_once, gcb_init, NULL);
  hook_list = g_hash_table_lookup(gcb_callback_hash, key);
  if (hook_list == NULL)
    return;
  hook = g_hook_find_func_data(hook_list, TRUE, func, user_data);
  if (hook == NULL)
    return;

  g_hook_destroy_link(hook_list, hook);
  if (hook_list->hooks == NULL) {
    g_hash_table_remove(gcb_callback_hash, key);
    g_free(hook_list);
  }
}

gboolean gnc_gconf_get_bool	(	const gchar *	section,
		const gchar *	name,
		GError **	error
	)

Get a boolean value from GConf.

Retrieve a TRUE/FALSE value from GConf. The section and key names provided as arguments are combined with the standard gnucash key prefix to produce a fully qualified key name. Either name (but not both) may be a fully qualified key path name, in which case it is used as is, without the standard gnucash prefix. This allows the program to access keys like standard desktop settings. Either name (but not both) may be NULL.

Parameters:

	section	This string provides a grouping of keys within the GnuCash section of the gconf database. It can be a simple string as in "history" for settings that are common to many areas of gnucash, or it can be a partial path name as in "dialogs/business/invoice" for setting that only apply to one specific area of the program.
	name	This string is the name of the particular key within the named section of gconf.
	error	An optional pointer to a GError structure. If NULL, this function will check for any errors returned by GConf and will display an error message via stdout. If present, this function will pass any error back to the calling function for it to handle.

Returns:

This function returns the TRUE or FALSE value stored at the requested key in the gconf database. If the key has never been set, this function passes on the default value returned by GConf as specified in the schema for this key. If there is an error in processing, this function passed on the value of FALSE as returned by GConf.

Definition at line 402 of file gnc-gconf-utils.c.

{
  GError *error = NULL;
  gboolean value;
  gchar *key;

  if (our_client == NULL)
    our_client = gconf_client_get_default();

  key = gnc_gconf_make_key(section, name);
  value = gconf_client_get_bool(our_client, key, &error);
  if (error) {
    gnc_gconf_load_error(key, caller_error, error);
  }
  g_free(key);
  return value;
}

gboolean gnc_gconf_get_bool_no_error	(	const gchar *	section,
		const gchar *	name
	)

Get a boolean value from GConf with no error argument.

Retrieve a TRUE/FALSE value from GConf. The section and key names provided as arguments are combined with the standard gnucash key prefix to produce a fully qualified key name. Either name (but not both) may be a fully qualified key path name, in which case it is used as is, without the standard gnucash prefix. This allows the program to access keys like standard desktop settings. Either name (but not both) may be NULL.

Parameters:

	section	This string provides a grouping of keys within the GnuCash section of the gconf database. It can be a simple string as in "history" for settings that are common to many areas of gnucash, or it can be a partial path name as in "dialogs/business/invoice" for setting that only apply to one specific area of the program.
	name	This string is the name of the particular key within the named section of gconf.

Returns:

This function returns the TRUE or FALSE value stored at the requested key in the gconf database. If the key has never been set, this function passes on the default value returned by GConf as specified in the schema for this key. If there is an error in processing, this function passed on the value of FALSE as returned by GConf.

Note:

This function was intended for use only by the guile wrapper functions. It should not be called from C code.

Definition at line 423 of file gnc-gconf-utils.c.

{
  return gnc_gconf_get_bool(section, name, NULL);
}

gdouble gnc_gconf_get_float	(	const gchar *	section,
		const gchar *	name,
		GError **	error
	)

Get an float value from GConf.

Retrieve an float value from GConf. The section and key names provided as arguments are combined with the standard gnucash key prefix to produce a fully qualified key name. Either name (but not both) may be a fully qualified key path name, in which case it is used as is, without the standard gnucash prefix. This allows the program to access keys like standard desktop settings. Either name (but not both) may be NULL.

Parameters:

	section	This string provides a grouping of keys within the GnuCash section of the gconf database. It can be a simple string as in "history" for settings that are common to many areas of gnucash, or it can be a partial path name as in "dialogs/business/invoice" for setting that only apply to one specific area of the program.
	name	This string is the name of the particular key within the named section of gconf.
	error	An optional pointer to a GError structure. If NULL, this function will check for any errors returned by GConf and will display an error message via stdout. If present, this function will pass any error back to the calling function for it to handle.

Returns:

This function returns the integer value stored at the requested key in the gconf database. If the key has never been set, this function passes on the default value returned by GConf as specified in the schema for this key. If there is an error in processing, this function passed on the value of zero as returned by GConf.

Definition at line 491 of file gnc-gconf-utils.c.

{
  GError *error = NULL;
  gint value;
  gchar *key;

  if (our_client == NULL)
    our_client = gconf_client_get_default();

  key = gnc_gconf_make_key(section, name);
  value = gconf_client_get_float(our_client, key, &error);
  if (error) {
    gnc_gconf_load_error(key, caller_error, error);
  }
  g_free(key);
  return value;
}

gint gnc_gconf_get_int	(	const gchar *	section,
		const gchar *	name,
		GError **	error
	)

Get an integer value from GConf.

Retrieve an integer value from GConf. The section and key names provided as arguments are combined with the standard gnucash key prefix to produce a fully qualified key name. Either name (but not both) may be a fully qualified key path name, in which case it is used as is, without the standard gnucash prefix. This allows the program to access keys like standard desktop settings. Either name (but not both) may be NULL.

Parameters:

	section	This string provides a grouping of keys within the GnuCash section of the gconf database. It can be a simple string as in "history" for settings that are common to many areas of gnucash, or it can be a partial path name as in "dialogs/business/invoice" for setting that only apply to one specific area of the program.
	name	This string is the name of the particular key within the named section of gconf.
	error	An optional pointer to a GError structure. If NULL, this function will check for any errors returned by GConf and will display an error message via stdout. If present, this function will pass any error back to the calling function for it to handle.

Returns:

This function returns the float value stored at the requested key in the gconf database. If the key has never been set, this function passes on the default value returned by GConf as specified in the schema for this key. If there is an error in processing, this function passed on the value of zero as returned by GConf.

Definition at line 450 of file gnc-gconf-utils.c.

{
  GError *error = NULL;
  gint value;
  gchar *key;

  if (our_client == NULL)
    our_client = gconf_client_get_default();

  key = gnc_gconf_make_key(section, name);
  value = gconf_client_get_int(our_client, key, &error);
  if (error) {
    gnc_gconf_load_error(key, caller_error, error);
  }
  g_free(key);
  return value;
}

GSList* gnc_gconf_get_list	(	const gchar *	section,
		const gchar *	name,
		GConfValueType	list_type,
		GError **	error
	)

Get a list of values from GConf.

Retrieve a list of values from GConf. This list may be of any kind of value understood by GConf, but all values in the list will be of the same type. The section and key names provided as arguments are combined with the standard gnucash key prefix to produce a fully qualified key name. Either name (but not both) may be a fully qualified key path name, in which case it is used as is, without the standard gnucash prefix. This allows the program to access keys like standard desktop settings. Either name (but not both) may be NULL.

Parameters:

	section	This string provides a grouping of keys within the GnuCash section of the gconf database. It can be a simple string as in "history" for settings that are common to many areas of gnucash, or it can be a partial path name as in "dialogs/business/invoice" for setting that only apply to one specific area of the program.
	name	This string is the name of the particular key within the named section of gconf.
	list_type	This enum indicates the type of each item in the returned list. This type must match the type off the stored items.
	error	An optional pointer to a GError structure. If NULL, this function will check for any errors returned by GConf and will display an error message via stdout. If present, this function will pass any error back to the calling function for it to handle.

Returns:

This function returns a list of value stored at the requested key in the gconf database. If the key has never been set, this function passes on the default value returned by GConf as specified in the schema for this key. If there is an error in processing, this function passed on the NULL value as returned by GConf. It is the callers responsibility to free any memory returned by this function. This include the list itself, and any list data that are string values.

Definition at line 577 of file gnc-gconf-utils.c.

{
  GError *error = NULL;
  GSList *value;
  gchar *key;

  if (our_client == NULL)
    our_client = gconf_client_get_default();

  key = gnc_gconf_make_key(section, name);
  value = gconf_client_get_list(our_client, key, list_type, &error);
  if (error) {
    gnc_gconf_load_error(key, caller_error, error);
  }
  g_free(key);
  return value;
}

GConfSchema* gnc_gconf_get_schema	(	const gchar *	section,
		const gchar *	name,
		GError **	caller_error
	)

Get a schema value from GConf.

Retrieve a schema value from GConf. The section and key names provided as arguments are combined with the standard gnucash key prefix to produce a fully qualified key name. Either name (but not both) may be a fully qualified key path name, in which case it is used as is, without the standard gnucash prefix. This allows the program to access keys like standard desktop settings. Either name (but not both) may be NULL.

Parameters:

	section	This string provides a grouping of keys within the GnuCash section of the gconf database. It can be a simple string as in "history" for settings that are common to many areas of gnucash, or it can be a partial path name as in "dialogs/business/invoice" for setting that only apply to one specific area of the program.
	name	This string is the name of the particular key within the named section of gconf.
	caller_error	An optional pointer to a GError structure. If NULL, this function will check for any errors returned by GConf and will display an error message via stdout. If present, this function will pass any error back to the calling function for it to handle.

Returns:

This function returns the schema stored at the requested key in the gconf database. If there is an error in processing, this function passed on the NULL value as returned by GConf. It is the callers responsibility to free any returned schema by calling the gconf_schema_free() function.

Definition at line 619 of file gnc-gconf-utils.c.

{
  GError *error = NULL;
  GConfSchema *value;
  gchar *key;

  if (our_client == NULL)
    our_client = gconf_client_get_default();

  key = gnc_gconf_make_key(section, name);
  value = gconf_client_get_schema(our_client, key, &error);
  if (error) {
    gnc_gconf_load_error(key, caller_error, error);
  }
  g_free(key);
  return value;
}

char* gnc_gconf_get_string	(	const gchar *	section,
		const gchar *	name,
		GError **	error
	)

Get a string value from GConf.

Retrieve an string value from GConf. The section and key names provided as arguments are combined with the standard gnucash key prefix to produce a fully qualified key name. Either name (but not both) may be a fully qualified key path name, in which case it is used as is, without the standard gnucash prefix. This allows the program to access keys like standard desktop settings. Either name (but not both) may be NULL.

Parameters:

	section	This string provides a grouping of keys within the GnuCash section of the gconf database. It can be a simple string as in "history" for settings that are common to many areas of gnucash, or it can be a partial path name as in "dialogs/business/invoice" for setting that only apply to one specific area of the program.
	name	This string is the name of the particular key within the named section of gconf.
	error	An optional pointer to a GError structure. If NULL, this function will check for any errors returned by GConf and will display an error message via stdout. If present, this function will pass any error back to the calling function for it to handle.

Returns:

This function returns the string value stored at the requested key in the gconf database. If the key has never been set, this function passes on the default value returned by GConf as specified in the schema for this key. If there is an error in processing, this function passed on the NULL value as returned by GConf. It is the callers responsibility to free any string returned by this function.

Definition at line 532 of file gnc-gconf-utils.c.

{
  GError *error = NULL;
  gchar *value;
  gchar *key;

  if (our_client == NULL)
    our_client = gconf_client_get_default();

  key = gnc_gconf_make_key(section, name);
  value = gconf_client_get_string(our_client, key, &error);
  if (error) {
    gnc_gconf_load_error(key, caller_error, error);
  }
  g_free(key);

  if (value && strlen(value) == 0) {
    g_free(value);
    return NULL;
  }
  return value;
}

void gnc_gconf_remove_anon_notification	(	const gchar *	section,
		guint	cnxn_id
	)

An alternative method for remove a callback from GConf; paired with gnc_gconf_add_anon_notification().

Remove a GConf callback function previously added with the gnc_gconf_add_notification function. The section name must be the same string provided when the callback function was added. This name is used to find/remove the callback.

Parameters:

	section	This string is used to find the correct notification function to remove from GConf.
	cnxn_id	An identification number returned by the gnc_gconf_add_anon_notification() function.

Definition at line 878 of file gnc-gconf-utils.c.

{
        GConfClient *client;
        gchar *path;

        /*
         * Remove any gconf notifications
         */
        path = gnc_gconf_section_name(section);
        client = gconf_client_get_default();
        if (client) {
          gconf_client_notify_remove(client, cnxn_id);
          gconf_client_remove_dir(client, path, NULL);
          g_object_unref(client);
        }
        g_free(path);
}

void gnc_gconf_remove_notification	(	GObject *	object,
		const gchar *	section,
		const gchar *	whoami
	)

Remove a callback from GConf.

Remove a GConf callback function previously added with the gnc_gconf_add_notification function. The section name must be the same string provided when the callback function was added. This name is used to find/remove the callback.

Parameters:

	object	This is a pointer to a GObject derivative. This must be the same object originally passed to the gnc_gconf_add_notification() function, as that function attached several values to the object that are needed by this function.
	section	This string is used to find the correct notification function to remove from GConf.
	whoami	A magic value that must match up this call to the corresponding call to gnc_gconf_add_notification(). The pair of section and whoami should be unique across all callers.

Definition at line 847 of file gnc-gconf-utils.c.

{
        GConfClient *client;
        gchar *path, *client_tag, *notify_tag;
        guint id;

        g_return_if_fail(G_IS_OBJECT(object));
        g_return_if_fail(whoami != NULL);

        /*
         * Remove any gconf notifications
         */
        client_tag = g_strdup_printf(CLIENT_TAG, section ? section:"", whoami);
        client = g_object_get_data(object, client_tag);
        path = gnc_gconf_section_name(section);
        if (client) {
          notify_tag = g_strdup_printf(NOTIFY_TAG, section ? section:"", whoami);
          id = GPOINTER_TO_UINT(g_object_get_data(object, notify_tag));
          gconf_client_notify_remove(client, id);
          gconf_client_remove_dir(client, path, NULL);
          g_object_unref(client);
          g_free(notify_tag);
        }
        g_free(path);
        g_free(client_tag);
}

char* gnc_gconf_schema_section_name

(

const char *

name

)

Convert a local schema key name to a full gconf schemapath name.

This function takes a gconf schema key name and converts it into a fully qualified gconf schema path name. It does this by prepending the standard path for all gnucash schema keys. It the key is already fully qualified (i.e. begins with the string "/schemas), this routine does not change the key.

Parameters:

name

A partial gconf schema key or section name. This name is added to the standard schema prefix to produce a fully qualified schema key name.

Returns:

This function returns a string pointer to the fully qualified path name of the gconf schema key. It is the caller's responsibility to free this string.

Definition at line 275 of file gnc-gconf-utils.c.

{
  if (strncmp(name, "/schemas", sizeof("/schemas")) == 0) {
    /* Need to return a newly allocated string */
    return g_strdup(name);
  }

  /* This could (should?) be accomplished with a call to
   * gnome_gconf_get_app_settings_relative(), but that would introduce
   * a new library dependancy, even though its not a gui library.  In
   * order to keep this file completely "gnome-free" this approach was
   * used.
   */
  return g_strconcat("/schemas", gnc_get_gconf_path(), "/", name, NULL);
}

gboolean gnc_gconf_schemas_found

(

void

)

Check gconf to see if the schema for one of the gnucash keys can be found. This function is called to determine whether or not to launch a druid to help the user properly set up GConf for Gnucash.

Returns:

This function returns TRUE if it was able to find a schema.

Definition at line 900 of file gnc-gconf-utils.c.

{
  GConfSchema* schema;
  GError *err = NULL;
  gchar *key;

  if (our_client == NULL)
    our_client = gconf_client_get_default();

  key = gnc_gconf_make_schema_key(GCONF_GENERAL_REGISTER, "use_theme_colors");
  schema = gconf_client_get_schema(our_client, key, &err);
  g_free(key);
  if (schema == NULL) {
    return FALSE;
  }
  gconf_schema_free(schema);

  /* Set up convenience callback for general section */
  
  gconf_general_cb_id =
    gnc_gconf_add_anon_notification(GCONF_GENERAL, gnc_gconf_general_changed,
                                    NULL);
    return TRUE;
}

char* gnc_gconf_section_name

(

const char *

name

)

Convert a local key name to a full gconf path name.

This function takes a gconf key name and converts it into a fully qualified gconf path name. It does this by prepending the standard path for all gnucash keys. It the key is already fully qualified (i.e. begins with a '/' character), this routine does not change the key.

Parameters:

name

A partial gconf key or section name. This name is added to the standard prefix to produce a fully qualified key name.

Returns:

This function returns a string pointer to the fully qualified path name of the gconf key. It is the caller's responsibility to free this string.

Definition at line 254 of file gnc-gconf-utils.c.

{
  if (name == NULL) {
    /* Need to return a newly allocated string */
    return g_strdup(gnc_get_gconf_path());
  }
  if (*name == '/') {
    /* Need to return a newly allocated string */
    return g_strdup(name);
  }

  /* This could (should?) be accomplished with a call to
   * gnome_gconf_get_app_settings_relative(), but that would introduce
   * a new library dependancy, even though its not a gui library.  In
   * order to keep this file completely "gnome-free" this approach was
   * used.
   */
  return g_strjoin("/", gnc_get_gconf_path(), name, NULL);
}

void gnc_gconf_set_bool	(	const gchar *	section,
		const gchar *	name,
		const gboolean	value,
		GError **	error
	)

Store a boolean value into GConf.

Store a boolean value into GConf. The section and key names provided as arguments are combined with the standard gnucash key prefix to produce a fully qualified key name. Either name (but not both) may be a fully qualified key path name, in which case it is used as is, without the standard gnucash prefix. This allows the program to access keys like standard desktop settings. Either name (but not both) may be NULL.

Parameters:

	section	This string provides a grouping of keys within the GnuCash section of the gconf database. It can be a simple string as in "history" for settings that are common to many areas of gnucash, or it can be a partial path name as in "dialogs/business/invoice" for setting that only apply to one specific area of the program.
	name	This string is the name of the particular key within the named section of gconf.
	value	The TRUE/FALSE value to be stored.
	error	An optional pointer to a GError structure. If NULL, this function will check for any errors returned by GConf and will display an error message via stdout. If present, this function will pass any error back to the calling function for it to handle.

Definition at line 430 of file gnc-gconf-utils.c.

{
  GError *error = NULL;
  gchar *key;

  if (our_client == NULL)
    our_client = gconf_client_get_default();

  /* Remember whether the column width */
  key = gnc_gconf_make_key(section, name);
  if (!gconf_client_set_bool(our_client, key, value, &error)) {
    gnc_gconf_save_error(key, caller_error, error);
  }
  g_free(key);
}

void gnc_gconf_set_float	(	const gchar *	section,
		const gchar *	name,
		const gdouble	value,
		GError **	error
	)

Store an float value into GConf.

Store an float into GConf. The section and key names provided as arguments are combined with the standard gnucash key prefix to produce a fully qualified key name. Either name (but not both) may be a fully qualified key path name, in which case it is used as is, without the standard gnucash prefix. This allows the program to access keys like standard desktop settings. Either name (but not both) may be NULL.

Parameters:

	section	This string provides a grouping of keys within the GnuCash section of the gconf database. It can be a simple string as in "history" for settings that are common to many areas of gnucash, or it can be a partial path name as in "dialogs/business/invoice" for setting that only apply to one specific area of the program.
	name	This string is the name of the particular key within the named section of gconf.
	value	The number to be stored.
	error	An optional pointer to a GError structure. If NULL, this function will check for any errors returned by GConf and will display an error message via stdout. If present, this function will pass any error back to the calling function for it to handle.

Definition at line 512 of file gnc-gconf-utils.c.

{
  GError *error = NULL;
  gchar *key;

  if (our_client == NULL)
    our_client = gconf_client_get_default();

  /* Remember whether the column width */
  key = gnc_gconf_make_key(section, name);
  if (!gconf_client_set_float(our_client, key, value, &error)) {
    gnc_gconf_save_error(key, caller_error, error);
  }
  g_free(key);
}

void gnc_gconf_set_int	(	const gchar *	section,
		const gchar *	name,
		const gint	value,
		GError **	error
	)

Store an integer value into GConf.

Store an integer into GConf. The section and key names provided as arguments are combined with the standard gnucash key prefix to produce a fully qualified key name. Either name (but not both) may be a fully qualified key path name, in which case it is used as is, without the standard gnucash prefix. This allows the program to access keys like standard desktop settings. Either name (but not both) may be NULL.

Parameters:

	section	This string provides a grouping of keys within the GnuCash section of the gconf database. It can be a simple string as in "history" for settings that are common to many areas of gnucash, or it can be a partial path name as in "dialogs/business/invoice" for setting that only apply to one specific area of the program.
	name	This string is the name of the particular key within the named section of gconf.
	value	The number to be stored.
	error	An optional pointer to a GError structure. If NULL, this function will check for any errors returned by GConf and will display an error message via stdout. If present, this function will pass any error back to the calling function for it to handle.

Definition at line 471 of file gnc-gconf-utils.c.

{
  GError *error = NULL;
  gchar *key;

  if (our_client == NULL)
    our_client = gconf_client_get_default();

  /* Remember whether the column width */
  key = gnc_gconf_make_key(section, name);
  if (!gconf_client_set_int(our_client, key, value, &error)) {
    gnc_gconf_save_error(key, caller_error, error);
  }
  g_free(key);
}

void gnc_gconf_set_list	(	const gchar *	section,
		const gchar *	name,
		GConfValueType	list_type,
		GSList *	value,
		GError **	error
	)

Store a list of values into GConf.

Store a list of values into GConf. This list may be of any kind of value understood by GConf, but all values in the list must be of the same type. The section and key names provided as arguments are combined with the standard gnucash key prefix to produce a fully qualified key name. Either name (but not both) may be a fully qualified key path name, in which case it is used as is, without the standard gnucash prefix. This allows the program to access keys like standard desktop settings. Either name (but not both) may be NULL.

Parameters:

	section	This string provides a grouping of keys within the GnuCash section of the gconf database. It can be a simple string as in "history" for settings that are common to many areas of gnucash, or it can be a partial path name as in "dialogs/business/invoice" for setting that only apply to one specific area of the program.
	name	This string is the name of the particular key within the named section of gconf.
	list_type	This enum indicates the type of each item in the list to be stored.
	value	The list of items to be stored. Each item in the list must be of the type specified. E.G. If the list_type is GCONF_VALUE_STRING, then the data field of each element in the list must be a string pointer.
	error	An optional pointer to a GError structure. If NULL, this function will check for any errors returned by GConf and will display an error message via stdout. If present, this function will pass any error back to the calling function for it to handle.

Definition at line 599 of file gnc-gconf-utils.c.

{
  GError *error = NULL;
  gchar *key;

  if (our_client == NULL)
    our_client = gconf_client_get_default();

  key = gnc_gconf_make_key(section, name);
  if (!gconf_client_set_list(our_client, key, list_type, value, &error)) {
    gnc_gconf_save_error(key, caller_error, error);
  }
  g_free(key);
}

void gnc_gconf_set_string	(	const gchar *	section,
		const gchar *	name,
		const gchar *	value,
		GError **	error
	)

Store a string into GConf.

Store a single string into GConf. The section and key names provided as arguments are combined with the standard gnucash key prefix to produce a fully qualified key name. Either name (but not both) may be a fully qualified key path name, in which case it is used as is, without the standard gnucash prefix. This allows the program to access keys like standard desktop settings. Either name (but not both) may be NULL.

Parameters:

	section	This string provides a grouping of keys within the GnuCash section of the gconf database. It can be a simple string as in "history" for settings that are common to many areas of gnucash, or it can be a partial path name as in "dialogs/business/invoice" for setting that only apply to one specific area of the program.
	name	This string is the name of the particular key within the named section of gconf.
	value	The string to be stored. GConf will make a copy of this string, so it is the callers responsibility to free the space used by this string (if necessary).
	error	An optional pointer to a GError structure. If NULL, this function will check for any errors returned by GConf and will display an error message via stdout. If present, this function will pass any error back to the calling function for it to handle.

Definition at line 558 of file gnc-gconf-utils.c.

{
  GError *error = NULL;
  gchar *key;

  if (our_client == NULL)
    our_client = gconf_client_get_default();

  key = gnc_gconf_make_key(section, name);
  if (!gconf_client_set_string(our_client, key, value, &error)) {
    gnc_gconf_save_error(key, caller_error, error);
  }
  g_free(key);
}

void gnc_gconf_suggest_sync

(

void

)

Tell GConf to propagate changes.

This function tells gconf that changes have been made and that is should propagate its internal state to permanent storage and any other clients. This function is a suggestion to gconf, not a directive, and is therefore should be considered optional. Doesn't hurt to call it though if you've made numerous changes to gconf in a short period of time.

Definition at line 728 of file gnc-gconf-utils.c.

{
  GError *error = NULL;

  if (our_client == NULL)
    our_client = gconf_client_get_default();

  gconf_client_suggest_sync(our_client, &error);
  if (error != NULL) {
    printf("Failed to sync gconf: %s", error->message);
    g_error_free(error);
  }
}

void gnc_gconf_unset	(	const gchar *	section,
		const gchar *	name,
		GError **	error
	)

Delete a value from GConf.

Completely remove a value from GConf. The next attempt to read this value will return the default as specified in the GConf schema for this key. The section and key names provided as arguments are combined with the standard gnucash key prefix to produce a fully qualified key name. Either name (but not both) may be a fully qualified key path name, in which case it is used as is, without the standard gnucash prefix. This allows the program to access keys like standard desktop settings. Either name (but not both) may be NULL.

Parameters:

	section	This string provides a grouping of keys within the GnuCash section of the gconf database. It can be a simple string as in "history" for settings that are common to many areas of gnucash, or it can be a partial path name as in "dialogs/business/invoice" for setting that only apply to one specific area of the program.
	name	This string is the name of the particular key within the named section of gconf.
	error	An optional pointer to a GError structure. If NULL, this function will check for any errors returned by GConf and will display an error message via stdout. If present, this function will pass any error back to the calling function for it to handle.

Definition at line 660 of file gnc-gconf-utils.c.

{
  GError *error = NULL;
  gchar *key;

  if (our_client == NULL)
    our_client = gconf_client_get_default();

  key = gnc_gconf_make_key(section, name);
  if (!gconf_client_unset(our_client, key, &error)) {
    if (caller_error) {
      g_propagate_error(caller_error, error);
    } else {
      printf("Failed to unset key %s: %s", key, error->message);
      g_error_free(error);
    }
  }
  g_free(key);
}