[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-core-devel
Subject:    Icon specs: please read (LONG)
From:       Geert Jansen <g.t.jansen () stud ! tue ! nl>
Date:       2000-03-21 12:18:23
[Download RAW message or body]

Hi.

I worked out the icon scheme Torsten proposed a bit more and made some minor
modifications. A specification of the scheme I propose is attached below.

It's rather LOONG but please read this and tell me if we want to go this
way and/or if you have any suggestion.

I already implemented some of this (the iconloader) but before I put more
work into it, I need to know whether you want this.

Thanks!

<snip>

RFC: New (and hopefully improved) icon handling.

The KDE artist team proposed a new icon handling scheme. I implemented it
with some minor modifications. The scheme is discussed below.

** Description.

The icon scheme is theme and group/context based. Let's discuss these things
separately.

** Icon Themes.

Theme based means that every icon belongs to a certain "theme". A theme is a
collection of icons which belong together _visually_. They can have a 
distinct look, colordepth or any other property that makes the artist decide 
they are a distinct theme. There is one globally active theme.

A theme can inherit other themes, meaning it doesn't have to provide every 
icon used in KDE. If an icon is not found, the base themes are searched
recursively.

There are 2 standard themes: "hicolor" and "lowcolor" and they are required
to be present. These will contain the icons currently available in KDE. If 
there's no theme specified, one of these is chosen according to the current 
display depth.

** Icon Groups.

Group based means that from the user and API view, icons belong to a group. 
A group denotes a certain location on the screen where the icon is used. 
Possible groups are: 

- Desktop: Icons for use in konqueror, kdesktop, ...
- Kicker: Icons used in kicker
- Small: Icons used in listviews and menus
- Toolbar: Icons in toolbars.
- ListItem: For in Espen's nice dialog.

What makes this very powerfull is that the user can select for every group
individually how and how large the icons will be displayed. This mapping 
from group to visual appearance is specified by: 1. a global theme, and, for 
every icon group, 2. a size, 3. effects and/or possible enhancements.

An example: A user can say: I want icon theme "B/W stylized". For the Desktop 
icons, I want a size of 48 pixels and this effect. The toolbar icons, I want 
32 pixels with no effects.

** Icon contexts

Another concept that needs to be introduced is the icon _Context_. The icon
Context tells you that the icon _means_. It's principal use is to limit the
choice a use has when selecting an icon for something. For example, if the
user creates a .desktop file for an application, only icons with the context 
"Application" should be displayed.

Possible contexts are:

- Device: The icon represents a device
- MimeType: A mimetype.
- FileSystem: A filesystem.
- Application: The icons represents an application.
- Action: The icon represents an action, i.e. in a toolbar. 

Compare the icon context with the the icon group. The former tells you what
the icon _means_, the latter where it is _used_.

Icon context and group are not totally unrelated. Most "Toolbar" group icons
will probably have an "Action" context. On the other hand, "Desktop" group 
icons, can have any context, as devices, mimetypes and all other context can 
and do appear on the desktop.

** Summary

Every icon belongs to a theme. Themes can inherit other themes. Icons have 
(apart from their name) the properties group and context.

** Discussion

Pros:

- The group based view is more intuitive. Icons that are used in the same
  circumstances, will belong to the same group. The user doesn't need to
  specify the settings for every application, just for the group.

- The mapping between icon group and visual result can have lots of
  parameters. It can provide special effects for visually impaired people,
  for example double pixels or a color transform. By being able to choose
  the icon size for every group, a user can customize his desktop.

- Theme based is cool. Seriously, this way it is very easy to add new icon
  themes to KDE. Since themes can inherit other themes, themes don't need to
  provide every icon.

Cons:

- It's not really correct anymore to use KStandardDirs to locate "icon"
  type resources. Due to theme inheritance, you can't just look into some
  directory, but some more intelligent searching needs to be done. Sure, it 
  can just use KIconLoader::iconPath(), but it would not be very usefull
  because: The application has to respect the settings the user has 
  given for the group and cannot display it directly as it is on disk. 
  KIconLoader will apply these efects transparently and it should be the
  only code that does that. I don't really see this as a con, but sources 
  using findResource("icon", "fiets") will need to be ported.

- The change is very invasive. Not complex, but as almost every KDE app uses
  icons, allmost all sources will be touched.


** API:

The API remains more or less the same, except that icons are not loaded by
_size_, but by _group_.

So: loader->loadIcon("kedit", Large), 
will become: loader->loadIcon("kedit", Desktop)

You can also specify the icon context. It defaults to any context.
These lines:

loader->loadIcon("kedit", Desktop);
loader->loadIcon("kedit", Desktop, Application);

will load the same icon.


** Global configuration:

I propose the section [Icons] in kdeglobals. This will contain:

[Icons]
Theme=bw
KickerSize=48
KickerDoublePixels=false
KickerXXX=YYY
ToolbarSize=16
ToolbarDoublePixels=true
...


** On disk layout:

The path "icnlib" was proposed for the new icon hierarchy. This allows some
more compatibility with user's KDE1 ~/.kde/share dir. The "icons" directory
can still contain miscelaneous icons, not belonging to a theme.

In icnlib/, there's are directory for each theme. In each theme directory,
there's a file called index.desktop. This file contains something like this:

[KDE Icon Theme]
Name=B/W
Description=Black and White
Inherits=hicolor,lowcolor
Directories=huge/apps,large/mimetypes
[huge/apps]
Size=128
Type=Fixed
Context=Application
[large/mimetypes]
Size=64
Type=Scalable
Context=MimeType

The first three lines are self explanatory. The "Directories=" lines contains
a list of subdirectories, each containing a set of icons having a specific 
size, type and context. These directories determine what's available. As
said before, the user can choose to use any of these available types for any 
of the icon groups.

The name of the subdirectories can be chosen freely, as long as there's a 
correct "Directory=" line in the index file.  One exception are the standard 
themes: "lowcolor" and "hicolor". They must use standard names, as other KDE 
applications will install icons there. I propose the names <size>/<context>.

Example:

$KDEDIR/share/icnlib:

  /hicolor/
    index.desktop
    /large/mimetypes
      tex.png
      tar.png
    /huge/apps
      kedit.png
      kfind.png

  /mytheme/
    index.desktop
    /insane/
      pica.png
      picb.png
 

** Applications using icons

If an application provides multiple versions of an icon, each for a specific 
theme (only "lowcolor" and "hicolor" are standard) the icons should be 
installed under the icnlib/ hierarchy. This is possible because the
hierarchy below icnlib/lowcolor and icnlib/hicolor is standard.

For applications providing only one icon, not requiring themeing 
functionality, icons can be installed in (like the current situation):

$KDEDIR/share:

  /apps/<appname>/pics
  /icons/

$KDEHOME/share:

  /apps/<appname>/pics
  /icons/

From the API side, these legacy icons can be loaded by requesting the group
"User". So:

loader->loadIcon("pica", User)

or, shorter:

KIconLoader::UserIcon("pica")

will load an application specific icon from disk, without applying any effects.


** Misc. notes

The concepts Context and Group where not there/used consistently in the old
scheme. For example: the XXXIcon() functions. BarIcon() loads a toolbar
icon: an icon in the Toolbar _group_. MimeIcon(), loads an icon for a 
mimetype _context_. A grep through the sources indicates that BarIcon() is
used extensively, while the _context_ functions are not. I think it's better
not to provide the latter because of consistency.


** Conclusion

It is my opinion that the new scheme is more flexible and has no
disadvantages. Hence it should be used.

</snip>

 -- 
    Geert Jansen                       email: <g.t.jansen at stud.tue.nl>
    Phylosopher, Physicist,                    email: <jansen at kde.org>           
    KDE enthusiast                                 PGP key ID: 0xD2B5E7CE            

[prev in list] [next in list] [prev in thread] [next in thread]