Home · All Namespaces · All Classes · Grouped Classes · Modules · Functions codeless banner

Desktop File Standard

A .desktop file provides the information required by the the Qt Extended Document System to include an application in a launcher folder.

Installation

The install path for a .desktop file is /apps/<category>/<appname>.desktop where <category> is the category ID of the launcher folder the entry should appear in and <appname> is the name of the application binary. The category ID must belong to an existing launcher folder and will typically be one of the following:

These categories have been chosen and defined in this way to make it easier for the average user to differentiate between them.

To install software in other categories would create confusion and should be avoided. For example, you should not attempt to categorize your software as a "Utility", since it is difficult to differentiate this category from the Settings and Applications categories (it falls somewhere in between).

For information on creating additional application categories see Create a launcher folder.

File Format

The whole file has to be encoded using the QSettings INI file format and encoded in UTF-8, see also Desktop & Configuration File Internationalization.

The file structure is similar to that used by the Unix desktops KDE and Gnome.

A .desktop file is composed of the following settings groups:

Desktop Entry

The [Desktop Entry] group contains all the mandatory information for .desktop file.

ParameterDescriptionRequired
Name[]The user-visible name that will appear in the launcher folder.

This is equivalent to the QContent::name() property.

Yes
TypeThe type of the application or document the .desktop file links to. For applications this should always be Application, for documents it is the MIME type of the document and is equivalent to the QContent::type() property.Yes
RoleCategories entries according to their intended usage, possible values include Application, Document, and Data.

This equivalent to the QContent::role() property().

No
ExecSpecifies the executable name of applications.Applications
FileSpecifies the file name of documents and data.

This is equivalent to the QContent::fileName() property.

Documents, Data
IconSpecifies the icon to be found in /opt/Qtopia/pics. Endings are auto-detected.

This is equivalent to the QContent::iconName() property.

No
Comment[]Specifies a comment describing the launcher entry.No
MimeTypeSpecifies a comma separated list of MIME types an application can open.

This is equivalent to the QContent::mimeTypes() property.

See Main Document Widget for more information on associating MIME types with an application.

No
MimeTypeIconsSpecifies a comma separated list of icons for documents of the types in the MimeType list. There should be an icon in this list for each type in the MimeType list.

This is equivalent to the QContent::mimeTypeIcons() property.

No
CategoriesSpecifies categories to add the launcher entry to in addition to the one specified in the installation path. Categories should be listed as a comma separated list of category IDs.No
CanFastLoadIndicates whether the application can be fast loaded.No
BuiltinIndicates the application is a built-in application.No

Note: Lists may by semi-colon separated instead of comma separated, however semi-colon separated lists must be enclosed in double quotes otherwise the first semi-colon will be interpreted as a comment character and everything following it will be discarded.

Translation

The [Translation] group identifies where translation data for the .desktop file can be loaded from.

ParameterDescription
FileThe name of the translation file to load.
ContextThe translation context within the file.

See also Desktop & Configuration File Internationalization.

DRM

The [DRM] group contains additional information required for DRM enabled applications.

ParameterDescription
MimeTypePermissionsContains a comma separated list of permissions that must be verified before asking the application to open a document. There should be one permission for each MIME type in the MimeType parameter.

See also Document System: DRM Integration

Other groups

If other groups are included in the .desktop their contents will be pulled into the documents database and stored as properties of the QContent created from the .desktop. These properties can be accessed using QContent::property( const QString &key, const QString &group ) where key is the parameter name and group is the settings group.

Example Application .desktop file

For applications that are simply executables, the format is as follows (lines beginning with a ';' are ignored as comments):

    [Desktop Entry]
    ; the line above is mandatory at the beginning of the file
    ;
    ; Exec specifies the name of the executable that should be in /opt/Qtopia/bin
    ; Command-line arguments to the executable are not supported and should not be used.
    Exec=executablename
    ;
    ; This should always be Application for links to applications.
    Type=Application
    ;
    ; Specifies the icon to be found in /opt/Qtopia/pics. Endings are auto-detected.
    ; The icons should be at least 32x32 and should smooth-scale well
    ; from 14x14 to at least 48x48
    Icon=Iconfile
    ;
    ; The mimetype entry specifies a comma separated list of mimetypes this application can handle.
    MimeType="audio/mp3"
    ;
    ; the next lines specify the name of the application as it should appear in the launcher
    ; and start menu
    ; Name[]="My fancy application"

For applications that are realized by a service request, the format is similar, except the Type is a service (must take one QString parameter), File is an arbitrary parameter, and Role must be "Application":

    [Desktop Entry]
    Type=Service/MyService::myMessage(QString)
    File=MyParameter
    Role=Application
    Icon=Iconfile
    Name[]="My fancy application"

By using Services to realize applications, a single application can present an interface depending on information loaded from the parameter. For example, a Java engine could load a .jar file or a weblet could load a webpage.


Copyright © 2009 Trolltech Trademarks
Qt Extended 4.4.3