<page xmlns="http://projectmallard.org/1.0/"
      type="topic" style="task"
      id="backgrounds-extra">

  <info>
    <link type="guide" xref="index#appearance" />
    <revision pkgversion="3.8" date="2012-07-02" status="draft"/>

    <credit type="author copyright">
      <name>Matthias Clasen</name>
      <email>matthias.clasen@gmail.com</email>
      <years>2012</years>
    </credit>
    <credit type="editor">
      <name>Jana Svarova</name>
      <email>jana.svarova@gmail.com</email>
      <years>2013</years>
    </credit>

    <desc>How do I make extra backgrounds available to my users?</desc>
  </info>

  <title>Add extra backgrounds</title>
  <p>You can make extra backgrounds available to users on your system:</p>

<steps>
  <title>Set your extra background</title>
	<item>
  <p>Create a <var>filename</var>.xml file specifying your extra
  background's appearance using the <em>org.gnome.desktop.background schemas</em>. 
  Here is a list of the most frequently used schemas; the full range of options 
  is to be found in the <sys>dconf-editor</sys> GUI or <sys>gsettings</sys> command-line utility.</p>
  
<table frame="top bottom" rules="all" shade="rows">
   <title>org.gnome.desktop.background schemas GSettings Keys</title>
<tbody>
<tr>
  <td><p>Key Name</p></td>
  <td><p>Possible Values</p></td>
  <td><p>Description</p></td>
</tr>
<tr>
  <td><p>picture-options</p></td>
  <td><p>"none", "wallpaper", "centered", "scaled", "stretched", "zoom", "spanned"</p></td>
  <td><p>Determines how the image set by <var>wallpaper_filename</var> is rendered.</p></td>
</tr>
<tr>
  <td><p>color-shading-type</p></td>
  <td><p>"horizontal", "vertical", and "solid"</p></td>
  <td><p>How to shade the background color.</p></td>
</tr>
<tr>
  <td><p>primary-color</p></td>
  <td><p>default: #023c88</p></td>
  <td><p>Left or Top color when drawing gradients, or the solid color.</p></td>
</tr>
<tr>
  <td><p>secondary-color</p></td>
  <td><p>default: #5789ca</p></td>
  <td><p>Right or Bottom color when drawing gradients, not used for solid color.</p></td>
</tr>
</tbody>
  </table>
	</item>
	<item>
  <p>Store the <var>filename</var>.xml file in the 
  <file>/usr/share/gnome-background-properties/</file> directory.</p>
	</item>
</steps>

  <p>When you click on your name in the top right corner and choose 
  <guiseq><gui>Settings</gui><gui>Personal</gui><gui>Background</gui></guiseq>, 
  you will see the new background available.</p>
  <p>Look at the example and see how <em>org.gnome.desktop.background</em> GSettings keys
  are implemented practically. Here is a sample <code>&lt;wallpaper&gt;</code> element.</p>
  
<code><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE wallpapers SYSTEM "gnome-wp-list.dtd">
<wallpapers>
  <wallpaper deleted="false">
    <name>Company Background</name>
    <name xml:lang="de">Firmenhintergrund</name>
    <filename>/usr/local/share/backgrounds/company-wallpaper.jpg</filename>
    <options>zoom</options>
    <shade_type>solid</shade_type>
    <pcolor>#ffffff</pcolor>
    <scolor>#000000</scolor>
  </wallpaper>
</wallpapers>
]]></code>

<section id="backgrounds-extra-two-wallpapers">
  <title>Specify multiple backgrounds</title>
  <p>In one configuration file, you can specify multiple
  <code>&lt;wallpaper&gt;</code> elements to add more backgrounds.</p>
  <p>See the following example which shows an <sys>XML</sys> file with two
  <code>&lt;wallpaper&gt;</code> elements, adding two different backgrounds:</p>

<code><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE wallpapers SYSTEM "gnome-wp-list.dtd">
<wallpapers>
  <wallpaper deleted="false">
    <name>Company Background</name>
    <name xml:lang="de">Firmenhintergrund</name>
    <filename>/usr/local/share/backgrounds/company-wallpaper.jpg</filename>
    <options>zoom</options>
    <shade_type>solid</shade_type>
    <pcolor>#ffffff</pcolor>
    <scolor>#000000</scolor>
  </wallpaper>
  <wallpaper deleted="false">
    <name>Company Background 2</name>
    <name xml:lang="de">Firmenhintergrund 2</name>
    <filename>/usr/local/share/backgrounds/company-wallpaper-2.jpg</filename>
    <options>zoom</options>
    <shade_type>solid</shade_type>
    <pcolor>#ff0000</pcolor>
    <scolor>#00ffff</scolor>
  </wallpaper>
</wallpapers>
]]></code>

</section>
</page>
