Difference between revisions of "Development/Tutorials/Icons"

Jump to: navigation, search
m (found a better way)
 
(48 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{stub}}
+
__TOC__
  
 
When you create your own KDE application you will probably want icons in it like this:
 
When you create your own KDE application you will probably want icons in it like this:
Line 5: Line 5:
 
[[File:Snapshot-krep-arrow.png]]
 
[[File:Snapshot-krep-arrow.png]]
  
This article shows you how to do this on the example of the software [http://www.staerk.de/thorsten/krep krep]. In case of a [[cmake]] based project you will need to   
+
These icons are called [http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKIcon.html KIcon]s. This article shows you how to do this using the software [http://www.staerk.de/thorsten/krep krep] as an example. In case of a [[Development/Tutorials/CMake|
 +
CMake]]-based project you will need to   
 
* [http://websvn.kde.org/trunk/playground/utils/krep/main.cpp?r1=1154359&r2=1249871 modify main.cpp (as it is typically called)]
 
* [http://websvn.kde.org/trunk/playground/utils/krep/main.cpp?r1=1154359&r2=1249871 modify main.cpp (as it is typically called)]
 
* [http://websvn.kde.org/trunk/playground/utils/krep/CMakeLists.txt?r1=813330&r2=1249871&sortby=date modify CMakeLists.txt]
 
* [http://websvn.kde.org/trunk/playground/utils/krep/CMakeLists.txt?r1=813330&r2=1249871&sortby=date modify CMakeLists.txt]
  
When trying to add an icon to your program, you will realize there is a lot of wording against common sense. You will see the classes, KIconLoader, KIconEngine, QIconEngine, QIcon and KIcon that all seem to mean the same thing, an icon.
+
How to use icons in QMake-based projects is discussed [http://appdeveloper.intel.com/en-us/Qt%20C%20Plus%20Plus%20app%20MeeGo%20SDK elsewhere].
 +
 
 +
= Your KDE project =
 +
If you have a KDE project and want to use icons within it, and want these icons installed seamlessly, you will have to name the icons after the project. In the following we look at a project named ''krep''. The important lines in CMakeLists.txt are the ones printed bold below:
 +
<syntaxhighlight lang="cmake">
 +
PROJECT( krep )
 +
FIND_PACKAGE( KDE4 REQUIRED )
 +
INCLUDE_DIRECTORIES( ${KDE4_INCLUDES} . )
 +
 +
SET( krepSources main.cpp krep.cpp krep.h )
 +
 +
qt4_add_dbus_adaptor( krepSources
 +
                      org.kde.krep.xml
 +
                      krep.h
 +
                      krep
 +
                      mainadaptor
 +
                      MainAdaptor )
 +
 +
kde4_add_ui_files( krepSources krepui.ui )
 +
 +
kde4_add_app_icon( krepSources "hi*-app-krep.png" )
 +
 +
KDE4_ADD_EXECUTABLE( krep ${krepSources} )
 +
 +
TARGET_LINK_LIBRARIES( krep ${KDE4_KPARTS_LIBS} )
 +
 +
install( TARGETS krep ${INSTALL_TARGETS_DEFAULT_ARGS} )
 +
 +
kde4_install_icons( ${ICON_INSTALL_DIR} )
 +
</syntaxhighlight>
 +
Weitere Informationen:
 +
* [[Development/CMake/Addons_for_KDE#Macros|kde4_add_app_icon]]
 +
* [[Development/CMake/Addons_for_KDE#The_locations_of_install_directories|ICON_INSTALL_DIR]]
 +
 
 +
= How to test it =
 +
The easy way is to define a custom cmake install prefix where you can simply insall the project without touching your system.  
 +
Use following commands to setup this:
 +
 
 +
<syntaxhighlight lang="bash">
 +
cd build
 +
cmake -DCMAKE_INSTALL_PREFIX=$HOME/playground ../
 +
make && make install
 +
</syntaxhighlight>
 +
 
 +
now the files should be deployed under
 +
<syntaxhighlight lang="bash">
 +
$HOME/playground/bin/krep
 +
$HOME/playground/share/apps/krep
 +
$HOME/playground/share/icons/hicolor/22x22/apps/krep.png
 +
</syntaxhighlight>
 +
 
 +
With this method you can easy see what you will get.
 +
 
 +
{{Note| You can still not see the icon in your application because $HOME/playground is not a know path by kde.
 +
Normaly kde support a user defined space under $HOME/.kde.
 +
 
 +
Find out if this is supported with the command
 +
<syntaxhighlight lang="bash">
 +
kde4-config -path icon
 +
</syntaxhighlight>
 +
 
 +
finally you have to extend the search path for kde
 +
<syntaxhighlight lang="bash">
 +
export KDEDIRS=$KDEDIRS:$HOME/playground
 +
</syntaxhighlight>
 +
}}
 +
 
 +
= The icon naming scheme =
 +
Example for icon names:
 +
* hisc-apps-bla.svgz will be installed e.g. to /usr/local/share/icons/hicolor/scalable/apps/bla.svgz. <tt>hi</tt> stands for "hicolor", <tt>sc</tt> for "scalable", <tt>apps</tt> for "applications", <tt>bla</tt> for the application's name and <tt>.svgz</tt> is the suffix for gzipped scalable vector graphic files.
 +
* hi128-apps-ktimetracker.png will be installed e.g. to /usr/share/icons/hicolor/128x128/apps/ktimetracker.png. <tt>hi</tt> stands for "hicolor", <tt>128</tt> for a resolution of 128x128 pixels, <tt>apps</tt> for "applications", <tt>ktimetracker</tt> for the application's name and <tt>.png</tt> is the suffix for portable network graphic files.
 +
 
 +
= example application =
 +
In this chapter we will build - on top of the [[Development/Tutorials/Using_KActions|KAction example]] - an example application ''kicons'' that looks like this:
 +
 
 +
[[File:Snapshot-tutorial-kicon.png]]
 +
 
 +
You can obtain its source code as part of kdeexamples by calling
 +
git clone git://anongit.kde.org/kdeexamples
 +
 
 +
== files ==
 +
The example application consists of
 +
* [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/main.cpp main.cpp]
 +
: just taken from the [[Development/Tutorials/Using_KActions|KAction example]]
 +
* [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/mainwindow.cpp mainwindow.cpp]
 +
: Note the command <syntaxhighlight lang="bash">clearAction->setIcon(KIcon("tutorial-kicon"));</syntaxhighlight> that sets the icon
 +
* [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/mainwindow.h mainwindow.h]
 +
: just taken from the [[Development/Tutorials/Using_KActions|KAction example]]
 +
* [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/world.svg world.svg]
 +
: This is a file that defines our icon in (almost natural) english language. It is a scalable vector graphic file. Before being used, it must be converted into a zipped scalable vector graphic named ''hisc-apps-tutorial-kicon.svgz'', see below.
 +
* [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/tutorial-kiconui.rc tutorial-kiconui.rc]
 +
: just taken from the [[Development/Tutorials/Using_KActions|KAction example]]
 +
* [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/hisc-apps-tutorial-kicon.svgz hisc-apps-tutorial-kicon.svgz]
 +
: sorry for the name, but there are [[#The_icon_naming_scheme|naming conventions]]. Create this file with the ''convert'' command from the ''ImageMagick'' package <syntaxhighlight lang="bash">convert world.svg hisc-apps-tutorial-kicon.svgz</syntaxhighlight>
 +
* [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/CMakeLists.txt CMakeLists.txt]
 +
: Note the commands <syntaxhighlight lang="bash">kde4_install_icons(${ICON_INSTALL_DIR})</syntaxhighlight> and <syntaxhighlight lang="bash">kde4_update_iconcache()</syntaxhighlight> which integrate the icons.
 +
 
 +
== build it ==
 +
To compile, link and install the example application, do a
 +
<syntaxhighlight lang="bash">
 +
mkdir build && cd build
 +
cmake ../ && make && make install
 +
</syntaxhighlight>
 +
To run it, call
 +
<syntaxhighlight lang="bash">
 +
tutorial-kicon
 +
</syntaxhighlight>
  
 
= Analyzing the KApplications =
 
= Analyzing the KApplications =
 
Maybe you have already searched for yourself how a KDE application finds its icons. You will not be successful like this:
 
Maybe you have already searched for yourself how a KDE application finds its icons. You will not be successful like this:
 +
<syntaxhighlight lang="bash">
 
  # [http://www.linuxintro.org/wiki/Strace#Search_for_a_syscall strace -e open] ktimetracker 2>&1 | grep icon
 
  # [http://www.linuxintro.org/wiki/Strace#Search_for_a_syscall strace -e open] ktimetracker 2>&1 | grep icon
 
  open("/usr/lib64/libkemoticons.so.4", O_RDONLY) = 3
 
  open("/usr/lib64/libkemoticons.so.4", O_RDONLY) = 3
 
  #
 
  #
 +
</syntaxhighlight>
 
You see, a KDE application (in this case ktimetracker) does not open icon files or even look for them. However, it spawns a process to look for these icons:
 
You see, a KDE application (in this case ktimetracker) does not open icon files or even look for them. However, it spawns a process to look for these icons:
 
+
<syntaxhighlight lang="bash">
 
  linux-qgla:~/repos/kdepim/ktimetracker # strace -ffe open ktimetracker 2>&1 | grep icon
 
  linux-qgla:~/repos/kdepim/ktimetracker # strace -ffe open ktimetracker 2>&1 | grep icon
 
  open("/usr/lib64/libkemoticons.so.4", O_RDONLY) = 3
 
  open("/usr/lib64/libkemoticons.so.4", O_RDONLY) = 3
Line 27: Line 136:
 
  [pid  3457] open("/var/tmp/kdecache-root/kpc/kde-icon-cache.index", O_RDONLY|O_CLOEXEC) = 10
 
  [pid  3457] open("/var/tmp/kdecache-root/kpc/kde-icon-cache.index", O_RDONLY|O_CLOEXEC) = 10
 
  [...]
 
  [...]
 +
</syntaxhighlight>
  
= Your KDE project =
+
= Moving On =
If you have a KDE project and want to use icons within it, and want that these icons install seamlessly, you will have to name the icons after the project. In the following we look at a project named ''krep''. The important lines in CMakeLists.txt are the ones printed bold below:
+
Now you can move on to [[Development/Tutorials/Desktop_File|how to place your application in the K-Menu using .desktop files]].
PROJECT( krep )
+
FIND_PACKAGE( KDE4 REQUIRED )
+
INCLUDE_DIRECTORIES( ${KDE4_INCLUDES} . )
+
+
SET(krepSources main.cpp krep.cpp krep.h)
+
+
qt4_add_dbus_adaptor( krepSources
+
                      org.kde.krep.xml
+
                      krep.h
+
                      krep
+
                      mainadaptor
+
                      MainAdaptor )
+
+
kde4_add_ui_files( krepSources krepui.ui )
+
+
'''kde4_add_app_icon( krepSources "hi*-app-krep.png" )'''
+
+
KDE4_ADD_EXECUTABLE( krep ${krepSources} )
+
+
TARGET_LINK_LIBRARIES( krep ${KDE4_KPARTS_LIBS} )
+
+
install( TARGETS krep ${INSTALL_TARGETS_DEFAULT_ARGS} )
+
+
'''kde4_install_icons( ${ICON_INSTALL_DIR} )'''
+
 
+
= How to test it =
+
* delete a file
+
rm /usr/local/share/icons/hicolor/22x22/apps/krep.png
+
* delete your cache
+
rm -rf /var/tmp/kdecache-''user''/
+
* relogin
+
  
using this test case I could remove one icon after the other, 22x22, 64x64, 48x48, but when I removed 32x32, the icon disappeared from my application. This was the last icon that existed. Then I put in the 64x64 icon and the application carried an icon again. This means you can use any icon of 16x16, 22x22, 32x32, 48x48, 64x64, 128x128.
+
[[Category:C++]]

Latest revision as of 18:54, 25 November 2012

Contents


When you create your own KDE application you will probably want icons in it like this:

Snapshot-krep-arrow.png

These icons are called KIcons. This article shows you how to do this using the software krep as an example. In case of a CMake-based project you will need to

How to use icons in QMake-based projects is discussed elsewhere.

[edit] Your KDE project

If you have a KDE project and want to use icons within it, and want these icons installed seamlessly, you will have to name the icons after the project. In the following we look at a project named krep. The important lines in CMakeLists.txt are the ones printed bold below:

PROJECT( krep )
FIND_PACKAGE( KDE4 REQUIRED )
INCLUDE_DIRECTORIES( ${KDE4_INCLUDES} . )
 
SET( krepSources main.cpp krep.cpp krep.h )
 
qt4_add_dbus_adaptor( krepSources 
                      org.kde.krep.xml
                      krep.h
                      krep
                      mainadaptor
                      MainAdaptor )
 
kde4_add_ui_files( krepSources krepui.ui )
 
kde4_add_app_icon( krepSources "hi*-app-krep.png" )
 
KDE4_ADD_EXECUTABLE( krep ${krepSources} )
 
TARGET_LINK_LIBRARIES( krep ${KDE4_KPARTS_LIBS} )
 
install( TARGETS krep ${INSTALL_TARGETS_DEFAULT_ARGS} )
 
kde4_install_icons( ${ICON_INSTALL_DIR} )

Weitere Informationen:

[edit] How to test it

The easy way is to define a custom cmake install prefix where you can simply insall the project without touching your system. Use following commands to setup this:

cd build
cmake -DCMAKE_INSTALL_PREFIX=$HOME/playground ../
make && make install

now the files should be deployed under

$HOME/playground/bin/krep
$HOME/playground/share/apps/krep
$HOME/playground/share/icons/hicolor/22x22/apps/krep.png

With this method you can easy see what you will get.

noframe
 
Note
You can still not see the icon in your application because $HOME/playground is not a know path by kde.

Normaly kde support a user defined space under $HOME/.kde.

Find out if this is supported with the command

kde4-config -path icon

finally you have to extend the search path for kde

export KDEDIRS=$KDEDIRS:$HOME/playground

[edit] The icon naming scheme

Example for icon names:

  • hisc-apps-bla.svgz will be installed e.g. to /usr/local/share/icons/hicolor/scalable/apps/bla.svgz. hi stands for "hicolor", sc for "scalable", apps for "applications", bla for the application's name and .svgz is the suffix for gzipped scalable vector graphic files.
  • hi128-apps-ktimetracker.png will be installed e.g. to /usr/share/icons/hicolor/128x128/apps/ktimetracker.png. hi stands for "hicolor", 128 for a resolution of 128x128 pixels, apps for "applications", ktimetracker for the application's name and .png is the suffix for portable network graphic files.

[edit] example application

In this chapter we will build - on top of the KAction example - an example application kicons that looks like this:

Snapshot-tutorial-kicon.png

You can obtain its source code as part of kdeexamples by calling

git clone git://anongit.kde.org/kdeexamples

[edit] files

The example application consists of

just taken from the KAction example
Note the command
clearAction->setIcon(KIcon("tutorial-kicon"));
that sets the icon
just taken from the KAction example
This is a file that defines our icon in (almost natural) english language. It is a scalable vector graphic file. Before being used, it must be converted into a zipped scalable vector graphic named hisc-apps-tutorial-kicon.svgz, see below.
just taken from the KAction example
sorry for the name, but there are naming conventions. Create this file with the convert command from the ImageMagick package
convert world.svg hisc-apps-tutorial-kicon.svgz
Note the commands
kde4_install_icons(${ICON_INSTALL_DIR})
and
kde4_update_iconcache()
which integrate the icons.

[edit] build it

To compile, link and install the example application, do a

mkdir build && cd build
cmake ../ && make && make install

To run it, call

tutorial-kicon

[edit] Analyzing the KApplications

Maybe you have already searched for yourself how a KDE application finds its icons. You will not be successful like this:

 # [http://www.linuxintro.org/wiki/Strace#Search_for_a_syscall strace -e open] ktimetracker 2>&1 | grep icon
 open("/usr/lib64/libkemoticons.so.4", O_RDONLY) = 3
 #

You see, a KDE application (in this case ktimetracker) does not open icon files or even look for them. However, it spawns a process to look for these icons:

 linux-qgla:~/repos/kdepim/ktimetracker # strace -ffe open ktimetracker 2>&1 | grep icon
 open("/usr/lib64/libkemoticons.so.4", O_RDONLY) = 3
 [pid  3457] open("/root/.icons/DMZ/cursors/left_ptr", O_RDONLY) = -1 ENOENT (No such file or directory)
 [pid  3457] open("/root/.icons/DMZ/index.theme", O_RDONLY) = -1 ENOENT (No such file or directory)
 [pid  3457] open("/usr/share/icons/DMZ/cursors/left_ptr", O_RDONLY) = 10
 [pid  3457] open("/var/tmp/kdecache-root/icon-cache.kcache", O_RDWR|O_CREAT|O_CLOEXEC, 0666) = 10
 [pid  3457] open("/var/tmp/kdecache-root/kpc/kde-icon-cache.data", O_RDONLY|O_CLOEXEC) = 10
 [pid  3457] open("/var/tmp/kdecache-root/kpc/kde-icon-cache.index", O_RDONLY|O_CLOEXEC) = 10
 [...]

[edit] Moving On

Now you can move on to how to place your application in the K-Menu using .desktop files.


This page was last modified on 25 November 2012, at 18:54. This page has been accessed 14,672 times. Content is available under Creative Commons License SA 3.0 as well as the GNU Free Documentation License 1.2.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal