Development/Tutorials/Icons: Difference between revisions

    From KDE TechBase
    m (improve markup)
    (20 intermediate revisions by 2 users not shown)
    Line 5: Line 5:
    [[File:Snapshot-krep-arrow.png]]
    [[File:Snapshot-krep-arrow.png]]


    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 on the example of the software [http://www.staerk.de/thorsten/krep krep]. In case of a [[Development/Tutorials/CMake|
    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   
    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]


    How to use icons in a qmake base project is discussed [http://appdeveloper.intel.com/en-us/Qt%20C%20Plus%20Plus%20app%20MeeGo%20SDK elsewhere].
    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 =
    = Your KDE project =
    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:
    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 )
    <syntaxhighlight lang="cmake">
    FIND_PACKAGE( KDE4 REQUIRED )
    PROJECT( krep )
    INCLUDE_DIRECTORIES( ${KDE4_INCLUDES} . )
    FIND_PACKAGE( KDE4 REQUIRED )
    INCLUDE_DIRECTORIES( ${KDE4_INCLUDES} . )
       
       
    SET(krepSources main.cpp krep.cpp krep.h)
    SET( krepSources main.cpp krep.cpp krep.h )
       
       
    qt4_add_dbus_adaptor( krepSources  
    qt4_add_dbus_adaptor( krepSources  
                          org.kde.krep.xml
                          org.kde.krep.xml
                          krep.h
                          krep.h
                          krep
                          krep
                          mainadaptor
                          mainadaptor
                          MainAdaptor )
                          MainAdaptor )
       
       
    kde4_add_ui_files( krepSources krepui.ui )
    kde4_add_ui_files( krepSources krepui.ui )
       
       
    '''[[Development/CMake/Addons_for_KDE#Macros|kde4_add_app_icon]]( krepSources "hi*-app-krep.png" )'''
    kde4_add_app_icon]]( krepSources "hi*-app-krep.png" )
       
       
    KDE4_ADD_EXECUTABLE( krep ${krepSources} )
    KDE4_ADD_EXECUTABLE( krep ${krepSources} )
       
       
    TARGET_LINK_LIBRARIES( krep ${KDE4_KPARTS_LIBS} )
    TARGET_LINK_LIBRARIES( krep ${KDE4_KPARTS_LIBS} )
       
       
    install( TARGETS krep ${INSTALL_TARGETS_DEFAULT_ARGS} )
    install( TARGETS krep ${INSTALL_TARGETS_DEFAULT_ARGS} )
       
       
    '''kde4_install_icons( ${[[Development/CMake/Addons_for_KDE#The_locations_of_install_directories|ICON_INSTALL_DIR]]} )'''
    '''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 =
    = How to test it =
    * delete a file
    * delete a file
      rm /usr/local/share/icons/hicolor/22x22/apps/krep.png  
    <syntaxhighlight lang="bash">
      rm /usr/local/share/icons/hicolor/22x22/apps/krep.png
    </syntaxhighlight>
    {{Note| We are assuming your icon path is /usr/local/share/icons.
    Find it out with the command
    <syntaxhighlight lang="bash">
    kde4-config --path icon
    </syntaxhighlight>
    }}
    * delete your cache
    * delete your cache
    rm -rf /var/tmp/kdecache-''user''/
    <syntaxhighlight lang="bash">
    * relogin
    rm -rf /var/tmp/kdecache-''user''/icon-cache.kcache
    </syntaxhighlight>


    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.
    According to [[Development/CMake/Addons_for_KDE#Macros]] you need to provide a 128x128 pixels icon.


    = The icon naming scheme =
    = The icon naming scheme =
    Example for icon names:
    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.
    * 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-app-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, app for "applications", ktimetracker for the application's name and .png is the suffix for portable network graphic files.
    * hi128-app-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>app</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 =
    = example application =
    You can obtain an example application ''kicons'' as part of kdeexamples by calling
    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
      git clone git://anongit.kde.org/kdeexamples


    == create world.svg ==
    == files ==
    <pre>
    The example application consists of
    # cd
    * [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/main.cpp main.cpp]
    # cd kdeexamples/kicons
    : just taken from the [[Development/Tutorials/Using_KActions|KAction example]]
    # cat >world.svg<<EOF
    * [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/mainwindow.cpp mainwindow.cpp]
    <?xml version="1.0"?>
    : Note the command <syntaxhighlight lang="bash">clearAction->setIcon(KIcon("tutorial-kicon"));</syntaxhighlight> that sets the icon
    <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
    * [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/mainwindow.h mainwindow.h]
        "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
    : just taken from the [[Development/Tutorials/Using_KActions|KAction example]]
    <svg xmlns="http://www.w3.org/2000/svg" version="1.1"
    * [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/world.svg world.svg]
        width="300" height="300">
    : 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.
      <circle r="100" cx="150" cy="150" fill="blue" stroke-width="2px" stroke="black"/>
    * [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/tutorial-kiconui.rc tutorial-kiconui.rc]
    </svg>
    : just taken from the [[Development/Tutorials/Using_KActions|KAction example]]
    EOF
    * [http://quickgit.kde.org/?p=kdeexamples.git&a=blob&f=kicons/hisc-apps-tutorial-kicon.svgz hisc-apps-tutorial-kicon.svgz]
    </pre>
    : 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.


    == create hisc-apps-tutorial-kicon.svgz ==
    == build it ==
    Sorry for the name, but the naming scheme requires this.
    To compile, link and install the example application, do a
    # cd
    <syntaxhighlight lang="bash">
    # cd kdeexamples/kicons
    cmake . && make && make install
    # convert world.svg hisc-apps-tutorial-kicon.svgz
    </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 94: Line 120:
      [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>
    = Moving On =
    Now you can move on to [[Development/Tutorials/Desktop_File|how to place your application in the K-Menu using .desktop files]].


    = See also =
    [[Category:C++]]
    * [[Development/Tutorials]]

    Revision as of 20:23, 28 September 2011

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

    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.

    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:

    How to test it

    • delete a file
     rm /usr/local/share/icons/hicolor/22x22/apps/krep.png
    
    Note
    We are assuming your icon path is /usr/local/share/icons.

    Find it out with the command

    kde4-config --path icon
    
    • delete your cache
    rm -rf /var/tmp/kdecache-''user''/icon-cache.kcache
    

    According to Development/CMake/Addons_for_KDE#Macros you need to provide a 128x128 pixels icon.

    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-app-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, app for "applications", ktimetracker for the application's name and .png is the suffix for portable network graphic files.

    example application

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

    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

    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.

    build it

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

    cmake . && make && make install
    

    To run it, call

    tutorial-kicon
    

    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
     [...]
    

    Moving On

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