Difference between revisions of "Icon Loading"

From Trinity Desktop Project Wiki
Jump to navigation Jump to search
m (Added table of contents)
m (-Applicable to TDE (redundant), categories to bottom)
Line 1: Line 1:
 
'''Icons''' are an important user interface element in any desktop environment.
[[Category:KDE3]]
 
[[Category:Architecture]]
 
[[Category:Developers]]
 
{{Applicable to TDE}}
 
 
<!--T:2-->
 
Icons are an important user interface element in any desktop environment.
 
 
Because of different user preferences and video hardware, one icon may
 
Because of different user preferences and video hardware, one icon may
 
come in different sizes and display depths. In order to make this manageable,
 
come in different sizes and display depths. In order to make this manageable,
Line 12: Line 6:
 
__TOC__
 
__TOC__
   
== Loading icons == <!--T:3-->
+
== Loading icons ==
   
=== Accessing the iconloader === <!--T:4-->
+
=== Accessing the iconloader ===
   
<!--T:5-->
 
 
Icons are loaded using the class [http://trinitydesktop.org/docs/trinity/tdelibs/tdecore/html/classTDEIconLoader.html TDEIconLoader]. Every TDE
 
Icons are loaded using the class [http://trinitydesktop.org/docs/trinity/tdelibs/tdecore/html/classTDEIconLoader.html TDEIconLoader]. Every TDE
 
appliation has a global iconloader object. You can access this object with:
 
appliation has a global iconloader object. You can access this object with:
   
<!--T:6-->
 
 
<syntaxhighlight lang="cpp-qt">
 
<syntaxhighlight lang="cpp-qt">
 
#include <tdeglobal.h>
 
#include <tdeglobal.h>
Line 28: Line 20:
 
</syntaxhighlight>
 
</syntaxhighlight>
   
=== Loading icons with loadIcon() === <!--T:7-->
+
=== Loading icons with loadIcon() ===
   
<!--T:8-->
 
 
The iconloader loads icons, transparently '''caches''' them and applies effects.
 
The iconloader loads icons, transparently '''caches''' them and applies effects.
 
To load an icon, use the method [http://trinitydesktop.org/docs/trinity/tdelibs/tdecore/html/classTDEIconLoader.html#a73764006b6eaa18ee5a0ac71ee417c5a loadIcon()], which is defined like this:
 
To load an icon, use the method [http://trinitydesktop.org/docs/trinity/tdelibs/tdecore/html/classTDEIconLoader.html#a73764006b6eaa18ee5a0ac71ee417c5a loadIcon()], which is defined like this:
   
<!--T:9-->
 
 
<syntaxhighlight lang="cpp-qt">
 
<syntaxhighlight lang="cpp-qt">
 
TQPixmap loadIcon( TQString name, int group, int size=0,
 
TQPixmap loadIcon( TQString name, int group, int size=0,
Line 41: Line 31:
 
</syntaxhighlight>
 
</syntaxhighlight>
   
<!--T:10-->
 
 
As you see, there are a lot of parameters. The first two are most important:
 
As you see, there are a lot of parameters. The first two are most important:
   
<!--T:11-->
 
 
# '''name''' - The name of the icon to load. You must pass the bare icon name here, without extension.
 
# '''name''' - The name of the icon to load. You must pass the bare icon name here, without extension.
 
# '''group''' - The icon group. This is explained below.
 
# '''group''' - The icon group. This is explained below.
   
=== Icon groups === <!--T:12-->
+
=== Icon groups ===
   
<!--T:13-->
 
 
The idea of an ''icon group'' is an important concept in the TDE icon
 
The idea of an ''icon group'' is an important concept in the TDE icon
 
scheme. The icon group denotes where on the screen the icon is going to be used.
 
scheme. The icon group denotes where on the screen the icon is going to be used.
Line 59: Line 46:
 
the whole Trinity desktop.
 
the whole Trinity desktop.
   
<!--T:14-->
 
 
For example: The user can configure that (s)he wants 32 pixel icons with 0.2
 
For example: The user can configure that (s)he wants 32 pixel icons with 0.2
 
desaturation for the main toolbars.
 
desaturation for the main toolbars.
   
<!--T:15-->
 
 
The available icon groups are given below. All are defined in the
 
The available icon groups are given below. All are defined in the
 
[http://trinitydesktop.org/docs/trinity/tdelibs/tdecore/html/classTDEIcon.html TDEIcon]
 
[http://trinitydesktop.org/docs/trinity/tdelibs/tdecore/html/classTDEIcon.html TDEIcon]
 
class, so prefix them with ''TDEIcon::''.
 
class, so prefix them with ''TDEIcon::''.
   
<!--T:16-->
 
 
* '''Desktop''' - Icons for use on the desktop, in the filemanager and similar places.
 
* '''Desktop''' - Icons for use on the desktop, in the filemanager and similar places.
 
* '''Toolbar''' - Icon for use innormal toolbars.
 
* '''Toolbar''' - Icon for use innormal toolbars.
Line 76: Line 60:
 
* '''User''' - Special group for loading application specific icons. This is explained in section 3: Installing icons.
 
* '''User''' - Special group for loading application specific icons. This is explained in section 3: Installing icons.
   
<!--T:17-->
 
 
So, to load the icon "kfind" for use in the ''Desktop'' group, you'd use:
 
So, to load the icon "kfind" for use in the ''Desktop'' group, you'd use:
   
<!--T:18-->
 
 
<syntaxhighlight lang="cpp-qt">
 
<syntaxhighlight lang="cpp-qt">
 
TQPixmap icon;
 
TQPixmap icon;
Line 85: Line 67:
 
</syntaxhighlight>
 
</syntaxhighlight>
   
=== loadIcon() continued === <!--T:19-->
+
=== loadIcon() continued ===
   
<!--T:20-->
 
 
Now lets discuss the other parameters of ''loadIcon''.
 
Now lets discuss the other parameters of ''loadIcon''.
   
<!--T:21-->
 
 
# '''size''' - Override the globally configured size for the specified icon group. Effects bound to the group are still applied.
 
# '''size''' - Override the globally configured size for the specified icon group. Effects bound to the group are still applied.
 
# '''state''' - The icon state. The icon state is one of ''TDEIcon::DefaultState'', ''TDEIcon::ActiveState'' or ''KIcon::DisabledState''. The icon state denotes in which state the icon is. Toolbar buttons, for example, are in state ''active'' if the mouse pointer is above them, in state ''disabled'' when they are not available, and ''default'' otherwise. Each icon state can have different effects assigned to it to give the user visual feedback.
 
# '''state''' - The icon state. The icon state is one of ''TDEIcon::DefaultState'', ''TDEIcon::ActiveState'' or ''KIcon::DisabledState''. The icon state denotes in which state the icon is. Toolbar buttons, for example, are in state ''active'' if the mouse pointer is above them, in state ''disabled'' when they are not available, and ''default'' otherwise. Each icon state can have different effects assigned to it to give the user visual feedback.
Line 96: Line 76:
 
# '''canReturnNull''' - If the requested icon is not found, the result of ''loadIcon'' depends on this parameter. If ''canReturnNull'' is ''true'', a null pixmap will be returned, if not, the "unknown" icon is returned.
 
# '''canReturnNull''' - If the requested icon is not found, the result of ''loadIcon'' depends on this parameter. If ''canReturnNull'' is ''true'', a null pixmap will be returned, if not, the "unknown" icon is returned.
   
== Installing icons == <!--T:22-->
+
== Installing icons ==
   
<!--T:23-->
 
 
Icons may come in different sizes and display depths.
 
Icons may come in different sizes and display depths.
 
I shall refer to these icons as ''themed icons''. Icons that come in
 
I shall refer to these icons as ''themed icons''. Icons that come in
 
just one form are referred to as ''unthemed icons''.
 
just one form are referred to as ''unthemed icons''.
   
=== Default icon sizes === <!--T:24-->
+
=== Default icon sizes ===
   
<!--T:25-->
 
 
Themed icons come in different sizes and display depths. The standard sizes
 
Themed icons come in different sizes and display depths. The standard sizes
 
are:
 
are:
   
<!--T:26-->
 
 
;40 Colors
 
;40 Colors
 
:16x16 pixels
 
:16x16 pixels
Line 115: Line 92:
 
:32x32 pixels
 
:32x32 pixels
   
<!--T:27-->
 
 
;Truecolor
 
;Truecolor
 
:22x22 pixels
 
:22x22 pixels
Line 121: Line 97:
 
:48x48 pixels
 
:48x48 pixels
   
<!--T:28-->
 
 
Please refer to the [https://web.archive.org/web/20060924173511/http://wiki.kde.org/tiki-index.php?page=Icon+Guide KDE Icon Guide]
 
Please refer to the [https://web.archive.org/web/20060924173511/http://wiki.kde.org/tiki-index.php?page=Icon+Guide KDE Icon Guide]
 
for information on which icon sizes are mandatory and more.
 
for information on which icon sizes are mandatory and more.
 
Remember that each of these sizes can be bound to an icon group.
 
Remember that each of these sizes can be bound to an icon group.
   
=== Icon context === <!--T:29-->
+
=== Icon context ===
   
<!--T:30-->
 
 
Themed icons are stored in a directory hierarchy according to their
 
Themed icons are stored in a directory hierarchy according to their
 
'''1. depth''', '''2. size''' and '''3. context'''.
 
'''1. depth''', '''2. size''' and '''3. context'''.
Line 135: Line 109:
 
contexts are given below:
 
contexts are given below:
   
<!--T:31-->
 
 
* '''action''' - The icon represents an action in a toolbar, for example "Open" or "Save".
 
* '''action''' - The icon represents an action in a toolbar, for example "Open" or "Save".
 
* '''application''' - The icon represents an application, for example "kfind".
 
* '''application''' - The icon represents an application, for example "kfind".
Line 142: Line 115:
 
* '''mimetype''' - The icon represents an mimetype, for example "text/html".
 
* '''mimetype''' - The icon represents an mimetype, for example "text/html".
   
<!--T:32-->
 
 
''Contexts'' are important in one case: selecting an
 
''Contexts'' are important in one case: selecting an
 
icon. When an application wants the user to select an icon for, say, a
 
icon. When an application wants the user to select an icon for, say, a
Line 150: Line 122:
 
therefore are suitable for in toolbars.
 
therefore are suitable for in toolbars.
   
=== Directory hierarchy === <!--T:33-->
+
=== Directory hierarchy ===
   
<!--T:34-->
 
 
The directory hierarchy in which themed icons are stored follows.
 
The directory hierarchy in which themed icons are stored follows.
 
The directory names are self explanatory.
 
The directory names are self explanatory.
   
<!--T:35-->
 
 
hicolor/
 
hicolor/
 
22x22/
 
22x22/
Line 177: Line 147:
 
...
 
...
   
=== Directory roots === <!--T:36-->
+
=== Directory roots ===
   
<!--T:37-->
 
 
Themed icons can be installed either globally with respect to TDE, or in
 
Themed icons can be installed either globally with respect to TDE, or in
 
application specific place. In the global case, the icon theme hierarchy
 
application specific place. In the global case, the icon theme hierarchy
Line 185: Line 154:
 
case, it is under $TDEDIR/share/apps/$APPNAME/icons.
 
case, it is under $TDEDIR/share/apps/$APPNAME/icons.
   
=== Installing themed icons === <!--T:38-->
+
=== Installing themed icons ===
   
<!--T:39-->
 
 
The Trinity framework has support for installing themed icons. First, you
 
The Trinity framework 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.
 
have to name your icons in a way that it is clear where it must be installed.
Line 193: Line 161:
 
the table below:
 
the table below:
   
<!--T:40-->
 
 
{|
 
{|
 
!|depth
 
!|depth
Line 214: Line 181:
 
|}
 
|}
   
<!--T:41-->
 
 
Examples:
 
Examples:
   
<!--T:42-->
 
 
lo22-action-open.png
 
lo22-action-open.png
 
hi48-app-kfind.png
 
hi48-app-kfind.png
   
<!--T:43-->
 
 
Then use the following macro in your CMakeLists.txt file:
 
Then use the following macro in your CMakeLists.txt file:
   
Line 239: Line 203:
 
-->
 
-->
   
=== Loading themed icons === <!--T:47-->
+
=== Loading themed icons ===
 
Themed icons are loaded with the iconloader, using the standard icon groups.
 
Themed icons are loaded with the iconloader, using the standard icon groups.
 
For example:
 
For example:
   
<!--T:48-->
 
 
<syntaxhighlight lang="cpp-qt">
 
<syntaxhighlight lang="cpp-qt">
 
TQPixmap pm;
 
TQPixmap pm;
 
pm = loader->loadIcon("kfind", TDEIcon::Desktop);
 
pm = loader->loadIcon("kfind", TDEIcon::Desktop);
 
</syntaxhighlight>
 
</syntaxhighlight>
 
<!--T:49-->
 
 
This will load the "kfind" icon, of depth and size specified for the
 
This will load the "kfind" icon, of depth and size specified for the
 
''Desktop'' group.
 
''Desktop'' group.
   
=== Unthemed icons === <!--T:50-->
+
=== Unthemed icons ===
   
<!--T:51-->
 
 
Unthemed icons are installed in $TDEDIR/share/apps/$APPNAME/pics.
 
Unthemed icons are installed in $TDEDIR/share/apps/$APPNAME/pics.
 
To install them, use this in your CMakeLists.txt:
 
To install them, use this in your CMakeLists.txt:
Line 268: Line 228:
 
-->
 
-->
   
<!--T:53-->
 
 
You must not give the icons special names.
 
You must not give the icons special names.
 
Also, no further processing is done on them: no effects and size, depth selection
 
Also, no further processing is done on them: no effects and size, depth selection
 
is done.
 
is done.
   
<!--T:54-->
 
 
Unthemed icons can be loaded with the iconloader using the ''User''
 
Unthemed icons can be loaded with the iconloader using the ''User''
 
group. This will load a user icon:
 
group. This will load a user icon:
   
<!--T:55-->
 
 
<syntaxhighlight lang="cpp-qt">
 
<syntaxhighlight lang="cpp-qt">
 
TQPixmap pm;
 
TQPixmap pm;
Line 283: Line 240:
 
</syntaxhighlight>
 
</syntaxhighlight>
   
== Conclusion == <!--T:56-->
+
== Conclusion ==
 
There are 3 ways to install icons: global themed, application
 
There are 3 ways to install icons: global themed, application
 
specific themed and unthemed. All types of icons can be loaded with the
 
specific themed and unthemed. All types of icons can be loaded with the
Line 289: Line 246:
 
needs.
 
needs.
   
 
<!--T:57-->
 
 
''Initial Author:'' Geert Jansen [mailto:jansen@kde.org &lt;jansen@kde.org&gt;]
 
''Initial Author:'' Geert Jansen [mailto:jansen@kde.org &lt;jansen@kde.org&gt;]
   
 
[[Category:KDE3]]
<!--T:58-->
 
 
[[Category:Architecture]]
 
[[Category:Developers]]

Revision as of 15:44, 21 April 2022

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.

Loading icons

Accessing the iconloader

Icons are loaded using the class TDEIconLoader. Every TDE appliation has a global iconloader object. You can access this object with:

#include <tdeglobal.h>
#include <kiconloader.h>
 
TDEIconLoader *loader = TDEGlobal::iconLoader();

Loading icons with loadIcon()

The iconloader loads icons, transparently caches them and applies effects. To load an icon, use the method loadIcon(), which is defined like this:

TQPixmap loadIcon( TQString name, int group, int size=0,
                   int state=TDEIcon::DefaultState, 
                   TQString *path_store=0L, bool canReturnNull=false);

As you see, there are a lot of parameters. The first two are most important:

  1. name - The name of the icon to load. You must pass the bare icon name here, without extension.
  2. group - The icon group. This is explained below.

Icon groups

The idea of an icon group is an important concept in the TDE icon scheme. The icon group denotes where on the screen the icon is going to be used. This is relevant because the TDE 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 Trinity desktop.

For example: The user can configure that (s)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 TDEIcon class, so prefix them with TDEIcon::.

  • Desktop - Icons for use on the desktop, in the filemanager and similar places.
  • Toolbar - Icon for use innormal toolbars.
  • MainToolbar - Icons for use in the main toolbar. An application can have multiple toolbars, of which one is always the main toolbar. This typically has entries like "Save" and "Open" and contains larger icons than the other toolbars.
  • Small - Various small icons, like the ones in popup menus, listviews and treelists.
  • Panel - Icons for use in Kicker panels.
  • User - Special group for loading application specific icons. This is explained in section 3: Installing icons.

So, to load the icon "kfind" for use in the Desktop group, you'd use:

TQPixmap icon;
icon = loader->loadIcon("kfind", TDEIcon::Desktop);

loadIcon() continued

Now lets discuss the other parameters of loadIcon.

  1. size - Override the globally configured size for the specified icon group. Effects bound to the group are still applied.
  2. state - The icon state. The icon state is one of TDEIcon::DefaultState, TDEIcon::ActiveState or KIcon::DisabledState. The icon state denotes in which state the icon is. Toolbar buttons, for example, are in state active if the mouse pointer is above them, in state disabled when they are not available, and default otherwise. Each icon state can have different effects assigned to it to give the user visual feedback.
  3. path_store - If you want to know where the icon you just loaded is in the filesystem, you can pass a pointer to a TQString here and the icon path is stored there.
  4. canReturnNull - If the requested icon is not found, the result of loadIcon depends on this parameter. If canReturnNull is true, a null pixmap will be returned, if not, the "unknown" icon is returned.

Installing icons

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.

Default icon sizes

Themed icons come in different sizes and display depths. The standard sizes are:

40 Colors
16x16 pixels
22x22 pixels
32x32 pixels
Truecolor
22x22 pixels
32x32 pixels
48x48 pixels

Please refer to the KDE Icon Guide for information on which icon sizes are mandatory and more. Remember that each of these sizes can be bound to an icon group.

Icon context

Themed icons are stored in a directory hierarchy according to their 1. depth, 2. size and 3. context. The term context is a new concept introduced by KDE/Trinity icon schemes. The context of an icon is what the icon means. The standard contexts are given below:

  • action - The icon represents an action in a toolbar, for example "Open" or "Save".
  • application - The icon represents an application, for example "kfind".
  • device - The icon represents something related to a device, for example "floppy" or "mount".
  • filesystem - The icon represents something in the filesystem, for example "directory", "socket" or "trashcan".
  • mimetype - The icon represents an mimetype, for example "text/html".

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 Trinity. 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.

Directory hierarchy

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/
        ...

Directory roots

Themed icons can be installed either globally with respect to TDE, or in application specific place. In the global case, the icon theme hierarchy resides under $TDEDIR/share/icons while in the application specific case, it is under $TDEDIR/share/apps/$APPNAME/icons.

Installing themed icons

The Trinity framework 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

Then use the following macro in your CMakeLists.txt file:

tde_install_icons( )


Loading themed icons

Themed icons are loaded with the iconloader, using the standard icon groups. For example:

TQPixmap pm;
pm = loader->loadIcon("kfind", TDEIcon::Desktop);

This will load the "kfind" icon, of depth and size specified for the Desktop group.

Unthemed icons

Unthemed icons are installed in $TDEDIR/share/apps/$APPNAME/pics. To install them, use this in your CMakeLists.txt:

install( FILES open.png kfind.png DESTINATION ${DATA_INSTALL_DIR}/myapp/pics )


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:

TQPixmap pm;
pm = loader->loadIcon("myicon", TDEIcon::User);

Conclusion

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>