[glib/wip/schemasource] add plugin example for GSettingsSchemaSource

[Ryan Lortie <ryanl src gnome org>]

commit 7da381366f296e5ec0ba92ea6a19fa17dd66568b
Author: Ryan Lortie <desrt desrt ca>
Date:   Thu Nov 17 14:02:39 2011 +0000

    add plugin example for GSettingsSchemaSource

 gio/gsettingsschema.c |   89 ++++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 88 insertions(+), 1 deletions(-)
---
diff --git a/gio/gsettingsschema.c b/gio/gsettingsschema.c
index 8a81565..f9a87bb 100644
--- a/gio/gsettingsschema.c
+++ b/gio/gsettingsschema.c
@@ -38,8 +38,95 @@
  * mechanism for advanced control over the loading of schemas and a
  * mechanism for introspecting their content.
  *
+ * Plugin loading systems that wish to provide plugins a way to access
+ * settings face the problem of how to make the schemas for these
+ * settings visible to GSettings.  Typically, a plugin will want to ship
+ * the schema along with itself and it won't be installed into the
+ * standard system directories for schemas.
+ *
+ * #GSettingsSchemaSource provides a mechanism for dealing with this by
+ * allowing the creation of a new 'schema source' from which schemas can
+ * be acquired.  This schema source can then become part of the metadata
+ * associated with the plugin and queried whenever the plugin requires
+ * access to some settings.
+ *
+ * Consider the following example:
+ *
+ * |[
+ * typedef struct
+ * {
+ *    ...
+ *    GSettingsSchemaSource *schema_source;
+ *    ...
+ * } Plugin;
+ *
+ * Plugin *
+ * initialise_plugin (const gchar *dir)
+ * {
+ *   Plugin *plugin;
+ *
+ *   ...
+ *
+ *   plugin->schema_source =
+ *     g_settings_new_schema_source_from_directory (dir,
+ *       g_settings_schema_source_get_default (), FALSE, NULL);
+ *
+ *   ...
+ *
+ *   return plugin;
+ * }
+ *
+ * ...
+ *
+ * GSettings *
+ * plugin_get_settings (Plugin      *plugin,
+ *                      const gchar *schema_id)
+ * {
+ *   GSettingsSchema *schema;
+ *
+ *   if (schema_id == NULL)
+ *     schema_id = plugin->identifier;
+ *
+ *   schema = g_settings_schema_source_lookup (plugin->schema_source,
+ *                                             schema_id, FALSE);
+ *
+ *   if (schema == NULL)
+ *     {
+ *       ... disable the plugin or abort, etc ...
+ *     }
+ *
+ *   return g_settings_new_full (schema, NULL, NULL);
+ * }
+ * ]|
+ *
+ * The code above shows how hooks should be added to the code that
+ * initialises (or enables) the plugin to create the schema source and
+ * how an API can be added to the plugin system to provide a convenient
+ * way for the plugin to access its settings, using the schemas that it
+ * ships.
+ *
+ * From the standpoint of the plugin, it would need to ensure that it
+ * ships a gschemas.compiled file as part of itself, and then simply do
+ * the following:
+ *
+ * |[
+ * {
+ *   GSettings *settings;
+ *   gint some_value;
+ *
+ *   settings = plugin_get_settings (self, NULL);
+ *   some_value = g_settings_get_int (settings, "some-value");
+ *   ...
+ * }
+ * ]|
+ *
+ * It's also possible that the plugin system expects the schema source
+ * files (ie: .gschema.xml files) instead of a gschemas.compiled file.
+ * In that case, the plugin loading system must compile the schemas for
+ * itself before attempting to create the settings source.
+ *
  * Since: 2.32
- */
+ **/
 
 /**
  * GSettingsSchema: