Dolphin/Desktop entries
The XDG Desktop Entry specification defines a standard for applications to integrate into application menus of desktop environments implementing the XDG Desktop Menu specification.
Basics
Each desktop entry must have a Vorlage:Ic and a Vorlage:Ic key and can optionally define its appearance in the application menu.
The three available types are:
- Application
- Defines how to launch an application and what MIME types it supports (used by XDG MIME Applications). With XDG Autostart Application entries can be started automatically by placing them in specific directories. Application entries use the Vorlage:Ic file extension. See #Application entry.
- Link
- Defines a shortcut to a Vorlage:Ic. Link entries use the Vorlage:Ic file extension.
- Directory
- Defines the appearance of a submenu in the application menu. Directory entries use the Vorlage:Ic file extension.
The following sections will roughly explain how these are created and validated.
Application entry
Desktop entries for applications, or Vorlage:Ic files, are generally a combination of meta information resources and a shortcut of an application. These files usually reside in Vorlage:Ic or Vorlage:Ic for applications installed system-wide, or Vorlage:Ic for user-specific applications. User entries take precedence over system entries.
File example
Following is an example of its structure with additional comments. The example is only meant to give a quick impression, and does not show how to utilize all possible entry keys. The complete list of keys can be found in the freedesktop specification.
[Desktop Entry] # The type as listed above Type=Application # The version of the desktop entry specification to which this file complies Version=1.0 # The name of the application Name=jMemorize # A comment which can/will be used as a tooltip Comment=Flash card based learning tool # The path to the folder in which the executable is run Path=/opt/jmemorise # The executable of the application, possibly with arguments. Exec=jmemorize # The name of the icon that will be used to display this entry Icon=jmemorize # Describes whether this application needs to be run in a terminal or not Terminal=false # Describes the categories in which this entry should be shown Categories=Education;Languages;Java;
Key definition
All recognized entries can be found on the freedesktop site. For example, the Vorlage:Ic key defines three types of desktop entries: Application (type 1), Link (type 2) and Directory (type 3).
- Vorlage:Ic key does not stand for the version of the application, but for the version of the desktop entry specification to which this file complies.
- Vorlage:Ic, Vorlage:Ic and Vorlage:Ic often contain redundant values in the form of combinations of them, like:
Name=Pidgin Internet Messenger GenericName=Internet Messenger
or
Name=NoteCase notes manager Comment=Notes Manager
This should be avoided, as it will only be confusing to users. The Vorlage:Ic key should only contain the name, or maybe an abbreviation/acronym if available.
- Vorlage:Ic should state what you would generally call an application that does what this specific application offers (i.e. Firefox is a "Web Browser").
- Vorlage:Ic is intended to contain any useful additional information.
Validation
As some keys have become deprecated over time, you may want to validate your desktop entries using Vorlage:Man which is part of the Vorlage:Pkg package. To validate, run:
$ desktop-file-validate <your desktop file>
This will give you very verbose and useful warnings and error messages.
Installation
Use Vorlage:Man to install desktop file into target directory. For example:
$ desktop-file-install --dir=$HOME/.local/share/applications ~/app.desktop
Update database of desktop entries
To make desktop entries defined in Vorlage:Ic work, run the following command:
$ update-desktop-database ~/.local/share/applications
Icons
See also the Icon Theme Specification.
Common image formats
Here is a short overview of image formats commonly used for icons.
| Extension | Full Name and/or Description | Graphics Type | Container Format | Supported |
|---|---|---|---|---|
| .png | Portable Network Graphics | Raster | Vorlage:No | Vorlage:Yes |
| .svg(z) | Scalable Vector Graphics | Vector | Vorlage:No | Vorlage:G |
| .xpm | X PixMap | Raster | Vorlage:No | Vorlage:Y |
| .gif | Graphics Interchange Format | Raster | Vorlage:No | Vorlage:No |
| .ico | MS Windows Icon Format | Raster | Vorlage:Yes | Vorlage:No |
| .icns | Apple Icon Image | Raster | Vorlage:Yes | Vorlage:No |
Converting icons
If you stumble across an icon which is in a format that is not supported by the freedesktop.org standard (like Vorlage:Ic or Vorlage:Ic), you can use the convert tool (which is part of the Vorlage:Pkg package) to convert it to a supported/recommended format, e.g.:
$ convert <icon name>.gif <icon name>.png
If you convert from a container format like Vorlage:Ic, you will get all images that were encapsulated in the Vorlage:Ic file in the form Vorlage:Ic. If you want to know the size of the image, or the number of images in a container file like Vorlage:Ic you can use the identify tool (also part of the Vorlage:Pkg package):
As you can see, the example ico file, although its name might suggest a single image of size 48x48, contains no less than 6 different sizes, of which one is even greater than 48x48, namely 128x128.
Alternatively, you can use icotool (from Vorlage:Pkg) to extract png images from ico container:
$ icotool -x <icon name>.ico
For extracting images from .icns container, you can use icns2png (provided by Vorlage:Pkg):
$ icns2png -x <icon name>.icns
Obtaining icons
Although packages that already ship with a .desktop file most certainly contain an icon or a set of icons, there is sometimes the case when a developer has not created a .desktop file, but may ship icons, nonetheless. So a good start is to look for icons in the source package. You can i.e. first filter for the extension with find and then use grep to filter further for certain buzzwords like the package name, "icon", "logo", etc, if there are quite a lot of images in the source package.
$ find /path/to/source/package -regex ".*\.\(svg\|png\|xpm\|gif\|ico\)$"
If the developers of an application do not include icons in their source packages, the next step would be to search on their web sites. Some projects, like i.e. Vorlage:AUR have an artwork/logo page where additional icons may be found. If a project is multi-platform, there may be the case that even if the linux/unix package does not come with an icon, the Windows package might provide one. If the project uses a Version control system like CVS/SVN/etc. and you have some experience with it, you also might consider browsing it for icons. If everything fails, the project might simply have no icon/logo yet.
Icon path
The freedesktop.org standard specifies in which order and directories programs should look for icons:
- Vorlage:Ic (for backwards compatibility)
- Vorlage:Ic
- Vorlage:Ic
Tools
Arronax
Vorlage:AUR is a graphical program to create and modify desktop entries for applications and locations.
Alacarte
Vorlage:Pkg is a graphical menu editor for GNOME using the freedesktop.org menu specification. It also supports overriding desktop entries.
jdDesktopEntryEdit
Vorlage:AUR is a graphical program using Qt to edit desktop entries.
gendesk
Vorlage:Pkg started as an Arch Linux-specific tool for generating .desktop files by fetching the needed information directly from PKGBUILD files. Now it is a general tool that takes command-line arguments.
Icons can be automatically downloaded from openiconlibrary, if available. (The source for icons is configurable).
How to use
- Add Vorlage:Ic to makedepends
- Start the Vorlage:Ic function with:
- Alternatively, if an icon is already provided ($pkgname.png, for instance). The Vorlage:Ic flag is for not downloading an icon or using the default icon. Example:
- Vorlage:Ic will be created and can be installed in the Vorlage:Ic function with:
- The icon can be installed with:
- Use Vorlage:Ic for choosing a name for the menu entry.
- Use Vorlage:Ic for setting the exec field.
- See the gendesk project for more information.
lsdesktopf
Vorlage:AUR can list available .desktop files or search their contents.
$ lsdesktopf $ lsdesktopf --list $ lsdesktopf --list gtk zh_TW,zh_CN,en_GB
It can also perform MIME-type-related searches. See XDG MIME Applications#lsdesktopf.
fbrokendesktop
The Vorlage:AUR Bash script detects broken Vorlage:Ic values pointing to non-existent paths. Without any arguments it uses preset directories in the Vorlage:Ic array. It shows only broken .desktop with full path and filename that is missing.
Examples
$ fbrokendesktop $ fbrokendesktop /usr $ fbrokendesktop /usr/share/xsessions/icewm.desktop
Tips and tricks
Run a desktop file from a terminal
If Vorlage:Pkg is installed, run Vorlage:Ic.
Or install the Vorlage:Pkg package and run Vorlage:Ic.
Modify desktop files
For system-wide .desktop files (e.g. those installed from a package), first copy the relevant .desktop file (e.g. from Vorlage:Ic) to Vorlage:Ic (e.g. Vorlage:Ic). This prevents your changes from being overwritten when the package gets updated during system upgrades. The local user-specific .desktop files should automatically take precedence over the system-wide files. Now you can modify the local user-specific .desktop file as needed.
Modify environment variables
To set environment variables, in the .desktop file, edit the Vorlage:Ic line to first use the Vorlage:Man command to set your variables. For example, with the original line commented out:
Modify command line arguments
To change or add the command line arguments, edit the Vorlage:Ic line to append the desired options. As an example, with the original line commented out:
Hide desktop entries
The visibility of the desktop entry can be controlled in multiple ways. See the Desktop Entry Specification for more information. Add one of the following lines to your .desktop file:
- All desktop environments, choose one (or both) of the following:
- Add the line Vorlage:Ic for applications that you do not want displayed in the menus.
- Add the line Vorlage:Ic for applications that you consider deleted and do not want displayed in the menus.
- Specified desktop environments, choose one of the following where Vorlage:Ic is a semicolon-delimited list of desktop environments (e.g. Vorlage:Ic, Vorlage:Ic):
- Add the line Vorlage:Ic to hide the entry only in the specified desktop environments.
- Add the line Vorlage:Ic to show the entry only in the specified desktop environments.