docs/reference/gio/html/ch25s06.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>Schema conversion</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
   7 <link rel="home" href="index.html" title="GIO Reference Manual">
   8 <link rel="up" href="ch25.html" title="Migrating from GConf to GSettings">
   9 <link rel="prev" href="ch25s05.html" title="Change sets">
  10 <link rel="next" href="ch25s07.html" title="Data conversion">
  11 <meta name="generator" content="GTK-Doc V1.14 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
  16 <td><a accesskey="p" href="ch25s05.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  17 <td><a accesskey="u" href="ch25.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  18 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  19 <th width="100%" align="center">GIO Reference Manual</th>
  20 <td><a accesskey="n" href="ch25s07.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  21 </tr></table>
  22 <div class="section" title="Schema conversion">
  23 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  24 <a name="id707572"></a>Schema conversion</h2></div></div></div>
  25 <p>
  26         If you are porting your application from GConf, most likely you already
  27         have a GConf schema. GIO comes with a commandline tool
  28         <a href="gsettings-schema-convert.html">gsettings-schema-convert</a>
  29         that can help with the task of converting a GConf schema into
  30         an equivalent GSettings schema. The tool is not perfect and
  31         may need assistence in some cases.
  32       </p>
  33 <div class="example">
  34 <a name="id656587"></a><p class="title"><b>Example 11. An example for using gsettings-schema-convert</b></p>
  35 <div class="example-contents">
  36 <p>Running <strong class="userinput"><code>gsettings-schema-convert --gconf --xml --schema-id "org.gnome.font-rendering" --output org.gnome.font-rendering.gschema.xml destop_gnome_font_rendering.schemas</code></strong> on the following <code class="filename">desktop_gnome_font_rendering.schemas</code> file:
  37         </p>
  38 <pre class="programlisting">
  39
  40 &lt;?xml version="1.0"?&gt;
  41 &lt;gconfschemafile&gt;
  42     &lt;schemalist&gt;
  43         &lt;schema&gt;
  44             &lt;key&gt;/schemas/desktop/gnome/font_rendering/dpi&lt;/key&gt;
  45             &lt;applyto&gt;/desktop/gnome/font_rendering/dpi&lt;/applyto&gt;
  46             &lt;owner&gt;gnome&lt;/owner&gt;
  47             &lt;type&gt;int&lt;/type&gt;
  48             &lt;default&gt;96&lt;/default&gt;
  49             &lt;locale name="C"&gt;
  50                 &lt;short&gt;DPI&lt;/short&gt;
  51                 &lt;long&gt;The resolution used for converting font sizes to pixel sizes, in dots per inch.&lt;/long&gt;
  52             &lt;/locale&gt;
  53         &lt;/schema&gt;
  54     &lt;/schemalist&gt;
  55 &lt;/gconfschemafile&gt;
  56
  57 </pre>
  58 <p>
  59 produces a <code class="filename">org.gnome.font-rendering.gschema.xml</code> file with the following content:
  60 </p>
  61 <pre class="programlisting">
  62
  63 &lt;schemalist&gt;
  64   &lt;schema id="org.gnome.font-rendering" path="/desktop/gnome/font_rendering/"&gt;
  65     &lt;key name="dpi" type="i"&gt;
  66       &lt;default&gt;96&lt;/default&gt;
  67       &lt;summary&gt;DPI&lt;/summary&gt;
  68       &lt;description&gt;The resolution used for converting font sizes to pixel sizes, in dots per inch.&lt;/description&gt;
  69     &lt;/key&gt;
  70   &lt;/schema&gt;
  71 &lt;/schemalist&gt;
  72
  73 </pre>
  74 <p>
  75 </p>
  76 </div>
  77 </div>
  78 <br class="example-break"><p>
  79         GSettings schemas are identified at runtime by their id (as specified
  80         in the XML source file). It is recommended to use a dotted name as schema
  81         id, similar in style to a DBus bus name, e.g. "org.gnome.font-rendering".
  82        The filename used for the XML schema source is immaterial, but
  83        schema compiler expects the files to have the extension
  84        <code class="filename">.gschema.xml</code>. It is recommended to simply
  85        use the schema id as the filename, followed by this extension,
  86        e.g. <code class="filename">org.gnome.font-rendering.gschema.xml</code>.
  87       </p>
  88 <p>
  89         The XML source file for your GSettings schema needs to get installed
  90         into <code class="filename">$datadir/glib-2.0/schemas</code>, and needs to be
  91         compiled into a binary form. At runtime, GSettings looks for compiled
  92         schemas in the <code class="filename">glib-2.0/schemas</code> subdirectories
  93         of all <code class="envar">XDG_DATA_DIRS</code> directories, so if you install
  94         your schema in a different location, you need to set the
  95         <code class="envar">XDG_DATA_DIRS</code> environment variable appropriately.
  96       </p>
  97 <p>
  98         Schemas are compiled into binary form by the
  99         <a href="glib-compile-schemas.html">glib-compile-schemas</a> utility.
 100         GIO provides a <code class="literal">gschema_compile</code>
 101         variable for the schema compiler, which can be used in
 102         <code class="filename">configure.in</code> as follows:
 103 </p>
 104 <pre class="programlisting">
 105 GLIB_GSETTINGS
 106 </pre>
 107 <p>
 108         The corresponding <code class="filename">Makefile.am</code> fragment looks like
 109         this:
 110 </p>
 111 <pre class="programlisting">
 112 # gsettingsschemadir and gschema_compile are defined by the GLIB_GSETTINGS
 113 # macro in configure.ac
 114 gsettingsschema_DATA = my.app.gschema.xml
 115 # This rule will check your schemas for validity before installation
 116 @GSETTINGS_CHECK_RULE@
 117 if GSETTINGS_SCHEMAS_INSTALL
 118 install-data-hook:
 119         $(GLIB_COMPILE_SCHEMAS) $(DESTDIR)$(gsettingsschemadir)
 120 endif
 121 </pre>
 122 <p>
 123       </p>
 124 <p>
 125         One possible pitfall in doing schema conversion is that the default
 126         values in GSettings schemas are parsed by the <a href="/home/desrt/local/share/gtk-doc/html/glib/glib-GVariant.html#GVariant"><span class="type">GVariant</span></a> parser.
 127         This means that strings need to include quotes in the XML.  Also note
 128         that the types are now specified as <a href="/home/desrt/local/share/gtk-doc/html/glib/glib-GVariant.html#GVariant"><span class="type">GVariant</span></a> type strings.
 129         </p>
 130 <pre class="programlisting">
 131
 132 &lt;type&gt;string&lt;/type&gt;
 133 &lt;default&gt;rgb&lt;/default&gt;
 134
 135         </pre>
 136 <p>
 137         becomes
 138         </p>
 139 <pre class="programlisting">
 140
 141 &lt;key name="rgba-order" type="s"&gt;
 142   &lt;default&gt;'rgb'&lt;/default&gt; &lt;!-- note quotes --&gt;
 143 &lt;/key&gt;
 144
 145         </pre>
 146 <p>
 147       </p>
 148 <p>
 149         Another possible complication is that GConf specifies full paths
 150         for each key, while a GSettings schema has a 'path' attribute that
 151         contains the prefix for all the keys in the schema, and individual
 152         keys just have a simple name. So
 153         </p>
 154 <pre class="programlisting">
 155
 156 &lt;key&gt;/schemas/desktop/gnome/font_rendering/antialiasing&lt;/key&gt;
 157
 158         </pre>
 159 <p>
 160         becomes
 161         </p>
 162 <pre class="programlisting">
 163
 164 &lt;schema id="org.gnome.font" path="/desktop/gnome/font_rendering/"&gt;
 165   &lt;key name="antialiasing" type="s"&gt;
 166
 167         </pre>
 168 <p>
 169       </p>
 170 <p>
 171         Default values can be localized in both GConf and GSettings schemas,
 172         but GSettings uses gettext for the localization. You can specify
 173         the gettext domain to use in the <code class="sgmltag-attribute">gettext-domain</code>
 174         attribute. Therefore, when converting localized defaults in GConf,
 175         </p>
 176 <pre class="programlisting">
 177
 178 &lt;key&gt;/schemas/apps/my_app/font_size&lt;/key&gt;
 179   &lt;locale name="C"&gt;
 180     &lt;default&gt;18&lt;/default&gt;
 181   &lt;/locale&gt;
 182   &lt;locale name="be"&gt;
 183     &lt;default&gt;24&lt;/default&gt;
 184   &lt;/locale&gt;
 185 &lt;/key&gt;
 186
 187         </pre>
 188 <p>
 189         becomes
 190         </p>
 191 <pre class="programlisting">
 192
 193 &lt;schema id="..." gettext-domain="your-domain"&gt;
 194  ...
 195 &lt;key name="font-size" type="i"&gt;
 196   &lt;default l10n="messages" context="font_size"&gt;18&lt;/default&gt;
 197 &lt;/key&gt;
 198
 199         </pre>
 200 <p>
 201         Note how we used the context attribute to add msgctxt - "18" is not a
 202         good string to look up in gettext by itself. Also note that the value
 203         24 is not present in the schema anymore. It has to be added to the
 204         gettext catalog for "be" instead.
 205       </p>
 206 <p>
 207         GSettings schemas have optional <code class="sgmltag-starttag">&lt;summary&gt;</code> and
 208         <code class="sgmltag-starttag">&lt;description&gt;</code> elements for each key which
 209         correspond to the <code class="sgmltag-starttag">&lt;short&gt;</code> and
 210         <code class="sgmltag-starttag">&lt;long&gt;</code> elements in the GConf schema and
 211         will be used in similar ways by a future gsettings-editor, so you
 212         should use the same conventions for them: The summary is just a short
 213         label with no punctuation, the description can be one or more complete
 214         sentences. Translations for these strings will also be handled
 215         via gettext, so you should arrange for these strings to be
 216         extracted into your gettext catalog.
 217       </p>
 218 <p>
 219         GSettings is a bit more restrictive about key names than GConf. Key
 220         names in GSettings can be at most 32 characters long, and must only
 221         consist of lowercase characters, numbers and dashes, with no
 222         consecutive dashes. The first character must not be a number or dash,
 223         and the last character cannot be '-'.
 224       </p>
 225 <p>
 226         If you are using the GConf backend for GSettings during the
 227         transition, you may want to keep your key names the same they
 228         were in GConf, so that existing settings in the users GConf
 229         database are preserved. You can achieve this by using the
 230         <code class="option">--allow-any-name</code> with the
 231         <a href="glib-compile-schemas.html">glib-compile-schemas</a> schema
 232         compiler. Note that this option is only meant
 233         to ease the process of porting your application, allowing parts
 234         of your application to continue to access GConf and parts to use
 235         GSettings. By the time you have finished porting your application
 236         you must ensure that all key names are valid.
 237       </p>
 238 </div>
 239 <div class="footer">
 240 <hr>
 241           Generated by GTK-Doc V1.14</div>
 242 </body>
 243 </html>