DesktopEntry

A desktop entry: the `.desktop` file that names a program, its icon and the file types it opens to a Linux desktop.

In the namespace platform. Declared in src/libs/libplatform/platform/DesktopEntry.hpp.

Detailed description

The parser follows the Desktop Entry Specification (https://specifications.freedesktop.org/desktop-entry/latest/). It reads every group. The keys of the program are in the group `[Desktop Entry]`, which the specification wants first. A file with another group before it is still read, and mainGroupIsFirst() says so; the keys of the other group never count as the program's.

The accessors read the recognized keys: type(), name() with its localizations, exec(), tryExec(), icon(), workingFolder(), hidden(), noDisplay(), terminal() and mimeTypes(). isLaunchable() says whether a launcher may offer the entry: `Hidden=true` means the entry is deleted, and a `TryExec` program that is not there means that the program is not installed.

The entry keeps its file line by line (platform::KeyFile), so text() gives back the comments and empty lines it was read with.

expandExec() and execCommands() turn the `Exec` key into the argument lists to start.

See also platform::KeyFile, platform::MimeAppsList, platform::resolveMimeHandlers().

Member function documentation

boolValue

bool DesktopEntry::boolValue(const QString &key, bool defaultValue = false, const QString &group = mainGroup()) const

Returns the boolean value of key in group.

The specification's values are `true` and `false`. `1` and `0` are read too, as older files write them. Returns defaultValue when the key is missing or has another value.

exec

QString DesktopEntry::exec() const

Returns the `Exec` key, with the string escapes undone and the quoting not yet. expandExec() does the rest.

filePath

QString DesktopEntry::filePath() const

Returns the path of the file the entry was read from, or an empty string.

fromFile

[static] platform::DesktopEntry DesktopEntry::fromFile(const QString &path, QString *error = nullptr)

Reads the file at path. error, when given, says why it could not be read. Returns the entry, which is not valid when the file was not read.

fromText

[static] platform::DesktopEntry DesktopEntry::fromText(const QString &text, const QString &filePath = QString())

Parses text. filePath is the file it came from, which the `%k` field code gives to the program. Returns the entry.

hidden

bool DesktopEntry::hidden() const

Returns the `Hidden` key. True means that the entry is deleted: "strictly equivalent to the .desktop file not existing at all".

icon

QString DesktopEntry::icon() const

Returns the `Icon` key: a name in the icon theme, or an absolute path.

isLaunchable

bool DesktopEntry::isLaunchable(const platform::DesktopEntry::ProgramFinder &findProgram = ProgramFinder()) const

Returns true when a launcher may offer the entry: it is valid, of type `Application`, not hidden, has an `Exec` key, and its `TryExec` program is found with findProgram.

isValid

bool DesktopEntry::isValid() const

Returns true when the file has a `[Desktop Entry]` group.

keyFile

const platform::KeyFile &DesktopEntry::keyFile() const

Returns the lines of the file.

listValue

QStringList DesktopEntry::listValue(const QString &key, const QString &group = mainGroup()) const

Returns the list value of key in group, split at its separators and unescaped.

localeFallbacks

[static] QStringList DesktopEntry::localeFallbacks(const QString &locale)

Returns the locale suffixes to try for locale, most specific first.

The order is the one of the specification's localized-keys.html. The encoding part is ignored. For `lang_COUNTRY@MODIFIER`: `lang_COUNTRY@MODIFIER`, `lang_COUNTRY`, `lang@MODIFIER`, `lang`. For `lang_COUNTRY`: `lang_COUNTRY`, `lang`. For `lang@MODIFIER`: `lang@MODIFIER`, `lang`. The `C` and `POSIX` locales, and an empty one, have no suffix. A `-` is read as `_`.

localizedValue

QString DesktopEntry::localizedValue(const QString &key, const QString &locale, const QString &group = mainGroup()) const

Returns the value of key in group for locale.

The localized keys are tried in the order of localeFallbacks(), then the key without a locale. locale has the form `lang_COUNTRY.ENCODING@MODIFIER`, each part but `lang` optional, as `QLocale::name()` gives it. The caller passes it, because this layer reads no environment.

mainGroup

[static] QString DesktopEntry::mainGroup()

Returns the name of the group that holds the keys of the program, `Desktop Entry`.

mainGroupIsFirst

bool DesktopEntry::mainGroupIsFirst() const

Returns true when `[Desktop Entry]` is the first group of the file, as the specification wants. Comments before it are allowed.

mimeTypes

QStringList DesktopEntry::mimeTypes() const

Returns the MIME types of the `MimeType` key.

name

QString DesktopEntry::name(const QString &locale = QString()) const

Returns the `Name` key for locale, with the fallbacks of localizedValue().

noDisplay

bool DesktopEntry::noDisplay() const

Returns the `NoDisplay` key. True means that the program exists but is not shown in menus. It still opens the types it names.

setValue

void DesktopEntry::setValue(const QString &key, const QString &value, const QString &group = mainGroup())

Sets key of group to value, escaped. The other lines of the file stay as they are.

See also value().

terminal

bool DesktopEntry::terminal() const

Returns the `Terminal` key: whether the program runs in a terminal window.

text

QString DesktopEntry::text() const

Returns the file as text, with every line that no change touched as it was read.

tryExec

QString DesktopEntry::tryExec() const

Returns the `TryExec` key: the program that must exist for the entry to count.

tryExecFound

bool DesktopEntry::tryExecFound(const platform::DesktopEntry::ProgramFinder &findProgram = ProgramFinder()) const

Returns true when the entry has no `TryExec` key, or when its program exists and can run.

An absolute path is checked as it is. A name is looked up with findProgram, which is `QStandardPaths::findExecutable` when not given.

type

QString DesktopEntry::type() const

Returns the `Type` key: `Application`, `Link` or `Directory`.

value

QString DesktopEntry::value(const QString &key, const QString &group = mainGroup()) const

Returns the string value of key in group, unescaped. An empty string when the key is missing.

See also setValue().

workingFolder

QString DesktopEntry::workingFolder() const

Returns the `Path` key: the folder to start the program in, or an empty string.

Related non-members

QString desktopFileForId(const QStringList &applicationFolders, const QString &desktopId)

Returns the file that desktopId names in applicationFolders, the first folder first, or an empty string.

QString desktopFileId(const QString &applicationFolder, const QString &filePath)

Returns the desktop file id of filePath, which is below applicationFolder.

The id is the path below the folder with each `/` made a `-`: `applications/kde/foo.desktop` is `kde-foo.desktop` (Desktop Entry Specification, "Desktop File ID").

QList execCommands(const platform::DesktopEntry &entry, const QStringList &paths, const QString &locale = QString(), QString *error = nullptr)

Returns the argument lists that open paths with entry.

One list, from expandExec(), when the program takes many files. With `%f` or `%u`, which take one, one list for each path: the specification says the launcher "should probably spawn and execute multiple copies of a program". An empty result, with error set when given, when the entry is refused. locale is passed on to expandExec().

bool execTakesManyFiles(const platform::DesktopEntry &entry)

Returns true when the `Exec` key of entry takes many files in one start: it has `%F` or `%U`, or no file field code at all.

QStringList expandExec(const platform::DesktopEntry &entry, const QStringList &paths, const QString &locale = QString(), QString *error = nullptr)

Returns the argument list that starts entry with paths: the program first, then its arguments.

The rules are those of exec-variables.html. The quoting of `Exec` is undone first, then each field code is expanded once:

• `%f`: the first of paths. `%u`: the same as a URL.
• `%F`: each of paths as an argument of its own. `%U`: the same as URLs.
• `%i`: `–icon` and the `Icon` key, or nothing when there is no icon.
• `%c`: the name of the entry for locale.
• `%k`: the file of the entry.
• `%%`: a percent sign.
• The deprecated codes `%d %D %n %N %v %m` are removed.

A path is one argument, whatever it holds: no shell sees it. An argument that was only field codes, and expands to nothing, is dropped.

Returns an empty list, with error set when given, when the entry has no `Exec` key, when a quote does not close, when a field code is not in the specification, when `%F`, `%U` or `%i` is not an argument of its own, or when there are two file field codes: the specification says such a line "must not be processed".

With `%f` or `%u`, only the first path is used. execCommands() starts one program for each path in that case.