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