[prev in list] [next in list] [prev in thread] [next in thread]
List: kde-artists
Subject: K-ARTIST:Fwd: Icon Themes spec [draft]
From: Torsten Rahn <tackat () kde ! org>
Date: 2002-04-26 1:54:10
[Download RAW message or body]
Great News!
It seems we'll agree on a common desktop icontheme standard soon which seems
to be mostly based on KDE's icon theme stuff :-)
Please have a look at it and feel free to comment!
The mailinglist archive is available here:
https://listman.redhat.com/pipermail/xdg-list/2002-April/date.html
I already made a reply.
Greetings,
Tackat
---------- Forwarded Message ----------
Subject: Icon Themes spec [draft]
Date: Today 18:04:29
From: Alex Larsson <alexl@redhat.com>
To: xdg-list@freedesktop.org
Here is the first draft of the icon theme spec. It's also availible in
html at: http://people.redhat.com/alexl/icon-theme-spec.html
It's mostly based on how KDE does it, with some added stuff that nautilus
needs.
Removed keys from KDE:
DisplayDepth - Maybe this would be nice, but i don't like it being
8 or 32. What if I run in 16 bit?
ScreenShot, Example - These didn't seem to be used in KDE
LinkOverlay, LockOverlay, ZipOverlay - These are KDE specific
All the icon default size keys, they are also KDE specific.
The icon search order is also slightly changed. Kde looks for an exact
match for png, then a loose match for png, then an exact match for xpm,
and last a loose match for xpm. In the spec we do exact matches for svg,
png, and xpm, then we look for loose matches for them.
I also made the Context key optional. I'm not sure about this, but I'm
not even sure i like the Context key. Maybe it needs better
standardization if we're gonna keep it.
Comments?
--
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Alexander Larsson Red Hat, Inc
alexl@redhat.com alla@lysator.liu.se
He's a witless bohemian cyborg from a doomed world. She's a warm-hearted
communist femme fatale who dreams of becoming Elvis. They fight crime!
-------------------------------------------------------
--
David FAURE, david@mandrakesoft.com, faure@kde.org
http://people.mandrakesoft.com/~david/
Contributing to: http://www.konqueror.org/, http://www.koffice.org/
KDE, Making The Future of Computing Available Today
-------------------------------------------------------
--
Dipl.-Phys. Torsten Rahn
<tackat@suse.de> <tackat@kde.org> <tackat@tackat.org>
KDE - Conquer Your Desktop!
http://www.kde.org
[" " (TEXT/xml)]
<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
]>
<article id="index">
<articleinfo>
<title>Icon Theme Specification</title>
<releaseinfo>Version 0.1</releaseinfo>
<date>22 April 2002</date>
<authorgroup>
<author>
<firstname>Alexander</firstname>
<surname>Larsson</surname>
<affiliation>
<address>
<email>alexl@redhat.com</email>
</address>
</affiliation>
</author>
</authorgroup>
</articleinfo>
<sect1 id="overview">
<title>Overview</title>
<para>
An icon theme is a set of icons that share a common look and
feel. The user can then select the icon theme that they want to
use, and all apps use icons from the theme. The initial user of
icon themes is the icon field of the desktop file specification,
but in the future it can have other uses (such as mimetype
icons).
</para>
<para>
From a programmer perspective an icon theme is just a
mapping. Given a set of directories to look for icons in and a theme
name it maps from icon name and nominal icon size to an icon filename.
</para>
</sect1>
<sect1 id="definitions">
<title>Definitions</title>
<variablelist>
<varlistentry>
<term>Icon Theme</term>
<listitem>
<para>
An icon theme is a named set of icons. It is used to map
from an iconname and size to a files. Themes may inherit
from other themes as a way to extend them.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Icon file</term>
<listitem>
<para>
An icon file is an image that can be loaded and used as an
icon. The supported image file formats are PNG, XPM and SVG.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Base Directory</term>
<listitem>
<para>
Icons and themes are searched for in a set of directories,
called base directories. The themes are stored in
subdirectories of the base directories.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="directory_layout">
<title>Directory Layout</title>
<para>
Icons and themes are looked for in a set of directories. As a
default apps should look in $HOME/.icons, /usr/share/icons and
/usr/share/pixmaps (in that order). Applications may further add
their own icon directories to this list, and users may extend or
change the list (in application/desktop specific ways).In each of
these directories themes are stored as subdirectories. A theme can
be spread across several directories by having subdirectories of
the same name. This way users can extend and override system
themes.
</para>
<para>
Each theme is stored as subdirectories of the base
directories. The internal name of the theme is the name of the
subdirectory, although the user-visible name as specified by the
theme may be different. Hence, theme names are case sensitive, and
are limited to ASCII characters. Theme names may also not contain
comma or space.
</para>
<para>
In at least one of the theme directories there must be a file
called index.theme that describes the theme. The first index.theme
found while searching the base directories in order is used. This
file describes the general attributes of the theme.
</para>
<para>
In the theme directory are also a set of subdirectories containing
image files. Each directory contains icons designed for a certain
nominal icon size, as described by the index.theme file. The
subdirectories are allowed to be several levels deep, e.g. the
subdirectory "48x48/apps" in the theme "hicolor" would end up at
$basedir/hicolor/48x48/apps.
</para>
<para>
The image files must be one of the types: PNG, XPM, or SVG, and
the extension must be ".png", ".xpm", or ".svg" (lower case). In
addition to this there may be an additional file with extra
icon-data for each file. It should have the same basename as the
image file, with the extension ".icon". e.g. if the icon file is
called "mime_source_c.png" the corresponding file would be named
"mime_source_c.icon".
</para>
</sect1>
<sect1 id="file_formats">
<title>File Formats</title>
<para>
Both the icon theme description file and the icon data files are
ini-style text files, as described in the desktop file
specification. They don't have any encoding field, instead they
must always be stored in UTF8 encoding.
</para>
<para>
The index.theme file must starts with a section called "Icon
Theme", with contents according to table 1 below. All lists are
comma-separated.
<table>
<title>Standard Keys</title>
<tgroup cols="4">
<thead>
<row>
<entry>Key</entry>
<entry>Description</entry>
<entry>Value Type</entry>
<entry>Required</entry>
</row>
</thead>
<tbody>
<row>
<entry>Name</entry>
<entry>
short name of the icon theme, used in e.g. lists when
selecting themes.
</entry>
<entry>localestring</entry>
<entry>YES</entry>
</row>
<row>
<entry>Comment</entry>
<entry>
longer string describing the theme
</entry>
<entry>localestring</entry>
<entry>YES</entry>
</row>
<row>
<entry>Inherits</entry>
<entry>
list of themes that this theme inherits from. If an icon
name is not found in the current theme, these themes
will be searched in the specified order.
</entry>
<entry>strings</entry >
<entry>NO</entry>
</row>
<row>
<entry>Directories</entry>
<entry>
list of subdirectories for this theme. For every
subdirectory there must be a section in the index.theme
file describing that directory.
</entry>
<entry>strings</entry >
<entry>YES</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
Each directory specified in the Directory key has a corresponding section
with the same name as the directory. The contents of this section is
listed in table 2 below.
<table>
<title>Per Directory Keys</title>
<tgroup cols="4">
<thead>
<row>
<entry>Key</entry>
<entry>Description</entry>
<entry>Value Type</entry>
<entry>Required</entry>
<entry>Type</entry>
</row>
</thead>
<tbody>
<row>
<entry>Size</entry>
<entry>
Nominal size of the icons in this directory.
</entry>
<entry>integer</entry>
<entry>YES</entry>
</row>
<row>
<entry>Context</entry>
<entry>
the context the icon is normally used in. This can be
used to e.g. let the user pick an specific type of
icon. Currently used contexts are: Actions,
Applications, Devices, FileSystems, MimeTypes.
</entry>
<entry>string</entry>
<entry>NO</entry>
</row>
<row>
<entry>Type</entry>
<entry>
The type of icon sizes for the icons in this
directory. Valid types are Fixed, Scalable and
Threshold. The type decides what other keys in the
section are used.
</entry>
<entry>string</entry>
<entry>YES</entry>
</row>
<row>
<entry>MaxSize</entry>
<entry>
Specifies the maximum size that the icons in this
directory can be scaled to. Defaults to the value
of Size if not present.
</entry>
<entry>string</entry>
<entry>NO</entry>
<entry>Scalable</entry>
</row>
<row>
<entry>MinSize</entry>
<entry>
Specifies the minimum size that the icons in this
directory can be scaled to. Defaults to the value
of Size if not present.
</entry>
<entry>string</entry>
<entry>NO</entry>
<entry>Scalable</entry>
</row>
<row>
<entry>Threshold</entry>
<entry>
The icons in this directory can be used if the size differ
at most this much from the desired size. Defaults to 2 if not
present.
</entry>
<entry>string</entry>
<entry>NO</entry>
<entry>Threshold</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
In addition to these groups you may add extra groups to the
index.theme file in order to extend it. These extensions must
begin with "X-", and can be used to add desktop specific
information to the theme file. Example group names would be "X-KDE
Icon Theme" or "X-Gnome Icon Theme".
</para>
<para>
The optional filename.icon file contains a group called "Icon
Data", with the content listed in table 3.
<table>
<title>Icon Data Keys</title>
<tgroup cols="4">
<thead>
<row>
<entry>Key</entry>
<entry>Description</entry>
<entry>Value Type</entry>
<entry>Required</entry>
</row>
</thead>
<tbody>
<row>
<entry>EmbeddedTextRectangle</entry>
<entry>
If this exist it specifies the four corners of a
rectangle where the program displaying the icon can
embedd text. This is normally used by e.g. file managers
that want to display a preview of text filee contents in
the icon. The corners are specified by a list of for
values: x0,y0,x1,y1. The values are pixel coordinates
from the top left corner of the icon, except for SVG
files, where they are specified in a 1000x1000
coordinate space that is scaled to the final rendered
size of the icon.
</entry>
<entry>integers</entry>
<entry>NO</entry>
</row>
<row>
<entry>AttachPoints</entry>
<entry>
A list of points, separated by "|" that may be used as
anchor points for emblems/overlays. The points are pixel
coordinates from the top left corner of the icon, except
for SVG files, where they are specified in a 1000x1000
coordinate space that is scaled to the final rendered
size of the icon.
</entry>
<entry>points</entry>
<entry>NO</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
Extensions to the filename.icon file are allowed, but the
keys must be begin with "X-" to avoid collisions with future
standardized extensions to this format.
</para>
</sect1>
<sect1 id="icon_lookup">
<title>Icon Lookup</title>
<para>
The icon lookup mechanism has two global settings, the list of
base directories and the internal name of the current theme. Given
these we need to specify how to look up an icon file from the icon
name and the nominal size.
</para>
<para>
The lookup is done first in the current theme, and then
recursively in each of the themes inherited the current theme. As
soon as there is an icon of any size that matches in a theme the
search is stopped. Even if there may be an icon with a size closer
to the correct one in an inherited theme we don't want to use
it. Doing so may generate an inconsistant change in an icon when
you change icon sizes (e.g. zoom in).
</para>
<para>
The lookup inside a theme is done in three phases. First all the
directories are scanned for an exact match, e.g. one where the
allowed size of the icon files match what was looked up. Then all
the directories are scanned for any icon that matches the name. If
that fails we finally fall back on unthemed icons. If we fail to
find any icon at all it is up to the application to pick a good
fallback, as the correct choice depends on the context.
</para>
<para>
The exact algorithm (in pseudocode) for looking up an icon is:
<programlisting>LookupIcon (iconname, size):
for each subdir in $(theme subdir list) {
for each directory in $(basename list) {
for extension in ("svg", "png", "xpm") {
if DirectoryMatchesSize(subdir, size) {
filename = directory/$(themename)/subdirectory/iconname.extension
if exist filename
return filename
}
}
}
}
minimal_size = MAXINT
for each subdir in $(theme subdir list) {
for each directory in $(basename list) {
for extension in "svg", "png", "xpm" {
filename = directory/$(themename)/subdirectory/iconname.extension
if exist filename and DirectorySizeDistance(subdir, size) < minimal_size
closest_filename = filename
minimal_size = DirectorySizeDistance(subdir, size)
}
}
}
if closest_filename set
return closest_filename
for each directory in $(basename list) {
for extension in "svg", "png", "xpm" {
if exists directory/iconname.extension
return directory/iconname.extension
}
}
return failed icon lookup
</programlisting>
With the following helper functions:
<programlisting>DirectoryMatchesSize(subdir, iconsize):
read Type and size data from subdir
if Type is Fixed
return Size == iconsize
if Type is Scaled
return MinSize <= iconsize <= MaxSize
if Type is Threshold
return Size - Threshold <= iconsize <= Size + Threshold
DirectorySizeDistance(subdir, size):
read Type and size data from subdir
if Type is Fixed
return abs(Size - iconsize)
if Type is Scaled
if iconsize < MinSize
return MinSize - iconsize
if iconsize > MaxSize
return iconsize - MaxSize
return 0
if Type is Threshold
if iconsize < Size - Threshold
return MinSize - iconsize
if iconsize > Size + Threshold
return iconsize - MaxSize
return 0
</programlisting>
</para>
</sect1>
<sect1 id="example">
<title>Example</title>
<para>
Here is an example index.theme file:
<programlisting>[Icon Theme]
Name=Birch
Name[sv]=Björk
Comment=Icon theme with a wooden look
Comment[sv]=Träinspirerat ikontema
Inherits=wood,default
Directories=48x48/apps,48x48/mimetypes,32x32/apps,any/apps,any/mimetypes
[any/apps]
Size=48
Type=Scalable
MinSize=1
MaxSize=256
Context=Applications
[any/mimetypes]
Size=48
Type=Scalable
MinSize=1
MaxSize=256
Context=MimeTypes
[32x32/apps]
Size=32
Type=Fixed
Context=Applications
[48x48/apps]
Size=48
Type=Fixed
Context=Applications
[48x48/mimetypes]
Size=48
Type=Fixed
Context=MimeTypes</programlisting>
The corresponding directory tree in the /usr/share/icons
directory could look like this:
<programlisting>birch/index.theme
birch/any/apps/mozilla.svg
birch/any/mimetypes/mime_text_plain.svg
birch/any/mimetypes/mime_text_plain.icon
birch/48x48/apps/mozilla.png
birch/32x32/apps/mozilla.png
birch/48x48/mimetypes/mime_text_plain.png
birch/48x48/mimetypes/mime_text_plain.icon</programlisting>
Where birch/any/mimetypes/mime_text_plain.icon contains:
<programlisting>[Icon Data]
EmbeddedTextRectangle=100,100,900,900
AttachPoints=200,200|800,200|500,500|200,800|800,800</programlisting>
And birch/48x48/mimetypes/mime_text_plain.icon contains:
<programlisting>[Icon Data]
EmbeddedTextRectangle=8,8,40,40
AttachPoints=200,200|800,200|500,500|200,800|800,800</programlisting>
</para>
<para>
In this example a lookup of "mozilla" would get the prerendered
48x48 and 32x32 icons before the SVG icons due to the order of
Directories.
</para>
</sect1>
<appendix id="changes">
<title>Change history</title>
<formalpara>
<title>Version 0.1, 22 April 2002, Alexander Larsson</title>
<para>
<itemizedlist>
<listitem>
<para>
Created initial draft.
</para>
</listitem>
</itemizedlist>
</para>
</formalpara>
</appendix>
</article>
_______________________________________________
kde-artists mailing list
kde-artists@mail.kde.org
http://mail.kde.org/mailman/listinfo/kde-artists
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic