Blu256: Blu256 moved page Icon Loading (KDE3 Architecture) to Icon Loading: Simplify

2022-04-21T15:49:02Z

Blu256 moved page Icon Loading (KDE3 Architecture) to Icon Loading: Simplify

Blu256: /* loadIcon() continued */ KIcon->TDEIcon

2022-04-21T15:44:27Z

loadIcon() continued: KIcon->TDEIcon

Blu256: -Applicable to TDE (redundant), categories to bottom

2022-04-21T15:44:03Z

-Applicable to TDE (redundant), categories to bottom

Show changes

Blu256: Added table of contents

2021-12-21T19:24:49Z

Added table of contents

Blu256: Fixed own mistake

2021-08-23T18:50:17Z

Fixed own mistake

Blu256: Updated (API doc links, classes, CMake)

2021-08-22T21:16:43Z

Updated (API doc links, classes, CMake)

Show changes

imported>Eliddell at 20:51, 27 May 2014

2014-05-27T20:51:54Z

imported>Eliddell: Created page with " 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 ..."

2014-05-27T20:43:36Z

Created page with "  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 ..."

New page

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 [http://api.kde.org/3.5-api/kdelibs-apidocs/kdecore/html/classKIconLoader.html KIconLoader]. Every KDE
appliation has a global iconloader object. You can access this object with:


<syntaxhighlight lang="cpp-qt">
#include <kglobal.h>
#include <kiconloader.h>

KIconLoader *loader = KGlobal::iconLoader();
</syntaxhighlight>

=== Loading icons with loadIcon === 


The iconloader loads icons, transparently '''caches''' them and applies effects.
To load an icon, use the method [http://api.kde.org/3.5-api/kdelibs-apidocs/kdecore/html/classKIconLoader.html#a3 loadIcon()], which is defined like this:


<syntaxhighlight lang="cpp-qt">
QPixmap loadIcon( QString name, int group, int size=0,
int state=KIcon::DefaultState,
QString *path_store=0L, bool canReturnNull=false);
</syntaxhighlight>


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


# '''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.

=== Icon groups === 


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
[http://api.kde.org/3.5-api/kdelibs-apidocs/kdecore/html/classKIcon.html KIcon]
class, so prefix them with ''KIcon::''.


* '''Desktop''' - Icons for use on the desktop, in the filemanager and similar places.
* '''Toolbar''' - Icon for in normal toolbars.
* '''MainToolbar''' - Icons for in the main toolbar. An application can have multiple toolbars, of which one is allways 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.
* '''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:


<syntaxhighlight lang="cpp-qt">
QPixmap icon;
icon = loader->loadIcon("kfind", KIcon::Desktop);
</syntaxhighlight>

=== loadIcon continued === 


Now lets discuss the other parameters of ''loadIcon''.


# '''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 ''KIcon::DefaultState'', ''KIcon::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.
# '''path_store''' - If you want to know where the icon you just loaded is in the filesystem, you can pass a pointer to a QString here and the icon path is stored there.
# '''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 [http://www.kde-artists.org/introduction.html 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.

=== Icon context === 


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:


* '''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 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.

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

=== Installing themed 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 <tt>Makefile.am</tt>.


KDE_ICON = open kfind


and to install them in an application specific directory, use this:


icondir = $(kde_datadir)/myapp/icons
icon_ICON = open kfind

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


<syntaxhighlight lang="cpp-qt">
QPixmap pm;
pm = loader->loadIcon("kfind", KIcon::Desktop);
</syntaxhighlight>


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

=== Unthemed icons === 


Unthemed icons are installed in $KDEDIR/share/apps/$APPNAME/pics.
To install them, use this in you <tt>Makefile.am</tt>.


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:


<syntaxhighlight lang="cpp-qt">
QPixmap pm;
pm = loader->loadIcon("myicon", KIcon::User);
</syntaxhighlight>

== 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 [mailto:jansen@kde.org <jansen@kde.org>]


[[Category:KDE3]]
[[Category:Architecture]]

@@ Line 72: / Line 72: @@
 # '''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 ''TDEIcon::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.
 # '''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.
 # '''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.

@@ Line 220: / Line 220: @@
 <!--T:43-->
+Then use the following macro in your CMakeLists.txt file:
-The icons are installed automatically when using the TDE CMake macros.
+<syntaxhighlight lang="cmake">
+tde_install_icons( )
+</syntaxhighlight>
 <!--

← Older revision	Revision as of 15:49, 21 April 2022
(No difference)

@@ Line 9: / Line 9: @@
 come in different sizes and display depths. In order to make this manageable,
 a standard way of storing and accessing icons has been developed.
+__TOC__
 == Loading icons == <!--T:3-->

@@ Line 115: / Line 115: @@
 <!--T:28-->
-Please refer to the [http://www.kde-artists.org/introduction.html KDE icon factory]
+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.
 Remember that each of these sizes can be bound to an icon group.

Icon Loading - Revision history