Merge branch '976-disable-assert-checks' into 'master'
[glib.git] / gio / gsettings.c
blob194a73778249f68034e890b1dfcf432c291a93d5
1 /*
2 * Copyright © 2009, 2010 Codethink Limited
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2.1 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
17 * Author: Ryan Lortie <desrt@desrt.ca>
20 /* Prelude {{{1 */
21 #include "config.h"
23 #include <glib.h>
24 #include <glibintl.h>
26 #include "gsettings.h"
28 #include "gdelayedsettingsbackend.h"
29 #include "gsettingsbackendinternal.h"
30 #include "gsettings-mapping.h"
31 #include "gsettingsschema-internal.h"
32 #include "gaction.h"
34 #include "strinfo.c"
36 /**
37 * SECTION:gsettings
38 * @short_description: High-level API for application settings
39 * @include: gio/gio.h
41 * The #GSettings class provides a convenient API for storing and retrieving
42 * application settings.
44 * Reads and writes can be considered to be non-blocking. Reading
45 * settings with #GSettings is typically extremely fast: on
46 * approximately the same order of magnitude (but slower than) a
47 * #GHashTable lookup. Writing settings is also extremely fast in terms
48 * of time to return to your application, but can be extremely expensive
49 * for other threads and other processes. Many settings backends
50 * (including dconf) have lazy initialisation which means in the common
51 * case of the user using their computer without modifying any settings
52 * a lot of work can be avoided. For dconf, the D-Bus service doesn't
53 * even need to be started in this case. For this reason, you should
54 * only ever modify #GSettings keys in response to explicit user action.
55 * Particular care should be paid to ensure that modifications are not
56 * made during startup -- for example, when setting the initial value
57 * of preferences widgets. The built-in g_settings_bind() functionality
58 * is careful not to write settings in response to notify signals as a
59 * result of modifications that it makes to widgets.
61 * When creating a GSettings instance, you have to specify a schema
62 * that describes the keys in your settings and their types and default
63 * values, as well as some other information.
65 * Normally, a schema has a fixed path that determines where the settings
66 * are stored in the conceptual global tree of settings. However, schemas
67 * can also be '[relocatable][gsettings-relocatable]', i.e. not equipped with
68 * a fixed path. This is
69 * useful e.g. when the schema describes an 'account', and you want to be
70 * able to store a arbitrary number of accounts.
72 * Paths must start with and end with a forward slash character ('/')
73 * and must not contain two sequential slash characters. Paths should
74 * be chosen based on a domain name associated with the program or
75 * library to which the settings belong. Examples of paths are
76 * "/org/gtk/settings/file-chooser/" and "/ca/desrt/dconf-editor/".
77 * Paths should not start with "/apps/", "/desktop/" or "/system/" as
78 * they often did in GConf.
80 * Unlike other configuration systems (like GConf), GSettings does not
81 * restrict keys to basic types like strings and numbers. GSettings stores
82 * values as #GVariant, and allows any #GVariantType for keys. Key names
83 * are restricted to lowercase characters, numbers and '-'. Furthermore,
84 * the names must begin with a lowercase character, must not end
85 * with a '-', and must not contain consecutive dashes.
87 * Similar to GConf, the default values in GSettings schemas can be
88 * localized, but the localized values are stored in gettext catalogs
89 * and looked up with the domain that is specified in the
90 * `gettext-domain` attribute of the <schemalist> or <schema>
91 * elements and the category that is specified in the `l10n` attribute of
92 * the <default> element. The string which is translated includes all text in
93 * the <default> element, including any surrounding quotation marks.
95 * The `l10n` attribute must be set to `messages` or `time`, and sets the
96 * [locale category for
97 * translation](https://www.gnu.org/software/gettext/manual/html_node/Aspects.html#index-locale-categories-1).
98 * The `messages` category should be used by default; use `time` for
99 * translatable date or time formats. A translation comment can be added as an
100 * XML comment immediately above the <default> element — it is recommended to
101 * add these comments to aid translators understand the meaning and
102 * implications of the default value. An optional translation `context`
103 * attribute can be set on the <default> element to disambiguate multiple
104 * defaults which use the same string.
106 * For example:
107 * |[
108 * <!-- Translators: A list of words which are not allowed to be typed, in
109 * GVariant serialization syntax.
110 * See: https://developer.gnome.org/glib/stable/gvariant-text.html -->
111 * <default l10n='messages' context='Banned words'>['bad', 'words']</default>
112 * ]|
114 * Translations of default values must remain syntactically valid serialized
115 * #GVariants (e.g. retaining any surrounding quotation marks) or runtime
116 * errors will occur.
118 * GSettings uses schemas in a compact binary form that is created
119 * by the [glib-compile-schemas][glib-compile-schemas]
120 * utility. The input is a schema description in an XML format.
122 * A DTD for the gschema XML format can be found here:
123 * [gschema.dtd](https://git.gnome.org/browse/glib/tree/gio/gschema.dtd)
125 * The [glib-compile-schemas][glib-compile-schemas] tool expects schema
126 * files to have the extension `.gschema.xml`.
128 * At runtime, schemas are identified by their id (as specified in the
129 * id attribute of the <schema> element). The convention for schema
130 * ids is to use a dotted name, similar in style to a D-Bus bus name,
131 * e.g. "org.gnome.SessionManager". In particular, if the settings are
132 * for a specific service that owns a D-Bus bus name, the D-Bus bus name
133 * and schema id should match. For schemas which deal with settings not
134 * associated with one named application, the id should not use
135 * StudlyCaps, e.g. "org.gnome.font-rendering".
137 * In addition to #GVariant types, keys can have types that have
138 * enumerated types. These can be described by a <choice>,
139 * <enum> or <flags> element, as seen in the
140 * [example][schema-enumerated]. The underlying type of such a key
141 * is string, but you can use g_settings_get_enum(), g_settings_set_enum(),
142 * g_settings_get_flags(), g_settings_set_flags() access the numeric values
143 * corresponding to the string value of enum and flags keys.
145 * An example for default value:
146 * |[
147 * <schemalist>
148 * <schema id="org.gtk.Test" path="/org/gtk/Test/" gettext-domain="test">
150 * <key name="greeting" type="s">
151 * <default l10n="messages">"Hello, earthlings"</default>
152 * <summary>A greeting</summary>
153 * <description>
154 * Greeting of the invading martians
155 * </description>
156 * </key>
158 * <key name="box" type="(ii)">
159 * <default>(20,30)</default>
160 * </key>
162 * </schema>
163 * </schemalist>
164 * ]|
166 * An example for ranges, choices and enumerated types:
167 * |[
168 * <schemalist>
170 * <enum id="org.gtk.Test.myenum">
171 * <value nick="first" value="1"/>
172 * <value nick="second" value="2"/>
173 * </enum>
175 * <flags id="org.gtk.Test.myflags">
176 * <value nick="flag1" value="1"/>
177 * <value nick="flag2" value="2"/>
178 * <value nick="flag3" value="4"/>
179 * </flags>
181 * <schema id="org.gtk.Test">
183 * <key name="key-with-range" type="i">
184 * <range min="1" max="100"/>
185 * <default>10</default>
186 * </key>
188 * <key name="key-with-choices" type="s">
189 * <choices>
190 * <choice value='Elisabeth'/>
191 * <choice value='Annabeth'/>
192 * <choice value='Joe'/>
193 * </choices>
194 * <aliases>
195 * <alias value='Anna' target='Annabeth'/>
196 * <alias value='Beth' target='Elisabeth'/>
197 * </aliases>
198 * <default>'Joe'</default>
199 * </key>
201 * <key name='enumerated-key' enum='org.gtk.Test.myenum'>
202 * <default>'first'</default>
203 * </key>
205 * <key name='flags-key' flags='org.gtk.Test.myflags'>
206 * <default>["flag1","flag2"]</default>
207 * </key>
208 * </schema>
209 * </schemalist>
210 * ]|
212 * ## Vendor overrides
214 * Default values are defined in the schemas that get installed by
215 * an application. Sometimes, it is necessary for a vendor or distributor
216 * to adjust these defaults. Since patching the XML source for the schema
217 * is inconvenient and error-prone,
218 * [glib-compile-schemas][glib-compile-schemas] reads so-called vendor
219 * override' files. These are keyfiles in the same directory as the XML
220 * schema sources which can override default values. The schema id serves
221 * as the group name in the key file, and the values are expected in
222 * serialized GVariant form, as in the following example:
223 * |[
224 * [org.gtk.Example]
225 * key1='string'
226 * key2=1.5
227 * ]|
229 * glib-compile-schemas expects schema files to have the extension
230 * `.gschema.override`.
232 * ## Binding
234 * A very convenient feature of GSettings lets you bind #GObject properties
235 * directly to settings, using g_settings_bind(). Once a GObject property
236 * has been bound to a setting, changes on either side are automatically
237 * propagated to the other side. GSettings handles details like mapping
238 * between GObject and GVariant types, and preventing infinite cycles.
240 * This makes it very easy to hook up a preferences dialog to the
241 * underlying settings. To make this even more convenient, GSettings
242 * looks for a boolean property with the name "sensitivity" and
243 * automatically binds it to the writability of the bound setting.
244 * If this 'magic' gets in the way, it can be suppressed with the
245 * #G_SETTINGS_BIND_NO_SENSITIVITY flag.
247 * ## Relocatable schemas # {#gsettings-relocatable}
249 * A relocatable schema is one with no `path` attribute specified on its
250 * <schema> element. By using g_settings_new_with_path(), a #GSettings object
251 * can be instantiated for a relocatable schema, assigning a path to the
252 * instance. Paths passed to g_settings_new_with_path() will typically be
253 * constructed dynamically from a constant prefix plus some form of instance
254 * identifier; but they must still be valid GSettings paths. Paths could also
255 * be constant and used with a globally installed schema originating from a
256 * dependency library.
258 * For example, a relocatable schema could be used to store geometry information
259 * for different windows in an application. If the schema ID was
260 * `org.foo.MyApp.Window`, it could be instantiated for paths
261 * `/org/foo/MyApp/main/`, `/org/foo/MyApp/document-1/`,
262 * `/org/foo/MyApp/document-2/`, etc. If any of the paths are well-known
263 * they can be specified as <child> elements in the parent schema, e.g.:
264 * |[
265 * <schema id="org.foo.MyApp" path="/org/foo/MyApp/">
266 * <child name="main" schema="org.foo.MyApp.Window"/>
267 * </schema>
268 * ]|
270 * ## Build system integration # {#gsettings-build-system}
272 * GSettings comes with autotools integration to simplify compiling and
273 * installing schemas. To add GSettings support to an application, add the
274 * following to your `configure.ac`:
275 * |[
276 * GLIB_GSETTINGS
277 * ]|
279 * In the appropriate `Makefile.am`, use the following snippet to compile and
280 * install the named schema:
281 * |[
282 * gsettings_SCHEMAS = org.foo.MyApp.gschema.xml
283 * EXTRA_DIST = $(gsettings_SCHEMAS)
285 * @GSETTINGS_RULES@
286 * ]|
288 * No changes are needed to the build system to mark a schema XML file for
289 * translation. Assuming it sets the `gettext-domain` attribute, a schema may
290 * be marked for translation by adding it to `POTFILES.in`, assuming gettext
291 * 0.19 is in use (the preferred method for translation):
292 * |[
293 * data/org.foo.MyApp.gschema.xml
294 * ]|
296 * Alternatively, if intltool 0.50.1 is in use:
297 * |[
298 * [type: gettext/gsettings]data/org.foo.MyApp.gschema.xml
299 * ]|
301 * GSettings will use gettext to look up translations for the <summary> and
302 * <description> elements, and also any <default> elements which have a `l10n`
303 * attribute set. Translations must not be included in the `.gschema.xml` file
304 * by the build system, for example by using intltool XML rules with a
305 * `.gschema.xml.in` template.
307 * If an enumerated type defined in a C header file is to be used in a GSettings
308 * schema, it can either be defined manually using an <enum> element in the
309 * schema XML, or it can be extracted automatically from the C header. This
310 * approach is preferred, as it ensures the two representations are always
311 * synchronised. To do so, add the following to the relevant `Makefile.am`:
312 * |[
313 * gsettings_ENUM_NAMESPACE = org.foo.MyApp
314 * gsettings_ENUM_FILES = my-app-enums.h my-app-misc.h
315 * ]|
317 * `gsettings_ENUM_NAMESPACE` specifies the schema namespace for the enum files,
318 * which are specified in `gsettings_ENUM_FILES`. This will generate a
319 * `org.foo.MyApp.enums.xml` file containing the extracted enums, which will be
320 * automatically included in the schema compilation, install and uninstall
321 * rules. It should not be committed to version control or included in
322 * `EXTRA_DIST`.
326 * GSettings:
328 * #GSettings is an opaque data structure and can only be accessed
329 * using the following functions.
332 struct _GSettingsPrivate
334 /* where the signals go... */
335 GMainContext *main_context;
337 GSettingsBackend *backend;
338 GSettingsSchema *schema;
339 gchar *path;
341 GDelayedSettingsBackend *delayed;
344 enum
346 PROP_0,
347 PROP_SCHEMA,
348 PROP_SCHEMA_ID,
349 PROP_BACKEND,
350 PROP_PATH,
351 PROP_HAS_UNAPPLIED,
352 PROP_DELAY_APPLY
355 enum
357 SIGNAL_WRITABLE_CHANGE_EVENT,
358 SIGNAL_WRITABLE_CHANGED,
359 SIGNAL_CHANGE_EVENT,
360 SIGNAL_CHANGED,
361 N_SIGNALS
364 static guint g_settings_signals[N_SIGNALS];
366 G_DEFINE_TYPE_WITH_PRIVATE (GSettings, g_settings, G_TYPE_OBJECT)
368 /* Signals {{{1 */
369 static gboolean
370 g_settings_real_change_event (GSettings *settings,
371 const GQuark *keys,
372 gint n_keys)
374 gint i;
376 if (keys == NULL)
377 keys = g_settings_schema_list (settings->priv->schema, &n_keys);
379 for (i = 0; i < n_keys; i++)
381 const gchar *key = g_quark_to_string (keys[i]);
383 if (g_str_has_suffix (key, "/"))
384 continue;
386 g_signal_emit (settings, g_settings_signals[SIGNAL_CHANGED], keys[i], key);
389 return FALSE;
392 static gboolean
393 g_settings_real_writable_change_event (GSettings *settings,
394 GQuark key)
396 const GQuark *keys = &key;
397 gint n_keys = 1;
398 gint i;
400 if (key == 0)
401 keys = g_settings_schema_list (settings->priv->schema, &n_keys);
403 for (i = 0; i < n_keys; i++)
405 const gchar *key = g_quark_to_string (keys[i]);
407 if (g_str_has_suffix (key, "/"))
408 continue;
410 g_signal_emit (settings, g_settings_signals[SIGNAL_WRITABLE_CHANGED], keys[i], key);
413 return FALSE;
416 static void
417 settings_backend_changed (GObject *target,
418 GSettingsBackend *backend,
419 const gchar *key,
420 gpointer origin_tag)
422 GSettings *settings = G_SETTINGS (target);
423 gboolean ignore_this;
424 gint i;
426 /* We used to assert here:
428 * settings->priv->backend == backend
430 * but it could be the case that a notification is queued for delivery
431 * while someone calls g_settings_delay() (which changes the backend).
433 * Since the delay backend would just pass that straight through
434 * anyway, it doesn't make sense to try to detect this case.
435 * Therefore, we just accept it.
438 for (i = 0; key[i] == settings->priv->path[i]; i++);
440 if (settings->priv->path[i] == '\0' &&
441 g_settings_schema_has_key (settings->priv->schema, key + i))
443 GQuark quark;
445 quark = g_quark_from_string (key + i);
446 g_signal_emit (settings, g_settings_signals[SIGNAL_CHANGE_EVENT],
447 0, &quark, 1, &ignore_this);
451 static void
452 settings_backend_path_changed (GObject *target,
453 GSettingsBackend *backend,
454 const gchar *path,
455 gpointer origin_tag)
457 GSettings *settings = G_SETTINGS (target);
458 gboolean ignore_this;
460 if (g_str_has_prefix (settings->priv->path, path))
461 g_signal_emit (settings, g_settings_signals[SIGNAL_CHANGE_EVENT],
462 0, NULL, 0, &ignore_this);
465 static void
466 settings_backend_keys_changed (GObject *target,
467 GSettingsBackend *backend,
468 const gchar *path,
469 gpointer origin_tag,
470 const gchar * const *items)
472 GSettings *settings = G_SETTINGS (target);
473 gboolean ignore_this;
474 gint i;
476 for (i = 0; settings->priv->path[i] &&
477 settings->priv->path[i] == path[i]; i++);
479 if (path[i] == '\0')
481 GQuark quarks[256];
482 gint j, l = 0;
484 for (j = 0; items[j]; j++)
486 const gchar *item = items[j];
487 gint k;
489 for (k = 0; item[k] == settings->priv->path[i + k]; k++);
491 if (settings->priv->path[i + k] == '\0' &&
492 g_settings_schema_has_key (settings->priv->schema, item + k))
493 quarks[l++] = g_quark_from_string (item + k);
495 /* "256 quarks ought to be enough for anybody!"
496 * If this bites you, I'm sorry. Please file a bug.
498 g_assert (l < 256);
501 if (l > 0)
502 g_signal_emit (settings, g_settings_signals[SIGNAL_CHANGE_EVENT],
503 0, quarks, l, &ignore_this);
507 static void
508 settings_backend_writable_changed (GObject *target,
509 GSettingsBackend *backend,
510 const gchar *key)
512 GSettings *settings = G_SETTINGS (target);
513 gboolean ignore_this;
514 gint i;
516 for (i = 0; key[i] == settings->priv->path[i]; i++);
518 if (settings->priv->path[i] == '\0' &&
519 g_settings_schema_has_key (settings->priv->schema, key + i))
520 g_signal_emit (settings, g_settings_signals[SIGNAL_WRITABLE_CHANGE_EVENT],
521 0, g_quark_from_string (key + i), &ignore_this);
524 static void
525 settings_backend_path_writable_changed (GObject *target,
526 GSettingsBackend *backend,
527 const gchar *path)
529 GSettings *settings = G_SETTINGS (target);
530 gboolean ignore_this;
532 if (g_str_has_prefix (settings->priv->path, path))
533 g_signal_emit (settings, g_settings_signals[SIGNAL_WRITABLE_CHANGE_EVENT],
534 0, (GQuark) 0, &ignore_this);
537 /* Properties, Construction, Destruction {{{1 */
538 static void
539 g_settings_set_property (GObject *object,
540 guint prop_id,
541 const GValue *value,
542 GParamSpec *pspec)
544 GSettings *settings = G_SETTINGS (object);
546 switch (prop_id)
548 case PROP_SCHEMA:
550 GSettingsSchema *schema;
552 schema = g_value_dup_boxed (value);
554 /* we receive a set_property() call for "settings-schema" even
555 * if it was not specified (ie: with NULL value). ->schema
556 * could already be set at this point (ie: via "schema-id").
557 * check for NULL to avoid clobbering the existing value.
559 if (schema != NULL)
561 g_assert (settings->priv->schema == NULL);
562 settings->priv->schema = schema;
565 break;
567 case PROP_SCHEMA_ID:
569 const gchar *schema_id;
571 schema_id = g_value_get_string (value);
573 /* we receive a set_property() call for both "schema" and
574 * "schema-id", even if they are not set. Hopefully only one of
575 * them is non-NULL.
577 if (schema_id != NULL)
579 GSettingsSchemaSource *default_source;
581 g_assert (settings->priv->schema == NULL);
582 default_source = g_settings_schema_source_get_default ();
584 if (default_source == NULL)
585 g_error ("No GSettings schemas are installed on the system");
587 settings->priv->schema = g_settings_schema_source_lookup (default_source, schema_id, TRUE);
589 if (settings->priv->schema == NULL)
590 g_error ("Settings schema '%s' is not installed", schema_id);
593 break;
595 case PROP_PATH:
596 settings->priv->path = g_value_dup_string (value);
597 break;
599 case PROP_BACKEND:
600 settings->priv->backend = g_value_dup_object (value);
601 break;
603 default:
604 g_assert_not_reached ();
608 static void
609 g_settings_get_property (GObject *object,
610 guint prop_id,
611 GValue *value,
612 GParamSpec *pspec)
614 GSettings *settings = G_SETTINGS (object);
616 switch (prop_id)
618 case PROP_SCHEMA:
619 g_value_set_boxed (value, settings->priv->schema);
620 break;
622 case PROP_SCHEMA_ID:
623 g_value_set_string (value, g_settings_schema_get_id (settings->priv->schema));
624 break;
626 case PROP_BACKEND:
627 g_value_set_object (value, settings->priv->backend);
628 break;
630 case PROP_PATH:
631 g_value_set_string (value, settings->priv->path);
632 break;
634 case PROP_HAS_UNAPPLIED:
635 g_value_set_boolean (value, g_settings_get_has_unapplied (settings));
636 break;
638 case PROP_DELAY_APPLY:
639 g_value_set_boolean (value, settings->priv->delayed != NULL);
640 break;
642 default:
643 g_assert_not_reached ();
647 static const GSettingsListenerVTable listener_vtable = {
648 settings_backend_changed,
649 settings_backend_path_changed,
650 settings_backend_keys_changed,
651 settings_backend_writable_changed,
652 settings_backend_path_writable_changed
655 static void
656 g_settings_constructed (GObject *object)
658 GSettings *settings = G_SETTINGS (object);
659 const gchar *schema_path;
661 schema_path = g_settings_schema_get_path (settings->priv->schema);
663 if (settings->priv->path && schema_path && strcmp (settings->priv->path, schema_path) != 0)
664 g_error ("settings object created with schema '%s' and path '%s', but path '%s' is specified by schema",
665 g_settings_schema_get_id (settings->priv->schema), settings->priv->path, schema_path);
667 if (settings->priv->path == NULL)
669 if (schema_path == NULL)
670 g_error ("attempting to create schema '%s' without a path",
671 g_settings_schema_get_id (settings->priv->schema));
673 settings->priv->path = g_strdup (schema_path);
676 if (settings->priv->backend == NULL)
677 settings->priv->backend = g_settings_backend_get_default ();
679 g_settings_backend_watch (settings->priv->backend,
680 &listener_vtable, G_OBJECT (settings),
681 settings->priv->main_context);
682 g_settings_backend_subscribe (settings->priv->backend,
683 settings->priv->path);
686 static void
687 g_settings_finalize (GObject *object)
689 GSettings *settings = G_SETTINGS (object);
691 g_settings_backend_unsubscribe (settings->priv->backend,
692 settings->priv->path);
693 g_main_context_unref (settings->priv->main_context);
694 g_object_unref (settings->priv->backend);
695 g_settings_schema_unref (settings->priv->schema);
696 g_free (settings->priv->path);
698 G_OBJECT_CLASS (g_settings_parent_class)->finalize (object);
701 static void
702 g_settings_init (GSettings *settings)
704 settings->priv = g_settings_get_instance_private (settings);
705 settings->priv->main_context = g_main_context_ref_thread_default ();
708 static void
709 g_settings_class_init (GSettingsClass *class)
711 GObjectClass *object_class = G_OBJECT_CLASS (class);
713 class->writable_change_event = g_settings_real_writable_change_event;
714 class->change_event = g_settings_real_change_event;
716 object_class->set_property = g_settings_set_property;
717 object_class->get_property = g_settings_get_property;
718 object_class->constructed = g_settings_constructed;
719 object_class->finalize = g_settings_finalize;
722 * GSettings::changed:
723 * @settings: the object on which the signal was emitted
724 * @key: the name of the key that changed
726 * The "changed" signal is emitted when a key has potentially changed.
727 * You should call one of the g_settings_get() calls to check the new
728 * value.
730 * This signal supports detailed connections. You can connect to the
731 * detailed signal "changed::x" in order to only receive callbacks
732 * when key "x" changes.
734 * Note that @settings only emits this signal if you have read @key at
735 * least once while a signal handler was already connected for @key.
737 g_settings_signals[SIGNAL_CHANGED] =
738 g_signal_new (I_("changed"), G_TYPE_SETTINGS,
739 G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
740 G_STRUCT_OFFSET (GSettingsClass, changed),
741 NULL, NULL, g_cclosure_marshal_VOID__STRING, G_TYPE_NONE,
742 1, G_TYPE_STRING | G_SIGNAL_TYPE_STATIC_SCOPE);
745 * GSettings::change-event:
746 * @settings: the object on which the signal was emitted
747 * @keys: (array length=n_keys) (element-type GQuark) (nullable):
748 * an array of #GQuarks for the changed keys, or %NULL
749 * @n_keys: the length of the @keys array, or 0
751 * The "change-event" signal is emitted once per change event that
752 * affects this settings object. You should connect to this signal
753 * only if you are interested in viewing groups of changes before they
754 * are split out into multiple emissions of the "changed" signal.
755 * For most use cases it is more appropriate to use the "changed" signal.
757 * In the event that the change event applies to one or more specified
758 * keys, @keys will be an array of #GQuark of length @n_keys. In the
759 * event that the change event applies to the #GSettings object as a
760 * whole (ie: potentially every key has been changed) then @keys will
761 * be %NULL and @n_keys will be 0.
763 * The default handler for this signal invokes the "changed" signal
764 * for each affected key. If any other connected handler returns
765 * %TRUE then this default functionality will be suppressed.
767 * Returns: %TRUE to stop other handlers from being invoked for the
768 * event. FALSE to propagate the event further.
770 g_settings_signals[SIGNAL_CHANGE_EVENT] =
771 g_signal_new (I_("change-event"), G_TYPE_SETTINGS,
772 G_SIGNAL_RUN_LAST,
773 G_STRUCT_OFFSET (GSettingsClass, change_event),
774 g_signal_accumulator_true_handled, NULL,
775 NULL,
776 G_TYPE_BOOLEAN, 2, G_TYPE_POINTER, G_TYPE_INT);
779 * GSettings::writable-changed:
780 * @settings: the object on which the signal was emitted
781 * @key: the key
783 * The "writable-changed" signal is emitted when the writability of a
784 * key has potentially changed. You should call
785 * g_settings_is_writable() in order to determine the new status.
787 * This signal supports detailed connections. You can connect to the
788 * detailed signal "writable-changed::x" in order to only receive
789 * callbacks when the writability of "x" changes.
791 g_settings_signals[SIGNAL_WRITABLE_CHANGED] =
792 g_signal_new (I_("writable-changed"), G_TYPE_SETTINGS,
793 G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
794 G_STRUCT_OFFSET (GSettingsClass, writable_changed),
795 NULL, NULL, g_cclosure_marshal_VOID__STRING, G_TYPE_NONE,
796 1, G_TYPE_STRING | G_SIGNAL_TYPE_STATIC_SCOPE);
799 * GSettings::writable-change-event:
800 * @settings: the object on which the signal was emitted
801 * @key: the quark of the key, or 0
803 * The "writable-change-event" signal is emitted once per writability
804 * change event that affects this settings object. You should connect
805 * to this signal if you are interested in viewing groups of changes
806 * before they are split out into multiple emissions of the
807 * "writable-changed" signal. For most use cases it is more
808 * appropriate to use the "writable-changed" signal.
810 * In the event that the writability change applies only to a single
811 * key, @key will be set to the #GQuark for that key. In the event
812 * that the writability change affects the entire settings object,
813 * @key will be 0.
815 * The default handler for this signal invokes the "writable-changed"
816 * and "changed" signals for each affected key. This is done because
817 * changes in writability might also imply changes in value (if for
818 * example, a new mandatory setting is introduced). If any other
819 * connected handler returns %TRUE then this default functionality
820 * will be suppressed.
822 * Returns: %TRUE to stop other handlers from being invoked for the
823 * event. FALSE to propagate the event further.
825 g_settings_signals[SIGNAL_WRITABLE_CHANGE_EVENT] =
826 g_signal_new (I_("writable-change-event"), G_TYPE_SETTINGS,
827 G_SIGNAL_RUN_LAST,
828 G_STRUCT_OFFSET (GSettingsClass, writable_change_event),
829 g_signal_accumulator_true_handled, NULL,
830 NULL, G_TYPE_BOOLEAN, 1, G_TYPE_UINT);
833 * GSettings:backend:
835 * The name of the context that the settings are stored in.
837 g_object_class_install_property (object_class, PROP_BACKEND,
838 g_param_spec_object ("backend",
839 P_("GSettingsBackend"),
840 P_("The GSettingsBackend for this settings object"),
841 G_TYPE_SETTINGS_BACKEND, G_PARAM_CONSTRUCT_ONLY |
842 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
845 * GSettings:settings-schema:
847 * The #GSettingsSchema describing the types of keys for this
848 * #GSettings object.
850 * Ideally, this property would be called 'schema'. #GSettingsSchema
851 * has only existed since version 2.32, however, and before then the
852 * 'schema' property was used to refer to the ID of the schema rather
853 * than the schema itself. Take care.
855 g_object_class_install_property (object_class, PROP_SCHEMA,
856 g_param_spec_boxed ("settings-schema",
857 P_("schema"),
858 P_("The GSettingsSchema for this settings object"),
859 G_TYPE_SETTINGS_SCHEMA,
860 G_PARAM_CONSTRUCT_ONLY |
861 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
864 * GSettings:schema:
866 * The name of the schema that describes the types of keys
867 * for this #GSettings object.
869 * The type of this property is *not* #GSettingsSchema.
870 * #GSettingsSchema has only existed since version 2.32 and
871 * unfortunately this name was used in previous versions to refer to
872 * the schema ID rather than the schema itself. Take care to use the
873 * 'settings-schema' property if you wish to pass in a
874 * #GSettingsSchema.
876 * Deprecated:2.32:Use the 'schema-id' property instead. In a future
877 * version, this property may instead refer to a #GSettingsSchema.
879 g_object_class_install_property (object_class, PROP_SCHEMA_ID,
880 g_param_spec_string ("schema",
881 P_("Schema name"),
882 P_("The name of the schema for this settings object"),
883 NULL,
884 G_PARAM_CONSTRUCT_ONLY |
885 G_PARAM_DEPRECATED | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
888 * GSettings:schema-id:
890 * The name of the schema that describes the types of keys
891 * for this #GSettings object.
893 g_object_class_install_property (object_class, PROP_SCHEMA_ID,
894 g_param_spec_string ("schema-id",
895 P_("Schema name"),
896 P_("The name of the schema for this settings object"),
897 NULL,
898 G_PARAM_CONSTRUCT_ONLY |
899 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
902 * GSettings:path:
904 * The path within the backend where the settings are stored.
906 g_object_class_install_property (object_class, PROP_PATH,
907 g_param_spec_string ("path",
908 P_("Base path"),
909 P_("The path within the backend where the settings are"),
910 NULL,
911 G_PARAM_CONSTRUCT_ONLY |
912 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
915 * GSettings:has-unapplied:
917 * If this property is %TRUE, the #GSettings object has outstanding
918 * changes that will be applied when g_settings_apply() is called.
920 g_object_class_install_property (object_class, PROP_HAS_UNAPPLIED,
921 g_param_spec_boolean ("has-unapplied",
922 P_("Has unapplied changes"),
923 P_("TRUE if there are outstanding changes to apply()"),
924 FALSE,
925 G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
928 * GSettings:delay-apply:
930 * Whether the #GSettings object is in 'delay-apply' mode. See
931 * g_settings_delay() for details.
933 * Since: 2.28
935 g_object_class_install_property (object_class, PROP_DELAY_APPLY,
936 g_param_spec_boolean ("delay-apply",
937 P_("Delay-apply mode"),
938 P_("Whether this settings object is in “delay-apply” mode"),
939 FALSE,
940 G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
943 /* Construction (new, new_with_path, etc.) {{{1 */
945 * g_settings_new:
946 * @schema_id: the id of the schema
948 * Creates a new #GSettings object with the schema specified by
949 * @schema_id.
951 * Signals on the newly created #GSettings object will be dispatched
952 * via the thread-default #GMainContext in effect at the time of the
953 * call to g_settings_new(). The new #GSettings will hold a reference
954 * on the context. See g_main_context_push_thread_default().
956 * Returns: a new #GSettings object
958 * Since: 2.26
960 GSettings *
961 g_settings_new (const gchar *schema_id)
963 g_return_val_if_fail (schema_id != NULL, NULL);
965 return g_object_new (G_TYPE_SETTINGS,
966 "schema-id", schema_id,
967 NULL);
970 static gboolean
971 path_is_valid (const gchar *path)
973 if (!path)
974 return FALSE;
976 if (path[0] != '/')
977 return FALSE;
979 if (!g_str_has_suffix (path, "/"))
980 return FALSE;
982 return strstr (path, "//") == NULL;
986 * g_settings_new_with_path:
987 * @schema_id: the id of the schema
988 * @path: the path to use
990 * Creates a new #GSettings object with the relocatable schema specified
991 * by @schema_id and a given path.
993 * You only need to do this if you want to directly create a settings
994 * object with a schema that doesn't have a specified path of its own.
995 * That's quite rare.
997 * It is a programmer error to call this function for a schema that
998 * has an explicitly specified path.
1000 * It is a programmer error if @path is not a valid path. A valid path
1001 * begins and ends with '/' and does not contain two consecutive '/'
1002 * characters.
1004 * Returns: a new #GSettings object
1006 * Since: 2.26
1008 GSettings *
1009 g_settings_new_with_path (const gchar *schema_id,
1010 const gchar *path)
1012 g_return_val_if_fail (schema_id != NULL, NULL);
1013 g_return_val_if_fail (path_is_valid (path), NULL);
1015 return g_object_new (G_TYPE_SETTINGS,
1016 "schema-id", schema_id,
1017 "path", path,
1018 NULL);
1022 * g_settings_new_with_backend:
1023 * @schema_id: the id of the schema
1024 * @backend: the #GSettingsBackend to use
1026 * Creates a new #GSettings object with the schema specified by
1027 * @schema_id and a given #GSettingsBackend.
1029 * Creating a #GSettings object with a different backend allows accessing
1030 * settings from a database other than the usual one. For example, it may make
1031 * sense to pass a backend corresponding to the "defaults" settings database on
1032 * the system to get a settings object that modifies the system default
1033 * settings instead of the settings for this user.
1035 * Returns: a new #GSettings object
1037 * Since: 2.26
1039 GSettings *
1040 g_settings_new_with_backend (const gchar *schema_id,
1041 GSettingsBackend *backend)
1043 g_return_val_if_fail (schema_id != NULL, NULL);
1044 g_return_val_if_fail (G_IS_SETTINGS_BACKEND (backend), NULL);
1046 return g_object_new (G_TYPE_SETTINGS,
1047 "schema-id", schema_id,
1048 "backend", backend,
1049 NULL);
1053 * g_settings_new_with_backend_and_path:
1054 * @schema_id: the id of the schema
1055 * @backend: the #GSettingsBackend to use
1056 * @path: the path to use
1058 * Creates a new #GSettings object with the schema specified by
1059 * @schema_id and a given #GSettingsBackend and path.
1061 * This is a mix of g_settings_new_with_backend() and
1062 * g_settings_new_with_path().
1064 * Returns: a new #GSettings object
1066 * Since: 2.26
1068 GSettings *
1069 g_settings_new_with_backend_and_path (const gchar *schema_id,
1070 GSettingsBackend *backend,
1071 const gchar *path)
1073 g_return_val_if_fail (schema_id != NULL, NULL);
1074 g_return_val_if_fail (G_IS_SETTINGS_BACKEND (backend), NULL);
1075 g_return_val_if_fail (path_is_valid (path), NULL);
1077 return g_object_new (G_TYPE_SETTINGS,
1078 "schema-id", schema_id,
1079 "backend", backend,
1080 "path", path,
1081 NULL);
1085 * g_settings_new_full:
1086 * @schema: a #GSettingsSchema
1087 * @backend: (nullable): a #GSettingsBackend
1088 * @path: (nullable): the path to use
1090 * Creates a new #GSettings object with a given schema, backend and
1091 * path.
1093 * It should be extremely rare that you ever want to use this function.
1094 * It is made available for advanced use-cases (such as plugin systems
1095 * that want to provide access to schemas loaded from custom locations,
1096 * etc).
1098 * At the most basic level, a #GSettings object is a pure composition of
1099 * 4 things: a #GSettingsSchema, a #GSettingsBackend, a path within that
1100 * backend, and a #GMainContext to which signals are dispatched.
1102 * This constructor therefore gives you full control over constructing
1103 * #GSettings instances. The first 3 parameters are given directly as
1104 * @schema, @backend and @path, and the main context is taken from the
1105 * thread-default (as per g_settings_new()).
1107 * If @backend is %NULL then the default backend is used.
1109 * If @path is %NULL then the path from the schema is used. It is an
1110 * error if @path is %NULL and the schema has no path of its own or if
1111 * @path is non-%NULL and not equal to the path that the schema does
1112 * have.
1114 * Returns: a new #GSettings object
1116 * Since: 2.32
1118 GSettings *
1119 g_settings_new_full (GSettingsSchema *schema,
1120 GSettingsBackend *backend,
1121 const gchar *path)
1123 g_return_val_if_fail (schema != NULL, NULL);
1124 g_return_val_if_fail (backend == NULL || G_IS_SETTINGS_BACKEND (backend), NULL);
1125 g_return_val_if_fail (path == NULL || path_is_valid (path), NULL);
1127 return g_object_new (G_TYPE_SETTINGS,
1128 "settings-schema", schema,
1129 "backend", backend,
1130 "path", path,
1131 NULL);
1134 /* Internal read/write utilities {{{1 */
1135 static gboolean
1136 g_settings_write_to_backend (GSettings *settings,
1137 GSettingsSchemaKey *key,
1138 GVariant *value)
1140 gboolean success;
1141 gchar *path;
1143 path = g_strconcat (settings->priv->path, key->name, NULL);
1144 success = g_settings_backend_write (settings->priv->backend, path, value, NULL);
1145 g_free (path);
1147 return success;
1150 static GVariant *
1151 g_settings_read_from_backend (GSettings *settings,
1152 GSettingsSchemaKey *key,
1153 gboolean user_value_only,
1154 gboolean default_value)
1156 GVariant *value;
1157 GVariant *fixup;
1158 gchar *path;
1160 path = g_strconcat (settings->priv->path, key->name, NULL);
1161 if (user_value_only)
1162 value = g_settings_backend_read_user_value (settings->priv->backend, path, key->type);
1163 else
1164 value = g_settings_backend_read (settings->priv->backend, path, key->type, default_value);
1165 g_free (path);
1167 if (value != NULL)
1169 fixup = g_settings_schema_key_range_fixup (key, value);
1170 g_variant_unref (value);
1172 else
1173 fixup = NULL;
1175 return fixup;
1178 /* Public Get/Set API {{{1 (get, get_value, set, set_value, get_mapped) */
1180 * g_settings_get_value:
1181 * @settings: a #GSettings object
1182 * @key: the key to get the value for
1184 * Gets the value that is stored in @settings for @key.
1186 * It is a programmer error to give a @key that isn't contained in the
1187 * schema for @settings.
1189 * Returns: a new #GVariant
1191 * Since: 2.26
1193 GVariant *
1194 g_settings_get_value (GSettings *settings,
1195 const gchar *key)
1197 GSettingsSchemaKey skey;
1198 GVariant *value;
1200 g_return_val_if_fail (G_IS_SETTINGS (settings), NULL);
1201 g_return_val_if_fail (key != NULL, NULL);
1203 g_settings_schema_key_init (&skey, settings->priv->schema, key);
1204 value = g_settings_read_from_backend (settings, &skey, FALSE, FALSE);
1206 if (value == NULL)
1207 value = g_settings_schema_key_get_default_value (&skey);
1209 g_settings_schema_key_clear (&skey);
1211 return value;
1215 * g_settings_get_user_value:
1216 * @settings: a #GSettings object
1217 * @key: the key to get the user value for
1219 * Checks the "user value" of a key, if there is one.
1221 * The user value of a key is the last value that was set by the user.
1223 * After calling g_settings_reset() this function should always return
1224 * %NULL (assuming something is not wrong with the system
1225 * configuration).
1227 * It is possible that g_settings_get_value() will return a different
1228 * value than this function. This can happen in the case that the user
1229 * set a value for a key that was subsequently locked down by the system
1230 * administrator -- this function will return the user's old value.
1232 * This function may be useful for adding a "reset" option to a UI or
1233 * for providing indication that a particular value has been changed.
1235 * It is a programmer error to give a @key that isn't contained in the
1236 * schema for @settings.
1238 * Returns: (nullable) (transfer full): the user's value, if set
1240 * Since: 2.40
1242 GVariant *
1243 g_settings_get_user_value (GSettings *settings,
1244 const gchar *key)
1246 GSettingsSchemaKey skey;
1247 GVariant *value;
1249 g_return_val_if_fail (G_IS_SETTINGS (settings), NULL);
1250 g_return_val_if_fail (key != NULL, NULL);
1252 g_settings_schema_key_init (&skey, settings->priv->schema, key);
1253 value = g_settings_read_from_backend (settings, &skey, TRUE, FALSE);
1254 g_settings_schema_key_clear (&skey);
1256 return value;
1260 * g_settings_get_default_value:
1261 * @settings: a #GSettings object
1262 * @key: the key to get the default value for
1264 * Gets the "default value" of a key.
1266 * This is the value that would be read if g_settings_reset() were to be
1267 * called on the key.
1269 * Note that this may be a different value than returned by
1270 * g_settings_schema_key_get_default_value() if the system administrator
1271 * has provided a default value.
1273 * Comparing the return values of g_settings_get_default_value() and
1274 * g_settings_get_value() is not sufficient for determining if a value
1275 * has been set because the user may have explicitly set the value to
1276 * something that happens to be equal to the default. The difference
1277 * here is that if the default changes in the future, the user's key
1278 * will still be set.
1280 * This function may be useful for adding an indication to a UI of what
1281 * the default value was before the user set it.
1283 * It is a programmer error to give a @key that isn't contained in the
1284 * schema for @settings.
1286 * Returns: (nullable) (transfer full): the default value
1288 * Since: 2.40
1290 GVariant *
1291 g_settings_get_default_value (GSettings *settings,
1292 const gchar *key)
1294 GSettingsSchemaKey skey;
1295 GVariant *value;
1297 g_return_val_if_fail (G_IS_SETTINGS (settings), NULL);
1298 g_return_val_if_fail (key != NULL, NULL);
1300 g_settings_schema_key_init (&skey, settings->priv->schema, key);
1301 value = g_settings_read_from_backend (settings, &skey, FALSE, TRUE);
1303 if (value == NULL)
1304 value = g_settings_schema_key_get_default_value (&skey);
1306 g_settings_schema_key_clear (&skey);
1308 return value;
1312 * g_settings_get_enum:
1313 * @settings: a #GSettings object
1314 * @key: the key to get the value for
1316 * Gets the value that is stored in @settings for @key and converts it
1317 * to the enum value that it represents.
1319 * In order to use this function the type of the value must be a string
1320 * and it must be marked in the schema file as an enumerated type.
1322 * It is a programmer error to give a @key that isn't contained in the
1323 * schema for @settings or is not marked as an enumerated type.
1325 * If the value stored in the configuration database is not a valid
1326 * value for the enumerated type then this function will return the
1327 * default value.
1329 * Returns: the enum value
1331 * Since: 2.26
1333 gint
1334 g_settings_get_enum (GSettings *settings,
1335 const gchar *key)
1337 GSettingsSchemaKey skey;
1338 GVariant *value;
1339 gint result;
1341 g_return_val_if_fail (G_IS_SETTINGS (settings), -1);
1342 g_return_val_if_fail (key != NULL, -1);
1344 g_settings_schema_key_init (&skey, settings->priv->schema, key);
1346 if (!skey.is_enum)
1348 g_critical ("g_settings_get_enum() called on key '%s' which is not "
1349 "associated with an enumerated type", skey.name);
1350 g_settings_schema_key_clear (&skey);
1351 return -1;
1354 value = g_settings_read_from_backend (settings, &skey, FALSE, FALSE);
1356 if (value == NULL)
1357 value = g_settings_schema_key_get_default_value (&skey);
1359 result = g_settings_schema_key_to_enum (&skey, value);
1360 g_settings_schema_key_clear (&skey);
1361 g_variant_unref (value);
1363 return result;
1367 * g_settings_set_enum:
1368 * @settings: a #GSettings object
1369 * @key: a key, within @settings
1370 * @value: an enumerated value
1372 * Looks up the enumerated type nick for @value and writes it to @key,
1373 * within @settings.
1375 * It is a programmer error to give a @key that isn't contained in the
1376 * schema for @settings or is not marked as an enumerated type, or for
1377 * @value not to be a valid value for the named type.
1379 * After performing the write, accessing @key directly with
1380 * g_settings_get_string() will return the 'nick' associated with
1381 * @value.
1383 * Returns: %TRUE, if the set succeeds
1385 gboolean
1386 g_settings_set_enum (GSettings *settings,
1387 const gchar *key,
1388 gint value)
1390 GSettingsSchemaKey skey;
1391 GVariant *variant;
1392 gboolean success;
1394 g_return_val_if_fail (G_IS_SETTINGS (settings), FALSE);
1395 g_return_val_if_fail (key != NULL, FALSE);
1397 g_settings_schema_key_init (&skey, settings->priv->schema, key);
1399 if (!skey.is_enum)
1401 g_critical ("g_settings_set_enum() called on key '%s' which is not "
1402 "associated with an enumerated type", skey.name);
1403 return FALSE;
1406 if (!(variant = g_settings_schema_key_from_enum (&skey, value)))
1408 g_critical ("g_settings_set_enum(): invalid enum value %d for key '%s' "
1409 "in schema '%s'. Doing nothing.", value, skey.name,
1410 g_settings_schema_get_id (skey.schema));
1411 g_settings_schema_key_clear (&skey);
1412 return FALSE;
1415 success = g_settings_write_to_backend (settings, &skey, variant);
1416 g_settings_schema_key_clear (&skey);
1418 return success;
1422 * g_settings_get_flags:
1423 * @settings: a #GSettings object
1424 * @key: the key to get the value for
1426 * Gets the value that is stored in @settings for @key and converts it
1427 * to the flags value that it represents.
1429 * In order to use this function the type of the value must be an array
1430 * of strings and it must be marked in the schema file as an flags type.
1432 * It is a programmer error to give a @key that isn't contained in the
1433 * schema for @settings or is not marked as a flags type.
1435 * If the value stored in the configuration database is not a valid
1436 * value for the flags type then this function will return the default
1437 * value.
1439 * Returns: the flags value
1441 * Since: 2.26
1443 guint
1444 g_settings_get_flags (GSettings *settings,
1445 const gchar *key)
1447 GSettingsSchemaKey skey;
1448 GVariant *value;
1449 guint result;
1451 g_return_val_if_fail (G_IS_SETTINGS (settings), -1);
1452 g_return_val_if_fail (key != NULL, -1);
1454 g_settings_schema_key_init (&skey, settings->priv->schema, key);
1456 if (!skey.is_flags)
1458 g_critical ("g_settings_get_flags() called on key '%s' which is not "
1459 "associated with a flags type", skey.name);
1460 g_settings_schema_key_clear (&skey);
1461 return -1;
1464 value = g_settings_read_from_backend (settings, &skey, FALSE, FALSE);
1466 if (value == NULL)
1467 value = g_settings_schema_key_get_default_value (&skey);
1469 result = g_settings_schema_key_to_flags (&skey, value);
1470 g_settings_schema_key_clear (&skey);
1471 g_variant_unref (value);
1473 return result;
1477 * g_settings_set_flags:
1478 * @settings: a #GSettings object
1479 * @key: a key, within @settings
1480 * @value: a flags value
1482 * Looks up the flags type nicks for the bits specified by @value, puts
1483 * them in an array of strings and writes the array to @key, within
1484 * @settings.
1486 * It is a programmer error to give a @key that isn't contained in the
1487 * schema for @settings or is not marked as a flags type, or for @value
1488 * to contain any bits that are not value for the named type.
1490 * After performing the write, accessing @key directly with
1491 * g_settings_get_strv() will return an array of 'nicks'; one for each
1492 * bit in @value.
1494 * Returns: %TRUE, if the set succeeds
1496 gboolean
1497 g_settings_set_flags (GSettings *settings,
1498 const gchar *key,
1499 guint value)
1501 GSettingsSchemaKey skey;
1502 GVariant *variant;
1503 gboolean success;
1505 g_return_val_if_fail (G_IS_SETTINGS (settings), FALSE);
1506 g_return_val_if_fail (key != NULL, FALSE);
1508 g_settings_schema_key_init (&skey, settings->priv->schema, key);
1510 if (!skey.is_flags)
1512 g_critical ("g_settings_set_flags() called on key '%s' which is not "
1513 "associated with a flags type", skey.name);
1514 return FALSE;
1517 if (!(variant = g_settings_schema_key_from_flags (&skey, value)))
1519 g_critical ("g_settings_set_flags(): invalid flags value 0x%08x "
1520 "for key '%s' in schema '%s'. Doing nothing.",
1521 value, skey.name, g_settings_schema_get_id (skey.schema));
1522 g_settings_schema_key_clear (&skey);
1523 return FALSE;
1526 success = g_settings_write_to_backend (settings, &skey, variant);
1527 g_settings_schema_key_clear (&skey);
1529 return success;
1533 * g_settings_set_value:
1534 * @settings: a #GSettings object
1535 * @key: the name of the key to set
1536 * @value: a #GVariant of the correct type
1538 * Sets @key in @settings to @value.
1540 * It is a programmer error to give a @key that isn't contained in the
1541 * schema for @settings or for @value to have the incorrect type, per
1542 * the schema.
1544 * If @value is floating then this function consumes the reference.
1546 * Returns: %TRUE if setting the key succeeded,
1547 * %FALSE if the key was not writable
1549 * Since: 2.26
1551 gboolean
1552 g_settings_set_value (GSettings *settings,
1553 const gchar *key,
1554 GVariant *value)
1556 GSettingsSchemaKey skey;
1557 gboolean success;
1559 g_return_val_if_fail (G_IS_SETTINGS (settings), FALSE);
1560 g_return_val_if_fail (key != NULL, FALSE);
1562 g_variant_ref_sink (value);
1563 g_settings_schema_key_init (&skey, settings->priv->schema, key);
1565 if (!g_settings_schema_key_type_check (&skey, value))
1567 g_critical ("g_settings_set_value: key '%s' in '%s' expects type '%s', but a GVariant of type '%s' was given",
1568 key,
1569 g_settings_schema_get_id (settings->priv->schema),
1570 g_variant_type_peek_string (skey.type),
1571 g_variant_get_type_string (value));
1572 success = FALSE;
1574 else if (!g_settings_schema_key_range_check (&skey, value))
1576 g_warning ("g_settings_set_value: value for key '%s' in schema '%s' "
1577 "is outside of valid range",
1578 key,
1579 g_settings_schema_get_id (settings->priv->schema));
1580 success = FALSE;
1582 else
1584 success = g_settings_write_to_backend (settings, &skey, value);
1587 g_settings_schema_key_clear (&skey);
1588 g_variant_unref (value);
1590 return success;
1594 * g_settings_get:
1595 * @settings: a #GSettings object
1596 * @key: the key to get the value for
1597 * @format: a #GVariant format string
1598 * @...: arguments as per @format
1600 * Gets the value that is stored at @key in @settings.
1602 * A convenience function that combines g_settings_get_value() with
1603 * g_variant_get().
1605 * It is a programmer error to give a @key that isn't contained in the
1606 * schema for @settings or for the #GVariantType of @format to mismatch
1607 * the type given in the schema.
1609 * Since: 2.26
1611 void
1612 g_settings_get (GSettings *settings,
1613 const gchar *key,
1614 const gchar *format,
1615 ...)
1617 GVariant *value;
1618 va_list ap;
1620 value = g_settings_get_value (settings, key);
1622 if (strchr (format, '&'))
1624 g_critical ("%s: the format string may not contain '&' (key '%s' from schema '%s'). "
1625 "This call will probably stop working with a future version of glib.",
1626 G_STRFUNC, key, g_settings_schema_get_id (settings->priv->schema));
1629 va_start (ap, format);
1630 g_variant_get_va (value, format, NULL, &ap);
1631 va_end (ap);
1633 g_variant_unref (value);
1637 * g_settings_set:
1638 * @settings: a #GSettings object
1639 * @key: the name of the key to set
1640 * @format: a #GVariant format string
1641 * @...: arguments as per @format
1643 * Sets @key in @settings to @value.
1645 * A convenience function that combines g_settings_set_value() with
1646 * g_variant_new().
1648 * It is a programmer error to give a @key that isn't contained in the
1649 * schema for @settings or for the #GVariantType of @format to mismatch
1650 * the type given in the schema.
1652 * Returns: %TRUE if setting the key succeeded,
1653 * %FALSE if the key was not writable
1655 * Since: 2.26
1657 gboolean
1658 g_settings_set (GSettings *settings,
1659 const gchar *key,
1660 const gchar *format,
1661 ...)
1663 GVariant *value;
1664 va_list ap;
1666 va_start (ap, format);
1667 value = g_variant_new_va (format, NULL, &ap);
1668 va_end (ap);
1670 return g_settings_set_value (settings, key, value);
1674 * g_settings_get_mapped:
1675 * @settings: a #GSettings object
1676 * @key: the key to get the value for
1677 * @mapping: (scope call): the function to map the value in the
1678 * settings database to the value used by the application
1679 * @user_data: user data for @mapping
1681 * Gets the value that is stored at @key in @settings, subject to
1682 * application-level validation/mapping.
1684 * You should use this function when the application needs to perform
1685 * some processing on the value of the key (for example, parsing). The
1686 * @mapping function performs that processing. If the function
1687 * indicates that the processing was unsuccessful (due to a parse error,
1688 * for example) then the mapping is tried again with another value.
1690 * This allows a robust 'fall back to defaults' behaviour to be
1691 * implemented somewhat automatically.
1693 * The first value that is tried is the user's setting for the key. If
1694 * the mapping function fails to map this value, other values may be
1695 * tried in an unspecified order (system or site defaults, translated
1696 * schema default values, untranslated schema default values, etc).
1698 * If the mapping function fails for all possible values, one additional
1699 * attempt is made: the mapping function is called with a %NULL value.
1700 * If the mapping function still indicates failure at this point then
1701 * the application will be aborted.
1703 * The result parameter for the @mapping function is pointed to a
1704 * #gpointer which is initially set to %NULL. The same pointer is given
1705 * to each invocation of @mapping. The final value of that #gpointer is
1706 * what is returned by this function. %NULL is valid; it is returned
1707 * just as any other value would be.
1709 * Returns: (transfer full): the result, which may be %NULL
1711 gpointer
1712 g_settings_get_mapped (GSettings *settings,
1713 const gchar *key,
1714 GSettingsGetMapping mapping,
1715 gpointer user_data)
1717 gpointer result = NULL;
1718 GSettingsSchemaKey skey;
1719 GVariant *value;
1720 gboolean okay;
1722 g_return_val_if_fail (G_IS_SETTINGS (settings), NULL);
1723 g_return_val_if_fail (key != NULL, NULL);
1724 g_return_val_if_fail (mapping != NULL, NULL);
1726 g_settings_schema_key_init (&skey, settings->priv->schema, key);
1728 if ((value = g_settings_read_from_backend (settings, &skey, FALSE, FALSE)))
1730 okay = mapping (value, &result, user_data);
1731 g_variant_unref (value);
1732 if (okay) goto okay;
1735 if ((value = g_settings_schema_key_get_translated_default (&skey)))
1737 okay = mapping (value, &result, user_data);
1738 g_variant_unref (value);
1739 if (okay) goto okay;
1742 if ((value = g_settings_schema_key_get_per_desktop_default (&skey)))
1744 okay = mapping (value, &result, user_data);
1745 g_variant_unref (value);
1746 if (okay) goto okay;
1749 if (mapping (skey.default_value, &result, user_data))
1750 goto okay;
1752 if (!mapping (NULL, &result, user_data))
1753 g_error ("The mapping function given to g_settings_get_mapped() for key "
1754 "'%s' in schema '%s' returned FALSE when given a NULL value.",
1755 key, g_settings_schema_get_id (settings->priv->schema));
1757 okay:
1758 g_settings_schema_key_clear (&skey);
1760 return result;
1763 /* Convenience API (get, set_string, int, double, boolean, strv) {{{1 */
1765 * g_settings_get_string:
1766 * @settings: a #GSettings object
1767 * @key: the key to get the value for
1769 * Gets the value that is stored at @key in @settings.
1771 * A convenience variant of g_settings_get() for strings.
1773 * It is a programmer error to give a @key that isn't specified as
1774 * having a string type in the schema for @settings.
1776 * Returns: a newly-allocated string
1778 * Since: 2.26
1780 gchar *
1781 g_settings_get_string (GSettings *settings,
1782 const gchar *key)
1784 GVariant *value;
1785 gchar *result;
1787 value = g_settings_get_value (settings, key);
1788 result = g_variant_dup_string (value, NULL);
1789 g_variant_unref (value);
1791 return result;
1795 * g_settings_set_string:
1796 * @settings: a #GSettings object
1797 * @key: the name of the key to set
1798 * @value: the value to set it to
1800 * Sets @key in @settings to @value.
1802 * A convenience variant of g_settings_set() for strings.
1804 * It is a programmer error to give a @key that isn't specified as
1805 * having a string type in the schema for @settings.
1807 * Returns: %TRUE if setting the key succeeded,
1808 * %FALSE if the key was not writable
1810 * Since: 2.26
1812 gboolean
1813 g_settings_set_string (GSettings *settings,
1814 const gchar *key,
1815 const gchar *value)
1817 return g_settings_set_value (settings, key, g_variant_new_string (value));
1821 * g_settings_get_int:
1822 * @settings: a #GSettings object
1823 * @key: the key to get the value for
1825 * Gets the value that is stored at @key in @settings.
1827 * A convenience variant of g_settings_get() for 32-bit integers.
1829 * It is a programmer error to give a @key that isn't specified as
1830 * having a int32 type in the schema for @settings.
1832 * Returns: an integer
1834 * Since: 2.26
1836 gint
1837 g_settings_get_int (GSettings *settings,
1838 const gchar *key)
1840 GVariant *value;
1841 gint result;
1843 value = g_settings_get_value (settings, key);
1844 result = g_variant_get_int32 (value);
1845 g_variant_unref (value);
1847 return result;
1851 * g_settings_set_int:
1852 * @settings: a #GSettings object
1853 * @key: the name of the key to set
1854 * @value: the value to set it to
1856 * Sets @key in @settings to @value.
1858 * A convenience variant of g_settings_set() for 32-bit integers.
1860 * It is a programmer error to give a @key that isn't specified as
1861 * having a int32 type in the schema for @settings.
1863 * Returns: %TRUE if setting the key succeeded,
1864 * %FALSE if the key was not writable
1866 * Since: 2.26
1868 gboolean
1869 g_settings_set_int (GSettings *settings,
1870 const gchar *key,
1871 gint value)
1873 return g_settings_set_value (settings, key, g_variant_new_int32 (value));
1877 * g_settings_get_int64:
1878 * @settings: a #GSettings object
1879 * @key: the key to get the value for
1881 * Gets the value that is stored at @key in @settings.
1883 * A convenience variant of g_settings_get() for 64-bit integers.
1885 * It is a programmer error to give a @key that isn't specified as
1886 * having a int64 type in the schema for @settings.
1888 * Returns: a 64-bit integer
1890 * Since: 2.50
1892 gint64
1893 g_settings_get_int64 (GSettings *settings,
1894 const gchar *key)
1896 GVariant *value;
1897 gint64 result;
1899 value = g_settings_get_value (settings, key);
1900 result = g_variant_get_int64 (value);
1901 g_variant_unref (value);
1903 return result;
1907 * g_settings_set_int64:
1908 * @settings: a #GSettings object
1909 * @key: the name of the key to set
1910 * @value: the value to set it to
1912 * Sets @key in @settings to @value.
1914 * A convenience variant of g_settings_set() for 64-bit integers.
1916 * It is a programmer error to give a @key that isn't specified as
1917 * having a int64 type in the schema for @settings.
1919 * Returns: %TRUE if setting the key succeeded,
1920 * %FALSE if the key was not writable
1922 * Since: 2.50
1924 gboolean
1925 g_settings_set_int64 (GSettings *settings,
1926 const gchar *key,
1927 gint64 value)
1929 return g_settings_set_value (settings, key, g_variant_new_int64 (value));
1933 * g_settings_get_uint:
1934 * @settings: a #GSettings object
1935 * @key: the key to get the value for
1937 * Gets the value that is stored at @key in @settings.
1939 * A convenience variant of g_settings_get() for 32-bit unsigned
1940 * integers.
1942 * It is a programmer error to give a @key that isn't specified as
1943 * having a uint32 type in the schema for @settings.
1945 * Returns: an unsigned integer
1947 * Since: 2.30
1949 guint
1950 g_settings_get_uint (GSettings *settings,
1951 const gchar *key)
1953 GVariant *value;
1954 guint result;
1956 value = g_settings_get_value (settings, key);
1957 result = g_variant_get_uint32 (value);
1958 g_variant_unref (value);
1960 return result;
1964 * g_settings_set_uint:
1965 * @settings: a #GSettings object
1966 * @key: the name of the key to set
1967 * @value: the value to set it to
1969 * Sets @key in @settings to @value.
1971 * A convenience variant of g_settings_set() for 32-bit unsigned
1972 * integers.
1974 * It is a programmer error to give a @key that isn't specified as
1975 * having a uint32 type in the schema for @settings.
1977 * Returns: %TRUE if setting the key succeeded,
1978 * %FALSE if the key was not writable
1980 * Since: 2.30
1982 gboolean
1983 g_settings_set_uint (GSettings *settings,
1984 const gchar *key,
1985 guint value)
1987 return g_settings_set_value (settings, key, g_variant_new_uint32 (value));
1991 * g_settings_get_uint64:
1992 * @settings: a #GSettings object
1993 * @key: the key to get the value for
1995 * Gets the value that is stored at @key in @settings.
1997 * A convenience variant of g_settings_get() for 64-bit unsigned
1998 * integers.
2000 * It is a programmer error to give a @key that isn't specified as
2001 * having a uint64 type in the schema for @settings.
2003 * Returns: a 64-bit unsigned integer
2005 * Since: 2.50
2007 guint64
2008 g_settings_get_uint64 (GSettings *settings,
2009 const gchar *key)
2011 GVariant *value;
2012 guint64 result;
2014 value = g_settings_get_value (settings, key);
2015 result = g_variant_get_uint64 (value);
2016 g_variant_unref (value);
2018 return result;
2022 * g_settings_set_uint64:
2023 * @settings: a #GSettings object
2024 * @key: the name of the key to set
2025 * @value: the value to set it to
2027 * Sets @key in @settings to @value.
2029 * A convenience variant of g_settings_set() for 64-bit unsigned
2030 * integers.
2032 * It is a programmer error to give a @key that isn't specified as
2033 * having a uint64 type in the schema for @settings.
2035 * Returns: %TRUE if setting the key succeeded,
2036 * %FALSE if the key was not writable
2038 * Since: 2.50
2040 gboolean
2041 g_settings_set_uint64 (GSettings *settings,
2042 const gchar *key,
2043 guint64 value)
2045 return g_settings_set_value (settings, key, g_variant_new_uint64 (value));
2049 * g_settings_get_double:
2050 * @settings: a #GSettings object
2051 * @key: the key to get the value for
2053 * Gets the value that is stored at @key in @settings.
2055 * A convenience variant of g_settings_get() for doubles.
2057 * It is a programmer error to give a @key that isn't specified as
2058 * having a 'double' type in the schema for @settings.
2060 * Returns: a double
2062 * Since: 2.26
2064 gdouble
2065 g_settings_get_double (GSettings *settings,
2066 const gchar *key)
2068 GVariant *value;
2069 gdouble result;
2071 value = g_settings_get_value (settings, key);
2072 result = g_variant_get_double (value);
2073 g_variant_unref (value);
2075 return result;
2079 * g_settings_set_double:
2080 * @settings: a #GSettings object
2081 * @key: the name of the key to set
2082 * @value: the value to set it to
2084 * Sets @key in @settings to @value.
2086 * A convenience variant of g_settings_set() for doubles.
2088 * It is a programmer error to give a @key that isn't specified as
2089 * having a 'double' type in the schema for @settings.
2091 * Returns: %TRUE if setting the key succeeded,
2092 * %FALSE if the key was not writable
2094 * Since: 2.26
2096 gboolean
2097 g_settings_set_double (GSettings *settings,
2098 const gchar *key,
2099 gdouble value)
2101 return g_settings_set_value (settings, key, g_variant_new_double (value));
2105 * g_settings_get_boolean:
2106 * @settings: a #GSettings object
2107 * @key: the key to get the value for
2109 * Gets the value that is stored at @key in @settings.
2111 * A convenience variant of g_settings_get() for booleans.
2113 * It is a programmer error to give a @key that isn't specified as
2114 * having a boolean type in the schema for @settings.
2116 * Returns: a boolean
2118 * Since: 2.26
2120 gboolean
2121 g_settings_get_boolean (GSettings *settings,
2122 const gchar *key)
2124 GVariant *value;
2125 gboolean result;
2127 value = g_settings_get_value (settings, key);
2128 result = g_variant_get_boolean (value);
2129 g_variant_unref (value);
2131 return result;
2135 * g_settings_set_boolean:
2136 * @settings: a #GSettings object
2137 * @key: the name of the key to set
2138 * @value: the value to set it to
2140 * Sets @key in @settings to @value.
2142 * A convenience variant of g_settings_set() for booleans.
2144 * It is a programmer error to give a @key that isn't specified as
2145 * having a boolean type in the schema for @settings.
2147 * Returns: %TRUE if setting the key succeeded,
2148 * %FALSE if the key was not writable
2150 * Since: 2.26
2152 gboolean
2153 g_settings_set_boolean (GSettings *settings,
2154 const gchar *key,
2155 gboolean value)
2157 return g_settings_set_value (settings, key, g_variant_new_boolean (value));
2161 * g_settings_get_strv:
2162 * @settings: a #GSettings object
2163 * @key: the key to get the value for
2165 * A convenience variant of g_settings_get() for string arrays.
2167 * It is a programmer error to give a @key that isn't specified as
2168 * having an array of strings type in the schema for @settings.
2170 * Returns: (array zero-terminated=1) (transfer full): a
2171 * newly-allocated, %NULL-terminated array of strings, the value that
2172 * is stored at @key in @settings.
2174 * Since: 2.26
2176 gchar **
2177 g_settings_get_strv (GSettings *settings,
2178 const gchar *key)
2180 GVariant *value;
2181 gchar **result;
2183 value = g_settings_get_value (settings, key);
2184 result = g_variant_dup_strv (value, NULL);
2185 g_variant_unref (value);
2187 return result;
2191 * g_settings_set_strv:
2192 * @settings: a #GSettings object
2193 * @key: the name of the key to set
2194 * @value: (nullable) (array zero-terminated=1): the value to set it to, or %NULL
2196 * Sets @key in @settings to @value.
2198 * A convenience variant of g_settings_set() for string arrays. If
2199 * @value is %NULL, then @key is set to be the empty array.
2201 * It is a programmer error to give a @key that isn't specified as
2202 * having an array of strings type in the schema for @settings.
2204 * Returns: %TRUE if setting the key succeeded,
2205 * %FALSE if the key was not writable
2207 * Since: 2.26
2209 gboolean
2210 g_settings_set_strv (GSettings *settings,
2211 const gchar *key,
2212 const gchar * const *value)
2214 GVariant *array;
2216 if (value != NULL)
2217 array = g_variant_new_strv (value, -1);
2218 else
2219 array = g_variant_new_strv (NULL, 0);
2221 return g_settings_set_value (settings, key, array);
2224 /* Delayed apply (delay, apply, revert, get_has_unapplied) {{{1 */
2226 * g_settings_delay:
2227 * @settings: a #GSettings object
2229 * Changes the #GSettings object into 'delay-apply' mode. In this
2230 * mode, changes to @settings are not immediately propagated to the
2231 * backend, but kept locally until g_settings_apply() is called.
2233 * Since: 2.26
2235 void
2236 g_settings_delay (GSettings *settings)
2238 g_return_if_fail (G_IS_SETTINGS (settings));
2240 if (settings->priv->delayed)
2241 return;
2243 settings->priv->delayed =
2244 g_delayed_settings_backend_new (settings->priv->backend,
2245 settings,
2246 settings->priv->main_context);
2247 g_settings_backend_unwatch (settings->priv->backend, G_OBJECT (settings));
2248 g_object_unref (settings->priv->backend);
2250 settings->priv->backend = G_SETTINGS_BACKEND (settings->priv->delayed);
2251 g_settings_backend_watch (settings->priv->backend,
2252 &listener_vtable, G_OBJECT (settings),
2253 settings->priv->main_context);
2255 g_object_notify (G_OBJECT (settings), "delay-apply");
2259 * g_settings_apply:
2260 * @settings: a #GSettings instance
2262 * Applies any changes that have been made to the settings. This
2263 * function does nothing unless @settings is in 'delay-apply' mode;
2264 * see g_settings_delay(). In the normal case settings are always
2265 * applied immediately.
2267 void
2268 g_settings_apply (GSettings *settings)
2270 if (settings->priv->delayed)
2272 GDelayedSettingsBackend *delayed;
2274 delayed = G_DELAYED_SETTINGS_BACKEND (settings->priv->backend);
2275 g_delayed_settings_backend_apply (delayed);
2280 * g_settings_revert:
2281 * @settings: a #GSettings instance
2283 * Reverts all non-applied changes to the settings. This function
2284 * does nothing unless @settings is in 'delay-apply' mode; see
2285 * g_settings_delay(). In the normal case settings are always applied
2286 * immediately.
2288 * Change notifications will be emitted for affected keys.
2290 void
2291 g_settings_revert (GSettings *settings)
2293 if (settings->priv->delayed)
2295 GDelayedSettingsBackend *delayed;
2297 delayed = G_DELAYED_SETTINGS_BACKEND (settings->priv->backend);
2298 g_delayed_settings_backend_revert (delayed);
2303 * g_settings_get_has_unapplied:
2304 * @settings: a #GSettings object
2306 * Returns whether the #GSettings object has any unapplied
2307 * changes. This can only be the case if it is in 'delayed-apply' mode.
2309 * Returns: %TRUE if @settings has unapplied changes
2311 * Since: 2.26
2313 gboolean
2314 g_settings_get_has_unapplied (GSettings *settings)
2316 g_return_val_if_fail (G_IS_SETTINGS (settings), FALSE);
2318 return settings->priv->delayed &&
2319 g_delayed_settings_backend_get_has_unapplied (
2320 G_DELAYED_SETTINGS_BACKEND (settings->priv->backend));
2323 /* Extra API (reset, sync, get_child, is_writable, list_*, ranges) {{{1 */
2325 * g_settings_reset:
2326 * @settings: a #GSettings object
2327 * @key: the name of a key
2329 * Resets @key to its default value.
2331 * This call resets the key, as much as possible, to its default value.
2332 * That might the value specified in the schema or the one set by the
2333 * administrator.
2335 void
2336 g_settings_reset (GSettings *settings,
2337 const gchar *key)
2339 gchar *path;
2341 g_return_if_fail (G_IS_SETTINGS (settings));
2342 g_return_if_fail (key != NULL);
2344 path = g_strconcat (settings->priv->path, key, NULL);
2345 g_settings_backend_reset (settings->priv->backend, path, NULL);
2346 g_free (path);
2350 * g_settings_sync:
2352 * Ensures that all pending operations are complete for the default backend.
2354 * Writes made to a #GSettings are handled asynchronously. For this
2355 * reason, it is very unlikely that the changes have it to disk by the
2356 * time g_settings_set() returns.
2358 * This call will block until all of the writes have made it to the
2359 * backend. Since the mainloop is not running, no change notifications
2360 * will be dispatched during this call (but some may be queued by the
2361 * time the call is done).
2363 void
2364 g_settings_sync (void)
2366 g_settings_backend_sync_default ();
2370 * g_settings_is_writable:
2371 * @settings: a #GSettings object
2372 * @name: the name of a key
2374 * Finds out if a key can be written or not
2376 * Returns: %TRUE if the key @name is writable
2378 * Since: 2.26
2380 gboolean
2381 g_settings_is_writable (GSettings *settings,
2382 const gchar *name)
2384 gboolean writable;
2385 gchar *path;
2387 g_return_val_if_fail (G_IS_SETTINGS (settings), FALSE);
2389 path = g_strconcat (settings->priv->path, name, NULL);
2390 writable = g_settings_backend_get_writable (settings->priv->backend, path);
2391 g_free (path);
2393 return writable;
2397 * g_settings_get_child:
2398 * @settings: a #GSettings object
2399 * @name: the name of the child schema
2401 * Creates a child settings object which has a base path of
2402 * `base-path/@name`, where `base-path` is the base path of
2403 * @settings.
2405 * The schema for the child settings object must have been declared
2406 * in the schema of @settings using a <child> element.
2408 * Returns: (transfer full): a 'child' settings object
2410 * Since: 2.26
2412 GSettings *
2413 g_settings_get_child (GSettings *settings,
2414 const gchar *name)
2416 const gchar *child_schema;
2417 gchar *child_path;
2418 gchar *child_name;
2419 GSettings *child;
2421 g_return_val_if_fail (G_IS_SETTINGS (settings), NULL);
2423 child_name = g_strconcat (name, "/", NULL);
2424 child_schema = g_settings_schema_get_string (settings->priv->schema,
2425 child_name);
2426 if (child_schema == NULL)
2427 g_error ("Schema '%s' has no child '%s'",
2428 g_settings_schema_get_id (settings->priv->schema), name);
2430 child_path = g_strconcat (settings->priv->path, child_name, NULL);
2431 child = g_object_new (G_TYPE_SETTINGS,
2432 "backend", settings->priv->backend,
2433 "schema-id", child_schema,
2434 "path", child_path,
2435 NULL);
2436 g_free (child_path);
2437 g_free (child_name);
2439 return child;
2443 * g_settings_list_keys:
2444 * @settings: a #GSettings object
2446 * Introspects the list of keys on @settings.
2448 * You should probably not be calling this function from "normal" code
2449 * (since you should already know what keys are in your schema). This
2450 * function is intended for introspection reasons.
2452 * You should free the return value with g_strfreev() when you are done
2453 * with it.
2455 * Returns: (transfer full) (element-type utf8): a list of the keys on @settings
2457 gchar **
2458 g_settings_list_keys (GSettings *settings)
2460 return g_settings_schema_list_keys (settings->priv->schema);
2464 * g_settings_list_children:
2465 * @settings: a #GSettings object
2467 * Gets the list of children on @settings.
2469 * The list is exactly the list of strings for which it is not an error
2470 * to call g_settings_get_child().
2472 * For GSettings objects that are lists, this value can change at any
2473 * time. Note that there is a race condition here: you may
2474 * request a child after listing it only for it to have been destroyed
2475 * in the meantime. For this reason, g_settings_get_child() may return
2476 * %NULL even for a child that was listed by this function.
2478 * For GSettings objects that are not lists, you should probably not be
2479 * calling this function from "normal" code (since you should already
2480 * know what children are in your schema). This function may still be
2481 * useful there for introspection reasons, however.
2483 * You should free the return value with g_strfreev() when you are done
2484 * with it.
2486 * Returns: (transfer full) (element-type utf8): a list of the children on @settings
2488 gchar **
2489 g_settings_list_children (GSettings *settings)
2491 return g_settings_schema_list_children (settings->priv->schema);
2495 * g_settings_get_range:
2496 * @settings: a #GSettings
2497 * @key: the key to query the range of
2499 * Queries the range of a key.
2501 * Since: 2.28
2503 * Deprecated:2.40:Use g_settings_schema_key_get_range() instead.
2505 GVariant *
2506 g_settings_get_range (GSettings *settings,
2507 const gchar *key)
2509 GSettingsSchemaKey skey;
2510 GVariant *range;
2512 g_settings_schema_key_init (&skey, settings->priv->schema, key);
2513 range = g_settings_schema_key_get_range (&skey);
2514 g_settings_schema_key_clear (&skey);
2516 return range;
2520 * g_settings_range_check:
2521 * @settings: a #GSettings
2522 * @key: the key to check
2523 * @value: the value to check
2525 * Checks if the given @value is of the correct type and within the
2526 * permitted range for @key.
2528 * Returns: %TRUE if @value is valid for @key
2530 * Since: 2.28
2532 * Deprecated:2.40:Use g_settings_schema_key_range_check() instead.
2534 gboolean
2535 g_settings_range_check (GSettings *settings,
2536 const gchar *key,
2537 GVariant *value)
2539 GSettingsSchemaKey skey;
2540 gboolean good;
2542 g_settings_schema_key_init (&skey, settings->priv->schema, key);
2543 good = g_settings_schema_key_range_check (&skey, value);
2544 g_settings_schema_key_clear (&skey);
2546 return good;
2549 /* Binding {{{1 */
2550 typedef struct
2552 GSettingsSchemaKey key;
2553 GSettings *settings;
2554 GObject *object;
2556 GSettingsBindGetMapping get_mapping;
2557 GSettingsBindSetMapping set_mapping;
2558 gpointer user_data;
2559 GDestroyNotify destroy;
2561 guint writable_handler_id;
2562 guint property_handler_id;
2563 const GParamSpec *property;
2564 guint key_handler_id;
2566 /* prevent recursion */
2567 gboolean running;
2568 } GSettingsBinding;
2570 static void
2571 g_settings_binding_free (gpointer data)
2573 GSettingsBinding *binding = data;
2575 g_assert (!binding->running);
2577 if (binding->writable_handler_id)
2578 g_signal_handler_disconnect (binding->settings,
2579 binding->writable_handler_id);
2581 if (binding->key_handler_id)
2582 g_signal_handler_disconnect (binding->settings,
2583 binding->key_handler_id);
2585 if (g_signal_handler_is_connected (binding->object,
2586 binding->property_handler_id))
2587 g_signal_handler_disconnect (binding->object,
2588 binding->property_handler_id);
2590 g_settings_schema_key_clear (&binding->key);
2592 if (binding->destroy)
2593 binding->destroy (binding->user_data);
2595 g_object_unref (binding->settings);
2597 g_slice_free (GSettingsBinding, binding);
2600 static GQuark
2601 g_settings_binding_quark (const char *property)
2603 GQuark quark;
2604 gchar *tmp;
2606 tmp = g_strdup_printf ("gsettingsbinding-%s", property);
2607 quark = g_quark_from_string (tmp);
2608 g_free (tmp);
2610 return quark;
2613 static void
2614 g_settings_binding_key_changed (GSettings *settings,
2615 const gchar *key,
2616 gpointer user_data)
2618 GSettingsBinding *binding = user_data;
2619 GValue value = G_VALUE_INIT;
2620 GVariant *variant;
2622 g_assert (settings == binding->settings);
2623 g_assert (key == binding->key.name);
2625 if (binding->running)
2626 return;
2628 binding->running = TRUE;
2630 g_value_init (&value, binding->property->value_type);
2632 variant = g_settings_read_from_backend (binding->settings, &binding->key, FALSE, FALSE);
2633 if (variant && !binding->get_mapping (&value, variant, binding->user_data))
2635 /* silently ignore errors in the user's config database */
2636 g_variant_unref (variant);
2637 variant = NULL;
2640 if (variant == NULL)
2642 variant = g_settings_schema_key_get_translated_default (&binding->key);
2643 if (variant &&
2644 !binding->get_mapping (&value, variant, binding->user_data))
2646 /* flag translation errors with a warning */
2647 g_warning ("Translated default '%s' for key '%s' in schema '%s' "
2648 "was rejected by the binding mapping function",
2649 binding->key.unparsed, binding->key.name,
2650 g_settings_schema_get_id (binding->key.schema));
2651 g_variant_unref (variant);
2652 variant = NULL;
2656 if (variant == NULL)
2658 variant = g_settings_schema_key_get_per_desktop_default (&binding->key);
2659 if (variant &&
2660 !binding->get_mapping (&value, variant, binding->user_data))
2662 g_error ("Per-desktop default value for key '%s' in schema '%s' "
2663 "was rejected by the binding mapping function.",
2664 binding->key.name, g_settings_schema_get_id (binding->key.schema));
2665 g_variant_unref (variant);
2666 variant = NULL;
2670 if (variant == NULL)
2672 variant = g_variant_ref (binding->key.default_value);
2673 if (!binding->get_mapping (&value, variant, binding->user_data))
2674 g_error ("The schema default value for key '%s' in schema '%s' "
2675 "was rejected by the binding mapping function.",
2676 binding->key.name, g_settings_schema_get_id (binding->key.schema));
2679 g_object_set_property (binding->object, binding->property->name, &value);
2680 g_variant_unref (variant);
2681 g_value_unset (&value);
2683 binding->running = FALSE;
2686 static void
2687 g_settings_binding_property_changed (GObject *object,
2688 const GParamSpec *pspec,
2689 gpointer user_data)
2691 GSettingsBinding *binding = user_data;
2692 GValue value = G_VALUE_INIT;
2693 GVariant *variant;
2694 gboolean valid = TRUE;
2696 g_assert (object == binding->object);
2697 g_assert (pspec == binding->property);
2699 if (binding->running)
2700 return;
2702 binding->running = TRUE;
2704 g_value_init (&value, pspec->value_type);
2705 g_object_get_property (object, pspec->name, &value);
2706 if ((variant = binding->set_mapping (&value, binding->key.type,
2707 binding->user_data)))
2709 g_variant_take_ref (variant);
2711 if (!g_settings_schema_key_type_check (&binding->key, variant))
2713 gchar *type_str;
2714 type_str = g_variant_type_dup_string (binding->key.type);
2715 g_critical ("binding mapping function for key '%s' returned "
2716 "GVariant of type '%s' when type '%s' was requested",
2717 binding->key.name, g_variant_get_type_string (variant),
2718 type_str);
2719 g_free (type_str);
2720 valid = FALSE;
2723 if (valid && !g_settings_schema_key_range_check (&binding->key, variant))
2725 gchar *variant_str;
2726 variant_str = g_variant_print (variant, TRUE);
2727 g_critical ("GObject property '%s' on a '%s' object is out of "
2728 "schema-specified range for key '%s' of '%s': %s",
2729 binding->property->name, g_type_name (binding->property->owner_type),
2730 binding->key.name, g_settings_schema_get_id (binding->key.schema),
2731 variant_str);
2732 g_free (variant_str);
2733 valid = FALSE;
2736 if (valid)
2738 g_settings_write_to_backend (binding->settings, &binding->key, variant);
2740 g_variant_unref (variant);
2742 g_value_unset (&value);
2744 binding->running = FALSE;
2747 static gboolean
2748 g_settings_bind_invert_boolean_get_mapping (GValue *value,
2749 GVariant *variant,
2750 gpointer user_data)
2752 g_value_set_boolean (value, !g_variant_get_boolean (variant));
2753 return TRUE;
2756 static GVariant *
2757 g_settings_bind_invert_boolean_set_mapping (const GValue *value,
2758 const GVariantType *expected_type,
2759 gpointer user_data)
2761 return g_variant_new_boolean (!g_value_get_boolean (value));
2765 * g_settings_bind:
2766 * @settings: a #GSettings object
2767 * @key: the key to bind
2768 * @object: (type GObject.Object): a #GObject
2769 * @property: the name of the property to bind
2770 * @flags: flags for the binding
2772 * Create a binding between the @key in the @settings object
2773 * and the property @property of @object.
2775 * The binding uses the default GIO mapping functions to map
2776 * between the settings and property values. These functions
2777 * handle booleans, numeric types and string types in a
2778 * straightforward way. Use g_settings_bind_with_mapping() if
2779 * you need a custom mapping, or map between types that are not
2780 * supported by the default mapping functions.
2782 * Unless the @flags include %G_SETTINGS_BIND_NO_SENSITIVITY, this
2783 * function also establishes a binding between the writability of
2784 * @key and the "sensitive" property of @object (if @object has
2785 * a boolean property by that name). See g_settings_bind_writable()
2786 * for more details about writable bindings.
2788 * Note that the lifecycle of the binding is tied to @object,
2789 * and that you can have only one binding per object property.
2790 * If you bind the same property twice on the same object, the second
2791 * binding overrides the first one.
2793 * Since: 2.26
2795 void
2796 g_settings_bind (GSettings *settings,
2797 const gchar *key,
2798 gpointer object,
2799 const gchar *property,
2800 GSettingsBindFlags flags)
2802 GSettingsBindGetMapping get_mapping = NULL;
2803 GSettingsBindSetMapping set_mapping = NULL;
2805 if (flags & G_SETTINGS_BIND_INVERT_BOOLEAN)
2807 get_mapping = g_settings_bind_invert_boolean_get_mapping;
2808 set_mapping = g_settings_bind_invert_boolean_set_mapping;
2810 /* can't pass this flag to g_settings_bind_with_mapping() */
2811 flags &= ~G_SETTINGS_BIND_INVERT_BOOLEAN;
2814 g_settings_bind_with_mapping (settings, key, object, property, flags,
2815 get_mapping, set_mapping, NULL, NULL);
2819 * g_settings_bind_with_mapping: (skip)
2820 * @settings: a #GSettings object
2821 * @key: the key to bind
2822 * @object: (type GObject.Object): a #GObject
2823 * @property: the name of the property to bind
2824 * @flags: flags for the binding
2825 * @get_mapping: a function that gets called to convert values
2826 * from @settings to @object, or %NULL to use the default GIO mapping
2827 * @set_mapping: a function that gets called to convert values
2828 * from @object to @settings, or %NULL to use the default GIO mapping
2829 * @user_data: data that gets passed to @get_mapping and @set_mapping
2830 * @destroy: #GDestroyNotify function for @user_data
2832 * Create a binding between the @key in the @settings object
2833 * and the property @property of @object.
2835 * The binding uses the provided mapping functions to map between
2836 * settings and property values.
2838 * Note that the lifecycle of the binding is tied to @object,
2839 * and that you can have only one binding per object property.
2840 * If you bind the same property twice on the same object, the second
2841 * binding overrides the first one.
2843 * Since: 2.26
2845 void
2846 g_settings_bind_with_mapping (GSettings *settings,
2847 const gchar *key,
2848 gpointer object,
2849 const gchar *property,
2850 GSettingsBindFlags flags,
2851 GSettingsBindGetMapping get_mapping,
2852 GSettingsBindSetMapping set_mapping,
2853 gpointer user_data,
2854 GDestroyNotify destroy)
2856 GSettingsBinding *binding;
2857 GObjectClass *objectclass;
2858 gchar *detailed_signal;
2859 GQuark binding_quark;
2861 g_return_if_fail (G_IS_SETTINGS (settings));
2862 g_return_if_fail (key != NULL);
2863 g_return_if_fail (G_IS_OBJECT (object));
2864 g_return_if_fail (property != NULL);
2865 g_return_if_fail (~flags & G_SETTINGS_BIND_INVERT_BOOLEAN);
2867 objectclass = G_OBJECT_GET_CLASS (object);
2869 binding = g_slice_new0 (GSettingsBinding);
2870 g_settings_schema_key_init (&binding->key, settings->priv->schema, key);
2871 binding->settings = g_object_ref (settings);
2872 binding->object = object;
2873 binding->property = g_object_class_find_property (objectclass, property);
2874 binding->user_data = user_data;
2875 binding->destroy = destroy;
2876 binding->get_mapping = get_mapping ? get_mapping : g_settings_get_mapping;
2877 binding->set_mapping = set_mapping ? set_mapping : g_settings_set_mapping;
2879 if (!(flags & (G_SETTINGS_BIND_GET | G_SETTINGS_BIND_SET)))
2880 flags |= G_SETTINGS_BIND_GET | G_SETTINGS_BIND_SET;
2882 if (binding->property == NULL)
2884 g_critical ("g_settings_bind: no property '%s' on class '%s'",
2885 property, G_OBJECT_TYPE_NAME (object));
2886 return;
2889 if ((flags & G_SETTINGS_BIND_GET) &&
2890 (binding->property->flags & G_PARAM_WRITABLE) == 0)
2892 g_critical ("g_settings_bind: property '%s' on class '%s' is not "
2893 "writable", binding->property->name, G_OBJECT_TYPE_NAME (object));
2894 return;
2896 if ((flags & G_SETTINGS_BIND_SET) &&
2897 (binding->property->flags & G_PARAM_READABLE) == 0)
2899 g_critical ("g_settings_bind: property '%s' on class '%s' is not "
2900 "readable", binding->property->name, G_OBJECT_TYPE_NAME (object));
2901 return;
2904 if (get_mapping == g_settings_bind_invert_boolean_get_mapping)
2906 /* g_settings_bind_invert_boolean_get_mapping() is a private
2907 * function, so if we are here it means that g_settings_bind() was
2908 * called with G_SETTINGS_BIND_INVERT_BOOLEAN.
2910 * Ensure that both sides are boolean.
2913 if (binding->property->value_type != G_TYPE_BOOLEAN)
2915 g_critical ("g_settings_bind: G_SETTINGS_BIND_INVERT_BOOLEAN "
2916 "was specified, but property '%s' on type '%s' has "
2917 "type '%s'", binding->property->name, G_OBJECT_TYPE_NAME (object),
2918 g_type_name ((binding->property->value_type)));
2919 return;
2922 if (!g_variant_type_equal (binding->key.type, G_VARIANT_TYPE_BOOLEAN))
2924 g_critical ("g_settings_bind: G_SETTINGS_BIND_INVERT_BOOLEAN "
2925 "was specified, but key '%s' on schema '%s' has "
2926 "type '%s'", key, g_settings_schema_get_id (settings->priv->schema),
2927 g_variant_type_dup_string (binding->key.type));
2928 return;
2933 else if (((get_mapping == NULL && (flags & G_SETTINGS_BIND_GET)) ||
2934 (set_mapping == NULL && (flags & G_SETTINGS_BIND_SET))) &&
2935 !g_settings_mapping_is_compatible (binding->property->value_type,
2936 binding->key.type))
2938 g_critical ("g_settings_bind: property '%s' on class '%s' has type "
2939 "'%s' which is not compatible with type '%s' of key '%s' "
2940 "on schema '%s'", binding->property->name, G_OBJECT_TYPE_NAME (object),
2941 g_type_name (binding->property->value_type),
2942 g_variant_type_dup_string (binding->key.type), key,
2943 g_settings_schema_get_id (settings->priv->schema));
2944 return;
2947 if ((flags & G_SETTINGS_BIND_SET) &&
2948 (~flags & G_SETTINGS_BIND_NO_SENSITIVITY))
2950 GParamSpec *sensitive;
2952 sensitive = g_object_class_find_property (objectclass, "sensitive");
2954 if (sensitive && sensitive->value_type == G_TYPE_BOOLEAN &&
2955 (sensitive->flags & G_PARAM_WRITABLE))
2956 g_settings_bind_writable (settings, binding->key.name, object, "sensitive", FALSE);
2959 if (flags & G_SETTINGS_BIND_SET)
2961 detailed_signal = g_strdup_printf ("notify::%s", binding->property->name);
2962 binding->property_handler_id =
2963 g_signal_connect (object, detailed_signal,
2964 G_CALLBACK (g_settings_binding_property_changed),
2965 binding);
2966 g_free (detailed_signal);
2968 if (~flags & G_SETTINGS_BIND_GET)
2969 g_settings_binding_property_changed (object,
2970 binding->property,
2971 binding);
2974 if (flags & G_SETTINGS_BIND_GET)
2976 if (~flags & G_SETTINGS_BIND_GET_NO_CHANGES)
2978 detailed_signal = g_strdup_printf ("changed::%s", key);
2979 binding->key_handler_id =
2980 g_signal_connect (settings, detailed_signal,
2981 G_CALLBACK (g_settings_binding_key_changed),
2982 binding);
2983 g_free (detailed_signal);
2986 g_settings_binding_key_changed (settings, binding->key.name, binding);
2989 binding_quark = g_settings_binding_quark (binding->property->name);
2990 g_object_set_qdata_full (object, binding_quark,
2991 binding, g_settings_binding_free);
2994 /* Writability binding {{{1 */
2995 typedef struct
2997 GSettings *settings;
2998 gpointer object;
2999 const gchar *key;
3000 const gchar *property;
3001 gboolean inverted;
3002 gulong handler_id;
3003 } GSettingsWritableBinding;
3005 static void
3006 g_settings_writable_binding_free (gpointer data)
3008 GSettingsWritableBinding *binding = data;
3010 g_signal_handler_disconnect (binding->settings, binding->handler_id);
3011 g_object_unref (binding->settings);
3012 g_slice_free (GSettingsWritableBinding, binding);
3015 static void
3016 g_settings_binding_writable_changed (GSettings *settings,
3017 const gchar *key,
3018 gpointer user_data)
3020 GSettingsWritableBinding *binding = user_data;
3021 gboolean writable;
3023 g_assert (settings == binding->settings);
3024 g_assert (key == binding->key);
3026 writable = g_settings_is_writable (settings, key);
3028 if (binding->inverted)
3029 writable = !writable;
3031 g_object_set (binding->object, binding->property, writable, NULL);
3035 * g_settings_bind_writable:
3036 * @settings: a #GSettings object
3037 * @key: the key to bind
3038 * @object: (type GObject.Object):a #GObject
3039 * @property: the name of a boolean property to bind
3040 * @inverted: whether to 'invert' the value
3042 * Create a binding between the writability of @key in the
3043 * @settings object and the property @property of @object.
3044 * The property must be boolean; "sensitive" or "visible"
3045 * properties of widgets are the most likely candidates.
3047 * Writable bindings are always uni-directional; changes of the
3048 * writability of the setting will be propagated to the object
3049 * property, not the other way.
3051 * When the @inverted argument is %TRUE, the binding inverts the
3052 * value as it passes from the setting to the object, i.e. @property
3053 * will be set to %TRUE if the key is not writable.
3055 * Note that the lifecycle of the binding is tied to @object,
3056 * and that you can have only one binding per object property.
3057 * If you bind the same property twice on the same object, the second
3058 * binding overrides the first one.
3060 * Since: 2.26
3062 void
3063 g_settings_bind_writable (GSettings *settings,
3064 const gchar *key,
3065 gpointer object,
3066 const gchar *property,
3067 gboolean inverted)
3069 GSettingsWritableBinding *binding;
3070 gchar *detailed_signal;
3071 GParamSpec *pspec;
3073 g_return_if_fail (G_IS_SETTINGS (settings));
3075 pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (object), property);
3076 if (pspec == NULL)
3078 g_critical ("g_settings_bind_writable: no property '%s' on class '%s'",
3079 property, G_OBJECT_TYPE_NAME (object));
3080 return;
3082 if ((pspec->flags & G_PARAM_WRITABLE) == 0)
3084 g_critical ("g_settings_bind_writable: property '%s' on class '%s' is not writable",
3085 property, G_OBJECT_TYPE_NAME (object));
3086 return;
3089 binding = g_slice_new (GSettingsWritableBinding);
3090 binding->settings = g_object_ref (settings);
3091 binding->object = object;
3092 binding->key = g_intern_string (key);
3093 binding->property = g_intern_string (property);
3094 binding->inverted = inverted;
3096 detailed_signal = g_strdup_printf ("writable-changed::%s", key);
3097 binding->handler_id =
3098 g_signal_connect (settings, detailed_signal,
3099 G_CALLBACK (g_settings_binding_writable_changed),
3100 binding);
3101 g_free (detailed_signal);
3103 g_object_set_qdata_full (object, g_settings_binding_quark (property),
3104 binding, g_settings_writable_binding_free);
3106 g_settings_binding_writable_changed (settings, binding->key, binding);
3110 * g_settings_unbind:
3111 * @object: (type GObject.Object): the object
3112 * @property: the property whose binding is removed
3114 * Removes an existing binding for @property on @object.
3116 * Note that bindings are automatically removed when the
3117 * object is finalized, so it is rarely necessary to call this
3118 * function.
3120 * Since: 2.26
3122 void
3123 g_settings_unbind (gpointer object,
3124 const gchar *property)
3126 GQuark binding_quark;
3128 binding_quark = g_settings_binding_quark (property);
3129 g_object_set_qdata (object, binding_quark, NULL);
3132 /* GAction {{{1 */
3134 typedef struct
3136 GObject parent_instance;
3138 GSettingsSchemaKey key;
3139 GSettings *settings;
3140 } GSettingsAction;
3142 typedef GObjectClass GSettingsActionClass;
3144 static GType g_settings_action_get_type (void);
3145 static void g_settings_action_iface_init (GActionInterface *iface);
3146 G_DEFINE_TYPE_WITH_CODE (GSettingsAction, g_settings_action, G_TYPE_OBJECT,
3147 G_IMPLEMENT_INTERFACE (G_TYPE_ACTION, g_settings_action_iface_init))
3149 enum
3151 ACTION_PROP_0,
3152 ACTION_PROP_NAME,
3153 ACTION_PROP_PARAMETER_TYPE,
3154 ACTION_PROP_ENABLED,
3155 ACTION_PROP_STATE_TYPE,
3156 ACTION_PROP_STATE
3159 static const gchar *
3160 g_settings_action_get_name (GAction *action)
3162 GSettingsAction *gsa = (GSettingsAction *) action;
3164 return gsa->key.name;
3167 static const GVariantType *
3168 g_settings_action_get_parameter_type (GAction *action)
3170 GSettingsAction *gsa = (GSettingsAction *) action;
3171 const GVariantType *type;
3173 type = g_variant_get_type (gsa->key.default_value);
3174 if (g_variant_type_equal (type, G_VARIANT_TYPE_BOOLEAN))
3175 type = NULL;
3177 return type;
3180 static gboolean
3181 g_settings_action_get_enabled (GAction *action)
3183 GSettingsAction *gsa = (GSettingsAction *) action;
3185 return g_settings_is_writable (gsa->settings, gsa->key.name);
3188 static const GVariantType *
3189 g_settings_action_get_state_type (GAction *action)
3191 GSettingsAction *gsa = (GSettingsAction *) action;
3193 return g_variant_get_type (gsa->key.default_value);
3196 static GVariant *
3197 g_settings_action_get_state (GAction *action)
3199 GSettingsAction *gsa = (GSettingsAction *) action;
3200 GVariant *value;
3202 value = g_settings_read_from_backend (gsa->settings, &gsa->key, FALSE, FALSE);
3204 if (value == NULL)
3205 value = g_settings_schema_key_get_translated_default (&gsa->key);
3207 if (value == NULL)
3208 value = g_variant_ref (gsa->key.default_value);
3210 return value;
3213 static GVariant *
3214 g_settings_action_get_state_hint (GAction *action)
3216 GSettingsAction *gsa = (GSettingsAction *) action;
3218 /* no point in reimplementing this... */
3219 return g_settings_schema_key_get_range (&gsa->key);
3222 static void
3223 g_settings_action_change_state (GAction *action,
3224 GVariant *value)
3226 GSettingsAction *gsa = (GSettingsAction *) action;
3228 if (g_settings_schema_key_type_check (&gsa->key, value) && g_settings_schema_key_range_check (&gsa->key, value))
3229 g_settings_write_to_backend (gsa->settings, &gsa->key, value);
3232 static void
3233 g_settings_action_activate (GAction *action,
3234 GVariant *parameter)
3236 GSettingsAction *gsa = (GSettingsAction *) action;
3238 if (g_variant_is_of_type (gsa->key.default_value, G_VARIANT_TYPE_BOOLEAN))
3240 GVariant *old;
3242 if (parameter != NULL)
3243 return;
3245 old = g_settings_action_get_state (action);
3246 parameter = g_variant_new_boolean (!g_variant_get_boolean (old));
3247 g_variant_unref (old);
3250 g_action_change_state (action, parameter);
3253 static void
3254 g_settings_action_get_property (GObject *object, guint prop_id,
3255 GValue *value, GParamSpec *pspec)
3257 GAction *action = G_ACTION (object);
3259 switch (prop_id)
3261 case ACTION_PROP_NAME:
3262 g_value_set_string (value, g_settings_action_get_name (action));
3263 break;
3265 case ACTION_PROP_PARAMETER_TYPE:
3266 g_value_set_boxed (value, g_settings_action_get_parameter_type (action));
3267 break;
3269 case ACTION_PROP_ENABLED:
3270 g_value_set_boolean (value, g_settings_action_get_enabled (action));
3271 break;
3273 case ACTION_PROP_STATE_TYPE:
3274 g_value_set_boxed (value, g_settings_action_get_state_type (action));
3275 break;
3277 case ACTION_PROP_STATE:
3278 g_value_set_variant (value, g_settings_action_get_state (action));
3279 break;
3281 default:
3282 g_assert_not_reached ();
3286 static void
3287 g_settings_action_finalize (GObject *object)
3289 GSettingsAction *gsa = (GSettingsAction *) object;
3291 g_signal_handlers_disconnect_by_data (gsa->settings, gsa);
3292 g_object_unref (gsa->settings);
3293 g_settings_schema_key_clear (&gsa->key);
3295 G_OBJECT_CLASS (g_settings_action_parent_class)
3296 ->finalize (object);
3299 static void
3300 g_settings_action_init (GSettingsAction *gsa)
3304 static void
3305 g_settings_action_iface_init (GActionInterface *iface)
3307 iface->get_name = g_settings_action_get_name;
3308 iface->get_parameter_type = g_settings_action_get_parameter_type;
3309 iface->get_enabled = g_settings_action_get_enabled;
3310 iface->get_state_type = g_settings_action_get_state_type;
3311 iface->get_state = g_settings_action_get_state;
3312 iface->get_state_hint = g_settings_action_get_state_hint;
3313 iface->change_state = g_settings_action_change_state;
3314 iface->activate = g_settings_action_activate;
3317 static void
3318 g_settings_action_class_init (GSettingsActionClass *class)
3320 class->get_property = g_settings_action_get_property;
3321 class->finalize = g_settings_action_finalize;
3323 g_object_class_override_property (class, ACTION_PROP_NAME, "name");
3324 g_object_class_override_property (class, ACTION_PROP_PARAMETER_TYPE, "parameter-type");
3325 g_object_class_override_property (class, ACTION_PROP_ENABLED, "enabled");
3326 g_object_class_override_property (class, ACTION_PROP_STATE_TYPE, "state-type");
3327 g_object_class_override_property (class, ACTION_PROP_STATE, "state");
3330 static void
3331 g_settings_action_changed (GSettings *settings,
3332 const gchar *key,
3333 gpointer user_data)
3335 g_object_notify (user_data, "state");
3338 static void
3339 g_settings_action_enabled_changed (GSettings *settings,
3340 const gchar *key,
3341 gpointer user_data)
3343 g_object_notify (user_data, "enabled");
3347 * g_settings_create_action:
3348 * @settings: a #GSettings
3349 * @key: the name of a key in @settings
3351 * Creates a #GAction corresponding to a given #GSettings key.
3353 * The action has the same name as the key.
3355 * The value of the key becomes the state of the action and the action
3356 * is enabled when the key is writable. Changing the state of the
3357 * action results in the key being written to. Changes to the value or
3358 * writability of the key cause appropriate change notifications to be
3359 * emitted for the action.
3361 * For boolean-valued keys, action activations take no parameter and
3362 * result in the toggling of the value. For all other types,
3363 * activations take the new value for the key (which must have the
3364 * correct type).
3366 * Returns: (transfer full): a new #GAction
3368 * Since: 2.32
3370 GAction *
3371 g_settings_create_action (GSettings *settings,
3372 const gchar *key)
3374 GSettingsAction *gsa;
3375 gchar *detailed_signal;
3377 g_return_val_if_fail (G_IS_SETTINGS (settings), NULL);
3378 g_return_val_if_fail (key != NULL, NULL);
3380 gsa = g_object_new (g_settings_action_get_type (), NULL);
3381 gsa->settings = g_object_ref (settings);
3382 g_settings_schema_key_init (&gsa->key, settings->priv->schema, key);
3384 detailed_signal = g_strdup_printf ("changed::%s", key);
3385 g_signal_connect (settings, detailed_signal, G_CALLBACK (g_settings_action_changed), gsa);
3386 g_free (detailed_signal);
3387 detailed_signal = g_strdup_printf ("writable-changed::%s", key);
3388 g_signal_connect (settings, detailed_signal, G_CALLBACK (g_settings_action_enabled_changed), gsa);
3389 g_free (detailed_signal);
3391 return G_ACTION (gsa);
3394 /* Epilogue {{{1 */
3396 /* vim:set foldmethod=marker: */