News | About | Get Frugalware | Packages | Documentation | Discussion Forums | Bug Tracker | Wiki | Community | Development

Creating desktop entries and menus

From FrugalWiki

Jump to: navigation, search


Contents

Introduction

As quite a lot of projects do either not supply desktop entries yet or supply some which could be improved, this article is meant to explain how to create usefull and standard compliant desktop entries and menus. It is mainly intended for package contributors and maintainers, but may hopefully be usefull for software developers, too, as in the long run, the goal is to share these contributions back upstream (AKA back to the official/original software developers) so that they and also other distributions can profit from the result.

In the following sections, we'll take a look at how desktop entries and menus are created and validated, how to cope with icons, and where to find the official standards for further reading and details.

At the moment, there are 3 types of desktop entries (descriptions are probably very inaccurate, but a good start):

Application 
a shortcut to an application (this is what most of this article is about)
Link 
a shortcut to a web link.
Directory 
a container of meta data of a menu entry

Desktop files

Desktop entries for applications (often referred to as .desktop-files) are (in general) some kind combination of meta information resource and shortcut of a program. These files have the extention .desktop and usually reside in /usr/share/applications. Here's is an example of its structure with additional comments.

[Desktop Entry]
Type=Application                          # Indicates the type as listed above
Version=1.0                               # The version of the desktop entry specification to which this file complies
Name=jMemorize                            # The name of the application
Comment=Flash card based learning tool    # A comment which can/will be used as a tooltip
Exec=jmemorize                            # The executable of the application.
Icon=jmemorize                            # The name of the icon that will be used to display this entry
Terminal=false                            # Describes whether this application needs to be run in a terminal or not
Categories=Education;Languages;Java;      # Describes the categories in which this entry should be shown

The example above is only meant to give a quick impression, and does not utilize all possible entry keys. The complete list can be found here.

Common mistakes

  1. The Version key does not stand for the version of the application, but for the version of the desktop entry specification to which this file complies.
  2. The keys Name, GenericName and Comment 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
    Please avoid something like that, as this will only confuse users. Therefore we have a standard. The Name should only contain the name, or maybe an abbreviation/acronym if available. The GenericName should state what you would generally call an application that does what this specific application offers (i.e. Firefox is a "Web Browser"). The Comment is intended to contain any usefull additional information.
  3. There are quite some keys that have become deprecated over time as the standard has matured. The best/simplest way is to use the tool desktop-file-validate which is part of the package desktop-file-utils. Just run
    $ desktop-file-validate <your desktop file>
    and it will give you very verbose and useful warnings and error messages.

Menu files

Adding Menu Items

Adding entries to menus differs depending on what desktop environment you are on.

Gnome

To edit menu entries in Gnome right click on a menu (eg "Applications"), then click on "Edit Menus". You are now presented with an app to add applications to your menu. For example, to add an application to the Accessories menu, click on the "Accessories" entry on the left, the click on the "New Item" button on the right. You can the add an icon (see below), change the name and what file is run (usually the same as the name)

Icons

Quick overview of common image formats

Here is a short overview of image formats commonly used for icons.

Support for image formats for icons as specified by the freedesktop.org standard.
Extension Full Name and/or Description Graphics Type Container Format Supported
.png Portable Network Graphics Raster no yes
.svg(z) Scalable Vector Graphics Vector no yes (optional)
.xpm X PixMap Raster no yes (deprecated)
.gif Graphics Interchange Format Raster no no
.ico MS Windows Icon Format Raster yes no
.icns Apple Icon Image Raster yes no

Converting icons

If you stumble across an icon which is in a format that is not supported by the freedesktop.org standard (like gif or ico), you can convert (which is part of the imagemagick package) it to a supported/recommended format, e.g.:

$ convert <icon name>.gif <icon name>.png             /* Converts from gif to png */

If you convert from a container format like ico, you'll get all images that were encapsulated in the ico file in the form <icon name>-<number>.png. If you want to know the size of the image, or the number of images in a container file like ico you can use identify (also part of the imagemagick package)

$ identify /usr/share/vlc/vlc48x48.ico
/usr/share/vlc/vlc48x48.ico[0] ICO 32x32 32x32+0+0 8-bit DirectClass 84.3kb
/usr/share/vlc/vlc48x48.ico[1] ICO 16x16 16x16+0+0 8-bit DirectClass 84.3kb
/usr/share/vlc/vlc48x48.ico[2] ICO 128x128 128x128+0+0 8-bit DirectClass 84.3kb
/usr/share/vlc/vlc48x48.ico[3] ICO 48x48 48x48+0+0 8-bit DirectClass 84.3kb
/usr/share/vlc/vlc48x48.ico[4] ICO 32x32 32x32+0+0 8-bit DirectClass 84.3kb
/usr/share/vlc/vlc48x48.ico[5] ICO 16x16 16x16+0+0 8-bit DirectClass 84.3kb

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. And to give a bit of motivation on this subject, at the point of writing this section (2008-10-27), the 128x128 size was missing in the vlc package (0.9.4-2). So the next step would be to look at the vlc PKGBUILD and check whether this icon format was not in the source package to begin with (in that case we'd inform the vlc developers), or whether this icon was somehow omitted from the Arch-specific package (in that case we can file a bug report at http://bugs.archlinux.org). (Update: this bug has now been fixed, so as you can see, your work won't be in vain.)

Obtaining icons

Although packages that already ship with a .desktop-file most certainly contain an icon or a set of icons, there's sometimes the case when a developer hasn't 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\)$"      /* this filters for common extensions */

If the developers of an application don't include icons in their source packages, the next step would be to search on their web sites. Some projects, like i.e. tvbrowser 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 doesn't 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 simple have no icon/logo yet.

Where to place icons

Into /usr/share/pixmaps

More Resources

Personal tools
Namespaces
Variants
Actions