<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<book id="index" lang="en_GB">
  <bookinfo>
    <title>Integrating existing software with GNOME</title>
    <subtitle>Guide for Independent Software Vendors</subtitle>
    <abstract role="description"><para>Guide for Independent Software Vendors</para></abstract>

    <authorgroup>
      <author>
	<firstname>Rosanna</firstname>
	<surname>Yuen</surname>
	<affiliation>
	  <address>
	    <email>zana@gnome.org</email>
	  </address>
	</affiliation>
      </author>
      <author role="maintainer">
	<firstname>Federico</firstname>
	<surname>Mena-Quintero</surname>
	<affiliation>
	  <address>
	    <email>federico@gnu.org</email>
	  </address>
	</affiliation>
      </author>
      <author>
	<firstname>Mike</firstname>
	<surname>Hearn</surname>
	<affiliation>
	  <address>
	    <email>mike@navi.cx</email>
	  </address>
	</affiliation>
      </author>
    </authorgroup>

    <copyright>
      <year>2005, 2006</year>
      <holder>Rosanna Yuen, Federico Mena-Quintero, Mike Hearn</holder>
    </copyright><copyright><year>2009</year><holder>Jen Ockwell (jenfraggleubuntu@gmail.com)</holder></copyright>

    <revhistory>
      <revision>
	<revnumber>0.6</revnumber>
	<date>19th September 2006</date>
	<revdescription>
	  <para>Extended the icon guidelines.</para>
	</revdescription>
      </revision>
 <revision>
	<revnumber>0.5</revnumber>
	<date>18th September 2006</date>
	<revdescription>
	  <para>Integrated the content of Rosanna Yuen's first article on freedesktop.org standards.</para>
	</revdescription>
      </revision>
      <revision>
	<revnumber>0.0</revnumber>
	<date>June 2005</date>
	<revdescription>
	  <para>Initial version of this document.</para>
	</revdescription>
      </revision>
    </revhistory>
<!-- Added with permission of federico -->
<legalnotice id="legalnotice">
  <para>Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation Licence (GFDL), Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. You can find a copy of the GFDL at this <ulink url="ghelp:fdl">link</ulink> or in the file COPYING-DOCS distributed with this manual.</para>
  <para>This manual is part of a collection of GNOME manuals distributed under the GFDL. If you want to distribute this manual separately from the collection, you can do so by adding a copy of the licence to the manual, as described in section 6 of the licence.</para>
  <para>Many of the names used by companies to distinguish their products and services are claimed as trademarks. Where those names appear in any GNOME documentation, and the members of the GNOME Documentation Project are made aware of those trademarks, then the names are in capital letters or initial capital letters.</para>
  <para>DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT ARE PROVIDED UNDER THE TERMS OF THE GNU FREE DOCUMENTATION LICENCE WITH THE FURTHER UNDERSTANDING THAT: <orderedlist>
      <listitem>
	<para>DOCUMENT IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, WARRANTIES THAT THE DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT IS FREE OF DEFECTS MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE OR NON-INFRINGING. THE ENTIRE RISK AS TO THE QUALITY, ACCURACY, AND PERFORMANCE OF THE DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT IS WITH YOU. SHOULD ANY DOCUMENT OR MODIFIED VERSION PROVE DEFECTIVE IN ANY RESPECT, YOU (NOT THE INITIAL WRITER, AUTHOR OR ANY CONTRIBUTOR) ASSUME THE COST OF ANY NECESSARY SERVICING, REPAIR OR CORRECTION. THIS DISCLAIMER OF WARRANTY CONSTITUTES AN ESSENTIAL PART OF THIS LICENCE. NO USE OF ANY DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT IS AUTHORIZED HEREUNDER EXCEPT UNDER THIS DISCLAIMER; AND</para>
      </listitem>
      <listitem>
	<para>UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL THEORY, WHETHER IN TORT (INCLUDING NEGLIGENCE), CONTRACT, OR OTHERWISE, SHALL THE AUTHOR, INITIAL WRITER, ANY CONTRIBUTOR, OR ANY DISTRIBUTOR OF THE DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT, OR ANY SUPPLIER OF ANY OF SUCH PARTIES, BE LIABLE TO ANY PERSON FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR MALFUNCTION, OR ANY AND ALL OTHER DAMAGES OR LOSSES ARISING OUT OF OR RELATING TO USE OF THE DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT, EVEN IF SUCH PARTY SHALL HAVE BEEN INFORMED OF THE POSSIBILITY OF SUCH DAMAGES.</para>
      </listitem>
    </orderedlist></para>
</legalnotice>
  </bookinfo>

  <preface id="preface">
    <title>Preface</title>

    <para>GNOME is a project to build a complete desktop and development platform based entirely on free software. Many companies, governments, schools, institutions, and individuals have deployed the GNOME desktop on their systems. If you are a developer of third-party software ("Independent Software Vendor" or <acronym>ISV</acronym>, or "Independent Software Developer" (<acronym>ISD</acronym>) if you don't do it commercially), you may want to ensure that your existing software runs properly under GNOME. This guide explains how to integrate existing software with GNOME, without actually rewriting that software to explicitly use the GNOME platform libraries and development tools.</para>

    <para>This guide will be useful in the following situations:</para>

    <itemizedlist>
      <listitem>
	<para>You are a software developer or distributor who has an application that is not explicitly designed to work with GNOME, but you want to ensure that it runs comfortably within a GNOME desktop.</para>
      </listitem>

      <listitem>
	<para>You are a system administrator for an institution that has deployed GNOME desktops to its users. You also have legacy or in-house applications, and you want your users of GNOME to be able to access those applications comfortably.</para>
      </listitem>

      <listitem>
	<para>You are writing a GNOME application proper and you need a checklist of basic things to do to ensure that your application integrates well with the rest of the GNOME desktop.</para>
      </listitem>
    </itemizedlist>

    <para>In general, this guide is about integrating existing software into a GNOME desktop. On the other hand, if you are considering writing new software, we encourage you to develop it completely with GNOME as your target platform; please refer to the <ulink url="http://developer.gnome.org">GNOME Developer's Site</ulink> for more information.</para>

    <para>One of the main concerns of GNOME is the user experience. Users should have a comfortable computing environment: this means having a complete desktop and a set of applications which operate together in a consistent way. With relatively little work, applications which are not written explicitly with GNOME in mind can be made to run comfortably within a GNOME desktop.</para>

    <section id="structure">
      <title>Structure of this guide</title>

      <para>This guide is structured as a list of tasks that you need to perform to integrate existing software with GNOME. The guide presents these tasks roughly in order of importance. For example, the task of adding your application to the GNOME desktop's menus appears before the task for adding drag-and-drop support. Also, this guide has an <link linkend="apx-integration-checklist">appendix with an integration checklist</link> to aid you in evaluating your integration work.</para>
    </section>

    <section id="standards">
      <title>Standards and freedesktop.org</title>

      <para>Many of the integration tasks in this guide rely on standards which are relevant to more than GNOME. Other desktop projects like the <ulink url="http://www.kde.org">K Desktop Environment</ulink> also use these standards: if you integrate your applications with GNOME, you should have to do little or no extra work to make them run in those other environments as well.</para>

      <para>Creating a perfect application is a wonderful feeling. Whether large or small, you want the desktop to recognise your application and for them to interact appropriately. With multiple desktops currently available, it is best for your application to be able to integrate itself in as many of them as possible. Even though no official rules have been adopted, there is a set of specifications available at <emphasis>freedesktop.org</emphasis>.</para>

      <para>Although not a formal standards body, freedesktop.org maintains a set of informal but commonly agreed upon guidelines. When followed, these guidelines allow applications to be integrated on to compliant desktops.</para>
    </section>
  </preface>

  <chapter id="basic-integration">
    <title>Basic Integration</title>

    <para>This chapter teaches you about the very basic steps you should take to integrate a program into the GNOME desktop. These steps concern the following:</para>

    <itemizedlist>
      <listitem>
	<para>Letting the user launch your application by making it appear in the desktop's panel menus, or any other launching mechanism in the desktop.</para>
      </listitem>
      <listitem>
	<para>Letting the desktop know which types of user-created files require your application to be launched.</para>
      </listitem>
      <listitem>
	<para>Letting the desktop know how to display the appropriate icons for your program and the files which your program creates.</para>
      </listitem>
    </itemizedlist>

    <section id="desktop-files">
      <title>Desktop files: putting your application in the desktop menus</title>

      <para>To run applications from GNOME, users click on icons on their desktops or they select the applications which they want to run from a menu. Therefore, the first step in integrating an existing program with GNOME is to <firstterm>register</firstterm> it with the set of applications that users can run.</para>

      <para>Unlike in Windows or Mac OS, in GNOME the user's menus are automatically constructed from the list of registered applications. Each published application specifies a set of categories to which it belongs, and the systems menu configuration sorts and arranges them. This mechanism follows the freedesktop.org desktop entry and menu standards.</para>

      <note><para>Though common in other desktops, creating your own application-specific submenu is not recommended. Instead, provide one menu item for each application you ship. Extra items such as help files, READMEs or links to your web site should be embedded into the application itself.</para></note>

      <para>In GNOME and other freedesktop.org-compliant desktops, an application gets registered into the desktop's menus through a <firstterm>desktop entry</firstterm>, which is a text file with the <filename>.desktop</filename> extension. This desktop file contains a listing of the configurations for your application. The desktop takes the information in this file and uses it to:</para>

      <itemizedlist>
	<listitem>
	  <para>
	    put the application in the <guimenu>Main Menu</guimenu>. To find a list of
            valid categories, take a look into FreeDesktop.org's
	    <ulink url="http://standards.freedesktop.org/menu-spec/latest/">Desktop
	    Menu Specification</ulink>.
	  </para>
	</listitem>
	<listitem>
	  <para>list the application in the <application>Run Application</application> dialogue</para>
	</listitem>
	<listitem>
	  <para>create appropriate launchers in the menu or on the desktop.</para>
	</listitem>
	<listitem>
	  <para>associate the name and description of the application.</para>
	</listitem>
	<listitem>
	  <para>use the appropriate icon.</para>
	</listitem>
	<listitem>
	  <para>recognise the MIME types it supports for opening files.</para>
	</listitem>
      </itemizedlist>

      <para>To add a menu entry for your application, create a desktop file. It should have a unique filename, and there are no length limits so avoid abbreviations and feel free to include brand names. However, don't put spaces or international characters in the file name. For instance, "foocorp-painter-pro.desktop" would be a good filename to choose but "fcpp.desktop" would be a bad name, as would "FooCorp Painter Pro.desktop". The file should be UTF-8 encoded, and should resemble the following template:</para>

      <programlisting><![CDATA[
	[Desktop Entry]
	Name=FooCorp Painter Pro
	Exec=foocorp-painter-pro
	Icon=foocorp-painter-pro
	Type=Application
	Categories=GTK;GNOME;Utility;
	]]></programlisting>

      <para>These desktop files contain metadata about your application, and play a central role in integrating the program with the GNOME and other standards compliant desktops. The template presented here is the most basic possible. The file can be linguistically translated so your applications name can appear in the user's native language.</para>

      <para>Place this file in the <filename class="directory">/usr/share/applications</filename> directory so that it is accessible by everyone, or in <filename class="directory">~/.local/share/applications</filename> if you only wish to make it accessible to a single user. Which is used should depend on whether your application is installed systemwide or into a user's home directory. GNOME monitors these directories for changes, so simply copying the file to the right location is enough to register it with the desktop. <footnote>
	  <para>Note that the <filename class="directory">~/.local/share/applications</filename> location is not monitored by versions of GNOME prior to version 2.10 or on Fedora Core Linux, prior to version 2.8. These versions of GNOME follow the now-deprecated vfolder standard, and so desktop files must be installed to <filename class="directory">~/.gnome2/vfolders/applications</filename>. This location is not supported by GNOME 2.8 on Fedora Core nor on upstream GNOME 2.10 so for maximum compatibility with deployed desktops, put the file in both locations.</para>

	  <para>Note that the KDE Desktop requires one to run <command>kbuildsycoca</command> to force a refresh of the menus.</para>

	
	</footnote></para>

      <para>Each working desktop file needs to follow the same format. A minimal example of a desktop file is shown in <xref linkend="ex-sample-desktop-file"/>. The file is split into sections, each starting with the section descriptor in square brackets. In this example, only one section is shown as that is the essential section to integrating your application to the desktop. Within each section, the part of each line before the equal sign is the <firstterm>key</firstterm> while the second half is the <firstterm>value</firstterm>. An explanation of each line is shown in <xref linkend="tb-desktop-file"/>.</para>

      <note>
	<para>Other than the first line identifying the desktop file, the order of the lines is not important. In <xref linkend="ex-sample-desktop-file"/>, the line <command>Type=Application</command> could be the second row, the fifth row, or the last row and the result would be the same.</para>

	<para>However, the keys are case-sensitive. <command>Type=Application</command> is not the same as <command>type=Application</command> or <command>TYPE=Application</command>.</para>
      </note>

      <example id="ex-sample-desktop-file">
	<title>Sample desktop file</title>
<screen>
[Desktop Entry]
Type=Application
Encoding=UTF-8
Name=Sample Application Name
Comment=A sample application
Exec=application
Icon=application.png
Terminal=false
</screen>
      </example>

      <table id="tb-desktop-file">
	<title>Line-by-line explanation</title>
	<tgroup cols="2">
	  <colspec colnum="1" colname="line" colwidth="1"/>
	  <colspec colnum="2" colname="desc" colwidth="1"/>

	  <thead>
	    <row>
	      <entry>Line</entry>
	      <entry>Description</entry>
	    </row>
	  </thead>

	  <tbody>
	    <row>
	      <entry><command>[Desktop Entry]</command></entry>
	      <entry>The first line of every desktop file and the section header to identify the block of key value pairs associated with the desktop. Necessary for the desktop to recognise the file correctly.</entry>
	    </row>
	    <row>
	      <entry><command>Type=Application</command></entry>
	      <entry>Tells the desktop that this desktop file pertains to an application. Other valid values for this key are <command>Link</command> and <command>Directory</command>.</entry>
	    </row>
	    <row>
	      <entry><command>Encoding=UTF-8</command></entry>
	      <entry>Describes the encoding of the entries in this desktop file.</entry>
	    </row>
	    <row>
	      <entry><command>Name=Sample Application Name</command></entry>
	      <entry>Names of your application for the main menu and any launchers.</entry>
	    </row>
	    <row>
	      <entry><command>Comment=A sample application</command></entry>
	      <entry>Describes the application. Used as a tooltip.</entry>
	    </row>
	    <row>
	      <entry><command>Exec=application</command></entry>
	      <entry>The command that starts this application from a shell. It can have arguments.</entry>
	    </row>
	    <row>
	      <entry><command>Icon=application.png</command></entry>
	      <entry>The icon name associated with this application.</entry>
	    </row>
	    <row>
	      <entry><command>Terminal=false</command></entry>
	      <entry>Describes whether the application should run in a terminal.</entry>
	    </row>
	  </tbody>

	</tgroup>
      </table>

      <section id="commandline">
	<title>Starting your application</title>
	<para>If your application can take command line arguments, you can signify that by using the fields as shown in <xref linkend="tb-exec-params"/>.</para>

	<table id="tb-exec-params">
	  <title>Exec variables</title>
	  <tgroup cols="2">
	    <colspec colnum="1" colname="line" colwidth="1"/>
	    <colspec colnum="2" colname="desc" colwidth="1"/>

	    <thead>
	      <row>
		<entry>Add...</entry>
		<entry>Accepts...</entry>
	      </row>
	    </thead>

	    <tbody>
	      <row>
		<entry><command>%f</command></entry>
		<entry>a single filename.</entry>
	      </row>
	      <row>
		<entry><command>%F</command></entry>
		<entry>multiple filenames.</entry>
	      </row>
	      <row>
		<entry><command>%u</command></entry>
		<entry>a single URL.</entry>
	      </row>
	      <row>
		<entry><command>%U</command></entry>
		<entry>multiple URLs.</entry>
	      </row>
	      <row>
		<entry><command>%d</command></entry>
		<entry>a single directory. Used in conjunction with <command>%f</command> to locate a file.</entry>
	      </row>
	      <row>
		<entry><command>%D</command></entry>
		<entry>multiple directories. Used in conjunction with <command>%F</command> to locate files.</entry>
	      </row>
	      <row>
		<entry><command>%n</command></entry>
		<entry>a single filename without a path.</entry>
	      </row>
	      <row>
		<entry><command>%N</command></entry>
		<entry>multiple filenames without paths.</entry>
	      </row>
	      <row>
		<entry><command>%k</command></entry>
		<entry>a URI or local filename of the location of the desktop file.</entry>
	      </row>
	      <row>
		<entry><command>%v</command></entry>
		<entry>the name of the Device entry.</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</table>

      </section>

      <section id="internationalization">
	<title>Foreign languages</title>

	<para>To create localised names and comments, additional lines for each locale need to be added. For example, to add a Swedish version of the comment, add the following line:</para>

	<para>
	  <command>Comment[sv]=Exempelprogramnamn</command>
	</para>

	<para>There is no limit to the number of translations in the file.</para>

	<tip>
	  <para>Since maintaining a long list of translations in a file is cumbersome, a better way to create these translations is to use the <application>intltool</application> package. See the man pages for <application>intltool-extract</application> and <application>intltool-merge</application> for more information.</para>
	</tip>

      </section>

      <section id="desktop-references">
	<title>References</title>

	<para><ulink url="http://standards.freedesktop.org/desktop-entry-spec/latest/index.html">Desktop Entry Specification</ulink> — Specifications for creating a desktop file.</para>
      </section>
    </section>

    <section id="icons">
      <title>Installing icons</title>

      <para>In <xref linkend="ex-sample-desktop-file"/>, we have specified the icon for this application as <filename><replaceable>application.png</replaceable></filename>. In order for this to work, we need to put that icon file in the correct directory.</para>

      <para>The desktop looks for icons in the selected theme directory of <filename class="directory">/usr/share/icons/</filename>. Application icons should be available at least at a resolution of 48x48 pixels. Place the icon in <filename class="directory">/usr/share/icons/hicolor/48x48/apps/</filename>. This is the directory the desktop looks in if there is no icon for your application in the selected theme. If you have themed icons, put them in the appropriate directories.</para>

      <para>To better visually integrate with the GNOME desktop, while keeping your application look native when run under KDE, Windows XP or Mac OS X, follow the <ulink url="http://tango.freedesktop.org/Tango_Icon_Theme_Guidelines">Tango Style guidelines</ulink> when creating your artwork. The document explains various aspects of icon design, including colours, lighting and sizes. Some typical workflow and video tutorials are also provided.</para>


      <section id="icons-references">
	<title>References</title>

	<para><ulink url="http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html">Icon Theme Specification</ulink> — Describes how to install and look up icons in a themeable way.</para>

	<para><ulink url="http://standards.freedesktop.org/icon-naming-spec/latest/">Icon Naming Specification</ulink> — Provides a canonical naming scheme for icon files.</para>

	<para><ulink url="http://tango.freedesktop.org/Tango_Icon_Theme_Guidelines">Tango Style Guidelines</ulink> — Provides description on how to design clean and 'multiplatform' icon artwork.</para>
      </section>
    </section>

    <section id="mime">
      <title>Adding MIME types</title>

      <para>If your application can open specific MIME types, you need to let the desktop know in the desktop file. For example, if your application can accept <acronym>PNG</acronym> files, add the following line into your desktop file:</para>

      <para>
	<screen>MimeType=image/png</screen>
      </para>

      <para>Additional MIME types can be added by separating the different types with semicolons.</para>

      <para>The system already knows of a large number of MIME types. However, if you are creating one of your own, you need to register your MIME type with the MIME database. In the <filename class="directory">/usr/share/mime/packages/</filename> directory, create an <acronym>XML</acronym> file with the format as shown in <xref linkend="ex-mime-xml"/>.</para>

      <example id="ex-mime-xml">
	<title>Sample file for registering a new MIME type</title>
<screen>
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info"&gt;
   &lt;mime-type type="application/x-<replaceable>example</replaceable>"&gt;
     &lt;comment&gt;Example file type &lt;/comment&gt;
     &lt;magic priority="50"&gt;
       &lt;match value="<replaceable>search-string</replaceable>" type="string" offset="10:140"/&gt;
     &lt;/magic&gt;
     &lt;glob pattern="*.<replaceable>newextension</replaceable>"/&gt;
   &lt;/mime-type&gt;
&lt;/mime-info&gt;
</screen>
      </example>

      <para>In this example, replace the example MIME type with the name of your MIME type. The <firstterm>magic</firstterm> section searches files for the search string for identification. The <firstterm>glob</firstterm> line uses the suffix of file names for identification.</para>

      <tip>
	<para>Because the <command>magic</command> command forces the computer to open the files to search for the string, the <command>glob</command> command is preferable.</para>
      </tip>

      <para>Once your new MIME type is adequately described in the file, run the following in a shell:</para>

      <para>
	<screen>update-mime-database /usr/share/mime</screen>
      </para>

      <tip>
	<para>For more information on choosing a good MIME extension and to register your MIME type, go to the <ulink url="http://www.iana.org/cgi-bin/mediatypes.pl">IANA</ulink> website.</para>
      </tip>

      <section id="mime-references">
	<title>References</title>

	<para><ulink url="http://standards.freedesktop.org/shared-mime-info-spec/latest/">Shared MIME Info Specification</ulink> — Describes the MIME registration system in detail.</para>
      </section>

    </section>

  </chapter>

  <chapter id="deeper-integration">
    <title>Deeper Integration with the Desktop</title>

    <para>This chapter contains a list of things which you can do to make your application have better integration with GNOME than the absolute minimum. For example, GNOME is able to display feedback while an application is being launched: you can see how to enable this feedback in <xref linkend="startup-notification"/>. Also, if your software creates documents or other "printable" data, you can install a thumbnailer utility to let the GNOME file manager create thumbnail images specific to your program.</para>

    <section id="startup-notification">
      <title>Startup notification</title>

      <para>Although the fields shown in <xref linkend="desktop-files"/> provide enough information for the desktop to recognise your application, there are other fields that may be useful for your particular case. One of these fields is <firstterm>startup notification</firstterm>.</para>

      <para>When startup notification is set, the panel and cursor notifies the user that the application has started. When the application appears onscreen, the panel and cursor return to normal.</para>

      <para>To let the launcher know your application supports startup notification, add the following line to your desktop file:</para>

      <para>
	<command>StartupNotify=true</command>
      </para>

      <para>This command in the desktop file enables the desktop to use whatever startup notification is built in to either your application or your toolkit. Most modern toolkits work transparently with the startup notification system. If you are not using a modern toolkit, the <ulink url="http://freedesktop.org/wiki/Standards_2fstartup_2dnotification_2dspec">Startup Notification Spec</ulink> has the details that you need to implement it yourself.</para>

      <tip>
	<para>Regardless of toolkit, there is one type of application where you would have to manually handle feedback. Applications with remoting capabilities (where you tell an existing process to open a new window instead of starting a new process) cannot use the built-in mechanism. The value of the <envar>DESKTOP_LAUNCH_ID</envar> environment has to be passed by your application and have it notify the launching system of your new window. If you are using <application>GTK+</application>, the documentation for <function>gdk_notify_startup_complete()</function> has a bit more information.</para>
      </tip>

      <section id="startup-notification-references">
	<title>References</title>

	<para><ulink url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt">Startup Notification Protocol</ulink> — Describes the low-level details of how startup notification is implemented in the X Window System.</para>
      </section>
    </section>

    <section id="thumbnailer">
      <title>Installing a Thumbnailer Program</title>

      <para>The GNOME file manager, <application>Nautilus</application>, can display little thumbnails tailored for each file instead of generic icons in its file lists. For example, a word processor document can be made to appear as a little version of the first page in the document. This is useful because users can see a small representation of the visible data in their files, which may aid in recalling what file they are looking for. You can make your application create these thumbnails with a few simple steps.</para>

      <!-- FIXME: screenshot of Nautilus showing thumbnails -->

      <para>A <firstterm>thumbnailer</firstterm> is a program with no user interface that takes a file and a pixel size as inputs, and it writes a thumbnail for that file. GNOME determines which thumbnailer program to use based on the MIME type of the file for which a thumbnail is to be generated. The mapping between MIME types and thumbnailer programs is stored as a series of GConf keys.</para>

      <para>For each MIME type which you want to handle, you have to create a pair of GConf keys:</para>

      <variablelist>
	<varlistentry>
	  <term><literal>/desktop/gnome/thumbnailers/<replaceable>application@x-foo</replaceable>/enable</literal></term>
	  <listitem>
	    <para>Type: boolean. Determines whether this thumbnailer will be run. You can enable or disable individual thumbnailers. When you install a new thumbnailer, you should of course make this key's value be <symbol>true</symbol>.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>/desktop/gnome/thumbnailers/<replaceable>application@x-foo</replaceable>/command</literal></term>
	  <listitem>
	    <para>Type: string. The command which GNOME will use when it needs to generate a thumbnail for a file of type <replaceable>application@x-foo</replaceable>. For example, the value could be "<literal>application-x-foo-thumbnailer %i %o %s</literal>". See below for an explanation of the percent signs.</para>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>That is, each MIME type requires two GConf keys (<literal>enable</literal> and <literal>command</literal>) under the same path. The path name can be derived from the MIME type name by substituting a "<literal>/</literal>" with "<literal>@</literal>". For example, a thumbnailer for <literal>image/x-my-format</literal> would need two keys: <literal>/desktop/gnome/thumbnailers/<replaceable>image@x-my-format</replaceable>/enable</literal> and <literal>/desktop/gnome/thumbnailers/<replaceable>image@x-my-format</replaceable>/command</literal>.</para>

      <para>Within the <literal>command</literal> key, GNOME will look for percent sequences and substitute them with actual values:</para>

      <informaltable frame="none">
	<tgroup cols="2">
	  <tbody valign="top">
	    <row>
	      <entry><literal>%i</literal></entry>
	      <entry>Input file name. This is the file that your thumbnailer needs to read.</entry>
	    </row>
	    <row>
	      <entry><literal>%u</literal></entry>
	      <entry>Input URI. If your thumbnailer can handle URIs instead of plain file names, use <literal>%u</literal> instead of <literal>%i</literal>.</entry>
	    </row>
	    <row>
	      <entry><literal>%o</literal></entry>
	      <entry>Output file name. This is where your thumbnailer should write the thumbnail image in PNG format.</entry>
	    </row>
	    <row>
	      <entry><literal>%s</literal></entry>
	      <entry>Size of the thumbnail as a single integer. For example, if this gets substituted with <literal>128</literal>, it means that your thumbnailer should output an image no bigger than 128×128 pixels.</entry>
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>

      <para>Either of <literal>%i</literal> and <literal>%u</literal> must appear in your command, and <literal>%o</literal> is also mandatory. The <literal>%s</literal> substitution is optional, but we recommend that your thumbnailer pay attention to it.</para>

      <section>
	<title>Additional information</title>

	<para>As an additional configuration parameter, you can turn on the boolean key <literal>/desktop/gnome/thumbnailers/disable_all</literal> to disable the generation of all thumbnails.</para>
      </section>

      <!-- FIXME: we mentioned the GConf keys, but not how to set them
      globally.  Do we need to describe how to install
      schemas/defaults? -->
    </section>

  </chapter>

  <appendix id="apx-integration-checklist">
    <title>Integration Checklist</title>

    <para>This appendix provides a checklist of the various tasks presented through this guide. You can use the checklist to ensure that your software is integrated into GNOME in at least the most basic ways, and also as a resource to plan for further integration work.</para>

    <orderedlist>
      <listitem>
	<para>Does your application appear in the menus of the GNOME Panel?</para>
      </listitem>
      <listitem>
	<para>Does your application have an icon for the panel menus or the desktop? If so, does it have multiple pre-rendered sizes and a scalable <acronym>SVG</acronym> version?</para>
      </listitem>
      <listitem>
	<para>If your application can load or save files, does it register the MIME types that it can handle?</para>
      </listitem>
      <listitem>
	<para>Does your application provide MIME icons for the file manager?</para>
      </listitem>
      <listitem>
	<para>Does your application support startup notification, so that GNOME can display feedback to the user while your application is being launched?</para>
      </listitem>
      <listitem>
	<para>If your application creates "printable" documents, does it install a thumbnailer for use by the file manager?</para>
      </listitem>
    </orderedlist>
  </appendix>

  <appendix id="apx-acknowledgments">
    <title>Acknowledgments</title>

    <para>Many thanks to Jakub Steiner for providing a beautiful CSS stylesheet for the HTML version of this guide!</para>
  </appendix>

</book>