XfconfChannel

typedef struct _XfconfChannel XfconfChannel;

An opaque structure that holds state about a channel.

xfconf_channel_get ()

XfconfChannel *     xfconf_channel_get                  (const gchar *channel_name);

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.

Since 4.5.91

xfconf_channel_new ()

XfconfChannel *     xfconf_channel_new                  (const gchar *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().

xfconf_channel_new_with_property_base ()

XfconfChannel *     xfconf_channel_new_with_property_base
                                                        (const gchar *channel_name,
                                                         const gchar *property_base);

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.

Since 4.5.92

xfconf_channel_has_property ()

gboolean            xfconf_channel_has_property         (XfconfChannel *channel,
                                                         const gchar *property);

Checks to see if property exists on channel.

xfconf_channel_is_property_locked ()

gboolean            xfconf_channel_is_property_locked   (XfconfChannel *channel,
                                                         const gchar *property);

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.

Since 4.5.91

xfconf_channel_reset_property ()

void                xfconf_channel_reset_property       (XfconfChannel *channel,
                                                         const gchar *property_base,
                                                         gboolean recursive);

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.

Since 4.5.91

xfconf_channel_get_properties ()

GHashTable *        xfconf_channel_get_properties       (XfconfChannel *channel,
                                                         const gchar *property_base);

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.

xfconf_channel_get_string ()

gchar *             xfconf_channel_get_string           (XfconfChannel *channel,
                                                         const gchar *property,
                                                         const gchar *default_value);

Retrieves the string value associated with property on channel.

xfconf_channel_get_string_list ()

gchar **            xfconf_channel_get_string_list      (XfconfChannel *channel,
                                                         const gchar *property);

Retrieves the string list value associated with property on channel.

xfconf_channel_get_int ()

gint32              xfconf_channel_get_int              (XfconfChannel *channel,
                                                         const gchar *property,
                                                         gint32 default_value);

Retrieves the int value associated with property on channel.

xfconf_channel_get_uint ()

guint32             xfconf_channel_get_uint             (XfconfChannel *channel,
                                                         const gchar *property,
                                                         guint32 default_value);

Retrieves the unsigned int value associated with property on channel.

xfconf_channel_get_uint64 ()

guint64             xfconf_channel_get_uint64           (XfconfChannel *channel,
                                                         const gchar *property,
                                                         guint64 default_value);

Retrieves the 64-bit int value associated with property on channel.

xfconf_channel_get_double ()

gdouble             xfconf_channel_get_double           (XfconfChannel *channel,
                                                         const gchar *property,
                                                         gdouble default_value);

Retrieves the double value associated with property on channel.

xfconf_channel_get_bool ()

gboolean            xfconf_channel_get_bool             (XfconfChannel *channel,
                                                         const gchar *property,
                                                         gboolean default_value);

Retrieves the boolean value associated with property on channel.

xfconf_channel_set_string ()

gboolean            xfconf_channel_set_string           (XfconfChannel *channel,
                                                         const gchar *property,
                                                         const gchar *value);

Sets value for property on channel in the configuration store.

xfconf_channel_set_string_list ()

gboolean            xfconf_channel_set_string_list      (XfconfChannel *channel,
                                                         const gchar *property,
                                                         const gchar * const *values);

Sets values for property on channel in the configuration store.

xfconf_channel_set_int ()

gboolean            xfconf_channel_set_int              (XfconfChannel *channel,
                                                         const gchar *property,
                                                         gint32 value);

Sets value for property on channel in the configuration store.

xfconf_channel_set_uint ()

gboolean            xfconf_channel_set_uint             (XfconfChannel *channel,
                                                         const gchar *property,
                                                         guint32 value);

Sets value for property on channel in the configuration store.

xfconf_channel_set_uint64 ()

gboolean            xfconf_channel_set_uint64           (XfconfChannel *channel,
                                                         const gchar *property,
                                                         guint64 value);

Sets value for property on channel in the configuration store.

xfconf_channel_set_double ()

gboolean            xfconf_channel_set_double           (XfconfChannel *channel,
                                                         const gchar *property,
                                                         gdouble value);

Sets value for property on channel in the configuration store.

xfconf_channel_set_bool ()

gboolean            xfconf_channel_set_bool             (XfconfChannel *channel,
                                                         const gchar *property,
                                                         gboolean value);

Sets value for property on channel in the configuration store.

xfconf_channel_get_property ()

gboolean            xfconf_channel_get_property         (XfconfChannel *channel,
                                                         const gchar *property,
                                                         GValue *value);

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.

xfconf_channel_set_property ()

gboolean            xfconf_channel_set_property         (XfconfChannel *channel,
                                                         const gchar *property,
                                                         const GValue *value);

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.

xfconf_channel_get_array ()

gboolean            xfconf_channel_get_array            (XfconfChannel *channel,
                                                         const gchar *property,
                                                         GType first_value_type,
                                                         ...);

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.

xfconf_channel_get_array_valist ()

gboolean            xfconf_channel_get_array_valist     (XfconfChannel *channel,
                                                         const gchar *property,
                                                         GType first_value_type,
                                                         va_list var_args);

Gets an array property on channel. See xfconf_channel_get_array() for details.

xfconf_channel_get_arrayv ()

GPtrArray *         xfconf_channel_get_arrayv           (XfconfChannel *channel,
                                                         const gchar *property);

Gets an array property on channel and returns it as a GPtrArray, which can be freed with xfconf_array_free() when no longer needed.

xfconf_channel_set_array ()

gboolean            xfconf_channel_set_array            (XfconfChannel *channel,
                                                         const gchar *property,
                                                         GType first_value_type,
                                                         ...);

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.

xfconf_channel_set_array_valist ()

gboolean            xfconf_channel_set_array_valist     (XfconfChannel *channel,
                                                         const gchar *property,
                                                         GType first_value_type,
                                                         va_list var_args);

Sets an array property on channel. See xfconf_channel_set_array() for details.

xfconf_channel_set_arrayv ()

gboolean            xfconf_channel_set_arrayv           (XfconfChannel *channel,
                                                         const gchar *property,
                                                         GPtrArray *values);

Sets an array property on channel, using the values in the provided values array.

xfconf_channel_get_named_struct ()

gboolean            xfconf_channel_get_named_struct     (XfconfChannel *channel,
                                                         const gchar *property,
                                                         const gchar *struct_name,
                                                         gpointer value_struct);

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

xfconf_channel_set_named_struct ()

gboolean            xfconf_channel_set_named_struct     (XfconfChannel *channel,
                                                         const gchar *property,
                                                         const gchar *struct_name,
                                                         gpointer value_struct);

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

xfconf_channel_get_struct ()

gboolean            xfconf_channel_get_struct           (XfconfChannel *channel,
                                                         const gchar *property,
                                                         gpointer value_struct,
                                                         GType first_member_type,
                                                         ...);

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 GTypes 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.

xfconf_channel_get_struct_valist ()

gboolean            xfconf_channel_get_struct_valist    (XfconfChannel *channel,
                                                         const gchar *property,
                                                         gpointer value_struct,
                                                         GType first_member_type,
                                                         va_list var_args);

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.

xfconf_channel_get_structv ()

gboolean            xfconf_channel_get_structv          (XfconfChannel *channel,
                                                         const gchar *property,
                                                         gpointer value_struct,
                                                         guint n_members,
                                                         GType *member_types);

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.

xfconf_channel_set_struct ()

gboolean            xfconf_channel_set_struct           (XfconfChannel *channel,
                                                         const gchar *property,
                                                         const gpointer value_struct,
                                                         GType first_member_type,
                                                         ...);

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 GTypes 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.

xfconf_channel_set_struct_valist ()

gboolean            xfconf_channel_set_struct_valist    (XfconfChannel *channel,
                                                         const gchar *property,
                                                         const gpointer value_struct,
                                                         GType first_member_type,
                                                         va_list var_args);

Sets a property on channel using the members of value_struct as a value array. See xfconf_channel_set_struct() for details.

xfconf_channel_set_structv ()

gboolean            xfconf_channel_set_structv          (XfconfChannel *channel,
                                                         const gchar *property,
                                                         const gpointer value_struct,
                                                         guint n_members,
                                                         GType *member_types);

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.

The "channel-name" property

  "channel-name"             gchar*                : Read / Write / Construct Only

The name of the channel.

Default value: NULL

The "is-singleton" property

  "is-singleton"             gboolean              : Read / Write / Construct Only

Whether or not this instance is a singleton.

Default value: TRUE

The "property-base" property

  "property-base"            gchar*                : Read / Write / Construct Only

Base property path.

Default value: NULL

The "property-changed" signal

void                user_function                      (XfconfChannel *channel,
                                                        gchar         *property,
                                                        GValue        *value,
                                                        gpointer       user_data)      : Has Details

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

G_VALUE_TYPE(value) == G_TYPE_INVALID