desktop-file.page.in

<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      id="desktop-file">
<info>
  <credit type="author maintainer copyright">
    <name>Philip Chimento</name>
    <email>philip.chimento@gmail.com</email>
    <years>2008-2012</years>
  </credit>
  <license href="http://creativecommons.org/licenses/by-nc-sa/3.0/">
    <p>This work is licensed under a <link href="http://creativecommons.org/licenses/by-nc-sa/3.0/">Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License</link>.</p>
  </license>
  <link type="next" xref="gettext-project"/>
  <link type="guide" xref="real-life-app-setup" group="#default"/>
  <desc>Installing your program onto the user's desktop</desc>
</info>
<title>Icons and desktop files</title>

<synopsis>
<p>In this tutorial, you will learn:</p>
<list>
  <item><p>How to add an icon to your program</p></item>
  <item><p>How to add your program to the applications menu</p></item>
</list>
<p>This tutorial is part of the <em>Setting up a real-life GTK application</em> series.
If you don't want to follow along with the previous parts, simply copy the <link href="../app-skeleton2"><file>app-skeleton2</file></link> directory from the tutorial's code examples.
Or, you can start from the <link xref="real-life-app-setup">beginning</link>.</p>
</synopsis>

<p>Most users who can use a terminal are also familiar with the time-tested routine of <cmd>./configure</cmd>, <cmd>make</cmd> and <cmd>make install</cmd>.
However, as the Linux desktop gains more and more ground, package managers are on the rise.
Users expect to be able to install a package and then find a new entry in their Applications menu.
The <file>Makefile.am</file> may install our executable file into <file>/usr/local/bin</file>, but nowadays we can't expect users to open a terminal every time they want to run it.
We can put an entry into the menu by means of a <em>desktop file</em>.</p>

<section id="adding-icon">
<title>Adding an icon to the program</title>

<p>Copy the <file>app-skeleton2</file> project to <file>app-skeleton3</file>, or just rename it.
(Change the version number in the <code>AC_INIT</code> call in <file>configure.ac</file> to 3 as well, if you like.)
First we will appropriate an icon from the GNOME icon theme for our program.
Again, we will do this the lazy way, by downloading all available sizes directly from the GNOME git repository.
In the <file>app-skeleton3</file> directory, type:</p>

<screen>
<input>for size in 16 22 24 32 48; do
mkdir -p pixmaps/${size}x${size}/apps
wget -O pixmaps/${size}x${size}/apps/app-skeleton.png \
  http://git.gnome.org/browse/gnome-icon-theme/plain/gnome/${size}x${size}/status/weather-showers-scattered.png
done</input>
</screen>

<p>This is the icon we have just downloaded, in five different sizes: 
<media type="image" src="app-skeleton3/pixmaps/48x48/apps/app-skeleton.png">[An icon of a raincloud from the GNOME icon theme]</media></p>

<p>There is a reason why we are creating this particular directory structure.
It is explained in the Free Desktop <link href="http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html">Icon Theme Specification</link> and <link href="http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">Icon Naming Specification</link>.</p>

<p>The new <file>pixmaps</file> directory needs a <file>Makefile.am</file> too.
Create one there and put in it:</p>

<!--{{{app-skeleton3/pixmaps/Makefile.am:1-21%automake}}}-->

<p>The Automake variable <code>nobase_dist_icons_DATA</code> has four parts.
The prefix <code>nobase</code> means to install the files with the same directory structure into the destination directory.
Another prefix, <code>dist</code> means to include the files in the tarball produced when you type <cmd>make dist</cmd>.
(By default, data files are not included.)</p>

<p>The third segment, <code>icons</code>, functions like <code>bin</code> did in <code>bin_PROGRAMS</code>: it tells where to install the files.
The difference is that <code>bin</code> is predefined and <code>icons</code> is not.
Automake will install the files in the location stored in the variable <code>iconsdir</code>, which we define above.
Why it is called <file>hicolor</file>, you can read in the <link href="http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html">Icon Theme Specification</link>.</p>

<p>Finally, the <code>DATA</code> directive tells Automake that these are data files; they do not need to be compiled.</p>

<p>The rest of the file calls the <cmd>gtk-update-icon-cache</cmd> utility whenever the program is installed or uninstalled.
This is necessary so that the new icons can be found in the icon theme.
The test may look a little confusing at first; testing whether the <code>DESTDIR</code> is empty means testing whether we are really installing the program into the file system, or doing a <em>staged install</em>.
In the latter case, the icon files are not really being installed into the icon theme directory, so it makes no sense to update the icon cache.
In that case, the makefile prints a message to remind the user to update the icon cache when the program is really installed.</p>

<p>As a last bit of icing on the cake, let us use the icon as our program's icon (in the corner of the title bar in some desktop themes, or in the application switcher.)
Since we have already installed the icon into the icon theme, having the program use it is quite simple.
Add the following line to the <code>main()</code> function of <file>hello-world.c</file>, for example as line 47:</p>

<!--{{{app-skeleton3/src/hello-world.c:47}}}-->

<p>When an icon is present in the icon theme, it can be used like this as a <em>named icon</em>.
(Remember that you have to run <cmd>make install</cmd> before it will work, though.)</p>

</section>
<section id="desktop-file">
<title>The desktop file</title>

<p>Now to create our desktop file.
Create a file <file>app-skeleton.desktop</file> in the <file>app-skeleton3</file> directory and write in it:</p>

<!--{{{app-skeleton3/app-skeleton.desktop:1-9%desktop}}}-->

<p>In short, <code>Name</code> is the program name that will appear in the menu, <code>Icon</code> is the named icon to use for the program in the menu, and <code>Comment</code> is the tooltip to use when the user hovers their mouse over the program name.
The <code>Terminal=false</code> line tells the desktop environment not to start the program in a terminal.
The <code>Categories</code> field is a hint to the desktop environment about what category it should put the program launcher into.
(Some desktops, like Gnome Shell, don't use categories.)</p>

<p>A full list of fields and categories for use in this file, along with explanations of what they are for, can be found in two other Free Desktop specifications, the <link href="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop Entry Specification</link> and the <link href="http://standards.freedesktop.org/menu-spec/latest/">Desktop Menu Specification</link>.</p>

<p>Finally, we need to update our top-level <file>Makefile.am</file>:</p>

<!--{{{app-skeleton3/Makefile.am:1-4%automake}}}-->

<p>We add the <file>pixmaps</file> subdirectory to our <code>SUBDIRS</code> variable, and instruct Automake to install the desktop file in the proper place so the desktop environment can find it.</p>

<p>Lastly, we add <code>pixmaps/Makefile</code> to the <code>AC_CONFIG_FILES</code> call in <file>configure.ac</file>.
With that, we are ready to go.
Try <cmd>make</cmd> followed by <cmd>make install</cmd>.
A new entry should show up in your desktop's applications chooser!</p>

<p>But what if the user speaks another language?
They will not be able to understand the name of the program and the description we have put in the desktop file.
Solving this problem is what the next section is about.</p>

</section>

</page>