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>
26 #include "gsettings.h"
28 #include "gdelayedsettingsbackend.h"
29 #include "gsettingsbackendinternal.h"
30 #include "gsettings-mapping.h"
31 #include "gsettingsschema-internal.h"
38 * @short_description: High-level API for application settings
41 * The #GSettings class provides a convenient API for storing and retrieving
42 * application settings.
44 * Reads and writes can be considered to be non-blocking. Reading
45 * settings with #GSettings is typically extremely fast: on
46 * approximately the same order of magnitude (but slower than) a
47 * #GHashTable lookup. Writing settings is also extremely fast in terms
48 * of time to return to your application, but can be extremely expensive
49 * for other threads and other processes. Many settings backends
50 * (including dconf) have lazy initialisation which means in the common
51 * case of the user using their computer without modifying any settings
52 * a lot of work can be avoided. For dconf, the D-Bus service doesn't
53 * even need to be started in this case. For this reason, you should
54 * only ever modify #GSettings keys in response to explicit user action.
55 * Particular care should be paid to ensure that modifications are not
56 * made during startup -- for example, when setting the initial value
57 * of preferences widgets. The built-in g_settings_bind() functionality
58 * is careful not to write settings in response to notify signals as a
59 * result of modifications that it makes to widgets.
61 * When creating a GSettings instance, you have to specify a schema
62 * that describes the keys in your settings and their types and default
63 * values, as well as some other information.
65 * Normally, a schema has 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.
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>
114 * Translations of default values must remain syntactically valid serialized
115 * #GVariants (e.g. retaining any surrounding quotation marks) or runtime
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:
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>
154 * Greeting of the invading martians
158 * <key name="box" type="(ii)">
159 * <default>(20,30)</default>
162 * <key name="empty-string" type="s">
163 * <default>""</default>
164 * <summary>Empty strings have to be provided in GVariant form</summary>
171 * An example for ranges, choices and enumerated types:
175 * <enum id="org.gtk.Test.myenum">
176 * <value nick="first" value="1"/>
177 * <value nick="second" value="2"/>
180 * <flags id="org.gtk.Test.myflags">
181 * <value nick="flag1" value="1"/>
182 * <value nick="flag2" value="2"/>
183 * <value nick="flag3" value="4"/>
186 * <schema id="org.gtk.Test">
188 * <key name="key-with-range" type="i">
189 * <range min="1" max="100"/>
190 * <default>10</default>
193 * <key name="key-with-choices" type="s">
195 * <choice value='Elisabeth'/>
196 * <choice value='Annabeth'/>
197 * <choice value='Joe'/>
200 * <alias value='Anna' target='Annabeth'/>
201 * <alias value='Beth' target='Elisabeth'/>
203 * <default>'Joe'</default>
206 * <key name='enumerated-key' enum='org.gtk.Test.myenum'>
207 * <default>'first'</default>
210 * <key name='flags-key' flags='org.gtk.Test.myflags'>
211 * <default>["flag1","flag2"]</default>
217 * ## Vendor overrides
219 * Default values are defined in the schemas that get installed by
220 * an application. Sometimes, it is necessary for a vendor or distributor
221 * to adjust these defaults. Since patching the XML source for the schema
222 * is inconvenient and error-prone,
223 * [glib-compile-schemas][glib-compile-schemas] reads so-called vendor
224 * override' files. These are keyfiles in the same directory as the XML
225 * schema sources which can override default values. The schema id serves
226 * as the group name in the key file, and the values are expected in
227 * serialized GVariant form, as in the following example:
234 * glib-compile-schemas expects schema files to have the extension
235 * `.gschema.override`.
239 * A very convenient feature of GSettings lets you bind #GObject properties
240 * directly to settings, using g_settings_bind(). Once a GObject property
241 * has been bound to a setting, changes on either side are automatically
242 * propagated to the other side. GSettings handles details like mapping
243 * between GObject and GVariant types, and preventing infinite cycles.
245 * This makes it very easy to hook up a preferences dialog to the
246 * underlying settings. To make this even more convenient, GSettings
247 * looks for a boolean property with the name "sensitivity" and
248 * automatically binds it to the writability of the bound setting.
249 * If this 'magic' gets in the way, it can be suppressed with the
250 * #G_SETTINGS_BIND_NO_SENSITIVITY flag.
252 * ## Relocatable schemas # {#gsettings-relocatable}
254 * A relocatable schema is one with no `path` attribute specified on its
255 * <schema> element. By using g_settings_new_with_path(), a #GSettings object
256 * can be instantiated for a relocatable schema, assigning a path to the
257 * instance. Paths passed to g_settings_new_with_path() will typically be
258 * constructed dynamically from a constant prefix plus some form of instance
259 * identifier; but they must still be valid GSettings paths. Paths could also
260 * be constant and used with a globally installed schema originating from a
261 * dependency library.
263 * For example, a relocatable schema could be used to store geometry information
264 * for different windows in an application. If the schema ID was
265 * `org.foo.MyApp.Window`, it could be instantiated for paths
266 * `/org/foo/MyApp/main/`, `/org/foo/MyApp/document-1/`,
267 * `/org/foo/MyApp/document-2/`, etc. If any of the paths are well-known
268 * they can be specified as <child> elements in the parent schema, e.g.:
270 * <schema id="org.foo.MyApp" path="/org/foo/MyApp/">
271 * <child name="main" schema="org.foo.MyApp.Window"/>
275 * ## Build system integration # {#gsettings-build-system}
277 * GSettings comes with autotools integration to simplify compiling and
278 * installing schemas. To add GSettings support to an application, add the
279 * following to your `configure.ac`:
284 * In the appropriate `Makefile.am`, use the following snippet to compile and
285 * install the named schema:
287 * gsettings_SCHEMAS = org.foo.MyApp.gschema.xml
288 * EXTRA_DIST = $(gsettings_SCHEMAS)
293 * No changes are needed to the build system to mark a schema XML file for
294 * translation. Assuming it sets the `gettext-domain` attribute, a schema may
295 * be marked for translation by adding it to `POTFILES.in`, assuming gettext
296 * 0.19 is in use (the preferred method for translation):
298 * data/org.foo.MyApp.gschema.xml
301 * Alternatively, if intltool 0.50.1 is in use:
303 * [type: gettext/gsettings]data/org.foo.MyApp.gschema.xml
306 * GSettings will use gettext to look up translations for the <summary> and
307 * <description> elements, and also any <default> elements which have a `l10n`
308 * attribute set. Translations must not be included in the `.gschema.xml` file
309 * by the build system, for example by using intltool XML rules with a
310 * `.gschema.xml.in` template.
312 * If an enumerated type defined in a C header file is to be used in a GSettings
313 * schema, it can either be defined manually using an <enum> element in the
314 * schema XML, or it can be extracted automatically from the C header. This
315 * approach is preferred, as it ensures the two representations are always
316 * synchronised. To do so, add the following to the relevant `Makefile.am`:
318 * gsettings_ENUM_NAMESPACE = org.foo.MyApp
319 * gsettings_ENUM_FILES = my-app-enums.h my-app-misc.h
322 * `gsettings_ENUM_NAMESPACE` specifies the schema namespace for the enum files,
323 * which are specified in `gsettings_ENUM_FILES`. This will generate a
324 * `org.foo.MyApp.enums.xml` file containing the extracted enums, which will be
325 * automatically included in the schema compilation, install and uninstall
326 * rules. It should not be committed to version control or included in
333 * #GSettings is an opaque data structure and can only be accessed
334 * using the following functions.
337 struct _GSettingsPrivate
339 /* where the signals go... */
340 GMainContext *main_context;
342 GSettingsBackend *backend;
343 GSettingsSchema *schema;
346 GDelayedSettingsBackend *delayed;
362 SIGNAL_WRITABLE_CHANGE_EVENT,
363 SIGNAL_WRITABLE_CHANGED,
369 static guint g_settings_signals[N_SIGNALS];
371 G_DEFINE_TYPE_WITH_PRIVATE (GSettings, g_settings, G_TYPE_OBJECT)
375 g_settings_real_change_event (GSettings *settings,
382 keys = g_settings_schema_list (settings->priv->schema, &n_keys);
384 for (i = 0; i < n_keys; i++)
386 const gchar *key = g_quark_to_string (keys[i]);
388 if (g_str_has_suffix (key, "/"))
391 g_signal_emit (settings, g_settings_signals[SIGNAL_CHANGED], keys[i], key);
398 g_settings_real_writable_change_event (GSettings *settings,
401 const GQuark *keys = &key;
406 keys = g_settings_schema_list (settings->priv->schema, &n_keys);
408 for (i = 0; i < n_keys; i++)
410 const gchar *key = g_quark_to_string (keys[i]);
412 if (g_str_has_suffix (key, "/"))
415 g_signal_emit (settings, g_settings_signals[SIGNAL_WRITABLE_CHANGED], keys[i], key);
422 settings_backend_changed (GObject *target,
423 GSettingsBackend *backend,
427 GSettings *settings = G_SETTINGS (target);
428 gboolean ignore_this;
431 /* We used to assert here:
433 * settings->priv->backend == backend
435 * but it could be the case that a notification is queued for delivery
436 * while someone calls g_settings_delay() (which changes the backend).
438 * Since the delay backend would just pass that straight through
439 * anyway, it doesn't make sense to try to detect this case.
440 * Therefore, we just accept it.
443 for (i = 0; key[i] == settings->priv->path[i]; i++);
445 if (settings->priv->path[i] == '\0' &&
446 g_settings_schema_has_key (settings->priv->schema, key + i))
450 quark = g_quark_from_string (key + i);
451 g_signal_emit (settings, g_settings_signals[SIGNAL_CHANGE_EVENT],
452 0, &quark, 1, &ignore_this);
457 settings_backend_path_changed (GObject *target,
458 GSettingsBackend *backend,
462 GSettings *settings = G_SETTINGS (target);
463 gboolean ignore_this;
465 if (g_str_has_prefix (settings->priv->path, path))
466 g_signal_emit (settings, g_settings_signals[SIGNAL_CHANGE_EVENT],
467 0, NULL, 0, &ignore_this);
471 settings_backend_keys_changed (GObject *target,
472 GSettingsBackend *backend,
475 const gchar * const *items)
477 GSettings *settings = G_SETTINGS (target);
478 gboolean ignore_this;
481 for (i = 0; settings->priv->path[i] &&
482 settings->priv->path[i] == path[i]; i++);
489 for (j = 0; items[j]; j++)
491 const gchar *item = items[j];
494 for (k = 0; item[k] == settings->priv->path[i + k]; k++);
496 if (settings->priv->path[i + k] == '\0' &&
497 g_settings_schema_has_key (settings->priv->schema, item + k))
498 quarks[l++] = g_quark_from_string (item + k);
500 /* "256 quarks ought to be enough for anybody!"
501 * If this bites you, I'm sorry. Please file a bug.
507 g_signal_emit (settings, g_settings_signals[SIGNAL_CHANGE_EVENT],
508 0, quarks, l, &ignore_this);
513 settings_backend_writable_changed (GObject *target,
514 GSettingsBackend *backend,
517 GSettings *settings = G_SETTINGS (target);
518 gboolean ignore_this;
521 for (i = 0; key[i] == settings->priv->path[i]; i++);
523 if (settings->priv->path[i] == '\0' &&
524 g_settings_schema_has_key (settings->priv->schema, key + i))
525 g_signal_emit (settings, g_settings_signals[SIGNAL_WRITABLE_CHANGE_EVENT],
526 0, g_quark_from_string (key + i), &ignore_this);
530 settings_backend_path_writable_changed (GObject *target,
531 GSettingsBackend *backend,
534 GSettings *settings = G_SETTINGS (target);
535 gboolean ignore_this;
537 if (g_str_has_prefix (settings->priv->path, path))
538 g_signal_emit (settings, g_settings_signals[SIGNAL_WRITABLE_CHANGE_EVENT],
539 0, (GQuark) 0, &ignore_this);
542 /* Properties, Construction, Destruction {{{1 */
544 g_settings_set_property (GObject *object,
549 GSettings *settings = G_SETTINGS (object);
555 GSettingsSchema *schema;
557 schema = g_value_dup_boxed (value);
559 /* we receive a set_property() call for "settings-schema" even
560 * if it was not specified (ie: with NULL value). ->schema
561 * could already be set at this point (ie: via "schema-id").
562 * check for NULL to avoid clobbering the existing value.
566 g_assert (settings->priv->schema == NULL);
567 settings->priv->schema = schema;
574 const gchar *schema_id;
576 schema_id = g_value_get_string (value);
578 /* we receive a set_property() call for both "schema" and
579 * "schema-id", even if they are not set. Hopefully only one of
582 if (schema_id != NULL)
584 GSettingsSchemaSource *default_source;
586 g_assert (settings->priv->schema == NULL);
587 default_source = g_settings_schema_source_get_default ();
589 if (default_source == NULL)
590 g_error ("No GSettings schemas are installed on the system");
592 settings->priv->schema = g_settings_schema_source_lookup (default_source, schema_id, TRUE);
594 if (settings->priv->schema == NULL)
595 g_error ("Settings schema '%s' is not installed", schema_id);
601 settings->priv->path = g_value_dup_string (value);
605 settings->priv->backend = g_value_dup_object (value);
609 g_assert_not_reached ();
614 g_settings_get_property (GObject *object,
619 GSettings *settings = G_SETTINGS (object);
624 g_value_set_boxed (value, settings->priv->schema);
628 g_value_set_string (value, g_settings_schema_get_id (settings->priv->schema));
632 g_value_set_object (value, settings->priv->backend);
636 g_value_set_string (value, settings->priv->path);
639 case PROP_HAS_UNAPPLIED:
640 g_value_set_boolean (value, g_settings_get_has_unapplied (settings));
643 case PROP_DELAY_APPLY:
644 g_value_set_boolean (value, settings->priv->delayed != NULL);
648 g_assert_not_reached ();
652 static const GSettingsListenerVTable listener_vtable = {
653 settings_backend_changed,
654 settings_backend_path_changed,
655 settings_backend_keys_changed,
656 settings_backend_writable_changed,
657 settings_backend_path_writable_changed
661 g_settings_constructed (GObject *object)
663 GSettings *settings = G_SETTINGS (object);
664 const gchar *schema_path;
666 schema_path = g_settings_schema_get_path (settings->priv->schema);
668 if (settings->priv->path && schema_path && strcmp (settings->priv->path, schema_path) != 0)
669 g_error ("settings object created with schema '%s' and path '%s', but path '%s' is specified by schema",
670 g_settings_schema_get_id (settings->priv->schema), settings->priv->path, schema_path);
672 if (settings->priv->path == NULL)
674 if (schema_path == NULL)
675 g_error ("attempting to create schema '%s' without a path",
676 g_settings_schema_get_id (settings->priv->schema));
678 settings->priv->path = g_strdup (schema_path);
681 if (settings->priv->backend == NULL)
682 settings->priv->backend = g_settings_backend_get_default ();
684 g_settings_backend_watch (settings->priv->backend,
685 &listener_vtable, G_OBJECT (settings),
686 settings->priv->main_context);
687 g_settings_backend_subscribe (settings->priv->backend,
688 settings->priv->path);
692 g_settings_finalize (GObject *object)
694 GSettings *settings = G_SETTINGS (object);
696 g_settings_backend_unsubscribe (settings->priv->backend,
697 settings->priv->path);
698 g_main_context_unref (settings->priv->main_context);
699 g_object_unref (settings->priv->backend);
700 g_settings_schema_unref (settings->priv->schema);
701 g_free (settings->priv->path);
703 G_OBJECT_CLASS (g_settings_parent_class)->finalize (object);
707 g_settings_init (GSettings *settings)
709 settings->priv = g_settings_get_instance_private (settings);
710 settings->priv->main_context = g_main_context_ref_thread_default ();
714 g_settings_class_init (GSettingsClass *class)
716 GObjectClass *object_class = G_OBJECT_CLASS (class);
718 class->writable_change_event = g_settings_real_writable_change_event;
719 class->change_event = g_settings_real_change_event;
721 object_class->set_property = g_settings_set_property;
722 object_class->get_property = g_settings_get_property;
723 object_class->constructed = g_settings_constructed;
724 object_class->finalize = g_settings_finalize;
727 * GSettings::changed:
728 * @settings: the object on which the signal was emitted
729 * @key: the name of the key that changed
731 * The "changed" signal is emitted when a key has potentially changed.
732 * You should call one of the g_settings_get() calls to check the new
735 * This signal supports detailed connections. You can connect to the
736 * detailed signal "changed::x" in order to only receive callbacks
737 * when key "x" changes.
739 * Note that @settings only emits this signal if you have read @key at
740 * least once while a signal handler was already connected for @key.
742 g_settings_signals[SIGNAL_CHANGED] =
743 g_signal_new (I_("changed"), G_TYPE_SETTINGS,
744 G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
745 G_STRUCT_OFFSET (GSettingsClass, changed),
746 NULL, NULL, g_cclosure_marshal_VOID__STRING, G_TYPE_NONE,
747 1, G_TYPE_STRING | G_SIGNAL_TYPE_STATIC_SCOPE);
750 * GSettings::change-event:
751 * @settings: the object on which the signal was emitted
752 * @keys: (array length=n_keys) (element-type GQuark) (nullable):
753 * an array of #GQuarks for the changed keys, or %NULL
754 * @n_keys: the length of the @keys array, or 0
756 * The "change-event" signal is emitted once per change event that
757 * affects this settings object. You should connect to this signal
758 * only if you are interested in viewing groups of changes before they
759 * are split out into multiple emissions of the "changed" signal.
760 * For most use cases it is more appropriate to use the "changed" signal.
762 * In the event that the change event applies to one or more specified
763 * keys, @keys will be an array of #GQuark of length @n_keys. In the
764 * event that the change event applies to the #GSettings object as a
765 * whole (ie: potentially every key has been changed) then @keys will
766 * be %NULL and @n_keys will be 0.
768 * The default handler for this signal invokes the "changed" signal
769 * for each affected key. If any other connected handler returns
770 * %TRUE then this default functionality will be suppressed.
772 * Returns: %TRUE to stop other handlers from being invoked for the
773 * event. FALSE to propagate the event further.
775 g_settings_signals[SIGNAL_CHANGE_EVENT] =
776 g_signal_new (I_("change-event"), G_TYPE_SETTINGS,
778 G_STRUCT_OFFSET (GSettingsClass, change_event),
779 g_signal_accumulator_true_handled, NULL,
781 G_TYPE_BOOLEAN, 2, G_TYPE_POINTER, G_TYPE_INT);
784 * GSettings::writable-changed:
785 * @settings: the object on which the signal was emitted
788 * The "writable-changed" signal is emitted when the writability of a
789 * key has potentially changed. You should call
790 * g_settings_is_writable() in order to determine the new status.
792 * This signal supports detailed connections. You can connect to the
793 * detailed signal "writable-changed::x" in order to only receive
794 * callbacks when the writability of "x" changes.
796 g_settings_signals[SIGNAL_WRITABLE_CHANGED] =
797 g_signal_new (I_("writable-changed"), G_TYPE_SETTINGS,
798 G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
799 G_STRUCT_OFFSET (GSettingsClass, writable_changed),
800 NULL, NULL, g_cclosure_marshal_VOID__STRING, G_TYPE_NONE,
801 1, G_TYPE_STRING | G_SIGNAL_TYPE_STATIC_SCOPE);
804 * GSettings::writable-change-event:
805 * @settings: the object on which the signal was emitted
806 * @key: the quark of the key, or 0
808 * The "writable-change-event" signal is emitted once per writability
809 * change event that affects this settings object. You should connect
810 * to this signal if you are interested in viewing groups of changes
811 * before they are split out into multiple emissions of the
812 * "writable-changed" signal. For most use cases it is more
813 * appropriate to use the "writable-changed" signal.
815 * In the event that the writability change applies only to a single
816 * key, @key will be set to the #GQuark for that key. In the event
817 * that the writability change affects the entire settings object,
820 * The default handler for this signal invokes the "writable-changed"
821 * and "changed" signals for each affected key. This is done because
822 * changes in writability might also imply changes in value (if for
823 * example, a new mandatory setting is introduced). If any other
824 * connected handler returns %TRUE then this default functionality
825 * will be suppressed.
827 * Returns: %TRUE to stop other handlers from being invoked for the
828 * event. FALSE to propagate the event further.
830 g_settings_signals[SIGNAL_WRITABLE_CHANGE_EVENT] =
831 g_signal_new (I_("writable-change-event"), G_TYPE_SETTINGS,
833 G_STRUCT_OFFSET (GSettingsClass, writable_change_event),
834 g_signal_accumulator_true_handled, NULL,
835 NULL, G_TYPE_BOOLEAN, 1, G_TYPE_UINT);
840 * The name of the context that the settings are stored in.
842 g_object_class_install_property (object_class, PROP_BACKEND,
843 g_param_spec_object ("backend",
844 P_("GSettingsBackend"),
845 P_("The GSettingsBackend for this settings object"),
846 G_TYPE_SETTINGS_BACKEND, G_PARAM_CONSTRUCT_ONLY |
847 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
850 * GSettings:settings-schema:
852 * The #GSettingsSchema describing the types of keys for this
855 * Ideally, this property would be called 'schema'. #GSettingsSchema
856 * has only existed since version 2.32, however, and before then the
857 * 'schema' property was used to refer to the ID of the schema rather
858 * than the schema itself. Take care.
860 g_object_class_install_property (object_class, PROP_SCHEMA,
861 g_param_spec_boxed ("settings-schema",
863 P_("The GSettingsSchema for this settings object"),
864 G_TYPE_SETTINGS_SCHEMA,
865 G_PARAM_CONSTRUCT_ONLY |
866 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
871 * The name of the schema that describes the types of keys
872 * for this #GSettings object.
874 * The type of this property is *not* #GSettingsSchema.
875 * #GSettingsSchema has only existed since version 2.32 and
876 * unfortunately this name was used in previous versions to refer to
877 * the schema ID rather than the schema itself. Take care to use the
878 * 'settings-schema' property if you wish to pass in a
881 * Deprecated:2.32:Use the 'schema-id' property instead. In a future
882 * version, this property may instead refer to a #GSettingsSchema.
884 g_object_class_install_property (object_class, PROP_SCHEMA_ID,
885 g_param_spec_string ("schema",
887 P_("The name of the schema for this settings object"),
889 G_PARAM_CONSTRUCT_ONLY |
890 G_PARAM_DEPRECATED | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
893 * GSettings:schema-id:
895 * The name of the schema that describes the types of keys
896 * for this #GSettings object.
898 g_object_class_install_property (object_class, PROP_SCHEMA_ID,
899 g_param_spec_string ("schema-id",
901 P_("The name of the schema for this settings object"),
903 G_PARAM_CONSTRUCT_ONLY |
904 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
909 * The path within the backend where the settings are stored.
911 g_object_class_install_property (object_class, PROP_PATH,
912 g_param_spec_string ("path",
914 P_("The path within the backend where the settings are"),
916 G_PARAM_CONSTRUCT_ONLY |
917 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
920 * GSettings:has-unapplied:
922 * If this property is %TRUE, the #GSettings object has outstanding
923 * changes that will be applied when g_settings_apply() is called.
925 g_object_class_install_property (object_class, PROP_HAS_UNAPPLIED,
926 g_param_spec_boolean ("has-unapplied",
927 P_("Has unapplied changes"),
928 P_("TRUE if there are outstanding changes to apply()"),
930 G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
933 * GSettings:delay-apply:
935 * Whether the #GSettings object is in 'delay-apply' mode. See
936 * g_settings_delay() for details.
940 g_object_class_install_property (object_class, PROP_DELAY_APPLY,
941 g_param_spec_boolean ("delay-apply",
942 P_("Delay-apply mode"),
943 P_("Whether this settings object is in “delay-apply” mode"),
945 G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
948 /* Construction (new, new_with_path, etc.) {{{1 */
951 * @schema_id: the id of the schema
953 * Creates a new #GSettings object with the schema specified by
956 * Signals on the newly created #GSettings object will be dispatched
957 * via the thread-default #GMainContext in effect at the time of the
958 * call to g_settings_new(). The new #GSettings will hold a reference
959 * on the context. See g_main_context_push_thread_default().
961 * Returns: a new #GSettings object
966 g_settings_new (const gchar *schema_id)
968 g_return_val_if_fail (schema_id != NULL, NULL);
970 return g_object_new (G_TYPE_SETTINGS,
971 "schema-id", schema_id,
976 path_is_valid (const gchar *path)
984 if (!g_str_has_suffix (path, "/"))
987 return strstr (path, "//") == NULL;
991 * g_settings_new_with_path:
992 * @schema_id: the id of the schema
993 * @path: the path to use
995 * Creates a new #GSettings object with the relocatable schema specified
996 * by @schema_id and a given path.
998 * You only need to do this if you want to directly create a settings
999 * object with a schema that doesn't have a specified path of its own.
1000 * That's quite rare.
1002 * It is a programmer error to call this function for a schema that
1003 * has an explicitly specified path.
1005 * It is a programmer error if @path is not a valid path. A valid path
1006 * begins and ends with '/' and does not contain two consecutive '/'
1009 * Returns: a new #GSettings object
1014 g_settings_new_with_path (const gchar *schema_id,
1017 g_return_val_if_fail (schema_id != NULL, NULL);
1018 g_return_val_if_fail (path_is_valid (path), NULL);
1020 return g_object_new (G_TYPE_SETTINGS,
1021 "schema-id", schema_id,
1027 * g_settings_new_with_backend:
1028 * @schema_id: the id of the schema
1029 * @backend: the #GSettingsBackend to use
1031 * Creates a new #GSettings object with the schema specified by
1032 * @schema_id and a given #GSettingsBackend.
1034 * Creating a #GSettings object with a different backend allows accessing
1035 * settings from a database other than the usual one. For example, it may make
1036 * sense to pass a backend corresponding to the "defaults" settings database on
1037 * the system to get a settings object that modifies the system default
1038 * settings instead of the settings for this user.
1040 * Returns: a new #GSettings object
1045 g_settings_new_with_backend (const gchar *schema_id,
1046 GSettingsBackend *backend)
1048 g_return_val_if_fail (schema_id != NULL, NULL);
1049 g_return_val_if_fail (G_IS_SETTINGS_BACKEND (backend), NULL);
1051 return g_object_new (G_TYPE_SETTINGS,
1052 "schema-id", schema_id,
1058 * g_settings_new_with_backend_and_path:
1059 * @schema_id: the id of the schema
1060 * @backend: the #GSettingsBackend to use
1061 * @path: the path to use
1063 * Creates a new #GSettings object with the schema specified by
1064 * @schema_id and a given #GSettingsBackend and path.
1066 * This is a mix of g_settings_new_with_backend() and
1067 * g_settings_new_with_path().
1069 * Returns: a new #GSettings object
1074 g_settings_new_with_backend_and_path (const gchar *schema_id,
1075 GSettingsBackend *backend,
1078 g_return_val_if_fail (schema_id != NULL, NULL);
1079 g_return_val_if_fail (G_IS_SETTINGS_BACKEND (backend), NULL);
1080 g_return_val_if_fail (path_is_valid (path), NULL);
1082 return g_object_new (G_TYPE_SETTINGS,
1083 "schema-id", schema_id,
1090 * g_settings_new_full:
1091 * @schema: a #GSettingsSchema
1092 * @backend: (nullable): a #GSettingsBackend
1093 * @path: (nullable): the path to use
1095 * Creates a new #GSettings object with a given schema, backend and
1098 * It should be extremely rare that you ever want to use this function.
1099 * It is made available for advanced use-cases (such as plugin systems
1100 * that want to provide access to schemas loaded from custom locations,
1103 * At the most basic level, a #GSettings object is a pure composition of
1104 * 4 things: a #GSettingsSchema, a #GSettingsBackend, a path within that
1105 * backend, and a #GMainContext to which signals are dispatched.
1107 * This constructor therefore gives you full control over constructing
1108 * #GSettings instances. The first 3 parameters are given directly as
1109 * @schema, @backend and @path, and the main context is taken from the
1110 * thread-default (as per g_settings_new()).
1112 * If @backend is %NULL then the default backend is used.
1114 * If @path is %NULL then the path from the schema is used. It is an
1115 * error if @path is %NULL and the schema has no path of its own or if
1116 * @path is non-%NULL and not equal to the path that the schema does
1119 * Returns: a new #GSettings object
1124 g_settings_new_full (GSettingsSchema *schema,
1125 GSettingsBackend *backend,
1128 g_return_val_if_fail (schema != NULL, NULL);
1129 g_return_val_if_fail (backend == NULL || G_IS_SETTINGS_BACKEND (backend), NULL);
1130 g_return_val_if_fail (path == NULL || path_is_valid (path), NULL);
1132 return g_object_new (G_TYPE_SETTINGS,
1133 "settings-schema", schema,
1139 /* Internal read/write utilities {{{1 */
1141 g_settings_write_to_backend (GSettings *settings,
1142 GSettingsSchemaKey *key,
1148 path = g_strconcat (settings->priv->path, key->name, NULL);
1149 success = g_settings_backend_write (settings->priv->backend, path, value, NULL);
1156 g_settings_read_from_backend (GSettings *settings,
1157 GSettingsSchemaKey *key,
1158 gboolean user_value_only,
1159 gboolean default_value)
1165 path = g_strconcat (settings->priv->path, key->name, NULL);
1166 if (user_value_only)
1167 value = g_settings_backend_read_user_value (settings->priv->backend, path, key->type);
1169 value = g_settings_backend_read (settings->priv->backend, path, key->type, default_value);
1174 fixup = g_settings_schema_key_range_fixup (key, value);
1175 g_variant_unref (value);
1183 /* Public Get/Set API {{{1 (get, get_value, set, set_value, get_mapped) */
1185 * g_settings_get_value:
1186 * @settings: a #GSettings object
1187 * @key: the key to get the value for
1189 * Gets the value that is stored in @settings for @key.
1191 * It is a programmer error to give a @key that isn't contained in the
1192 * schema for @settings.
1194 * Returns: a new #GVariant
1199 g_settings_get_value (GSettings *settings,
1202 GSettingsSchemaKey skey;
1205 g_return_val_if_fail (G_IS_SETTINGS (settings), NULL);
1206 g_return_val_if_fail (key != NULL, NULL);
1208 g_settings_schema_key_init (&skey, settings->priv->schema, key);
1209 value = g_settings_read_from_backend (settings, &skey, FALSE, FALSE);
1212 value = g_settings_schema_key_get_default_value (&skey);
1214 g_settings_schema_key_clear (&skey);
1220 * g_settings_get_user_value:
1221 * @settings: a #GSettings object
1222 * @key: the key to get the user value for
1224 * Checks the "user value" of a key, if there is one.
1226 * The user value of a key is the last value that was set by the user.
1228 * After calling g_settings_reset() this function should always return
1229 * %NULL (assuming something is not wrong with the system
1232 * It is possible that g_settings_get_value() will return a different
1233 * value than this function. This can happen in the case that the user
1234 * set a value for a key that was subsequently locked down by the system
1235 * administrator -- this function will return the user's old value.
1237 * This function may be useful for adding a "reset" option to a UI or
1238 * for providing indication that a particular value has been changed.
1240 * It is a programmer error to give a @key that isn't contained in the
1241 * schema for @settings.
1243 * Returns: (nullable) (transfer full): the user's value, if set
1248 g_settings_get_user_value (GSettings *settings,
1251 GSettingsSchemaKey skey;
1254 g_return_val_if_fail (G_IS_SETTINGS (settings), NULL);
1255 g_return_val_if_fail (key != NULL, NULL);
1257 g_settings_schema_key_init (&skey, settings->priv->schema, key);
1258 value = g_settings_read_from_backend (settings, &skey, TRUE, FALSE);
1259 g_settings_schema_key_clear (&skey);
1265 * g_settings_get_default_value:
1266 * @settings: a #GSettings object
1267 * @key: the key to get the default value for
1269 * Gets the "default value" of a key.
1271 * This is the value that would be read if g_settings_reset() were to be
1272 * called on the key.
1274 * Note that this may be a different value than returned by
1275 * g_settings_schema_key_get_default_value() if the system administrator
1276 * has provided a default value.
1278 * Comparing the return values of g_settings_get_default_value() and
1279 * g_settings_get_value() is not sufficient for determining if a value
1280 * has been set because the user may have explicitly set the value to
1281 * something that happens to be equal to the default. The difference
1282 * here is that if the default changes in the future, the user's key
1283 * will still be set.
1285 * This function may be useful for adding an indication to a UI of what
1286 * the default value was before the user set it.
1288 * It is a programmer error to give a @key that isn't contained in the
1289 * schema for @settings.
1291 * Returns: (nullable) (transfer full): the default value
1296 g_settings_get_default_value (GSettings *settings,
1299 GSettingsSchemaKey skey;
1302 g_return_val_if_fail (G_IS_SETTINGS (settings), NULL);
1303 g_return_val_if_fail (key != NULL, NULL);
1305 g_settings_schema_key_init (&skey, settings->priv->schema, key);
1306 value = g_settings_read_from_backend (settings, &skey, FALSE, TRUE);
1309 value = g_settings_schema_key_get_default_value (&skey);
1311 g_settings_schema_key_clear (&skey);
1317 * g_settings_get_enum:
1318 * @settings: a #GSettings object
1319 * @key: the key to get the value for
1321 * Gets the value that is stored in @settings for @key and converts it
1322 * to the enum value that it represents.
1324 * In order to use this function the type of the value must be a string
1325 * and it must be marked in the schema file as an enumerated type.
1327 * It is a programmer error to give a @key that isn't contained in the
1328 * schema for @settings or is not marked as an enumerated type.
1330 * If the value stored in the configuration database is not a valid
1331 * value for the enumerated type then this function will return the
1334 * Returns: the enum value
1339 g_settings_get_enum (GSettings *settings,
1342 GSettingsSchemaKey skey;
1346 g_return_val_if_fail (G_IS_SETTINGS (settings), -1);
1347 g_return_val_if_fail (key != NULL, -1);
1349 g_settings_schema_key_init (&skey, settings->priv->schema, key);
1353 g_critical ("g_settings_get_enum() called on key '%s' which is not "
1354 "associated with an enumerated type", skey.name);
1355 g_settings_schema_key_clear (&skey);
1359 value = g_settings_read_from_backend (settings, &skey, FALSE, FALSE);
1362 value = g_settings_schema_key_get_default_value (&skey);
1364 result = g_settings_schema_key_to_enum (&skey, value);
1365 g_settings_schema_key_clear (&skey);
1366 g_variant_unref (value);
1372 * g_settings_set_enum:
1373 * @settings: a #GSettings object
1374 * @key: a key, within @settings
1375 * @value: an enumerated value
1377 * Looks up the enumerated type nick for @value and writes it to @key,
1380 * It is a programmer error to give a @key that isn't contained in the
1381 * schema for @settings or is not marked as an enumerated type, or for
1382 * @value not to be a valid value for the named type.
1384 * After performing the write, accessing @key directly with
1385 * g_settings_get_string() will return the 'nick' associated with
1388 * Returns: %TRUE, if the set succeeds
1391 g_settings_set_enum (GSettings *settings,
1395 GSettingsSchemaKey skey;
1399 g_return_val_if_fail (G_IS_SETTINGS (settings), FALSE);
1400 g_return_val_if_fail (key != NULL, FALSE);
1402 g_settings_schema_key_init (&skey, settings->priv->schema, key);
1406 g_critical ("g_settings_set_enum() called on key '%s' which is not "
1407 "associated with an enumerated type", skey.name);
1411 if (!(variant = g_settings_schema_key_from_enum (&skey, value)))
1413 g_critical ("g_settings_set_enum(): invalid enum value %d for key '%s' "
1414 "in schema '%s'. Doing nothing.", value, skey.name,
1415 g_settings_schema_get_id (skey.schema));
1416 g_settings_schema_key_clear (&skey);
1420 success = g_settings_write_to_backend (settings, &skey, variant);
1421 g_settings_schema_key_clear (&skey);
1427 * g_settings_get_flags:
1428 * @settings: a #GSettings object
1429 * @key: the key to get the value for
1431 * Gets the value that is stored in @settings for @key and converts it
1432 * to the flags value that it represents.
1434 * In order to use this function the type of the value must be an array
1435 * of strings and it must be marked in the schema file as an flags type.
1437 * It is a programmer error to give a @key that isn't contained in the
1438 * schema for @settings or is not marked as a flags type.
1440 * If the value stored in the configuration database is not a valid
1441 * value for the flags type then this function will return the default
1444 * Returns: the flags value
1449 g_settings_get_flags (GSettings *settings,
1452 GSettingsSchemaKey skey;
1456 g_return_val_if_fail (G_IS_SETTINGS (settings), -1);
1457 g_return_val_if_fail (key != NULL, -1);
1459 g_settings_schema_key_init (&skey, settings->priv->schema, key);
1463 g_critical ("g_settings_get_flags() called on key '%s' which is not "
1464 "associated with a flags type", skey.name);
1465 g_settings_schema_key_clear (&skey);
1469 value = g_settings_read_from_backend (settings, &skey, FALSE, FALSE);
1472 value = g_settings_schema_key_get_default_value (&skey);
1474 result = g_settings_schema_key_to_flags (&skey, value);
1475 g_settings_schema_key_clear (&skey);
1476 g_variant_unref (value);
1482 * g_settings_set_flags:
1483 * @settings: a #GSettings object
1484 * @key: a key, within @settings
1485 * @value: a flags value
1487 * Looks up the flags type nicks for the bits specified by @value, puts
1488 * them in an array of strings and writes the array to @key, within
1491 * It is a programmer error to give a @key that isn't contained in the
1492 * schema for @settings or is not marked as a flags type, or for @value
1493 * to contain any bits that are not value for the named type.
1495 * After performing the write, accessing @key directly with
1496 * g_settings_get_strv() will return an array of 'nicks'; one for each
1499 * Returns: %TRUE, if the set succeeds
1502 g_settings_set_flags (GSettings *settings,
1506 GSettingsSchemaKey skey;
1510 g_return_val_if_fail (G_IS_SETTINGS (settings), FALSE);
1511 g_return_val_if_fail (key != NULL, FALSE);
1513 g_settings_schema_key_init (&skey, settings->priv->schema, key);
1517 g_critical ("g_settings_set_flags() called on key '%s' which is not "
1518 "associated with a flags type", skey.name);
1522 if (!(variant = g_settings_schema_key_from_flags (&skey, value)))
1524 g_critical ("g_settings_set_flags(): invalid flags value 0x%08x "
1525 "for key '%s' in schema '%s'. Doing nothing.",
1526 value, skey.name, g_settings_schema_get_id (skey.schema));
1527 g_settings_schema_key_clear (&skey);
1531 success = g_settings_write_to_backend (settings, &skey, variant);
1532 g_settings_schema_key_clear (&skey);
1538 * g_settings_set_value:
1539 * @settings: a #GSettings object
1540 * @key: the name of the key to set
1541 * @value: a #GVariant of the correct type
1543 * Sets @key in @settings to @value.
1545 * It is a programmer error to give a @key that isn't contained in the
1546 * schema for @settings or for @value to have the incorrect type, per
1549 * If @value is floating then this function consumes the reference.
1551 * Returns: %TRUE if setting the key succeeded,
1552 * %FALSE if the key was not writable
1557 g_settings_set_value (GSettings *settings,
1561 GSettingsSchemaKey skey;
1564 g_return_val_if_fail (G_IS_SETTINGS (settings), FALSE);
1565 g_return_val_if_fail (key != NULL, FALSE);
1567 g_variant_ref_sink (value);
1568 g_settings_schema_key_init (&skey, settings->priv->schema, key);
1570 if (!g_settings_schema_key_type_check (&skey, value))
1572 g_critical ("g_settings_set_value: key '%s' in '%s' expects type '%s', but a GVariant of type '%s' was given",
1574 g_settings_schema_get_id (settings->priv->schema),
1575 g_variant_type_peek_string (skey.type),
1576 g_variant_get_type_string (value));
1579 else if (!g_settings_schema_key_range_check (&skey, value))
1581 g_warning ("g_settings_set_value: value for key '%s' in schema '%s' "
1582 "is outside of valid range",
1584 g_settings_schema_get_id (settings->priv->schema));
1589 success = g_settings_write_to_backend (settings, &skey, value);
1592 g_settings_schema_key_clear (&skey);
1593 g_variant_unref (value);
1600 * @settings: a #GSettings object
1601 * @key: the key to get the value for
1602 * @format: a #GVariant format string
1603 * @...: arguments as per @format
1605 * Gets the value that is stored at @key in @settings.
1607 * A convenience function that combines g_settings_get_value() with
1610 * It is a programmer error to give a @key that isn't contained in the
1611 * schema for @settings or for the #GVariantType of @format to mismatch
1612 * the type given in the schema.
1617 g_settings_get (GSettings *settings,
1619 const gchar *format,
1625 value = g_settings_get_value (settings, key);
1627 if (strchr (format, '&'))
1629 g_critical ("%s: the format string may not contain '&' (key '%s' from schema '%s'). "
1630 "This call will probably stop working with a future version of glib.",
1631 G_STRFUNC, key, g_settings_schema_get_id (settings->priv->schema));
1634 va_start (ap, format);
1635 g_variant_get_va (value, format, NULL, &ap);
1638 g_variant_unref (value);
1643 * @settings: a #GSettings object
1644 * @key: the name of the key to set
1645 * @format: a #GVariant format string
1646 * @...: arguments as per @format
1648 * Sets @key in @settings to @value.
1650 * A convenience function that combines g_settings_set_value() with
1653 * It is a programmer error to give a @key that isn't contained in the
1654 * schema for @settings or for the #GVariantType of @format to mismatch
1655 * the type given in the schema.
1657 * Returns: %TRUE if setting the key succeeded,
1658 * %FALSE if the key was not writable
1663 g_settings_set (GSettings *settings,
1665 const gchar *format,
1671 va_start (ap, format);
1672 value = g_variant_new_va (format, NULL, &ap);
1675 return g_settings_set_value (settings, key, value);
1679 * g_settings_get_mapped:
1680 * @settings: a #GSettings object
1681 * @key: the key to get the value for
1682 * @mapping: (scope call): the function to map the value in the
1683 * settings database to the value used by the application
1684 * @user_data: user data for @mapping
1686 * Gets the value that is stored at @key in @settings, subject to
1687 * application-level validation/mapping.
1689 * You should use this function when the application needs to perform
1690 * some processing on the value of the key (for example, parsing). The
1691 * @mapping function performs that processing. If the function
1692 * indicates that the processing was unsuccessful (due to a parse error,
1693 * for example) then the mapping is tried again with another value.
1695 * This allows a robust 'fall back to defaults' behaviour to be
1696 * implemented somewhat automatically.
1698 * The first value that is tried is the user's setting for the key. If
1699 * the mapping function fails to map this value, other values may be
1700 * tried in an unspecified order (system or site defaults, translated
1701 * schema default values, untranslated schema default values, etc).
1703 * If the mapping function fails for all possible values, one additional
1704 * attempt is made: the mapping function is called with a %NULL value.
1705 * If the mapping function still indicates failure at this point then
1706 * the application will be aborted.
1708 * The result parameter for the @mapping function is pointed to a
1709 * #gpointer which is initially set to %NULL. The same pointer is given
1710 * to each invocation of @mapping. The final value of that #gpointer is
1711 * what is returned by this function. %NULL is valid; it is returned
1712 * just as any other value would be.
1714 * Returns: (transfer full): the result, which may be %NULL
1717 g_settings_get_mapped (GSettings *settings,
1719 GSettingsGetMapping mapping,
1722 gpointer result = NULL;
1723 GSettingsSchemaKey skey;
1727 g_return_val_if_fail (G_IS_SETTINGS (settings), NULL);
1728 g_return_val_if_fail (key != NULL, NULL);
1729 g_return_val_if_fail (mapping != NULL, NULL);
1731 g_settings_schema_key_init (&skey, settings->priv->schema, key);
1733 if ((value = g_settings_read_from_backend (settings, &skey, FALSE, FALSE)))
1735 okay = mapping (value, &result, user_data);
1736 g_variant_unref (value);
1737 if (okay) goto okay;
1740 if ((value = g_settings_schema_key_get_translated_default (&skey)))
1742 okay = mapping (value, &result, user_data);
1743 g_variant_unref (value);
1744 if (okay) goto okay;
1747 if ((value = g_settings_schema_key_get_per_desktop_default (&skey)))
1749 okay = mapping (value, &result, user_data);
1750 g_variant_unref (value);
1751 if (okay) goto okay;
1754 if (mapping (skey.default_value, &result, user_data))
1757 if (!mapping (NULL, &result, user_data))
1758 g_error ("The mapping function given to g_settings_get_mapped() for key "
1759 "'%s' in schema '%s' returned FALSE when given a NULL value.",
1760 key, g_settings_schema_get_id (settings->priv->schema));
1763 g_settings_schema_key_clear (&skey);
1768 /* Convenience API (get, set_string, int, double, boolean, strv) {{{1 */
1770 * g_settings_get_string:
1771 * @settings: a #GSettings object
1772 * @key: the key to get the value for
1774 * Gets the value that is stored at @key in @settings.
1776 * A convenience variant of g_settings_get() for strings.
1778 * It is a programmer error to give a @key that isn't specified as
1779 * having a string type in the schema for @settings.
1781 * Returns: a newly-allocated string
1786 g_settings_get_string (GSettings *settings,
1792 value = g_settings_get_value (settings, key);
1793 result = g_variant_dup_string (value, NULL);
1794 g_variant_unref (value);
1800 * g_settings_set_string:
1801 * @settings: a #GSettings object
1802 * @key: the name of the key to set
1803 * @value: the value to set it to
1805 * Sets @key in @settings to @value.
1807 * A convenience variant of g_settings_set() for strings.
1809 * It is a programmer error to give a @key that isn't specified as
1810 * having a string type in the schema for @settings.
1812 * Returns: %TRUE if setting the key succeeded,
1813 * %FALSE if the key was not writable
1818 g_settings_set_string (GSettings *settings,
1822 return g_settings_set_value (settings, key, g_variant_new_string (value));
1826 * g_settings_get_int:
1827 * @settings: a #GSettings object
1828 * @key: the key to get the value for
1830 * Gets the value that is stored at @key in @settings.
1832 * A convenience variant of g_settings_get() for 32-bit integers.
1834 * It is a programmer error to give a @key that isn't specified as
1835 * having a int32 type in the schema for @settings.
1837 * Returns: an integer
1842 g_settings_get_int (GSettings *settings,
1848 value = g_settings_get_value (settings, key);
1849 result = g_variant_get_int32 (value);
1850 g_variant_unref (value);
1856 * g_settings_set_int:
1857 * @settings: a #GSettings object
1858 * @key: the name of the key to set
1859 * @value: the value to set it to
1861 * Sets @key in @settings to @value.
1863 * A convenience variant of g_settings_set() for 32-bit integers.
1865 * It is a programmer error to give a @key that isn't specified as
1866 * having a int32 type in the schema for @settings.
1868 * Returns: %TRUE if setting the key succeeded,
1869 * %FALSE if the key was not writable
1874 g_settings_set_int (GSettings *settings,
1878 return g_settings_set_value (settings, key, g_variant_new_int32 (value));
1882 * g_settings_get_int64:
1883 * @settings: a #GSettings object
1884 * @key: the key to get the value for
1886 * Gets the value that is stored at @key in @settings.
1888 * A convenience variant of g_settings_get() for 64-bit integers.
1890 * It is a programmer error to give a @key that isn't specified as
1891 * having a int64 type in the schema for @settings.
1893 * Returns: a 64-bit integer
1898 g_settings_get_int64 (GSettings *settings,
1904 value = g_settings_get_value (settings, key);
1905 result = g_variant_get_int64 (value);
1906 g_variant_unref (value);
1912 * g_settings_set_int64:
1913 * @settings: a #GSettings object
1914 * @key: the name of the key to set
1915 * @value: the value to set it to
1917 * Sets @key in @settings to @value.
1919 * A convenience variant of g_settings_set() for 64-bit integers.
1921 * It is a programmer error to give a @key that isn't specified as
1922 * having a int64 type in the schema for @settings.
1924 * Returns: %TRUE if setting the key succeeded,
1925 * %FALSE if the key was not writable
1930 g_settings_set_int64 (GSettings *settings,
1934 return g_settings_set_value (settings, key, g_variant_new_int64 (value));
1938 * g_settings_get_uint:
1939 * @settings: a #GSettings object
1940 * @key: the key to get the value for
1942 * Gets the value that is stored at @key in @settings.
1944 * A convenience variant of g_settings_get() for 32-bit unsigned
1947 * It is a programmer error to give a @key that isn't specified as
1948 * having a uint32 type in the schema for @settings.
1950 * Returns: an unsigned integer
1955 g_settings_get_uint (GSettings *settings,
1961 value = g_settings_get_value (settings, key);
1962 result = g_variant_get_uint32 (value);
1963 g_variant_unref (value);
1969 * g_settings_set_uint:
1970 * @settings: a #GSettings object
1971 * @key: the name of the key to set
1972 * @value: the value to set it to
1974 * Sets @key in @settings to @value.
1976 * A convenience variant of g_settings_set() for 32-bit unsigned
1979 * It is a programmer error to give a @key that isn't specified as
1980 * having a uint32 type in the schema for @settings.
1982 * Returns: %TRUE if setting the key succeeded,
1983 * %FALSE if the key was not writable
1988 g_settings_set_uint (GSettings *settings,
1992 return g_settings_set_value (settings, key, g_variant_new_uint32 (value));
1996 * g_settings_get_uint64:
1997 * @settings: a #GSettings object
1998 * @key: the key to get the value for
2000 * Gets the value that is stored at @key in @settings.
2002 * A convenience variant of g_settings_get() for 64-bit unsigned
2005 * It is a programmer error to give a @key that isn't specified as
2006 * having a uint64 type in the schema for @settings.
2008 * Returns: a 64-bit unsigned integer
2013 g_settings_get_uint64 (GSettings *settings,
2019 value = g_settings_get_value (settings, key);
2020 result = g_variant_get_uint64 (value);
2021 g_variant_unref (value);
2027 * g_settings_set_uint64:
2028 * @settings: a #GSettings object
2029 * @key: the name of the key to set
2030 * @value: the value to set it to
2032 * Sets @key in @settings to @value.
2034 * A convenience variant of g_settings_set() for 64-bit unsigned
2037 * It is a programmer error to give a @key that isn't specified as
2038 * having a uint64 type in the schema for @settings.
2040 * Returns: %TRUE if setting the key succeeded,
2041 * %FALSE if the key was not writable
2046 g_settings_set_uint64 (GSettings *settings,
2050 return g_settings_set_value (settings, key, g_variant_new_uint64 (value));
2054 * g_settings_get_double:
2055 * @settings: a #GSettings object
2056 * @key: the key to get the value for
2058 * Gets the value that is stored at @key in @settings.
2060 * A convenience variant of g_settings_get() for doubles.
2062 * It is a programmer error to give a @key that isn't specified as
2063 * having a 'double' type in the schema for @settings.
2070 g_settings_get_double (GSettings *settings,
2076 value = g_settings_get_value (settings, key);
2077 result = g_variant_get_double (value);
2078 g_variant_unref (value);
2084 * g_settings_set_double:
2085 * @settings: a #GSettings object
2086 * @key: the name of the key to set
2087 * @value: the value to set it to
2089 * Sets @key in @settings to @value.
2091 * A convenience variant of g_settings_set() for doubles.
2093 * It is a programmer error to give a @key that isn't specified as
2094 * having a 'double' type in the schema for @settings.
2096 * Returns: %TRUE if setting the key succeeded,
2097 * %FALSE if the key was not writable
2102 g_settings_set_double (GSettings *settings,
2106 return g_settings_set_value (settings, key, g_variant_new_double (value));
2110 * g_settings_get_boolean:
2111 * @settings: a #GSettings object
2112 * @key: the key to get the value for
2114 * Gets the value that is stored at @key in @settings.
2116 * A convenience variant of g_settings_get() for booleans.
2118 * It is a programmer error to give a @key that isn't specified as
2119 * having a boolean type in the schema for @settings.
2121 * Returns: a boolean
2126 g_settings_get_boolean (GSettings *settings,
2132 value = g_settings_get_value (settings, key);
2133 result = g_variant_get_boolean (value);
2134 g_variant_unref (value);
2140 * g_settings_set_boolean:
2141 * @settings: a #GSettings object
2142 * @key: the name of the key to set
2143 * @value: the value to set it to
2145 * Sets @key in @settings to @value.
2147 * A convenience variant of g_settings_set() for booleans.
2149 * It is a programmer error to give a @key that isn't specified as
2150 * having a boolean type in the schema for @settings.
2152 * Returns: %TRUE if setting the key succeeded,
2153 * %FALSE if the key was not writable
2158 g_settings_set_boolean (GSettings *settings,
2162 return g_settings_set_value (settings, key, g_variant_new_boolean (value));
2166 * g_settings_get_strv:
2167 * @settings: a #GSettings object
2168 * @key: the key to get the value for
2170 * A convenience variant of g_settings_get() for string arrays.
2172 * It is a programmer error to give a @key that isn't specified as
2173 * having an array of strings type in the schema for @settings.
2175 * Returns: (array zero-terminated=1) (transfer full): a
2176 * newly-allocated, %NULL-terminated array of strings, the value that
2177 * is stored at @key in @settings.
2182 g_settings_get_strv (GSettings *settings,
2188 value = g_settings_get_value (settings, key);
2189 result = g_variant_dup_strv (value, NULL);
2190 g_variant_unref (value);
2196 * g_settings_set_strv:
2197 * @settings: a #GSettings object
2198 * @key: the name of the key to set
2199 * @value: (nullable) (array zero-terminated=1): the value to set it to, or %NULL
2201 * Sets @key in @settings to @value.
2203 * A convenience variant of g_settings_set() for string arrays. If
2204 * @value is %NULL, then @key is set to be the empty array.
2206 * It is a programmer error to give a @key that isn't specified as
2207 * having an array of strings type in the schema for @settings.
2209 * Returns: %TRUE if setting the key succeeded,
2210 * %FALSE if the key was not writable
2215 g_settings_set_strv (GSettings *settings,
2217 const gchar * const *value)
2222 array = g_variant_new_strv (value, -1);
2224 array = g_variant_new_strv (NULL, 0);
2226 return g_settings_set_value (settings, key, array);
2229 /* Delayed apply (delay, apply, revert, get_has_unapplied) {{{1 */
2232 * @settings: a #GSettings object
2234 * Changes the #GSettings object into 'delay-apply' mode. In this
2235 * mode, changes to @settings are not immediately propagated to the
2236 * backend, but kept locally until g_settings_apply() is called.
2241 g_settings_delay (GSettings *settings)
2243 g_return_if_fail (G_IS_SETTINGS (settings));
2245 if (settings->priv->delayed)
2248 settings->priv->delayed =
2249 g_delayed_settings_backend_new (settings->priv->backend,
2251 settings->priv->main_context);
2252 g_settings_backend_unwatch (settings->priv->backend, G_OBJECT (settings));
2253 g_object_unref (settings->priv->backend);
2255 settings->priv->backend = G_SETTINGS_BACKEND (settings->priv->delayed);
2256 g_settings_backend_watch (settings->priv->backend,
2257 &listener_vtable, G_OBJECT (settings),
2258 settings->priv->main_context);
2260 g_object_notify (G_OBJECT (settings), "delay-apply");
2265 * @settings: a #GSettings instance
2267 * Applies any changes that have been made to the settings. This
2268 * function does nothing unless @settings is in 'delay-apply' mode;
2269 * see g_settings_delay(). In the normal case settings are always
2270 * applied immediately.
2273 g_settings_apply (GSettings *settings)
2275 if (settings->priv->delayed)
2277 GDelayedSettingsBackend *delayed;
2279 delayed = G_DELAYED_SETTINGS_BACKEND (settings->priv->backend);
2280 g_delayed_settings_backend_apply (delayed);
2285 * g_settings_revert:
2286 * @settings: a #GSettings instance
2288 * Reverts all non-applied changes to the settings. This function
2289 * does nothing unless @settings is in 'delay-apply' mode; see
2290 * g_settings_delay(). In the normal case settings are always applied
2293 * Change notifications will be emitted for affected keys.
2296 g_settings_revert (GSettings *settings)
2298 if (settings->priv->delayed)
2300 GDelayedSettingsBackend *delayed;
2302 delayed = G_DELAYED_SETTINGS_BACKEND (settings->priv->backend);
2303 g_delayed_settings_backend_revert (delayed);
2308 * g_settings_get_has_unapplied:
2309 * @settings: a #GSettings object
2311 * Returns whether the #GSettings object has any unapplied
2312 * changes. This can only be the case if it is in 'delayed-apply' mode.
2314 * Returns: %TRUE if @settings has unapplied changes
2319 g_settings_get_has_unapplied (GSettings *settings)
2321 g_return_val_if_fail (G_IS_SETTINGS (settings), FALSE);
2323 return settings->priv->delayed &&
2324 g_delayed_settings_backend_get_has_unapplied (
2325 G_DELAYED_SETTINGS_BACKEND (settings->priv->backend));
2328 /* Extra API (reset, sync, get_child, is_writable, list_*, ranges) {{{1 */
2331 * @settings: a #GSettings object
2332 * @key: the name of a key
2334 * Resets @key to its default value.
2336 * This call resets the key, as much as possible, to its default value.
2337 * That might the value specified in the schema or the one set by the
2341 g_settings_reset (GSettings *settings,
2346 g_return_if_fail (G_IS_SETTINGS (settings));
2347 g_return_if_fail (key != NULL);
2349 path = g_strconcat (settings->priv->path, key, NULL);
2350 g_settings_backend_reset (settings->priv->backend, path, NULL);
2357 * Ensures that all pending operations are complete for the default backend.
2359 * Writes made to a #GSettings are handled asynchronously. For this
2360 * reason, it is very unlikely that the changes have it to disk by the
2361 * time g_settings_set() returns.
2363 * This call will block until all of the writes have made it to the
2364 * backend. Since the mainloop is not running, no change notifications
2365 * will be dispatched during this call (but some may be queued by the
2366 * time the call is done).
2369 g_settings_sync (void)
2371 g_settings_backend_sync_default ();
2375 * g_settings_is_writable:
2376 * @settings: a #GSettings object
2377 * @name: the name of a key
2379 * Finds out if a key can be written or not
2381 * Returns: %TRUE if the key @name is writable
2386 g_settings_is_writable (GSettings *settings,
2392 g_return_val_if_fail (G_IS_SETTINGS (settings), FALSE);
2394 path = g_strconcat (settings->priv->path, name, NULL);
2395 writable = g_settings_backend_get_writable (settings->priv->backend, path);
2402 * g_settings_get_child:
2403 * @settings: a #GSettings object
2404 * @name: the name of the child schema
2406 * Creates a child settings object which has a base path of
2407 * `base-path/@name`, where `base-path` is the base path of
2410 * The schema for the child settings object must have been declared
2411 * in the schema of @settings using a <child> element.
2413 * Returns: (transfer full): a 'child' settings object
2418 g_settings_get_child (GSettings *settings,
2421 const gchar *child_schema;
2426 g_return_val_if_fail (G_IS_SETTINGS (settings), NULL);
2428 child_name = g_strconcat (name, "/", NULL);
2429 child_schema = g_settings_schema_get_string (settings->priv->schema,
2431 if (child_schema == NULL)
2432 g_error ("Schema '%s' has no child '%s'",
2433 g_settings_schema_get_id (settings->priv->schema), name);
2435 child_path = g_strconcat (settings->priv->path, child_name, NULL);
2436 child = g_object_new (G_TYPE_SETTINGS,
2437 "backend", settings->priv->backend,
2438 "schema-id", child_schema,
2441 g_free (child_path);
2442 g_free (child_name);
2448 * g_settings_list_keys:
2449 * @settings: a #GSettings object
2451 * Introspects the list of keys on @settings.
2453 * You should probably not be calling this function from "normal" code
2454 * (since you should already know what keys are in your schema). This
2455 * function is intended for introspection reasons.
2457 * You should free the return value with g_strfreev() when you are done
2460 * Returns: (transfer full) (element-type utf8): a list of the keys on @settings
2463 g_settings_list_keys (GSettings *settings)
2465 return g_settings_schema_list_keys (settings->priv->schema);
2469 * g_settings_list_children:
2470 * @settings: a #GSettings object
2472 * Gets the list of children on @settings.
2474 * The list is exactly the list of strings for which it is not an error
2475 * to call g_settings_get_child().
2477 * There is little reason to call this function from "normal" code, since
2478 * you should already know what children are in your schema. This function
2479 * may still be useful there for introspection reasons, however.
2481 * You should free the return value with g_strfreev() when you are done
2484 * Returns: (transfer full) (element-type utf8): a list of the children on @settings
2487 g_settings_list_children (GSettings *settings)
2489 return g_settings_schema_list_children (settings->priv->schema);
2493 * g_settings_get_range:
2494 * @settings: a #GSettings
2495 * @key: the key to query the range of
2497 * Queries the range of a key.
2501 * Deprecated:2.40:Use g_settings_schema_key_get_range() instead.
2504 g_settings_get_range (GSettings *settings,
2507 GSettingsSchemaKey skey;
2510 g_settings_schema_key_init (&skey, settings->priv->schema, key);
2511 range = g_settings_schema_key_get_range (&skey);
2512 g_settings_schema_key_clear (&skey);
2518 * g_settings_range_check:
2519 * @settings: a #GSettings
2520 * @key: the key to check
2521 * @value: the value to check
2523 * Checks if the given @value is of the correct type and within the
2524 * permitted range for @key.
2526 * Returns: %TRUE if @value is valid for @key
2530 * Deprecated:2.40:Use g_settings_schema_key_range_check() instead.
2533 g_settings_range_check (GSettings *settings,
2537 GSettingsSchemaKey skey;
2540 g_settings_schema_key_init (&skey, settings->priv->schema, key);
2541 good = g_settings_schema_key_range_check (&skey, value);
2542 g_settings_schema_key_clear (&skey);
2550 GSettingsSchemaKey key;
2551 GSettings *settings;
2554 GSettingsBindGetMapping get_mapping;
2555 GSettingsBindSetMapping set_mapping;
2557 GDestroyNotify destroy;
2559 guint writable_handler_id;
2560 guint property_handler_id;
2561 const GParamSpec *property;
2562 guint key_handler_id;
2564 /* prevent recursion */
2569 g_settings_binding_free (gpointer data)
2571 GSettingsBinding *binding = data;
2573 g_assert (!binding->running);
2575 if (binding->writable_handler_id)
2576 g_signal_handler_disconnect (binding->settings,
2577 binding->writable_handler_id);
2579 if (binding->key_handler_id)
2580 g_signal_handler_disconnect (binding->settings,
2581 binding->key_handler_id);
2583 if (g_signal_handler_is_connected (binding->object,
2584 binding->property_handler_id))
2585 g_signal_handler_disconnect (binding->object,
2586 binding->property_handler_id);
2588 g_settings_schema_key_clear (&binding->key);
2590 if (binding->destroy)
2591 binding->destroy (binding->user_data);
2593 g_object_unref (binding->settings);
2595 g_slice_free (GSettingsBinding, binding);
2599 g_settings_binding_quark (const char *property)
2604 tmp = g_strdup_printf ("gsettingsbinding-%s", property);
2605 quark = g_quark_from_string (tmp);
2612 g_settings_binding_key_changed (GSettings *settings,
2616 GSettingsBinding *binding = user_data;
2617 GValue value = G_VALUE_INIT;
2620 g_assert (settings == binding->settings);
2621 g_assert (key == binding->key.name);
2623 if (binding->running)
2626 binding->running = TRUE;
2628 g_value_init (&value, binding->property->value_type);
2630 variant = g_settings_read_from_backend (binding->settings, &binding->key, FALSE, FALSE);
2631 if (variant && !binding->get_mapping (&value, variant, binding->user_data))
2633 /* silently ignore errors in the user's config database */
2634 g_variant_unref (variant);
2638 if (variant == NULL)
2640 variant = g_settings_schema_key_get_translated_default (&binding->key);
2642 !binding->get_mapping (&value, variant, binding->user_data))
2644 /* flag translation errors with a warning */
2645 g_warning ("Translated default '%s' for key '%s' in schema '%s' "
2646 "was rejected by the binding mapping function",
2647 binding->key.unparsed, binding->key.name,
2648 g_settings_schema_get_id (binding->key.schema));
2649 g_variant_unref (variant);
2654 if (variant == NULL)
2656 variant = g_settings_schema_key_get_per_desktop_default (&binding->key);
2658 !binding->get_mapping (&value, variant, binding->user_data))
2660 g_error ("Per-desktop default value for key '%s' in schema '%s' "
2661 "was rejected by the binding mapping function.",
2662 binding->key.name, g_settings_schema_get_id (binding->key.schema));
2663 g_variant_unref (variant);
2668 if (variant == NULL)
2670 variant = g_variant_ref (binding->key.default_value);
2671 if (!binding->get_mapping (&value, variant, binding->user_data))
2672 g_error ("The schema default value for key '%s' in schema '%s' "
2673 "was rejected by the binding mapping function.",
2674 binding->key.name, g_settings_schema_get_id (binding->key.schema));
2677 g_object_set_property (binding->object, binding->property->name, &value);
2678 g_variant_unref (variant);
2679 g_value_unset (&value);
2681 binding->running = FALSE;
2685 g_settings_binding_property_changed (GObject *object,
2686 const GParamSpec *pspec,
2689 GSettingsBinding *binding = user_data;
2690 GValue value = G_VALUE_INIT;
2692 gboolean valid = TRUE;
2694 g_assert (object == binding->object);
2695 g_assert (pspec == binding->property);
2697 if (binding->running)
2700 binding->running = TRUE;
2702 g_value_init (&value, pspec->value_type);
2703 g_object_get_property (object, pspec->name, &value);
2704 if ((variant = binding->set_mapping (&value, binding->key.type,
2705 binding->user_data)))
2707 g_variant_take_ref (variant);
2709 if (!g_settings_schema_key_type_check (&binding->key, variant))
2712 type_str = g_variant_type_dup_string (binding->key.type);
2713 g_critical ("binding mapping function for key '%s' returned "
2714 "GVariant of type '%s' when type '%s' was requested",
2715 binding->key.name, g_variant_get_type_string (variant),
2721 if (valid && !g_settings_schema_key_range_check (&binding->key, variant))
2724 variant_str = g_variant_print (variant, TRUE);
2725 g_critical ("GObject property '%s' on a '%s' object is out of "
2726 "schema-specified range for key '%s' of '%s': %s",
2727 binding->property->name, g_type_name (binding->property->owner_type),
2728 binding->key.name, g_settings_schema_get_id (binding->key.schema),
2730 g_free (variant_str);
2736 g_settings_write_to_backend (binding->settings, &binding->key, variant);
2738 g_variant_unref (variant);
2740 g_value_unset (&value);
2742 binding->running = FALSE;
2746 g_settings_bind_invert_boolean_get_mapping (GValue *value,
2750 g_value_set_boolean (value, !g_variant_get_boolean (variant));
2755 g_settings_bind_invert_boolean_set_mapping (const GValue *value,
2756 const GVariantType *expected_type,
2759 return g_variant_new_boolean (!g_value_get_boolean (value));
2764 * @settings: a #GSettings object
2765 * @key: the key to bind
2766 * @object: (type GObject.Object): a #GObject
2767 * @property: the name of the property to bind
2768 * @flags: flags for the binding
2770 * Create a binding between the @key in the @settings object
2771 * and the property @property of @object.
2773 * The binding uses the default GIO mapping functions to map
2774 * between the settings and property values. These functions
2775 * handle booleans, numeric types and string types in a
2776 * straightforward way. Use g_settings_bind_with_mapping() if
2777 * you need a custom mapping, or map between types that are not
2778 * supported by the default mapping functions.
2780 * Unless the @flags include %G_SETTINGS_BIND_NO_SENSITIVITY, this
2781 * function also establishes a binding between the writability of
2782 * @key and the "sensitive" property of @object (if @object has
2783 * a boolean property by that name). See g_settings_bind_writable()
2784 * for more details about writable bindings.
2786 * Note that the lifecycle of the binding is tied to @object,
2787 * and that you can have only one binding per object property.
2788 * If you bind the same property twice on the same object, the second
2789 * binding overrides the first one.
2794 g_settings_bind (GSettings *settings,
2797 const gchar *property,
2798 GSettingsBindFlags flags)
2800 GSettingsBindGetMapping get_mapping = NULL;
2801 GSettingsBindSetMapping set_mapping = NULL;
2803 if (flags & G_SETTINGS_BIND_INVERT_BOOLEAN)
2805 get_mapping = g_settings_bind_invert_boolean_get_mapping;
2806 set_mapping = g_settings_bind_invert_boolean_set_mapping;
2808 /* can't pass this flag to g_settings_bind_with_mapping() */
2809 flags &= ~G_SETTINGS_BIND_INVERT_BOOLEAN;
2812 g_settings_bind_with_mapping (settings, key, object, property, flags,
2813 get_mapping, set_mapping, NULL, NULL);
2817 * g_settings_bind_with_mapping: (skip)
2818 * @settings: a #GSettings object
2819 * @key: the key to bind
2820 * @object: (type GObject.Object): a #GObject
2821 * @property: the name of the property to bind
2822 * @flags: flags for the binding
2823 * @get_mapping: a function that gets called to convert values
2824 * from @settings to @object, or %NULL to use the default GIO mapping
2825 * @set_mapping: a function that gets called to convert values
2826 * from @object to @settings, or %NULL to use the default GIO mapping
2827 * @user_data: data that gets passed to @get_mapping and @set_mapping
2828 * @destroy: #GDestroyNotify function for @user_data
2830 * Create a binding between the @key in the @settings object
2831 * and the property @property of @object.
2833 * The binding uses the provided mapping functions to map between
2834 * settings and property values.
2836 * Note that the lifecycle of the binding is tied to @object,
2837 * and that you can have only one binding per object property.
2838 * If you bind the same property twice on the same object, the second
2839 * binding overrides the first one.
2844 g_settings_bind_with_mapping (GSettings *settings,
2847 const gchar *property,
2848 GSettingsBindFlags flags,
2849 GSettingsBindGetMapping get_mapping,
2850 GSettingsBindSetMapping set_mapping,
2852 GDestroyNotify destroy)
2854 GSettingsBinding *binding;
2855 GObjectClass *objectclass;
2856 gchar *detailed_signal;
2857 GQuark binding_quark;
2859 g_return_if_fail (G_IS_SETTINGS (settings));
2860 g_return_if_fail (key != NULL);
2861 g_return_if_fail (G_IS_OBJECT (object));
2862 g_return_if_fail (property != NULL);
2863 g_return_if_fail (~flags & G_SETTINGS_BIND_INVERT_BOOLEAN);
2865 objectclass = G_OBJECT_GET_CLASS (object);
2867 binding = g_slice_new0 (GSettingsBinding);
2868 g_settings_schema_key_init (&binding->key, settings->priv->schema, key);
2869 binding->settings = g_object_ref (settings);
2870 binding->object = object;
2871 binding->property = g_object_class_find_property (objectclass, property);
2872 binding->user_data = user_data;
2873 binding->destroy = destroy;
2874 binding->get_mapping = get_mapping ? get_mapping : g_settings_get_mapping;
2875 binding->set_mapping = set_mapping ? set_mapping : g_settings_set_mapping;
2877 if (!(flags & (G_SETTINGS_BIND_GET | G_SETTINGS_BIND_SET)))
2878 flags |= G_SETTINGS_BIND_GET | G_SETTINGS_BIND_SET;
2880 if (binding->property == NULL)
2882 g_critical ("g_settings_bind: no property '%s' on class '%s'",
2883 property, G_OBJECT_TYPE_NAME (object));
2887 if ((flags & G_SETTINGS_BIND_GET) &&
2888 (binding->property->flags & G_PARAM_WRITABLE) == 0)
2890 g_critical ("g_settings_bind: property '%s' on class '%s' is not "
2891 "writable", binding->property->name, G_OBJECT_TYPE_NAME (object));
2894 if ((flags & G_SETTINGS_BIND_SET) &&
2895 (binding->property->flags & G_PARAM_READABLE) == 0)
2897 g_critical ("g_settings_bind: property '%s' on class '%s' is not "
2898 "readable", binding->property->name, G_OBJECT_TYPE_NAME (object));
2902 if (get_mapping == g_settings_bind_invert_boolean_get_mapping)
2904 /* g_settings_bind_invert_boolean_get_mapping() is a private
2905 * function, so if we are here it means that g_settings_bind() was
2906 * called with G_SETTINGS_BIND_INVERT_BOOLEAN.
2908 * Ensure that both sides are boolean.
2911 if (binding->property->value_type != G_TYPE_BOOLEAN)
2913 g_critical ("g_settings_bind: G_SETTINGS_BIND_INVERT_BOOLEAN "
2914 "was specified, but property '%s' on type '%s' has "
2915 "type '%s'", binding->property->name, G_OBJECT_TYPE_NAME (object),
2916 g_type_name ((binding->property->value_type)));
2920 if (!g_variant_type_equal (binding->key.type, G_VARIANT_TYPE_BOOLEAN))
2922 gchar *type_string = g_variant_type_dup_string (binding->key.type);
2923 g_critical ("g_settings_bind: G_SETTINGS_BIND_INVERT_BOOLEAN "
2924 "was specified, but key '%s' on schema '%s' has "
2925 "type '%s'", key, g_settings_schema_get_id (settings->priv->schema),
2927 g_free (type_string);
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,
2938 gchar *type_string = g_variant_type_dup_string (binding->key.type);
2939 g_critical ("g_settings_bind: property '%s' on class '%s' has type "
2940 "'%s' which is not compatible with type '%s' of key '%s' "
2941 "on schema '%s'", binding->property->name, G_OBJECT_TYPE_NAME (object),
2942 g_type_name (binding->property->value_type),
2944 g_settings_schema_get_id (settings->priv->schema));
2945 g_free (type_string);
2949 if ((flags & G_SETTINGS_BIND_SET) &&
2950 (~flags & G_SETTINGS_BIND_NO_SENSITIVITY))
2952 GParamSpec *sensitive;
2954 sensitive = g_object_class_find_property (objectclass, "sensitive");
2956 if (sensitive && sensitive->value_type == G_TYPE_BOOLEAN &&
2957 (sensitive->flags & G_PARAM_WRITABLE))
2958 g_settings_bind_writable (settings, binding->key.name, object, "sensitive", FALSE);
2961 if (flags & G_SETTINGS_BIND_SET)
2963 detailed_signal = g_strdup_printf ("notify::%s", binding->property->name);
2964 binding->property_handler_id =
2965 g_signal_connect (object, detailed_signal,
2966 G_CALLBACK (g_settings_binding_property_changed),
2968 g_free (detailed_signal);
2970 if (~flags & G_SETTINGS_BIND_GET)
2971 g_settings_binding_property_changed (object,
2976 if (flags & G_SETTINGS_BIND_GET)
2978 if (~flags & G_SETTINGS_BIND_GET_NO_CHANGES)
2980 detailed_signal = g_strdup_printf ("changed::%s", key);
2981 binding->key_handler_id =
2982 g_signal_connect (settings, detailed_signal,
2983 G_CALLBACK (g_settings_binding_key_changed),
2985 g_free (detailed_signal);
2988 g_settings_binding_key_changed (settings, binding->key.name, binding);
2991 binding_quark = g_settings_binding_quark (binding->property->name);
2992 g_object_set_qdata_full (object, binding_quark,
2993 binding, g_settings_binding_free);
2996 /* Writability binding {{{1 */
2999 GSettings *settings;
3002 const gchar *property;
3005 } GSettingsWritableBinding;
3008 g_settings_writable_binding_free (gpointer data)
3010 GSettingsWritableBinding *binding = data;
3012 g_signal_handler_disconnect (binding->settings, binding->handler_id);
3013 g_object_unref (binding->settings);
3014 g_slice_free (GSettingsWritableBinding, binding);
3018 g_settings_binding_writable_changed (GSettings *settings,
3022 GSettingsWritableBinding *binding = user_data;
3025 g_assert (settings == binding->settings);
3026 g_assert (key == binding->key);
3028 writable = g_settings_is_writable (settings, key);
3030 if (binding->inverted)
3031 writable = !writable;
3033 g_object_set (binding->object, binding->property, writable, NULL);
3037 * g_settings_bind_writable:
3038 * @settings: a #GSettings object
3039 * @key: the key to bind
3040 * @object: (type GObject.Object):a #GObject
3041 * @property: the name of a boolean property to bind
3042 * @inverted: whether to 'invert' the value
3044 * Create a binding between the writability of @key in the
3045 * @settings object and the property @property of @object.
3046 * The property must be boolean; "sensitive" or "visible"
3047 * properties of widgets are the most likely candidates.
3049 * Writable bindings are always uni-directional; changes of the
3050 * writability of the setting will be propagated to the object
3051 * property, not the other way.
3053 * When the @inverted argument is %TRUE, the binding inverts the
3054 * value as it passes from the setting to the object, i.e. @property
3055 * will be set to %TRUE if the key is not writable.
3057 * Note that the lifecycle of the binding is tied to @object,
3058 * and that you can have only one binding per object property.
3059 * If you bind the same property twice on the same object, the second
3060 * binding overrides the first one.
3065 g_settings_bind_writable (GSettings *settings,
3068 const gchar *property,
3071 GSettingsWritableBinding *binding;
3072 gchar *detailed_signal;
3075 g_return_if_fail (G_IS_SETTINGS (settings));
3077 pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (object), property);
3080 g_critical ("g_settings_bind_writable: no property '%s' on class '%s'",
3081 property, G_OBJECT_TYPE_NAME (object));
3084 if ((pspec->flags & G_PARAM_WRITABLE) == 0)
3086 g_critical ("g_settings_bind_writable: property '%s' on class '%s' is not writable",
3087 property, G_OBJECT_TYPE_NAME (object));
3091 binding = g_slice_new (GSettingsWritableBinding);
3092 binding->settings = g_object_ref (settings);
3093 binding->object = object;
3094 binding->key = g_intern_string (key);
3095 binding->property = g_intern_string (property);
3096 binding->inverted = inverted;
3098 detailed_signal = g_strdup_printf ("writable-changed::%s", key);
3099 binding->handler_id =
3100 g_signal_connect (settings, detailed_signal,
3101 G_CALLBACK (g_settings_binding_writable_changed),
3103 g_free (detailed_signal);
3105 g_object_set_qdata_full (object, g_settings_binding_quark (property),
3106 binding, g_settings_writable_binding_free);
3108 g_settings_binding_writable_changed (settings, binding->key, binding);
3112 * g_settings_unbind:
3113 * @object: (type GObject.Object): the object
3114 * @property: the property whose binding is removed
3116 * Removes an existing binding for @property on @object.
3118 * Note that bindings are automatically removed when the
3119 * object is finalized, so it is rarely necessary to call this
3125 g_settings_unbind (gpointer object,
3126 const gchar *property)
3128 GQuark binding_quark;
3130 binding_quark = g_settings_binding_quark (property);
3131 g_object_set_qdata (object, binding_quark, NULL);
3138 GObject parent_instance;
3140 GSettingsSchemaKey key;
3141 GSettings *settings;
3144 typedef GObjectClass GSettingsActionClass;
3146 static GType g_settings_action_get_type (void);
3147 static void g_settings_action_iface_init (GActionInterface *iface);
3148 G_DEFINE_TYPE_WITH_CODE (GSettingsAction, g_settings_action, G_TYPE_OBJECT,
3149 G_IMPLEMENT_INTERFACE (G_TYPE_ACTION, g_settings_action_iface_init))
3155 ACTION_PROP_PARAMETER_TYPE,
3156 ACTION_PROP_ENABLED,
3157 ACTION_PROP_STATE_TYPE,
3161 static const gchar *
3162 g_settings_action_get_name (GAction *action)
3164 GSettingsAction *gsa = (GSettingsAction *) action;
3166 return gsa->key.name;
3169 static const GVariantType *
3170 g_settings_action_get_parameter_type (GAction *action)
3172 GSettingsAction *gsa = (GSettingsAction *) action;
3173 const GVariantType *type;
3175 type = g_variant_get_type (gsa->key.default_value);
3176 if (g_variant_type_equal (type, G_VARIANT_TYPE_BOOLEAN))
3183 g_settings_action_get_enabled (GAction *action)
3185 GSettingsAction *gsa = (GSettingsAction *) action;
3187 return g_settings_is_writable (gsa->settings, gsa->key.name);
3190 static const GVariantType *
3191 g_settings_action_get_state_type (GAction *action)
3193 GSettingsAction *gsa = (GSettingsAction *) action;
3195 return g_variant_get_type (gsa->key.default_value);
3199 g_settings_action_get_state (GAction *action)
3201 GSettingsAction *gsa = (GSettingsAction *) action;
3204 value = g_settings_read_from_backend (gsa->settings, &gsa->key, FALSE, FALSE);
3207 value = g_settings_schema_key_get_translated_default (&gsa->key);
3210 value = g_variant_ref (gsa->key.default_value);
3216 g_settings_action_get_state_hint (GAction *action)
3218 GSettingsAction *gsa = (GSettingsAction *) action;
3220 /* no point in reimplementing this... */
3221 return g_settings_schema_key_get_range (&gsa->key);
3225 g_settings_action_change_state (GAction *action,
3228 GSettingsAction *gsa = (GSettingsAction *) action;
3230 if (g_settings_schema_key_type_check (&gsa->key, value) && g_settings_schema_key_range_check (&gsa->key, value))
3231 g_settings_write_to_backend (gsa->settings, &gsa->key, value);
3235 g_settings_action_activate (GAction *action,
3236 GVariant *parameter)
3238 GSettingsAction *gsa = (GSettingsAction *) action;
3240 if (g_variant_is_of_type (gsa->key.default_value, G_VARIANT_TYPE_BOOLEAN))
3244 if (parameter != NULL)
3247 old = g_settings_action_get_state (action);
3248 parameter = g_variant_new_boolean (!g_variant_get_boolean (old));
3249 g_variant_unref (old);
3252 g_action_change_state (action, parameter);
3256 g_settings_action_get_property (GObject *object, guint prop_id,
3257 GValue *value, GParamSpec *pspec)
3259 GAction *action = G_ACTION (object);
3263 case ACTION_PROP_NAME:
3264 g_value_set_string (value, g_settings_action_get_name (action));
3267 case ACTION_PROP_PARAMETER_TYPE:
3268 g_value_set_boxed (value, g_settings_action_get_parameter_type (action));
3271 case ACTION_PROP_ENABLED:
3272 g_value_set_boolean (value, g_settings_action_get_enabled (action));
3275 case ACTION_PROP_STATE_TYPE:
3276 g_value_set_boxed (value, g_settings_action_get_state_type (action));
3279 case ACTION_PROP_STATE:
3280 g_value_set_variant (value, g_settings_action_get_state (action));
3284 g_assert_not_reached ();
3289 g_settings_action_finalize (GObject *object)
3291 GSettingsAction *gsa = (GSettingsAction *) object;
3293 g_signal_handlers_disconnect_by_data (gsa->settings, gsa);
3294 g_object_unref (gsa->settings);
3295 g_settings_schema_key_clear (&gsa->key);
3297 G_OBJECT_CLASS (g_settings_action_parent_class)
3298 ->finalize (object);
3302 g_settings_action_init (GSettingsAction *gsa)
3307 g_settings_action_iface_init (GActionInterface *iface)
3309 iface->get_name = g_settings_action_get_name;
3310 iface->get_parameter_type = g_settings_action_get_parameter_type;
3311 iface->get_enabled = g_settings_action_get_enabled;
3312 iface->get_state_type = g_settings_action_get_state_type;
3313 iface->get_state = g_settings_action_get_state;
3314 iface->get_state_hint = g_settings_action_get_state_hint;
3315 iface->change_state = g_settings_action_change_state;
3316 iface->activate = g_settings_action_activate;
3320 g_settings_action_class_init (GSettingsActionClass *class)
3322 class->get_property = g_settings_action_get_property;
3323 class->finalize = g_settings_action_finalize;
3325 g_object_class_override_property (class, ACTION_PROP_NAME, "name");
3326 g_object_class_override_property (class, ACTION_PROP_PARAMETER_TYPE, "parameter-type");
3327 g_object_class_override_property (class, ACTION_PROP_ENABLED, "enabled");
3328 g_object_class_override_property (class, ACTION_PROP_STATE_TYPE, "state-type");
3329 g_object_class_override_property (class, ACTION_PROP_STATE, "state");
3333 g_settings_action_changed (GSettings *settings,
3337 g_object_notify (user_data, "state");
3341 g_settings_action_enabled_changed (GSettings *settings,
3345 g_object_notify (user_data, "enabled");
3349 * g_settings_create_action:
3350 * @settings: a #GSettings
3351 * @key: the name of a key in @settings
3353 * Creates a #GAction corresponding to a given #GSettings key.
3355 * The action has the same name as the key.
3357 * The value of the key becomes the state of the action and the action
3358 * is enabled when the key is writable. Changing the state of the
3359 * action results in the key being written to. Changes to the value or
3360 * writability of the key cause appropriate change notifications to be
3361 * emitted for the action.
3363 * For boolean-valued keys, action activations take no parameter and
3364 * result in the toggling of the value. For all other types,
3365 * activations take the new value for the key (which must have the
3368 * Returns: (transfer full): a new #GAction
3373 g_settings_create_action (GSettings *settings,
3376 GSettingsAction *gsa;
3377 gchar *detailed_signal;
3379 g_return_val_if_fail (G_IS_SETTINGS (settings), NULL);
3380 g_return_val_if_fail (key != NULL, NULL);
3382 gsa = g_object_new (g_settings_action_get_type (), NULL);
3383 gsa->settings = g_object_ref (settings);
3384 g_settings_schema_key_init (&gsa->key, settings->priv->schema, key);
3386 detailed_signal = g_strdup_printf ("changed::%s", key);
3387 g_signal_connect (settings, detailed_signal, G_CALLBACK (g_settings_action_changed), gsa);
3388 g_free (detailed_signal);
3389 detailed_signal = g_strdup_printf ("writable-changed::%s", key);
3390 g_signal_connect (settings, detailed_signal, G_CALLBACK (g_settings_action_enabled_changed), gsa);
3391 g_free (detailed_signal);
3393 return G_ACTION (gsa);
3398 /* vim:set foldmethod=marker: */