Desktop file format

(→Standard keys)
(→Maemo extension keys)
 
(9 intermediate revisions not shown)
Line 9: Line 9:
These files are parsed by a number of different modules in Maemo: hildon-desktop reads them to display icons in the main application menu, and launch applications. [http://maemo.gitorious.org/fremantle-hildon-desktop/libhildonmime/ libhildonmime] reads the files to launch applications associated with a specific mime type.  
These files are parsed by a number of different modules in Maemo: hildon-desktop reads them to display icons in the main application menu, and launch applications. [http://maemo.gitorious.org/fremantle-hildon-desktop/libhildonmime/ libhildonmime] reads the files to launch applications associated with a specific mime type.  
 +
 +
''widget''.desktop files are read from directory:
 +
/usr/share/applications/hildon-home/
 +
They determine which widgets can get added to desktop(s)
=== Standard keys ===
=== Standard keys ===
Line 15: Line 19:
{| class="wikitable"
{| class="wikitable"
 +
|+ Standardised desktop file keys supported in Maemo
|-
|-
! Key
! Key
Line 21: Line 26:
! Required?
! Required?
|-
|-
-
| Type
+
| <code>Type</code>
| string
| string
| Possible values are "Application", "Link" or "Directory". Only "Application" and "Directory" are parsed on Maemo.
| Possible values are "Application", "Link" or "Directory". Only "Application" and "Directory" are parsed on Maemo.
| Y
| Y
|-
|-
-
| Name
+
| <code>Name</code>
| string
| string
| The name of the Desktop Entry group - should be unique on the system
| The name of the Desktop Entry group - should be unique on the system
| Y
| Y
|-
|-
-
| Icon
+
| <code>Icon</code>
| string
| string
| Icon to display in file manager, menus, etc. If the name is an absolute path, the given file will be used. If the name is not an absolute path, the algorithm described in the [http://freedesktop.org/wiki/Standards/icon-theme-spec Icon Theme Specification] will be used to locate the icon.  
| Icon to display in file manager, menus, etc. If the name is an absolute path, the given file will be used. If the name is not an absolute path, the algorithm described in the [http://freedesktop.org/wiki/Standards/icon-theme-spec Icon Theme Specification] will be used to locate the icon.  
| N
| N
|-
|-
-
| Comment
+
| <code>Comment</code>
| string
| string
| Tooltip for the icon. Unused in touch interface.
| Tooltip for the icon. Unused in touch interface.
| N
| N
|-
|-
-
| NoDisplay
+
| <code>NoDisplay</code>
| boolean
| boolean
| If this is set to <code>true</code> the icon will not be shown in the menu. This is useful for applications which are associated with a mime type, but are not intended for standalone use.
| If this is set to <code>true</code> the icon will not be shown in the menu. This is useful for applications which are associated with a mime type, but are not intended for standalone use.
| N
| N
|-
|-
-
| Exec
+
| <code>Exec</code>
| string
| string
| The absolute path to the executable to be run when the desktop entry is selected.
| The absolute path to the executable to be run when the desktop entry is selected.
| N
| N
|-
|-
-
| Categories
+
| <code>Categories</code>
| string
| string
| This field is not used by hildon-desktop, but is used by 3rd party applications such as Catorise
| This field is not used by hildon-desktop, but is used by 3rd party applications such as Catorise
| N
| N
|-
|-
-
| MimeType
+
| <code>MimeType</code>
| string
| string
| Parsed by libhildonmime, this field relates the mime type of a file to the applications which can be used to open it.
| Parsed by libhildonmime, this field relates the mime type of a file to the applications which can be used to open it.
Line 62: Line 67:
|}
|}
-
The frequently found key "Version=" seems is unused in Maemo for time of this writing. Anyway according to http://standards.freedesktop.org/desktop-entry-spec/1.0/ar01s05.html it MUST NOT hold the version of the executable, rather it defines the format and version of the .desktop file itself *). In expression:
+
The frequently found key "<code>Version=</code>" is seemingly unused in Maemo at the time of this writing. Anyway according to http://standards.freedesktop.org/desktop-entry-spec/1.0/ar01s05.html it MUST NOT hold the version of the executable, rather it defines the format and version of the .desktop file itself *). In expression:
  Version=1.0  is the only valid version key for .desktop files (of v1.0)
  Version=1.0  is the only valid version key for .desktop files (of v1.0)
-
*)>>Version of the Desktop Entry Specification that the desktop entry conforms with. Entries that confirm with this version of the specification should use 1.0. Note that the version field is not required to be present.
+
*)>>Version of the Desktop Entry Specification that the desktop entry conforms with. Entries that conform to this version of the specification should use 1.0. Note that the version field is not required to be present.
=== Maemo extension keys ===
=== Maemo extension keys ===
Line 71: Line 76:
{| class="wikitable"
{| class="wikitable"
 +
|+ Maemo-specific extensions to the standardised desktop file keys supported in Maemo
|-
|-
! Key
! Key
Line 76: Line 82:
! Meaning
! Meaning
|-
|-
-
| X-Text-Domain
+
| <code>X-Text-Domain</code>
| string
| string
| The L10n domain from which the application name is translated (with dgettext)
| The L10n domain from which the application name is translated (with dgettext)
|-
|-
-
| X-Osso-Service
+
| <code>X-Osso-Service</code>
| string
| string
-
| DBus service name - if specified hildon desktop will try to call the top_application method on this service rather than execute what is listed in the Exec field).
+
| DBus service name - if specified hildon desktop will try to call the <code>top_application</code> method on this service rather than execute what is listed in the <code>Exec</code> field).
|-
|-
-
| X-App-Loading-Image
+
| <code>X-App-Loading-Image</code>
-
|  
+
| string
-
|  
+
| Location of application loading image, will  be loaded if there is no screenshot with the string of X-Osso-Service in $HOME/.cache/launch/, if none, no loading image is shown while the application is being started.
|-
|-
-
| X-Maemo-Prestarted
+
| <code>X-Maemo-Prestarted</code>
| boolean
| boolean
-
| If true, the application will be started automatically at boot time
+
| If true, the application will be started automatically at boot time. However: X-Maemo-Prestarted=always in calendar.desktop. Which works for e.g xchat as well
 +
 
|-
|-
-
| X-Maemo-Wm-Class
+
| <code>X-Maemo-Wm-Class</code>
|  
|  
|  
|  
|-
|-
-
| X-Maemo-Prestarted-Priority
+
| <code>X-Maemo-Prestarted-Priority</code>
-
| nuber
+
| number
-
| Proprity for the application launch - lower means application is launched sooner
+
| Priority for the application launch - lower means application is launched sooner
|-
|-
-
| X-Maemo-Switcher-Icon
+
| <code>X-Maemo-Switcher-Icon</code>
|  
|  
|  
|  
|-
|-
-
| X-Maemo-Ignore-Lowmem
+
| <code>X-Maemo-Ignore-Lowmem</code>
| boolean
| boolean
| Ignore the low memory status when this application is launched. If this is absent, or set to false, an application will not be launched if there is insufficient memory available.
| Ignore the low memory status when this application is launched. If this is absent, or set to false, an application will not be launched if there is insufficient memory available.
|-
|-
-
| X-Maemo-Prestarted-Ignore-Load
+
| <code>X-Maemo-Prestarted-Ignore-Load</code>
| boolean
| boolean
|  If true, prestart the app as soon as possible without regards to load or memory limits
|  If true, prestart the app as soon as possible without regards to load or memory limits
|-
|-
-
| X-Osso-Service
+
| <code>X-Osso-Service</code>
| string
| string
| The name of the DBus service to call to start this application on demand
| The name of the DBus service to call to start this application on demand
|-
|-
-
| X-Osso-URI-Actions
+
| <code>X-Osso-URI-Actions</code>
| string
| string
-
| Used in [[URL Handler/API rev1 | version 1 of URL handler]] to indicate URI handlers which this application can deal with
+
| Used in [[URL Handler/API rev1|version 1 of URL handler]] to indicate URI handlers which this application can deal with
 +
|-
 +
| <code>X-Multiple</code>
 +
| boolean
 +
| Allows installing multiple of these widgets on desktop (/usr/share/applications/hildon-home/*.desktop; needs reboot or killall hildon-home after edit)
|}
|}
-
Note that while Maemo 5 (Fremantle) does not by default read the "Categories="-entry from the desktop file, enhanced menu applications like [http://maemo.org/downloads/product/Maemo5/catorise/ Catorise] do. It is recommended that you add a Categories line to the .desktop file.
+
Note that while Maemo 5 (Fremantle) does not by default read the "<code>Categories=</code>"-entry from the desktop file, enhanced menu applications like [http://maemo.org/downloads/product/Maemo5/catorise/ Catorise] do. It is recommended that you add a Categories line to the .desktop file.
  Categories=Office;                ''Office or whatever Category is suitable''
  Categories=Office;                ''Office or whatever Category is suitable''
Line 131: Line 142:
=== URL handlers ===
=== URL handlers ===
-
There are a number of custom fields used in [http://maemo.gitorious.org/fremantle-hildon-desktop/libhildonmime/blobs/master/libhildonmime/hildon-uri.c hildon-uri.c] to handle [[URL Handler | custom URI groups]].
+
There are a number of custom fields used in [http://maemo.gitorious.org/fremantle-hildon-desktop/libhildonmime/blobs/master/libhildonmime/hildon-uri.c hildon-uri.c] to handle [[URL Handler|custom URI groups]].
== OS 2008 - Chinook ==
== OS 2008 - Chinook ==

Latest revision as of 15:51, 24 March 2011

Contents

[edit] Maemo 5 - Fremantle

application.desktop files are read from directory: 

/usr/share/applications/hildon/

application.desktop files consist of at least one Desktop Entry group, containing at least the fields Type and Name.

Maemo application.desktop files conform with the freedesktop.org desktop entry spec version 1.0.

These files are parsed by a number of different modules in Maemo: hildon-desktop reads them to display icons in the main application menu, and launch applications. libhildonmime reads the files to launch applications associated with a specific mime type.

widget.desktop files are read from directory: 

/usr/share/applications/hildon-home/

They determine which widgets can get added to desktop(s)

[edit] Standard keys

Maemo recognises and parses a subset of all of the standard keys defined in the desktop spec. The following keys have a specific meaning in Maemo:

Standardised desktop file keys supported in Maemo
Key Type Meaning Required?
Type string Possible values are "Application", "Link" or "Directory". Only "Application" and "Directory" are parsed on Maemo. Y
Name string The name of the Desktop Entry group - should be unique on the system Y
Icon string Icon to display in file manager, menus, etc. If the name is an absolute path, the given file will be used. If the name is not an absolute path, the algorithm described in the Icon Theme Specification will be used to locate the icon. N
Comment string Tooltip for the icon. Unused in touch interface. N
NoDisplay boolean If this is set to true the icon will not be shown in the menu. This is useful for applications which are associated with a mime type, but are not intended for standalone use. N
Exec string The absolute path to the executable to be run when the desktop entry is selected. N
Categories string This field is not used by hildon-desktop, but is used by 3rd party applications such as Catorise N
MimeType string Parsed by libhildonmime, this field relates the mime type of a file to the applications which can be used to open it. N

The frequently found key "Version=" is seemingly unused in Maemo at the time of this writing. Anyway according to http://standards.freedesktop.org/desktop-entry-spec/1.0/ar01s05.html it MUST NOT hold the version of the executable, rather it defines the format and version of the .desktop file itself *). In expression: 

Version=1.0   is the only valid version key for .desktop files (of v1.0)
  • )>>Version of the Desktop Entry Specification that the desktop entry conforms with. Entries that conform to this version of the specification should use 1.0. Note that the version field is not required to be present.

[edit] Maemo extension keys

The following keys have a particular meaning on Maemo. None of these fields are required.

Maemo-specific extensions to the standardised desktop file keys supported in Maemo
Key Type Meaning
X-Text-Domain string The L10n domain from which the application name is translated (with dgettext)
X-Osso-Service string DBus service name - if specified hildon desktop will try to call the top_application method on this service rather than execute what is listed in the Exec field).
X-App-Loading-Image string Location of application loading image, will be loaded if there is no screenshot with the string of X-Osso-Service in $HOME/.cache/launch/, if none, no loading image is shown while the application is being started.
X-Maemo-Prestarted boolean If true, the application will be started automatically at boot time. However: X-Maemo-Prestarted=always in calendar.desktop. Which works for e.g xchat as well
X-Maemo-Wm-Class
X-Maemo-Prestarted-Priority number Priority for the application launch - lower means application is launched sooner
X-Maemo-Switcher-Icon
X-Maemo-Ignore-Lowmem boolean Ignore the low memory status when this application is launched. If this is absent, or set to false, an application will not be launched if there is insufficient memory available.
X-Maemo-Prestarted-Ignore-Load boolean If true, prestart the app as soon as possible without regards to load or memory limits
X-Osso-Service string The name of the DBus service to call to start this application on demand
X-Osso-URI-Actions string Used in version 1 of URL handler to indicate URI handlers which this application can deal with
X-Multiple boolean Allows installing multiple of these widgets on desktop (/usr/share/applications/hildon-home/*.desktop; needs reboot or killall hildon-home after edit)

Note that while Maemo 5 (Fremantle) does not by default read the "Categories="-entry from the desktop file, enhanced menu applications like Catorise do. It is recommended that you add a Categories line to the .desktop file. 

Categories=Office;                 Office or whatever Category is suitable

It is silently ignored in the standard application menu, but allows you to pre-define the location of your application in Catorise. A list of valid categories is found here.

The canonical source for the key types supported on Maemo for the application menu is the hildon-desktop module, and specifically the files src/launcher/hd-launcher-item.c and src/launcher/hd-launcher-app.c

[edit] URL handlers

There are a number of custom fields used in hildon-uri.c to handle custom URI groups.

[edit] OS 2008 - Chinook

Format of Maemo .desktop files

Below are the fields supported in hildon-desktop:

Type
Should be application
Icon
Name
Categories
not used on Maemo, but used in Ubuntu mobile
Comment
now unused, was used as second line of text in the startup menu in Bora
Exec
NoDisplay
set to true to hide the entry in the menu
StartupNotify
set to false to disable the startup notification banner
StartupWMClass
used to override the expected window class name, default to the binary name

Some Maemo-specific extensions:

X-Text-Domain
set the L10n domain from which the application name is translated (with dgettext)
X-Osso-Service
a DBus service name - if specified hildon desktop will try to call the top_application method on this service rather than execute what is listed in the Exec field).

(Credits to Johan Billen)

BTW: If your application needs the browser to do special URL handling, the desktop file needs to be extended accordingly.

[edit] Further reading

Retrieved from "http://wiki.maemo.org/Desktop_file_format"