rename gsettingsschema.h to -internal.h
[platform/upstream/glib.git] / gio / gsettings.c
1 /*
2  * Copyright © 2009, 2010 Codethink Limited
3  *
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.
8  *
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.
13  *
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.
18  *
19  * Author: Ryan Lortie <desrt@desrt.ca>
20  */
21
22 /* Prelude {{{1 */
23 #include "config.h"
24
25 #include <glib.h>
26 #include <glibintl.h>
27 #include <locale.h>
28
29 #include "gsettings.h"
30
31 #include "gdelayedsettingsbackend.h"
32 #include "gsettingsbackendinternal.h"
33 #include "gsettings-mapping.h"
34 #include "gsettingsschema-internal.h"
35
36 #include <string.h>
37
38
39 #include "strinfo.c"
40
41 /**
42  * SECTION:gsettings
43  * @short_description: High-level API for application settings
44  *
45  * The #GSettings class provides a convenient API for storing and retrieving
46  * application settings.
47  *
48  * Reads and writes can be considered to be non-blocking.  Reading
49  * settings with #GSettings is typically extremely fast: on
50  * approximately the same order of magnitude (but slower than) a
51  * #GHashTable lookup.  Writing settings is also extremely fast in terms
52  * of time to return to your application, but can be extremely expensive
53  * for other threads and other processes.  Many settings backends
54  * (including dconf) have lazy initialisation which means in the common
55  * case of the user using their computer without modifying any settings
56  * a lot of work can be avoided.  For dconf, the D-Bus service doesn't
57  * even need to be started in this case.  For this reason, you should
58  * only ever modify #GSettings keys in response to explicit user action.
59  * Particular care should be paid to ensure that modifications are not
60  * made during startup -- for example, when setting the initial value
61  * of preferences widgets.  The built-in g_settings_bind() functionality
62  * is careful not to write settings in response to notify signals as a
63  * result of modifications that it makes to widgets.
64  *
65  * When creating a GSettings instance, you have to specify a schema
66  * that describes the keys in your settings and their types and default
67  * values, as well as some other information.
68  *
69  * Normally, a schema has as fixed path that determines where the settings
70  * are stored in the conceptual global tree of settings. However, schemas
71  * can also be 'relocatable', i.e. not equipped with a fixed path. This is
72  * useful e.g. when the schema describes an 'account', and you want to be
73  * able to store a arbitrary number of accounts.
74  *
75  * Unlike other configuration systems (like GConf), GSettings does not
76  * restrict keys to basic types like strings and numbers. GSettings stores
77  * values as #GVariant, and allows any #GVariantType for keys. Key names
78  * are restricted to lowercase characters, numbers and '-'. Furthermore,
79  * the names must begin with a lowercase character, must not end
80  * with a '-', and must not contain consecutive dashes.
81  *
82  * Similar to GConf, the default values in GSettings schemas can be
83  * localized, but the localized values are stored in gettext catalogs
84  * and looked up with the domain that is specified in the
85  * <tag class="attribute">gettext-domain</tag> attribute of the
86  * <tag class="starttag">schemalist</tag> or <tag class="starttag">schema</tag>
87  * elements and the category that is specified in the l10n attribute of the
88  * <tag class="starttag">key</tag> element.
89  *
90  * GSettings uses schemas in a compact binary form that is created
91  * by the <link linkend="glib-compile-schemas">glib-compile-schemas</link>
92  * utility. The input is a schema description in an XML format that can be
93  * described by the following DTD:
94  * |[<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>]|
95  *
96  * glib-compile-schemas expects schema files to have the extension <filename>.gschema.xml</filename>
97  *
98  * At runtime, schemas are identified by their id (as specified
99  * in the <tag class="attribute">id</tag> attribute of the
100  * <tag class="starttag">schema</tag> element). The
101  * convention for schema ids is to use a dotted name, similar in
102  * style to a D-Bus bus name, e.g. "org.gnome.SessionManager". In particular,
103  * if the settings are for a specific service that owns a D-Bus bus name,
104  * the D-Bus bus name and schema id should match. For schemas which deal
105  * with settings not associated with one named application, the id should
106  * not use StudlyCaps, e.g. "org.gnome.font-rendering".
107  *
108  * In addition to #GVariant types, keys can have types that have enumerated
109  * types. These can be described by a <tag class="starttag">choice</tag>,
110  * <tag class="starttag">enum</tag> or <tag class="starttag">flags</tag> element, see
111  * <xref linkend="schema-enumerated"/>. The underlying type of
112  * such a key is string, but you can use g_settings_get_enum(),
113  * g_settings_set_enum(), g_settings_get_flags(), g_settings_set_flags()
114  * access the numeric values corresponding to the string value of enum
115  * and flags keys.
116  *
117  * <example id="schema-default-values"><title>Default values</title>
118  * <programlisting><![CDATA[
119  * <schemalist>
120  *   <schema id="org.gtk.Test" path="/tests/" gettext-domain="test">
121  *
122  *     <key name="greeting" type="s">
123  *       <default l10n="messages">"Hello, earthlings"</default>
124  *       <summary>A greeting</summary>
125  *       <description>
126  *         Greeting of the invading martians
127  *       </description>
128  *     </key>
129  *
130  *     <key name="box" type="(ii)">
131  *       <default>(20,30)</default>
132  *     </key>
133  *
134  *   </schema>
135  * </schemalist>
136  * ]]></programlisting></example>
137  *
138  * <example id="schema-enumerated"><title>Ranges, choices and enumerated types</title>
139  * <programlisting><![CDATA[
140  * <schemalist>
141  *
142  *   <enum id="org.gtk.Test.myenum">
143  *     <value nick="first" value="1"/>
144  *     <value nick="second" value="2"/>
145  *   </enum>
146  *
147  *   <flags id="org.gtk.Test.myflags">
148  *     <value nick="flag1" value="1"/>
149  *     <value nick="flag2" value="2"/>
150  *     <value nick="flag3" value="4"/>
151  *   </flags>
152  *
153  *   <schema id="org.gtk.Test">
154  *
155  *     <key name="key-with-range" type="i">
156  *       <range min="1" max="100"/>
157  *       <default>10</default>
158  *     </key>
159  *
160  *     <key name="key-with-choices" type="s">
161  *       <choices>
162  *         <choice value='Elisabeth'/>
163  *         <choice value='Annabeth'/>
164  *         <choice value='Joe'/>
165  *       </choices>
166  *       <aliases>
167  *         <alias value='Anna' target='Annabeth'/>
168  *         <alias value='Beth' target='Elisabeth'/>
169  *       </aliases>
170  *       <default>'Joe'</default>
171  *     </key>
172  *
173  *     <key name='enumerated-key' enum='org.gtk.Test.myenum'>
174  *       <default>'first'</default>
175  *     </key>
176  *
177  *     <key name='flags-key' flags='org.gtk.Test.myflags'>
178  *       <default>["flag1",flag2"]</default>
179  *     </key>
180  *   </schema>
181  * </schemalist>
182  * ]]></programlisting></example>
183  *
184  * <refsect2>
185  *   <title>Vendor overrides</title>
186  *   <para>
187  *     Default values are defined in the schemas that get installed by
188  *     an application. Sometimes, it is necessary for a vendor or distributor
189  *     to adjust these defaults. Since patching the XML source for the schema
190  *     is inconvenient and error-prone,
191  *     <link linkend="glib-compile-schemas">glib-compile-schemas</link> reads
192  *     so-called 'vendor override' files. These are keyfiles in the same
193  *     directory as the XML schema sources which can override default values.
194  *     The schema id serves as the group name in the key file, and the values
195  *     are expected in serialized GVariant form, as in the following example:
196  *     <informalexample><programlisting>
197  *     [org.gtk.Example]
198  *     key1='string'
199  *     key2=1.5
200  *     </programlisting></informalexample>
201  *   </para>
202  *   <para>
203  *     glib-compile-schemas expects schema files to have the extension
204  *     <filename>.gschema.override</filename>
205  *   </para>
206  * </refsect2>
207  *
208  * <refsect2>
209  *   <title>Binding</title>
210  *   <para>
211  *     A very convenient feature of GSettings lets you bind #GObject properties
212  *     directly to settings, using g_settings_bind(). Once a GObject property
213  *     has been bound to a setting, changes on either side are automatically
214  *     propagated to the other side. GSettings handles details like
215  *     mapping between GObject and GVariant types, and preventing infinite
216  *     cycles.
217  *   </para>
218  *   <para>
219  *     This makes it very easy to hook up a preferences dialog to the
220  *     underlying settings. To make this even more convenient, GSettings
221  *     looks for a boolean property with the name "sensitivity" and
222  *     automatically binds it to the writability of the bound setting.
223  *     If this 'magic' gets in the way, it can be suppressed with the
224  *     #G_SETTINGS_BIND_NO_SENSITIVITY flag.
225  *   </para>
226  * </refsect2>
227  **/
228
229 struct _GSettingsPrivate
230 {
231   /* where the signals go... */
232   GMainContext *main_context;
233
234   GSettingsBackend *backend;
235   GSettingsSchema *schema;
236   gchar *schema_name;
237   gchar *path;
238
239   GDelayedSettingsBackend *delayed;
240 };
241
242 enum
243 {
244   PROP_0,
245   PROP_SCHEMA,
246   PROP_BACKEND,
247   PROP_PATH,
248   PROP_HAS_UNAPPLIED,
249   PROP_DELAY_APPLY
250 };
251
252 enum
253 {
254   SIGNAL_WRITABLE_CHANGE_EVENT,
255   SIGNAL_WRITABLE_CHANGED,
256   SIGNAL_CHANGE_EVENT,
257   SIGNAL_CHANGED,
258   N_SIGNALS
259 };
260
261 static guint g_settings_signals[N_SIGNALS];
262
263 G_DEFINE_TYPE (GSettings, g_settings, G_TYPE_OBJECT)
264
265 /* Signals {{{1 */
266 static gboolean
267 g_settings_real_change_event (GSettings    *settings,
268                               const GQuark *keys,
269                               gint          n_keys)
270 {
271   gint i;
272
273   if (keys == NULL)
274     keys = g_settings_schema_list (settings->priv->schema, &n_keys);
275
276   for (i = 0; i < n_keys; i++)
277     g_signal_emit (settings, g_settings_signals[SIGNAL_CHANGED],
278                    keys[i], g_quark_to_string (keys[i]));
279
280   return FALSE;
281 }
282
283 static gboolean
284 g_settings_real_writable_change_event (GSettings *settings,
285                                        GQuark     key)
286 {
287   const GQuark *keys = &key;
288   gint n_keys = 1;
289   gint i;
290
291   if (key == 0)
292     keys = g_settings_schema_list (settings->priv->schema, &n_keys);
293
294   for (i = 0; i < n_keys; i++)
295     g_signal_emit (settings, g_settings_signals[SIGNAL_WRITABLE_CHANGED],
296                    keys[i], g_quark_to_string (keys[i]));
297
298   return FALSE;
299 }
300
301 static void
302 settings_backend_changed (GObject             *target,
303                           GSettingsBackend    *backend,
304                           const gchar         *key,
305                           gpointer             origin_tag)
306 {
307   GSettings *settings = G_SETTINGS (target);
308   gboolean ignore_this;
309   gint i;
310
311   /* We used to assert here:
312    *
313    *   settings->priv->backend == backend
314    *
315    * but it could be the case that a notification is queued for delivery
316    * while someone calls g_settings_delay() (which changes the backend).
317    *
318    * Since the delay backend would just pass that straight through
319    * anyway, it doesn't make sense to try to detect this case.
320    * Therefore, we just accept it.
321    */
322
323   for (i = 0; key[i] == settings->priv->path[i]; i++);
324
325   if (settings->priv->path[i] == '\0' &&
326       g_settings_schema_has_key (settings->priv->schema, key + i))
327     {
328       GQuark quark;
329
330       quark = g_quark_from_string (key + i);
331       g_signal_emit (settings, g_settings_signals[SIGNAL_CHANGE_EVENT],
332                      0, &quark, 1, &ignore_this);
333     }
334 }
335
336 static void
337 settings_backend_path_changed (GObject          *target,
338                                GSettingsBackend *backend,
339                                const gchar      *path,
340                                gpointer          origin_tag)
341 {
342   GSettings *settings = G_SETTINGS (target);
343   gboolean ignore_this;
344
345   if (g_str_has_prefix (settings->priv->path, path))
346     g_signal_emit (settings, g_settings_signals[SIGNAL_CHANGE_EVENT],
347                    0, NULL, 0, &ignore_this);
348 }
349
350 static void
351 settings_backend_keys_changed (GObject             *target,
352                                GSettingsBackend    *backend,
353                                const gchar         *path,
354                                const gchar * const *items,
355                                gpointer             origin_tag)
356 {
357   GSettings *settings = G_SETTINGS (target);
358   gboolean ignore_this;
359   gint i;
360
361   for (i = 0; settings->priv->path[i] &&
362               settings->priv->path[i] == path[i]; i++);
363
364   if (path[i] == '\0')
365     {
366       GQuark quarks[256];
367       gint j, l = 0;
368
369       for (j = 0; items[j]; j++)
370          {
371            const gchar *item = items[j];
372            gint k;
373
374            for (k = 0; item[k] == settings->priv->path[i + k]; k++);
375
376            if (settings->priv->path[i + k] == '\0' &&
377                g_settings_schema_has_key (settings->priv->schema, item + k))
378              quarks[l++] = g_quark_from_string (item + k);
379
380            /* "256 quarks ought to be enough for anybody!"
381             * If this bites you, I'm sorry.  Please file a bug.
382             */
383            g_assert (l < 256);
384          }
385
386       if (l > 0)
387         g_signal_emit (settings, g_settings_signals[SIGNAL_CHANGE_EVENT],
388                        0, quarks, l, &ignore_this);
389     }
390 }
391
392 static void
393 settings_backend_writable_changed (GObject          *target,
394                                    GSettingsBackend *backend,
395                                    const gchar      *key)
396 {
397   GSettings *settings = G_SETTINGS (target);
398   gboolean ignore_this;
399   gint i;
400
401   for (i = 0; key[i] == settings->priv->path[i]; i++);
402
403   if (settings->priv->path[i] == '\0' &&
404       g_settings_schema_has_key (settings->priv->schema, key + i))
405     g_signal_emit (settings, g_settings_signals[SIGNAL_WRITABLE_CHANGE_EVENT],
406                    0, g_quark_from_string (key + i), &ignore_this);
407 }
408
409 static void
410 settings_backend_path_writable_changed (GObject          *target,
411                                         GSettingsBackend *backend,
412                                         const gchar      *path)
413 {
414   GSettings *settings = G_SETTINGS (target);
415   gboolean ignore_this;
416
417   if (g_str_has_prefix (settings->priv->path, path))
418     g_signal_emit (settings, g_settings_signals[SIGNAL_WRITABLE_CHANGE_EVENT],
419                    0, (GQuark) 0, &ignore_this);
420 }
421
422 /* Properties, Construction, Destruction {{{1 */
423 static void
424 g_settings_set_property (GObject      *object,
425                          guint         prop_id,
426                          const GValue *value,
427                          GParamSpec   *pspec)
428 {
429   GSettings *settings = G_SETTINGS (object);
430
431   switch (prop_id)
432     {
433     case PROP_SCHEMA:
434       g_assert (settings->priv->schema_name == NULL);
435       settings->priv->schema_name = g_value_dup_string (value);
436       break;
437
438     case PROP_PATH:
439       settings->priv->path = g_value_dup_string (value);
440       break;
441
442     case PROP_BACKEND:
443       settings->priv->backend = g_value_dup_object (value);
444       break;
445
446     default:
447       g_assert_not_reached ();
448     }
449 }
450
451 static void
452 g_settings_get_property (GObject    *object,
453                          guint       prop_id,
454                          GValue     *value,
455                          GParamSpec *pspec)
456 {
457   GSettings *settings = G_SETTINGS (object);
458
459   switch (prop_id)
460     {
461      case PROP_SCHEMA:
462       g_value_set_string (value, settings->priv->schema_name);
463       break;
464
465      case PROP_BACKEND:
466       g_value_set_object (value, settings->priv->backend);
467       break;
468
469      case PROP_PATH:
470       g_value_set_string (value, settings->priv->path);
471       break;
472
473      case PROP_HAS_UNAPPLIED:
474       g_value_set_boolean (value, g_settings_get_has_unapplied (settings));
475       break;
476
477      case PROP_DELAY_APPLY:
478       g_value_set_boolean (value, settings->priv->delayed != NULL);
479       break;
480
481      default:
482       g_assert_not_reached ();
483     }
484 }
485
486 static const GSettingsListenerVTable listener_vtable = {
487   settings_backend_changed,
488   settings_backend_path_changed,
489   settings_backend_keys_changed,
490   settings_backend_writable_changed,
491   settings_backend_path_writable_changed
492 };
493
494 static void
495 g_settings_constructed (GObject *object)
496 {
497   GSettings *settings = G_SETTINGS (object);
498   const gchar *schema_path;
499
500   settings->priv->schema = g_settings_schema_new (settings->priv->schema_name);
501   schema_path = g_settings_schema_get_path (settings->priv->schema);
502
503   if (settings->priv->path && schema_path && strcmp (settings->priv->path, schema_path) != 0)
504     g_error ("settings object created with schema '%s' and path '%s', but "
505              "path '%s' is specified by schema",
506              settings->priv->schema_name, settings->priv->path, schema_path);
507
508   if (settings->priv->path == NULL)
509     {
510       if (schema_path == NULL)
511         g_error ("attempting to create schema '%s' without a path",
512                  settings->priv->schema_name);
513
514       settings->priv->path = g_strdup (schema_path);
515     }
516
517   if (settings->priv->backend == NULL)
518     settings->priv->backend = g_settings_backend_get_default ();
519
520   g_settings_backend_watch (settings->priv->backend,
521                             &listener_vtable, G_OBJECT (settings),
522                             settings->priv->main_context);
523   g_settings_backend_subscribe (settings->priv->backend,
524                                 settings->priv->path);
525 }
526
527 static void
528 g_settings_finalize (GObject *object)
529 {
530   GSettings *settings = G_SETTINGS (object);
531
532   g_settings_backend_unsubscribe (settings->priv->backend,
533                                   settings->priv->path);
534   g_main_context_unref (settings->priv->main_context);
535   g_object_unref (settings->priv->backend);
536   g_settings_schema_unref (settings->priv->schema);
537   g_free (settings->priv->schema_name);
538   g_free (settings->priv->path);
539
540   G_OBJECT_CLASS (g_settings_parent_class)->finalize (object);
541 }
542
543 static void
544 g_settings_init (GSettings *settings)
545 {
546   settings->priv = G_TYPE_INSTANCE_GET_PRIVATE (settings,
547                                                 G_TYPE_SETTINGS,
548                                                 GSettingsPrivate);
549
550   settings->priv->main_context = g_main_context_ref_thread_default ();
551 }
552
553 static void
554 g_settings_class_init (GSettingsClass *class)
555 {
556   GObjectClass *object_class = G_OBJECT_CLASS (class);
557
558   class->writable_change_event = g_settings_real_writable_change_event;
559   class->change_event = g_settings_real_change_event;
560
561   object_class->set_property = g_settings_set_property;
562   object_class->get_property = g_settings_get_property;
563   object_class->constructed = g_settings_constructed;
564   object_class->finalize = g_settings_finalize;
565
566   g_type_class_add_private (object_class, sizeof (GSettingsPrivate));
567
568   /**
569    * GSettings::changed:
570    * @settings: the object on which the signal was emitted
571    * @key: the name of the key that changed
572    *
573    * The "changed" signal is emitted when a key has potentially changed.
574    * You should call one of the g_settings_get() calls to check the new
575    * value.
576    *
577    * This signal supports detailed connections.  You can connect to the
578    * detailed signal "changed::x" in order to only receive callbacks
579    * when key "x" changes.
580    */
581   g_settings_signals[SIGNAL_CHANGED] =
582     g_signal_new ("changed", G_TYPE_SETTINGS,
583                   G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
584                   G_STRUCT_OFFSET (GSettingsClass, changed),
585                   NULL, NULL, g_cclosure_marshal_VOID__STRING, G_TYPE_NONE,
586                   1, G_TYPE_STRING | G_SIGNAL_TYPE_STATIC_SCOPE);
587
588   /**
589    * GSettings::change-event:
590    * @settings: the object on which the signal was emitted
591    * @keys: (array length=n_keys) (element-type GQuark) (allow-none):
592    *        an array of #GQuark<!-- -->s for the changed keys, or %NULL
593    * @n_keys: the length of the @keys array, or 0
594    * @returns: %TRUE to stop other handlers from being invoked for the
595    *           event. FALSE to propagate the event further.
596    *
597    * The "change-event" signal is emitted once per change event that
598    * affects this settings object.  You should connect to this signal
599    * only if you are interested in viewing groups of changes before they
600    * are split out into multiple emissions of the "changed" signal.
601    * For most use cases it is more appropriate to use the "changed" signal.
602    *
603    * In the event that the change event applies to one or more specified
604    * keys, @keys will be an array of #GQuark of length @n_keys.  In the
605    * event that the change event applies to the #GSettings object as a
606    * whole (ie: potentially every key has been changed) then @keys will
607    * be %NULL and @n_keys will be 0.
608    *
609    * The default handler for this signal invokes the "changed" signal
610    * for each affected key.  If any other connected handler returns
611    * %TRUE then this default functionality will be suppressed.
612    */
613   g_settings_signals[SIGNAL_CHANGE_EVENT] =
614     g_signal_new ("change-event", G_TYPE_SETTINGS,
615                   G_SIGNAL_RUN_LAST,
616                   G_STRUCT_OFFSET (GSettingsClass, change_event),
617                   g_signal_accumulator_true_handled, NULL,
618                   NULL,
619                   G_TYPE_BOOLEAN, 2, G_TYPE_POINTER, G_TYPE_INT);
620
621   /**
622    * GSettings::writable-changed:
623    * @settings: the object on which the signal was emitted
624    * @key: the key
625    *
626    * The "writable-changed" signal is emitted when the writability of a
627    * key has potentially changed.  You should call
628    * g_settings_is_writable() in order to determine the new status.
629    *
630    * This signal supports detailed connections.  You can connect to the
631    * detailed signal "writable-changed::x" in order to only receive
632    * callbacks when the writability of "x" changes.
633    */
634   g_settings_signals[SIGNAL_WRITABLE_CHANGED] =
635     g_signal_new ("writable-changed", G_TYPE_SETTINGS,
636                   G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
637                   G_STRUCT_OFFSET (GSettingsClass, writable_changed),
638                   NULL, NULL, g_cclosure_marshal_VOID__STRING, G_TYPE_NONE,
639                   1, G_TYPE_STRING | G_SIGNAL_TYPE_STATIC_SCOPE);
640
641   /**
642    * GSettings::writable-change-event:
643    * @settings: the object on which the signal was emitted
644    * @key: the quark of the key, or 0
645    * @returns: %TRUE to stop other handlers from being invoked for the
646    *           event. FALSE to propagate the event further.
647    *
648    * The "writable-change-event" signal is emitted once per writability
649    * change event that affects this settings object.  You should connect
650    * to this signal if you are interested in viewing groups of changes
651    * before they are split out into multiple emissions of the
652    * "writable-changed" signal.  For most use cases it is more
653    * appropriate to use the "writable-changed" signal.
654    *
655    * In the event that the writability change applies only to a single
656    * key, @key will be set to the #GQuark for that key.  In the event
657    * that the writability change affects the entire settings object,
658    * @key will be 0.
659    *
660    * The default handler for this signal invokes the "writable-changed"
661    * and "changed" signals for each affected key.  This is done because
662    * changes in writability might also imply changes in value (if for
663    * example, a new mandatory setting is introduced).  If any other
664    * connected handler returns %TRUE then this default functionality
665    * will be suppressed.
666    */
667   g_settings_signals[SIGNAL_WRITABLE_CHANGE_EVENT] =
668     g_signal_new ("writable-change-event", G_TYPE_SETTINGS,
669                   G_SIGNAL_RUN_LAST,
670                   G_STRUCT_OFFSET (GSettingsClass, writable_change_event),
671                   g_signal_accumulator_true_handled, NULL,
672                   NULL, G_TYPE_BOOLEAN, 1, G_TYPE_UINT);
673
674   /**
675    * GSettings:context:
676    *
677    * The name of the context that the settings are stored in.
678    */
679   g_object_class_install_property (object_class, PROP_BACKEND,
680     g_param_spec_object ("backend",
681                          P_("GSettingsBackend"),
682                          P_("The GSettingsBackend for this settings object"),
683                          G_TYPE_SETTINGS_BACKEND, G_PARAM_CONSTRUCT_ONLY |
684                          G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
685
686   /**
687    * GSettings:schema:
688    *
689    * The name of the schema that describes the types of keys
690    * for this #GSettings object.
691    */
692   g_object_class_install_property (object_class, PROP_SCHEMA,
693     g_param_spec_string ("schema",
694                          P_("Schema name"),
695                          P_("The name of the schema for this settings object"),
696                          NULL,
697                          G_PARAM_CONSTRUCT_ONLY |
698                          G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
699
700    /**
701     * GSettings:path:
702     *
703     * The path within the backend where the settings are stored.
704     */
705    g_object_class_install_property (object_class, PROP_PATH,
706      g_param_spec_string ("path",
707                           P_("Base path"),
708                           P_("The path within the backend where the settings are"),
709                           NULL,
710                           G_PARAM_CONSTRUCT_ONLY |
711                           G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
712
713    /**
714     * GSettings:has-unapplied:
715     *
716     * If this property is %TRUE, the #GSettings object has outstanding
717     * changes that will be applied when g_settings_apply() is called.
718     */
719    g_object_class_install_property (object_class, PROP_HAS_UNAPPLIED,
720      g_param_spec_boolean ("has-unapplied",
721                            P_("Has unapplied changes"),
722                            P_("TRUE if there are outstanding changes to apply()"),
723                            FALSE,
724                            G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
725
726    /**
727     * GSettings:delay-apply:
728     *
729     * Whether the #GSettings object is in 'delay-apply' mode. See
730     * g_settings_delay() for details.
731     *
732     * Since: 2.28
733     */
734    g_object_class_install_property (object_class, PROP_DELAY_APPLY,
735      g_param_spec_boolean ("delay-apply",
736                            P_("Delay-apply mode"),
737                            P_("Whether this settings object is in 'delay-apply' mode"),
738                            FALSE,
739                            G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
740 }
741
742 /* Construction (new, new_with_path, etc.) {{{1 */
743 /**
744  * g_settings_new:
745  * @schema: the name of the schema
746  * @returns: a new #GSettings object
747  *
748  * Creates a new #GSettings object with a given schema.
749  *
750  * Signals on the newly created #GSettings object will be dispatched
751  * via the thread-default #GMainContext in effect at the time of the
752  * call to g_settings_new().  The new #GSettings will hold a reference
753  * on the context.  See g_main_context_push_thread_default().
754  *
755  * Since: 2.26
756  */
757 GSettings *
758 g_settings_new (const gchar *schema)
759 {
760   g_return_val_if_fail (schema != NULL, NULL);
761
762   return g_object_new (G_TYPE_SETTINGS,
763                        "schema", schema,
764                        NULL);
765 }
766
767 /**
768  * g_settings_new_with_path:
769  * @schema: the name of the schema
770  * @path: the path to use
771  * @returns: a new #GSettings object
772  *
773  * Creates a new #GSettings object with a given schema and path.
774  *
775  * You only need to do this if you want to directly create a settings
776  * object with a schema that doesn't have a specified path of its own.
777  * That's quite rare.
778  *
779  * It is a programmer error to call this function for a schema that
780  * has an explicitly specified path.
781  *
782  * Since: 2.26
783  */
784 GSettings *
785 g_settings_new_with_path (const gchar *schema,
786                           const gchar *path)
787 {
788   g_return_val_if_fail (schema != NULL, NULL);
789   g_return_val_if_fail (path != NULL, NULL);
790
791   return g_object_new (G_TYPE_SETTINGS,
792                        "schema", schema,
793                        "path", path,
794                        NULL);
795 }
796
797 /**
798  * g_settings_new_with_backend:
799  * @schema: the name of the schema
800  * @backend: the #GSettingsBackend to use
801  * @returns: a new #GSettings object
802  *
803  * Creates a new #GSettings object with a given schema and backend.
804  *
805  * Creating a #GSettings object with a different backend allows accessing
806  * settings from a database other than the usual one. For example, it may make
807  * sense to pass a backend corresponding to the "defaults" settings database on
808  * the system to get a settings object that modifies the system default
809  * settings instead of the settings for this user.
810  *
811  * Since: 2.26
812  */
813 GSettings *
814 g_settings_new_with_backend (const gchar      *schema,
815                              GSettingsBackend *backend)
816 {
817   g_return_val_if_fail (schema != NULL, NULL);
818   g_return_val_if_fail (G_IS_SETTINGS_BACKEND (backend), NULL);
819
820   return g_object_new (G_TYPE_SETTINGS,
821                        "schema", schema,
822                        "backend", backend,
823                        NULL);
824 }
825
826 /**
827  * g_settings_new_with_backend_and_path:
828  * @schema: the name of the schema
829  * @backend: the #GSettingsBackend to use
830  * @path: the path to use
831  * @returns: a new #GSettings object
832  *
833  * Creates a new #GSettings object with a given schema, backend and
834  * path.
835  *
836  * This is a mix of g_settings_new_with_backend() and
837  * g_settings_new_with_path().
838  *
839  * Since: 2.26
840  */
841 GSettings *
842 g_settings_new_with_backend_and_path (const gchar      *schema,
843                                       GSettingsBackend *backend,
844                                       const gchar      *path)
845 {
846   g_return_val_if_fail (schema != NULL, NULL);
847   g_return_val_if_fail (G_IS_SETTINGS_BACKEND (backend), NULL);
848   g_return_val_if_fail (path != NULL, NULL);
849
850   return g_object_new (G_TYPE_SETTINGS,
851                        "schema", schema,
852                        "backend", backend,
853                        "path", path,
854                        NULL);
855 }
856
857 /* Internal read/write utilities, enum/flags conversion, validation {{{1 */
858 typedef struct
859 {
860   GSettings *settings;
861   const gchar *key;
862
863   GSettingsSchema *schema;
864
865   guint is_flags : 1;
866   guint is_enum  : 1;
867
868   const guint32 *strinfo;
869   gsize strinfo_length;
870
871   const gchar *unparsed;
872   gchar lc_char;
873
874   const GVariantType *type;
875   GVariant *minimum, *maximum;
876   GVariant *default_value;
877 } GSettingsKeyInfo;
878
879 static inline void
880 endian_fixup (GVariant **value)
881 {
882 #if G_BYTE_ORDER == G_BIG_ENDIAN
883   GVariant *tmp;
884
885   tmp = g_variant_byteswap (*value);
886   g_variant_unref (*value);
887   *value = tmp;
888 #endif
889 }
890
891 static void
892 g_settings_get_key_info (GSettingsKeyInfo *info,
893                          GSettings        *settings,
894                          const gchar      *key)
895 {
896   GVariantIter *iter;
897   GVariant *data;
898   guchar code;
899
900   memset (info, 0, sizeof *info);
901
902   iter = g_settings_schema_get_value (settings->priv->schema, key);
903
904   info->default_value = g_variant_iter_next_value (iter);
905   endian_fixup (&info->default_value);
906   info->type = g_variant_get_type (info->default_value);
907   info->settings = g_object_ref (settings);
908   info->key = g_intern_string (key);
909
910   while (g_variant_iter_next (iter, "(y*)", &code, &data))
911     {
912       switch (code)
913         {
914         case 'l':
915           /* translation requested */
916           g_variant_get (data, "(y&s)", &info->lc_char, &info->unparsed);
917           break;
918
919         case 'e':
920           /* enumerated types... */
921           info->is_enum = TRUE;
922           goto choice;
923
924         case 'f':
925           /* flags... */
926           info->is_flags = TRUE;
927           goto choice;
928
929         choice: case 'c':
930           /* ..., choices, aliases */
931           info->strinfo = g_variant_get_fixed_array (data,
932                                                      &info->strinfo_length,
933                                                      sizeof (guint32));
934           break;
935
936         case 'r':
937           g_variant_get (data, "(**)", &info->minimum, &info->maximum);
938           endian_fixup (&info->minimum);
939           endian_fixup (&info->maximum);
940           break;
941
942         default:
943           g_warning ("unknown schema extension '%c'", code);
944           break;
945         }
946
947       g_variant_unref (data);
948     }
949
950   g_variant_iter_free (iter);
951 }
952
953 static void
954 g_settings_free_key_info (GSettingsKeyInfo *info)
955 {
956   if (info->minimum)
957     g_variant_unref (info->minimum);
958
959   if (info->maximum)
960     g_variant_unref (info->maximum);
961
962   g_variant_unref (info->default_value);
963   g_object_unref (info->settings);
964 }
965
966 static gboolean
967 g_settings_write_to_backend (GSettingsKeyInfo *info,
968                              GVariant         *value)
969 {
970   gboolean success;
971   gchar *path;
972
973   path = g_strconcat (info->settings->priv->path, info->key, NULL);
974   success = g_settings_backend_write (info->settings->priv->backend,
975                                       path, value, NULL);
976   g_free (path);
977
978   return success;
979 }
980
981 static gboolean
982 g_settings_type_check (GSettingsKeyInfo *info,
983                        GVariant         *value)
984 {
985   g_return_val_if_fail (value != NULL, FALSE);
986
987   return g_variant_is_of_type (value, info->type);
988 }
989
990 static gboolean
991 g_settings_key_info_range_check (GSettingsKeyInfo *info,
992                                  GVariant         *value)
993 {
994   if (info->minimum == NULL && info->strinfo == NULL)
995     return TRUE;
996
997   if (g_variant_is_container (value))
998     {
999       gboolean ok = TRUE;
1000       GVariantIter iter;
1001       GVariant *child;
1002
1003       g_variant_iter_init (&iter, value);
1004       while (ok && (child = g_variant_iter_next_value (&iter)))
1005         {
1006           ok = g_settings_key_info_range_check (info, child);
1007           g_variant_unref (child);
1008         }
1009
1010       return ok;
1011     }
1012
1013   if (info->minimum)
1014     {
1015       return g_variant_compare (info->minimum, value) <= 0 &&
1016              g_variant_compare (value, info->maximum) <= 0;
1017     }
1018
1019   return strinfo_is_string_valid (info->strinfo,
1020                                   info->strinfo_length,
1021                                   g_variant_get_string (value, NULL));
1022 }
1023
1024 static GVariant *
1025 g_settings_range_fixup (GSettingsKeyInfo *info,
1026                         GVariant         *value)
1027 {
1028   const gchar *target;
1029
1030   if (g_settings_key_info_range_check (info, value))
1031     return g_variant_ref (value);
1032
1033   if (info->strinfo == NULL)
1034     return NULL;
1035
1036   if (g_variant_is_container (value))
1037     {
1038       GVariantBuilder builder;
1039       GVariantIter iter;
1040       GVariant *child;
1041
1042       g_variant_iter_init (&iter, value);
1043       g_variant_builder_init (&builder, g_variant_get_type (value));
1044
1045       while ((child = g_variant_iter_next_value (&iter)))
1046         {
1047           GVariant *fixed;
1048
1049           fixed = g_settings_range_fixup (info, child);
1050           g_variant_unref (child);
1051
1052           if (fixed == NULL)
1053             {
1054               g_variant_builder_clear (&builder);
1055               return NULL;
1056             }
1057
1058           g_variant_builder_add_value (&builder, fixed);
1059           g_variant_unref (fixed);
1060         }
1061
1062       return g_variant_ref_sink (g_variant_builder_end (&builder));
1063     }
1064
1065   target = strinfo_string_from_alias (info->strinfo, info->strinfo_length,
1066                                       g_variant_get_string (value, NULL));
1067   return target ? g_variant_ref_sink (g_variant_new_string (target)) : NULL;
1068 }
1069
1070 static GVariant *
1071 g_settings_read_from_backend (GSettingsKeyInfo *info)
1072 {
1073   GVariant *value;
1074   GVariant *fixup;
1075   gchar *path;
1076
1077   path = g_strconcat (info->settings->priv->path, info->key, NULL);
1078   value = g_settings_backend_read (info->settings->priv->backend,
1079                                    path, info->type, FALSE);
1080   g_free (path);
1081
1082   if (value != NULL)
1083     {
1084       fixup = g_settings_range_fixup (info, value);
1085       g_variant_unref (value);
1086     }
1087   else
1088     fixup = NULL;
1089
1090   return fixup;
1091 }
1092
1093 static GVariant *
1094 g_settings_get_translated_default (GSettingsKeyInfo *info)
1095 {
1096   const gchar *translated;
1097   GError *error = NULL;
1098   const gchar *domain;
1099   GVariant *value;
1100
1101   if (info->lc_char == '\0')
1102     /* translation not requested for this key */
1103     return NULL;
1104
1105   domain = g_settings_schema_get_gettext_domain (info->settings->priv->schema);
1106
1107   if (info->lc_char == 't')
1108     translated = g_dcgettext (domain, info->unparsed, LC_TIME);
1109   else
1110     translated = g_dgettext (domain, info->unparsed);
1111
1112   if (translated == info->unparsed)
1113     /* the default value was not translated */
1114     return NULL;
1115
1116   /* try to parse the translation of the unparsed default */
1117   value = g_variant_parse (info->type, translated, NULL, NULL, &error);
1118
1119   if (value == NULL)
1120     {
1121       g_warning ("Failed to parse translated string `%s' for "
1122                  "key `%s' in schema `%s': %s", info->unparsed, info->key,
1123                  info->settings->priv->schema_name, error->message);
1124       g_warning ("Using untranslated default instead.");
1125       g_error_free (error);
1126     }
1127
1128   else if (!g_settings_key_info_range_check (info, value))
1129     {
1130       g_warning ("Translated default `%s' for key `%s' in schema `%s' "
1131                  "is outside of valid range", info->unparsed, info->key,
1132                  info->settings->priv->schema_name);
1133       g_variant_unref (value);
1134       value = NULL;
1135     }
1136
1137   return value;
1138 }
1139
1140 static gint
1141 g_settings_to_enum (GSettingsKeyInfo *info,
1142                     GVariant         *value)
1143 {
1144   gboolean it_worked;
1145   guint result;
1146
1147   it_worked = strinfo_enum_from_string (info->strinfo, info->strinfo_length,
1148                                         g_variant_get_string (value, NULL),
1149                                         &result);
1150
1151   /* 'value' can only come from the backend after being filtered for validity,
1152    * from the translation after being filtered for validity, or from the schema
1153    * itself (which the schema compiler checks for validity).  If this assertion
1154    * fails then it's really a bug in GSettings or the schema compiler...
1155    */
1156   g_assert (it_worked);
1157
1158   return result;
1159 }
1160
1161 static GVariant *
1162 g_settings_from_enum (GSettingsKeyInfo *info,
1163                       gint              value)
1164 {
1165   const gchar *string;
1166
1167   string = strinfo_string_from_enum (info->strinfo,
1168                                      info->strinfo_length,
1169                                      value);
1170
1171   if (string == NULL)
1172     return NULL;
1173
1174   return g_variant_new_string (string);
1175 }
1176
1177 static guint
1178 g_settings_to_flags (GSettingsKeyInfo *info,
1179                      GVariant         *value)
1180 {
1181   GVariantIter iter;
1182   const gchar *flag;
1183   guint result;
1184
1185   result = 0;
1186   g_variant_iter_init (&iter, value);
1187   while (g_variant_iter_next (&iter, "&s", &flag))
1188     {
1189       gboolean it_worked;
1190       guint flag_value;
1191
1192       it_worked = strinfo_enum_from_string (info->strinfo,
1193                                             info->strinfo_length,
1194                                             flag, &flag_value);
1195       /* as in g_settings_to_enum() */
1196       g_assert (it_worked);
1197
1198       result |= flag_value;
1199     }
1200
1201   return result;
1202 }
1203
1204 static GVariant *
1205 g_settings_from_flags (GSettingsKeyInfo *info,
1206                        guint             value)
1207 {
1208   GVariantBuilder builder;
1209   gint i;
1210
1211   g_variant_builder_init (&builder, G_VARIANT_TYPE ("as"));
1212
1213   for (i = 0; i < 32; i++)
1214     if (value & (1u << i))
1215       {
1216         const gchar *string;
1217
1218         string = strinfo_string_from_enum (info->strinfo,
1219                                            info->strinfo_length,
1220                                            1u << i);
1221
1222         if (string == NULL)
1223           {
1224             g_variant_builder_clear (&builder);
1225             return NULL;
1226           }
1227
1228         g_variant_builder_add (&builder, "s", string);
1229       }
1230
1231   return g_variant_builder_end (&builder);
1232 }
1233
1234 /* Public Get/Set API {{{1 (get, get_value, set, set_value, get_mapped) */
1235 /**
1236  * g_settings_get_value:
1237  * @settings: a #GSettings object
1238  * @key: the key to get the value for
1239  * @returns: a new #GVariant
1240  *
1241  * Gets the value that is stored in @settings for @key.
1242  *
1243  * It is a programmer error to give a @key that isn't contained in the
1244  * schema for @settings.
1245  *
1246  * Since: 2.26
1247  */
1248 GVariant *
1249 g_settings_get_value (GSettings   *settings,
1250                       const gchar *key)
1251 {
1252   GSettingsKeyInfo info;
1253   GVariant *value;
1254
1255   g_return_val_if_fail (G_IS_SETTINGS (settings), NULL);
1256   g_return_val_if_fail (key != NULL, NULL);
1257
1258   g_settings_get_key_info (&info, settings, key);
1259   value = g_settings_read_from_backend (&info);
1260
1261   if (value == NULL)
1262     value = g_settings_get_translated_default (&info);
1263
1264   if (value == NULL)
1265     value = g_variant_ref (info.default_value);
1266
1267   g_settings_free_key_info (&info);
1268
1269   return value;
1270 }
1271
1272 /**
1273  * g_settings_get_enum:
1274  * @settings: a #GSettings object
1275  * @key: the key to get the value for
1276  * @returns: the enum value
1277  *
1278  * Gets the value that is stored in @settings for @key and converts it
1279  * to the enum value that it represents.
1280  *
1281  * In order to use this function the type of the value must be a string
1282  * and it must be marked in the schema file as an enumerated type.
1283  *
1284  * It is a programmer error to give a @key that isn't contained in the
1285  * schema for @settings or is not marked as an enumerated type.
1286  *
1287  * If the value stored in the configuration database is not a valid
1288  * value for the enumerated type then this function will return the
1289  * default value.
1290  *
1291  * Since: 2.26
1292  **/
1293 gint
1294 g_settings_get_enum (GSettings   *settings,
1295                      const gchar *key)
1296 {
1297   GSettingsKeyInfo info;
1298   GVariant *value;
1299   gint result;
1300
1301   g_return_val_if_fail (G_IS_SETTINGS (settings), -1);
1302   g_return_val_if_fail (key != NULL, -1);
1303
1304   g_settings_get_key_info (&info, settings, key);
1305
1306   if (!info.is_enum)
1307     {
1308       g_critical ("g_settings_get_enum() called on key `%s' which is not "
1309                   "associated with an enumerated type", info.key);
1310       g_settings_free_key_info (&info);
1311       return -1;
1312     }
1313
1314   value = g_settings_read_from_backend (&info);
1315
1316   if (value == NULL)
1317     value = g_settings_get_translated_default (&info);
1318
1319   if (value == NULL)
1320     value = g_variant_ref (info.default_value);
1321
1322   result = g_settings_to_enum (&info, value);
1323   g_settings_free_key_info (&info);
1324   g_variant_unref (value);
1325
1326   return result;
1327 }
1328
1329 /**
1330  * g_settings_set_enum:
1331  * @settings: a #GSettings object
1332  * @key: a key, within @settings
1333  * @value: an enumerated value
1334  * @returns: %TRUE, if the set succeeds
1335  *
1336  * Looks up the enumerated type nick for @value and writes it to @key,
1337  * within @settings.
1338  *
1339  * It is a programmer error to give a @key that isn't contained in the
1340  * schema for @settings or is not marked as an enumerated type, or for
1341  * @value not to be a valid value for the named type.
1342  *
1343  * After performing the write, accessing @key directly with
1344  * g_settings_get_string() will return the 'nick' associated with
1345  * @value.
1346  **/
1347 gboolean
1348 g_settings_set_enum (GSettings   *settings,
1349                      const gchar *key,
1350                      gint         value)
1351 {
1352   GSettingsKeyInfo info;
1353   GVariant *variant;
1354   gboolean success;
1355
1356   g_return_val_if_fail (G_IS_SETTINGS (settings), FALSE);
1357   g_return_val_if_fail (key != NULL, FALSE);
1358
1359   g_settings_get_key_info (&info, settings, key);
1360
1361   if (!info.is_enum)
1362     {
1363       g_critical ("g_settings_set_enum() called on key `%s' which is not "
1364                   "associated with an enumerated type", info.key);
1365       return FALSE;
1366     }
1367
1368   if (!(variant = g_settings_from_enum (&info, value)))
1369     {
1370       g_critical ("g_settings_set_enum(): invalid enum value %d for key `%s' "
1371                   "in schema `%s'.  Doing nothing.", value, info.key,
1372                   info.settings->priv->schema_name);
1373       g_settings_free_key_info (&info);
1374       return FALSE;
1375     }
1376
1377   success = g_settings_write_to_backend (&info, variant);
1378   g_settings_free_key_info (&info);
1379
1380   return success;
1381 }
1382
1383 /**
1384  * g_settings_get_flags:
1385  * @settings: a #GSettings object
1386  * @key: the key to get the value for
1387  * @returns: the flags value
1388  *
1389  * Gets the value that is stored in @settings for @key and converts it
1390  * to the flags value that it represents.
1391  *
1392  * In order to use this function the type of the value must be an array
1393  * of strings and it must be marked in the schema file as an flags type.
1394  *
1395  * It is a programmer error to give a @key that isn't contained in the
1396  * schema for @settings or is not marked as a flags type.
1397  *
1398  * If the value stored in the configuration database is not a valid
1399  * value for the flags type then this function will return the default
1400  * value.
1401  *
1402  * Since: 2.26
1403  **/
1404 guint
1405 g_settings_get_flags (GSettings   *settings,
1406                       const gchar *key)
1407 {
1408   GSettingsKeyInfo info;
1409   GVariant *value;
1410   guint result;
1411
1412   g_return_val_if_fail (G_IS_SETTINGS (settings), -1);
1413   g_return_val_if_fail (key != NULL, -1);
1414
1415   g_settings_get_key_info (&info, settings, key);
1416
1417   if (!info.is_flags)
1418     {
1419       g_critical ("g_settings_get_flags() called on key `%s' which is not "
1420                   "associated with a flags type", info.key);
1421       g_settings_free_key_info (&info);
1422       return -1;
1423     }
1424
1425   value = g_settings_read_from_backend (&info);
1426
1427   if (value == NULL)
1428     value = g_settings_get_translated_default (&info);
1429
1430   if (value == NULL)
1431     value = g_variant_ref (info.default_value);
1432
1433   result = g_settings_to_flags (&info, value);
1434   g_settings_free_key_info (&info);
1435   g_variant_unref (value);
1436
1437   return result;
1438 }
1439
1440 /**
1441  * g_settings_set_flags:
1442  * @settings: a #GSettings object
1443  * @key: a key, within @settings
1444  * @value: a flags value
1445  * @returns: %TRUE, if the set succeeds
1446  *
1447  * Looks up the flags type nicks for the bits specified by @value, puts
1448  * them in an array of strings and writes the array to @key, within
1449  * @settings.
1450  *
1451  * It is a programmer error to give a @key that isn't contained in the
1452  * schema for @settings or is not marked as a flags type, or for @value
1453  * to contain any bits that are not value for the named type.
1454  *
1455  * After performing the write, accessing @key directly with
1456  * g_settings_get_strv() will return an array of 'nicks'; one for each
1457  * bit in @value.
1458  **/
1459 gboolean
1460 g_settings_set_flags (GSettings   *settings,
1461                       const gchar *key,
1462                       guint        value)
1463 {
1464   GSettingsKeyInfo info;
1465   GVariant *variant;
1466   gboolean success;
1467
1468   g_return_val_if_fail (G_IS_SETTINGS (settings), FALSE);
1469   g_return_val_if_fail (key != NULL, FALSE);
1470
1471   g_settings_get_key_info (&info, settings, key);
1472
1473   if (!info.is_flags)
1474     {
1475       g_critical ("g_settings_set_flags() called on key `%s' which is not "
1476                   "associated with a flags type", info.key);
1477       return FALSE;
1478     }
1479
1480   if (!(variant = g_settings_from_flags (&info, value)))
1481     {
1482       g_critical ("g_settings_set_flags(): invalid flags value 0x%08x "
1483                   "for key `%s' in schema `%s'.  Doing nothing.",
1484                   value, info.key, info.settings->priv->schema_name);
1485       g_settings_free_key_info (&info);
1486       return FALSE;
1487     }
1488
1489   success = g_settings_write_to_backend (&info, variant);
1490   g_settings_free_key_info (&info);
1491
1492   return success;
1493 }
1494
1495 /**
1496  * g_settings_set_value:
1497  * @settings: a #GSettings object
1498  * @key: the name of the key to set
1499  * @value: a #GVariant of the correct type
1500  * @returns: %TRUE if setting the key succeeded,
1501  *     %FALSE if the key was not writable
1502  *
1503  * Sets @key in @settings to @value.
1504  *
1505  * It is a programmer error to give a @key that isn't contained in the
1506  * schema for @settings or for @value to have the incorrect type, per
1507  * the schema.
1508  *
1509  * If @value is floating then this function consumes the reference.
1510  *
1511  * Since: 2.26
1512  **/
1513 gboolean
1514 g_settings_set_value (GSettings   *settings,
1515                       const gchar *key,
1516                       GVariant    *value)
1517 {
1518   GSettingsKeyInfo info;
1519
1520   g_return_val_if_fail (G_IS_SETTINGS (settings), FALSE);
1521   g_return_val_if_fail (key != NULL, FALSE);
1522
1523   g_settings_get_key_info (&info, settings, key);
1524
1525   if (!g_settings_type_check (&info, value))
1526     {
1527       g_critical ("g_settings_set_value: key '%s' in '%s' expects type '%s', but a GVariant of type '%s' was given",
1528                   key,
1529                   settings->priv->schema_name,
1530                   g_variant_type_peek_string (info.type),
1531                   g_variant_get_type_string (value));
1532
1533         return FALSE;
1534       }
1535
1536   if (!g_settings_key_info_range_check (&info, value))
1537     {
1538       g_warning ("g_settings_set_value: value for key '%s' in schema '%s' "
1539                  "is outside of valid range",
1540                  key,
1541                  settings->priv->schema_name);
1542
1543         return FALSE;
1544     }
1545
1546   g_settings_free_key_info (&info);
1547
1548   return g_settings_write_to_backend (&info, value);
1549 }
1550
1551 /**
1552  * g_settings_get:
1553  * @settings: a #GSettings object
1554  * @key: the key to get the value for
1555  * @format: a #GVariant format string
1556  * @...: arguments as per @format
1557  *
1558  * Gets the value that is stored at @key in @settings.
1559  *
1560  * A convenience function that combines g_settings_get_value() with
1561  * g_variant_get().
1562  *
1563  * It is a programmer error to give a @key that isn't contained in the
1564  * schema for @settings or for the #GVariantType of @format to mismatch
1565  * the type given in the schema.
1566  *
1567  * Since: 2.26
1568  */
1569 void
1570 g_settings_get (GSettings   *settings,
1571                 const gchar *key,
1572                 const gchar *format,
1573                 ...)
1574 {
1575   GVariant *value;
1576   va_list ap;
1577
1578   value = g_settings_get_value (settings, key);
1579
1580   va_start (ap, format);
1581   g_variant_get_va (value, format, NULL, &ap);
1582   va_end (ap);
1583
1584   g_variant_unref (value);
1585 }
1586
1587 /**
1588  * g_settings_set:
1589  * @settings: a #GSettings object
1590  * @key: the name of the key to set
1591  * @format: a #GVariant format string
1592  * @...: arguments as per @format
1593  * @returns: %TRUE if setting the key succeeded,
1594  *     %FALSE if the key was not writable
1595  *
1596  * Sets @key in @settings to @value.
1597  *
1598  * A convenience function that combines g_settings_set_value() with
1599  * g_variant_new().
1600  *
1601  * It is a programmer error to give a @key that isn't contained in the
1602  * schema for @settings or for the #GVariantType of @format to mismatch
1603  * the type given in the schema.
1604  *
1605  * Since: 2.26
1606  */
1607 gboolean
1608 g_settings_set (GSettings   *settings,
1609                 const gchar *key,
1610                 const gchar *format,
1611                 ...)
1612 {
1613   GVariant *value;
1614   va_list ap;
1615
1616   va_start (ap, format);
1617   value = g_variant_new_va (format, NULL, &ap);
1618   va_end (ap);
1619
1620   return g_settings_set_value (settings, key, value);
1621 }
1622
1623 /**
1624  * g_settings_get_mapped:
1625  * @settings: a #GSettings object
1626  * @key: the key to get the value for
1627  * @mapping: (scope call): the function to map the value in the
1628  *           settings database to the value used by the application
1629  * @user_data: user data for @mapping
1630  * @returns: (transfer full): the result, which may be %NULL
1631  *
1632  * Gets the value that is stored at @key in @settings, subject to
1633  * application-level validation/mapping.
1634  *
1635  * You should use this function when the application needs to perform
1636  * some processing on the value of the key (for example, parsing).  The
1637  * @mapping function performs that processing.  If the function
1638  * indicates that the processing was unsuccessful (due to a parse error,
1639  * for example) then the mapping is tried again with another value.
1640
1641  * This allows a robust 'fall back to defaults' behaviour to be
1642  * implemented somewhat automatically.
1643  *
1644  * The first value that is tried is the user's setting for the key.  If
1645  * the mapping function fails to map this value, other values may be
1646  * tried in an unspecified order (system or site defaults, translated
1647  * schema default values, untranslated schema default values, etc).
1648  *
1649  * If the mapping function fails for all possible values, one additional
1650  * attempt is made: the mapping function is called with a %NULL value.
1651  * If the mapping function still indicates failure at this point then
1652  * the application will be aborted.
1653  *
1654  * The result parameter for the @mapping function is pointed to a
1655  * #gpointer which is initially set to %NULL.  The same pointer is given
1656  * to each invocation of @mapping.  The final value of that #gpointer is
1657  * what is returned by this function.  %NULL is valid; it is returned
1658  * just as any other value would be.
1659  **/
1660 gpointer
1661 g_settings_get_mapped (GSettings           *settings,
1662                        const gchar         *key,
1663                        GSettingsGetMapping  mapping,
1664                        gpointer             user_data)
1665 {
1666   gpointer result = NULL;
1667   GSettingsKeyInfo info;
1668   GVariant *value;
1669   gboolean okay;
1670
1671   g_return_val_if_fail (G_IS_SETTINGS (settings), NULL);
1672   g_return_val_if_fail (key != NULL, NULL);
1673   g_return_val_if_fail (mapping != NULL, NULL);
1674
1675   g_settings_get_key_info (&info, settings, key);
1676
1677   if ((value = g_settings_read_from_backend (&info)))
1678     {
1679       okay = mapping (value, &result, user_data);
1680       g_variant_unref (value);
1681       if (okay) goto okay;
1682     }
1683
1684   if ((value = g_settings_get_translated_default (&info)))
1685     {
1686       okay = mapping (value, &result, user_data);
1687       g_variant_unref (value);
1688       if (okay) goto okay;
1689     }
1690
1691   if (mapping (info.default_value, &result, user_data))
1692     goto okay;
1693
1694   if (!mapping (NULL, &result, user_data))
1695     g_error ("The mapping function given to g_settings_get_mapped() for key "
1696              "`%s' in schema `%s' returned FALSE when given a NULL value.",
1697              key, settings->priv->schema_name);
1698
1699  okay:
1700   g_settings_free_key_info (&info);
1701
1702   return result;
1703 }
1704
1705 /* Convenience API (get, set_string, int, double, boolean, strv) {{{1 */
1706 /**
1707  * g_settings_get_string:
1708  * @settings: a #GSettings object
1709  * @key: the key to get the value for
1710  * @returns: a newly-allocated string
1711  *
1712  * Gets the value that is stored at @key in @settings.
1713  *
1714  * A convenience variant of g_settings_get() for strings.
1715  *
1716  * It is a programmer error to give a @key that isn't specified as
1717  * having a string type in the schema for @settings.
1718  *
1719  * Since: 2.26
1720  */
1721 gchar *
1722 g_settings_get_string (GSettings   *settings,
1723                        const gchar *key)
1724 {
1725   GVariant *value;
1726   gchar *result;
1727
1728   value = g_settings_get_value (settings, key);
1729   result = g_variant_dup_string (value, NULL);
1730   g_variant_unref (value);
1731
1732   return result;
1733 }
1734
1735 /**
1736  * g_settings_set_string:
1737  * @settings: a #GSettings object
1738  * @key: the name of the key to set
1739  * @value: the value to set it to
1740  * @returns: %TRUE if setting the key succeeded,
1741  *     %FALSE if the key was not writable
1742  *
1743  * Sets @key in @settings to @value.
1744  *
1745  * A convenience variant of g_settings_set() for strings.
1746  *
1747  * It is a programmer error to give a @key that isn't specified as
1748  * having a string type in the schema for @settings.
1749  *
1750  * Since: 2.26
1751  */
1752 gboolean
1753 g_settings_set_string (GSettings   *settings,
1754                        const gchar *key,
1755                        const gchar *value)
1756 {
1757   return g_settings_set_value (settings, key, g_variant_new_string (value));
1758 }
1759
1760 /**
1761  * g_settings_get_int:
1762  * @settings: a #GSettings object
1763  * @key: the key to get the value for
1764  * @returns: an integer
1765  *
1766  * Gets the value that is stored at @key in @settings.
1767  *
1768  * A convenience variant of g_settings_get() for 32-bit integers.
1769  *
1770  * It is a programmer error to give a @key that isn't specified as
1771  * having a int32 type in the schema for @settings.
1772  *
1773  * Since: 2.26
1774  */
1775 gint
1776 g_settings_get_int (GSettings   *settings,
1777                     const gchar *key)
1778 {
1779   GVariant *value;
1780   gint result;
1781
1782   value = g_settings_get_value (settings, key);
1783   result = g_variant_get_int32 (value);
1784   g_variant_unref (value);
1785
1786   return result;
1787 }
1788
1789 /**
1790  * g_settings_set_int:
1791  * @settings: a #GSettings object
1792  * @key: the name of the key to set
1793  * @value: the value to set it to
1794  * @returns: %TRUE if setting the key succeeded,
1795  *     %FALSE if the key was not writable
1796  *
1797  * Sets @key in @settings to @value.
1798  *
1799  * A convenience variant of g_settings_set() for 32-bit integers.
1800  *
1801  * It is a programmer error to give a @key that isn't specified as
1802  * having a int32 type in the schema for @settings.
1803  *
1804  * Since: 2.26
1805  */
1806 gboolean
1807 g_settings_set_int (GSettings   *settings,
1808                     const gchar *key,
1809                     gint         value)
1810 {
1811   return g_settings_set_value (settings, key, g_variant_new_int32 (value));
1812 }
1813
1814 /**
1815  * g_settings_get_uint:
1816  * @settings: a #GSettings object
1817  * @key: the key to get the value for
1818  * @returns: an unsigned integer
1819  *
1820  * Gets the value that is stored at @key in @settings.
1821  *
1822  * A convenience variant of g_settings_get() for 32-bit unsigned
1823  * integers.
1824  *
1825  * It is a programmer error to give a @key that isn't specified as
1826  * having a uint32 type in the schema for @settings.
1827  *
1828  * Since: 2.30
1829  */
1830 guint
1831 g_settings_get_uint (GSettings   *settings,
1832                      const gchar *key)
1833 {
1834   GVariant *value;
1835   guint result;
1836
1837   value = g_settings_get_value (settings, key);
1838   result = g_variant_get_uint32 (value);
1839   g_variant_unref (value);
1840
1841   return result;
1842 }
1843
1844 /**
1845  * g_settings_set_uint:
1846  * @settings: a #GSettings object
1847  * @key: the name of the key to set
1848  * @value: the value to set it to
1849  * @returns: %TRUE if setting the key succeeded,
1850  *     %FALSE if the key was not writable
1851  *
1852  * Sets @key in @settings to @value.
1853  *
1854  * A convenience variant of g_settings_set() for 32-bit unsigned
1855  * integers.
1856  *
1857  * It is a programmer error to give a @key that isn't specified as
1858  * having a uint32 type in the schema for @settings.
1859  *
1860  * Since: 2.30
1861  */
1862 gboolean
1863 g_settings_set_uint (GSettings   *settings,
1864                      const gchar *key,
1865                      guint        value)
1866 {
1867   return g_settings_set_value (settings, key, g_variant_new_uint32 (value));
1868 }
1869
1870 /**
1871  * g_settings_get_double:
1872  * @settings: a #GSettings object
1873  * @key: the key to get the value for
1874  * @returns: a double
1875  *
1876  * Gets the value that is stored at @key in @settings.
1877  *
1878  * A convenience variant of g_settings_get() for doubles.
1879  *
1880  * It is a programmer error to give a @key that isn't specified as
1881  * having a 'double' type in the schema for @settings.
1882  *
1883  * Since: 2.26
1884  */
1885 gdouble
1886 g_settings_get_double (GSettings   *settings,
1887                        const gchar *key)
1888 {
1889   GVariant *value;
1890   gdouble result;
1891
1892   value = g_settings_get_value (settings, key);
1893   result = g_variant_get_double (value);
1894   g_variant_unref (value);
1895
1896   return result;
1897 }
1898
1899 /**
1900  * g_settings_set_double:
1901  * @settings: a #GSettings object
1902  * @key: the name of the key to set
1903  * @value: the value to set it to
1904  * @returns: %TRUE if setting the key succeeded,
1905  *     %FALSE if the key was not writable
1906  *
1907  * Sets @key in @settings to @value.
1908  *
1909  * A convenience variant of g_settings_set() for doubles.
1910  *
1911  * It is a programmer error to give a @key that isn't specified as
1912  * having a 'double' type in the schema for @settings.
1913  *
1914  * Since: 2.26
1915  */
1916 gboolean
1917 g_settings_set_double (GSettings   *settings,
1918                        const gchar *key,
1919                        gdouble      value)
1920 {
1921   return g_settings_set_value (settings, key, g_variant_new_double (value));
1922 }
1923
1924 /**
1925  * g_settings_get_boolean:
1926  * @settings: a #GSettings object
1927  * @key: the key to get the value for
1928  * @returns: a boolean
1929  *
1930  * Gets the value that is stored at @key in @settings.
1931  *
1932  * A convenience variant of g_settings_get() for booleans.
1933  *
1934  * It is a programmer error to give a @key that isn't specified as
1935  * having a boolean type in the schema for @settings.
1936  *
1937  * Since: 2.26
1938  */
1939 gboolean
1940 g_settings_get_boolean (GSettings  *settings,
1941                        const gchar *key)
1942 {
1943   GVariant *value;
1944   gboolean result;
1945
1946   value = g_settings_get_value (settings, key);
1947   result = g_variant_get_boolean (value);
1948   g_variant_unref (value);
1949
1950   return result;
1951 }
1952
1953 /**
1954  * g_settings_set_boolean:
1955  * @settings: a #GSettings object
1956  * @key: the name of the key to set
1957  * @value: the value to set it to
1958  * @returns: %TRUE if setting the key succeeded,
1959  *     %FALSE if the key was not writable
1960  *
1961  * Sets @key in @settings to @value.
1962  *
1963  * A convenience variant of g_settings_set() for booleans.
1964  *
1965  * It is a programmer error to give a @key that isn't specified as
1966  * having a boolean type in the schema for @settings.
1967  *
1968  * Since: 2.26
1969  */
1970 gboolean
1971 g_settings_set_boolean (GSettings  *settings,
1972                        const gchar *key,
1973                        gboolean     value)
1974 {
1975   return g_settings_set_value (settings, key, g_variant_new_boolean (value));
1976 }
1977
1978 /**
1979  * g_settings_get_strv:
1980  * @settings: a #GSettings object
1981  * @key: the key to get the value for
1982  * @returns: (array zero-terminated=1) (transfer full): a
1983  * newly-allocated, %NULL-terminated array of strings, the value that
1984  * is stored at @key in @settings.
1985  *
1986  * A convenience variant of g_settings_get() for string arrays.
1987  *
1988  * It is a programmer error to give a @key that isn't specified as
1989  * having an array of strings type in the schema for @settings.
1990  *
1991  * Since: 2.26
1992  */
1993 gchar **
1994 g_settings_get_strv (GSettings   *settings,
1995                      const gchar *key)
1996 {
1997   GVariant *value;
1998   gchar **result;
1999
2000   value = g_settings_get_value (settings, key);
2001   result = g_variant_dup_strv (value, NULL);
2002   g_variant_unref (value);
2003
2004   return result;
2005 }
2006
2007 /**
2008  * g_settings_set_strv:
2009  * @settings: a #GSettings object
2010  * @key: the name of the key to set
2011  * @value: (allow-none) (array zero-terminated=1): the value to set it to, or %NULL
2012  * @returns: %TRUE if setting the key succeeded,
2013  *     %FALSE if the key was not writable
2014  *
2015  * Sets @key in @settings to @value.
2016  *
2017  * A convenience variant of g_settings_set() for string arrays.  If
2018  * @value is %NULL, then @key is set to be the empty array.
2019  *
2020  * It is a programmer error to give a @key that isn't specified as
2021  * having an array of strings type in the schema for @settings.
2022  *
2023  * Since: 2.26
2024  */
2025 gboolean
2026 g_settings_set_strv (GSettings           *settings,
2027                      const gchar         *key,
2028                      const gchar * const *value)
2029 {
2030   GVariant *array;
2031
2032   if (value != NULL)
2033     array = g_variant_new_strv (value, -1);
2034   else
2035     array = g_variant_new_strv (NULL, 0);
2036
2037   return g_settings_set_value (settings, key, array);
2038 }
2039
2040 /* Delayed apply (delay, apply, revert, get_has_unapplied) {{{1 */
2041 /**
2042  * g_settings_delay:
2043  * @settings: a #GSettings object
2044  *
2045  * Changes the #GSettings object into 'delay-apply' mode. In this
2046  * mode, changes to @settings are not immediately propagated to the
2047  * backend, but kept locally until g_settings_apply() is called.
2048  *
2049  * Since: 2.26
2050  */
2051 void
2052 g_settings_delay (GSettings *settings)
2053 {
2054   g_return_if_fail (G_IS_SETTINGS (settings));
2055
2056   if (settings->priv->delayed)
2057     return;
2058
2059   settings->priv->delayed =
2060     g_delayed_settings_backend_new (settings->priv->backend,
2061                                     settings,
2062                                     settings->priv->main_context);
2063   g_settings_backend_unwatch (settings->priv->backend, G_OBJECT (settings));
2064   g_object_unref (settings->priv->backend);
2065
2066   settings->priv->backend = G_SETTINGS_BACKEND (settings->priv->delayed);
2067   g_settings_backend_watch (settings->priv->backend,
2068                             &listener_vtable, G_OBJECT (settings),
2069                             settings->priv->main_context);
2070
2071   g_object_notify (G_OBJECT (settings), "delay-apply");
2072 }
2073
2074 /**
2075  * g_settings_apply:
2076  * @settings: a #GSettings instance
2077  *
2078  * Applies any changes that have been made to the settings.  This
2079  * function does nothing unless @settings is in 'delay-apply' mode;
2080  * see g_settings_delay().  In the normal case settings are always
2081  * applied immediately.
2082  **/
2083 void
2084 g_settings_apply (GSettings *settings)
2085 {
2086   if (settings->priv->delayed)
2087     {
2088       GDelayedSettingsBackend *delayed;
2089
2090       delayed = G_DELAYED_SETTINGS_BACKEND (settings->priv->backend);
2091       g_delayed_settings_backend_apply (delayed);
2092     }
2093 }
2094
2095 /**
2096  * g_settings_revert:
2097  * @settings: a #GSettings instance
2098  *
2099  * Reverts all non-applied changes to the settings.  This function
2100  * does nothing unless @settings is in 'delay-apply' mode; see
2101  * g_settings_delay().  In the normal case settings are always applied
2102  * immediately.
2103  *
2104  * Change notifications will be emitted for affected keys.
2105  **/
2106 void
2107 g_settings_revert (GSettings *settings)
2108 {
2109   if (settings->priv->delayed)
2110     {
2111       GDelayedSettingsBackend *delayed;
2112
2113       delayed = G_DELAYED_SETTINGS_BACKEND (settings->priv->backend);
2114       g_delayed_settings_backend_revert (delayed);
2115     }
2116 }
2117
2118 /**
2119  * g_settings_get_has_unapplied:
2120  * @settings: a #GSettings object
2121  * @returns: %TRUE if @settings has unapplied changes
2122  *
2123  * Returns whether the #GSettings object has any unapplied
2124  * changes.  This can only be the case if it is in 'delayed-apply' mode.
2125  *
2126  * Since: 2.26
2127  */
2128 gboolean
2129 g_settings_get_has_unapplied (GSettings *settings)
2130 {
2131   g_return_val_if_fail (G_IS_SETTINGS (settings), FALSE);
2132
2133   return settings->priv->delayed &&
2134          g_delayed_settings_backend_get_has_unapplied (
2135            G_DELAYED_SETTINGS_BACKEND (settings->priv->backend));
2136 }
2137
2138 /* Extra API (reset, sync, get_child, is_writable, list_*, ranges) {{{1 */
2139 /**
2140  * g_settings_reset:
2141  * @settings: a #GSettings object
2142  * @key: the name of a key
2143  *
2144  * Resets @key to its default value.
2145  *
2146  * This call resets the key, as much as possible, to its default value.
2147  * That might the value specified in the schema or the one set by the
2148  * administrator.
2149  **/
2150 void
2151 g_settings_reset (GSettings *settings,
2152                   const gchar *key)
2153 {
2154   gchar *path;
2155
2156   path = g_strconcat (settings->priv->path, key, NULL);
2157   g_settings_backend_reset (settings->priv->backend, path, NULL);
2158   g_free (path);
2159 }
2160
2161 /**
2162  * g_settings_sync:
2163  *
2164  * Ensures that all pending operations for the given are complete for
2165  * the default backend.
2166  *
2167  * Writes made to a #GSettings are handled asynchronously.  For this
2168  * reason, it is very unlikely that the changes have it to disk by the
2169  * time g_settings_set() returns.
2170  *
2171  * This call will block until all of the writes have made it to the
2172  * backend.  Since the mainloop is not running, no change notifications
2173  * will be dispatched during this call (but some may be queued by the
2174  * time the call is done).
2175  **/
2176 void
2177 g_settings_sync (void)
2178 {
2179   g_settings_backend_sync_default ();
2180 }
2181
2182 /**
2183  * g_settings_is_writable:
2184  * @settings: a #GSettings object
2185  * @name: the name of a key
2186  * @returns: %TRUE if the key @name is writable
2187  *
2188  * Finds out if a key can be written or not
2189  *
2190  * Since: 2.26
2191  */
2192 gboolean
2193 g_settings_is_writable (GSettings   *settings,
2194                         const gchar *name)
2195 {
2196   gboolean writable;
2197   gchar *path;
2198
2199   g_return_val_if_fail (G_IS_SETTINGS (settings), FALSE);
2200
2201   path = g_strconcat (settings->priv->path, name, NULL);
2202   writable = g_settings_backend_get_writable (settings->priv->backend, path);
2203   g_free (path);
2204
2205   return writable;
2206 }
2207
2208 /**
2209  * g_settings_get_child:
2210  * @settings: a #GSettings object
2211  * @name: the name of the 'child' schema
2212  * @returns: (transfer full): a 'child' settings object
2213  *
2214  * Creates a 'child' settings object which has a base path of
2215  * <replaceable>base-path</replaceable>/@name, where
2216  * <replaceable>base-path</replaceable> is the base path of @settings.
2217  *
2218  * The schema for the child settings object must have been declared
2219  * in the schema of @settings using a <tag class="starttag">child</tag> element.
2220  *
2221  * Since: 2.26
2222  */
2223 GSettings *
2224 g_settings_get_child (GSettings   *settings,
2225                       const gchar *name)
2226 {
2227   const gchar *child_schema;
2228   gchar *child_path;
2229   gchar *child_name;
2230   GSettings *child;
2231
2232   g_return_val_if_fail (G_IS_SETTINGS (settings), NULL);
2233
2234   child_name = g_strconcat (name, "/", NULL);
2235   child_schema = g_settings_schema_get_string (settings->priv->schema,
2236                                                child_name);
2237   if (child_schema == NULL)
2238     g_error ("Schema '%s' has no child '%s'",
2239              settings->priv->schema_name, name);
2240
2241   child_path = g_strconcat (settings->priv->path, child_name, NULL);
2242   child = g_object_new (G_TYPE_SETTINGS,
2243                         "schema", child_schema,
2244                         "path", child_path,
2245                         NULL);
2246   g_free (child_path);
2247   g_free (child_name);
2248
2249   return child;
2250 }
2251
2252 /**
2253  * g_settings_list_keys:
2254  * @settings: a #GSettings object
2255  * @returns: (transfer full) (element-type utf8): a list of the keys on @settings
2256  *
2257  * Introspects the list of keys on @settings.
2258  *
2259  * You should probably not be calling this function from "normal" code
2260  * (since you should already know what keys are in your schema).  This
2261  * function is intended for introspection reasons.
2262  *
2263  * You should free the return value with g_strfreev() when you are done
2264  * with it.
2265  */
2266 gchar **
2267 g_settings_list_keys (GSettings *settings)
2268 {
2269   const GQuark *keys;
2270   gchar **strv;
2271   gint n_keys;
2272   gint i, j;
2273
2274   keys = g_settings_schema_list (settings->priv->schema, &n_keys);
2275   strv = g_new (gchar *, n_keys + 1);
2276   for (i = j = 0; i < n_keys; i++)
2277     {
2278       const gchar *key = g_quark_to_string (keys[i]);
2279
2280       if (!g_str_has_suffix (key, "/"))
2281         strv[j++] = g_strdup (key);
2282     }
2283   strv[j] = NULL;
2284
2285   return strv;
2286 }
2287
2288 /**
2289  * g_settings_list_children:
2290  * @settings: a #GSettings object
2291  * @returns: (transfer full) (element-type utf8): a list of the children on @settings
2292  *
2293  * Gets the list of children on @settings.
2294  *
2295  * The list is exactly the list of strings for which it is not an error
2296  * to call g_settings_get_child().
2297  *
2298  * For GSettings objects that are lists, this value can change at any
2299  * time and you should connect to the "children-changed" signal to watch
2300  * for those changes.  Note that there is a race condition here: you may
2301  * request a child after listing it only for it to have been destroyed
2302  * in the meantime.  For this reason, g_settings_get_child() may return
2303  * %NULL even for a child that was listed by this function.
2304  *
2305  * For GSettings objects that are not lists, you should probably not be
2306  * calling this function from "normal" code (since you should already
2307  * know what children are in your schema).  This function may still be
2308  * useful there for introspection reasons, however.
2309  *
2310  * You should free the return value with g_strfreev() when you are done
2311  * with it.
2312  */
2313 gchar **
2314 g_settings_list_children (GSettings *settings)
2315 {
2316   const GQuark *keys;
2317   gchar **strv;
2318   gint n_keys;
2319   gint i, j;
2320
2321   keys = g_settings_schema_list (settings->priv->schema, &n_keys);
2322   strv = g_new (gchar *, n_keys + 1);
2323   for (i = j = 0; i < n_keys; i++)
2324     {
2325       const gchar *key = g_quark_to_string (keys[i]);
2326
2327       if (g_str_has_suffix (key, "/"))
2328         {
2329           gint length = strlen (key);
2330
2331           strv[j] = g_memdup (key, length);
2332           strv[j][length - 1] = '\0';
2333           j++;
2334         }
2335     }
2336   strv[j] = NULL;
2337
2338   return strv;
2339 }
2340
2341 /**
2342  * g_settings_get_range:
2343  * @settings: a #GSettings
2344  * @key: the key to query the range of
2345  * @returns: a #GVariant describing the range
2346  *
2347  * Queries the range of a key.
2348  *
2349  * This function will return a #GVariant that fully describes the range
2350  * of values that are valid for @key.
2351  *
2352  * The type of #GVariant returned is <literal>(sv)</literal>.  The
2353  * string describes the type of range restriction in effect.  The type
2354  * and meaning of the value contained in the variant depends on the
2355  * string.
2356  *
2357  * If the string is <literal>'type'</literal> then the variant contains
2358  * an empty array.  The element type of that empty array is the expected
2359  * type of value and all values of that type are valid.
2360  *
2361  * If the string is <literal>'enum'</literal> then the variant contains
2362  * an array enumerating the possible values.  Each item in the array is
2363  * a possible valid value and no other values are valid.
2364  *
2365  * If the string is <literal>'flags'</literal> then the variant contains
2366  * an array.  Each item in the array is a value that may appear zero or
2367  * one times in an array to be used as the value for this key.  For
2368  * example, if the variant contained the array <literal>['x',
2369  * 'y']</literal> then the valid values for the key would be
2370  * <literal>[]</literal>, <literal>['x']</literal>,
2371  * <literal>['y']</literal>, <literal>['x', 'y']</literal> and
2372  * <literal>['y', 'x']</literal>.
2373  *
2374  * Finally, if the string is <literal>'range'</literal> then the variant
2375  * contains a pair of like-typed values -- the minimum and maximum
2376  * permissible values for this key.
2377  *
2378  * This information should not be used by normal programs.  It is
2379  * considered to be a hint for introspection purposes.  Normal programs
2380  * should already know what is permitted by their own schema.  The
2381  * format may change in any way in the future -- but particularly, new
2382  * forms may be added to the possibilities described above.
2383  *
2384  * It is a programmer error to give a @key that isn't contained in the
2385  * schema for @settings.
2386  *
2387  * You should free the returned value with g_variant_unref() when it is
2388  * no longer needed.
2389  *
2390  * Since: 2.28
2391  **/
2392 GVariant *
2393 g_settings_get_range (GSettings   *settings,
2394                       const gchar *key)
2395 {
2396   GSettingsKeyInfo info;
2397   const gchar *type;
2398   GVariant *range;
2399
2400   g_settings_get_key_info (&info, settings, key);
2401
2402   if (info.minimum)
2403     {
2404       range = g_variant_new ("(**)", info.minimum, info.maximum);
2405       type = "range";
2406     }
2407   else if (info.strinfo)
2408     {
2409       range = strinfo_enumerate (info.strinfo, info.strinfo_length);
2410       type = info.is_flags ? "flags" : "enum";
2411     }
2412   else
2413     {
2414       range = g_variant_new_array (info.type, NULL, 0);
2415       type = "type";
2416     }
2417
2418   g_settings_free_key_info (&info);
2419
2420   return g_variant_ref_sink (g_variant_new ("(sv)", type, range));
2421 }
2422
2423 /**
2424  * g_settings_range_check:
2425  * @settings: a #GSettings
2426  * @key: the key to check
2427  * @value: the value to check
2428  * @returns: %TRUE if @value is valid for @key
2429  *
2430  * Checks if the given @value is of the correct type and within the
2431  * permitted range for @key.
2432  *
2433  * This API is not intended to be used by normal programs -- they should
2434  * already know what is permitted by their own schemas.  This API is
2435  * meant to be used by programs such as editors or commandline tools.
2436  *
2437  * It is a programmer error to give a @key that isn't contained in the
2438  * schema for @settings.
2439  *
2440  * Since: 2.28
2441  **/
2442 gboolean
2443 g_settings_range_check (GSettings   *settings,
2444                         const gchar *key,
2445                         GVariant    *value)
2446 {
2447   GSettingsKeyInfo info;
2448   gboolean good;
2449
2450   g_settings_get_key_info (&info, settings, key);
2451   good = g_settings_type_check (&info, value) &&
2452          g_settings_key_info_range_check (&info, value);
2453   g_settings_free_key_info (&info);
2454
2455   return good;
2456 }
2457
2458 /* Binding {{{1 */
2459 typedef struct
2460 {
2461   GSettingsKeyInfo info;
2462   GObject *object;
2463
2464   GSettingsBindGetMapping get_mapping;
2465   GSettingsBindSetMapping set_mapping;
2466   gpointer user_data;
2467   GDestroyNotify destroy;
2468
2469   guint writable_handler_id;
2470   guint property_handler_id;
2471   const GParamSpec *property;
2472   guint key_handler_id;
2473
2474   /* prevent recursion */
2475   gboolean running;
2476 } GSettingsBinding;
2477
2478 static void
2479 g_settings_binding_free (gpointer data)
2480 {
2481   GSettingsBinding *binding = data;
2482
2483   g_assert (!binding->running);
2484
2485   if (binding->writable_handler_id)
2486     g_signal_handler_disconnect (binding->info.settings,
2487                                  binding->writable_handler_id);
2488
2489   if (binding->key_handler_id)
2490     g_signal_handler_disconnect (binding->info.settings,
2491                                  binding->key_handler_id);
2492
2493   if (g_signal_handler_is_connected (binding->object,
2494                                      binding->property_handler_id))
2495   g_signal_handler_disconnect (binding->object,
2496                                binding->property_handler_id);
2497
2498   g_settings_free_key_info (&binding->info);
2499
2500   if (binding->destroy)
2501     binding->destroy (binding->user_data);
2502
2503   g_slice_free (GSettingsBinding, binding);
2504 }
2505
2506 static GQuark
2507 g_settings_binding_quark (const char *property)
2508 {
2509   GQuark quark;
2510   gchar *tmp;
2511
2512   tmp = g_strdup_printf ("gsettingsbinding-%s", property);
2513   quark = g_quark_from_string (tmp);
2514   g_free (tmp);
2515
2516   return quark;
2517 }
2518
2519 static void
2520 g_settings_binding_key_changed (GSettings   *settings,
2521                                 const gchar *key,
2522                                 gpointer     user_data)
2523 {
2524   GSettingsBinding *binding = user_data;
2525   GValue value = G_VALUE_INIT;
2526   GVariant *variant;
2527
2528   g_assert (settings == binding->info.settings);
2529   g_assert (key == binding->info.key);
2530
2531   if (binding->running)
2532     return;
2533
2534   binding->running = TRUE;
2535
2536   g_value_init (&value, binding->property->value_type);
2537
2538   variant = g_settings_read_from_backend (&binding->info);
2539   if (variant && !binding->get_mapping (&value, variant, binding->user_data))
2540     {
2541       /* silently ignore errors in the user's config database */
2542       g_variant_unref (variant);
2543       variant = NULL;
2544     }
2545
2546   if (variant == NULL)
2547     {
2548       variant = g_settings_get_translated_default (&binding->info);
2549       if (variant &&
2550           !binding->get_mapping (&value, variant, binding->user_data))
2551         {
2552           /* flag translation errors with a warning */
2553           g_warning ("Translated default `%s' for key `%s' in schema `%s' "
2554                      "was rejected by the binding mapping function",
2555                      binding->info.unparsed, binding->info.key,
2556                      binding->info.settings->priv->schema_name);
2557           g_variant_unref (variant);
2558           variant = NULL;
2559         }
2560     }
2561
2562   if (variant == NULL)
2563     {
2564       variant = g_variant_ref (binding->info.default_value);
2565       if (!binding->get_mapping (&value, variant, binding->user_data))
2566         g_error ("The schema default value for key `%s' in schema `%s' "
2567                  "was rejected by the binding mapping function.",
2568                  binding->info.key,
2569                  binding->info.settings->priv->schema_name);
2570     }
2571
2572   g_object_set_property (binding->object, binding->property->name, &value);
2573   g_variant_unref (variant);
2574   g_value_unset (&value);
2575
2576   binding->running = FALSE;
2577 }
2578
2579 static void
2580 g_settings_binding_property_changed (GObject          *object,
2581                                      const GParamSpec *pspec,
2582                                      gpointer          user_data)
2583 {
2584   GSettingsBinding *binding = user_data;
2585   GValue value = G_VALUE_INIT;
2586   GVariant *variant;
2587
2588   g_assert (object == binding->object);
2589   g_assert (pspec == binding->property);
2590
2591   if (binding->running)
2592     return;
2593
2594   binding->running = TRUE;
2595
2596   g_value_init (&value, pspec->value_type);
2597   g_object_get_property (object, pspec->name, &value);
2598   if ((variant = binding->set_mapping (&value, binding->info.type,
2599                                        binding->user_data)))
2600     {
2601       g_variant_take_ref (variant);
2602
2603       if (!g_settings_type_check (&binding->info, variant))
2604         {
2605           g_critical ("binding mapping function for key `%s' returned "
2606                       "GVariant of type `%s' when type `%s' was requested",
2607                       binding->info.key, g_variant_get_type_string (variant),
2608                       g_variant_type_dup_string (binding->info.type));
2609           return;
2610         }
2611
2612       if (!g_settings_key_info_range_check (&binding->info, variant))
2613         {
2614           g_critical ("GObject property `%s' on a `%s' object is out of "
2615                       "schema-specified range for key `%s' of `%s': %s",
2616                       binding->property->name,
2617                       g_type_name (binding->property->owner_type),
2618                       binding->info.key,
2619                       binding->info.settings->priv->schema_name,
2620                       g_variant_print (variant, TRUE));
2621           return;
2622         }
2623
2624       g_settings_write_to_backend (&binding->info, variant);
2625       g_variant_unref (variant);
2626     }
2627   g_value_unset (&value);
2628
2629   binding->running = FALSE;
2630 }
2631
2632 static gboolean
2633 g_settings_bind_invert_boolean_get_mapping (GValue   *value,
2634                                             GVariant *variant,
2635                                             gpointer  user_data)
2636 {
2637   g_value_set_boolean (value, !g_variant_get_boolean (variant));
2638   return TRUE;
2639 }
2640
2641 static GVariant *
2642 g_settings_bind_invert_boolean_set_mapping (const GValue       *value,
2643                                             const GVariantType *expected_type,
2644                                             gpointer            user_data)
2645 {
2646   return g_variant_new_boolean (!g_value_get_boolean (value));
2647 }
2648
2649 /**
2650  * g_settings_bind:
2651  * @settings: a #GSettings object
2652  * @key: the key to bind
2653  * @object: (type GObject.Object): a #GObject
2654  * @property: the name of the property to bind
2655  * @flags: flags for the binding
2656  *
2657  * Create a binding between the @key in the @settings object
2658  * and the property @property of @object.
2659  *
2660  * The binding uses the default GIO mapping functions to map
2661  * between the settings and property values. These functions
2662  * handle booleans, numeric types and string types in a
2663  * straightforward way. Use g_settings_bind_with_mapping() if
2664  * you need a custom mapping, or map between types that are not
2665  * supported by the default mapping functions.
2666  *
2667  * Unless the @flags include %G_SETTINGS_BIND_NO_SENSITIVITY, this
2668  * function also establishes a binding between the writability of
2669  * @key and the "sensitive" property of @object (if @object has
2670  * a boolean property by that name). See g_settings_bind_writable()
2671  * for more details about writable bindings.
2672  *
2673  * Note that the lifecycle of the binding is tied to the object,
2674  * and that you can have only one binding per object property.
2675  * If you bind the same property twice on the same object, the second
2676  * binding overrides the first one.
2677  *
2678  * Since: 2.26
2679  */
2680 void
2681 g_settings_bind (GSettings          *settings,
2682                  const gchar        *key,
2683                  gpointer            object,
2684                  const gchar        *property,
2685                  GSettingsBindFlags  flags)
2686 {
2687   GSettingsBindGetMapping get_mapping = NULL;
2688   GSettingsBindSetMapping set_mapping = NULL;
2689
2690   if (flags & G_SETTINGS_BIND_INVERT_BOOLEAN)
2691     {
2692       get_mapping = g_settings_bind_invert_boolean_get_mapping;
2693       set_mapping = g_settings_bind_invert_boolean_set_mapping;
2694
2695       /* can't pass this flag to g_settings_bind_with_mapping() */
2696       flags &= ~G_SETTINGS_BIND_INVERT_BOOLEAN;
2697     }
2698
2699   g_settings_bind_with_mapping (settings, key, object, property, flags,
2700                                 get_mapping, set_mapping, NULL, NULL);
2701 }
2702
2703 /**
2704  * g_settings_bind_with_mapping: (skip)
2705  * @settings: a #GSettings object
2706  * @key: the key to bind
2707  * @object: (type GObject.Object): a #GObject
2708  * @property: the name of the property to bind
2709  * @flags: flags for the binding
2710  * @get_mapping: a function that gets called to convert values
2711  *     from @settings to @object, or %NULL to use the default GIO mapping
2712  * @set_mapping: a function that gets called to convert values
2713  *     from @object to @settings, or %NULL to use the default GIO mapping
2714  * @user_data: data that gets passed to @get_mapping and @set_mapping
2715  * @destroy: #GDestroyNotify function for @user_data
2716  *
2717  * Create a binding between the @key in the @settings object
2718  * and the property @property of @object.
2719  *
2720  * The binding uses the provided mapping functions to map between
2721  * settings and property values.
2722  *
2723  * Note that the lifecycle of the binding is tied to the object,
2724  * and that you can have only one binding per object property.
2725  * If you bind the same property twice on the same object, the second
2726  * binding overrides the first one.
2727  *
2728  * Since: 2.26
2729  */
2730 void
2731 g_settings_bind_with_mapping (GSettings               *settings,
2732                               const gchar             *key,
2733                               gpointer                 object,
2734                               const gchar             *property,
2735                               GSettingsBindFlags       flags,
2736                               GSettingsBindGetMapping  get_mapping,
2737                               GSettingsBindSetMapping  set_mapping,
2738                               gpointer                 user_data,
2739                               GDestroyNotify           destroy)
2740 {
2741   GSettingsBinding *binding;
2742   GObjectClass *objectclass;
2743   gchar *detailed_signal;
2744   GQuark binding_quark;
2745
2746   g_return_if_fail (G_IS_SETTINGS (settings));
2747   g_return_if_fail (key != NULL);
2748   g_return_if_fail (G_IS_OBJECT (object));
2749   g_return_if_fail (property != NULL);
2750   g_return_if_fail (~flags & G_SETTINGS_BIND_INVERT_BOOLEAN);
2751
2752   objectclass = G_OBJECT_GET_CLASS (object);
2753
2754   binding = g_slice_new0 (GSettingsBinding);
2755   g_settings_get_key_info (&binding->info, settings, key);
2756   binding->object = object;
2757   binding->property = g_object_class_find_property (objectclass, property);
2758   binding->user_data = user_data;
2759   binding->destroy = destroy;
2760   binding->get_mapping = get_mapping ? get_mapping : g_settings_get_mapping;
2761   binding->set_mapping = set_mapping ? set_mapping : g_settings_set_mapping;
2762
2763   if (!(flags & (G_SETTINGS_BIND_GET | G_SETTINGS_BIND_SET)))
2764     flags |= G_SETTINGS_BIND_GET | G_SETTINGS_BIND_SET;
2765
2766   if (binding->property == NULL)
2767     {
2768       g_critical ("g_settings_bind: no property '%s' on class '%s'",
2769                   property, G_OBJECT_TYPE_NAME (object));
2770       return;
2771     }
2772
2773   if ((flags & G_SETTINGS_BIND_GET) &&
2774       (binding->property->flags & G_PARAM_WRITABLE) == 0)
2775     {
2776       g_critical ("g_settings_bind: property '%s' on class '%s' is not "
2777                   "writable", property, G_OBJECT_TYPE_NAME (object));
2778       return;
2779     }
2780   if ((flags & G_SETTINGS_BIND_SET) &&
2781       (binding->property->flags & G_PARAM_READABLE) == 0)
2782     {
2783       g_critical ("g_settings_bind: property '%s' on class '%s' is not "
2784                   "readable", property, G_OBJECT_TYPE_NAME (object));
2785       return;
2786     }
2787
2788   if (get_mapping == g_settings_bind_invert_boolean_get_mapping)
2789     {
2790       /* g_settings_bind_invert_boolean_get_mapping() is a private
2791        * function, so if we are here it means that g_settings_bind() was
2792        * called with G_SETTINGS_BIND_INVERT_BOOLEAN.
2793        *
2794        * Ensure that both sides are boolean.
2795        */
2796
2797       if (binding->property->value_type != G_TYPE_BOOLEAN)
2798         {
2799           g_critical ("g_settings_bind: G_SETTINGS_BIND_INVERT_BOOLEAN "
2800                       "was specified, but property `%s' on type `%s' has "
2801                       "type `%s'", property, G_OBJECT_TYPE_NAME (object),
2802                       g_type_name ((binding->property->value_type)));
2803           return;
2804         }
2805
2806       if (!g_variant_type_equal (binding->info.type, G_VARIANT_TYPE_BOOLEAN))
2807         {
2808           g_critical ("g_settings_bind: G_SETTINGS_BIND_INVERT_BOOLEAN "
2809                       "was specified, but key `%s' on schema `%s' has "
2810                       "type `%s'", key, settings->priv->schema_name,
2811                       g_variant_type_dup_string (binding->info.type));
2812           return;
2813         }
2814
2815     }
2816
2817   else if (((get_mapping == NULL && (flags & G_SETTINGS_BIND_GET)) ||
2818             (set_mapping == NULL && (flags & G_SETTINGS_BIND_SET))) &&
2819            !g_settings_mapping_is_compatible (binding->property->value_type,
2820                                               binding->info.type))
2821     {
2822       g_critical ("g_settings_bind: property '%s' on class '%s' has type "
2823                   "'%s' which is not compatible with type '%s' of key '%s' "
2824                   "on schema '%s'", property, G_OBJECT_TYPE_NAME (object),
2825                   g_type_name (binding->property->value_type),
2826                   g_variant_type_dup_string (binding->info.type), key,
2827                   settings->priv->schema_name);
2828       return;
2829     }
2830
2831   if ((flags & G_SETTINGS_BIND_SET) &&
2832       (~flags & G_SETTINGS_BIND_NO_SENSITIVITY))
2833     {
2834       GParamSpec *sensitive;
2835
2836       sensitive = g_object_class_find_property (objectclass, "sensitive");
2837
2838       if (sensitive && sensitive->value_type == G_TYPE_BOOLEAN &&
2839           (sensitive->flags & G_PARAM_WRITABLE))
2840         g_settings_bind_writable (settings, binding->info.key,
2841                                   object, "sensitive", FALSE);
2842     }
2843
2844   if (flags & G_SETTINGS_BIND_SET)
2845     {
2846       detailed_signal = g_strdup_printf ("notify::%s", property);
2847       binding->property_handler_id =
2848         g_signal_connect (object, detailed_signal,
2849                           G_CALLBACK (g_settings_binding_property_changed),
2850                           binding);
2851       g_free (detailed_signal);
2852
2853       if (~flags & G_SETTINGS_BIND_GET)
2854         g_settings_binding_property_changed (object,
2855                                              binding->property,
2856                                              binding);
2857     }
2858
2859   if (flags & G_SETTINGS_BIND_GET)
2860     {
2861       if (~flags & G_SETTINGS_BIND_GET_NO_CHANGES)
2862         {
2863           detailed_signal = g_strdup_printf ("changed::%s", key);
2864           binding->key_handler_id =
2865             g_signal_connect (settings, detailed_signal,
2866                               G_CALLBACK (g_settings_binding_key_changed),
2867                               binding);
2868           g_free (detailed_signal);
2869         }
2870
2871       g_settings_binding_key_changed (settings, binding->info.key, binding);
2872     }
2873
2874   binding_quark = g_settings_binding_quark (property);
2875   g_object_set_qdata_full (object, binding_quark,
2876                            binding, g_settings_binding_free);
2877 }
2878
2879 /* Writability binding {{{1 */
2880 typedef struct
2881 {
2882   GSettings *settings;
2883   gpointer object;
2884   const gchar *key;
2885   const gchar *property;
2886   gboolean inverted;
2887   gulong handler_id;
2888 } GSettingsWritableBinding;
2889
2890 static void
2891 g_settings_writable_binding_free (gpointer data)
2892 {
2893   GSettingsWritableBinding *binding = data;
2894
2895   g_signal_handler_disconnect (binding->settings, binding->handler_id);
2896   g_object_unref (binding->settings);
2897   g_slice_free (GSettingsWritableBinding, binding);
2898 }
2899
2900 static void
2901 g_settings_binding_writable_changed (GSettings   *settings,
2902                                      const gchar *key,
2903                                      gpointer     user_data)
2904 {
2905   GSettingsWritableBinding *binding = user_data;
2906   gboolean writable;
2907
2908   g_assert (settings == binding->settings);
2909   g_assert (key == binding->key);
2910
2911   writable = g_settings_is_writable (settings, key);
2912
2913   if (binding->inverted)
2914     writable = !writable;
2915
2916   g_object_set (binding->object, binding->property, writable, NULL);
2917 }
2918
2919 /**
2920  * g_settings_bind_writable:
2921  * @settings: a #GSettings object
2922  * @key: the key to bind
2923  * @object: (type GObject.Object):a #GObject
2924  * @property: the name of a boolean property to bind
2925  * @inverted: whether to 'invert' the value
2926  *
2927  * Create a binding between the writability of @key in the
2928  * @settings object and the property @property of @object.
2929  * The property must be boolean; "sensitive" or "visible"
2930  * properties of widgets are the most likely candidates.
2931  *
2932  * Writable bindings are always uni-directional; changes of the
2933  * writability of the setting will be propagated to the object
2934  * property, not the other way.
2935  *
2936  * When the @inverted argument is %TRUE, the binding inverts the
2937  * value as it passes from the setting to the object, i.e. @property
2938  * will be set to %TRUE if the key is <emphasis>not</emphasis>
2939  * writable.
2940  *
2941  * Note that the lifecycle of the binding is tied to the object,
2942  * and that you can have only one binding per object property.
2943  * If you bind the same property twice on the same object, the second
2944  * binding overrides the first one.
2945  *
2946  * Since: 2.26
2947  */
2948 void
2949 g_settings_bind_writable (GSettings   *settings,
2950                           const gchar *key,
2951                           gpointer     object,
2952                           const gchar *property,
2953                           gboolean     inverted)
2954 {
2955   GSettingsWritableBinding *binding;
2956   gchar *detailed_signal;
2957   GParamSpec *pspec;
2958
2959   g_return_if_fail (G_IS_SETTINGS (settings));
2960
2961   pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (object), property);
2962   if (pspec == NULL)
2963     {
2964       g_critical ("g_settings_bind_writable: no property '%s' on class '%s'",
2965                   property, G_OBJECT_TYPE_NAME (object));
2966       return;
2967     }
2968   if ((pspec->flags & G_PARAM_WRITABLE) == 0)
2969     {
2970       g_critical ("g_settings_bind_writable: property '%s' on class '%s' is not writable",
2971                   property, G_OBJECT_TYPE_NAME (object));
2972       return;
2973     }
2974
2975   binding = g_slice_new (GSettingsWritableBinding);
2976   binding->settings = g_object_ref (settings);
2977   binding->object = object;
2978   binding->key = g_intern_string (key);
2979   binding->property = g_intern_string (property);
2980   binding->inverted = inverted;
2981
2982   detailed_signal = g_strdup_printf ("writable-changed::%s", key);
2983   binding->handler_id =
2984     g_signal_connect (settings, detailed_signal,
2985                       G_CALLBACK (g_settings_binding_writable_changed),
2986                       binding);
2987   g_free (detailed_signal);
2988
2989   g_object_set_qdata_full (object, g_settings_binding_quark (property),
2990                            binding, g_settings_writable_binding_free);
2991
2992   g_settings_binding_writable_changed (settings, binding->key, binding);
2993 }
2994
2995 /**
2996  * g_settings_unbind:
2997  * @object: the object
2998  * @property: the property whose binding is removed
2999  *
3000  * Removes an existing binding for @property on @object.
3001  *
3002  * Note that bindings are automatically removed when the
3003  * object is finalized, so it is rarely necessary to call this
3004  * function.
3005  *
3006  * Since: 2.26
3007  */
3008 void
3009 g_settings_unbind (gpointer     object,
3010                    const gchar *property)
3011 {
3012   GQuark binding_quark;
3013
3014   binding_quark = g_settings_binding_quark (property);
3015   g_object_set_qdata (object, binding_quark, NULL);
3016 }
3017
3018 /* Epilogue {{{1 */
3019
3020 /* vim:set foldmethod=marker: */