Reference Manual

Inti Logo
Main Page | Namespace List | Alphabetical List | Compound List | File List | Namespace Members | Compound Members | File Members

Inti::GConf::Client Class Reference

A GConfClient C++ wrapper class. More...

#include <inti/gconf/client.h>

List of all members.

Public Types

Public Member Functions

Constructors
Accessors
Methods
Signal Proxies

Static Public Member Functions

Protected Member Functions

Signal Handlers

Detailed Description

A GConfClient C++ wrapper class.

GConf::Client adds to plain GConf a client-side cache for a specified list of directories you're interested in. You can preload entire directories into the cache, speeding things up even more. There is automatic error handling, if you request it, and signals when a value changes or an error occurs.


Member Typedef Documentation

typedef Slot2<void, unsigned int, const Entry&> Inti::GConf::Client::NotifySlot
 

Signature for the notify method invoked when the value of a key changes.

Example: Method signature for NotifySlot.

             void method(unsigned int cnxn_id, const Entry& entry);
            
             // cnxn_id: The connection indentifier returned by notify_add().
             // entry: The Entry holding the new value. Entry::is_set() returns false if the value was unset.

The value argument should not be modified, and should be copied if you want to keep it around (the Client will destroy it sometime after your notify method is called).


Member Enumeration Documentation

enum Inti::GConf::Client::ErrorHandlingMode
 

ErrorHandlingMode is used to control GConf::Client's default error handling.

GConf::Client can pop up a dialog in the default signal handler for "error" or "unreturned_error". You can specify that no errors are handled, only unreturned errors are handled, or all errors are handled with this enumeration. You can prevent specific errors from being handled automatically by stopping the signal emission before the default signal handler is called (see the GTK+ documentation, gtk_signal_emit_stop_by_name() for example).

Enumeration values:
HANDLE_NONE  never run a default error handler.
HANDLE_UNRETURNED  run a default error handler for unreturned errors ("unreturned_error" signal).
HANDLE_ALL  run a default error handler for all errors ("error" signal).

enum Inti::GConf::Client::PreloadType
 

PreloadType is used to tell GConf::Client how to preload one of its directories.

As a rule of thumb, if you plan to get the value of almost all the keys in a directory, preloading that directory will probably enhance performance. If you plan to use only half the keys, preloading is likely a bad idea.

Enumeration values:
PRELOAD_NONE  No preload occurs.
PRELOAD_ONELEVEL  Loads the immediate children of the directory.
PRELOAD_RECURSIVE  Loads all children of the directory and its subdirectories, recursively.


Constructor & Destructor Documentation

Inti::GConf::Client::Client GConfClient *  client,
bool  reference = true
[explicit, protected]
 

Construct a new Client from an existing GConfClient.

Parameters:
client A pointer to a GConfClient.
reference Set false if the initial reference count is floating, set true if it's not.

The client can be a newly created GConfClient or an existing GConfClient. (see G::Object::Object).


Member Function Documentation

void Inti::GConf::Client::add_dir const String &  dir,
PreloadType  preload,
G::Error *  error = 0
 

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

Parameters:
dir Directory to add to the list.
preload Degree of preload.
error A G::Error object, or null to ignore errors.

See add_dir(const char*, PreloadType, G::Error*) for details.

void Inti::GConf::Client::add_dir const char *  dir,
PreloadType  preload,
G::Error *  error = 0
 

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

Parameters:
dir Directory to add to the list.
preload Degree of preload.
error A G::Error object, or null to ignore errors.

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 to preload 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 gconf_client_remove_dir() an equal number of times.

std::vector<String> Inti::GConf::Client::all_dirs const String &  dir,
G::Error *  error = 0
 

Lists the subdirectories in dir.

Parameters:
dir The directory to get subdirectories from.
error A G::Error object, or null to ignore errors.
Returns:
a standard vector of Strings that are subdirectory names.

std::vector<Entry> Inti::GConf::Client::all_entries const String &  dir,
G::Error *  error = 0
 

Lists the key-value pairs in dir.

Does not list subdirectories; for that use all_dirs().

Parameters:
dir The directory to list.
error A G::Error object, or null to ignore errors.
Returns:
A standard vector of Entry objects.

The returned vector contains GConf::Entry objects. A GConf::Entry contains a relative key and a value. The list is not recursive, it contains only the immediate children of dir.

Pointer<ChangeSet> Inti::GConf::Client::change_set_from_current const std::vector< String >  keys,
G::Error *  error = 0
 

Creates a change set that will change the keys in the vector of keys to their current state.

Parameters:
keys A vector of key names.
error A G::Error object, or null to ignore errors.
Returns:
A new change set that changes all the keys to their current state.

Use this to save the current state of a collection of keys; then you can later revert to the current state by committing the returned change set.

void Inti::GConf::Client::clear_cache  ) 
 

Dumps everything out of the Client client-side cache.

If you know you're done using the Client for a while, you can call this method to save some memory. Note that this nullifies the effect of any preloading you may have done.

bool Inti::GConf::Client::commit_change_set ChangeSet cs,
bool  remove_committed,
G::Error *  error = 0
 

Applies the changes in the change set to the Client.

Parameters:
cs A ChangeSet.
remove_committed Whether to remove successfully-committed changes from the set.
error A G::Error object, or null to ignore errors.
Returns:
true on success, false if an error occurs.

If remove_committed is true, then any successfully-committed changes are removed from the change set. If remove_committed is false, the ChangeSet is left unmodified. If any set or unset operation results in an error, then processing terminates and the error is returned in error (unless error was was). If remove_committed was true, then all the changes committed before the error occurred will have been removed from the set. If any error occurs, false is returned.

bool Inti::GConf::Client::dir_exists const String &  dir,
G::Error *  error = 0
const
 

Queries whether the directory dir exists in the GConf database.

Parameters:
dir The directory to check for.
error A G::Error object, or null to ignore errors.
Returns:
true if the directory exists.

void Inti::GConf::Client::error G::Error &  error  ) 
 

Emits the "error" signal.

Rarely useful.

Parameters:
error A reference to the error to pass to signal handlers.

Value Inti::GConf::Client::get const String &  key,
G::Error *  error = 0
const
 

Get the current value stored at key, or null if no value is set.

Parameters:
key The key to get.
error A G::Error object, or null to ignore errors.
Returns:
a Value object.

If you know the expected type of the value, you probably want to use the type-specific convenience wrappers (get_int(), etc.) because they will do the type-checking for you and return the appropriate type. Automatically returns the default value for a key, if the key is unset and a default exists.

bool Inti::GConf::Client::get_bool const String &  key,
G::Error *  error = 0
const
 

Requests the bool value (VALUE_BOOL) stored at key.

Parameters:
key The key you want the value of.
error A G::Error object, or null to ignore errors.
Returns:
The value of key, or false if no value is obtained.

Automatically performs type-checking, so if a non-bool is stored at key, an error is returned. On error, or if key is unset, false is returned.

Pointer<Client> Inti::GConf::Client::get_default  )  [static]
 

Creates a new Client using the default GConfEngine; normally this is the engine you want.

Returns:
A smart pointer to the new Client.

If someone else is already using the default Client, this function returns the same one they're using, but with the reference count incremented. So it has to be unreferenced either way. To save you the trouble a smart pointer is returned. The smart pointer will unreference the Client when it goes out of scope.

Value Inti::GConf::Client::get_default_from_schema const String &  key,
G::Error *  error = 0
const
 

Get the value for key in the default schema.

Parameters:
key The key to get.
error A G::Error object, or null to ignore errors.
Returns:
A Value object.

Returns the default value stored in the key's schema, if the key has a schema associated and the schema exists and the schema contains a default value. Note that get(), get_string(), and so on already return the default value if no other value is found, so normally you do not need this function. This function is just for convenience; you could also get the GConf::MetaInfo for the key, read the schema name from there, then look up the schema by name and extract the default value.

Entry Inti::GConf::Client::get_entry const String &  key,
const String &  locale,
bool  use_schema_default,
G::Error *  error = 0
const
 

Obtain the full GConf::Entry for a value.

Parameters:
key The key to get.
locale Locales not implemented yet; pass null for this value (not "").
use_schema_default Set true to return default value for key, instead of VALUE_INVALID.
error A G::Error object, or null to ignore errors.
Returns:
an Entry object.

An Entry object stores an entry from a GConf directory, including a key-value pair, the name of the schema applicable to this entry, whether the value is a default value, and whether GConf can write a new value at this key. key should be an absolute key, not a relative key. To access the key and value, use Entry::get_key() and Entry::get_value().

double Inti::GConf::Client::get_float const String &  key,
G::Error *  error = 0
const
 

Requests the floating point number (VALUE_FLOAT) stored at key.

Parameters:
key The key you want the value of.
error A G::Error object, or null to ignore errors.
Returns:
The value of key, or 0.0 if no value is obtained.

Automatically performs type-checking, so if a non-float is stored at key, an error is returned. On error, or if key is unset, 0.0 is returned.

Pointer<Client> Inti::GConf::Client::get_for_engine GConfEngine *  engine  )  [static]
 

Creates a new GConfClient with a specific GConfEngine.

Parameters:
engine The GConfEngine to use.
Returns:
A smart pointer to the new Client.

Only specialized configuration-related programs should need to call this function. Remember to avoid using the GConfEngine directly once you have a GConfClient wrapper. The smart pointer will unreference the Client when it goes out of scope.

int Inti::GConf::Client::get_int const String &  key,
G::Error *  error = 0
const
 

Requests the integer (VALUE_INT) stored at key.

Parameters:
key The key you want the value of.
error A G::Error object, or null to ignore errors.
Returns:
The value of key, or 0 if no value is obtained.

Automatically performs type-checking, so if a non-integer is stored at key, an error is returned. On error, or if key is unset, 0 is returned.

bool Inti::GConf::Client::get_list const String &  key,
std::vector< Schema > &  list,
G::Error *  error = 0
const
 

Requests the list (VALUE_SCHEMA) stored at key.

Parameters:
key The key you want the value of.
list A reference to a vector of Schema, to hold the list elements.
error A G::Error object, or null to ignore errors.
Returns:
true on success, false if an error occurs.

Automatically performs type-checking, so if a non-list is stored at key, or the list does not contain elements of type VALUE_SCHEMA, an error is returned. If no value is set or an error occurs, false is returned.

bool Inti::GConf::Client::get_list const String &  key,
std::vector< String > &  list,
G::Error *  error = 0
const
 

Requests the list (VALUE_STRING) stored at key.

Parameters:
key The key you want the value of.
list A reference to a vector of String, to hold the list elements.
error A G::Error object, or null to ignore errors.
Returns:
true on success, false if an error occurs.

Automatically performs type-checking, so if a non-list is stored at key, or the list does not contain elements of type VALUE_STRING, an error is returned. If no value is set or an error occurs, false is returned.

bool Inti::GConf::Client::get_list const String &  key,
std::vector< double > &  list,
G::Error *  error = 0
const
 

Requests the list (VALUE_FLOAT) stored at key.

Parameters:
key The key you want the value of.
list A reference to a vector of double, to hold the list elements.
error A G::Error object, or null to ignore errors.
Returns:
true on success, false if an error occurs.

Automatically performs type-checking, so if a non-list is stored at key, or the list does not contain elements of type VALUE_FLOAT, an error is returned. If no value is set or an error occurs, false is returned.

bool Inti::GConf::Client::get_list const String &  key,
std::vector< bool > &  list,
G::Error *  error = 0
const
 

Requests the list (VALUE_BOOL) stored at key.

Parameters:
key The key you want the value of.
list A reference to a vector of bool, to hold the list elements.
error A G::Error object, or null to ignore errors.
Returns:
true on success, false if an error occurs.

Automatically performs type-checking, so if a non-list is stored at key, or the list does not contain elements of type VALUE_BOOL, an error is returned. If no value is set or an error occurs, false is returned.

bool Inti::GConf::Client::get_list const String &  key,
std::vector< int > &  list,
G::Error *  error = 0
const
 

Requests the list (VALUE_INT) stored at key.

Parameters:
key The key you want the value of.
list A reference to a vector of int, to hold the list elements.
error A G::Error object, or null to ignore errors.
Returns:
true on success, false if an error occurs.

Automatically performs type-checking, so if a non-list is stored at key, or the list does not contain elements of type VALUE_INT, an error is returned. If no value is set or an error occurs, false is returned.

bool Inti::GConf::Client::get_pair const String &  key,
int &  car_data,
int &  cdr_data,
G::Error *  error = 0
const
 

Requests the pair (VALUE_INT/VALUE_INT) stored at key.

Parameters:
key The key you want the value of.
car_data Reference to the return location for the car.
cdr_data Reference to the return location for the cdr.
error A G::Error object, or null to ignore errors.
Returns:
true on success, false if an error occurs.

Automatically performs type-checking, so if a non-pair is stored at key, an error is returned. Remember that the car of a pair is its first value, and the cdr is its second value, in the Lisp tradition. get_pair() stores the two fields of the pair in the locations pointed to by car_data and cdr_data. If there's an error or the value is unset, car_data and cdr_data are left unchanged.

Example: An example of get_pair() in action.

             #include <iostream>
             int car = 10;
             String cdr;
             G::Error error;
            
             Pointer<GConf::Client> client = GConf::Client::get_default();
             if (!client->get_pair("/foo", car, cdr, &error))
             {
                 // Note: car/cdr should be untouched, because an error occurred.
                 if (error.get())
                     std::cout << error.mesage() << std::endl;
             }
             else
             {
                 // Note: car/cdr may be untouched even though there was no error, if no value was set for "/foo".
                 std::cout << "Found pair (" << car << "," << cdr << ")" << std::endl;
             }

Schema Inti::GConf::Client::get_schema const String &  key,
G::Error *  error = 0
const
 

Requests the schema (VALUE_SCHEMA) stored at key.

Parameters:
key The key you want the value of.
error A G::Error object, or null to ignore errors.
Returns:
The value of key as a Schema object, or null if no value was obtained.

Automatically performs type-checking, so if a non-schema is stored at key, an error is returned. If no value is set or an error occurs, null is returned. Note that this returns the schema stored at key, NOT the schema that key conforms to.

String Inti::GConf::Client::get_string const String &  key,
G::Error *  error = 0
const
 

Requests the string (VALUE_STRING) stored at key.

Parameters:
key The key you want the value of.
error A G::Error object, or null to ignore errors.
Returns:
The string (value of key), or a null string if no value is obtained.

Automatically performs type-checking, so if a non-string is stored at key, an error is returned. On error, or if key is unset, a null string is returned.

Value Inti::GConf::Client::get_without_default const String &  key,
G::Error *  error = 0
const
 

Get the current value for the key.

Parameters:
key The key to get.
error A G::Error object, or null to ignore errors.
Returns:
a Value object.

Identical to get(), except that it will return null in place of the default value if the key is unset. Note that get() can also return null if no default exists or an error occurs.

bool Inti::GConf::Client::key_is_writable const String &  key,
G::Error *  error = 0
const
 

Checks wether the key is writable.

Parameters:
key The key to check.
error A G::Error object, or null to ignore errors.
Returns:
true if the key is writable.

unsigned int Inti::GConf::Client::notify_add const String &  namespace_section,
NotifySlot slot,
G::Error *  error = 0
 

Request notification of changes to namespace_section.

Parameters:
namespace_section Where to listen for changes.
slot A NotifySlot to call when changes occur.
error A G::Error object, or null to ignore errors.
Returns:
A connection ID for removing the notification.

This includes the key namespace_section itself, and any keys below it (the behavior is identical to gconf_engine_notify_add(), but while gconf_engine_notify_add() places a notification request on the server for every notify function, GConf::Client requests server notification for directories added with add_dir() and keeps the list of NotifySlots on the client side).

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 method returns a connection ID you can use to call notify_remove().See the description of NotifySlot for details on how the notification method is called.

void Inti::GConf::Client::notify_remove unsigned int  connect_id  ) 
 

Remove a notification using the ID returned from notify_add().

Parameters:
connect_id The connection indentifier.

virtual void Inti::GConf::Client::on_error const G::Error &  error  )  [protected, virtual]
 

Emitted whenever an error occurs inside a Client method.

Parameters:
error An Error object.

Depending on the ErrorHandlingMode, the default handler for this signal may or may not display an error dialog.

virtual void Inti::GConf::Client::on_unreturned_error const G::Error &  error  )  [protected, virtual]
 

Emitted when you pass null for the G::Error* argument to any Client method, and an error occurs.

Parameters:
error The unhandled error.

Depending on the ErrorHandlingMode, the default handler for this signal may or may not display an error dialog.

virtual void Inti::GConf::Client::on_value_changed const String &  key,
const Value value
[protected, virtual]
 

Emitted when a key below one of the directories added with add_dir() receives a new value or is unset.

Parameters:
key The GConf key whose value has changed.
value The new value if set, or null if unset.
Called when a key below one of the directories added with add_dir() receives a new value or is unset. It can be much more efficient to use notify_add().

void Inti::GConf::Client::preload const String &  dirname,
PreloadType  type,
G::Error *  error = 0
 

Preloads a directory.

Parameters:
dirname The name of the directory to preload.
type The degree of preload.
error A G::Error object, or null to ignore errors.

Normally you do this when you call add_dir(), but if you've called clear_cache() there may be a reason to do it again. Not useful otherwise.

void Inti::GConf::Client::remove_dir const String &  dir,
G::Error *  error = 0
 

Remove a directory from the list created with add_dir().

Parameters:
dir Directory to remove from the list.
error A G::Error object, or null to ignore errors.

See remove_dir(const char*, PreloadType, G::Error*) for details.

void Inti::GConf::Client::remove_dir const char *  dir,
G::Error *  error = 0
 

Remove a directory from the list created with add_dir().

Parameters:
dir Directory to remove from the list.
error A G::Error object, or null to ignore errors.

If any notifications have been added below this directory with notify_add(), those notifications will be disabled until you re-add the removed directory. Note that if a directory has been added multiple times, you must remove it the same number of times before the remove takes effect.

Pointer<ChangeSet> Inti::GConf::Client::reverse_change_set ChangeSet cs,
G::Error *  error = 0
 

Create a change set that would revert the given change set for the Client.

Parameters:
cs The change set to create the reverse of.
error A G::Error object, or null to ignore errors.
Returns:
A new change set that would restore the current state of each key in cs.

Creates a change set that would reverse cs. That is, for each change in cs, save the current state of that key in the returned change set.

void Inti::GConf::Client::set const String &  key,
const Value value,
G::Error *  error = 0
 

Sets the value for a configuration key.

Parameters:
key A key to set.
value The new value.
error A G::Error object, or null to ignore errors.

Just like gconf_engine_set(), but uses the Client caching and error-handling features. The value argument will not be modified. These keys do not have to be in the client's directory list, but they won't be cached unless they are.

bool Inti::GConf::Client::set_bool const String &  key,
bool  value,
G::Error *  error = 0
 

Sets the bool value (VALUE_BOOL) for a key.

Parameters:
key The key you want to set.
value The new value.
error A G::Error object, or null to ignore errors.
Returns:
true on success, or false if an error occurs.

Note that you still should call suggest_sync().

void Inti::GConf::Client::set_error_handling ErrorHandlingMode  mode  ) 
 

Controls the default error handling for the Client.

Parameters:
mode The error handling mode.

If you don't want the default handler, set the error handling to CLIENT_HANDLE_NONE. Error handling happens in the default signal handler, so you can selectively override the default handling by connecting to the error signal and calling g_signal_emission_stop().

bool Inti::GConf::Client::set_float const String &  key,
double  value,
G::Error *  error = 0
 

Sets the floating point value (VALUE_FLOAT) for a key.

Parameters:
key The key you want to set.
value The new value.
error A G::Error object, or null to ignore errors.
Returns:
true on success, or false if an error occurs.

Note that you still should call suggest_sync().

bool Inti::GConf::Client::set_int const String &  key,
int  value,
G::Error *  error = 0
 

Sets the integer value (VALUE_INT) for key.

Parameters:
key The key you want to set.
value The new value.
error A G::Error object, or null to ignore errors.
Returns:
true on success, or false if an error occurs.

Note that you still should call suggest_sync().

bool Inti::GConf::Client::set_list const String &  key,
const std::vector< Schema > &  list,
G::Error *  error = 0
 

Sets the list (VALUE_SCHEMA) for a key.

Parameters:
key The key you want set.
list A reference to a vector of String that contains the list elements.
error A G::Error object, or null to ignore errors.
Returns:
true on success, false if an error occurs.

bool Inti::GConf::Client::set_list const String &  key,
const std::vector< String > &  list,
G::Error *  error = 0
 

Sets the list (VALUE_STRING) for a key.

Parameters:
key The key you want set.
list A reference to a vector of String that contains the list elements.
error A G::Error object, or null to ignore errors.
Returns:
true on success, false if an error occurs.

bool Inti::GConf::Client::set_list const String &  key,
const std::vector< double > &  list,
G::Error *  error = 0
 

Sets the list (VALUE_FLOAT) for a key.

Parameters:
key The key you want set.
list A reference to a vector of double that contains the list elements.
error A G::Error object, or null to ignore errors.
Returns:
true on success, false if an error occurs.

bool Inti::GConf::Client::set_list const String &  key,
const std::vector< bool > &  list,
G::Error *  error = 0
 

Sets the list (VALUE_BOOL) for a key.

Parameters:
key The key you want set.
list A reference to a vector of bool that contains the list elements.
error A G::Error object, or null to ignore errors.
Returns:
true on success, false if an error occurs.

bool Inti::GConf::Client::set_list const String &  key,
const std::vector< int > &  list,
G::Error *  error = 0
 

Sets the list (VALUE_INT) for a key.

Parameters:
key The key you want set.
list A reference to a vector of int that contains the list elements.
error A G::Error object, or null to ignore errors.
Returns:
true on success, false if an error occurs.

bool Inti::GConf::Client::set_pair const String &  key,
int  car_data,
int  cdr_data,
G::Error *  error = 0
 

Sets the pair (VALUE_INT/VALUE_INT) for a key.

Parameters:
key The key you want to set.
car_data The new value for the first field (car).
cdr_data The new value for the second field (cdr).
error A G::Error object, or null to ignore errors.
Returns:
true on success, false if an error occurs.

bool Inti::GConf::Client::set_schema const String &  key,
const Schema value,
G::Error *  error = 0
 

Sets the Schema value (VALUE_SCHEMA) for a key.

Parameters:
key The key you want to set.
value The new value.
error A G::Error object, or null to ignore errors.
Returns:
true on success, or false if an error occurs.

Note that you still should call suggest_sync().

bool Inti::GConf::Client::set_string const String &  key,
const String &  value,
G::Error *  error = 0
 

Sets the String value (VALUE_STRING) for a key.

Parameters:
key The key you want to set.
value The new value.
error A G::Error object, or null to ignore errors.
Returns:
true on success, or false if an error occurs.

Note that you still should call suggest_sync().

void Inti::GConf::Client::suggest_sync G::Error *  error = 0  ) 
 

Suggests to gconfd that you've just finished a block of changes, and it would be an optimal time to sync to permanent storage.

Parameters:
error A G::Error object, or null to ignore errors.

This is only a suggestion; and gconfd will eventually sync even if you don't call suggest_sync(). This method is just a "hint" provided to gconfd to maximize efficiency and minimize data loss.

bool Inti::GConf::Client::unset const String &  key,
G::Error *  error = 0
 

Unsets the value of key; if key is already unset, it has no effect.

Parameters:
key A key to unset.
error A G::Error object, or null to ignore errors.
Returns:
true on success, false on error.

An error of note is GCONF_OVERRIDDEN, indicating that the system administrator has forced a value for this key.

void Inti::GConf::Client::value_changed const String &  key,
Value value
 

Emits the "value_changed" signal.

Rarely useful.

Parameters:
key The key to pass to signal handlers.
value The value of key to pass to signal handlers.


The documentation for this class was generated from the following file: Main Page - Footer


Generated on Sun Sep 14 23:52:40 2003 for Inti-GConf by doxygen 1.3.2 written by Dimitri van Heesch, © 1997-2002