Top |
char * | channel-name | Read / Write / Construct Only |
gboolean | is-singleton | Read / Write / Construct Only |
char * | property-base | Read / Write / Construct Only |
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.
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
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()
.
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
gboolean xfconf_channel_has_property (XfconfChannel *channel
,const gchar *property
);
Checks to see if property
exists on channel
.
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
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.
channel |
An XfconfChannel. |
|
property_base |
A property tree root or property name. |
|
recursive |
Whether to reset properties recursively. |
Since: 4.5.91
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
.
channel |
An XfconfChannel. |
|
property_base |
The base property name of properties to retrieve. |
gchar * xfconf_channel_get_string (XfconfChannel *channel
,const gchar *property
,const gchar *default_value
);
Retrieves the string value associated with property
on channel
.
gchar ** xfconf_channel_get_string_list (XfconfChannel *channel
,const gchar *property
);
Retrieves the string list value associated with property
on channel
.
gint32 xfconf_channel_get_int (XfconfChannel *channel
,const gchar *property
,gint32 default_value
);
Retrieves the int value associated with property
on channel
.
guint32 xfconf_channel_get_uint (XfconfChannel *channel
,const gchar *property
,guint32 default_value
);
Retrieves the unsigned int value associated with property
on channel
.
guint64 xfconf_channel_get_uint64 (XfconfChannel *channel
,const gchar *property
,guint64 default_value
);
Retrieves the 64-bit int value associated with property
on channel
.
gdouble xfconf_channel_get_double (XfconfChannel *channel
,const gchar *property
,gdouble default_value
);
Retrieves the double value associated with property
on channel
.
gboolean xfconf_channel_get_bool (XfconfChannel *channel
,const gchar *property
,gboolean default_value
);
Retrieves the boolean value associated with property
on channel
.
gboolean xfconf_channel_set_string (XfconfChannel *channel
,const gchar *property
,const gchar *value
);
Sets value
for property
on channel
in the configuration store.
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.
gboolean xfconf_channel_set_int (XfconfChannel *channel
,const gchar *property
,gint32 value
);
Sets value
for property
on channel
in the configuration store.
gboolean xfconf_channel_set_uint (XfconfChannel *channel
,const gchar *property
,guint32 value
);
Sets value
for property
on channel
in the configuration store.
gboolean xfconf_channel_set_uint64 (XfconfChannel *channel
,const gchar *property
,guint64 value
);
Sets value
for property
on channel
in the configuration store.
gboolean xfconf_channel_set_double (XfconfChannel *channel
,const gchar *property
,gdouble value
);
Sets value
for property
on channel
in the configuration store.
gboolean xfconf_channel_set_bool (XfconfChannel *channel
,const gchar *property
,gboolean value
);
Sets value
for property
on channel
in the configuration store.
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.
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.
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.
channel |
An XfconfChannel. |
|
property |
A property string. |
|
first_value_type |
The type of the first argument in the array. |
|
... |
A variable argument list of types and values. |
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.
channel |
An XfconfChannel. |
|
property |
A property string. |
|
first_value_type |
The type of the first argument in the array. |
|
var_args |
A variable argument list of types and values. |
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.
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.
channel |
An XfconfChannel. |
|
property |
A property string. |
|
first_value_type |
The type of the first argument in the array. |
|
... |
A variable argument list of types and values. |
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.
channel |
An XfconfChannel. |
|
property |
A property string. |
|
first_value_type |
The type of the first argument in the array. |
|
var_args |
A variable argument list of types and values. |
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.
channel |
An XfconfChannel. |
|
property |
A property string. |
|
values |
A GPtrArray of GValues. |
[element-type GValue] |
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()
.
channel |
An XfconfChannel. |
|
property |
A string property name. |
|
struct_name |
A string struct name. |
|
value_struct |
A pointer to a 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()
.
channel |
An XfconfChannel. |
|
property |
A string property name. |
|
struct_name |
A string struct name. |
|
value_struct |
A pointer to a 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.
channel |
An XfconfChannel. |
|
property |
A string property name. |
|
value_struct |
A pointer to a struct in which to store values. |
|
first_member_type |
The GType of the first member of |
|
... |
A variable argument list of GTypes. |
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.
channel |
An XfconfChannel. |
|
property |
A string property name. |
|
value_struct |
A pointer to a struct in which to store values. |
|
first_member_type |
The GType of the first member of |
|
var_args |
A variable argument list of GTypes. |
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.
channel |
An XfconfChannel. |
|
property |
A string property name. |
|
value_struct |
A pointer to a struct in which to store values. |
|
n_members |
The number of data members in the struct. |
|
member_types |
An array of |
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.
channel |
An XfconfChannel. |
|
property |
A string property name. |
|
value_struct |
A pointer to a struct from which to take values. |
|
first_member_type |
The GType of the first member of |
|
... |
A variable argument list of GTypes. |
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.
channel |
An XfconfChannel. |
|
property |
A string property name. |
|
value_struct |
A pointer to a struct from which to take values. |
|
first_member_type |
The GType of the first member of |
|
var_args |
A variable argument list of GTypes. |
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.
channel |
An XfconfChannel. |
|
property |
A string property name. |
|
value_struct |
A pointer to a struct from which to take values. |
|
n_members |
The number of data members in the struct. |
|
member_types |
An array of |
“channel-name”
property “channel-name” char *
The string identifier used for this channel.
Owner: XfconfChannel
Flags: Read / Write / Construct Only
Default value: NULL
“is-singleton”
property “is-singleton” gboolean
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.
Owner: XfconfChannel
Flags: Read / Write / Construct Only
Default value: TRUE
“property-changed”
signalvoid user_function (XfconfChannel *channel, char *property, GValue *value, gpointer user_data)
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
1 |
G_VALUE_TYPE(value) == G_TYPE_INVALID |
channel |
The XfconfChannel emitting the signal. |
|
property |
The property that changed. |
|
value |
The new value. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Has Details