gconfmm: Gnome::Conf::Client Class Reference

Inheritance diagram for Gnome::Conf::Client:

Collaboration diagram for Gnome::Conf::Client:

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

gconfmm: Gnome::Conf::Client Class Reference

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Related Functions

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation