Reference Manual |
![]() |
#include <inti/gconf/client.h>
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.
|
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). |
|
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). |
|
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. |
|
Construct a new Client from an existing GConfClient.
The client can be a newly created GConfClient or an existing GConfClient. (see G::Object::Object). |
|
Add a directory to the list of directories the Client will watch.
See add_dir(const char*, PreloadType, G::Error*) for details. |
|
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 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. |
|
Lists the subdirectories in dir.
|
|
Lists the key-value pairs in dir. Does not list subdirectories; for that use all_dirs().
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. |
|
Creates a change set that will change the keys in the vector of 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. |
|
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. |
|
Applies the changes in the change set to the Client.
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. |
|
Queries whether the directory dir exists in the GConf database.
|
|
Emits the "error" signal. Rarely useful.
|
|
Get the current value stored at key, or null if no value is set.
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. |
|
Requests the bool value (VALUE_BOOL) stored at key.
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. |
|
Creates a new Client using the default GConfEngine; normally this is the engine you want.
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. |
|
Get the value for key in the default schema.
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. |
|
Obtain the full GConf::Entry for a value.
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(). |
|
Requests the floating point number (VALUE_FLOAT) stored at key.
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. |
|
Creates a new GConfClient with a specific GConfEngine.
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. |
|
Requests the integer (VALUE_INT) stored at key.
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. |
|
Requests the list (VALUE_SCHEMA) stored at key.
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. |
|
Requests the list (VALUE_STRING) stored at key.
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. |
|
Requests the list (VALUE_FLOAT) stored at key.
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. |
|
Requests the list (VALUE_BOOL) stored at key.
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. |
|
Requests the list (VALUE_INT) stored at key.
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. |
|
Requests the pair (VALUE_INT/VALUE_INT) stored at key.
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; } |
|
Requests the schema (VALUE_SCHEMA) stored at key.
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. |
|
Requests the string (VALUE_STRING) stored at key.
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. |
|
Get the current value for the key.
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. |
|
Checks wether the key is writable.
|
|
Request notification of changes to namespace_section.
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. |
|
Remove a notification using the ID returned from notify_add().
|
|
Emitted whenever an error occurs inside a Client method.
Depending on the ErrorHandlingMode, the default handler for this signal may or may not display an error dialog. |
|
Emitted when you pass null for the G::Error* argument to any Client method, and an error occurs.
Depending on the ErrorHandlingMode, the default handler for this signal may or may not display an error dialog. |
|
Emitted when a key below one of the directories added with add_dir() receives a new value or is unset.
|
|
Preloads a directory.
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. |
|
Remove a directory from the list created with add_dir().
See remove_dir(const char*, PreloadType, G::Error*) for details. |
|
Remove a directory from the list created with add_dir().
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. |
|
Create a change set that would revert the given change set for the Client.
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. |
|
Sets the value for a configuration key.
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. |
|
Sets the bool value (VALUE_BOOL) for a key.
Note that you still should call suggest_sync(). |
|
Controls the default error handling for the Client.
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(). |
|
Sets the floating point value (VALUE_FLOAT) for a key.
Note that you still should call suggest_sync(). |
|
Sets the integer value (VALUE_INT) for key.
Note that you still should call suggest_sync(). |
|
Sets the list (VALUE_SCHEMA) for a key.
|
|
Sets the list (VALUE_STRING) for a key.
|
|
Sets the list (VALUE_FLOAT) for a key.
|
|
Sets the list (VALUE_BOOL) for a key.
|
|
Sets the list (VALUE_INT) for a key.
|
|
Sets the pair (VALUE_INT/VALUE_INT) for a key.
|
|
Sets the Schema value (VALUE_SCHEMA) for a key.
Note that you still should call suggest_sync(). |
|
Sets the String value (VALUE_STRING) for a key.
Note that you still should call suggest_sync(). |
|
Suggests to gconfd that you've just finished a block of changes, and it would be an optimal time to sync to permanent storage.
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. |
|
Unsets the value of key; if key is already unset, it has no effect.
An error of note is GCONF_OVERRIDDEN, indicating that the system administrator has forced a value for this key. |
|
Emits the "value_changed" signal. Rarely useful.
|
|
Generated on Sun Sep 14 23:52:40 2003 for Inti-GConf by ![]() |