</para>
<para>
It is always a good idea to have a look at how others have handled
- similar problems before. An examplaric conversion can be found e.g.
- in the <ulink url="http://git.gnome.org/browse/gnome-utils/log/?h=gsettings-tutorial">gsettings-tutorial</ulink> branch of gnome-utils.
+ similar problems before.
</para>
</section>
<para>
If you are porting your application from GConf, most likely you already
- have a GConf schema. GIO comes with a commandline tool
- <link linkend="gsettings-schema-convert">gsettings-schema-convert</link>
- that can help with the task of converting a GConf schema into
- an equivalent GSettings schema. The tool is not perfect and
- may need assistence in some cases.
+ have a GConf schema. GConf comes with a commandline tool
+ gsettings-schema-convert that can help with the task of converting
+ a GConf schema into an equivalent GSettings schema. The tool is not
+ perfect and may need assistence in some cases.
</para>
<example><title>An example for using gsettings-schema-convert</title>
<para>Running <userinput>gsettings-schema-convert --gconf --xml --schema-id "org.gnome.font-rendering" --output org.gnome.font-rendering.gschema.xml destop_gnome_font_rendering.schemas</userinput> on the following <filename>desktop_gnome_font_rendering.schemas</filename> file:
</example>
<para>
- GSettings schemas are identified at runtime by their id (as specified
- in the XML source file). It is recommended to use a dotted name as schema
- id, similar in style to a DBus bus name, e.g. "org.gnome.font-rendering".
+ GSettings schemas are identified at runtime by their id (as specified
+ in the XML source file). It is recommended to use a dotted name as schema
+ id, similar in style to a D-Bus bus name, e.g. "org.gnome.SessionManager".
+ In cases where the settings are general and not specific to one application,
+ the id should not use StudlyCaps, e.g. "org.gnome.font-rendering".
The filename used for the XML schema source is immaterial, but
schema compiler expects the files to have the extension
<filename>.gschema.xml</filename>. It is recommended to simply
use the schema id as the filename, followed by this extension,
- e.g. <filename>org.gnome.font-rendering.gschema.xml</filename>.
+ e.g. <filename>org.gnome.SessionManager.gschema.xml</filename>.
</para>
<para>
Schemas are compiled into binary form by the
<link linkend="glib-compile-schemas">glib-compile-schemas</link> utility.
GIO provides a <literal>glib_compile_schemas</literal>
- variable for the schema compiler, which can be used in
- <filename>configure.in</filename> as follows:
+ variable for the schema compiler.
+ </para>
+ <para>
+ You can ignore all of this by using the provided m4 macros. To
+ do this, add to your <filename>configure.ac</filename>:
<programlisting>
GLIB_GSETTINGS
</programlisting>
The corresponding <filename>Makefile.am</filename> fragment looks like
this:
<programlisting>
-# gsettingsschemadir and gschema_compile are defined by the GLIB_GSETTINGS
-# macro in configure.ac
-gsettingsschema_DATA = my.app.gschema.xml
-# This rule will check your schemas for validity before installation
-@GSETTINGS_CHECK_RULE@
-if GSETTINGS_SCHEMAS_INSTALL
-install-data-hook:
- $(GLIB_COMPILE_SCHEMAS) $(DESTDIR)$(gsettingsschemadir)
-endif
+# gsettings_SCHEMAS is a list of all the schemas you want to install
+gsettings_SCHEMAS = my.app.gschema.xml
+
+# include the appropriate makefile rules for schema handling
+@GSETTINGS_RULES@
</programlisting>
</para>
<para>
+ This is not sufficient on its own. You need to mention what the source
+ of the <filename>my.app.gschema.xml</filename> file is. If the schema
+ file is distributed directly with your project's tarball then a mention
+ in <varname>EXTRA_DIST</varname> is appropriate. If the schema file is
+ generated from another source then you will need the appropriate rule
+ for that, plus probably an item in <varname>EXTRA_DIST</varname> for the
+ source files used by that rule.
+ </para>
+
+ <para>
One possible pitfall in doing schema conversion is that the default
values in GSettings schemas are parsed by the #GVariant parser.
This means that strings need to include quotes in the XML. Also note
</key>
]]>
</programlisting>
- Note how we used the context attribute to add msgctxt - "18" is not a
- good string to look up in gettext by itself. Also note that the value
- 24 is not present in the schema anymore. It has to be added to the
- gettext catalog for "be" instead.
+ </para>
+ <para>
+ GSettings uses gettext for translation of default values.
+ The string that is translated is exactly the string that appears
+ inside of the <tag class='starttag'>default</tag> element. This
+ includes the quotation marks that appear around strings.
+ Default values must be marked with the <varname>l10n</varname>
+ attribute in the <tag class='starttag'>default</tag> tag, which
+ should be set as equal to <literal>'messages'</literal> or
+ <literal>'time'</literal> depending on the desired category. An
+ optional translation context can also be specified with the
+ <varname>context</varname> attribute, as in the example. This
+ is usually recommended, since the string "<literal>18</literal>"
+ is not particularly easy to translate without context. The
+ translated version of the default value should be stored in the
+ specified <varname>gettext-domain</varname>. Care must be taken
+ during translation to ensure that all translated values remain
+ syntactically valid; mistakes here will cause runtime errors.
</para>
<para>
GSettings schemas have optional <tag class="starttag">summary</tag> and
will be used in similar ways by a future gsettings-editor, so you
should use the same conventions for them: The summary is just a short
label with no punctuation, the description can be one or more complete
- sentences.
+ sentences. If multiple paragraphs are desired for the description, the
+ paragraphs should be separated by a completely empty line.
</para>
<para>
Translations for these strings will also be handled
via gettext, so you should arrange for these strings to be
extracted into your gettext catalog. One way to do that is to use
- intltool. For that, you use <tag class="starttag">_summary</tag>
- and <tag class="starttag">_description</tag> elements in a
- .gschema.xml.in file and use <literal>@INTLTOOL_NOMERGE_RULE@</literal>
- in your Makefile.am to produce the .gschema.xml file. The
- <literal>NOMERGE</literal> part of the rule instructs intltool
- to extract translatable strings, but not merge the translations
- back into the generated xml file.
+ intltool. Since intltool 0.50.1, schema files are
+ supported, so all you have to do is to add your .gschema.xml
+ files to <filename>POTFILES.in</filename> with a line like
+ <programlisting>
+ [type: gettext/gsettings]data/org.foo.MyApp.gschema.xml
+ </programlisting>
</para>
<para>
GSettings is a bit more restrictive about key names than GConf. Key
script if you are making use of the GConf backend or the conversion
utility.
</para>
+
+ <para>
+ If, as an application developer, you are interested in manually
+ ensuring that <command>gsettings-data-convert</command> has been
+ invoked (for example, to deal with the case where the user is
+ logged in during a distribution upgrade or for non-XDG desktop
+ environments which do not run the command as an autostart) you
+ may invoke it manually during your program initialisation. This
+ is not recommended for all application authors -- it is your
+ choice if this use case concerns you enough.
+ </para>
+ <para>
+ Internally, <command>gsettings-data-convert</command> uses a
+ keyfile to track which settings have been migrated. The
+ following code fragment will check that keyfile to see if your
+ data conversion script has been run yet and, if not, will
+ attempt to invoke the tool to run it. You should adapt it to
+ your application as you see fit.
+ </para>
+ <para>
+ <programlisting>
+<![CDATA[
+static void
+ensure_migrated (const gchar *name)
+{
+ gboolean needed = TRUE;
+ GKeyFile *kf;
+ gchar **list;
+ gsize i, n;
+
+ kf = g_key_file_new ();
+
+ g_key_file_load_from_data_dirs (kf, "gsettings-data-convert",
+ NULL, G_KEY_FILE_NONE, NULL);
+ list = g_key_file_get_string_list (kf, "State", "converted", &n, NULL);
+
+ if (list)
+ {
+ for (i = 0; i < n; i++)
+ if (strcmp (list[i], name) == 0)
+ {
+ needed = FALSE;
+ break;
+ }
+
+ g_strfreev (list);
+ }
+
+ g_key_file_free (kf);
+
+ if (needed)
+ g_spawn_command_line_sync ("gsettings-data-convert",
+ NULL, NULL, NULL, NULL);
+}
+
+]]>
+ </programlisting>
+ </para>
+ <para>
+ Although there is the possibility that the
+ <command>gsettings-data-convert</command> script will end up
+ running multiple times concurrently with this approach, it is
+ believed that this is safe.
+ </para>
</section>
</chapter>
projects / platform / upstream / glib.git / blobdiff