View All Attachments for Bug 43943

Attachment #59086
theme-config-spec 0.1	text/html	2012-03-26 12:52:29 UTC	13.21 KB	no flags	Details

<html><head><title>theme-config-spec</title><style type="text/css">ol{margin:0;padding:0}p{margin:0}.c1{color:#aa22ff;font-size:9pt;background-color:#ffffff;font-family:Courier New;font-weight:bold}.c3{color:#bb4444;font-size:9pt;background-color:#ffffff;font-family:Courier New}.c6{color:#666666;font-size:9pt;background-color:#ffffff;font-family:Courier New}.c11{color:#666666;font-size:10pt;background-color:#f8f8f8}.c7{font-size:9pt;background-color:#ffffff;font-family:Courier New}.c16{max-width:502.5pt;background-color:#ffffff;padding:72pt 52.5pt 72pt 57pt}.c13{list-style-type:decimal;margin:0;padding:0}.c4{color:#7d9029;font-size:10pt;background-color:#f8f8f8}.c18{color:#008000;font-size:10pt;background-color:#f8f8f8}.c23{list-style-type:disc;margin:0;padding:0}.c9{color:#ba2121;font-size:10pt;background-color:#f8f8f8}.c10{color:#1155cc;text-decoration:underline}.c12{font-size:9pt;font-family:Courier New}.c2{height:11pt;direction:ltr}.c0{color:#282828;background-color:#f8f8f8}.c5{color:inherit;text-decoration:inherit}.c20{color:#008800;font-style:italic}.c19{padding-left:0pt;margin-left:36pt}.c14{font-size:14pt;font-weight:bold}.c8{direction:ltr}.c21{color:#ff0000}.c17{background-color:#ffffff}.c15{font-weight:bold}.c22{font-style:italic}.title{padding-top:24pt;line-height:1.15;text-align:left;color:#000000;font-size:36pt;font-family:Arial;font-weight:bold;padding-bottom:6pt}.subtitle{padding-top:18pt;line-height:1.15;text-align:left;color:#666666;font-style:italic;font-size:24pt;font-family:Georgia;padding-bottom:4pt}body{color:#000000;font-size:11pt;font-family:Arial}h1{padding-top:24pt;line-height:1.15;text-align:left;color:#000000;font-size:18pt;font-family:Arial;font-weight:bold;padding-bottom:6pt}h2{padding-top:18pt;line-height:1.15;text-align:left;color:#000000;font-size:14pt;font-family:Arial;font-weight:bold;padding-bottom:4pt}h3{padding-top:14pt;line-height:1.15;text-align:left;color:#666666;font-size:12pt;font-family:Arial;font-weight:bold;padding-bottom:4pt}h4{padding-top:12pt;line-height:1.15;text-align:left;color:#666666;font-style:italic;font-size:11pt;font-family:Arial;padding-bottom:2pt}h5{padding-top:11pt;line-height:1.15;text-align:left;color:#666666;font-size:10pt;font-family:Arial;font-weight:bold;padding-bottom:2pt}h6{padding-top:10pt;line-height:1.15;text-align:left;color:#666666;font-style:italic;font-size:10pt;font-family:Arial;padding-bottom:2pt}</style></head><body class="c16"><p class="c8"><span class="c14">Overview</span></p><p class="c2"><span></span></p><p class="c8"><span>This document defines a way for applications to set and get the default themes (icon theme, cursor theme and sound theme), as well as environment-specific themes and fallback themes.</span></p><p class="c2"><span></span></p><p class="c8"><span>The lists are stored in a theme.list file, located at the root of $</span><span class="c17">XDG_DATA_DIRS/themes, as specified in the </span><span class="c10 c17"><a class="c5" href="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">Base Directory specification</a></span><span class="c17">.</span></p><p class="c2"><span></span></p><p class="c2"><span></span></p><p class="c8"><span class="c14">The &lsquo;theme.list&rsquo; file</span></p><p class="c8"><span>This document specifies the format of a </span><span class="c22">theme.list</span><span>&nbsp;file. This is a human-readable file that follows the format for .ini files, commonly used for storing settings and programatically-readable information.</span></p><p class="c8"><span>The values stored within those keys must follow the types defined in the </span><span class="c10"><a class="c5" href="http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html">Desktop Entry specification</a></span><span>. The only value type this specification defines is a list of string (semicolon-separated string values).</span></p><p class="c2"><span></span></p><p class="c8"><span>The file lists two types of sections: &ldquo;Environment&rdquo; and &ldquo;Default&rdquo;. Environment sections should follow &ldquo;[Environment &lt;name&gt;]&rdquo;, where &lt;name&gt; is the name of the environment </span><span class="c15 c21">[See issue #1]</span><span>. Default is a fallback.</span></p><p class="c2"><span></span></p><p class="c8"><span>Every section may store the following keys, all optional:</span></p><p class="c8"><span>- IconTheme, containing a list of theme names for selected icon themes.</span></p><p class="c8"><span>- CursorTheme, containing a list of theme names for selected cursor themes</span></p><p class="c8"><span>- SoundTheme, containing a list of theme names for selected sound themes</span></p><p class="c8"><span>Keys not present in this </span><span>spec</span><span>ification may be added, such keys must begin with X-, such as X-GTKTheme.</span></p><p class="c2"><span></span></p><p class="c8"><span>IconTheme and CursorTheme keys contain lists of theme names as specified in the </span><span class="c10"><a class="c5" href="http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html">Icon Theme specification</a></span><span>. SoundTheme contains a list of theme names as specified in the </span><span class="c10"><a class="c5" href="http://0pointer.de/public/sound-theme-spec.html">Sound Theme specification</a></span><span>.</span></p><p class="c8"><span>List values must be semicolon-separated lists and must have a trailing semicolon. </span></p><p class="c2"><span></span></p><p class="c8"><span>In order to find the chosen icon theme for the current environment, the client application has to go through the following steps:</span></p><p class="c2"><span></span></p><p class="c8"><span>1. Look for theme.list in the next-highest priority XDG_DATA_DIR. If no readable theme.list file is found, or there is no more directory to check, go to step 2.</span></p><p class="c8"><span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1.1. Look for a section called &ldquo;Environment &lt;name&gt;&rdquo;. If the environment is not known, go to 1.2.</span></p><p class="c8"><span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1.1.1. Look for a key called &ldquo;IconTheme&rdquo; containing a non-empty list of values. If no such key is found, or a syntax error is encountered, go to 1.2.</span></p><p class="c8"><span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1.1.2. Read, from left-to-right, the next key in the list.</span></p><p class="c8"><span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1.1.3. Attempt to find a valid theme given the name. If not found, go to step 1.2.</span></p><p class="c8"><span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1.1.4. Return the valid theme name.</span></p><p class="c8"><span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1.2. Look for a section called &ldquo;Default&rdquo;. If no such section is found, go back to step 1.</span></p><p class="c8"><span>2. Return &ldquo;hicolor&rdquo;</span></p><p class="c2"><span></span></p><p class="c8"><span>Finding the cursor theme would execute the same steps, replacing IconTheme by CursorTheme. For the sound theme, IconTheme would be replaced by SoundTheme.</span></p><p class="c2"><span></span></p><hr style="page-break-before:always;display:none;"><p class="c2"><span></span></p><p class="c2"><span></span></p><h2 class="c8"><a name="h.2uviecliik09"></a><span>Examples</span></h2><p class="c2"><span></span></p><p class="c8"><span class="c15">Example theme.list file</span></p><p class="c2"><span></span></p><p class="c8"><span class="c15 c18">[Environment KDE]</span><span class="c0"><br></span><span class="c4">IconTheme</span><span class="c11">=</span><span class="c9">oxygen;crystal;</span><span class="c0"><br></span><span class="c4">CursorTheme</span><span class="c11">=</span><span class="c9">oxygen;</span><span class="c0"><br><br></span><span class="c18 c15">[Environment GNOME]</span><span class="c0"><br></span><span class="c4">IconTheme</span><span class="c11">=</span><span class="c9">tango;</span><span class="c0"><br><br></span><span class="c18 c15">[Default]</span><span class="c0"><br></span><span class="c4">IconTheme</span><span class="c11">=</span><span class="c9">oxygen;</span><span class="c0"><br></span><span class="c4">CursorTheme</span><span class="c11">=</span><span class="c9">oxygen;</span><span class="c0"><br></span><span class="c4">SoundTheme</span><span class="c11">=</span><span class="c9">freedesktop;</span></p><p class="c2"><span></span></p><p class="c2"><span></span></p><p class="c8"><span class="c15">Example implementation in Python</span></p><p class="c2"><span></span></p><p class="c8"><span class="c7 c20"># Pseudocode to get default Icon theme on GNOME</span><span class="c7"><br></span><span class="c7">DE</span><span class="c7">&nbsp;</span><span class="c6">=</span><span class="c7">&nbsp;</span><span class="c3">&quot;GNOME&quot;</span></p><p class="c8"><span class="c7">XDG_DIRS </span><span class="c6">=</span><span class="c7">&nbsp;os</span><span class="c6">.</span><span class="c7">environ</span><span class="c6">.</span><span class="c7">get(</span><span class="c3">&quot;XDG_DATA_HOME&quot;</span><span class="c7">, os</span><span class="c6">.</span><span class="c7">path</span><span class="c6">.</span><span class="c7">expandvars(</span><span class="c3">&quot;$HOME/.local/share&quot;</span><span class="c7">))</span><span class="c7"><br>XDG_DIRS </span><span class="c6">+=</span><span class="c7">&nbsp;</span><span class="c3">&quot;:&quot;</span><span class="c7">&nbsp;</span><span class="c6">+</span><span class="c7">&nbsp;os</span><span class="c6">.</span><span class="c7">environ</span><span class="c6">.</span><span class="c7">get(</span><span class="c3">&quot;XDG_DATA_DIRS&quot;</span><span class="c7">, </span><span class="c3">&quot;/usr/local/share/:/usr/share/&quot;</span><span class="c7">)<br></span><span class="c1">for</span><span class="c7">&nbsp;path </span><span class="c1">in</span><span class="c7">&nbsp;XDG_DIRS:<br></span><span class="c7">&nbsp; &nbsp; </span><span class="c7">f </span><span class="c6">=</span><span class="c7">&nbsp;IniFile(path </span><span class="c6">+</span><span class="c7">&nbsp;</span><span class="c3">&quot;themes/&quot;</span><span class="c7">&nbsp;</span><span class="c6">+</span><span class="c7">&nbsp;</span><span class="c3">&quot;theme.list&quot;</span><span class="c7">)<br> &nbsp; &nbsp;</span><span class="c1">if</span><span class="c7">&nbsp;f:<br> &nbsp; &nbsp; &nbsp; &nbsp;</span><span class="c1">for</span><span class="c7">&nbsp;sectionName </span><span class="c1">in</span><span class="c7">&nbsp;((</span><span class="c3">&quot;Environment &quot;</span><span class="c7">&nbsp;</span><span class="c6">+</span><span class="c7">&nbsp;DE), </span><span class="c3">&quot;Default&quot;</span><span class="c7">):<br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;section </span><span class="c6">=</span><span class="c7">&nbsp;f</span><span class="c6">.</span><span class="c7">section(sectionName)<br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;</span><span class="c1">if</span><span class="c7">&nbsp;section:<br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;</span><span class="c1">if</span><span class="c7">&nbsp;section</span><span class="c6">.</span><span class="c7">key(</span><span class="c3">&quot;IconTheme&quot;</span><span class="c7">):<br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;</span><span class="c1">for</span><span class="c7">&nbsp;theme </span><span class="c1">in</span><span class="c7">&nbsp;section</span><span class="c6">.</span><span class="c7">key(</span><span class="c3">&quot;IconTheme&quot;</span><span class="c7">)</span><span class="c6">.</span><span class="c7">list():<br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;</span><span class="c1">if</span><span class="c7">&nbsp;</span><span class="c7">Theme</span><span class="c7">(theme)</span><span class="c6">.</span><span class="c7">isValid():<br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;</span><span class="c1">return</span><span class="c7">&nbsp;theme<br></span><span class="c1">return</span><span class="c7">&nbsp;</span><span class="c3">&quot;hicolor&quot;</span></p><p class="c2"><span class="c12"></span></p><p class="c2"><span></span></p><p class="c2"><span></span></p><p class="c8"><span class="c15">References</span></p><ol class="c23" start="1"><li class="c19 c8"><span class="c10"><a class="c5" href="https://bugs.freedesktop.org/show_bug.cgi?id=43943">Portland Bug 43943</a></span><span>&nbsp;- Freedesktop needs to define a way to get/set the default icon theme</span></li></ol><p class="c2"><span></span></p><p class="c8"><span class="c15">Issues</span></p><ol class="c13" start="1"><li class="c19 c8"><span>How does the app get the current environment? Alexander Sokorov proposes using </span><span class="c10"><a class="c5" href="http://lists.freedesktop.org/archives/xdg/2011-July/012004.html">$XDG_CURRENT_DESKTOP</a></span><span>. Do gnome and kde use this yet? LXDE and Xfce do.</span></li><li class="c8 c19"><span>Proposed on xdg-list: Use Xsettings to expose the settings to the app. Should it be included?</span></li></ol><p class="c2"><span></span></p></body></html>

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.