Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
DesktopEntry.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: 2026 fuddlesworth
2// SPDX-License-Identifier: LGPL-2.1-or-later
3#pragma once
4
5#include <PhosphorShellLauncher/phosphorshelllauncher_export.h>
6
7#include <QList>
8#include <QString>
9#include <QStringList>
10
11#include <optional>
12
13namespace PhosphorShellLauncher {
14
15// One application from a freedesktop .desktop file: the fields the
16// launcher needs to list it, match it and start it. Not a general
17// key-file reader; the Desktop Entry group only, Type=Application only.
18//
19// Hand-parsed rather than through QSettings' IniFormat, which mangles
20// exactly the parts of the spec a launcher relies on: it splits
21// `;`-separated list values, drops localised `Name[de]` keys, and
22// unescapes nothing. KService is not a dependency of this tree.
23struct PHOSPHORSHELLLAUNCHER_EXPORT DesktopEntry
24{
25 // The desktop-file id per the spec: the path relative to the
26 // applications directory with '/' replaced by '-' and the .desktop
27 // suffix removed. "org.mozilla.firefox", "kde4-konsole".
28 QString id;
29 // Absolute path of the file this came from.
30 QString filePath;
31 // Name and the optional secondary lines, already localised for the
32 // locale the parser was given.
33 QString name;
34 QString genericName;
35 QString comment;
36 // Freedesktop icon name, or an absolute path.
37 QString icon;
38 // The Exec line as written, field codes intact.
39 QString exec;
40 // Working directory for the process, if the entry asks for one.
41 QString path;
42 // Search terms the entry lists beyond its name.
43 QStringList keywords;
44 QStringList categories;
45 // Runs in a terminal (Terminal=true).
46 bool terminal = false;
47 // NoDisplay / Hidden. Parsed and reported rather than rejected, so a
48 // scanner can decide; the default scan drops both.
49 bool noDisplay = false;
50 bool hidden = false;
51 // OnlyShowIn / NotShowIn desktop-environment lists, verbatim.
52 QStringList onlyShowIn;
53 QStringList notShowIn;
54
55 // The Exec line turned into an argv the launcher can start: shell-style
56 // quoting resolved per the spec, and the field codes (%f %u %F %U %i
57 // %c %k and the rest) removed since a launcher passes no document.
58 // `%%` becomes a literal `%`. Empty when Exec was empty.
59 [[nodiscard]] QStringList execArgs() const;
60
61 // Whether this entry should be shown on `currentDesktop` (the
62 // `:`-separated XDG_CURRENT_DESKTOP list, e.g. {"KDE"}). Applies
63 // OnlyShowIn then NotShowIn per the spec. An empty currentDesktop
64 // shows everything that has no OnlyShowIn.
65 [[nodiscard]] bool showsOn(const QStringList& currentDesktop) const;
66
67 // Parse one file. `locale` picks the localised Name/GenericName/Comment
68 // per the spec's fallback order ("de_DE" → "de" → unlocalised); pass
69 // an empty locale for the unlocalised strings. Returns nullopt for a
70 // file that is unreadable, has no [Desktop Entry] group, is not
71 // Type=Application, has no Name, or names a TryExec that cannot be
72 // found on PATH (the spec's "treat as if it did not exist").
81 [[nodiscard]] static std::optional<DesktopEntry> parse(const QString& filePath, const QString& locale,
82 const QString& id = QString());
83};
84
85// Enumerates the applications a launcher should offer.
86class PHOSPHORSHELLLAUNCHER_EXPORT DesktopEntryScanner
87{
88public:
89 // Static-only. Instantiating it would suggest there is per-scanner
90 // state, and there is none.
92
93 // The applications directories in precedence order: the user's own
94 // first, then each XDG_DATA_DIRS entry. What QStandardPaths reports
95 // for ApplicationsLocation.
96 [[nodiscard]] static QStringList defaultDirectories();
97
98 // Scan `directories` in order. The first directory to define an id
99 // wins and later definitions of the same id are ignored, which is how
100 // a user's ~/.local/share/applications override shadows a system
101 // entry. Subdirectories are walked and folded into the id with '-'.
102 //
103 // Entries with NoDisplay or Hidden, and entries whose OnlyShowIn /
104 // NotShowIn exclude `currentDesktop`, are dropped. Files that fail to
105 // parse are skipped silently; a launcher should not refuse to list
106 // anything because one packager's file is malformed.
107 [[nodiscard]] static QList<DesktopEntry> scan(const QStringList& directories, const QString& locale,
108 const QStringList& currentDesktop);
109};
110
111} // namespace PhosphorShellLauncher
static QList< DesktopEntry > scan(const QStringList &directories, const QString &locale, const QStringList &currentDesktop)
Definition AppsProvider.h:19
Definition DesktopEntry.h:24
QString name
Definition DesktopEntry.h:33
bool showsOn(const QStringList &currentDesktop) const
bool hidden
Definition DesktopEntry.h:50
QString exec
Definition DesktopEntry.h:39
bool terminal
Definition DesktopEntry.h:46
QString id
Definition DesktopEntry.h:28
QString icon
Definition DesktopEntry.h:37
QString genericName
Definition DesktopEntry.h:34
bool noDisplay
Definition DesktopEntry.h:49
QString path
Definition DesktopEntry.h:41
QString filePath
Definition DesktopEntry.h:30
QStringList categories
Definition DesktopEntry.h:44
QString comment
Definition DesktopEntry.h:35
static std::optional< DesktopEntry > parse(const QString &filePath, const QString &locale, const QString &id=QString())
id is the entry id to stamp on the result.
QStringList onlyShowIn
Definition DesktopEntry.h:52
QStringList keywords
Definition DesktopEntry.h:43
QStringList notShowIn
Definition DesktopEntry.h:53