docs/reference/gio/html/ch29s06.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.76.1">
   7 <link rel="home" href="index.html" title="GIO Reference Manual">
   8 <link rel="up" href="ch29.html" title="Migrating from GConf to GSettings">
   9 <link rel="prev" href="ch29s05.html" title="Change sets">
  10 <link rel="next" href="ch29s07.html" title="Data conversion">
  11 <meta name="generator" content="GTK-Doc V1.18 (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="ch29s05.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  17 <td><a accesskey="u" href="ch29.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="ch29s07.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  21 </tr></table>
  22 <div class="section">
  23 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  24 <a name="id1005963"></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. GConf comes with a commandline tool
  28         gsettings-schema-convert that can help with the task of converting
  29         a GConf schema into an equivalent GSettings schema. The tool is not
  30         perfect and may need assistence in some cases.
  31       </p>
  32 <div class="example">
  33 <a name="id573133"></a><p class="title"><b>Example 22. An example for using gsettings-schema-convert</b></p>
  34 <div class="example-contents">
  35 <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:
  36         </p>
  37 <pre class="programlisting">
  38
  39 &lt;?xml version="1.0"?&gt;
  40 &lt;gconfschemafile&gt;
  41     &lt;schemalist&gt;
  42         &lt;schema&gt;
  43             &lt;key&gt;/schemas/desktop/gnome/font_rendering/dpi&lt;/key&gt;
  44             &lt;applyto&gt;/desktop/gnome/font_rendering/dpi&lt;/applyto&gt;
  45             &lt;owner&gt;gnome&lt;/owner&gt;
  46             &lt;type&gt;int&lt;/type&gt;
  47             &lt;default&gt;96&lt;/default&gt;
  48             &lt;locale name="C"&gt;
  49                 &lt;short&gt;DPI&lt;/short&gt;
  50                 &lt;long&gt;The resolution used for converting font sizes to pixel sizes, in dots per inch.&lt;/long&gt;
  51             &lt;/locale&gt;
  52         &lt;/schema&gt;
  53     &lt;/schemalist&gt;
  54 &lt;/gconfschemafile&gt;
  55
  56 </pre>
  57 <p>
  58 produces a <code class="filename">org.gnome.font-rendering.gschema.xml</code> file with the following content:
  59 </p>
  60 <pre class="programlisting">
  61
  62 &lt;schemalist&gt;
  63   &lt;schema id="org.gnome.font-rendering" path="/desktop/gnome/font_rendering/"&gt;
  64     &lt;key name="dpi" type="i"&gt;
  65       &lt;default&gt;96&lt;/default&gt;
  66       &lt;summary&gt;DPI&lt;/summary&gt;
  67       &lt;description&gt;The resolution used for converting font sizes to pixel sizes, in dots per inch.&lt;/description&gt;
  68     &lt;/key&gt;
  69   &lt;/schema&gt;
  70 &lt;/schemalist&gt;
  71
  72 </pre>
  73 <p>
  74 </p>
  75 </div>
  76 </div>
  77 <br class="example-break"><p>
  78        GSettings schemas are identified at runtime by their id (as specified
  79        in the XML source file). It is recommended to use a dotted name as schema
  80        id, similar in style to a D-Bus bus name, e.g. "org.gnome.SessionManager".
  81        In cases where the settings are general and not specific to one application,
  82        the id should not use StudlyCaps, e.g. "org.gnome.font-rendering".
  83        The filename used for the XML schema source is immaterial, but
  84        schema compiler expects the files to have the extension
  85        <code class="filename">.gschema.xml</code>. It is recommended to simply
  86        use the schema id as the filename, followed by this extension,
  87        e.g. <code class="filename">org.gnome.SessionManager.gschema.xml</code>.
  88       </p>
  89 <p>
  90         The XML source file for your GSettings schema needs to get installed
  91         into <code class="filename">$datadir/glib-2.0/schemas</code>, and needs to be
  92         compiled into a binary form. At runtime, GSettings looks for compiled
  93         schemas in the <code class="filename">glib-2.0/schemas</code> subdirectories
  94         of all <code class="envar">XDG_DATA_DIRS</code> directories, so if you install
  95         your schema in a different location, you need to set the
  96         <code class="envar">XDG_DATA_DIRS</code> environment variable appropriately.
  97       </p>
  98 <p>
  99         Schemas are compiled into binary form by the
 100         <a href="glib-compile-schemas.html">glib-compile-schemas</a> utility.
 101         GIO provides a <code class="literal">glib_compile_schemas</code>
 102         variable for the schema compiler.
 103       </p>
 104 <p>
 105         You can ignore all of this by using the provided m4 macros.  To
 106         do this, add to your <code class="filename">configure.ac</code>:
 107 </p>
 108 <pre class="programlisting">
 109 GLIB_GSETTINGS
 110 </pre>
 111 <p>
 112         The corresponding <code class="filename">Makefile.am</code> fragment looks like
 113         this:
 114 </p>
 115 <pre class="programlisting">
 116 # gsettings_SCHEMAS is a list of all the schemas you want to install
 117 gsettings_SCHEMAS = my.app.gschema.xml
 118
 119 # include the appropriate makefile rules for schema handling
 120 @GSETTINGS_RULES@
 121 </pre>
 122 <p>
 123       </p>
 124 <p>
 125         This is not sufficient on its own.  You need to mention what the source
 126         of the <code class="filename">my.app.gschema.xml</code> file is.  If the schema
 127         file is distributed directly with your project's tarball then a mention
 128         in <code class="varname">EXTRA_DIST</code> is appropriate.  If the schema file is
 129         generated from another source then you will need the appropriate rule
 130         for that, plus probably an item in <code class="varname">EXTRA_DIST</code> for the
 131         source files used by that rule.
 132       </p>
 133 <p>
 134         One possible pitfall in doing schema conversion is that the default
 135         values in GSettings schemas are parsed by the <a href="./../glib/glib/glib-GVariant.html#GVariant"><span class="type">GVariant</span></a> parser.
 136         This means that strings need to include quotes in the XML.  Also note
 137         that the types are now specified as <a href="./../glib/glib/glib-GVariant.html#GVariant"><span class="type">GVariant</span></a> type strings.
 138         </p>
 139 <pre class="programlisting">
 140
 141 &lt;type&gt;string&lt;/type&gt;
 142 &lt;default&gt;rgb&lt;/default&gt;
 143
 144         </pre>
 145 <p>
 146         becomes
 147         </p>
 148 <pre class="programlisting">
 149
 150 &lt;key name="rgba-order" type="s"&gt;
 151   &lt;default&gt;'rgb'&lt;/default&gt; &lt;!-- note quotes --&gt;
 152 &lt;/key&gt;
 153
 154         </pre>
 155 <p>
 156       </p>
 157 <p>
 158         Another possible complication is that GConf specifies full paths
 159         for each key, while a GSettings schema has a 'path' attribute that
 160         contains the prefix for all the keys in the schema, and individual
 161         keys just have a simple name. So
 162         </p>
 163 <pre class="programlisting">
 164
 165 &lt;key&gt;/schemas/desktop/gnome/font_rendering/antialiasing&lt;/key&gt;
 166
 167         </pre>
 168 <p>
 169         becomes
 170         </p>
 171 <pre class="programlisting">
 172
 173 &lt;schema id="org.gnome.font" path="/desktop/gnome/font_rendering/"&gt;
 174   &lt;key name="antialiasing" type="s"&gt;
 175
 176         </pre>
 177 <p>
 178       </p>
 179 <p>
 180         Default values can be localized in both GConf and GSettings schemas,
 181         but GSettings uses gettext for the localization. You can specify
 182         the gettext domain to use in the <code class="sgmltag-attribute">gettext-domain</code>
 183         attribute. Therefore, when converting localized defaults in GConf,
 184         </p>
 185 <pre class="programlisting">
 186
 187 &lt;key&gt;/schemas/apps/my_app/font_size&lt;/key&gt;
 188   &lt;locale name="C"&gt;
 189     &lt;default&gt;18&lt;/default&gt;
 190   &lt;/locale&gt;
 191   &lt;locale name="be"&gt;
 192     &lt;default&gt;24&lt;/default&gt;
 193   &lt;/locale&gt;
 194 &lt;/key&gt;
 195
 196         </pre>
 197 <p>
 198         becomes
 199         </p>
 200 <pre class="programlisting">
 201
 202 &lt;schema id="..." gettext-domain="your-domain"&gt;
 203  ...
 204 &lt;key name="font-size" type="i"&gt;
 205   &lt;default l10n="messages" context="font_size"&gt;18&lt;/default&gt;
 206 &lt;/key&gt;
 207
 208         </pre>
 209 <p>
 210       </p>
 211 <p>
 212         GSettings uses gettext for translation of default values.
 213         The string that is translated is exactly the string that appears
 214         inside of the <code class="sgmltag-starttag">&lt;default&gt;</code> element.  This
 215         includes the quotation marks that appear around strings.
 216         Default values must be marked with the <code class="varname">l10n</code>
 217         attribute in the <code class="sgmltag-starttag">&lt;default&gt;</code> tag, which
 218         should be set as equal to <code class="literal">'messages'</code> or
 219         <code class="literal">'time'</code> depending on the desired category.  An
 220         optional translation context can also be specified with the
 221         <code class="varname">context</code> attribute, as in the example.  This
 222         is usually recommended, since the string "<code class="literal">18</code>"
 223         is not particularly easy to translate without context.  The
 224         translated version of the default value should be stored in the
 225         specified <code class="varname">gettext-domain</code>.  Care must be taken
 226         during translation to ensure that all translated values remain
 227         syntactically valid; mistakes here will cause runtime errors.
 228       </p>
 229 <p>
 230         GSettings schemas have optional <code class="sgmltag-starttag">&lt;summary&gt;</code> and
 231         <code class="sgmltag-starttag">&lt;description&gt;</code> elements for each key which
 232         correspond to the <code class="sgmltag-starttag">&lt;short&gt;</code> and
 233         <code class="sgmltag-starttag">&lt;long&gt;</code> elements in the GConf schema and
 234         will be used in similar ways by a future gsettings-editor, so you
 235         should use the same conventions for them: The summary is just a short
 236         label with no punctuation, the description can be one or more complete
 237         sentences. If multiple paragraphs are desired for the description, the
 238         paragraphs should be separated by a completely empty line.
 239       </p>
 240 <p>
 241         Translations for these strings will also be handled
 242         via gettext, so you should arrange for these strings to be
 243         extracted into your gettext catalog. One way to do that is to use
 244         intltool. For that, you use <code class="sgmltag-starttag">&lt;_summary&gt;</code>
 245         and <code class="sgmltag-starttag">&lt;_description&gt;</code> elements in a
 246         .gschema.xml.in file and use
 247         <code class="literal">@INTLTOOL_XML_NOMERGE_RULE@</code>
 248         in your Makefile.am to produce the .gschema.xml file. The
 249         <code class="literal">NOMERGE</code> part of the rule instructs intltool
 250         to extract translatable strings, but not merge the translations
 251         back into the generated xml file.
 252       </p>
 253 <p>
 254         GSettings is a bit more restrictive about key names than GConf. Key
 255         names in GSettings can be at most 32 characters long, and must only
 256         consist of lowercase characters, numbers and dashes, with no
 257         consecutive dashes. The first character must not be a number or dash,
 258         and the last character cannot be '-'.
 259       </p>
 260 <p>
 261         If you are using the GConf backend for GSettings during the
 262         transition, you may want to keep your key names the same they
 263         were in GConf, so that existing settings in the users GConf
 264         database are preserved. You can achieve this by using the
 265         <code class="option">--allow-any-name</code> with the
 266         <a href="glib-compile-schemas.html">glib-compile-schemas</a> schema
 267         compiler. Note that this option is only meant
 268         to ease the process of porting your application, allowing parts
 269         of your application to continue to access GConf and parts to use
 270         GSettings. By the time you have finished porting your application
 271         you must ensure that all key names are valid.
 272       </p>
 273 </div>
 274 <div class="footer">
 275 <hr>
 276           Generated by GTK-Doc V1.18</div>
 277 </body>
 278 </html>