<?xml version="1.0" encoding="utf-8"?>
<?db.chunk.max_depth 3?>
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:db="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="mate-dconf" xml:lang="cy">
    <info><title xml:lang="en">Desktop Settings Storage</title></info>

  <highlights>
    <para xml:lang="en">
      This chapter describes how are your MATE desktop settings stored,
      and how to retrieve or modify them using the <command>dconf</command>
      or <command>gsettings</command> command line tools, or the
      <application>Dconf Editor</application> GUI application.
    </para>
  </highlights>

  <section xml:id="mate-dconf-intro"><info><title xml:lang="en">Introduction</title></info>
    <para xml:lang="en">
      The settings of your MATE desktop are managed and stored by
      <application>dconf</application>, which is a key-based configuration system
      for hardware and software configurations.
    </para>

    <para xml:lang="en">
      <application>dconf</application> uses several database files in GVDB binary format, one database per file.
      A dconf profile consists of a single file, in plain text format, which contains a list of database files in GVDB format.
      All dconf profiles are stored in the <filename class="directory">/etc/dconf/profile</filename> folder.
    </para>
    <para xml:lang="en">
      In most systems, there is no dconf profile file since they only use the default database, user.db which is stored in ~/.config/dconf/user. In such case, there is no system-wide setting, i.e. users just have their own settings.
    </para>
    <para xml:lang="en">
      Example of content for the user profile (/etc/dconf/profile/user file):
    </para>

<literallayout xml:lang="en">user-db: user
system-db: local
system-db: site
system-db: distro</literallayout>

    <para xml:lang="en">
      The previous dconf profile contains 4 GVDB files, one per line.
    </para>

    <itemizedlist>
      <listitem>
        <para xml:lang="en"><database class="name">user</database> is the name of the user's databases. They are usually located in the <filename class="directory">~/.config/dconf</filename> folder</para>
      </listitem>
      <listitem>
        <para xml:lang="en"><database class="name">local</database>, <database class="name">site</database> and <database class="name">distro</database> are system databases. They are usually located in the <filename class="directory">/etc/dconf/db</filename> folder</para>
      </listitem>
    </itemizedlist>

    <para xml:lang="en">
      Each one of these databases store key-value pairs using a hash map data structure, which can map string keys to GVariant values in a way that is extremely efficient for lookups.
      The lookup preference is determined by the order of appearance in the dconf profile file, user's databases have the highest preference in the previous dconf profile example.
      The keys from multiple configuration sources coexist in a logical tree structure. MATE Desktop key-value hashmap entries are under the /org/mate logical node, which are usually stored in user's databases.
    </para>

    <note>
      <para xml:lang="en">Refer to the <link xlink:href="man:dconf(7)"><citerefentry><refentrytitle>dconf</refentrytitle><manvolnum>7</manvolnum></citerefentry></link> for more information about the dconf configuration system.</para>
    </note>

  <section xml:id="mate-dconf-one-read"><info><title xml:lang="en">To read the value of a dconf key</title></info>
    

    <para xml:lang="en">
      The value of a dconf key can be read using the <command>dconf</command> or <command>gsettings</command> command line tools, or the <application>Dconf Editor</application> GUI application.
    </para>

    <para xml:lang="en">
      This section shows how to read the background picture of your MATE desktop, this values is stored in the dconf key:
    </para>
    <itemizedlist>
      <listitem>
        <para xml:lang="en">/org/mate/desktop/background/picture-filename</para>
      </listitem>
    </itemizedlist>

    <para xml:lang="en">
      The following figure displays the full path to this dconf key. Note that the other directories have not been expanded, or they have been removed, and only are showed the keys for dconf directory:
    </para>

    <itemizedlist>
      <listitem>
        <para xml:lang="en">/org/mate/desktop/background/</para>
      </listitem>
    </itemizedlist>

    <figure xml:id="dconf-logical-full-bakgroud-keys-fig"><info><title xml:lang="en">/org/mate/desktop/background/ dconf directory</title></info>
       
      <mediaobject xml:lang="en">
        <imageobject>
          <imagedata fileref="figures/org_mate_desktop_background_logical_view.png" format="PNG"/>
        </imageobject>
        <textobject>
          <phrase>Figure showing the contents of /org/mate/desktop/background/ dconf directory.</phrase>
        </textobject>
      </mediaobject>
    </figure>

    <para xml:lang="en">
      You can read the value of a dconf key:
    </para>

    <section xml:id="read-key-dconf-using-dconf-editor"><info><title xml:lang="en">Using the dconf-editor GUI application</title></info>
      
      <para xml:lang="en">
        To show the value of a dconf key using the <application>Dconf Editor</application> application, perform the following steps:
      </para>
      <orderedlist>
        <listitem>
          <para xml:lang="en">Choose <menuchoice><guimenu>Applications</guimenu><guimenuitem>System Tools</guimenuitem><guimenuitem>dconf Editor</guimenuitem></menuchoice> from the top panel.</para>
        </listitem>
        <listitem>
          <para xml:lang="en">Click on the folders to get the full path to the dconf directory.</para>
        </listitem>
      </orderedlist>

      <figure><info><title xml:lang="en">Dconf-Editor showing the value of /org/mate/desktop/background/picture-filename key</title></info>
        
        <screenshot>
          <mediaobject xml:lang="en">
            <imageobject>
              <imagedata fileref="figures/picture_filename_dconf_key_view.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase>Dconf-Editor showing the value of /org/mate/desktop/background/picture-filename key</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </figure>
    </section>

    <section xml:id="read-key-dconf-using-dconf"><info><title xml:lang="en">Using the dconf command line tool</title></info>
      
      <para xml:lang="en">
        To read the value of a dconf key using the <command>dconf</command> command line tool, run the following command:
      </para>
      <screen xml:lang="en">$ dconf read /org/mate/desktop/background/picture-filename
'/usr/share/backgrounds/mate/desktop/MATE-Stripes-Dark.png'</screen>
      <para xml:lang="en">
        Synopsis:
      </para>
      <synopsis xml:lang="en">dconf read [-d] KEY</synopsis>
      <para xml:lang="en">
        Refer to the <link xlink:href="man:dconf"><citerefentry><refentrytitle>dconf</refentrytitle><manvolnum>1</manvolnum></citerefentry></link> for more information on how to use <command>dconf</command> command line tool.
      </para>
      <tip><para xml:lang="en">You can use the <keycap>Tab</keycap> key to auto complete the path to the dconf key. </para></tip>
    </section>

    <section xml:id="read-key-dconf-using-gsettings"><info><title xml:lang="en">Using the gsettings command line tool</title></info>
      
      <para xml:lang="en">
        To read the value of a dconf key using the <command>gsettings</command> command line tool, run the following command:
      </para>
      <screen xml:lang="en">$ gsettings get org.mate.background picture-filename
'/usr/share/backgrounds/mate/desktop/MATE-Stripes-Dark.png'</screen>
      <para xml:lang="en">
        Synopsis:
      </para>
      <synopsis xml:lang="en">gsettings [--schemadir SCHEMADIR] get SCHEMA[:PATH] KEY</synopsis>
      <para xml:lang="en">
        Refer to the <link xlink:href="man:gsettings"><citerefentry><refentrytitle>gsettings</refentrytitle><manvolnum>1</manvolnum></citerefentry></link> for more information on how to use <command>gsettings</command> command line tool.
      </para>
    </section>
  </section>

  <section xml:id="mate-dconf-one-change"><info><title xml:lang="en">To change the value of a dconf key</title></info>
    

    <para xml:lang="en">
      The value of a dconf key can be modified using the <command>dconf</command> command or the <application>Dconf Editor</application> application.
    </para>
    <para xml:lang="en">
      This section shows how to change the background picture of your MATE desktop, this values is stored in the dconf key:
    </para>
    <itemizedlist>
      <listitem>
        <para xml:lang="en">/org/mate/desktop/background/picture-filename</para>
      </listitem>
    </itemizedlist>

    <para xml:lang="en">
      The following figure displays the full path to this dconf key. Note that the other directories have not been expanded, or they have been removed, and only are showed the keys for dconf directory:
    </para>
    <itemizedlist>
      <listitem>
        <para xml:lang="en">/org/mate/desktop/background/</para>
      </listitem>
    </itemizedlist>

    <figure xml:id="dconf-logical-short-bakgroud-keys-fig"><info><title xml:lang="en">/org/mate/desktop/background/ dconf directory</title></info>
      
      <mediaobject xml:lang="en">
        <imageobject>
          <imagedata fileref="figures/org_mate_desktop_background_only_logical_view.png" format="PNG"/>
        </imageobject>
        <textobject>
          <phrase>Figure showing the contents of /org/mate/desktop/background/ dconf directory.</phrase>
        </textobject>
      </mediaobject>
    </figure>

    <para xml:lang="en">
      You can mofify the value of a dconf key:
    </para>

    <section xml:id="modify-key-dconf-using-dconf-editor"><info><title xml:lang="en">Using the dconf-editor GUI application</title></info>
      
      <para xml:lang="en">
        To edit the background picture of your MATE desktop in <application>Dconf Editor</application>, perform the following steps:
      </para>

      <orderedlist>
        <listitem>
            <para xml:lang="en">Choose <menuchoice><guimenu>Applications</guimenu><guimenuitem>System Tools</guimenuitem><guimenuitem>dconf Editor</guimenuitem></menuchoice> from the top panel.</para>
        </listitem>
        <listitem>
          <para xml:lang="en">Click on the folders to get the full path to the dconf directory, and then click on the dconf key to edit its value.</para>
        </listitem>
        <listitem>
           <para xml:lang="en">Enter the new value in <guilabel>Custom value</guilabel> text box.</para>
        </listitem>
        <listitem>
           <para xml:lang="en">Click on the Check mark button to apply the change.</para>
        </listitem>
      </orderedlist>

      <figure><info><title xml:lang="en">Editing the value of /org/mate/desktop/background/picture-filename key in Dconf-Editor dialog</title></info>
        
        <screenshot>
          <mediaobject xml:lang="en">
            <imageobject>
              <imagedata fileref="figures/picture_filename_dconf_key_edit.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase>Editing the value of /org/mate/desktop/background/picture-filename key in Dconf-Editor dialog</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </figure>
    </section>

    <section xml:id="modify-key-dconf-using-dconf"><info><title xml:lang="en">Using the dconf command line tool</title></info>
      
      <para xml:lang="en">
        To change the background picture of your MATE desktop, run the following command:
      </para>
      <screen xml:lang="en">$ dconf write /org/mate/desktop/background/picture-filename \
"'/usr/share/backgrounds/mate/desktop/MATE-Stripes-Light.png'"</screen>
      <para xml:lang="en">
        Synopsis:
      </para>
      <synopsis xml:lang="en">dconf write KEY VALUE</synopsis>
      <para xml:lang="en">
        Refer to the <link xlink:href="man:dconf"><citerefentry><refentrytitle>dconf</refentrytitle><manvolnum>1</manvolnum></citerefentry></link> for more information on how to use <command>dconf</command>.
      </para>
    </section>

    <section xml:id="modify-key-dconf-using-gsettings"><info><title xml:lang="en">Using the gsettings command line tool</title></info>
      
      <para xml:lang="en">
        To change the background picture of your MATE desktop, run the following command:
      </para>
      <screen xml:lang="en">$ gsettings set org.mate.background picture-filename \
"'/usr/share/backgrounds/mate/desktop/MATE-Stripes-Light.png'"</screen>
      <para xml:lang="en">
        Synopsis:
      </para>
      <synopsis xml:lang="en">gsettings [--schemadir SCHEMADIR] set SCHEMA[:PATH] KEY VALUE</synopsis>
      <para xml:lang="en">
        Refer to the <link xlink:href="man:gsettings"><citerefentry><refentrytitle>gsettings</refentrytitle><manvolnum>1</manvolnum></citerefentry></link> for more information on how to use <command>dconf</command>.
      </para>
    </section>
  </section>

  <section xml:id="mate-dconf-some-changes"><info><title xml:lang="en">To change the value of several dconf keys</title></info>
    

    <para xml:lang="en">
      To change the value of several dconf keys at the same time, perform the following steps:
    </para>
    <orderedlist>
      <listitem>
        <para xml:lang="en">Dump the contents of a dconf directory to a new plain text file:</para>
        <screen xml:lang="en">$ dconf dump /org/mate/desktop/background/ &gt; file.dconf</screen>
      </listitem>
      <listitem>
        <para xml:lang="en">Make changes in the plain text file</para>
<literallayout xml:lang="en">[/]
color-shading-type='vertical-gradient'
primary-color='rgb(88,145,188)'
picture-options='zoom'
picture-filename='/usr/share/backgrounds/mate/desktop/MATE-Stripes-Light.png'
secondary-color='rgb(60,143,37)'
</literallayout>
      </listitem>
      <listitem>
        <para xml:lang="en">Load the contents of the plain text file to a dconf directory</para>
        <screen xml:lang="en">$ dconf load /org/mate/desktop/background/ &lt; file.dconf</screen>
      </listitem>
    </orderedlist>
    <tip><para xml:lang="en">You can also dump/load several directories at once, e.g. to back up and restore all configurations of your MATE desktop:</para>
        <screen xml:lang="en">$ dconf dump /org/mate/ &gt; backup.dconf
$ dconf load /org/mate/ &lt; backup.dconf</screen>
    </tip>

    <para xml:lang="en">
      Refer to the <link xlink:href="man:dconf"><citerefentry><refentrytitle>dconf</refentrytitle><manvolnum>1</manvolnum></citerefentry></link> for more information on how to use <command>dconf</command> command line tool.
    </para>

  </section>

  </section>

  <xi:include href="gosdconfkeys.xml"/>   <!-- List of dconf keys -->

</chapter>
