Main Page | Modules | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | File Members

Gnome::Conf::Client Class Reference

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

#include <client.h>

Inheritance diagram for Gnome::Conf::Client:

[legend]
List of all members.

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 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.
Glib::SListHandle< Entryall_entries (const Glib::ustring &dir) const
 Retrieve all keys in the given configuration directory.
Glib::SListHandle< Glib::ustringall_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 &) const
 Determine whether a given configuration directory exists.
bool key_is_writable (const Glib::ustring &) 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.
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< Clientget_default_client ()
 Get the default client object for this application.
static Glib::RefPtr< Clientget_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::Clientwrap (GConfClient *object, bool take_copy=false)

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.


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

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. 

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. 

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

Provides access to the underlying C GObject.

Reimplemented from Glib::ObjectBase.

GConfClient* Gnome::Conf::Client::gobj  )  [inline]
 

Provides access to the underlying C GObject.

Reimplemented from Glib::ObjectBase.

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

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

Returns:
true if the key is writeable.
Exceptions:
Gnome::Conf::Error. 

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::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,
const Value what
[virtual]
 

Set the given configuration key to the specified 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.

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.

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.

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.

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,
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_error_handling ClientErrorHandlingMode  mode  ) 
 

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.

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

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]
 

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:
Generated on Tue Feb 1 03:31:18 2005 for gconfmm by  doxygen 1.4.1