gconfmm 2.28.3
Gnome::Conf::Client Class Reference

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

#include <gconfmm/client.h>

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< Entryall_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)
 
- Public Member Functions inherited from Gnome::Conf::SetInterface
void set (const Glib::ustring& key, const ValuePair&pair)
 
void set_int_list (const Glib::ustring& key, const SListHandle_ValueInt& list)
 
void set_bool_list (const Glib::ustring& key, const SListHandle_ValueBool& list)
 
void set_float_list (const Glib::ustring& key, const SListHandle_ValueFloat& list)
 
void set_string_list (const Glib::ustring& key, const SListHandle_ValueString& list)
 
void set_schema_list (const Glib::ustring& key, const SListHandle_ValueSchema& list)
 

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 Symbols

(Note that these are not member symbols.)

Glib::RefPtr< Gnome::Conf::Clientwrap (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

◆ SListHandleBools

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

◆ SListHandleFloats

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

◆ SListHandleInts

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

Constructor & Destructor Documentation

◆ ~Client()

virtual Gnome::Conf::Client::~Client ( )
virtual

Member Function Documentation

◆ add_dir()

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
dirthe directory to watch.
preloadthe preload type (if any) to be performed.

◆ all_dirs()

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

Retrieve all subdirectories of a given configuration directory.

Parameters
dirthe configuration directory to scan.
Returns
a container with the names of the subdirectories.
Exceptions
Gnome::Conf::Error.

◆ all_entries()

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
dirthe configuration directory to scan.
Returns
a container with the names of the configuration keys.
Exceptions
Gnome::Conf::Error.

◆ change_set_commit()

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
setthe ChangeSet to commit.
remove_commitedwhether to remove successfully-commited keys from the ChangeSet.
Exceptions
Gnome::Conf::Error
See also
ChangeSet

◆ change_set_from_current()

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
setA container of the configuration keys to backup.
Returns
the ChangeSet with the current values.
Exceptions
Gnome::Conf::Error
See also
ChangeSet

◆ change_set_reverse()

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
setthe ChangeSet to reverse.
Returns
the reverse ChangeSet.
Exceptions
Gnome::Conf::Error
See also
ChangeSet

◆ clear_cache()

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

Clear the client-side cache.

◆ dir_exists()

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.

◆ error()

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

◆ get()

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

Get the value of a configuration key.

@parameter key: the configuration key to retrieve.

Returns
the Value of the key.
Exceptions
Gnome::Conf::Error.

◆ get_bool()

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

Get the boolean at the given configuration key.

◆ get_bool_list()

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

Get the list of booleans at the given configuration key.

◆ get_client_for_engine()

static Glib::RefPtr< Client > Gnome::Conf::Client::get_client_for_engine ( GConfEngine * engine)
static

◆ get_default_client()

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.

◆ get_default_from_schema()

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.

@parameter key: the configuration key to retrieve.

Returns
the default Value of the key.
Exceptions
Gnome::Conf::Error.

◆ get_entry() [1/2]

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
keythe configuration key to retrieve.
use_schema_defaultwhether 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.

◆ get_entry() [2/2]

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
keythe configuration key to retrieve.
localethe locale for the user-visible strings in the Entry's Schema. Use 0 to use the default.
use_schema_defaultwhether 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.

◆ get_float()

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
keythe configuration key to fetch.
Returns
the value at the specified configuration key.
Exceptions
Gnome::Conf::Error

◆ get_float_list()

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

Get the list of doubles at the given configuration key.

◆ get_int()

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

Get the integer at the given configuration key.

◆ get_int_list()

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
keythe configuration key that contains the list.
Returns
a Glib::SListHandle of the appropriate type.
Exceptions
Gnome::Conf::Error

◆ get_pair()

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
keythe configuration key that contains the pair.
typesa pair of the expected types of the values.
Returns
a ValuePair.
Exceptions
Gnome::Conf::Error

◆ get_schema()

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

Get the Schema at the given configuration key.

◆ get_schema_list()

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

Get the list of Schemas at the given configuration key.

◆ get_string()

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

Get the string at the given configuration key.

◆ get_string_list()

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

Get the list of strings at the given configuration key.

◆ get_without_default()

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
keythe configuration key to retrieve.
Returns
the Value of the key.
Exceptions
Gnome::Conf::Error.

◆ gobj() [1/2]

GConfClient * Gnome::Conf::Client::gobj ( )
inline

Provides access to the underlying C GObject.

◆ gobj() [2/2]

const GConfClient * Gnome::Conf::Client::gobj ( ) const
inline

Provides access to the underlying C GObject.

◆ gobj_copy()

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.

◆ key_is_writable()

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.

◆ notify()

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

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

Parameters
keyThe key that has changed.

@newin2p24

◆ notify_add()

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_sectionthe namespace section for which notification is required.
callbackthe 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.

◆ notify_remove()

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

Cancel a notification request.

Parameters
cnxna connection id, previously returned by notify_add()
See also
notify_add()

◆ on_error()

virtual void Gnome::Conf::Client::on_error ( const Glib::Error & error)
protectedvirtual

◆ on_unreturned_error()

virtual void Gnome::Conf::Client::on_unreturned_error ( const Glib::Error & error)
protectedvirtual

◆ on_value_changed()

virtual void Gnome::Conf::Client::on_value_changed ( const Glib::ustring & key,
const Value& value )
protectedvirtual

◆ preload()

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

◆ recursive_unset()

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
keyThe configuration key to unset.
flagsChange how the unset is done.
Exceptions
Gnome::Conf::Error.

@newin2p24

◆ remove_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()

◆ set() [1/6]

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
keythe configuration key to set.
whatthe value to set it to.
Exceptions
Gnome::Conf::Error

Implements Gnome::Conf::SetInterface.

◆ set() [2/6]

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
keythe configuration key to set.
whatthe value to set it to.
Exceptions
Gnome::Conf::Error

Implements Gnome::Conf::SetInterface.

◆ set() [3/6]

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
keythe configuration key to set.
whatthe value to set it to.
Exceptions
Gnome::Conf::Error

Implements Gnome::Conf::SetInterface.

◆ set() [4/6]

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
keythe configuration key to set.
whatthe value to set it to.
Exceptions
Gnome::Conf::Error

Implements Gnome::Conf::SetInterface.

◆ set() [5/6]

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
keythe configuration key to set.
whatthe value to set it to.
Exceptions
Gnome::Conf::Error

Implements Gnome::Conf::SetInterface.

◆ set() [6/6]

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

Set the given configuration key to the specified integer value.

Parameters
keythe configuration key to set.
whatthe value to set it to.
Exceptions
Gnome::Conf::Error

Implements Gnome::Conf::SetInterface.

◆ set_bool_list()

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

◆ set_error_handling()

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

◆ set_float_list()

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

◆ set_int_list()

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

◆ set_schema_list()

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

◆ set_string_list()

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

◆ signal_error()

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)

◆ signal_value_changed()

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)

◆ suggest_sync()

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.

◆ unset()

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

Unset a configuration key.

Parameters
keythe configuration key to unset.
Exceptions
Gnome::Conf::Error.

◆ value_changed()

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

Friends And Related Symbol Documentation

◆ wrap()

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

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

Parameters
objectThe C instance.
take_copyFalse 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: