2 * Copyright © 2009, 2010 Codethink Limited
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the licence, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA.
19 * Author: Ryan Lortie <desrt@desrt.ca>
28 #include "gsettings.h"
30 #include "gdelayedsettingsbackend.h"
31 #include "gsettingsbackendinternal.h"
32 #include "gsettings-mapping.h"
33 #include "gsettingsschema-internal.h"
39 * @short_description: High-level API for application settings
41 * The #GSettings class provides a convenient API for storing and retrieving
42 * application settings.
44 * Reads and writes can be considered to be non-blocking. Reading
45 * settings with #GSettings is typically extremely fast: on
46 * approximately the same order of magnitude (but slower than) a
47 * #GHashTable lookup. Writing settings is also extremely fast in terms
48 * of time to return to your application, but can be extremely expensive
49 * for other threads and other processes. Many settings backends
50 * (including dconf) have lazy initialisation which means in the common
51 * case of the user using their computer without modifying any settings
52 * a lot of work can be avoided. For dconf, the D-Bus service doesn't
53 * even need to be started in this case. For this reason, you should
54 * only ever modify #GSettings keys in response to explicit user action.
55 * Particular care should be paid to ensure that modifications are not
56 * made during startup -- for example, when setting the initial value
57 * of preferences widgets. The built-in g_settings_bind() functionality
58 * is careful not to write settings in response to notify signals as a
59 * result of modifications that it makes to widgets.
61 * When creating a GSettings instance, you have to specify a schema
62 * that describes the keys in your settings and their types and default
63 * values, as well as some other information.
65 * Normally, a schema has as fixed path that determines where the settings
66 * are stored in the conceptual global tree of settings. However, schemas
67 * can also be 'relocatable', i.e. not equipped with a fixed path. This is
68 * useful e.g. when the schema describes an 'account', and you want to be
69 * able to store a arbitrary number of accounts.
71 * Unlike other configuration systems (like GConf), GSettings does not
72 * restrict keys to basic types like strings and numbers. GSettings stores
73 * values as #GVariant, and allows any #GVariantType for keys. Key names
74 * are restricted to lowercase characters, numbers and '-'. Furthermore,
75 * the names must begin with a lowercase character, must not end
76 * with a '-', and must not contain consecutive dashes.
78 * Similar to GConf, the default values in GSettings schemas can be
79 * localized, but the localized values are stored in gettext catalogs
80 * and looked up with the domain that is specified in the
81 * <tag class="attribute">gettext-domain</tag> attribute of the
82 * <tag class="starttag">schemalist</tag> or <tag class="starttag">schema</tag>
83 * elements and the category that is specified in the l10n attribute of the
84 * <tag class="starttag">key</tag> element.
86 * GSettings uses schemas in a compact binary form that is created
87 * by the <link linkend="glib-compile-schemas">glib-compile-schemas</link>
88 * utility. The input is a schema description in an XML format that can be
89 * described by the following DTD:
90 * |[<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/gschema.dtd"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include>]|
92 * glib-compile-schemas expects schema files to have the extension <filename>.gschema.xml</filename>
94 * At runtime, schemas are identified by their id (as specified
95 * in the <tag class="attribute">id</tag> attribute of the
96 * <tag class="starttag">schema</tag> element). The
97 * convention for schema ids is to use a dotted name, similar in
98 * style to a D-Bus bus name, e.g. "org.gnome.SessionManager". In particular,
99 * if the settings are for a specific service that owns a D-Bus bus name,
100 * the D-Bus bus name and schema id should match. For schemas which deal
101 * with settings not associated with one named application, the id should
102 * not use StudlyCaps, e.g. "org.gnome.font-rendering".
104 * In addition to #GVariant types, keys can have types that have enumerated
105 * types. These can be described by a <tag class="starttag">choice</tag>,
106 * <tag class="starttag">enum</tag> or <tag class="starttag">flags</tag> element, see
107 * <xref linkend="schema-enumerated"/>. The underlying type of
108 * such a key is string, but you can use g_settings_get_enum(),
109 * g_settings_set_enum(), g_settings_get_flags(), g_settings_set_flags()
110 * access the numeric values corresponding to the string value of enum
113 * <example id="schema-default-values"><title>Default values</title>
114 * <programlisting><![CDATA[
116 * <schema id="org.gtk.Test" path="/tests/" gettext-domain="test">
118 * <key name="greeting" type="s">
119 * <default l10n="messages">"Hello, earthlings"</default>
120 * <summary>A greeting</summary>
122 * Greeting of the invading martians
126 * <key name="box" type="(ii)">
127 * <default>(20,30)</default>
132 * ]]></programlisting></example>
134 * <example id="schema-enumerated"><title>Ranges, choices and enumerated types</title>
135 * <programlisting><![CDATA[
138 * <enum id="org.gtk.Test.myenum">
139 * <value nick="first" value="1"/>
140 * <value nick="second" value="2"/>
143 * <flags id="org.gtk.Test.myflags">
144 * <value nick="flag1" value="1"/>
145 * <value nick="flag2" value="2"/>
146 * <value nick="flag3" value="4"/>
149 * <schema id="org.gtk.Test">
151 * <key name="key-with-range" type="i">
152 * <range min="1" max="100"/>
153 * <default>10</default>
156 * <key name="key-with-choices" type="s">
158 * <choice value='Elisabeth'/>
159 * <choice value='Annabeth'/>
160 * <choice value='Joe'/>
163 * <alias value='Anna' target='Annabeth'/>
164 * <alias value='Beth' target='Elisabeth'/>
166 * <default>'Joe'</default>
169 * <key name='enumerated-key' enum='org.gtk.Test.myenum'>
170 * <default>'first'</default>
173 * <key name='flags-key' flags='org.gtk.Test.myflags'>
174 * <default>["flag1",flag2"]</default>
178 * ]]></programlisting></example>
181 * <title>Vendor overrides</title>
183 * Default values are defined in the schemas that get installed by
184 * an application. Sometimes, it is necessary for a vendor or distributor
185 * to adjust these defaults. Since patching the XML source for the schema
186 * is inconvenient and error-prone,
187 * <link linkend="glib-compile-schemas">glib-compile-schemas</link> reads
188 * so-called 'vendor override' files. These are keyfiles in the same
189 * directory as the XML schema sources which can override default values.
190 * The schema id serves as the group name in the key file, and the values
191 * are expected in serialized GVariant form, as in the following example:
192 * <informalexample><programlisting>
196 * </programlisting></informalexample>
199 * glib-compile-schemas expects schema files to have the extension
200 * <filename>.gschema.override</filename>
205 * <title>Binding</title>
207 * A very convenient feature of GSettings lets you bind #GObject properties
208 * directly to settings, using g_settings_bind(). Once a GObject property
209 * has been bound to a setting, changes on either side are automatically
210 * propagated to the other side. GSettings handles details like
211 * mapping between GObject and GVariant types, and preventing infinite
215 * This makes it very easy to hook up a preferences dialog to the
216 * underlying settings. To make this even more convenient, GSettings
217 * looks for a boolean property with the name "sensitivity" and
218 * automatically binds it to the writability of the bound setting.
219 * If this 'magic' gets in the way, it can be suppressed with the
220 * #G_SETTINGS_BIND_NO_SENSITIVITY flag.
225 struct _GSettingsPrivate
227 /* where the signals go... */
228 GMainContext *main_context;
230 GSettingsBackend *backend;
231 GSettingsSchema *schema;
234 GDelayedSettingsBackend *delayed;
250 SIGNAL_WRITABLE_CHANGE_EVENT,
251 SIGNAL_WRITABLE_CHANGED,
257 static guint g_settings_signals[N_SIGNALS];
259 G_DEFINE_TYPE (GSettings, g_settings, G_TYPE_OBJECT)
263 g_settings_real_change_event (GSettings *settings,
270 keys = g_settings_schema_list (settings->priv->schema, &n_keys);
272 for (i = 0; i < n_keys; i++)
273 g_signal_emit (settings, g_settings_signals[SIGNAL_CHANGED],
274 keys[i], g_quark_to_string (keys[i]));
280 g_settings_real_writable_change_event (GSettings *settings,
283 const GQuark *keys = &key;
288 keys = g_settings_schema_list (settings->priv->schema, &n_keys);
290 for (i = 0; i < n_keys; i++)
291 g_signal_emit (settings, g_settings_signals[SIGNAL_WRITABLE_CHANGED],
292 keys[i], g_quark_to_string (keys[i]));
298 settings_backend_changed (GObject *target,
299 GSettingsBackend *backend,
303 GSettings *settings = G_SETTINGS (target);
304 gboolean ignore_this;
307 /* We used to assert here:
309 * settings->priv->backend == backend
311 * but it could be the case that a notification is queued for delivery
312 * while someone calls g_settings_delay() (which changes the backend).
314 * Since the delay backend would just pass that straight through
315 * anyway, it doesn't make sense to try to detect this case.
316 * Therefore, we just accept it.
319 for (i = 0; key[i] == settings->priv->path[i]; i++);
321 if (settings->priv->path[i] == '\0' &&
322 g_settings_schema_has_key (settings->priv->schema, key + i))
326 quark = g_quark_from_string (key + i);
327 g_signal_emit (settings, g_settings_signals[SIGNAL_CHANGE_EVENT],
328 0, &quark, 1, &ignore_this);
333 settings_backend_path_changed (GObject *target,
334 GSettingsBackend *backend,
338 GSettings *settings = G_SETTINGS (target);
339 gboolean ignore_this;
341 if (g_str_has_prefix (settings->priv->path, path))
342 g_signal_emit (settings, g_settings_signals[SIGNAL_CHANGE_EVENT],
343 0, NULL, 0, &ignore_this);
347 settings_backend_keys_changed (GObject *target,
348 GSettingsBackend *backend,
350 const gchar * const *items,
353 GSettings *settings = G_SETTINGS (target);
354 gboolean ignore_this;
357 for (i = 0; settings->priv->path[i] &&
358 settings->priv->path[i] == path[i]; i++);
365 for (j = 0; items[j]; j++)
367 const gchar *item = items[j];
370 for (k = 0; item[k] == settings->priv->path[i + k]; k++);
372 if (settings->priv->path[i + k] == '\0' &&
373 g_settings_schema_has_key (settings->priv->schema, item + k))
374 quarks[l++] = g_quark_from_string (item + k);
376 /* "256 quarks ought to be enough for anybody!"
377 * If this bites you, I'm sorry. Please file a bug.
383 g_signal_emit (settings, g_settings_signals[SIGNAL_CHANGE_EVENT],
384 0, quarks, l, &ignore_this);
389 settings_backend_writable_changed (GObject *target,
390 GSettingsBackend *backend,
393 GSettings *settings = G_SETTINGS (target);
394 gboolean ignore_this;
397 for (i = 0; key[i] == settings->priv->path[i]; i++);
399 if (settings->priv->path[i] == '\0' &&
400 g_settings_schema_has_key (settings->priv->schema, key + i))
401 g_signal_emit (settings, g_settings_signals[SIGNAL_WRITABLE_CHANGE_EVENT],
402 0, g_quark_from_string (key + i), &ignore_this);
406 settings_backend_path_writable_changed (GObject *target,
407 GSettingsBackend *backend,
410 GSettings *settings = G_SETTINGS (target);
411 gboolean ignore_this;
413 if (g_str_has_prefix (settings->priv->path, path))
414 g_signal_emit (settings, g_settings_signals[SIGNAL_WRITABLE_CHANGE_EVENT],
415 0, (GQuark) 0, &ignore_this);
418 /* Properties, Construction, Destruction {{{1 */
420 g_settings_set_property (GObject *object,
425 GSettings *settings = G_SETTINGS (object);
431 GSettingsSchema *schema;
433 schema = g_value_dup_boxed (value);
435 /* we receive a set_property() call for "settings-schema" even
436 * if it was not specified (ie: with NULL value). ->schema
437 * could already be set at this point (ie: via "schema-id").
438 * check for NULL to avoid clobbering the existing value.
442 g_assert (settings->priv->schema == NULL);
443 settings->priv->schema = schema;
450 const gchar *schema_id;
452 schema_id = g_value_get_string (value);
454 /* we receive a set_property() call for both "schema" and
455 * "schema-id", even if they are not set. Hopefully only one of
458 if (schema_id != NULL)
460 GSettingsSchemaSource *default_source;
462 g_assert (settings->priv->schema == NULL);
463 default_source = g_settings_schema_source_get_default ();
465 if (default_source == NULL)
466 g_error ("No GSettings schemas are installed on the system");
468 settings->priv->schema = g_settings_schema_source_lookup (default_source, schema_id, TRUE);
470 if (settings->priv->schema == NULL)
471 g_error ("Settings schema '%s' is not installed\n", schema_id);
477 settings->priv->path = g_value_dup_string (value);
481 settings->priv->backend = g_value_dup_object (value);
485 g_assert_not_reached ();
490 g_settings_get_property (GObject *object,
495 GSettings *settings = G_SETTINGS (object);
500 g_value_set_boxed (value, settings->priv->schema);
504 g_value_set_string (value, g_settings_schema_get_id (settings->priv->schema));
508 g_value_set_object (value, settings->priv->backend);
512 g_value_set_string (value, settings->priv->path);
515 case PROP_HAS_UNAPPLIED:
516 g_value_set_boolean (value, g_settings_get_has_unapplied (settings));
519 case PROP_DELAY_APPLY:
520 g_value_set_boolean (value, settings->priv->delayed != NULL);
524 g_assert_not_reached ();
528 static const GSettingsListenerVTable listener_vtable = {
529 settings_backend_changed,
530 settings_backend_path_changed,
531 settings_backend_keys_changed,
532 settings_backend_writable_changed,
533 settings_backend_path_writable_changed
537 g_settings_constructed (GObject *object)
539 GSettings *settings = G_SETTINGS (object);
540 const gchar *schema_path;
542 schema_path = g_settings_schema_get_path (settings->priv->schema);
544 if (settings->priv->path && schema_path && strcmp (settings->priv->path, schema_path) != 0)
545 g_error ("settings object created with schema '%s' and path '%s', but path '%s' is specified by schema",
546 g_settings_schema_get_id (settings->priv->schema), settings->priv->path, schema_path);
548 if (settings->priv->path == NULL)
550 if (schema_path == NULL)
551 g_error ("attempting to create schema '%s' without a path",
552 g_settings_schema_get_id (settings->priv->schema));
554 settings->priv->path = g_strdup (schema_path);
557 if (settings->priv->backend == NULL)
558 settings->priv->backend = g_settings_backend_get_default ();
560 g_settings_backend_watch (settings->priv->backend,
561 &listener_vtable, G_OBJECT (settings),
562 settings->priv->main_context);
563 g_settings_backend_subscribe (settings->priv->backend,
564 settings->priv->path);
568 g_settings_finalize (GObject *object)
570 GSettings *settings = G_SETTINGS (object);
572 g_settings_backend_unsubscribe (settings->priv->backend,
573 settings->priv->path);
574 g_main_context_unref (settings->priv->main_context);
575 g_object_unref (settings->priv->backend);
576 g_settings_schema_unref (settings->priv->schema);
577 g_free (settings->priv->path);
579 G_OBJECT_CLASS (g_settings_parent_class)->finalize (object);
583 g_settings_init (GSettings *settings)
585 settings->priv = G_TYPE_INSTANCE_GET_PRIVATE (settings,
589 settings->priv->main_context = g_main_context_ref_thread_default ();
593 g_settings_class_init (GSettingsClass *class)
595 GObjectClass *object_class = G_OBJECT_CLASS (class);
597 class->writable_change_event = g_settings_real_writable_change_event;
598 class->change_event = g_settings_real_change_event;
600 object_class->set_property = g_settings_set_property;
601 object_class->get_property = g_settings_get_property;
602 object_class->constructed = g_settings_constructed;
603 object_class->finalize = g_settings_finalize;
605 g_type_class_add_private (object_class, sizeof (GSettingsPrivate));
608 * GSettings::changed:
609 * @settings: the object on which the signal was emitted
610 * @key: the name of the key that changed
612 * The "changed" signal is emitted when a key has potentially changed.
613 * You should call one of the g_settings_get() calls to check the new
616 * This signal supports detailed connections. You can connect to the
617 * detailed signal "changed::x" in order to only receive callbacks
618 * when key "x" changes.
620 g_settings_signals[SIGNAL_CHANGED] =
621 g_signal_new ("changed", G_TYPE_SETTINGS,
622 G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
623 G_STRUCT_OFFSET (GSettingsClass, changed),
624 NULL, NULL, g_cclosure_marshal_VOID__STRING, G_TYPE_NONE,
625 1, G_TYPE_STRING | G_SIGNAL_TYPE_STATIC_SCOPE);
628 * GSettings::change-event:
629 * @settings: the object on which the signal was emitted
630 * @keys: (array length=n_keys) (element-type GQuark) (allow-none):
631 * an array of #GQuark<!-- -->s for the changed keys, or %NULL
632 * @n_keys: the length of the @keys array, or 0
633 * @returns: %TRUE to stop other handlers from being invoked for the
634 * event. FALSE to propagate the event further.
636 * The "change-event" signal is emitted once per change event that
637 * affects this settings object. You should connect to this signal
638 * only if you are interested in viewing groups of changes before they
639 * are split out into multiple emissions of the "changed" signal.
640 * For most use cases it is more appropriate to use the "changed" signal.
642 * In the event that the change event applies to one or more specified
643 * keys, @keys will be an array of #GQuark of length @n_keys. In the
644 * event that the change event applies to the #GSettings object as a
645 * whole (ie: potentially every key has been changed) then @keys will
646 * be %NULL and @n_keys will be 0.
648 * The default handler for this signal invokes the "changed" signal
649 * for each affected key. If any other connected handler returns
650 * %TRUE then this default functionality will be suppressed.
652 g_settings_signals[SIGNAL_CHANGE_EVENT] =
653 g_signal_new ("change-event", G_TYPE_SETTINGS,
655 G_STRUCT_OFFSET (GSettingsClass, change_event),
656 g_signal_accumulator_true_handled, NULL,
658 G_TYPE_BOOLEAN, 2, G_TYPE_POINTER, G_TYPE_INT);
661 * GSettings::writable-changed:
662 * @settings: the object on which the signal was emitted
665 * The "writable-changed" signal is emitted when the writability of a
666 * key has potentially changed. You should call
667 * g_settings_is_writable() in order to determine the new status.
669 * This signal supports detailed connections. You can connect to the
670 * detailed signal "writable-changed::x" in order to only receive
671 * callbacks when the writability of "x" changes.
673 g_settings_signals[SIGNAL_WRITABLE_CHANGED] =
674 g_signal_new ("writable-changed", G_TYPE_SETTINGS,
675 G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
676 G_STRUCT_OFFSET (GSettingsClass, writable_changed),
677 NULL, NULL, g_cclosure_marshal_VOID__STRING, G_TYPE_NONE,
678 1, G_TYPE_STRING | G_SIGNAL_TYPE_STATIC_SCOPE);
681 * GSettings::writable-change-event:
682 * @settings: the object on which the signal was emitted
683 * @key: the quark of the key, or 0
684 * @returns: %TRUE to stop other handlers from being invoked for the
685 * event. FALSE to propagate the event further.
687 * The "writable-change-event" signal is emitted once per writability
688 * change event that affects this settings object. You should connect
689 * to this signal if you are interested in viewing groups of changes
690 * before they are split out into multiple emissions of the
691 * "writable-changed" signal. For most use cases it is more
692 * appropriate to use the "writable-changed" signal.
694 * In the event that the writability change applies only to a single
695 * key, @key will be set to the #GQuark for that key. In the event
696 * that the writability change affects the entire settings object,
699 * The default handler for this signal invokes the "writable-changed"
700 * and "changed" signals for each affected key. This is done because
701 * changes in writability might also imply changes in value (if for
702 * example, a new mandatory setting is introduced). If any other
703 * connected handler returns %TRUE then this default functionality
704 * will be suppressed.
706 g_settings_signals[SIGNAL_WRITABLE_CHANGE_EVENT] =
707 g_signal_new ("writable-change-event", G_TYPE_SETTINGS,
709 G_STRUCT_OFFSET (GSettingsClass, writable_change_event),
710 g_signal_accumulator_true_handled, NULL,
711 NULL, G_TYPE_BOOLEAN, 1, G_TYPE_UINT);
716 * The name of the context that the settings are stored in.
718 g_object_class_install_property (object_class, PROP_BACKEND,
719 g_param_spec_object ("backend",
720 P_("GSettingsBackend"),
721 P_("The GSettingsBackend for this settings object"),
722 G_TYPE_SETTINGS_BACKEND, G_PARAM_CONSTRUCT_ONLY |
723 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
726 * GSettings:settings-schema:
728 * The #GSettingsSchema describing the types of keys for this
731 * Ideally, this property would be called 'schema'. #GSettingsSchema
732 * has only existed since version 2.32, however, and before then the
733 * 'schema' property was used to refer to the ID of the schema rather
734 * than the schema itself. Take care.
736 g_object_class_install_property (object_class, PROP_SCHEMA,
737 g_param_spec_boxed ("settings-schema",
739 P_("The GSettingsSchema for this settings object"),
740 G_TYPE_SETTINGS_SCHEMA,
741 G_PARAM_CONSTRUCT_ONLY |
742 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
747 * The name of the schema that describes the types of keys
748 * for this #GSettings object.
750 * The type of this property is *not* #GSettingsSchema.
751 * #GSettingsSchema has only existed since version 2.32 and
752 * unfortunately this name was used in previous versions to refer to
753 * the schema ID rather than the schema itself. Take care to use the
754 * 'settings-schema' property if you wish to pass in a
757 * Deprecated:2.32:Use the 'schema-id' property instead. In a future
758 * version, this property may instead refer to a #GSettingsSchema.
760 g_object_class_install_property (object_class, PROP_SCHEMA_ID,
761 g_param_spec_string ("schema",
763 P_("The name of the schema for this settings object"),
765 G_PARAM_CONSTRUCT_ONLY |
766 G_PARAM_DEPRECATED | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
769 * GSettings:schema-id:
771 * The name of the schema that describes the types of keys
772 * for this #GSettings object.
774 g_object_class_install_property (object_class, PROP_SCHEMA_ID,
775 g_param_spec_string ("schema-id",
777 P_("The name of the schema for this settings object"),
779 G_PARAM_CONSTRUCT_ONLY |
780 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
785 * The path within the backend where the settings are stored.
787 g_object_class_install_property (object_class, PROP_PATH,
788 g_param_spec_string ("path",
790 P_("The path within the backend where the settings are"),
792 G_PARAM_CONSTRUCT_ONLY |
793 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
796 * GSettings:has-unapplied:
798 * If this property is %TRUE, the #GSettings object has outstanding
799 * changes that will be applied when g_settings_apply() is called.
801 g_object_class_install_property (object_class, PROP_HAS_UNAPPLIED,
802 g_param_spec_boolean ("has-unapplied",
803 P_("Has unapplied changes"),
804 P_("TRUE if there are outstanding changes to apply()"),
806 G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
809 * GSettings:delay-apply:
811 * Whether the #GSettings object is in 'delay-apply' mode. See
812 * g_settings_delay() for details.
816 g_object_class_install_property (object_class, PROP_DELAY_APPLY,
817 g_param_spec_boolean ("delay-apply",
818 P_("Delay-apply mode"),
819 P_("Whether this settings object is in 'delay-apply' mode"),
821 G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
824 /* Construction (new, new_with_path, etc.) {{{1 */
827 * @schema_id: the id of the schema
828 * @returns: a new #GSettings object
830 * Creates a new #GSettings object with the schema specified by
833 * Signals on the newly created #GSettings object will be dispatched
834 * via the thread-default #GMainContext in effect at the time of the
835 * call to g_settings_new(). The new #GSettings will hold a reference
836 * on the context. See g_main_context_push_thread_default().
841 g_settings_new (const gchar *schema_id)
843 g_return_val_if_fail (schema_id != NULL, NULL);
845 return g_object_new (G_TYPE_SETTINGS,
846 "schema-id", schema_id,
851 * g_settings_new_with_path:
852 * @schema_id: the id of the schema
853 * @path: the path to use
854 * @returns: a new #GSettings object
856 * Creates a new #GSettings object with the relocatable schema specified
857 * by @schema_id and a given path.
859 * You only need to do this if you want to directly create a settings
860 * object with a schema that doesn't have a specified path of its own.
863 * It is a programmer error to call this function for a schema that
864 * has an explicitly specified path.
869 g_settings_new_with_path (const gchar *schema_id,
872 g_return_val_if_fail (schema_id != NULL, NULL);
873 g_return_val_if_fail (path != NULL, NULL);
875 return g_object_new (G_TYPE_SETTINGS,
876 "schema-id", schema_id,
882 * g_settings_new_with_backend:
883 * @schema_id: the id of the schema
884 * @backend: the #GSettingsBackend to use
885 * @returns: a new #GSettings object
887 * Creates a new #GSettings object with the schema specified by
888 * @schema_id and a given #GSettingsBackend.
890 * Creating a #GSettings object with a different backend allows accessing
891 * settings from a database other than the usual one. For example, it may make
892 * sense to pass a backend corresponding to the "defaults" settings database on
893 * the system to get a settings object that modifies the system default
894 * settings instead of the settings for this user.
899 g_settings_new_with_backend (const gchar *schema_id,
900 GSettingsBackend *backend)
902 g_return_val_if_fail (schema_id != NULL, NULL);
903 g_return_val_if_fail (G_IS_SETTINGS_BACKEND (backend), NULL);
905 return g_object_new (G_TYPE_SETTINGS,
906 "schema-id", schema_id,
912 * g_settings_new_with_backend_and_path:
913 * @schema_id: the id of the schema
914 * @backend: the #GSettingsBackend to use
915 * @path: the path to use
916 * @returns: a new #GSettings object
918 * Creates a new #GSettings object with the schema specified by
919 * @schema_id and a given #GSettingsBackend and path.
921 * This is a mix of g_settings_new_with_backend() and
922 * g_settings_new_with_path().
927 g_settings_new_with_backend_and_path (const gchar *schema_id,
928 GSettingsBackend *backend,
931 g_return_val_if_fail (schema_id != NULL, NULL);
932 g_return_val_if_fail (G_IS_SETTINGS_BACKEND (backend), NULL);
933 g_return_val_if_fail (path != NULL, NULL);
935 return g_object_new (G_TYPE_SETTINGS,
936 "schema-id", schema_id,
943 * g_settings_new_full:
944 * @schema: a #GSettingsSchema
945 * @backend: (allow-none): a #GSettingsBackend
946 * @path: (allow-none): the path to use
947 * @returns: a new #GSettings object
949 * Creates a new #GSettings object with a given schema, backend and
952 * It should be extremely rare that you ever want to use this function.
953 * It is made available for advanced use-cases (such as plugin systems
954 * that want to provide access to schemas loaded from custom locations,
957 * At the most basic level, a #GSettings object is a pure composition of
958 * 4 things: a #GSettingsSchema, a #GSettingsBackend, a path within that
959 * backend, and a #GMainContext to which signals are dispatched.
961 * This constructor therefore gives you full control over constructing
962 * #GSettings instances. The first 4 parameters are given directly as
963 * @schema, @backend and @path, and the main context is taken from the
964 * thread-default (as per g_settings_new()).
966 * If @backend is %NULL then the default backend is used.
968 * If @path is %NULL then the path from the schema is used. It is an
969 * error f @path is %NULL and the schema has no path of its own or if
970 * @path is non-%NULL and not equal to the path that the schema does
976 g_settings_new_full (GSettingsSchema *schema,
977 GSettingsBackend *backend,
980 return g_object_new (G_TYPE_SETTINGS,
981 "settings-schema", schema,
987 /* Internal read/write utilities {{{1 */
989 g_settings_write_to_backend (GSettings *settings,
990 GSettingsSchemaKey *key,
996 path = g_strconcat (settings->priv->path, key->name, NULL);
997 success = g_settings_backend_write (settings->priv->backend, path, value, NULL);
1004 g_settings_read_from_backend (GSettings *settings,
1005 GSettingsSchemaKey *key)
1011 path = g_strconcat (settings->priv->path, key->name, NULL);
1012 value = g_settings_backend_read (settings->priv->backend, path, key->type, FALSE);
1017 fixup = g_settings_schema_key_range_fixup (key, value);
1018 g_variant_unref (value);
1026 /* Public Get/Set API {{{1 (get, get_value, set, set_value, get_mapped) */
1028 * g_settings_get_value:
1029 * @settings: a #GSettings object
1030 * @key: the key to get the value for
1031 * @returns: a new #GVariant
1033 * Gets the value that is stored in @settings for @key.
1035 * It is a programmer error to give a @key that isn't contained in the
1036 * schema for @settings.
1041 g_settings_get_value (GSettings *settings,
1044 GSettingsSchemaKey skey;
1047 g_return_val_if_fail (G_IS_SETTINGS (settings), NULL);
1048 g_return_val_if_fail (key != NULL, NULL);
1050 g_settings_schema_key_init (&skey, settings->priv->schema, key);
1051 value = g_settings_read_from_backend (settings, &skey);
1054 value = g_settings_schema_key_get_translated_default (&skey);
1057 value = g_variant_ref (skey.default_value);
1059 g_settings_schema_key_clear (&skey);
1065 * g_settings_get_enum:
1066 * @settings: a #GSettings object
1067 * @key: the key to get the value for
1068 * @returns: the enum value
1070 * Gets the value that is stored in @settings for @key and converts it
1071 * to the enum value that it represents.
1073 * In order to use this function the type of the value must be a string
1074 * and it must be marked in the schema file as an enumerated type.
1076 * It is a programmer error to give a @key that isn't contained in the
1077 * schema for @settings or is not marked as an enumerated type.
1079 * If the value stored in the configuration database is not a valid
1080 * value for the enumerated type then this function will return the
1086 g_settings_get_enum (GSettings *settings,
1089 GSettingsSchemaKey skey;
1093 g_return_val_if_fail (G_IS_SETTINGS (settings), -1);
1094 g_return_val_if_fail (key != NULL, -1);
1096 g_settings_schema_key_init (&skey, settings->priv->schema, key);
1100 g_critical ("g_settings_get_enum() called on key `%s' which is not "
1101 "associated with an enumerated type", skey.name);
1102 g_settings_schema_key_clear (&skey);
1106 value = g_settings_read_from_backend (settings, &skey);
1109 value = g_settings_schema_key_get_translated_default (&skey);
1112 value = g_variant_ref (skey.default_value);
1114 result = g_settings_schema_key_to_enum (&skey, value);
1115 g_settings_schema_key_clear (&skey);
1116 g_variant_unref (value);
1122 * g_settings_set_enum:
1123 * @settings: a #GSettings object
1124 * @key: a key, within @settings
1125 * @value: an enumerated value
1126 * @returns: %TRUE, if the set succeeds
1128 * Looks up the enumerated type nick for @value and writes it to @key,
1131 * It is a programmer error to give a @key that isn't contained in the
1132 * schema for @settings or is not marked as an enumerated type, or for
1133 * @value not to be a valid value for the named type.
1135 * After performing the write, accessing @key directly with
1136 * g_settings_get_string() will return the 'nick' associated with
1140 g_settings_set_enum (GSettings *settings,
1144 GSettingsSchemaKey skey;
1148 g_return_val_if_fail (G_IS_SETTINGS (settings), FALSE);
1149 g_return_val_if_fail (key != NULL, FALSE);
1151 g_settings_schema_key_init (&skey, settings->priv->schema, key);
1155 g_critical ("g_settings_set_enum() called on key `%s' which is not "
1156 "associated with an enumerated type", skey.name);
1160 if (!(variant = g_settings_schema_key_from_enum (&skey, value)))
1162 g_critical ("g_settings_set_enum(): invalid enum value %d for key `%s' "
1163 "in schema `%s'. Doing nothing.", value, skey.name,
1164 g_settings_schema_get_id (skey.schema));
1165 g_settings_schema_key_clear (&skey);
1169 success = g_settings_write_to_backend (settings, &skey, variant);
1170 g_settings_schema_key_clear (&skey);
1176 * g_settings_get_flags:
1177 * @settings: a #GSettings object
1178 * @key: the key to get the value for
1179 * @returns: the flags value
1181 * Gets the value that is stored in @settings for @key and converts it
1182 * to the flags value that it represents.
1184 * In order to use this function the type of the value must be an array
1185 * of strings and it must be marked in the schema file as an flags type.
1187 * It is a programmer error to give a @key that isn't contained in the
1188 * schema for @settings or is not marked as a flags type.
1190 * If the value stored in the configuration database is not a valid
1191 * value for the flags type then this function will return the default
1197 g_settings_get_flags (GSettings *settings,
1200 GSettingsSchemaKey skey;
1204 g_return_val_if_fail (G_IS_SETTINGS (settings), -1);
1205 g_return_val_if_fail (key != NULL, -1);
1207 g_settings_schema_key_init (&skey, settings->priv->schema, key);
1211 g_critical ("g_settings_get_flags() called on key `%s' which is not "
1212 "associated with a flags type", skey.name);
1213 g_settings_schema_key_clear (&skey);
1217 value = g_settings_read_from_backend (settings, &skey);
1220 value = g_settings_schema_key_get_translated_default (&skey);
1223 value = g_variant_ref (skey.default_value);
1225 result = g_settings_schema_key_to_flags (&skey, value);
1226 g_settings_schema_key_clear (&skey);
1227 g_variant_unref (value);
1233 * g_settings_set_flags:
1234 * @settings: a #GSettings object
1235 * @key: a key, within @settings
1236 * @value: a flags value
1237 * @returns: %TRUE, if the set succeeds
1239 * Looks up the flags type nicks for the bits specified by @value, puts
1240 * them in an array of strings and writes the array to @key, within
1243 * It is a programmer error to give a @key that isn't contained in the
1244 * schema for @settings or is not marked as a flags type, or for @value
1245 * to contain any bits that are not value for the named type.
1247 * After performing the write, accessing @key directly with
1248 * g_settings_get_strv() will return an array of 'nicks'; one for each
1252 g_settings_set_flags (GSettings *settings,
1256 GSettingsSchemaKey skey;
1260 g_return_val_if_fail (G_IS_SETTINGS (settings), FALSE);
1261 g_return_val_if_fail (key != NULL, FALSE);
1263 g_settings_schema_key_init (&skey, settings->priv->schema, key);
1267 g_critical ("g_settings_set_flags() called on key `%s' which is not "
1268 "associated with a flags type", skey.name);
1272 if (!(variant = g_settings_schema_key_from_flags (&skey, value)))
1274 g_critical ("g_settings_set_flags(): invalid flags value 0x%08x "
1275 "for key `%s' in schema `%s'. Doing nothing.",
1276 value, skey.name, g_settings_schema_get_id (skey.schema));
1277 g_settings_schema_key_clear (&skey);
1281 success = g_settings_write_to_backend (settings, &skey, variant);
1282 g_settings_schema_key_clear (&skey);
1288 * g_settings_set_value:
1289 * @settings: a #GSettings object
1290 * @key: the name of the key to set
1291 * @value: a #GVariant of the correct type
1292 * @returns: %TRUE if setting the key succeeded,
1293 * %FALSE if the key was not writable
1295 * Sets @key in @settings to @value.
1297 * It is a programmer error to give a @key that isn't contained in the
1298 * schema for @settings or for @value to have the incorrect type, per
1301 * If @value is floating then this function consumes the reference.
1306 g_settings_set_value (GSettings *settings,
1310 GSettingsSchemaKey skey;
1312 g_return_val_if_fail (G_IS_SETTINGS (settings), FALSE);
1313 g_return_val_if_fail (key != NULL, FALSE);
1315 g_settings_schema_key_init (&skey, settings->priv->schema, key);
1317 if (!g_settings_schema_key_type_check (&skey, value))
1319 g_critical ("g_settings_set_value: key '%s' in '%s' expects type '%s', but a GVariant of type '%s' was given",
1321 g_settings_schema_get_id (settings->priv->schema),
1322 g_variant_type_peek_string (skey.type),
1323 g_variant_get_type_string (value));
1328 if (!g_settings_schema_key_range_check (&skey, value))
1330 g_warning ("g_settings_set_value: value for key '%s' in schema '%s' "
1331 "is outside of valid range",
1333 g_settings_schema_get_id (settings->priv->schema));
1338 g_settings_schema_key_clear (&skey);
1340 return g_settings_write_to_backend (settings, &skey, value);
1345 * @settings: a #GSettings object
1346 * @key: the key to get the value for
1347 * @format: a #GVariant format string
1348 * @...: arguments as per @format
1350 * Gets the value that is stored at @key in @settings.
1352 * A convenience function that combines g_settings_get_value() with
1355 * It is a programmer error to give a @key that isn't contained in the
1356 * schema for @settings or for the #GVariantType of @format to mismatch
1357 * the type given in the schema.
1362 g_settings_get (GSettings *settings,
1364 const gchar *format,
1370 value = g_settings_get_value (settings, key);
1372 va_start (ap, format);
1373 g_variant_get_va (value, format, NULL, &ap);
1376 g_variant_unref (value);
1381 * @settings: a #GSettings object
1382 * @key: the name of the key to set
1383 * @format: a #GVariant format string
1384 * @...: arguments as per @format
1385 * @returns: %TRUE if setting the key succeeded,
1386 * %FALSE if the key was not writable
1388 * Sets @key in @settings to @value.
1390 * A convenience function that combines g_settings_set_value() with
1393 * It is a programmer error to give a @key that isn't contained in the
1394 * schema for @settings or for the #GVariantType of @format to mismatch
1395 * the type given in the schema.
1400 g_settings_set (GSettings *settings,
1402 const gchar *format,
1408 va_start (ap, format);
1409 value = g_variant_new_va (format, NULL, &ap);
1412 return g_settings_set_value (settings, key, value);
1416 * g_settings_get_mapped:
1417 * @settings: a #GSettings object
1418 * @key: the key to get the value for
1419 * @mapping: (scope call): the function to map the value in the
1420 * settings database to the value used by the application
1421 * @user_data: user data for @mapping
1422 * @returns: (transfer full): the result, which may be %NULL
1424 * Gets the value that is stored at @key in @settings, subject to
1425 * application-level validation/mapping.
1427 * You should use this function when the application needs to perform
1428 * some processing on the value of the key (for example, parsing). The
1429 * @mapping function performs that processing. If the function
1430 * indicates that the processing was unsuccessful (due to a parse error,
1431 * for example) then the mapping is tried again with another value.
1433 * This allows a robust 'fall back to defaults' behaviour to be
1434 * implemented somewhat automatically.
1436 * The first value that is tried is the user's setting for the key. If
1437 * the mapping function fails to map this value, other values may be
1438 * tried in an unspecified order (system or site defaults, translated
1439 * schema default values, untranslated schema default values, etc).
1441 * If the mapping function fails for all possible values, one additional
1442 * attempt is made: the mapping function is called with a %NULL value.
1443 * If the mapping function still indicates failure at this point then
1444 * the application will be aborted.
1446 * The result parameter for the @mapping function is pointed to a
1447 * #gpointer which is initially set to %NULL. The same pointer is given
1448 * to each invocation of @mapping. The final value of that #gpointer is
1449 * what is returned by this function. %NULL is valid; it is returned
1450 * just as any other value would be.
1453 g_settings_get_mapped (GSettings *settings,
1455 GSettingsGetMapping mapping,
1458 gpointer result = NULL;
1459 GSettingsSchemaKey skey;
1463 g_return_val_if_fail (G_IS_SETTINGS (settings), NULL);
1464 g_return_val_if_fail (key != NULL, NULL);
1465 g_return_val_if_fail (mapping != NULL, NULL);
1467 g_settings_schema_key_init (&skey, settings->priv->schema, key);
1469 if ((value = g_settings_read_from_backend (settings, &skey)))
1471 okay = mapping (value, &result, user_data);
1472 g_variant_unref (value);
1473 if (okay) goto okay;
1476 if ((value = g_settings_schema_key_get_translated_default (&skey)))
1478 okay = mapping (value, &result, user_data);
1479 g_variant_unref (value);
1480 if (okay) goto okay;
1483 if (mapping (skey.default_value, &result, user_data))
1486 if (!mapping (NULL, &result, user_data))
1487 g_error ("The mapping function given to g_settings_get_mapped() for key "
1488 "`%s' in schema `%s' returned FALSE when given a NULL value.",
1489 key, g_settings_schema_get_id (settings->priv->schema));
1492 g_settings_schema_key_clear (&skey);
1497 /* Convenience API (get, set_string, int, double, boolean, strv) {{{1 */
1499 * g_settings_get_string:
1500 * @settings: a #GSettings object
1501 * @key: the key to get the value for
1502 * @returns: a newly-allocated string
1504 * Gets the value that is stored at @key in @settings.
1506 * A convenience variant of g_settings_get() for strings.
1508 * It is a programmer error to give a @key that isn't specified as
1509 * having a string type in the schema for @settings.
1514 g_settings_get_string (GSettings *settings,
1520 value = g_settings_get_value (settings, key);
1521 result = g_variant_dup_string (value, NULL);
1522 g_variant_unref (value);
1528 * g_settings_set_string:
1529 * @settings: a #GSettings object
1530 * @key: the name of the key to set
1531 * @value: the value to set it to
1532 * @returns: %TRUE if setting the key succeeded,
1533 * %FALSE if the key was not writable
1535 * Sets @key in @settings to @value.
1537 * A convenience variant of g_settings_set() for strings.
1539 * It is a programmer error to give a @key that isn't specified as
1540 * having a string type in the schema for @settings.
1545 g_settings_set_string (GSettings *settings,
1549 return g_settings_set_value (settings, key, g_variant_new_string (value));
1553 * g_settings_get_int:
1554 * @settings: a #GSettings object
1555 * @key: the key to get the value for
1556 * @returns: an integer
1558 * Gets the value that is stored at @key in @settings.
1560 * A convenience variant of g_settings_get() for 32-bit integers.
1562 * It is a programmer error to give a @key that isn't specified as
1563 * having a int32 type in the schema for @settings.
1568 g_settings_get_int (GSettings *settings,
1574 value = g_settings_get_value (settings, key);
1575 result = g_variant_get_int32 (value);
1576 g_variant_unref (value);
1582 * g_settings_set_int:
1583 * @settings: a #GSettings object
1584 * @key: the name of the key to set
1585 * @value: the value to set it to
1586 * @returns: %TRUE if setting the key succeeded,
1587 * %FALSE if the key was not writable
1589 * Sets @key in @settings to @value.
1591 * A convenience variant of g_settings_set() for 32-bit integers.
1593 * It is a programmer error to give a @key that isn't specified as
1594 * having a int32 type in the schema for @settings.
1599 g_settings_set_int (GSettings *settings,
1603 return g_settings_set_value (settings, key, g_variant_new_int32 (value));
1607 * g_settings_get_uint:
1608 * @settings: a #GSettings object
1609 * @key: the key to get the value for
1610 * @returns: an unsigned integer
1612 * Gets the value that is stored at @key in @settings.
1614 * A convenience variant of g_settings_get() for 32-bit unsigned
1617 * It is a programmer error to give a @key that isn't specified as
1618 * having a uint32 type in the schema for @settings.
1623 g_settings_get_uint (GSettings *settings,
1629 value = g_settings_get_value (settings, key);
1630 result = g_variant_get_uint32 (value);
1631 g_variant_unref (value);
1637 * g_settings_set_uint:
1638 * @settings: a #GSettings object
1639 * @key: the name of the key to set
1640 * @value: the value to set it to
1641 * @returns: %TRUE if setting the key succeeded,
1642 * %FALSE if the key was not writable
1644 * Sets @key in @settings to @value.
1646 * A convenience variant of g_settings_set() for 32-bit unsigned
1649 * It is a programmer error to give a @key that isn't specified as
1650 * having a uint32 type in the schema for @settings.
1655 g_settings_set_uint (GSettings *settings,
1659 return g_settings_set_value (settings, key, g_variant_new_uint32 (value));
1663 * g_settings_get_double:
1664 * @settings: a #GSettings object
1665 * @key: the key to get the value for
1666 * @returns: a double
1668 * Gets the value that is stored at @key in @settings.
1670 * A convenience variant of g_settings_get() for doubles.
1672 * It is a programmer error to give a @key that isn't specified as
1673 * having a 'double' type in the schema for @settings.
1678 g_settings_get_double (GSettings *settings,
1684 value = g_settings_get_value (settings, key);
1685 result = g_variant_get_double (value);
1686 g_variant_unref (value);
1692 * g_settings_set_double:
1693 * @settings: a #GSettings object
1694 * @key: the name of the key to set
1695 * @value: the value to set it to
1696 * @returns: %TRUE if setting the key succeeded,
1697 * %FALSE if the key was not writable
1699 * Sets @key in @settings to @value.
1701 * A convenience variant of g_settings_set() for doubles.
1703 * It is a programmer error to give a @key that isn't specified as
1704 * having a 'double' type in the schema for @settings.
1709 g_settings_set_double (GSettings *settings,
1713 return g_settings_set_value (settings, key, g_variant_new_double (value));
1717 * g_settings_get_boolean:
1718 * @settings: a #GSettings object
1719 * @key: the key to get the value for
1720 * @returns: a boolean
1722 * Gets the value that is stored at @key in @settings.
1724 * A convenience variant of g_settings_get() for booleans.
1726 * It is a programmer error to give a @key that isn't specified as
1727 * having a boolean type in the schema for @settings.
1732 g_settings_get_boolean (GSettings *settings,
1738 value = g_settings_get_value (settings, key);
1739 result = g_variant_get_boolean (value);
1740 g_variant_unref (value);
1746 * g_settings_set_boolean:
1747 * @settings: a #GSettings object
1748 * @key: the name of the key to set
1749 * @value: the value to set it to
1750 * @returns: %TRUE if setting the key succeeded,
1751 * %FALSE if the key was not writable
1753 * Sets @key in @settings to @value.
1755 * A convenience variant of g_settings_set() for booleans.
1757 * It is a programmer error to give a @key that isn't specified as
1758 * having a boolean type in the schema for @settings.
1763 g_settings_set_boolean (GSettings *settings,
1767 return g_settings_set_value (settings, key, g_variant_new_boolean (value));
1771 * g_settings_get_strv:
1772 * @settings: a #GSettings object
1773 * @key: the key to get the value for
1774 * @returns: (array zero-terminated=1) (transfer full): a
1775 * newly-allocated, %NULL-terminated array of strings, the value that
1776 * is stored at @key in @settings.
1778 * A convenience variant of g_settings_get() for string arrays.
1780 * It is a programmer error to give a @key that isn't specified as
1781 * having an array of strings type in the schema for @settings.
1786 g_settings_get_strv (GSettings *settings,
1792 value = g_settings_get_value (settings, key);
1793 result = g_variant_dup_strv (value, NULL);
1794 g_variant_unref (value);
1800 * g_settings_set_strv:
1801 * @settings: a #GSettings object
1802 * @key: the name of the key to set
1803 * @value: (allow-none) (array zero-terminated=1): the value to set it to, or %NULL
1804 * @returns: %TRUE if setting the key succeeded,
1805 * %FALSE if the key was not writable
1807 * Sets @key in @settings to @value.
1809 * A convenience variant of g_settings_set() for string arrays. If
1810 * @value is %NULL, then @key is set to be the empty array.
1812 * It is a programmer error to give a @key that isn't specified as
1813 * having an array of strings type in the schema for @settings.
1818 g_settings_set_strv (GSettings *settings,
1820 const gchar * const *value)
1825 array = g_variant_new_strv (value, -1);
1827 array = g_variant_new_strv (NULL, 0);
1829 return g_settings_set_value (settings, key, array);
1832 /* Delayed apply (delay, apply, revert, get_has_unapplied) {{{1 */
1835 * @settings: a #GSettings object
1837 * Changes the #GSettings object into 'delay-apply' mode. In this
1838 * mode, changes to @settings are not immediately propagated to the
1839 * backend, but kept locally until g_settings_apply() is called.
1844 g_settings_delay (GSettings *settings)
1846 g_return_if_fail (G_IS_SETTINGS (settings));
1848 if (settings->priv->delayed)
1851 settings->priv->delayed =
1852 g_delayed_settings_backend_new (settings->priv->backend,
1854 settings->priv->main_context);
1855 g_settings_backend_unwatch (settings->priv->backend, G_OBJECT (settings));
1856 g_object_unref (settings->priv->backend);
1858 settings->priv->backend = G_SETTINGS_BACKEND (settings->priv->delayed);
1859 g_settings_backend_watch (settings->priv->backend,
1860 &listener_vtable, G_OBJECT (settings),
1861 settings->priv->main_context);
1863 g_object_notify (G_OBJECT (settings), "delay-apply");
1868 * @settings: a #GSettings instance
1870 * Applies any changes that have been made to the settings. This
1871 * function does nothing unless @settings is in 'delay-apply' mode;
1872 * see g_settings_delay(). In the normal case settings are always
1873 * applied immediately.
1876 g_settings_apply (GSettings *settings)
1878 if (settings->priv->delayed)
1880 GDelayedSettingsBackend *delayed;
1882 delayed = G_DELAYED_SETTINGS_BACKEND (settings->priv->backend);
1883 g_delayed_settings_backend_apply (delayed);
1888 * g_settings_revert:
1889 * @settings: a #GSettings instance
1891 * Reverts all non-applied changes to the settings. This function
1892 * does nothing unless @settings is in 'delay-apply' mode; see
1893 * g_settings_delay(). In the normal case settings are always applied
1896 * Change notifications will be emitted for affected keys.
1899 g_settings_revert (GSettings *settings)
1901 if (settings->priv->delayed)
1903 GDelayedSettingsBackend *delayed;
1905 delayed = G_DELAYED_SETTINGS_BACKEND (settings->priv->backend);
1906 g_delayed_settings_backend_revert (delayed);
1911 * g_settings_get_has_unapplied:
1912 * @settings: a #GSettings object
1913 * @returns: %TRUE if @settings has unapplied changes
1915 * Returns whether the #GSettings object has any unapplied
1916 * changes. This can only be the case if it is in 'delayed-apply' mode.
1921 g_settings_get_has_unapplied (GSettings *settings)
1923 g_return_val_if_fail (G_IS_SETTINGS (settings), FALSE);
1925 return settings->priv->delayed &&
1926 g_delayed_settings_backend_get_has_unapplied (
1927 G_DELAYED_SETTINGS_BACKEND (settings->priv->backend));
1930 /* Extra API (reset, sync, get_child, is_writable, list_*, ranges) {{{1 */
1933 * @settings: a #GSettings object
1934 * @key: the name of a key
1936 * Resets @key to its default value.
1938 * This call resets the key, as much as possible, to its default value.
1939 * That might the value specified in the schema or the one set by the
1943 g_settings_reset (GSettings *settings,
1948 path = g_strconcat (settings->priv->path, key, NULL);
1949 g_settings_backend_reset (settings->priv->backend, path, NULL);
1956 * Ensures that all pending operations for the given are complete for
1957 * the default backend.
1959 * Writes made to a #GSettings are handled asynchronously. For this
1960 * reason, it is very unlikely that the changes have it to disk by the
1961 * time g_settings_set() returns.
1963 * This call will block until all of the writes have made it to the
1964 * backend. Since the mainloop is not running, no change notifications
1965 * will be dispatched during this call (but some may be queued by the
1966 * time the call is done).
1969 g_settings_sync (void)
1971 g_settings_backend_sync_default ();
1975 * g_settings_is_writable:
1976 * @settings: a #GSettings object
1977 * @name: the name of a key
1978 * @returns: %TRUE if the key @name is writable
1980 * Finds out if a key can be written or not
1985 g_settings_is_writable (GSettings *settings,
1991 g_return_val_if_fail (G_IS_SETTINGS (settings), FALSE);
1993 path = g_strconcat (settings->priv->path, name, NULL);
1994 writable = g_settings_backend_get_writable (settings->priv->backend, path);
2001 * g_settings_get_child:
2002 * @settings: a #GSettings object
2003 * @name: the name of the 'child' schema
2004 * @returns: (transfer full): a 'child' settings object
2006 * Creates a 'child' settings object which has a base path of
2007 * <replaceable>base-path</replaceable>/@name, where
2008 * <replaceable>base-path</replaceable> is the base path of @settings.
2010 * The schema for the child settings object must have been declared
2011 * in the schema of @settings using a <tag class="starttag">child</tag> element.
2016 g_settings_get_child (GSettings *settings,
2019 const gchar *child_schema;
2024 g_return_val_if_fail (G_IS_SETTINGS (settings), NULL);
2026 child_name = g_strconcat (name, "/", NULL);
2027 child_schema = g_settings_schema_get_string (settings->priv->schema,
2029 if (child_schema == NULL)
2030 g_error ("Schema '%s' has no child '%s'",
2031 g_settings_schema_get_id (settings->priv->schema), name);
2033 child_path = g_strconcat (settings->priv->path, child_name, NULL);
2034 child = g_object_new (G_TYPE_SETTINGS,
2035 "schema-id", child_schema,
2038 g_free (child_path);
2039 g_free (child_name);
2045 * g_settings_list_keys:
2046 * @settings: a #GSettings object
2047 * @returns: (transfer full) (element-type utf8): a list of the keys on @settings
2049 * Introspects the list of keys on @settings.
2051 * You should probably not be calling this function from "normal" code
2052 * (since you should already know what keys are in your schema). This
2053 * function is intended for introspection reasons.
2055 * You should free the return value with g_strfreev() when you are done
2059 g_settings_list_keys (GSettings *settings)
2066 keys = g_settings_schema_list (settings->priv->schema, &n_keys);
2067 strv = g_new (gchar *, n_keys + 1);
2068 for (i = j = 0; i < n_keys; i++)
2070 const gchar *key = g_quark_to_string (keys[i]);
2072 if (!g_str_has_suffix (key, "/"))
2073 strv[j++] = g_strdup (key);
2081 * g_settings_list_children:
2082 * @settings: a #GSettings object
2083 * @returns: (transfer full) (element-type utf8): a list of the children on @settings
2085 * Gets the list of children on @settings.
2087 * The list is exactly the list of strings for which it is not an error
2088 * to call g_settings_get_child().
2090 * For GSettings objects that are lists, this value can change at any
2091 * time and you should connect to the "children-changed" signal to watch
2092 * for those changes. Note that there is a race condition here: you may
2093 * request a child after listing it only for it to have been destroyed
2094 * in the meantime. For this reason, g_settings_get_child() may return
2095 * %NULL even for a child that was listed by this function.
2097 * For GSettings objects that are not lists, you should probably not be
2098 * calling this function from "normal" code (since you should already
2099 * know what children are in your schema). This function may still be
2100 * useful there for introspection reasons, however.
2102 * You should free the return value with g_strfreev() when you are done
2106 g_settings_list_children (GSettings *settings)
2113 keys = g_settings_schema_list (settings->priv->schema, &n_keys);
2114 strv = g_new (gchar *, n_keys + 1);
2115 for (i = j = 0; i < n_keys; i++)
2117 const gchar *key = g_quark_to_string (keys[i]);
2119 if (g_str_has_suffix (key, "/"))
2121 gint length = strlen (key);
2123 strv[j] = g_memdup (key, length);
2124 strv[j][length - 1] = '\0';
2134 * g_settings_get_range:
2135 * @settings: a #GSettings
2136 * @key: the key to query the range of
2137 * @returns: a #GVariant describing the range
2139 * Queries the range of a key.
2141 * This function will return a #GVariant that fully describes the range
2142 * of values that are valid for @key.
2144 * The type of #GVariant returned is <literal>(sv)</literal>. The
2145 * string describes the type of range restriction in effect. The type
2146 * and meaning of the value contained in the variant depends on the
2149 * If the string is <literal>'type'</literal> then the variant contains
2150 * an empty array. The element type of that empty array is the expected
2151 * type of value and all values of that type are valid.
2153 * If the string is <literal>'enum'</literal> then the variant contains
2154 * an array enumerating the possible values. Each item in the array is
2155 * a possible valid value and no other values are valid.
2157 * If the string is <literal>'flags'</literal> then the variant contains
2158 * an array. Each item in the array is a value that may appear zero or
2159 * one times in an array to be used as the value for this key. For
2160 * example, if the variant contained the array <literal>['x',
2161 * 'y']</literal> then the valid values for the key would be
2162 * <literal>[]</literal>, <literal>['x']</literal>,
2163 * <literal>['y']</literal>, <literal>['x', 'y']</literal> and
2164 * <literal>['y', 'x']</literal>.
2166 * Finally, if the string is <literal>'range'</literal> then the variant
2167 * contains a pair of like-typed values -- the minimum and maximum
2168 * permissible values for this key.
2170 * This information should not be used by normal programs. It is
2171 * considered to be a hint for introspection purposes. Normal programs
2172 * should already know what is permitted by their own schema. The
2173 * format may change in any way in the future -- but particularly, new
2174 * forms may be added to the possibilities described above.
2176 * It is a programmer error to give a @key that isn't contained in the
2177 * schema for @settings.
2179 * You should free the returned value with g_variant_unref() when it is
2185 g_settings_get_range (GSettings *settings,
2188 GSettingsSchemaKey skey;
2192 g_settings_schema_key_init (&skey, settings->priv->schema, key);
2196 range = g_variant_new ("(**)", skey.minimum, skey.maximum);
2199 else if (skey.strinfo)
2201 range = strinfo_enumerate (skey.strinfo, skey.strinfo_length);
2202 type = skey.is_flags ? "flags" : "enum";
2206 range = g_variant_new_array (skey.type, NULL, 0);
2210 g_settings_schema_key_clear (&skey);
2212 return g_variant_ref_sink (g_variant_new ("(sv)", type, range));
2216 * g_settings_range_check:
2217 * @settings: a #GSettings
2218 * @key: the key to check
2219 * @value: the value to check
2220 * @returns: %TRUE if @value is valid for @key
2222 * Checks if the given @value is of the correct type and within the
2223 * permitted range for @key.
2225 * This API is not intended to be used by normal programs -- they should
2226 * already know what is permitted by their own schemas. This API is
2227 * meant to be used by programs such as editors or commandline tools.
2229 * It is a programmer error to give a @key that isn't contained in the
2230 * schema for @settings.
2235 g_settings_range_check (GSettings *settings,
2239 GSettingsSchemaKey skey;
2242 g_settings_schema_key_init (&skey, settings->priv->schema, key);
2243 good = g_settings_schema_key_type_check (&skey, value) &&
2244 g_settings_schema_key_range_check (&skey, value);
2245 g_settings_schema_key_clear (&skey);
2253 GSettingsSchemaKey key;
2254 GSettings *settings;
2257 GSettingsBindGetMapping get_mapping;
2258 GSettingsBindSetMapping set_mapping;
2260 GDestroyNotify destroy;
2262 guint writable_handler_id;
2263 guint property_handler_id;
2264 const GParamSpec *property;
2265 guint key_handler_id;
2267 /* prevent recursion */
2272 g_settings_binding_free (gpointer data)
2274 GSettingsBinding *binding = data;
2276 g_assert (!binding->running);
2278 if (binding->writable_handler_id)
2279 g_signal_handler_disconnect (binding->settings,
2280 binding->writable_handler_id);
2282 if (binding->key_handler_id)
2283 g_signal_handler_disconnect (binding->settings,
2284 binding->key_handler_id);
2286 if (g_signal_handler_is_connected (binding->object,
2287 binding->property_handler_id))
2288 g_signal_handler_disconnect (binding->object,
2289 binding->property_handler_id);
2291 g_settings_schema_key_clear (&binding->key);
2293 if (binding->destroy)
2294 binding->destroy (binding->user_data);
2296 g_object_unref (binding->settings);
2298 g_slice_free (GSettingsBinding, binding);
2302 g_settings_binding_quark (const char *property)
2307 tmp = g_strdup_printf ("gsettingsbinding-%s", property);
2308 quark = g_quark_from_string (tmp);
2315 g_settings_binding_key_changed (GSettings *settings,
2319 GSettingsBinding *binding = user_data;
2320 GValue value = G_VALUE_INIT;
2323 g_assert (settings == binding->settings);
2324 g_assert (key == binding->key.name);
2326 if (binding->running)
2329 binding->running = TRUE;
2331 g_value_init (&value, binding->property->value_type);
2333 variant = g_settings_read_from_backend (binding->settings, &binding->key);
2334 if (variant && !binding->get_mapping (&value, variant, binding->user_data))
2336 /* silently ignore errors in the user's config database */
2337 g_variant_unref (variant);
2341 if (variant == NULL)
2343 variant = g_settings_schema_key_get_translated_default (&binding->key);
2345 !binding->get_mapping (&value, variant, binding->user_data))
2347 /* flag translation errors with a warning */
2348 g_warning ("Translated default `%s' for key `%s' in schema `%s' "
2349 "was rejected by the binding mapping function",
2350 binding->key.unparsed, binding->key.name,
2351 g_settings_schema_get_id (binding->key.schema));
2352 g_variant_unref (variant);
2357 if (variant == NULL)
2359 variant = g_variant_ref (binding->key.default_value);
2360 if (!binding->get_mapping (&value, variant, binding->user_data))
2361 g_error ("The schema default value for key `%s' in schema `%s' "
2362 "was rejected by the binding mapping function.",
2363 binding->key.name, g_settings_schema_get_id (binding->key.schema));
2366 g_object_set_property (binding->object, binding->property->name, &value);
2367 g_variant_unref (variant);
2368 g_value_unset (&value);
2370 binding->running = FALSE;
2374 g_settings_binding_property_changed (GObject *object,
2375 const GParamSpec *pspec,
2378 GSettingsBinding *binding = user_data;
2379 GValue value = G_VALUE_INIT;
2382 g_assert (object == binding->object);
2383 g_assert (pspec == binding->property);
2385 if (binding->running)
2388 binding->running = TRUE;
2390 g_value_init (&value, pspec->value_type);
2391 g_object_get_property (object, pspec->name, &value);
2392 if ((variant = binding->set_mapping (&value, binding->key.type,
2393 binding->user_data)))
2395 g_variant_take_ref (variant);
2397 if (!g_settings_schema_key_type_check (&binding->key, variant))
2399 g_critical ("binding mapping function for key `%s' returned "
2400 "GVariant of type `%s' when type `%s' was requested",
2401 binding->key.name, g_variant_get_type_string (variant),
2402 g_variant_type_dup_string (binding->key.type));
2406 if (!g_settings_schema_key_range_check (&binding->key, variant))
2408 g_critical ("GObject property `%s' on a `%s' object is out of "
2409 "schema-specified range for key `%s' of `%s': %s",
2410 binding->property->name, g_type_name (binding->property->owner_type),
2411 binding->key.name, g_settings_schema_get_id (binding->key.schema),
2412 g_variant_print (variant, TRUE));
2416 g_settings_write_to_backend (binding->settings, &binding->key, variant);
2417 g_variant_unref (variant);
2419 g_value_unset (&value);
2421 binding->running = FALSE;
2425 g_settings_bind_invert_boolean_get_mapping (GValue *value,
2429 g_value_set_boolean (value, !g_variant_get_boolean (variant));
2434 g_settings_bind_invert_boolean_set_mapping (const GValue *value,
2435 const GVariantType *expected_type,
2438 return g_variant_new_boolean (!g_value_get_boolean (value));
2443 * @settings: a #GSettings object
2444 * @key: the key to bind
2445 * @object: (type GObject.Object): a #GObject
2446 * @property: the name of the property to bind
2447 * @flags: flags for the binding
2449 * Create a binding between the @key in the @settings object
2450 * and the property @property of @object.
2452 * The binding uses the default GIO mapping functions to map
2453 * between the settings and property values. These functions
2454 * handle booleans, numeric types and string types in a
2455 * straightforward way. Use g_settings_bind_with_mapping() if
2456 * you need a custom mapping, or map between types that are not
2457 * supported by the default mapping functions.
2459 * Unless the @flags include %G_SETTINGS_BIND_NO_SENSITIVITY, this
2460 * function also establishes a binding between the writability of
2461 * @key and the "sensitive" property of @object (if @object has
2462 * a boolean property by that name). See g_settings_bind_writable()
2463 * for more details about writable bindings.
2465 * Note that the lifecycle of the binding is tied to the object,
2466 * and that you can have only one binding per object property.
2467 * If you bind the same property twice on the same object, the second
2468 * binding overrides the first one.
2473 g_settings_bind (GSettings *settings,
2476 const gchar *property,
2477 GSettingsBindFlags flags)
2479 GSettingsBindGetMapping get_mapping = NULL;
2480 GSettingsBindSetMapping set_mapping = NULL;
2482 if (flags & G_SETTINGS_BIND_INVERT_BOOLEAN)
2484 get_mapping = g_settings_bind_invert_boolean_get_mapping;
2485 set_mapping = g_settings_bind_invert_boolean_set_mapping;
2487 /* can't pass this flag to g_settings_bind_with_mapping() */
2488 flags &= ~G_SETTINGS_BIND_INVERT_BOOLEAN;
2491 g_settings_bind_with_mapping (settings, key, object, property, flags,
2492 get_mapping, set_mapping, NULL, NULL);
2496 * g_settings_bind_with_mapping: (skip)
2497 * @settings: a #GSettings object
2498 * @key: the key to bind
2499 * @object: (type GObject.Object): a #GObject
2500 * @property: the name of the property to bind
2501 * @flags: flags for the binding
2502 * @get_mapping: a function that gets called to convert values
2503 * from @settings to @object, or %NULL to use the default GIO mapping
2504 * @set_mapping: a function that gets called to convert values
2505 * from @object to @settings, or %NULL to use the default GIO mapping
2506 * @user_data: data that gets passed to @get_mapping and @set_mapping
2507 * @destroy: #GDestroyNotify function for @user_data
2509 * Create a binding between the @key in the @settings object
2510 * and the property @property of @object.
2512 * The binding uses the provided mapping functions to map between
2513 * settings and property values.
2515 * Note that the lifecycle of the binding is tied to the object,
2516 * and that you can have only one binding per object property.
2517 * If you bind the same property twice on the same object, the second
2518 * binding overrides the first one.
2523 g_settings_bind_with_mapping (GSettings *settings,
2526 const gchar *property,
2527 GSettingsBindFlags flags,
2528 GSettingsBindGetMapping get_mapping,
2529 GSettingsBindSetMapping set_mapping,
2531 GDestroyNotify destroy)
2533 GSettingsBinding *binding;
2534 GObjectClass *objectclass;
2535 gchar *detailed_signal;
2536 GQuark binding_quark;
2538 g_return_if_fail (G_IS_SETTINGS (settings));
2539 g_return_if_fail (key != NULL);
2540 g_return_if_fail (G_IS_OBJECT (object));
2541 g_return_if_fail (property != NULL);
2542 g_return_if_fail (~flags & G_SETTINGS_BIND_INVERT_BOOLEAN);
2544 objectclass = G_OBJECT_GET_CLASS (object);
2546 binding = g_slice_new0 (GSettingsBinding);
2547 g_settings_schema_key_init (&binding->key, settings->priv->schema, key);
2548 binding->settings = g_object_ref (settings);
2549 binding->object = object;
2550 binding->property = g_object_class_find_property (objectclass, property);
2551 binding->user_data = user_data;
2552 binding->destroy = destroy;
2553 binding->get_mapping = get_mapping ? get_mapping : g_settings_get_mapping;
2554 binding->set_mapping = set_mapping ? set_mapping : g_settings_set_mapping;
2556 if (!(flags & (G_SETTINGS_BIND_GET | G_SETTINGS_BIND_SET)))
2557 flags |= G_SETTINGS_BIND_GET | G_SETTINGS_BIND_SET;
2559 if (binding->property == NULL)
2561 g_critical ("g_settings_bind: no property '%s' on class '%s'",
2562 property, G_OBJECT_TYPE_NAME (object));
2566 if ((flags & G_SETTINGS_BIND_GET) &&
2567 (binding->property->flags & G_PARAM_WRITABLE) == 0)
2569 g_critical ("g_settings_bind: property '%s' on class '%s' is not "
2570 "writable", property, G_OBJECT_TYPE_NAME (object));
2573 if ((flags & G_SETTINGS_BIND_SET) &&
2574 (binding->property->flags & G_PARAM_READABLE) == 0)
2576 g_critical ("g_settings_bind: property '%s' on class '%s' is not "
2577 "readable", property, G_OBJECT_TYPE_NAME (object));
2581 if (get_mapping == g_settings_bind_invert_boolean_get_mapping)
2583 /* g_settings_bind_invert_boolean_get_mapping() is a private
2584 * function, so if we are here it means that g_settings_bind() was
2585 * called with G_SETTINGS_BIND_INVERT_BOOLEAN.
2587 * Ensure that both sides are boolean.
2590 if (binding->property->value_type != G_TYPE_BOOLEAN)
2592 g_critical ("g_settings_bind: G_SETTINGS_BIND_INVERT_BOOLEAN "
2593 "was specified, but property `%s' on type `%s' has "
2594 "type `%s'", property, G_OBJECT_TYPE_NAME (object),
2595 g_type_name ((binding->property->value_type)));
2599 if (!g_variant_type_equal (binding->key.type, G_VARIANT_TYPE_BOOLEAN))
2601 g_critical ("g_settings_bind: G_SETTINGS_BIND_INVERT_BOOLEAN "
2602 "was specified, but key `%s' on schema `%s' has "
2603 "type `%s'", key, g_settings_schema_get_id (settings->priv->schema),
2604 g_variant_type_dup_string (binding->key.type));
2610 else if (((get_mapping == NULL && (flags & G_SETTINGS_BIND_GET)) ||
2611 (set_mapping == NULL && (flags & G_SETTINGS_BIND_SET))) &&
2612 !g_settings_mapping_is_compatible (binding->property->value_type,
2615 g_critical ("g_settings_bind: property '%s' on class '%s' has type "
2616 "'%s' which is not compatible with type '%s' of key '%s' "
2617 "on schema '%s'", property, G_OBJECT_TYPE_NAME (object),
2618 g_type_name (binding->property->value_type),
2619 g_variant_type_dup_string (binding->key.type), key,
2620 g_settings_schema_get_id (settings->priv->schema));
2624 if ((flags & G_SETTINGS_BIND_SET) &&
2625 (~flags & G_SETTINGS_BIND_NO_SENSITIVITY))
2627 GParamSpec *sensitive;
2629 sensitive = g_object_class_find_property (objectclass, "sensitive");
2631 if (sensitive && sensitive->value_type == G_TYPE_BOOLEAN &&
2632 (sensitive->flags & G_PARAM_WRITABLE))
2633 g_settings_bind_writable (settings, binding->key.name, object, "sensitive", FALSE);
2636 if (flags & G_SETTINGS_BIND_SET)
2638 detailed_signal = g_strdup_printf ("notify::%s", property);
2639 binding->property_handler_id =
2640 g_signal_connect (object, detailed_signal,
2641 G_CALLBACK (g_settings_binding_property_changed),
2643 g_free (detailed_signal);
2645 if (~flags & G_SETTINGS_BIND_GET)
2646 g_settings_binding_property_changed (object,
2651 if (flags & G_SETTINGS_BIND_GET)
2653 if (~flags & G_SETTINGS_BIND_GET_NO_CHANGES)
2655 detailed_signal = g_strdup_printf ("changed::%s", key);
2656 binding->key_handler_id =
2657 g_signal_connect (settings, detailed_signal,
2658 G_CALLBACK (g_settings_binding_key_changed),
2660 g_free (detailed_signal);
2663 g_settings_binding_key_changed (settings, binding->key.name, binding);
2666 binding_quark = g_settings_binding_quark (property);
2667 g_object_set_qdata_full (object, binding_quark,
2668 binding, g_settings_binding_free);
2671 /* Writability binding {{{1 */
2674 GSettings *settings;
2677 const gchar *property;
2680 } GSettingsWritableBinding;
2683 g_settings_writable_binding_free (gpointer data)
2685 GSettingsWritableBinding *binding = data;
2687 g_signal_handler_disconnect (binding->settings, binding->handler_id);
2688 g_object_unref (binding->settings);
2689 g_slice_free (GSettingsWritableBinding, binding);
2693 g_settings_binding_writable_changed (GSettings *settings,
2697 GSettingsWritableBinding *binding = user_data;
2700 g_assert (settings == binding->settings);
2701 g_assert (key == binding->key);
2703 writable = g_settings_is_writable (settings, key);
2705 if (binding->inverted)
2706 writable = !writable;
2708 g_object_set (binding->object, binding->property, writable, NULL);
2712 * g_settings_bind_writable:
2713 * @settings: a #GSettings object
2714 * @key: the key to bind
2715 * @object: (type GObject.Object):a #GObject
2716 * @property: the name of a boolean property to bind
2717 * @inverted: whether to 'invert' the value
2719 * Create a binding between the writability of @key in the
2720 * @settings object and the property @property of @object.
2721 * The property must be boolean; "sensitive" or "visible"
2722 * properties of widgets are the most likely candidates.
2724 * Writable bindings are always uni-directional; changes of the
2725 * writability of the setting will be propagated to the object
2726 * property, not the other way.
2728 * When the @inverted argument is %TRUE, the binding inverts the
2729 * value as it passes from the setting to the object, i.e. @property
2730 * will be set to %TRUE if the key is <emphasis>not</emphasis>
2733 * Note that the lifecycle of the binding is tied to the object,
2734 * and that you can have only one binding per object property.
2735 * If you bind the same property twice on the same object, the second
2736 * binding overrides the first one.
2741 g_settings_bind_writable (GSettings *settings,
2744 const gchar *property,
2747 GSettingsWritableBinding *binding;
2748 gchar *detailed_signal;
2751 g_return_if_fail (G_IS_SETTINGS (settings));
2753 pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (object), property);
2756 g_critical ("g_settings_bind_writable: no property '%s' on class '%s'",
2757 property, G_OBJECT_TYPE_NAME (object));
2760 if ((pspec->flags & G_PARAM_WRITABLE) == 0)
2762 g_critical ("g_settings_bind_writable: property '%s' on class '%s' is not writable",
2763 property, G_OBJECT_TYPE_NAME (object));
2767 binding = g_slice_new (GSettingsWritableBinding);
2768 binding->settings = g_object_ref (settings);
2769 binding->object = object;
2770 binding->key = g_intern_string (key);
2771 binding->property = g_intern_string (property);
2772 binding->inverted = inverted;
2774 detailed_signal = g_strdup_printf ("writable-changed::%s", key);
2775 binding->handler_id =
2776 g_signal_connect (settings, detailed_signal,
2777 G_CALLBACK (g_settings_binding_writable_changed),
2779 g_free (detailed_signal);
2781 g_object_set_qdata_full (object, g_settings_binding_quark (property),
2782 binding, g_settings_writable_binding_free);
2784 g_settings_binding_writable_changed (settings, binding->key, binding);
2788 * g_settings_unbind:
2789 * @object: the object
2790 * @property: the property whose binding is removed
2792 * Removes an existing binding for @property on @object.
2794 * Note that bindings are automatically removed when the
2795 * object is finalized, so it is rarely necessary to call this
2801 g_settings_unbind (gpointer object,
2802 const gchar *property)
2804 GQuark binding_quark;
2806 binding_quark = g_settings_binding_quark (property);
2807 g_object_set_qdata (object, binding_quark, NULL);
2812 /* vim:set foldmethod=marker: */