gio/gsettings.c

   1 /*
   2  * Copyright © 2009, 2010 Codethink Limited
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the licence, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17  * Boston, MA 02111-1307, USA.
  18  *
  19  * Author: Ryan Lortie <desrt@desrt.ca>
  20  */
  21
  22 #include "config.h"
  23 #include <glib.h>
  24 #include <glibintl.h>
  25 #include <locale.h>
  26
  27 #include "gsettings.h"
  28
  29 #include "gdelayedsettingsbackend.h"
  30 #include "gsettingsbackendinternal.h"
  31 #include "gsettings-mapping.h"
  32 #include "gio-marshal.h"
  33 #include "gsettingsschema.h"
  34
  35 #include <string.h>
  36
  37 #include "gioalias.h"
  38
  39 /**
  40  * SECTION:gsettings
  41  * @short_description: a high-level API for application settings
  42  *
  43  * The #GSettings class provides a convenient API for storing and retrieving
  44  * application settings.
  45  *
  46  * When creating a GSettings instance, you have to specify a schema
  47  * that describes the keys in your settings and their types and default
  48  * values, as well as some other information.
  49  *
  50  * Normally, a schema has as fixed path that determines where the settings
  51  * are stored in the conceptual global tree of settings. However, schemas
  52  * can also be 'relocatable', i.e. not equipped with a fixed path. This is
  53  * useful e.g. when the schema describes an 'account', and you want to be
  54  * able to store a arbitrary number of accounts.
  55  *
  56  * Unlike other configuration systems (like GConf), GSettings does not
  57  * restrict keys to basic types like strings and numbers. GSettings stores
  58  * values as #GVariant, and allows any #GVariantType for keys. Key names
  59  * are restricted to lowercase characters, numbers and '-'. Furthermore,
  60  * the names must begin with a lowercase character, must not end
  61  * with a '-', and must not contain consecutive dashes. Key names can
  62  * be up to 32 characters long.
  63  *
  64  * Similar to GConf, the default values in GSettings schemas can be
  65  * localized, but the localized values are stored in gettext catalogs
  66  * and looked up with the domain that is specified in the gettext-domain
  67  * attribute of the <tag>schemalist</tag> or <tag>schema</tag> elements
  68  * and the category that is specified in the l10n attribute of the
  69  * <tag>key</tag> element.
  70  *
  71  * GSettings uses schemas in a compact binary form that is created
  72  * by the gschema-compile utility. The input is a schema description in
  73  * an XML format that can be described by the following DTD:
  74  * |[<![CDATA[
  75  * <!ELEMENT schemalist (schema*) >
  76  * <!ATTLIST schemalist gettext-domain #IMPLIED >
  77  *
  78  * <!ELEMENT schema (key|child)* >
  79  * <!ATTLIST schema id             CDATA #REQUIRED
  80  *                  path           CDATA #IMPLIED
  81  *                  gettext-domain CDATA #IMPLIED >
  82  *
  83  * <!ELEMENT key (default|summary?|description?|range?|choices?) >
  84  * <!-- name can only contain lowercase letters, numbers and '-' -->
  85  * <!-- type must be a GVariant type string -->
  86  * <!ATTLIST key name CDATA #REQUIRED
  87  *               type CDATA #REQUIRED >
  88  *
  89  * <!-- the default value is specified a a serialized GVariant,
  90  *      i.e. you have to include the quotes when specifying a string -->
  91  * <!ELEMENT default (#PCDATA) >
  92  * <!-- the presence of the l10n attribute marks a default value for
  93  *      translation, its value is the gettext category to use -->
  94  * <!-- if context is present, it specifies msgctxt to use -->
  95  * <!ATTLIST default l10n (messages|time) #IMPLIED
  96  *                   context CDATA #IMPLIED >
  97  *
  98  * <!ELEMENT summary (#PCDATA) >
  99  * <!ELEMENT description (#PCDATA) >
 100  *
 101  * <!ELEMENT range (min,max)  >
 102  * <!ELEMENT min (#PCDATA) >
 103  * <!ELEMENT max (#PCDATA) >
 104  *
 105  * <!ELEMENT choices (choice+) >
 106  * <!ELEMENT choice (alias?) >
 107  * <!ATTLIST choice value CDATA #REQUIRED >
 108  * <!ELEMENT choice (alias?) >
 109  * <!ELEMENT alias EMPTY >
 110  * <!ATTLIST alias value CDATA #REQUIRED >
 111  *
 112  * <!ELEMENT child EMPTY >
 113  * <!ATTLIST child name  CDATA #REQUIRED
 114  *                 schema CDATA #REQUIRED >
 115  * ]]>
 116  * ]|
 117  *
 118  * <refsect2>
 119  *  <title>Binding</title>
 120  *   <para>
 121  *    A very convenient feature of GSettings lets you bind #GObject properties
 122  *    directly to settings, using g_settings_bind(). Once a GObject property
 123  *    has been bound to a setting, changes on either side are automatically
 124  *    propagated to the other side. GSettings handles details like
 125  *    mapping between GObject and GVariant types, and preventing infinite
 126  *    cycles.
 127  *   </para>
 128  *   <para>
 129  *    This makes it very easy to hook up a preferences dialog to the
 130  *    underlying settings. To make this even more convenient, GSettings
 131  *    looks for a boolean property with the name "sensitivity" and
 132  *    automatically binds it to the writability of the bound setting.
 133  *    If this 'magic' gets in the way, it can be suppressed with the
 134  *    #G_SETTINGS_BIND_NO_SENSITIVITY flag.
 135  *   </para>
 136  *  </refsect2>
 137  */
 138
 139 struct _GSettingsPrivate
 140 {
 141   GSettingsBackend *backend;
 142   GSettingsSchema *schema;
 143   gchar *schema_name;
 144   gchar *context;
 145   gchar *path;
 146
 147   GDelayedSettingsBackend *delayed;
 148 };
 149
 150 enum
 151 {
 152   PROP_0,
 153   PROP_BACKEND,
 154   PROP_SCHEMA,
 155   PROP_CONTEXT,
 156   PROP_PATH,
 157   PROP_HAS_UNAPPLIED,
 158 };
 159
 160 enum
 161 {
 162   SIGNAL_WRITABLE_CHANGE_EVENT,
 163   SIGNAL_WRITABLE_CHANGED,
 164   SIGNAL_CHANGE_EVENT,
 165   SIGNAL_CHANGED,
 166   N_SIGNALS
 167 };
 168
 169 static guint g_settings_signals[N_SIGNALS];
 170
 171 G_DEFINE_TYPE (GSettings, g_settings, G_TYPE_OBJECT)
 172
 173 static gboolean
 174 g_settings_real_change_event (GSettings    *settings,
 175                               const GQuark *keys,
 176                               gint          n_keys)
 177 {
 178   gint i;
 179
 180   if (keys == NULL)
 181     keys = g_settings_schema_list (settings->priv->schema, &n_keys);
 182
 183   for (i = 0; i < n_keys; i++)
 184     g_signal_emit (settings, g_settings_signals[SIGNAL_CHANGED],
 185                    keys[i], g_quark_to_string (keys[i]));
 186
 187   return FALSE;
 188 }
 189
 190 static gboolean
 191 g_settings_real_writable_change_event (GSettings *settings,
 192                                        GQuark     key)
 193 {
 194   const GQuark *keys = &key;
 195   gint n_keys = 1;
 196   gint i;
 197
 198   if (key == 0)
 199     keys = g_settings_schema_list (settings->priv->schema, &n_keys);
 200
 201   for (i = 0; i < n_keys; i++)
 202     {
 203       const gchar *string = g_quark_to_string (keys[i]);
 204
 205       g_signal_emit (settings, g_settings_signals[SIGNAL_WRITABLE_CHANGED],
 206                      keys[i], string);
 207       g_signal_emit (settings, g_settings_signals[SIGNAL_CHANGED],
 208                      keys[i], string);
 209     }
 210
 211   return FALSE;
 212 }
 213
 214 static void
 215 settings_backend_changed (GSettingsBackend    *backend,
 216                           const gchar         *key,
 217                           gpointer             origin_tag,
 218                           gpointer             user_data)
 219 {
 220   GSettings *settings = G_SETTINGS (user_data);
 221   gboolean ignore_this;
 222   gint i;
 223
 224   g_assert (settings->priv->backend == backend);
 225
 226   for (i = 0; key[i] == settings->priv->path[i]; i++);
 227
 228   if (settings->priv->path[i] == '\0' &&
 229       g_settings_schema_has_key (settings->priv->schema, key + i))
 230     {
 231       GQuark quark;
 232
 233       quark = g_quark_from_string (key + i);
 234       g_signal_emit (settings, g_settings_signals[SIGNAL_CHANGE_EVENT],
 235                      0, &quark, 1, &ignore_this);
 236     }
 237 }
 238
 239 static void
 240 settings_backend_path_changed (GSettingsBackend *backend,
 241                                const gchar      *path,
 242                                gpointer          origin_tag,
 243                                gpointer          user_data)
 244 {
 245   GSettings *settings = G_SETTINGS (user_data);
 246   gboolean ignore_this;
 247
 248   g_assert (settings->priv->backend == backend);
 249
 250   if (g_str_has_prefix (settings->priv->path, path))
 251     g_signal_emit (settings, g_settings_signals[SIGNAL_CHANGE_EVENT],
 252                    0, NULL, 0, &ignore_this);
 253 }
 254
 255 static void
 256 settings_backend_keys_changed (GSettingsBackend    *backend,
 257                                const gchar         *path,
 258                                const gchar * const *items,
 259                                gpointer             origin_tag,
 260                                gpointer             user_data)
 261 {
 262   GSettings *settings = G_SETTINGS (user_data);
 263   gboolean ignore_this;
 264   gint i;
 265
 266   g_assert (settings->priv->backend == backend);
 267
 268   for (i = 0; settings->priv->path[i] &&
 269               settings->priv->path[i] == path[i]; i++);
 270
 271   if (path[i] == '\0')
 272     {
 273       GQuark quarks[256];
 274       gint j, l = 0;
 275
 276       for (j = 0; items[j]; j++)
 277          {
 278            const gchar *item = items[j];
 279            gint k;
 280
 281            for (k = 0; item[k] == settings->priv->path[i + k]; k++);
 282
 283            if (settings->priv->path[i + k] == '\0' &&
 284                g_settings_schema_has_key (settings->priv->schema, item + k))
 285              quarks[l++] = g_quark_from_string (item + k);
 286
 287            /* "256 quarks ought to be enough for anybody!"
 288             * If this bites you, I'm sorry.  Please file a bug.
 289             */
 290            g_assert (l < 256);
 291          }
 292
 293       if (l > 0)
 294         g_signal_emit (settings, g_settings_signals[SIGNAL_CHANGE_EVENT],
 295                        0, quarks, l, &ignore_this);
 296     }
 297 }
 298
 299 static void
 300 settings_backend_writable_changed (GSettingsBackend *backend,
 301                                    const gchar      *key,
 302                                    gpointer          user_data)
 303 {
 304   GSettings *settings = G_SETTINGS (user_data);
 305   gboolean ignore_this;
 306   gint i;
 307
 308   g_assert (settings->priv->backend == backend);
 309
 310   for (i = 0; key[i] == settings->priv->path[i]; i++);
 311
 312   if (settings->priv->path[i] == '\0' &&
 313       g_settings_schema_has_key (settings->priv->schema, key + i))
 314     g_signal_emit (settings, g_settings_signals[SIGNAL_WRITABLE_CHANGE_EVENT],
 315                    0, g_quark_from_string (key + i), &ignore_this);
 316 }
 317
 318 static void
 319 settings_backend_path_writable_changed (GSettingsBackend *backend,
 320                                         const gchar      *path,
 321                                         gpointer          user_data)
 322 {
 323   GSettings *settings = G_SETTINGS (user_data);
 324   gboolean ignore_this;
 325
 326   g_assert (settings->priv->backend == backend);
 327
 328   if (g_str_has_prefix (settings->priv->path, path))
 329     g_signal_emit (settings, g_settings_signals[SIGNAL_WRITABLE_CHANGE_EVENT],
 330                    0, (GQuark) 0, &ignore_this);
 331 }
 332
 333 static void
 334 g_settings_constructed (GObject *object)
 335 {
 336   GSettings *settings = G_SETTINGS (object);
 337   const gchar *schema_path;
 338
 339   settings->priv->schema = g_settings_schema_new (settings->priv->schema_name);
 340   schema_path = g_settings_schema_get_path (settings->priv->schema);
 341
 342   if (settings->priv->path && schema_path && strcmp (settings->priv->path, schema_path) != 0)
 343     g_error ("settings object created with schema '%s' and path '%s', but "
 344              "path '%s' is specified by schema",
 345              settings->priv->schema_name, settings->priv->path, schema_path);
 346
 347   if (settings->priv->path == NULL)
 348     {
 349       if (schema_path == NULL)
 350         g_error ("attempting to create schema '%s' without a path",
 351                  settings->priv->schema_name);
 352
 353       settings->priv->path = g_strdup (schema_path);
 354     }
 355
 356   settings->priv->backend = g_settings_backend_get_with_context (settings->priv->context);
 357   g_settings_backend_watch (settings->priv->backend,
 358                             settings_backend_changed,
 359                             settings_backend_path_changed,
 360                             settings_backend_keys_changed,
 361                             settings_backend_writable_changed,
 362                             settings_backend_path_writable_changed,
 363                             settings);
 364   g_settings_backend_subscribe (settings->priv->backend,
 365                                 settings->priv->path);
 366 }
 367
 368 static void
 369 g_settings_init (GSettings *settings)
 370 {
 371   settings->priv = G_TYPE_INSTANCE_GET_PRIVATE (settings,
 372                                                 G_TYPE_SETTINGS,
 373                                                 GSettingsPrivate);
 374 }
 375
 376 /**
 377  * g_settings_delay:
 378  * @settings: a #GSettings object
 379  *
 380  * Changes the #GSettings object into 'delay-apply' mode. In this
 381  * mode, changes to @settings are not immediately propagated to the
 382  * backend, but kept locally until g_settings_apply() is called.
 383  *
 384  * Since: 2.26
 385  */
 386 void
 387 g_settings_delay (GSettings *settings)
 388 {
 389   if (settings->priv->delayed)
 390     return;
 391
 392   settings->priv->delayed =
 393     g_delayed_settings_backend_new (settings->priv->backend, settings);
 394   g_settings_backend_unwatch (settings->priv->backend, settings);
 395   g_object_unref (settings->priv->backend);
 396
 397   settings->priv->backend = G_SETTINGS_BACKEND (settings->priv->delayed);
 398   g_settings_backend_watch (settings->priv->backend,
 399                             settings_backend_changed,
 400                             settings_backend_path_changed,
 401                             settings_backend_keys_changed,
 402                             settings_backend_writable_changed,
 403                             settings_backend_path_writable_changed,
 404                             settings);
 405 }
 406
 407 /**
 408  * g_settings_apply:
 409  * @settings: a #GSettings instance
 410  *
 411  * Applies any changes that have been made to the settings.  This
 412  * function does nothing unless @settings is in 'delay-apply' mode;
 413  * see g_settings_set_delay_apply().  In the normal case settings are
 414  * always applied immediately.
 415  **/
 416 void
 417 g_settings_apply (GSettings *settings)
 418 {
 419   if (settings->priv->delayed)
 420     {
 421       GDelayedSettingsBackend *delayed;
 422
 423       delayed = G_DELAYED_SETTINGS_BACKEND (settings->priv->backend);
 424       g_delayed_settings_backend_apply (delayed);
 425     }
 426 }
 427
 428 /**
 429  * g_settings_revert:
 430  * @settings: a #GSettings instance
 431  *
 432  * Reverts all non-applied changes to the settings.  This function
 433  * does nothing unless @settings is in 'delay-apply' mode; see
 434  * g_settings_set_delay_apply().  In the normal case settings are
 435  * always applied immediately.
 436  *
 437  * Change notifications will be emitted for affected keys.
 438  **/
 439 void
 440 g_settings_revert (GSettings *settings)
 441 {
 442   if (settings->priv->delayed)
 443     {
 444       GDelayedSettingsBackend *delayed;
 445
 446       delayed = G_DELAYED_SETTINGS_BACKEND (settings->priv->backend);
 447       g_delayed_settings_backend_revert (delayed);
 448     }
 449 }
 450
 451 static void
 452 g_settings_set_property (GObject      *object,
 453                          guint         prop_id,
 454                          const GValue *value,
 455                          GParamSpec   *pspec)
 456 {
 457   GSettings *settings = G_SETTINGS (object);
 458
 459   switch (prop_id)
 460     {
 461     case PROP_SCHEMA:
 462       g_assert (settings->priv->schema_name == NULL);
 463       settings->priv->schema_name = g_value_dup_string (value);
 464       break;
 465
 466     case PROP_PATH:
 467       settings->priv->path = g_value_dup_string (value);
 468       break;
 469
 470     case PROP_CONTEXT:
 471       settings->priv->context = g_value_dup_string (value);
 472       break;
 473
 474     default:
 475       g_assert_not_reached ();
 476     }
 477 }
 478
 479 /**
 480  * g_settings_get_has_unapplied:
 481  * @settings: a #GSettings object
 482  * @returns: %TRUE if @settings has unapplied changes
 483  *
 484  * Returns whether the #GSettings object has any unapplied
 485  * changes.  This can only be the case if it is in 'delayed-apply' mode.
 486  *
 487  * Since: 2.26
 488  */
 489 gboolean
 490 g_settings_get_has_unapplied (GSettings *settings)
 491 {
 492   return settings->priv->delayed &&
 493          g_delayed_settings_backend_get_has_unapplied (
 494            G_DELAYED_SETTINGS_BACKEND (settings->priv->backend));
 495 }
 496
 497 static void
 498 g_settings_get_property (GObject    *object,
 499                          guint       prop_id,
 500                          GValue     *value,
 501                          GParamSpec *pspec)
 502 {
 503   GSettings *settings = G_SETTINGS (object);
 504
 505   switch (prop_id)
 506     {
 507      case PROP_SCHEMA:
 508       g_value_set_object (value, settings->priv->schema);
 509       break;
 510
 511      case PROP_HAS_UNAPPLIED:
 512       g_value_set_boolean (value, g_settings_get_has_unapplied (settings));
 513       break;
 514
 515      default:
 516       g_assert_not_reached ();
 517     }
 518 }
 519
 520 static void
 521 g_settings_finalize (GObject *object)
 522 {
 523   GSettings *settings = G_SETTINGS (object);
 524
 525   g_settings_backend_unwatch (settings->priv->backend, settings);
 526   g_settings_backend_unsubscribe (settings->priv->backend,
 527                                   settings->priv->path);
 528   g_object_unref (settings->priv->backend);
 529   g_object_unref (settings->priv->schema);
 530   g_free (settings->priv->schema_name);
 531   g_free (settings->priv->path);
 532 }
 533
 534 static void
 535 g_settings_class_init (GSettingsClass *class)
 536 {
 537   GObjectClass *object_class = G_OBJECT_CLASS (class);
 538
 539   class->writable_change_event = g_settings_real_writable_change_event;
 540   class->change_event = g_settings_real_change_event;
 541
 542   object_class->set_property = g_settings_set_property;
 543   object_class->get_property = g_settings_get_property;
 544   object_class->constructed = g_settings_constructed;
 545   object_class->finalize = g_settings_finalize;
 546
 547   g_type_class_add_private (object_class, sizeof (GSettingsPrivate));
 548
 549   /**
 550    * GSettings::changed:
 551    * @settings: the object on which the signal was emitted
 552    * @key: the name of the key that changed
 553    *
 554    * The "changed" signal is emitted when a key has potentially changed.
 555    * You should call one of the g_settings_get() calls to check the new
 556    * value.
 557    *
 558    * This signal supports detailed connections.  You can connect to the
 559    * detailed signal "changed::x" in order to only receive callbacks
 560    * when key "x" changes.
 561    */
 562   g_settings_signals[SIGNAL_CHANGED] =
 563     g_signal_new ("changed", G_TYPE_SETTINGS,
 564                   G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
 565                   G_STRUCT_OFFSET (GSettingsClass, changed),
 566                   NULL, NULL, g_cclosure_marshal_VOID__STRING, G_TYPE_NONE,
 567                   1, G_TYPE_STRING | G_SIGNAL_TYPE_STATIC_SCOPE);
 568
 569   /**
 570    * GSettings::change-event:
 571    * @settings: the object on which the signal was emitted
 572    * @keys: an array of #GQuark<!-- -->s for the changed keys, or %NULL
 573    * @n_keys: the length of the @keys array, or 0
 574    * @returns: %TRUE to stop other handlers from being invoked for the
 575    *           event. FALSE to propagate the event further.
 576    *
 577    * The "change-event" signal is emitted once per change event that
 578    * affects this settings object.  You should connect to this signal
 579    * only if you are interested in viewing groups of changes before they
 580    * are split out into multiple emissions of the "changed" signal.
 581    * For most use cases it is more appropriate to use the "changed" signal.
 582    *
 583    * In the event that the change event applies to one or more specified
 584    * keys, @keys will be an array of #GQuark of length @n_keys.  In the
 585    * event that the change event applies to the #GSettings object as a
 586    * whole (ie: potentially every key has been changed) then @keys will
 587    * be %NULL and @n_keys will be 0.
 588    *
 589    * The default handler for this signal invokes the "changed" signal
 590    * for each affected key.  If any other connected handler returns
 591    * %TRUE then this default functionality will be supressed.
 592    */
 593   g_settings_signals[SIGNAL_CHANGE_EVENT] =
 594     g_signal_new ("change-event", G_TYPE_SETTINGS,
 595                   G_SIGNAL_RUN_LAST,
 596                   G_STRUCT_OFFSET (GSettingsClass, change_event),
 597                   g_signal_accumulator_true_handled, NULL,
 598                   _gio_marshal_BOOL__POINTER_INT,
 599                   G_TYPE_BOOLEAN, 2, G_TYPE_POINTER, G_TYPE_INT);
 600
 601   /**
 602    * GSettings::writable-changed:
 603    * @settings: the object on which the signal was emitted
 604    * @key: the key
 605    *
 606    * The "writable-changed" signal is emitted when the writability of a
 607    * key has potentially changed.  You should call
 608    * g_settings_is_writable() in order to determine the new status.
 609    *
 610    * This signal supports detailed connections.  You can connect to the
 611    * detailed signal "writable-changed::x" in order to only receive
 612    * callbacks when the writability of "x" changes.
 613    */
 614   g_settings_signals[SIGNAL_WRITABLE_CHANGED] =
 615     g_signal_new ("writable-changed", G_TYPE_SETTINGS,
 616                   G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
 617                   G_STRUCT_OFFSET (GSettingsClass, changed),
 618                   NULL, NULL, g_cclosure_marshal_VOID__STRING, G_TYPE_NONE,
 619                   1, G_TYPE_STRING | G_SIGNAL_TYPE_STATIC_SCOPE);
 620
 621   /**
 622    * GSettings::writable-change-event:
 623    * @settings: the object on which the signal was emitted
 624    * @key: the quark of the key, or 0
 625    * @returns: %TRUE to stop other handlers from being invoked for the
 626    *           event. FALSE to propagate the event further.
 627    *
 628    * The "writable-change-event" signal is emitted once per writability
 629    * change event that affects this settings object.  You should connect
 630    * to this signal if you are interested in viewing groups of changes
 631    * before they are split out into multiple emissions of the
 632    * "writable-changed" signal.  For most use cases it is more
 633    * appropriate to use the "writable-changed" signal.
 634    *
 635    * In the event that the writability change applies only to a single
 636    * key, @key will be set to the #GQuark for that key.  In the event
 637    * that the writability change affects the entire settings object,
 638    * @key will be 0.
 639    *
 640    * The default handler for this signal invokes the "writable-changed"
 641    * and "changed" signals for each affected key.  This is done because
 642    * changes in writability might also imply changes in value (if for
 643    * example, a new mandatory setting is introduced).  If any other
 644    * connected handler returns %TRUE then this default functionality
 645    * will be supressed.
 646    */
 647   g_settings_signals[SIGNAL_WRITABLE_CHANGE_EVENT] =
 648     g_signal_new ("writable-change-event", G_TYPE_SETTINGS,
 649                   G_SIGNAL_RUN_LAST,
 650                   G_STRUCT_OFFSET (GSettingsClass, writable_change_event),
 651                   g_signal_accumulator_true_handled, NULL,
 652                   _gio_marshal_BOOLEAN__UINT, G_TYPE_BOOLEAN, 1, G_TYPE_UINT);
 653
 654   /**
 655    * GSettings:context:
 656    *
 657    * The name of the context that the settings are stored in.
 658    */
 659   g_object_class_install_property (object_class, PROP_CONTEXT,
 660     g_param_spec_string ("context",
 661                          P_("Context name"),
 662                          P_("The name of the context for this settings object"),
 663                          "", G_PARAM_CONSTRUCT_ONLY |
 664                          G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 665
 666   /**
 667    * GSettings:schema:
 668    *
 669    * The name of the schema that describes the types of keys
 670    * for this #GSettings object.
 671    */
 672   g_object_class_install_property (object_class, PROP_SCHEMA,
 673     g_param_spec_string ("schema",
 674                          P_("Schema name"),
 675                          P_("The name of the schema for this settings object"),
 676                          NULL,
 677                          G_PARAM_CONSTRUCT_ONLY |
 678                          G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 679
 680    /**
 681     * GSettings:path:
 682     *
 683     * The path within the backend where the settings are stored.
 684     */
 685    g_object_class_install_property (object_class, PROP_PATH,
 686      g_param_spec_string ("path",
 687                           P_("Base path"),
 688                           P_("The path within the backend where the settings are"),
 689                           NULL,
 690                           G_PARAM_CONSTRUCT_ONLY |
 691                           G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 692
 693    /**
 694     * GSettings:has-unapplied:
 695     *
 696     * If this property is %TRUE, the #GSettings object has outstanding
 697     * changes that will be applied when g_settings_apply() is called.
 698     */
 699    g_object_class_install_property (object_class, PROP_HAS_UNAPPLIED,
 700      g_param_spec_boolean ("has-unapplied",
 701                            P_("Has unapplied changes"),
 702                            P_("TRUE if there are outstanding changes to apply()"),
 703                            FALSE,
 704                            G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
 705
 706 }
 707
 708 /**
 709  * g_settings_get_value:
 710  * @settings: a #GSettings object
 711  * @key: the key to get the value for
 712  * @returns: a new #GVariant
 713  *
 714  * Gets the value that is stored in @settings for @key.
 715  *
 716  * It is a programmer error to give a @key that isn't valid for
 717  * @settings.
 718  *
 719  * Since: 2.26
 720  */
 721 GVariant *
 722 g_settings_get_value (GSettings   *settings,
 723                       const gchar *key)
 724 {
 725   const gchar *unparsed = NULL;
 726   GVariant *value, *options;
 727   const GVariantType *type;
 728   gchar lc_char = '\0';
 729   GVariant *sval;
 730   gchar *path;
 731
 732   sval = g_settings_schema_get_value (settings->priv->schema, key, &options);
 733
 734   if G_UNLIKELY (sval == NULL)
 735     g_error ("schema '%s' does not contain a key named '%s'",
 736              settings->priv->schema_name, key);
 737
 738   path = g_strconcat (settings->priv->path, key, NULL);
 739   type = g_variant_get_type (sval);
 740   value = g_settings_backend_read (settings->priv->backend, path, type);
 741   g_free (path);
 742
 743   if (options != NULL)
 744     {
 745       GVariantIter iter;
 746       const gchar *option;
 747       GVariant *option_value;
 748
 749       g_variant_iter_init (&iter, options);
 750       while (g_variant_iter_loop (&iter, "{&sv}", &option, &option_value))
 751         {
 752           if (strcmp (option, "l10n") == 0)
 753             g_variant_get (option_value, "(y&s)", &lc_char, &unparsed);
 754           else
 755             g_warning ("unknown schema extension '%s'", option);
 756         }
 757     }
 758
 759   if (value && !g_variant_is_of_type (value, type))
 760     {
 761       g_variant_unref (value);
 762       value = NULL;
 763     }
 764
 765   if (value == NULL && lc_char != '\0')
 766   /* we will need to translate the schema default value */
 767     {
 768       const gchar *translated;
 769       GError *error = NULL;
 770       const gchar *domain;
 771       gint lc_category;
 772
 773       domain = g_settings_schema_get_gettext_domain (settings->priv->schema);
 774
 775       if (lc_char == 't')
 776         lc_category = LC_TIME;
 777       else
 778         lc_category = LC_MESSAGES;
 779
 780       translated = dcgettext (domain, unparsed, lc_category);
 781
 782       if (translated != unparsed)
 783         /* it was translated, so we need to re-parse it */
 784         {
 785           value = g_variant_parse (g_variant_get_type (sval),
 786                                    translated, NULL, NULL, &error);
 787
 788           if (value == NULL)
 789             {
 790               g_warning ("Failed to parse translated string `%s' for "
 791                          "key `%s' in schema `%s': %s", unparsed, key,
 792                          settings->priv->schema_name, error->message);
 793               g_warning ("Using untranslated default instead.");
 794               g_error_free (error);
 795             }
 796         }
 797     }
 798
 799   if (value == NULL)
 800     /* either translation failed or there was none to do.
 801      * use the pre-compiled default.
 802      */
 803     value = g_variant_ref (sval);
 804
 805   g_variant_unref (sval);
 806
 807   return value;
 808 }
 809
 810 /**
 811  * g_settings_set_value:
 812  * @settings: a #GSettings object
 813  * @key: the name of the key to set
 814  * @value: a #GVariant of the correct type
 815  * @returns: %TRUE if setting the key succeeded,
 816  *     %FALSE if the key was not writable
 817  *
 818  * Sets @key in @settings to @value.
 819  *
 820  * It is a programmer error to give a @key that isn't valid for
 821  * @settings.  It is a programmer error to give a @value of the
 822  * incorrect type.
 823  *
 824  * If @value is floating then this function consumes the reference.
 825  *
 826  * Since: 2.26
 827  **/
 828 gboolean
 829 g_settings_set_value (GSettings   *settings,
 830                       const gchar *key,
 831                       GVariant    *value)
 832 {
 833   gboolean correct_type;
 834   gboolean result;
 835   GVariant *sval;
 836   gchar *path;
 837
 838   sval = g_settings_schema_get_value (settings->priv->schema, key, NULL);
 839   correct_type = g_variant_is_of_type (value, g_variant_get_type (sval));
 840   g_variant_unref (sval);
 841
 842   g_return_val_if_fail (correct_type, FALSE);
 843
 844   path = g_strconcat (settings->priv->path, key, NULL);
 845   result = g_settings_backend_write (settings->priv->backend,
 846                                      path, value, NULL);
 847   g_free (path);
 848
 849   return result;
 850 }
 851
 852 /**
 853  * g_settings_get:
 854  * @settings: a #GSettings object
 855  * @key: the key to get the value for
 856  * @format: a #GVariant format string
 857  * @...: arguments as per @format
 858  *
 859  * Gets the value that is stored at @key in @settings.
 860  *
 861  * A convenience function that combines g_settings_get_value() with
 862  * g_variant_get().
 863  *
 864  * It is a programmer error to pass a @key that isn't valid for
 865  * @settings or a @format_string that doesn't match the type of @key according
 866  * to the schema of @settings.
 867  *
 868  * Since: 2.26
 869  */
 870 void
 871 g_settings_get (GSettings   *settings,
 872                 const gchar *key,
 873                 const gchar *format,
 874                 ...)
 875 {
 876   GVariant *value;
 877   va_list ap;
 878
 879   value = g_settings_get_value (settings, key);
 880
 881   va_start (ap, format);
 882   g_variant_get_va (value, format, NULL, &ap);
 883   va_end (ap);
 884
 885   g_variant_unref (value);
 886 }
 887
 888 /**
 889  * g_settings_set:
 890  * @settings: a #GSettings object
 891  * @key: the name of the key to set
 892  * @format: a #GVariant format string
 893  * @...: arguments as per @format
 894  * @returns: %TRUE if setting the key succeeded,
 895  *     %FALSE if the key was not writable
 896  *
 897  * Sets @key in @settings to @value.
 898  *
 899  * A convenience function that combines g_settings_set_value() with
 900  * g_variant_new().
 901  *
 902  * It is a programmer error to pass a @key that isn't valid for
 903  * @settings or a @format that doesn't match the type of @key according
 904  * to the schema of @settings.
 905  *
 906  * Since: 2.26
 907  */
 908 gboolean
 909 g_settings_set (GSettings   *settings,
 910                 const gchar *key,
 911                 const gchar *format,
 912                 ...)
 913 {
 914   GVariant *value;
 915   va_list ap;
 916
 917   va_start (ap, format);
 918   value = g_variant_new_va (format, NULL, &ap);
 919   va_end (ap);
 920
 921   return g_settings_set_value (settings, key, value);
 922 }
 923
 924 /**
 925  * g_settings_is_writable:
 926  * @settings: a #GSettings object
 927  * @name: the name of a key
 928  * @returns: %TRUE if the key @name is writable
 929  *
 930  * Finds out if a key can be written or not
 931  *
 932  * Since: 2.26
 933  */
 934 gboolean
 935 g_settings_is_writable (GSettings   *settings,
 936                         const gchar *name)
 937 {
 938   gboolean writable;
 939   gchar *path;
 940
 941   path = g_strconcat (settings->priv->path, name, NULL);
 942   writable = g_settings_backend_get_writable (settings->priv->backend, path);
 943   g_free (path);
 944
 945   return writable;
 946 }
 947
 948 /**
 949  * g_settings_get_child:
 950  * @settings: a #GSettings object
 951  * @name: the name of the 'child' schema
 952  * @returns: a 'child' settings object
 953  *
 954  * Creates a 'child' settings object which has a base path of
 955  * <replaceable>base-path</replaceable>/@name", where
 956  * <replaceable>base-path</replaceable> is the base path of @settings.
 957  *
 958  * The schema for the child settings object must have been declared
 959  * in the schema of @settings using a <tag>child</tag> element.
 960  *
 961  * Since: 2.26
 962  */
 963 GSettings *
 964 g_settings_get_child (GSettings   *settings,
 965                       const gchar *name)
 966 {
 967   GVariant *child_schema;
 968   gchar *child_path;
 969   gchar *child_name;
 970   GSettings *child;
 971
 972   child_name = g_strconcat (name, "/", NULL);
 973   child_schema = g_settings_schema_get_value (settings->priv->schema,
 974                                               child_name, NULL);
 975   if (child_schema == NULL ||
 976       !g_variant_is_of_type (child_schema, G_VARIANT_TYPE_STRING))
 977     g_error ("Schema '%s' has no child '%s'",
 978              settings->priv->schema_name, name);
 979
 980   child_path = g_strconcat (settings->priv->path, child_name, NULL);
 981   child = g_object_new (G_TYPE_SETTINGS,
 982                         "schema", g_variant_get_string (child_schema, NULL),
 983                         "path", child_path,
 984                         NULL);
 985   g_variant_unref (child_schema);
 986   g_free (child_path);
 987   g_free (child_name);
 988
 989   return child;
 990 }
 991
 992 /**
 993  * g_settings_new:
 994  * @schema: the name of the schema
 995  * @returns: a new #GSettings object
 996  *
 997  * Creates a new #GSettings object with a given schema.
 998  *
 999  * Since: 2.26
1000  */
1001 GSettings *
1002 g_settings_new (const gchar *schema)
1003 {
1004   return g_object_new (G_TYPE_SETTINGS,
1005                        "schema", schema,
1006                        NULL);
1007 }
1008
1009 /**
1010  * g_settings_new_with_path:
1011  * @schema: the name of the schema
1012  * @path: the path to use
1013  * @returns: a new #GSettings object
1014  *
1015  * Creates a new #GSettings object with a given schema and path.
1016  *
1017  * You only need to do this if you want to directly create a settings
1018  * object with a schema that doesn't have a specified path of its own.
1019  * That's quite rare.
1020  *
1021  * It is a programmer error to call this function for a schema that
1022  * has an explicitly specified path.
1023  *
1024  * Since: 2.26
1025  */
1026 GSettings *
1027 g_settings_new_with_path (const gchar *schema,
1028                           const gchar *path)
1029 {
1030   return g_object_new (G_TYPE_SETTINGS,
1031                        "schema", schema,
1032                        "path", path,
1033                        NULL);
1034 }
1035
1036 /**
1037  * g_settings_new_with_context:
1038  * @schema: the name of the schema
1039  * @context: the context to use
1040  * @returns: a new #GSettings object
1041  *
1042  * Creates a new #GSettings object with a given schema and context.
1043  *
1044  * Creating settings objects with a context allow accessing settings
1045  * from a database other than the usual one.  For example, it may make
1046  * sense to specify "defaults" in order to get a settings object that
1047  * modifies the system default settings instead of the settings for this
1048  * user.
1049  *
1050  * It is a programmer error to call this function for an unsupported
1051  * context.  Use g_settings_supports_context() to determine if a context
1052  * is supported if you are unsure.
1053  *
1054  * Since: 2.26
1055  */
1056 GSettings *
1057 g_settings_new_with_context (const gchar *schema,
1058                              const gchar *context)
1059 {
1060   return g_object_new (G_TYPE_SETTINGS,
1061                        "schema", schema,
1062                        "context", context,
1063                        NULL);
1064 }
1065
1066 /**
1067  * g_settings_new_with_context_and_path:
1068  * @schema: the name of the schema
1069  * @path: the path to use
1070  * @returns: a new #GSettings object
1071  *
1072  * Creates a new #GSettings object with a given schema, context and
1073  * path.
1074  *
1075  * This is a mix of g_settings_new_with_context() and
1076  * g_settings_new_with_path().
1077  *
1078  * Since: 2.26
1079  */
1080 GSettings *
1081 g_settings_new_with_context_and_path (const gchar *schema,
1082                                       const gchar *context,
1083                                       const gchar *path)
1084 {
1085   return g_object_new (G_TYPE_SETTINGS,
1086                        "schema", schema,
1087                         "context", context,
1088                         "path", path,
1089                         NULL);
1090 }
1091
1092 typedef struct
1093 {
1094   GSettings *settings;
1095   GObject *object;
1096
1097   GSettingsBindGetMapping get_mapping;
1098   GSettingsBindSetMapping set_mapping;
1099   gpointer user_data;
1100   GDestroyNotify destroy;
1101
1102   guint writable_handler_id;
1103   guint property_handler_id;
1104   const GParamSpec *property;
1105   guint key_handler_id;
1106   GVariantType *type;
1107   const gchar *key;
1108
1109   /* prevent recursion */
1110   gboolean running;
1111 } GSettingsBinding;
1112
1113 static void
1114 g_settings_binding_free (gpointer data)
1115 {
1116   GSettingsBinding *binding = data;
1117
1118   g_assert (!binding->running);
1119
1120   if (binding->writable_handler_id)
1121     g_signal_handler_disconnect (binding->settings,
1122                                  binding->writable_handler_id);
1123
1124   if (binding->key_handler_id)
1125     g_signal_handler_disconnect (binding->settings,
1126                                  binding->key_handler_id);
1127
1128   if (g_signal_handler_is_connected (binding->object,
1129                                      binding->property_handler_id))
1130   g_signal_handler_disconnect (binding->object,
1131                                binding->property_handler_id);
1132
1133   g_variant_type_free (binding->type);
1134   g_object_unref (binding->settings);
1135
1136   if (binding->destroy)
1137     binding->destroy (binding->user_data);
1138
1139   g_slice_free (GSettingsBinding, binding);
1140 }
1141
1142 static GQuark
1143 g_settings_binding_quark (const char *property)
1144 {
1145   GQuark quark;
1146   gchar *tmp;
1147
1148   tmp = g_strdup_printf ("gsettingsbinding-%s", property);
1149   quark = g_quark_from_string (tmp);
1150   g_free (tmp);
1151
1152   return quark;
1153 }
1154
1155 static void
1156 g_settings_binding_key_changed (GSettings   *settings,
1157                                 const gchar *key,
1158                                 gpointer     user_data)
1159 {
1160   GSettingsBinding *binding = user_data;
1161   GValue value = {  };
1162   GVariant *variant;
1163
1164   g_assert (settings == binding->settings);
1165   g_assert (key == binding->key);
1166
1167   if (binding->running)
1168     return;
1169
1170   binding->running = TRUE;
1171
1172   g_value_init (&value, binding->property->value_type);
1173   variant = g_settings_get_value (settings, key);
1174   if (binding->get_mapping (&value, variant, binding->user_data))
1175     g_object_set_property (binding->object,
1176                            binding->property->name,
1177                            &value);
1178   g_value_unset (&value);
1179
1180   binding->running = FALSE;
1181 }
1182
1183 static void
1184 g_settings_binding_writable_changed (GSettings   *settings,
1185                                      const gchar *key,
1186                                      gpointer     user_data)
1187 {
1188   GSettingsBinding *binding = user_data;
1189   gboolean writable;
1190
1191   g_assert (settings == binding->settings);
1192   g_assert (key == binding->key);
1193
1194   writable = g_settings_is_writable (settings, key);
1195   g_object_set (binding->object, "sensitive", writable, NULL);
1196 }
1197
1198 static void
1199 g_settings_binding_property_changed (GObject          *object,
1200                                      const GParamSpec *pspec,
1201                                      gpointer          user_data)
1202 {
1203   GSettingsBinding *binding = user_data;
1204   GValue value = {  };
1205   GVariant *variant;
1206
1207   g_assert (object == binding->object);
1208   g_assert (pspec == binding->property);
1209
1210   if (binding->running)
1211     return;
1212
1213   binding->running = TRUE;
1214
1215   g_value_init (&value, pspec->value_type);
1216   g_object_get_property (object, pspec->name, &value);
1217   if ((variant = binding->set_mapping (&value, binding->type,
1218                                        binding->user_data)))
1219     {
1220       g_settings_set_value (binding->settings,
1221                             binding->key,
1222                             g_variant_ref_sink (variant));
1223       g_variant_unref (variant);
1224     }
1225   g_value_unset (&value);
1226
1227   binding->running = FALSE;
1228 }
1229
1230 /**
1231  * g_settings_bind:
1232  * @settings: a #GSettings object
1233  * @key: the key to bind
1234  * @object: a #GObject
1235  * @property: the name of the property to bind
1236  * @flags: flags for the binding
1237  *
1238  * Create a binding between the @key in the @settings object
1239  * and the property @property of @object.
1240  *
1241  * The binding uses the default GIO mapping functions to map
1242  * between the settings and property values. These functions
1243  * handle booleans, numeric types and string types in a
1244  * straightforward way. Use g_settings_bind_with_mapping()
1245  * if you need a custom mapping, or map between types that
1246  * are not supported by the default mapping functions.
1247  *
1248  * Note that the lifecycle of the binding is tied to the object,
1249  * and that you can have only one binding per object property.
1250  * If you bind the same property twice on the same object, the second
1251  * binding overrides the first one.
1252  *
1253  * Since: 2.26
1254  */
1255 void
1256 g_settings_bind (GSettings          *settings,
1257                  const gchar        *key,
1258                  gpointer            object,
1259                  const gchar        *property,
1260                  GSettingsBindFlags  flags)
1261 {
1262   g_settings_bind_with_mapping (settings, key, object, property,
1263                                 flags, NULL, NULL, NULL, NULL);
1264 }
1265
1266 /**
1267  * g_settings_bind_with_mapping:
1268  * @settings: a #GSettings object
1269  * @key: the key to bind
1270  * @object: a #GObject
1271  * @property: the name of the property to bind
1272  * @flags: flags for the binding
1273  * @get_mapping: a function that gets called to convert values
1274  *     from @settings to @object, or %NULL to use the default GIO mapping
1275  * @set_mapping: a function that gets called to convert values
1276  *     from @object to @settings, or %NULL to use the default GIO mapping
1277  * @user_data: data that gets passed to @get_mapping and @set_mapping
1278  * @destroy: #GDestroyNotify function for @user_data
1279  *
1280  * Create a binding between the @key in the @settings object
1281  * and the property @property of @object.
1282  *
1283  * The binding uses the provided mapping functions to map between
1284  * settings and property values.
1285  *
1286  * Note that the lifecycle of the binding is tied to the object,
1287  * and that you can have only one binding per object property.
1288  * If you bind the same property twice on the same object, the second
1289  * binding overrides the first one.
1290  *
1291  * Since: 2.26
1292  */
1293 void
1294 g_settings_bind_with_mapping (GSettings               *settings,
1295                               const gchar             *key,
1296                               gpointer                 object,
1297                               const gchar             *property,
1298                               GSettingsBindFlags       flags,
1299                               GSettingsBindGetMapping  get_mapping,
1300                               GSettingsBindSetMapping  set_mapping,
1301                               gpointer                 user_data,
1302                               GDestroyNotify           destroy)
1303 {
1304   GSettingsBinding *binding;
1305   GObjectClass *objectclass;
1306   gboolean bind_sensitive;
1307   gchar *detailed_signal;
1308   GQuark binding_quark;
1309
1310   objectclass = G_OBJECT_GET_CLASS (object);
1311
1312   binding = g_slice_new0 (GSettingsBinding);
1313   binding->settings = g_object_ref (settings);
1314   binding->object = object;
1315   binding->key = g_intern_string (key);
1316   binding->property = g_object_class_find_property (objectclass, property);
1317   binding->user_data = user_data;
1318   binding->destroy = destroy;
1319   binding->get_mapping = get_mapping ? get_mapping : g_settings_get_mapping;
1320   binding->set_mapping = set_mapping ? set_mapping : g_settings_set_mapping;
1321
1322   if (!(flags & (G_SETTINGS_BIND_GET | G_SETTINGS_BIND_SET)))
1323     flags |= G_SETTINGS_BIND_GET | G_SETTINGS_BIND_SET;
1324
1325   if (binding->property == NULL)
1326     {
1327       g_critical ("g_settings_bind: no property '%s' on class '%s'",
1328                   property, G_OBJECT_TYPE_NAME (object));
1329       return;
1330     }
1331
1332   {
1333     GVariant *value;
1334
1335     value = g_settings_schema_get_value (settings->priv->schema, key, NULL);
1336     binding->type = g_variant_type_copy (g_variant_get_type (value));
1337     if (value)
1338       g_variant_unref (value);
1339   }
1340
1341   if (binding->type == NULL)
1342     {
1343       g_critical ("g_settings_bind: no key '%s' on schema '%s'",
1344                   key, settings->priv->schema_name);
1345       return;
1346     }
1347
1348   if (((get_mapping == NULL && (flags & G_SETTINGS_BIND_GET)) ||
1349        (set_mapping == NULL && (flags & G_SETTINGS_BIND_SET))) &&
1350       !g_settings_mapping_is_compatible (binding->property->value_type,
1351                                          binding->type))
1352     {
1353       g_critical ("g_settings_bind: property '%s' on class '%s' has type"
1354                   "'%s' which is not compatible with type '%s' of key '%s'"
1355                   "on schema '%s'", property, G_OBJECT_TYPE_NAME (object),
1356                   g_type_name (binding->property->value_type),
1357                   g_variant_type_dup_string (binding->type), key,
1358                   settings->priv->schema_name);
1359       return;
1360     }
1361
1362   if ((flags & G_SETTINGS_BIND_SET) &&
1363       (~flags & G_SETTINGS_BIND_NO_SENSITIVITY))
1364     {
1365       GParamSpec *sensitive;
1366
1367       sensitive = g_object_class_find_property (objectclass, "sensitive");
1368       bind_sensitive = sensitive && sensitive->value_type == G_TYPE_BOOLEAN;
1369     }
1370   else
1371     bind_sensitive = FALSE;
1372
1373   if (flags & G_SETTINGS_BIND_SET)
1374     {
1375       detailed_signal = g_strdup_printf ("notify::%s", property);
1376       binding->property_handler_id =
1377         g_signal_connect (object, detailed_signal,
1378                           G_CALLBACK (g_settings_binding_property_changed),
1379                           binding);
1380       g_free (detailed_signal);
1381
1382       if (~flags & G_SETTINGS_BIND_GET)
1383         g_settings_binding_property_changed (object,
1384                                              binding->property,
1385                                              binding);
1386     }
1387
1388   if (flags & G_SETTINGS_BIND_GET)
1389     {
1390       if (~flags & G_SETTINGS_BIND_GET_NO_CHANGES)
1391         {
1392           detailed_signal = g_strdup_printf ("changed::%s", key);
1393           binding->key_handler_id =
1394             g_signal_connect (settings, detailed_signal,
1395                               G_CALLBACK (g_settings_binding_key_changed),
1396                               binding);
1397           g_free (detailed_signal);
1398         }
1399
1400       g_settings_binding_key_changed (settings, binding->key, binding);
1401     }
1402
1403   if (bind_sensitive)
1404     {
1405       detailed_signal = g_strdup_printf ("writable-changed::%s", key);
1406       binding->writable_handler_id =
1407         g_signal_connect (settings, detailed_signal,
1408                           G_CALLBACK (g_settings_binding_writable_changed),
1409                           binding);
1410       g_free (detailed_signal);
1411
1412       g_settings_binding_writable_changed (settings, binding->key, binding);
1413     }
1414
1415   binding_quark = g_settings_binding_quark (property);
1416   g_object_set_qdata_full (object, binding_quark,
1417                            binding, g_settings_binding_free);
1418 }
1419
1420 /**
1421  * g_settings_unbind:
1422  * @object: the object
1423  * @property: the property whose binding is removed
1424  *
1425  * Removes an existing binding for @property on @object.
1426  *
1427  * Note that bindings are automatically removed when the
1428  * object is finalized, so it is rarely necessary to call this
1429  * function.
1430  *
1431  * Since: 2.26
1432  */
1433 void
1434 g_settings_unbind (gpointer     object,
1435                    const gchar *property)
1436 {
1437   GQuark binding_quark;
1438
1439   binding_quark = g_settings_binding_quark (property);
1440   g_object_set_qdata (object, binding_quark, NULL);
1441 }
1442
1443 /**
1444  * g_settings_get_string:
1445  * @settings: a #GSettings object
1446  * @key: the key to get the value for
1447  * @returns: a newly-allocated string
1448  *
1449  * Gets the value that is stored at @key in @settings.
1450  *
1451  * A convenience variant of g_settings_get() for strings.
1452  *
1453  * It is a programmer error to pass a @key that isn't valid for
1454  * @settings or is not of type string.
1455  *
1456  * Since: 2.26
1457  */
1458 gchar *
1459 g_settings_get_string (GSettings   *settings,
1460                        const gchar *key)
1461 {
1462   GVariant *value;
1463   gchar *result;
1464
1465   value = g_settings_get_value (settings, key);
1466   result = g_variant_dup_string (value, NULL);
1467   g_variant_unref (value);
1468
1469   return result;
1470 }
1471
1472 /**
1473  * g_settings_set_string:
1474  * @settings: a #GSettings object
1475  * @key: the name of the key to set
1476  * @value: the value to set it to
1477  * @returns: %TRUE if setting the key succeeded,
1478  *     %FALSE if the key was not writable
1479  *
1480  * Sets @key in @settings to @value.
1481  *
1482  * A convenience variant of g_settings_set() for strings.
1483  *
1484  * It is a programmer error to pass a @key that isn't valid for
1485  * @settings or is not of type string.
1486  *
1487  * Since: 2.26
1488  */
1489 gboolean
1490 g_settings_set_string (GSettings   *settings,
1491                        const gchar *key,
1492                        const gchar *value)
1493 {
1494   return g_settings_set_value (settings, key, g_variant_new_string (value));
1495 }
1496
1497 /**
1498  * g_settings_get_int:
1499  * @settings: a #GSettings object
1500  * @key: the key to get the value for
1501  * @returns: an integer
1502  *
1503  * Gets the value that is stored at @key in @settings.
1504  *
1505  * A convenience variant of g_settings_get() for 32-bit integers.
1506  *
1507  * It is a programmer error to pass a @key that isn't valid for
1508  * @settings or is not of type int32.
1509  *
1510  * Since: 2.26
1511  */
1512 gint
1513 g_settings_get_int (GSettings   *settings,
1514                     const gchar *key)
1515 {
1516   GVariant *value;
1517   gint result;
1518
1519   value = g_settings_get_value (settings, key);
1520   result = g_variant_get_int32 (value);
1521   g_variant_unref (value);
1522
1523   return result;
1524 }
1525
1526 /**
1527  * g_settings_set_int:
1528  * @settings: a #GSettings object
1529  * @key: the name of the key to set
1530  * @value: the value to set it to
1531  * @returns: %TRUE if setting the key succeeded,
1532  *     %FALSE if the key was not writable
1533  *
1534  * Sets @key in @settings to @value.
1535  *
1536  * A convenience variant of g_settings_set() for 32-bit integers.
1537  *
1538  * It is a programmer error to pass a @key that isn't valid for
1539  * @settings or is not of type int32.
1540  *
1541  * Since: 2.26
1542  */
1543 gboolean
1544 g_settings_set_int (GSettings   *settings,
1545                     const gchar *key,
1546                     gint         value)
1547 {
1548   return g_settings_set_value (settings, key, g_variant_new_int32 (value));
1549 }
1550
1551 /**
1552  * g_settings_get_double:
1553  * @settings: a #GSettings object
1554  * @key: the key to get the value for
1555  * @returns: a double
1556  *
1557  * Gets the value that is stored at @key in @settings.
1558  *
1559  * A convenience variant of g_settings_get() for doubles.
1560  *
1561  * It is a programmer error to pass a @key that isn't valid for
1562  * @settings or is not of type double.
1563  *
1564  * Since: 2.26
1565  */
1566 gdouble
1567 g_settings_get_double (GSettings   *settings,
1568                        const gchar *key)
1569 {
1570   GVariant *value;
1571   gdouble result;
1572
1573   value = g_settings_get_value (settings, key);
1574   result = g_variant_get_double (value);
1575   g_variant_unref (value);
1576
1577   return result;
1578 }
1579
1580 /**
1581  * g_settings_set_double:
1582  * @settings: a #GSettings object
1583  * @key: the name of the key to set
1584  * @value: the value to set it to
1585  * @returns: %TRUE if setting the key succeeded,
1586  *     %FALSE if the key was not writable
1587  *
1588  * Sets @key in @settings to @value.
1589  *
1590  * A convenience variant of g_settings_set() for doubles.
1591  *
1592  * It is a programmer error to pass a @key that isn't valid for
1593  * @settings or is not of type double.
1594  *
1595  * Since: 2.26
1596  */
1597 gboolean
1598 g_settings_set_double (GSettings   *settings,
1599                        const gchar *key,
1600                        gdouble      value)
1601 {
1602   return g_settings_set_value (settings, key, g_variant_new_double (value));
1603 }
1604
1605 /**
1606  * g_settings_get_boolean:
1607  * @settings: a #GSettings object
1608  * @key: the key to get the value for
1609  * @returns: a boolean
1610  *
1611  * Gets the value that is stored at @key in @settings.
1612  *
1613  * A convenience variant of g_settings_get() for booleans.
1614  *
1615  * It is a programmer error to pass a @key that isn't valid for
1616  * @settings or is not of type boolean.
1617  *
1618  * Since: 2.26
1619  */
1620 gboolean
1621 g_settings_get_boolean (GSettings  *settings,
1622                        const gchar *key)
1623 {
1624   GVariant *value;
1625   gboolean result;
1626
1627   value = g_settings_get_value (settings, key);
1628   result = g_variant_get_boolean (value);
1629   g_variant_unref (value);
1630
1631   return result;
1632 }
1633
1634 /**
1635  * g_settings_set_boolean:
1636  * @settings: a #GSettings object
1637  * @key: the name of the key to set
1638  * @value: the value to set it to
1639  * @returns: %TRUE if setting the key succeeded,
1640  *     %FALSE if the key was not writable
1641  *
1642  * Sets @key in @settings to @value.
1643  *
1644  * A convenience variant of g_settings_set() for booleans.
1645  *
1646  * It is a programmer error to pass a @key that isn't valid for
1647  * @settings or is not of type boolean.
1648  *
1649  * Since: 2.26
1650  */
1651 gboolean
1652 g_settings_set_boolean (GSettings  *settings,
1653                        const gchar *key,
1654                        gboolean     value)
1655 {
1656   return g_settings_set_value (settings, key, g_variant_new_boolean (value));
1657 }
1658
1659 /**
1660  * g_settings_get_strv:
1661  * @settings: a #GSettings object
1662  * @key: the key to get the value for
1663  * @returns: a newly-allocated, %NULL-terminated array of strings
1664  *
1665  * Gets the value that is stored at @key in @settings.
1666  *
1667  * A convenience variant of g_settings_get() for string arrays.
1668  *
1669  * It is a programmer error to pass a @key that isn't valid for
1670  * @settings or is not of type 'string array'.
1671  *
1672  * Since: 2.26
1673  */
1674 gchar **
1675 g_settings_get_strv (GSettings   *settings,
1676                      const gchar *key,
1677                      gsize       *length)
1678 {
1679   GVariant *value;
1680   gchar **result;
1681
1682   value = g_settings_get_value (settings, key);
1683   result = g_variant_dup_strv (value, length);
1684   g_variant_unref (value);
1685
1686   return result;
1687 }
1688
1689 /**
1690  * g_settings_set_strv:
1691  * @settings: a #GSettings object
1692  * @key: the name of the key to set
1693  * @value: the value to set it to
1694  * @returns: %TRUE if setting the key succeeded,
1695  *     %FALSE if the key was not writable
1696  *
1697  * Sets @key in @settings to @value.
1698  *
1699  * A convenience variant of g_settings_set() for string arrays.
1700  *
1701  * It is a programmer error to pass a @key that isn't valid for
1702  * @settings or is not of type 'string array'.
1703  *
1704  * Since: 2.26
1705  */
1706 gboolean
1707 g_settings_set_strv (GSettings           *settings,
1708                      const gchar         *key,
1709                      const gchar * const *value,
1710                      gssize               length)
1711 {
1712   return g_settings_set_value (settings, key, g_variant_new_strv (value, length));
1713 }
1714
1715 #define __G_SETTINGS_C__
1716 #include "gioaliasdef.c"