gconfmm: Gnome::Conf::Client Class Reference

gconfmm 2.28.3

- Main Page
- Modules
- Namespaces
- Classes

- Class List
- Class Index
- Class Hierarchy
- Class Members

Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Related Functions
Gnome::Conf::Client Class Reference

The main Gnome::Conf object. More...

Inheritance diagram for Gnome::Conf::Client:
[legend]
Collaboration diagram for Gnome::Conf::Client:
[legend]

List of all members.

## Public Types
typedef Glib::SListHandle< int, BasicTypeTraits< int > > | SListHandleInts
typedef Glib::SListHandle < bool, BasicTypeTraits< bool > > | SListHandleBools
typedef Glib::SListHandle < double, BasicTypeTraits < double > > | SListHandleFloats
## Public Member Functions
virtual | ~Client ()
GConfClient* | gobj ()
| Provides access to the underlying C GObject.
const GConfClient* | gobj () const
| Provides access to the underlying C GObject.
GConfClient* | gobj_copy ()
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
void | add_dir (const Glib::ustring& dir, ClientPreloadType preload=CLIENT_PRELOAD_NONE)
| Add a directory to the list of directories the Client will watch.
void | remove_dir (const Glib::ustring& dir)
| Remove a directory from the list of directories the Client will watch.
guint | notify_add (const Glib::ustring& namespace_section, Callback callback)
| Request notification of changes to namespace_section.
void | notify_remove (guint cnxn)
| Cancel a notification request.
void | notify (const Glib::ustring& key)
| Emits the value_changed signal and notifies listeners as if key had been changed.
void | set_error_handling (ClientErrorHandlingMode mode)
void | clear_cache ()
| Clear the client-side cache.
void | preload (const Glib::ustring& dirname, ClientPreloadType type)
| Preloads a directory.
Value | get (const Glib::ustring& key) const
| Get the value of a configuration key.
Value | get_without_default (const Glib::ustring& key) const
| Get the value of a configuration key, without falling back to the default if the key has not been set.
Value | get_default_from_schema (const Glib::ustring& key) const
| Get the default value of this key by looking it up in the appropriate schema.
Entry | get_entry (const Glib::ustring& key, bool use_schema_default=true) const
| Get the complete Entry of the specified key.
Entry | get_entry (const Glib::ustring& key, const char* locale, bool use_schema_default=true) const
| Get the complete Entry of the specified key.
void | unset (const Glib::ustring& key)
| Unset a configuration key.
void | recursive_unset (const Glib::ustring& key, UnsetFlags flags=UNSET_INCLUDING_SCHEMA_NAMES)
| Unsets all keys below key, including key itself.
Glib::SListHandle< Entry > | all_entries (const Glib::ustring& dir) const
| Retrieve all keys in the given configuration directory.
Glib::SListHandle< Glib::ustring > | all_dirs (const Glib::ustring& dir) const
| Retrieve all subdirectories of a given configuration directory.
void | suggest_sync ()
| Suggest to the GConf server that a sync of cached data to stable storage would be appropriate now.
bool | dir_exists (const Glib::ustring& p1) const
| Determine whether a given configuration directory exists.
bool | key_is_writable (const Glib::ustring& p1) const
| Determine whether a given configuration key is writeable by the application.
double | get_float (const Glib::ustring& key) const
| Get the float value at the given configuration key.
gint | get_int (const Glib::ustring& key) const
| Get the integer at the given configuration key.
bool | get_bool (const Glib::ustring& key) const
| Get the boolean at the given configuration key.
Glib::ustring | get_string (const Glib::ustring& key) const
| Get the string at the given configuration key.
Schema | get_schema (const Glib::ustring& key) const
| Get the Schema at the given configuration key.
SListHandle_ValueInt | get_int_list (const Glib::ustring& key) const
| Get the list of integers at the given configuration key.
SListHandle_ValueBool | get_bool_list (const Glib::ustring& key) const
| Get the list of booleans at the given configuration key.
SListHandle_ValueFloat | get_float_list (const Glib::ustring& key) const
| Get the list of doubles at the given configuration key.
SListHandle_ValueSchema | get_schema_list (const Glib::ustring& key) const
| Get the list of Schemas at the given configuration key.
SListHandle_ValueString | get_string_list (const Glib::ustring& key) const
| Get the list of strings at the given configuration key.
ValuePair | get_pair (const Glib::ustring& key, ValueTypePair types) const
| Get the pair at the given configuration key.
void | set (const Glib::ustring& key, int what)
| Set the given configuration key to the specified integer value.
void | set (const Glib::ustring& key, bool what)
| Set the given configuration key to the specified boolean value.
void | set (const Glib::ustring& key, double what)
| Set the given configuration key to the specified double value.
void | set (const Glib::ustring& key, const Glib::ustring& what)
| Set the given configuration key to the specified string.
void | set (const Glib::ustring& key, const Schema& what)
| Set the given configuration key to the specified Schema.
void | set (const Glib::ustring& key, const Value& what)
| Set the given configuration key to the specified Value.
void | set_int_list (const Glib::ustring& key, const SListHandleInts& what)
void | set_bool_list (const Glib::ustring& key, const SListHandleBools& what)
void | set_float_list (const Glib::ustring& key, const SListHandleFloats& what)
void | set_schema_list (const Glib::ustring& key, const Glib::SListHandle< Schema >& what)
void | set_string_list (const Glib::ustring& key, const Glib::SListHandle< Glib::ustring >& what)
ChangeSet | change_set_from_current (const Glib::SArray& set)
| Create a ChangeSet from the current values of the configuration database.
void | change_set_commit (ChangeSet& set, bool remove_commited)
| Commit the ChangeSet to the configuration database.
ChangeSet | change_set_reverse (const ChangeSet& set)
| Creates a ChangeSet to reverse the effects of the given ChangeSet.
Glib::SignalProxy2< void, const Glib::ustring &, const Value& > | signal_value_changed ()
| A signal emitted when a value changes.
void | value_changed (const Glib::ustring& key, const Value&value)
Glib::SignalProxy1< void, const Glib::Error& > | signal_error ()
| A signal emitted when an error occurs.
void | error (const Glib::Error& error)
## Static Public Member Functions
static Glib::RefPtr< Client > | get_default_client ()
| Get the default client object for this application.
static Glib::RefPtr< Client > | get_client_for_engine (GConfEngine* engine)
## Protected Member Functions
virtual void | on_value_changed (const Glib::ustring& key, const Value&value)
virtual void | on_unreturned_error (const Glib::Error& error)
virtual void | on_error (const Glib::Error& error)
## Related Functions
(Note that these are not member functions.)
Glib::RefPtr< Gnome::Conf::Client > | wrap (GConfClient* object, bool take_copy=false)
| A Glib::wrap() method for this object.

## Detailed Description

The main Gnome::Conf object.

This class allows you to interface withe the Gnome configuration system. Generally, it stores key-value pairs. The keys have an hierarchical namespace, with elements separated by slashes. The values are either typed primitives (int, bool, string, float or a `Schema`), or lists of primitives or pairs of primitives (for limits on the compound values, see Value). For conventions on the names of keys, see the GConf documentation.

## Member Typedef Documentation

typedef Glib::SListHandle< bool, BasicTypeTraits<bool> > Gnome::Conf::Client::SListHandleBools

typedef Glib::SListHandle< double, BasicTypeTraits<double> > Gnome::Conf::Client::SListHandleFloats

typedef Glib::SListHandle< int, BasicTypeTraits<int> > Gnome::Conf::Client::SListHandleInts

## Constructor & Destructor Documentation

virtual Gnome::Conf::Client::~Client | ( |  | ) | `[virtual]`

## Member Function Documentation

void Gnome::Conf::Client::add_dir | ( | const Glib::ustring & | dir,
|  | ClientPreloadType | preload = `CLIENT_PRELOAD_NONE`
| ) |  |

Add a directory to the list of directories the Client will watch.

Any changes to keys below this directory will cause the "value_changed" signal to be emitted. When you add the directory, you can request that the Client preloads its contents - see ClientPreloadType for details.

Added directories may not overlap. That is, if you add "/foo", you may not add "/foo/bar". However you can add "/foo" and "/bar". You can also add "/foo" multiple times; if you add a directory multiple times, it will not be removed until you call remove_dir() an equal number of times.

Parameters:

  dir,: | the directory to watch.
  preload,: | the preload type (if any) to be performed.

Glib::SListHandle<Glib::ustring> Gnome::Conf::Client::all_dirs | ( | const Glib::ustring & | dir | ) | const

Retrieve all subdirectories of a given configuration directory.

Parameters:

  dir,: | the configuration directory to scan.

Returns:
  a container with the names of the subdirectories.

Exceptions:

  Gnome::Conf::Error. |

Glib::SListHandle<Entry> Gnome::Conf::Client::all_entries | ( | const Glib::ustring & | dir | ) | const

Retrieve all keys in the given configuration directory.

Get all the configuration keys in the given directory, without recursion.

Parameters:

  dir,: | the configuration directory to scan.

Returns:
  a container with the names of the configuration keys.

Exceptions:

  Gnome::Conf::Error. |

void Gnome::Conf::Client::change_set_commit | ( | ChangeSet& | set,
|  | bool | remove_commited
| ) |  |

Commit the ChangeSet to the configuration database.

Commits the configuration changes in the ChangeSet to the database. If `remove_commited` is `true`, all successfully commited keys will be removed from the ChangeSet. If an error occurs, a Gnome::Conf::Error will be thrown. This operation is not atomic - an error will be thrown on the first error.

Parameters:

  set | the ChangeSet to commit.
  remove_commited | whether to remove successfully-commited keys from the ChangeSet.

Exceptions:

  Gnome::Conf::Error |

See also:
  ChangeSet

ChangeSet Gnome::Conf::Client::change_set_from_current | ( | const Glib::SArray & | set | ) |

Create a ChangeSet from the current values of the configuration database.

Creates a ChangeSet containing the current values of all the keys listed in the `set`. For instance, this could be used in a preferences dialog as an undo operation.

Parameters:

  set | A container of the configuration keys to backup.

Returns:
  the ChangeSet with the current values.

Exceptions:

  Gnome::Conf::Error |

See also:
  ChangeSet

ChangeSet Gnome::Conf::Client::change_set_reverse | ( | const ChangeSet& | set | ) |

Creates a ChangeSet to reverse the effects of the given ChangeSet.

Creates a ChangeSet that contains the current values of the keys in `set`, effectively creating a back-up of the values in the database that will be modifed when the `set` will be commited. For instance, this allows you to create a back-up changeset to use in case of errors, or an undo facility for preferences.

Parameters:

  set | the ChangeSet to reverse.

Returns:
  the reverse ChangeSet.

Exceptions:

  Gnome::Conf::Error |

See also:
  ChangeSet

void Gnome::Conf::Client::clear_cache | ( |  | ) |

Clear the client-side cache.

bool Gnome::Conf::Client::dir_exists | ( | const Glib::ustring & | p1 | ) | const

Determine whether a given configuration directory exists.

Returns:
  true if the directory exists.

Exceptions:

  Gnome::Conf::Error. |

void Gnome::Conf::Client::error | ( | const Glib::Error & | error | ) |

Value Gnome::Conf::Client::get | ( | const Glib::ustring & | key | ) | const

Get the value of a configuration key.

key: the configuration key to retrieve.

Returns:
  the Value of the key.

Exceptions:

  Gnome::Conf::Error. |

bool Gnome::Conf::Client::get_bool | ( | const Glib::ustring & | key | ) | const

Get the boolean at the given configuration key.

SListHandle_ValueBool Gnome::Conf::Client::get_bool_list | ( | const Glib::ustring & | key | ) | const

Get the list of booleans at the given configuration key.

static Glib::RefPtr<Client> Gnome::Conf::Client::get_client_for_engine | ( | GConfEngine * | engine | ) | `[static]`

static Glib::RefPtr<Client> Gnome::Conf::Client::get_default_client | ( |  | ) | `[static]`

Get the default client object for this application.

The object is a Singleton, so you will always get the same instance. Most applications should use this.

Value Gnome::Conf::Client::get_default_from_schema | ( | const Glib::ustring & | key | ) | const

Get the default value of this key by looking it up in the appropriate schema.

key: the configuration key to retrieve.

Returns:
  the default Value of the key.

Exceptions:

  Gnome::Conf::Error. |

Entry Gnome::Conf::Client::get_entry | ( | const Glib::ustring & | key,
|  | bool | use_schema_default = `true`
| ) |  | const

Get the complete Entry of the specified key.

Uses the default locale

Parameters:

  key | the configuration key to retrieve.
  use_schema_default | whether to fall back to the Schema default value if the specified configuration key has not been set.

Returns:
  an Entry for the corresponding configuration key.

Exceptions:

  Gnome::Conf::Error. |

Entry Gnome::Conf::Client::get_entry | ( | const Glib::ustring & | key,
|  | const char * | locale,
|  | bool | use_schema_default = `true`
| ) |  | const

Get the complete Entry of the specified key.

Parameters:

  key | the configuration key to retrieve.
  locale | the locale for the user-visible strings in the Entry's Schema. Use 0 to use the default.
  use_schema_default | whether to fall back to the Schema default value if the specified configuration key has not been set.

Returns:
  an Entry for the corresponding configuration key.

Exceptions:

  Gnome::Conf::Error. |

double Gnome::Conf::Client::get_float | ( | const Glib::ustring & | key | ) | const

Get the float value at the given configuration key.

Throws an error if the key does not contain the appropriate type.

Parameters:

  key,: | the configuration key to fetch.

Returns:
  the value at the specified configuration key.

Exceptions:

  Gnome::Conf::Error |

SListHandle_ValueFloat Gnome::Conf::Client::get_float_list | ( | const Glib::ustring & | key | ) | const

Get the list of doubles at the given configuration key.

gint Gnome::Conf::Client::get_int | ( | const Glib::ustring & | key | ) | const

Get the integer at the given configuration key.

SListHandle_ValueInt Gnome::Conf::Client::get_int_list | ( | const Glib::ustring & | key | ) | const

Get the list of integers at the given configuration key.

If the given key is not a list, or the list elements are not of the appropriate type, an error will be thrown.

Parameters:

  key | the configuration key that contains the list.

Returns:
  a Glib::SListHandle of the appropriate type.

Exceptions:

  Gnome::Conf::Error |

ValuePair Gnome::Conf::Client::get_pair | ( | const Glib::ustring & | key,
|  | ValueTypePair | types
| ) |  | const

Get the pair at the given configuration key.

The pair's elements must have the types given in `types` respectively. If the value is not a pair or the types do not match, an error will be thrown.

Parameters:

  key | the configuration key that contains the pair.
  types | a pair of the expected types of the values.

Returns:
  a ValuePair.

Exceptions:

  Gnome::Conf::Error |

Schema Gnome::Conf::Client::get_schema | ( | const Glib::ustring & | key | ) | const

Get the Schema at the given configuration key.

SListHandle_ValueSchema Gnome::Conf::Client::get_schema_list | ( | const Glib::ustring & | key | ) | const

Get the list of Schemas at the given configuration key.

Glib::ustring Gnome::Conf::Client::get_string | ( | const Glib::ustring & | key | ) | const

Get the string at the given configuration key.

SListHandle_ValueString Gnome::Conf::Client::get_string_list | ( | const Glib::ustring & | key | ) | const

Get the list of strings at the given configuration key.

Value Gnome::Conf::Client::get_without_default | ( | const Glib::ustring & | key | ) | const

Get the value of a configuration key, without falling back to the default if the key has not been set.

In that case, the type of the value will be VALUE_INVALID.

Parameters:

  key,: | the configuration key to retrieve.

Returns:
  the Value of the key.

Exceptions:

  Gnome::Conf::Error. |

GConfClient* Gnome::Conf::Client::gobj | ( |  | ) | `[inline]`

Provides access to the underlying C GObject.

const GConfClient* Gnome::Conf::Client::gobj | ( |  | ) | const`[inline]`

Provides access to the underlying C GObject.

GConfClient* Gnome::Conf::Client::gobj_copy | ( |  | ) |

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

bool Gnome::Conf::Client::key_is_writable | ( | const Glib::ustring & | p1 | ) | const

Determine whether a given configuration key is writeable by the application.

Returns:
  true if the key is writeable.

Exceptions:

  Gnome::Conf::Error. |

void Gnome::Conf::Client::notify | ( | const Glib::ustring & | key | ) |

Emits the value_changed signal and notifies listeners as if key had been changed.

Parameters:

  key | The key that has changed.

guint Gnome::Conf::Client::notify_add | ( | const Glib::ustring & | namespace_section,
|  | Callback | callback
| ) |  |

Request notification of changes to namespace_section.

This includes the key `namespace_section` itself, and any keys below it. For the notification to happen, `namespace_section` must be equal to or below one of the directories added with add_dir(). You can still call notify_add() for other directories, but no notification will be received until you add a directory above or equal to `namespace_section`. One implication of this is that remove_dir() temporarily disables notifications that were below the removed directory.

The callback will be called with the key that changed and the Entry that holds the new Value. If the Value has a type of VALUE_INVALID, then the key has been unset.

The function returns a connection ID you can use when calling notify_remove().

Parameters:

  namespace_section,: | the namespace section for which notification is required.
  callback,: | the sigc::slot to call when the a key under namespace_section changes.

Returns:
  a connection id that can be passed to notify_remove() to cancel the notification request.

void Gnome::Conf::Client::notify_remove | ( | guint | cnxn | ) |

Cancel a notification request.

Parameters:

  cnxn,: | a connection id, previously returned by notify_add()

See also:
  notify_add()

virtual void Gnome::Conf::Client::on_error | ( | const Glib::Error & | error | ) | `[protected, virtual]`

virtual void Gnome::Conf::Client::on_unreturned_error | ( | const Glib::Error & | error | ) | `[protected, virtual]`

virtual void Gnome::Conf::Client::on_value_changed | ( | const Glib::ustring & | key,
|  | const Value& | value
| ) |  | `[protected, virtual]`

void Gnome::Conf::Client::preload | ( | const Glib::ustring & | dirname,
|  | ClientPreloadType | type
| ) |  |

Preloads a directory.

Normally this happens automatically with add_dir(), but if you've called clear_cache() you may need to do it again.

See also:
  add_dir()

void Gnome::Conf::Client::recursive_unset | ( | const Glib::ustring & | key,
|  | UnsetFlags | flags = `UNSET_INCLUDING_SCHEMA_NAMES`
| ) |  |

Unsets all keys below key, including key itself.

If any unset fails, it continues on to unset as much as it can. The first failure is then thrown as an exception.

Parameters:

  key | The configuration key to unset.
  flags | Change how the unset is done.

Exceptions:

  Gnome::Conf::Error. |

void Gnome::Conf::Client::remove_dir | ( | const Glib::ustring & | dir | ) |

Remove a directory from the list of directories the Client will watch.

See also:
  add_dir()

void Gnome::Conf::Client::set | ( | const Glib::ustring & | key,
|  | int | what
| ) |  | `[virtual]`

Set the given configuration key to the specified integer value.

Parameters:

  key | the configuration key to set.
  what | the value to set it to.

Exceptions:

  Gnome::Conf::Error |

Implements Gnome::Conf::SetInterface.

void Gnome::Conf::Client::set | ( | const Glib::ustring & | key,
|  | bool | what
| ) |  | `[virtual]`

Set the given configuration key to the specified boolean value.

Set the given configuration key to the specified integer value.

Parameters:

  key | the configuration key to set.
  what | the value to set it to.

Exceptions:

  Gnome::Conf::Error |

Implements Gnome::Conf::SetInterface.

void Gnome::Conf::Client::set | ( | const Glib::ustring & | key,
|  | double | what
| ) |  | `[virtual]`

Set the given configuration key to the specified double value.

Set the given configuration key to the specified integer value.

Parameters:

  key | the configuration key to set.
  what | the value to set it to.

Exceptions:

  Gnome::Conf::Error |

Implements Gnome::Conf::SetInterface.

void Gnome::Conf::Client::set | ( | const Glib::ustring & | key,
|  | const Glib::ustring & | what
| ) |  | `[virtual]`

Set the given configuration key to the specified string.

Set the given configuration key to the specified integer value.

Parameters:

  key | the configuration key to set.
  what | the value to set it to.

Exceptions:

  Gnome::Conf::Error |

Implements Gnome::Conf::SetInterface.

void Gnome::Conf::Client::set | ( | const Glib::ustring & | key,
|  | const Schema& | what
| ) |  | `[virtual]`

Set the given configuration key to the specified Schema.

Set the given configuration key to the specified integer value.

Parameters:

  key | the configuration key to set.
  what | the value to set it to.

Exceptions:

  Gnome::Conf::Error |

Implements Gnome::Conf::SetInterface.

void Gnome::Conf::Client::set | ( | const Glib::ustring & | key,
|  | const Value& | what
| ) |  | `[virtual]`

Set the given configuration key to the specified Value.

Set the given configuration key to the specified integer value.

Parameters:

  key | the configuration key to set.
  what | the value to set it to.

Exceptions:

  Gnome::Conf::Error |

Implements Gnome::Conf::SetInterface.

void Gnome::Conf::Client::set_bool_list | ( | const Glib::ustring & | key,
|  | const SListHandleBools& | what
| ) |  |

void Gnome::Conf::Client::set_error_handling | ( | ClientErrorHandlingMode | mode | ) |

void Gnome::Conf::Client::set_float_list | ( | const Glib::ustring & | key,
|  | const SListHandleFloats& | what
| ) |  |

void Gnome::Conf::Client::set_int_list | ( | const Glib::ustring & | key,
|  | const SListHandleInts& | what
| ) |  |

void Gnome::Conf::Client::set_schema_list | ( | const Glib::ustring & | key,
|  | const Glib::SListHandle< Schema >& | what
| ) |  |

void Gnome::Conf::Client::set_string_list | ( | const Glib::ustring & | key,
|  | const Glib::SListHandle< Glib::ustring > & | what
| ) |  |

Glib::SignalProxy1< void,const Glib::Error& > Gnome::Conf::Client::signal_error | ( |  | ) |

A signal emitted when an error occurs.

This signal will be emitted when an error occurs, right before the throw() of the error.

Prototype:
  `void on_my_error(const Glib::Error& error)`

Glib::SignalProxy2< void,const Glib::ustring&,const Value& > Gnome::Conf::Client::signal_value_changed | ( |  | ) |

A signal emitted when a value changes.

This signal will only be called for directories added with add_dir().

Prototype:
  `void on_my_value_changed(const Glib::ustring& key, const Value& value)`

void Gnome::Conf::Client::suggest_sync | ( |  | ) |

Suggest to the GConf server that a sync of cached data to stable storage would be appropriate now.

Exceptions:

  Gnome::Conf::Error. |

void Gnome::Conf::Client::unset | ( | const Glib::ustring & | key | ) |

Unset a configuration key.

Parameters:

  key | the configuration key to unset.

Exceptions:

  Gnome::Conf::Error. |

void Gnome::Conf::Client::value_changed | ( | const Glib::ustring & | key,
|  | const Value& | value
| ) |  |

## Friends And Related Function Documentation

Glib::RefPtr< Gnome::Conf::Client > wrap | ( | GConfClient * | object,
|  | bool | take_copy = `false`
| ) |  | `[related]`

A Glib::wrap() method for this object.

Parameters:

  object | The C instance.
  take_copy | False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns:
  A C++ instance that wraps this C instance.

The documentation for this class was generated from the following file:

- gconfmm/client.h