* the names must begin with a lowercase character, must not end
* with a '-', and must not contain consecutive dashes.
*
+ * GSettings supports change notification. The primary mechanism to
+ * watch for changes is to connect to the "changed" signal. You can
+ * optionally watch for changes on only a single key by using a signal
+ * detail. Signals are only guaranteed to be emitted for a given key
+ * after you have read the value of that key while a signal handler was
+ * connected for that key. Signals may or may not be emitted in the
+ * case that the key "changed" to the value that you had previously
+ * read. Signals may be reported in additional cases as well and the
+ * "changed" signal should really be treated as "may have changed".
+ *
* Similar to GConf, the default values in GSettings schemas can be
* localized, but the localized values are stored in gettext catalogs
* and looked up with the domain that is specified in the
- * <tag class="attribute">gettext-domain</tag> attribute of the
- * <tag class="starttag">schemalist</tag> or <tag class="starttag">schema</tag>
- * elements and the category that is specified in the l10n attribute of the
- * <tag class="starttag">key</tag> element.
+ * gettext-domain attribute of the <schemalist> or <schema>
+ * elements and the category that is specified in the l10n attribute of
+ * the <key> element.
*
* GSettings uses schemas in a compact binary form that is created
- * by the <link linkend="glib-compile-schemas">glib-compile-schemas</link>
+ * by the [glib-compile-schemas][glib-compile-schemas]
* utility. The input is a schema description in an XML format.
*
- * A DTD for the gschema XML format can be found here: <ulink url="https://git.gnome.org/browse/glib/tree/gio/gschema.dtd">gschema.dtd</ulink>
- *
- * The <link linkend="glib-compile-schemas">glib-compile-schemas</link>
- * tool expects schema files to have the extension `.gschema.xml`.
- *
- * At runtime, schemas are identified by their id (as specified
- * in the <tag class="attribute">id</tag> attribute of the
- * <tag class="starttag">schema</tag> element). The
- * convention for schema ids is to use a dotted name, similar in
- * style to a D-Bus bus name, e.g. "org.gnome.SessionManager". In particular,
- * if the settings are for a specific service that owns a D-Bus bus name,
- * the D-Bus bus name and schema id should match. For schemas which deal
- * with settings not associated with one named application, the id should
- * not use StudlyCaps, e.g. "org.gnome.font-rendering".
- *
- * In addition to #GVariant types, keys can have types that have enumerated
- * types. These can be described by a <tag class="starttag">choice</tag>,
- * <tag class="starttag">enum</tag> or <tag class="starttag">flags</tag> element, see
- * <xref linkend="schema-enumerated"/>. The underlying type of
- * such a key is string, but you can use g_settings_get_enum(),
- * g_settings_set_enum(), g_settings_get_flags(), g_settings_set_flags()
- * access the numeric values corresponding to the string value of enum
- * and flags keys.
+ * A DTD for the gschema XML format can be found here:
+ * [gschema.dtd](https://git.gnome.org/browse/glib/tree/gio/gschema.dtd)
+ *
+ * The [glib-compile-schemas][glib-compile-schemas] tool expects schema
+ * files to have the extension `.gschema.xml`.
+ *
+ * At runtime, schemas are identified by their id (as specified in the
+ * id attribute of the <schema> element). The convention for schema
+ * ids is to use a dotted name, similar in style to a D-Bus bus name,
+ * e.g. "org.gnome.SessionManager". In particular, if the settings are
+ * for a specific service that owns a D-Bus bus name, the D-Bus bus name
+ * and schema id should match. For schemas which deal with settings not
+ * associated with one named application, the id should not use
+ * StudlyCaps, e.g. "org.gnome.font-rendering".
+ *
+ * In addition to #GVariant types, keys can have types that have
+ * enumerated types. These can be described by a <choice>,
+ * <enum> or <flags> element, as seen in the
+ * [example][schema-enumerated]. The underlying type of such a key
+ * is string, but you can use g_settings_get_enum(), g_settings_set_enum(),
+ * g_settings_get_flags(), g_settings_set_flags() access the numeric values
+ * corresponding to the string value of enum and flags keys.
*
* An example for default value:
* |[
* an application. Sometimes, it is necessary for a vendor or distributor
* to adjust these defaults. Since patching the XML source for the schema
* is inconvenient and error-prone,
- * <link linkend="glib-compile-schemas">glib-compile-schemas</link> reads
- * so-called 'vendor override' files. These are keyfiles in the same
- * directory as the XML schema sources which can override default values.
- * The schema id serves as the group name in the key file, and the values
- * are expected in serialized GVariant form, as in the following example:
+ * [glib-compile-schemas][glib-compile-schemas] reads so-called vendor
+ * override' files. These are keyfiles in the same directory as the XML
+ * schema sources which can override default values. The schema id serves
+ * as the group name in the key file, and the values are expected in
+ * serialized GVariant form, as in the following example:
* |[
* [org.gtk.Example]
* key1='string'
GSettingsSchema *schema;
gchar *path;
+ gboolean is_subscribed;
+
GDelayedSettingsBackend *delayed;
};
return FALSE;
}
+static gboolean
+g_settings_has_signal_handlers (GSettings *settings)
+{
+ GSettingsClass *class = G_SETTINGS_GET_CLASS (settings);
+
+ if (class->change_event != g_settings_real_change_event ||
+ class->writable_change_event != g_settings_real_writable_change_event)
+ return TRUE;
+
+ if (g_signal_has_handler_pending (settings, g_settings_signals[SIGNAL_WRITABLE_CHANGE_EVENT], 0, TRUE) ||
+ g_signal_has_handler_pending (settings, g_settings_signals[SIGNAL_WRITABLE_CHANGED], 0, TRUE) ||
+ g_signal_has_handler_pending (settings, g_settings_signals[SIGNAL_CHANGE_EVENT], 0, TRUE) ||
+ g_signal_has_handler_pending (settings, g_settings_signals[SIGNAL_CHANGED], 0, TRUE))
+ return TRUE;
+
+ /* None of that? Then surely nobody is watching.... */
+ return FALSE;
+}
+
+
static void
settings_backend_changed (GObject *target,
GSettingsBackend *backend,
settings_backend_keys_changed (GObject *target,
GSettingsBackend *backend,
const gchar *path,
- const gchar * const *items,
- gpointer origin_tag)
+ gpointer origin_tag,
+ const gchar * const *items)
{
GSettings *settings = G_SETTINGS (target);
gboolean ignore_this;
g_settings_backend_watch (settings->priv->backend,
&listener_vtable, G_OBJECT (settings),
settings->priv->main_context);
- g_settings_backend_subscribe (settings->priv->backend,
- settings->priv->path);
}
static void
{
GSettings *settings = G_SETTINGS (object);
- g_settings_backend_unsubscribe (settings->priv->backend,
- settings->priv->path);
+ if (settings->priv->is_subscribed)
+ g_settings_backend_unsubscribe (settings->priv->backend,
+ settings->priv->path);
+
g_main_context_unref (settings->priv->main_context);
g_object_unref (settings->priv->backend);
g_settings_schema_unref (settings->priv->schema);
GVariant *fixup;
gchar *path;
+ /* If we are not yet watching for changes, consider doing it now... */
+ if (!settings->priv->is_subscribed && g_settings_has_signal_handlers (settings))
+ {
+ g_settings_backend_subscribe (settings->priv->backend, settings->priv->path);
+ settings->priv->is_subscribed = TRUE;
+ }
+
path = g_strconcat (settings->priv->path, key->name, NULL);
if (user_value_only)
value = g_settings_backend_read_user_value (settings->priv->backend, path, key->type);
/**
* g_settings_get_child:
* @settings: a #GSettings object
- * @name: the name of the 'child' schema
+ * @name: the name of the child schema
*
- * Creates a 'child' settings object which has a base path of
- * <replaceable>base-path</replaceable>/@name, where
- * <replaceable>base-path</replaceable> is the base path of @settings.
+ * Creates a child settings object which has a base path of
+ * `base-path/@name`, where `base-path` is the base path of
+ * @settings.
*
* The schema for the child settings object must have been declared
- * in the schema of @settings using a <tag class="starttag">child</tag> element.
+ * in the schema of @settings using a <child> element.
*
* Returns: (transfer full): a 'child' settings object
*
projects / platform / upstream / glib.git / blobdiff