linux - gnome desktop file

Desktop files: putting your application in the desktop menus

• Integrating existing software with GNOME
 
• Basic Integration

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 register it with the set of applications that users can run.

Unlike in Windows or MacOS, in GNOME the users 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.

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.

In GNOME and other freedesktop.org-compliant desktops, an application gets registered into the desktop's menus through a desktop entry, which is a text file with .desktop 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:

• put the application in the Main Menu. To find a list of valid categories, take a look into FreeDesktop.org's Desktop Menu Specification.
• list the application in the Run Application... dialog
• create appropriate launchers in the menu or on the desktop.
• associate the name and description of the application.
• use the appropriate icon.
• recognize the MIME types it supports for opening files.

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:

	[Desktop Entry]
	Name=FooCorp Painter Pro
	Exec=foocorp-painter-pro
	Icon=foocorp-painter-pro
	Type=Application
	Categories=GTK;GNOME;Utility;
	

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.

Place this file in the /usr/share/applications directory so that it is accessible by everyone, or in~/.local/share/applications 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. 1

Each working desktop file needs to follow the same format. A minimal example of a desktop file is shown in Example 1-1. 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 key while the second half is the value. An explanation of each line is shown in Table 1-1.

Other than the first line identifying the desktop file, the order of the lines is not important. In Example 1-1, the line Type=Application could be the second row, the fifth row, or the last row and the result would be the same.

However, the keys are case sensitive. Type=Application is not the same astype=Application or TYPE=Application.

Example 1-1 Sample desktop file

[Desktop Entry]
Type=Application
Encoding=UTF-8
Name=Sample Application Name
Comment=A sample application
Exec=application
Icon=application.png
Terminal=false

Table 1-1 Line by line explanation

Line	Description
[Desktop 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 recognize the file correctly.
Type=Application	Tells the desktop that this desktop file pertains to an application. Other valid values for this key are Link and Directory.
Encoding=UTF-8	Describes the encoding of the entries in this desktop file.
Name=Sample Application Name	Names of your application for the main menu and any launchers.
Comment=A sample application	Describes the application. Used as a tooltip.
Exec=application	The command that starts this application from a shell. It can have arguments.
Icon=application.png	The icon name associated with this application.
Terminal=false	Describes whether application should run in a terminal.

• 1.1.1. Starting your application
• 1.1.2. Foreign languages
• 1.1.3. References

1.1.1. Starting your application

If your application can take command line arguments, you can signify that by using the fields as shown in Table 1-2.

Table 1-2 Exec variables

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

1.1.2. Foreign languages

To create localized 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:

Comment[sv]=Exempelprogramnamn

There is no limit to the number of translations in the file.

Since maintaining a long list of translations in a file is cumbersome, a better way to create these translations is to use the intltool package. See the man pages for intltool-extract andintltool-merge for more information.

1.1.3. References

Desktop Entry Specification — Specifications for creating a desktop file.

1 

Note that the ~/.local/share/applications 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 ~/.gnome2/vfolders/applications. 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.

Note that the KDE Desktop requires one to run kbuildsycoca to force a refresh of the menus.

Desktop files: putting your application in the desktop menus

Installing icons

source - https://developer.gnome.org/integration-guide/stable/desktop-files.html.en

---

Desktop files

If a package contains a GUI application, then it needs to also include a properly installed .desktop file. For the purposes of these guidelines, a GUI application is defined as any application which draws an X window and runs from within that window. Installed .desktop files MUST follow the desktop-entry-spec , paying particular attention to validating correct usage of Name, GenericName, Categories , StartupNotify entries.

Icon tag in Desktop Files

The icon tag can be specified in two ways:

• Full path to specific icon file:

Icon=/usr/share/pixmaps/comical.png

• Short name without file extension:

Icon=comical

The short name without file extension is preferred, because it allows for icon theming (it assumes .png by default, then tries .svg and finally .xpm), but either method is acceptable.

Additionally, there are scriptlets for packages to use to update the icon cache to ensure that the Desktop files are able to load the included icon files. See Packaging:ScriptletSnippets#Icon_Cache.

.desktop file creation

If the package doesn't already include and install its own .desktop file, you need to make your own. You can do this by including a .desktop file you create as a Source: (e.g. Source3: %{name}.desktop) or generating it in the spec file. Here are the contents of a sample .desktop file (comical.desktop):

[Desktop Entry]
Name=Comical
GenericName=Comic Archive Reader
Comment=Open .cbr & .cbz files
Exec=comical
Icon=comical
Terminal=false
Type=Application
Categories=Graphics;

desktop-file-install usage

It is not simply enough to just include the .desktop file in the package, one MUST run desktop-file-install (in %install) OR desktop-file-validate (in %check or %install) and have BuildRequires: desktop-file-utils, to help ensure .desktop file safety and spec-compliance. desktop-file-install MUST be used if the package does not install the file or there are changes desired to the .desktop file (such as add/removing categories, etc). desktop-file-validateMAY be used instead if the .desktop file's content/location does not need modification. Here are some examples of usage:

desktop-file-install                                    \
--dir=${RPM_BUILD_ROOT}%{_datadir}/applications         \
%{SOURCE3}

desktop-file-install                                    \
--add-category="AudioVideo"                             \
--delete-original                                       \
--dir=%{buildroot}%{_datadir}/applications              \
%{buildroot}/%{_datadir}/applications/foo.desktop

desktop-file-validate %{buildroot}/%{_datadir}/applications/foo.desktop

--vendor and desktop-file-install
For F19 and onwards, do not apply a vendor tag to .desktop files (using --vendor). New packages should not add a vendor tag to any older branches either. The vendor tag is implemented by adding a vendor prefix to the .desktop filename which breaks some tools. If an existing package has a vendor tag in previous Fedora releases it must continue to do so but only in those releases. This is mostly for the sake of user menu-editing which bases off of .desktop file/path names and thus break if the filename changes.

source - https://fedoraproject.org/wiki/Packaging:Guidelines#Desktop_files