An opaque structure that holds state about a channel. Either creates a new channel, or fetches a singleton object for @channel_name. This function always returns a valid object; no checking is done to see if the channel exists or has a valid name. The reference count of the returned channel is owned by libxfconf. An #XfconfChannel singleton. A channel name. Creates a new channel using @name as the channel's identifier. This function always returns a valid object; no checking is done to see if the channel exists or has a valid name. Note: use of this function is not recommended, in favor of xfconf_channel_get(), which returns a singleton object and saves a little memory. However, xfconf_channel_new() can be useful in some cases where you want to tie an #XfconfChannel's lifetime (and thus the lifetime of connected signals and bound #GObject properties) to the lifetime of another object. Also note that each channel has its own cache, so if you create 2 new channels with the same name, it will double the dbus traffic, so in this cases it is highly recommended to use xfconf_channel_get(). A new #XfconfChannel. Release with g_object_unref() when no longer needed. A channel name. Creates a new channel using @name as the channel's identifier, restricting the accessible properties to be rooted at @property_base. This function always returns a valid object; no checking is done to see if the channel exists or has a valid name. A new #XfconfChannel. Release with g_object_unref() when no longer needed. A channel name. A property root name. Gets an array property on @channel. The @first_value_type argument specifies the type of the first value in the variable argument list. The variable argument list should alternate between pointers to locations to store the values, and the GType of the next value. The argument list should be terminated with G_TYPE_INVALID. Note: The configuration store backend almost certainly supports only a restricted set of value types. %TRUE if the property was retrieved successfully, %FALSE otherwise. An #XfconfChannel. A property string. The type of the first argument in the array. A variable argument list of types and values. Gets an array property on @channel. See xfconf_channel_get_array() for details. %TRUE if the property was retrieved successfully, %FALSE otherwise. An #XfconfChannel. A property string. The type of the first argument in the array. A variable argument list of types and values. Gets an array property on @channel and returns it as a #GPtrArray, which can be freed with xfconf_array_free() when no longer needed. A newly-allocated #GPtrArray on success, or %NULL on failure. An #XfconfChannel. A property string. Retrieves the boolean value associated with @property on @channel. The boolean value, or, if @property is not in @channel or if its type does not match, @default_value is returned. An #XfconfChannel. A property name. A fallback value. Retrieves the double value associated with @property on @channel. The double value, or, if @property is not in @channel or if its type does not match, @default_value is returned. An #XfconfChannel. A property name. A fallback value. Retrieves the int value associated with @property on @channel. The int value, or, if @property is not in @channel or if its type does not match, @default_value is returned. An #XfconfChannel. A property name. A fallback value. Gets a property from @channel and fills in @value_struct using the retrieved values. The @struct_name parameter is the same name that must have been used to register the struct's layout with xfconf_named_struct_register(). %TRUE if the property was retrieved successfully, %FALSE otherwise. An #XfconfChannel. A string property name. A string struct name. A pointer to a struct. Retrieves multiple properties from @channel and stores them in a #GHashTable in which the keys correspond to the string (gchar *) property names, and the values correspond to variant (GValue *) values. The keys and values are owned by the hash table and should be copied if needed. The value of the property specified by @property_base (if it exists) and all sub-properties are retrieved. To retrieve all properties in the channel, specify "/" or %NULL for @property_base. A newly-allocated #GHashTable, which should be freed with g_hash_table_destroy() when no longer needed. An #XfconfChannel. The base property name of properties to retrieve. Gets a property on @channel and stores it in @value. The caller is responsible for calling g_value_unset() when finished with @value. This function can be called with an initialized or uninitialized @value. If @value is initialized to a particular type, libxfconf will attempt to convert the value returned from the configuration store to that type if they don't match. If the value type returned from the configuration store is an array type, each element of the array will be converted to the type of @value. If @value is uninitialized, the value in the configuration store will be returned in its native type. %TRUE if the property was retrieved successfully, %FALSE otherwise. An #XfconfChannel. A string property name. A #GValue. Retrieves the string value associated with @property on @channel. A newly-allocated string which should be freed with g_free() when no longer needed. If @property is not in @channel or if its type does not match, a g_strdup()ed copy of @default_value is returned. An #XfconfChannel. A property name. A fallback value. Retrieves the string list value associated with @property on @channel. A newly-allocated string list which should be freed with g_strfreev() when no longer needed. If @property is not in @channel, %NULL is returned. An #XfconfChannel. A property name. Gets a property on @channel and stores it as members of the @value_struct struct. The @first_member_type argument specifies the #GType of the first member of the struct. The variable argument list specifies the #GType<!-- -->s of the rest of the struct members, and should be terminated with G_TYPE_INVALID. Note: This function takes your compiler's and platform's struct member alignment rules into account when storing values in @value_struct. Therefore, it cannot be used with structs that are declared as "packed" in such a way that the alignment rules are ignored by the compiler. Note: Struct members can only be non-pointer types such as int, boolean, double, etc. %TRUE if the property was retrieved successfully, %FALSE oherwise. An #XfconfChannel. A string property name. A pointer to a struct in which to store values. The GType of the first member of @value_struct. A variable argument list of #GType<!-- -->s. Gets a property on @channel and stores it as members of the @value_struct struct. See xfconf_channel_get_struct() for details. Note: Struct members can only be non-pointer types such as int, boolean, double, etc. %TRUE if the property was retrieved successfully, %FALSE oherwise. An #XfconfChannel. A string property name. A pointer to a struct in which to store values. The GType of the first member of @value_struct. A variable argument list of #GType<!-- -->s. Gets a property on @channel and stores it as members of the @value_struct struct. The @member_types array should hold a #GType for each member of the struct. Note: Struct members can only be non-pointer types such as int, boolean, double, etc. %TRUE if the property was retrieved successfully, %FALSE oherwise. An #XfconfChannel. A string property name. A pointer to a struct in which to store values. The number of data members in the struct. An array of @n_members #GType<!-- -->s. Retrieves the unsigned int value associated with @property on @channel. The uint value, or, if @property is not in @channel or if its type does not match, @default_value is returned. An #XfconfChannel. A property name. A fallback value. Retrieves the 64-bit int value associated with @property on @channel. The uint64 value, or, if @property is not in @channel or if its type does not match, @default_value is returned. An #XfconfChannel. A property name. A fallback value. Checks to see if @property exists on @channel. %TRUE if @property exists, %FALSE otherwise. An #XfconfChannel. A property name. Queries whether or not @property on @channel is locked by system policy. If the property is locked, calls to xfconf_channel_set_property() (or any of the "set" family of functions) or xfconf_channel_reset_property() will fail. %TRUE if the property is locked, %FALSE otherwise. An #XfconfChannel. A property name. Resets properties starting at (and including) @property_base. If @recursive is %TRUE, will also reset all properties that are under @property_base in the property hierarchy. A bit of an explanation as to what this function actually does: Since Xfconf backends are expected to support setting defaults via what you might call "optional schema," you can't really "remove" properties. Since the client library can't know if a channel provides default values (or even if the backend supports it!), at best it can only reset properties to their default values. The @property_base parameter can be %NULL or the empty string (""), in which case the channel root ("/") will be assumed. Of course, %TRUE must be passed for @recursive in this case. An #XfconfChannel. A property tree root or property name. Whether to reset properties recursively. Sets an array property on @channel. The @first_value_type argument specifies the type of the first value in the variable argument list. Note that all values specified MUST be pointers to variables holding the correct value, and may not be, e.g., numeric constants. The argument list should be terminated with G_TYPE_INVALID. Note: The configuration store backend almost certainly supports only a restricted set of value types. %TRUE if the property was set successfully, %FALSE otherwise. An #XfconfChannel. A property string. The type of the first argument in the array. A variable argument list of types and values. Sets an array property on @channel. See xfconf_channel_set_array() for details. %TRUE if the property was set successfully, %FALSE otherwise. An #XfconfChannel. A property string. The type of the first argument in the array. A variable argument list of types and values. Sets an array property on @channel, using the values in the provided @values array. %TRUE if the property was set successfully, %FALSE otherwise. An #XfconfChannel. A property string. A #GPtrArray of #GValue<!-- -->s. Sets @value for @property on @channel in the configuration store. %TRUE on success, %FALSE if an error occured. An #XfconfChannel. A property name. The value to set. Sets @value for @property on @channel in the configuration store. %TRUE on success, %FALSE if an error occured. An #XfconfChannel. A property name. The value to set. Sets @value for @property on @channel in the configuration store. %TRUE on success, %FALSE if an error occured. An #XfconfChannel. A property name. The value to set. Sets a property on @channel using the members of @value_struct as the array of values. The @struct_name parameter is the same name that must have been used to register the struct's layout with xfconf_named_struct_register(). %TRUE if the property was set successfully, %FALSE otherwise. An #XfconfChannel. A string property name. A string struct name. A pointer to a struct. Sets the value stored in @value to a property on @channel. Note: The configuration store backend almost certainly supports only a restricted set of value types. %TRUE if the property was set successfully, %FALSE otherwise. An #XfconfChannel. A string property name. A #GValue. Sets @value for @property on @channel in the configuration store. If @value is %NULL, the empty string ("") will be stored. %TRUE on success, %FALSE if an error occured. An #XfconfChannel. A property name. The value to set. Sets @values for @property on @channel in the configuration store. %TRUE on success, %FALSE if an error occured. An #XfconfChannel. A property name. The value to set. Sets a property on @channel using the members of @value_struct as a value array. The @first_member_type argument specifies the #GType of the first member of the struct. The variable argument list specifies the #GType<!-- -->s of the rest of the struct members, and should be terminated with G_TYPE_INVALID. Note: This function takes your compiler's and platform's struct member alignment rules into account when taking values in @value_struct. Therefore, it cannot be used with structs that are declared as "packed" such that the alignment rules are ignored by the compiler. %TRUE if the property was set successfully, %FALSE oherwise. An #XfconfChannel. A string property name. A pointer to a struct from which to take values. The GType of the first member of @value_struct. A variable argument list of #GType<!-- -->s. Sets a property on @channel using the members of @value_struct as a value array. See xfconf_channel_set_struct() for details. %TRUE if the property was set successfully, %FALSE oherwise. An #XfconfChannel. A string property name. A pointer to a struct from which to take values. The GType of the first member of @value_struct. A variable argument list of #GType<!-- -->s. Sets a property on @channel using the members of @value_struct as a value array. The @member_types array should hold a #GType for each member of the struct. %TRUE if the property was set successfully, %FALSE oherwise. An #XfconfChannel. A string property name. A pointer to a struct from which to take values. The number of data members in the struct. An array of @n_members #GType<!-- -->s. Sets @value for @property on @channel in the configuration store. %TRUE on success, %FALSE if an error occured. An #XfconfChannel. A property name. The value to set. Sets @value for @property on @channel in the configuration store. %TRUE on success, %FALSE if an error occured. An #XfconfChannel. A property name. The value to set. The string identifier used for this channel. Identifies the instance of the class as a singleton instance or not. This is mainly used internally by #XfconfChannel but may be useful for API users. The string identifier used for the property base inside a channel. This can be used to restrict a channel to a subset of properties. Emitted whenever a property on @channel has changed. If the change was caused by the removal of @property, @value will be unset; you should test this with <informalexample><programlisting> G_VALUE_TYPE(value) == G_TYPE_INVALID </programlisting></informalexample> The property that changed. The new value. An enumeration listing the different kinds of errors under the XFCONF_ERROR domain. An unknown error occurred The specified channel does not exist The specified property does not exist on the channel There was a failure reading from the configuration store There was a failure writing to the configuration store The user is not allowed to read or write to the channel or property An internal error (likely a bug in xfconf) occurred No backends were found, or those found could not be loaded The property name specified was invalid The channel name specified was invalid Properly frees a #GPtrArray structure containing a list of #GValue<!-- -->s. This will also cause the contents of the values to be freed as well. A #GPtrArray of #GValue<!-- -->s. Initializes the Xfconf library. Can be called multiple times with no adverse effects. %TRUE if the library was initialized succesfully, %FALSE on error. If there is an error @error will be set. Lists all channels known in the Xfconf configuration store. A newly-allocated array of strings. Free with g_strfreev() when no longer needed. Registers a named struct for use with xfconf_channel_get_named_struct() and xfconf_channel_set_named_struct(). The unique name of the struct to register. The number of data members in the struct. An array of the #GType<!-- -->s of the struct members. Binds an Xfconf property to a #GObject property. If the property is changed via either the #GObject or Xfconf, the corresponding property will also be updated. The binding is initialized from the Xfconf property, i.e. the initial value of the #GObject property is overwritten. Note that @xfconf_property_type is required since @xfconf_property may or may not already exist in the Xfconf store. The type of @object_property will be determined automatically. If the two types do not match, a conversion will be attempted. If you are binding a #GdkColor or #GdkRGBA property, pass #G_TYPE_PTR_ARRAY for @xfconf_property_type. an ID number that can be used to later remove the binding. An #XfconfChannel. A property on @channel. The type of @xfconf_property. A #GObject. A valid property on @object. Binds an Xfconf property to a #GObject property of type GDK_TYPE_COLOR (aka a #GdkColor struct). If the property is changed via either the #GObject or Xfconf, the corresponding property will also be updated. The binding is initialized from the Xfconf property, i.e. the initial value of the #GObject property is overwritten. This is a special-case binding; the GdkColor struct is not ideal as-is for binding to a property, so it is stored in the Xfconf store as four 16-bit unsigned ints (red, green, blue, alpha). Since GdkColor (currently) only supports RGB and not RGBA, the last value will always be set to 0xFFFF. Use #xfconf_g_property_bind() with #G_TYPE_PTR_ARRAY instead. an ID number that can be used to later remove the binding. An #XfconfChannel. A property on @channel. A #GObject. A valid property on @object. Binds an Xfconf property to a #GObject property of type GDK_TYPE_RGBA (aka a #GdkRGBA struct). If the property is changed via either the #GObject or Xfconf, the corresponding property will also be updated. The binding is initialized from the Xfconf property, i.e. the initial value of the #GObject property is overwritten. This is a special-case binding; the GdkRGBA struct is not ideal as-is for binding to a property, so it is stored in the Xfconf store as four 16-bit unsigned ints (red, green, blue, alpha). Use #xfconf_g_property_bind() with #G_TYPE_PTR_ARRAY instead. an ID number that can be used to later remove the binding. An #XfconfChannel. A property on @channel. A #GObject. A valid property on @object. Removes an Xfconf/GObject property binding based on the binding ID number. See xfconf_g_property_bind(). A binding ID number. Unbinds all Xfconf channel bindings (see xfconf_g_property_bind()) to @object. If @object is an #XfconfChannel, it will unbind all xfconf properties on that channel. If @object is a regular #GObject with properties bound to a channel, all those bindings will be removed. A #GObject or #XfconfChannel. Causes an Xfconf channel previously bound to a #GObject property (see xfconf_g_property_bind()) to no longer be bound. An #XfconfChannel. A bound property on @channel. A #GObject. A bound property on @object. Shuts down and frees any resources consumed by the Xfconf library. If xfconf_init() is called multiple times, xfconf_shutdown() must be called an equal number of times to shut down the library. Retrieves a 16-bit signed value from @value. A gint16. A #GValue. Retrieves a 16-bit unsigned value from @value. A guint16. A #GValue. Sets @value using a signed 16-bit integer. A #GValue. A gint16. Sets @value using an unsigned 16-bit integer. A #GValue. A guint16. Before libxfconf can be used, it must be initialized by calling xfconf_init(). To free resources used by the library, call xfconf_shutdown(). These calls are "recursive": multiple calls to xfconf_init() are allowed, but each call must be matched by a separate call to xfconf_shutdown() to really free the library's resources. Often it may be useful to bind an Xfconf property to a GObject property. Settings dialogs often display the current value of an Xfconf property, and a user may edit the value to change the value in the Xfconf store. If the Xfconf property changes outside the settings dialog, the user will usually want to see the settings dialog automatically update to reflect the new value. With a single line of code, Xfconf's binding functionality can automate all this. An XfconfChannel is a representation of a restricted domain or namespace that an application can define to store configuration settings. This is to ensure that different applications do not store configuration keys with the same names. libgobject lacks GObject fundamental types for 16-bit signed and unsigned integers, which may be useful to use in an Xfconf store. GObject types for these primitive types are provided here.