1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
|
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "AppStream.ent">
%BOOK_ENTITIES;
]>
<section id="sect-AppStream-IconCache">
<title>Icon Cache</title>
<section id="spec-iconcache-introduction">
<title>Introduction</title>
<para>
In order to display icons in software-centers, distributors should offer a repository of cached icons for applications defined in their AppStream XML files.
The icons should be PNG files or vectorgraphics (PNG is preferred) and match the name referenced in the applications .desktop file.
Their size should be 64x64px, it is okay to just provide one size.
</para>
</section>
<section id="spec-iconcache-location">
<title>Filesystem locations</title>
<para>
All icons of type <literal>cached</literal> must be placed in <filename>/usr/share/swcatalog/icons/%{origin}/%{size}/</filename> or <filename>/var/(lib|cache)/swcatalog/icons/%{origin}/%{size}/</filename>,
where <literal>origin</literal> is the AppStream data origin defined in the AppStream data file (see <xref linkend="spec-asxml-general"/>), and <literal>size</literal>
is <code>64x64</code> or <code>128x128</code> depending on the size of the icon. And icon might be present with different sizes in both directories.
When finding cached icons, they must only be searched for in the same location where the accompanying catalog metadata is located.
For example, icons for <filename>/var/lib/swcatalog/xml/debian-jessie-main.xml.gz</filename> must only be looked up in <filename>/var/lib/swcatalog/icons/debian-jessie-main/</filename> and not also in locations in <filename>/var/cache/</filename> or elsewhere.
</para>
<para>
For example the cache icon <code>krita.png</code> of a component in a data file with the origin <code>jessie</code> should be stored in
<filename>/usr/share/swcatalog/icons/jessie/64x64/krita.png</filename> (or in the <filename>/var/cache</filename> location).
</para>
<para>
Icon scaling factors commonly used for HiDPI display support are part of the size-directory filename and are separated from the regular size via an <code>@</code> sign.
If the scaling factor is 1, it must be omitted from the directory name.
For example, if the icon scaling factor is <literal>2</literal> for icons of size <literal>64x64</literal> from origin <literal>jessie</literal>, the icon must be placed
in <filename>/usr/share/swcatalog/icons/jessie/64x64@2/</filename>.
</para>
<note>
<title>Legacy Support</title>
<para>
In order to support the old icon cache layout, client applications may also look for icons in the folder below the size-directories, assuming
that the icons placed there are of size <code>64x64</code> pixels.
</para>
</note>
</section>
</section>
|
