Loading and installing icons in KDE
Icons are an important user interface element in any desktop environment. Because of different user preferences and video hardware, one icon may come in different sizes and display depths. In order to make this manageable, a standard way of storing and accessing icons has been developed.
Icons are loaded using the class KIconLoader. Every KDE appliation has a global iconloader object. You can access this object with:
KDE TechBase #include <kglobal.h>
#include <kiconloader.h>
KIconLoader *loader = KGlobal::iconLoader();
The iconloader loads icons, transparently caches them and applies effects. To load an icon, use the method loadIcon(), which is defined like this:
QPixmap loadIcon( QString name, int group, int size=0,
int state=KIcon::DefaultState,
QString *path_store=0L, bool canReturnNull=false);
As you see, there are a lot of parameters. The first two are most important:
The idea of an icon group is an important concept in the KDE icon scheme. The icon group denotes where on the screen the icon is going to be used. This is relevant because the KDE user can bind icon sizes and visual effects to each group. When passing the icon group to the icon loader, you are in fact telling it which incarnation of the icon to load. And by requiring the group argument, the iconloader provides the means to have a consistent and configurable icon look over the whole KDE desktop.
For example: The user can configure that he wants 32 pixel icons with 0.2 desaturation for the main toolbars.
The available icon groups are given below. All are defined in the KIcon class, so prefix them with KIcon::.
So, to load the icon "kfind" for use in the Desktop group, you'd use:
QPixmap icon;
icon = loader->loadIcon("kfind", KIcon::Desktop);
Now lets discuss the other parameters of loadIcon.
Icons may come in different sizes and display depths. I shall refer to these icons as themed icons. Icons that come in just one form are referred to as unthemed icons.
Themed icons come in different sizes and display depths. The standard sizes are:
Please refer to the KDE icon factory for information on which icon sizes are mandatory and more. Remember that each of these sizes can be bound to an icon group.
Themed icons are stored in a directory hierarchy according to their 1. depth, 2. size and 3. context. The term context is new concept introduced by the KDE icon scheme. The context of an icon is what the icon means. The standard contexts are given below:
Contexts are important in one case: selecting an icon. When an application wants the user to select an icon for, say, a toolbar, it would be very user unfriendly to show every single icon installed in KDE. Instead, it is much better to let the user select an icon from the "action" icons only. These all represent some action and therefore are suitable for in toolbars.
The directory hierarchy in which themed icons are stored follows. The directory names are self explanatory.
hicolor/
22x22/
actions/
apps/
devices/
filesystems/
mimetypes/
32x32/
...
48x48/
...
locolor/
16x16/
...
22x22/
...
32x32/
...
Themed icons can be installed either globally with respect to KDE, or in application specific place. In the global case, the icon theme hierarchy resides under $KDEDIR/share/icons while in the application specific case, it is under $KDEDIR/share/apps/$APPNAME/icons.
The KDE source configuration system (specifically, am_edit) has support for installing themed icons. First, you have to name your icons in a way that it is clear where it must be installed. The naming convention is explained in the table below:
| depth | size | - | context | - | name | .png |
|---|---|---|---|---|---|---|
| hi | 16 | action | ||||
| lo | 22 | app | ||||
| 32 | device | |||||
| 48 | filesys | |||||
| mime |
Examples:
lo22-action-open.png hi48-app-kfind.png
To install these icons globally, add this line to your Makefile.am.
KDE_ICON = open kfind
and to install them in an application specific directory, use this:
icondir = $(kde_datadir)/myapp/icons icon_ICON = open kfind
Themed icons are loaded with the iconloader, using the standard icon groups. For example:
QPixmap pm;
pm = loader->loadIcon("kfind", KIcon::Desktop);
This will load the "kfind" icon, of depth and size specified for the Desktop group.
Unthemed icons are installed in $KDEDIR/share/apps/$APPNAME/pics. To install them, use this in you Makefile.am.
icondir = $(kde_datadir)/myapp/pics icon_DATA = open kfind
You must not give the icons special names. Also, no further processing is done on them: no effects and size,depth selection is done.
Unthemed icons can be loaded with the iconloader using the User group. This will load a user icon:
QPixmap pm;
pm = loader->loadIcon("myicon", KIcon::User);
There are 3 ways to install icons: global themed, application specific themed and unthemed. All types of icons can be loaded with the iconloader. You should choose a specific installation depending on your needs.
Initial Author: Geert Jansen <jansen@kde.org>
