Application registration

Application can be registered in the compositor by adding Desktop Entry Files to the folder /etc/window_manager/clients. Each file specifies information for a specific application and defines one registration. These files follows the Desktop Entry Specification created by freedesktop.org. The specification is used to describe information about a program and how it is launched.

Basic format

Desktop Entry Files are encoded in UTF-8 and each file is interpreted as a series of lines that are separated by linefeed characters. The contents of the file is case sensitive.

File name

Desktop Entry Files begin with the application name and end with .desktop as the file extension. The name can only contain ASCII letters, digits, dash and underscore, set of characters [A-Za-z0-9-_]. File names must be unique.

Example of name:

ccwebbrowser.desktop

Comments

Lines beginning with # or empty / blank lines are considered comments and ignored.

Groups

Desktop Entry Files contains one or more groups. The groups are used to organize entries with similar properties together. Each entry following a specific group header belongs to that group, until a new group header is read. A group header is defined on one line with the following format:

[Group Name]

The group name can contain all ASCII characters except for [, ] and control characters. Multiple groups cannot have the same name. Every Desktop Entry File require that there are a group header named Desktop Entry. The group name is case sensitive and therefore the name Desktop Entry not equal to DESKTOP ENTRY. Other than comments nothing should precede this group in the desktop entry file.

See list of recognized groups in section Recognized Groups

Entries

Each new entry in the group are of a {key,value} pair in the format:

Key=Value

Spaces before and after the equal sign, =, are ignored.

Keys

Keys can only contain ASCII letters, digits and dash, set [A-Za-z0-9-]. The keys are also case sensitive and therefore the key Name is not equal to NAME. Keys in the same group cannot have the same name but a key can have the same name in different groups. Keys can either be REQUIRED or OPTIONAL. OPTIONAL key can be omitted from the file if the default value is desired.

See list of recognized keys in different groups in section Recognized Keys

Key types

Keys can be of the following types:

  • String: all ASCII characters except for control characters

  • Localestring: user displayed and encoded in UTF-8

  • Numeric: valid numeric floating number

  • Boolean: true or false

  • Key:Value: where Key and Value can only contain ASCII letters, digits and dash, set [A-Za-z0-9-].

Some keys can contain multiple values. These keys are specified with the type in plural. For example: string(s), (Key:Value)(s). Multiple values are separated by a semicolon, ;.

Locale keys

Localestring is used for keys that are displayable. Depending on the locality set on the display the appropriate key that matches the locale will be used when fetching the value.

Keys of the type localestring can be postfixed by [LOCALE] where LOCALE is locality in the format lang_COUNTRY, where _COUNTRY can be omitted. The locality is defined by the LC_MESSAGES field in the locale command of the display.

Locality is specified by writing the POSIX code of the language with or without the country code between brackets, [], after the Key name separated by an underscore, _, in the following format:

[language_COUNTRY]

Example of locale definition:

Name=CC Web browser
Name[sv]=CC Webbläsare
Name[sv_SE]=CC Webbläsare

Note If a key is postfixed with locality the same key needs to be defined without the postfix.

Recognized Groups

The following table contains the groups that we recognize and support.

Group Description
Desktop Entry Contains all the standard keys from the Desktop Entry Specification
X-CCWindowManager Settings Contains the keys that we have added to the Desktop Entry Specification

Recognized keys

Keys recognized in group Desktop Entry

Table of keys that are recognized in the group Desktop Entry.

Key Description Type REQ Default Value
Name Specifies the name of the application. Localestring Yes - -
Icon The path to the icon for the application. NOTE! The path needs to start with file:/// String No Default
TryExec The absolute path to the binary of the application. It is used to get the name of the binary and to confirm that the application is installed before executing the Exec command. String Yes - -
Exec The command to start the application with arguments. String Yes - -

Keys recognized in group X-CCWindowManager Settings

Table of keys that are recognized in the group X-CCWindowManager Settings.

Key Description Type REQ Default Value
X-DefaultRegion Defines default region for specific layout(s). Key is a layout ID and Value is a region ID in the layout. One region can be defined per layout. NOTE! It is possible to assign a default region to every layout by using the layout ID DEFAULT. Example: DEFAULT:Fullscreen. It is also possible to use the defaultRegion ID from a layout by using the region ID DEFAULT and the ID of the layout. Example: Half:DEFAULT (Key:Values)(s) No DEFAULT:QuickBar
X-WindowState The state of how the window should be at startup. See list off supported states in section X-WindowState. String No NORMAL
X-MinimizedMode The operation mode of the application while minimized. See list off supported states in section X-MinimizedMode. String No RUNNING
X-SurfaceContainer Path to custom qml file to replace the default surface container containing the surface item. NOTE! The path needs to start with file:/// String No Default
X-QuickBarElement Path to custom qml file to replace the default element in the Quick Bar. NOTE! The path needs to start with file:/// String No Default

Supported values for keys

Type

Supported values for the key Type.

Value Description
APPLICATION Defines that the desktop entry is an application registering to the Window Manager

Window State

Supported states for the key X-WindowState.

Value Description
MINIMIZED The application is minimized at start.
NORMAL The application starts in the operation area if the defined X-DefaultRegion for the current layout is available.

Minimized Mode

Supported modes for the key X-MinimizedMode.

Value Description
RUNNING The application will remain running while the window state is minimized.
PAUSED The application will be paused while the window state is minimized. The application will resume again when window state is normal.

Example of Desktop Entry file

Below is an example Desktop Entry File for the application CC Web Browser. In this example the application will be started from a service.

# Defining the group Desktop Entry
[Desktop Entry]
# Setting the name of the entry to CC Web browser
Name=CC Web browser
# Setting the name of the entry to CC Webbläsare if the language on the target is set to Swedish
Name[sv]=CC Webbläsare
# Setting the icon to be used in the Quick Bar
Icon=file:///opt/ccwebbrowser/icon/ccweb.png
# Setting the path to the binary that the service will execute
TryExec=/opt/ccwebbrowser/bin/ccwebbrowser
# Setting the command the service will execute
Exec=/opt/ccwebbrowser/bin/ccwebbrowser --platform wayland

# Defining the group X-CCWindowManager Settings
[X-CCWindowManager Settings]
# Setting the default region for the layout Single to Fullscreen, the layout Half to Left and the default region for all layouts Fullscreen
X-DefaultRegion=Single:Fullscreen;Half:Left;DEFAULT:Fullscreen
# Setting the Window State to NORMAL to start the application in the Operation Area
X-WindowState=NORMAL
# Setting that the application will be running in the background while minimized
X-MinimizedMode=RUNNING
# Setting path to custom Surface Container
X-SurfaceContainer=file:///opt/ccwebbrowser/qml/surfaceContainer.qml
# Setting path to custom QuickBar Element
X-QuickBarElement=file:///opt/ccwebbrowser/qml/quickBarElement.qml