Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
AppsProvider.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
8#include <PhosphorShellLauncher/phosphorshelllauncher_export.h>
9
10#include <QList>
11#include <QString>
12#include <QStringList>
13
14QT_BEGIN_NAMESPACE
15class QFileSystemWatcher;
16class QTimer;
17QT_END_NAMESPACE
18
20
21// Installed applications, from the .desktop files on the XDG applications
22// path, fuzzy-matched on name, generic name and keywords.
23//
24// The scan runs once at startup and again whenever one of the watched
25// directories changes, so an install or removal shows up on the next
26// keystroke without the shell restarting. Watcher-driven rescans are
27// coalesced, because one package install emits several change events. A
28// rescan is a full walk; applications directories are small enough that this
29// is not worth tracking per file.
30//
31// Whether the FIRST scan is synchronous depends on which constructor is
32// used; see each one.
33//
34// Ranking: each entry's score is the best fuzzy score across its name,
35// generic name and each keyword, with a fixed penalty on anything that was
36// NOT the name so "Files" the app outranks an app that merely lists
37// "files" as a keyword.
38class PHOSPHORSHELLLAUNCHER_EXPORT AppsProvider : public PhosphorRegistry::ILauncherProvider
39{
40 Q_OBJECT
41
42public:
43 // Production wiring: the XDG applications directories, the system
44 // locale, and XDG_CURRENT_DESKTOP.
45 //
46 // The first scan is DEFERRED to the event loop on this path. A shell
47 // constructs its providers before the first frame, and walking every
48 // applications directory there costs roughly a thousand file opens for a
49 // surface the user may never open.
50 explicit AppsProvider(QObject* parent = nullptr);
51 // Injectable wiring for tests and unusual hosts. `directories` in
52 // precedence order (first wins per id).
53 //
54 // Scans SYNCHRONOUSLY, so results are available as soon as the object
55 // is: a caller passing its own directories is not on a shell's startup
56 // path and generally wants to query immediately.
57 AppsProvider(QStringList directories, QString locale, QStringList currentDesktop, QObject* parent = nullptr);
58 ~AppsProvider() override;
59
60 [[nodiscard]] QString id() const override;
61 [[nodiscard]] QString displayName() const override;
62 [[nodiscard]] QString iconName() const override;
63
64 [[nodiscard]] bool listsOnEmptyQuery() const override
65 {
66 return m_listOnEmptyQuery;
67 }
68 void setListOnEmptyQuery(bool enabled);
69 void setQuery(const QString& query) override;
70 [[nodiscard]] QList<PhosphorRegistry::LauncherResult> results() const override;
71 [[nodiscard]] bool activate(const QString& resultId, Activation activation) override;
72
73 // How many rows a query may yield; the rest are dropped after ranking.
74 // Public so a host can retune it, and so tests can pin the cap.
79 void setMaximumResults(int count);
80 [[nodiscard]] int maximumResults() const;
81
82 // Score penalty applied to a match against anything but the name.
83 // Expressed against the matcher's own scale rather than as a bare
84 // number. Every other constant in the ranking derives from ScoreMatch,
85 // so retuning that would silently rescale them all and leave this one
86 // meaning something different. A quarter of one character match is
87 // enough to break a tie between a name hit and a keyword hit without
88 // outweighing a genuinely better match.
90
91 // Everything currently known, unfiltered. For tests and for a host
92 // that wants to show a full app grid.
93 //
94 // Returned BY VALUE on purpose. The watcher replaces this list wholesale
95 // from the event loop when an application is installed or removed, so a
96 // reference handed out here would dangle across any turn of the event
97 // loop, which is exactly what a host showing a grid would do with it.
98 [[nodiscard]] QList<DesktopEntry> entries() const;
99
100 // Re-walk the directories now. Also triggered by the directory watcher,
101 // through a short debounce.
102 //
103 // The CONSTRUCTOR does not call this inline: it walks every XDG
104 // applications directory and parses every file it finds, which is too
105 // much to put on a shell's pre-first-frame path for a surface the user
106 // may never open. The first scan is posted to the event loop instead, so
107 // results arrive shortly after startup rather than delaying it.
108 void rescan();
109
110 // Start `entry` the way the launcher would (detached, honouring
111 // Path and Terminal). Public and static so the surface, or a test,
112 // can launch without going through a query. Returns false when the
113 // entry has no runnable Exec, or Terminal=true and no terminal could
114 // be found.
122 [[nodiscard]] static bool launch(const DesktopEntry& entry);
123
124Q_SIGNALS:
126
127private:
128 // Shared body for both public constructors. `deferFirstScan` decides
129 // whether the initial walk runs inline or is posted to the event loop.
130 AppsProvider(QStringList directories, QString locale, QStringList currentDesktop, bool deferFirstScan,
131 QObject* parent);
132
133 void recompute();
134 // Add a watch for every configured directory that exists and is not
135 // already watched. Re-run on each rescan, because a directory can be
136 // created later or replaced out from under an existing watch.
137 void armWatches();
138
139 QStringList m_directories;
140 QString m_locale;
141 QStringList m_currentDesktop;
142 QList<DesktopEntry> m_entries;
143 QFileSystemWatcher* m_watcher = nullptr;
144 QTimer* m_rescanTimer = nullptr;
145 QString m_query;
146 QList<PhosphorRegistry::LauncherResult> m_results;
147 int m_maximumResults = 24;
148 bool m_listOnEmptyQuery = false;
149};
150
151} // namespace PhosphorShellLauncher
Definition ILauncherProvider.h:106
Activation
Definition ILauncherProvider.h:112
QList< PhosphorRegistry::LauncherResult > results() const override
QString id() const override
bool listsOnEmptyQuery() const override
Definition AppsProvider.h:64
void setListOnEmptyQuery(bool enabled)
AppsProvider(QObject *parent=nullptr)
bool activate(const QString &resultId, Activation activation) override
void setQuery(const QString &query) override
QList< DesktopEntry > entries() const
static bool launch(const DesktopEntry &entry)
Launch one entry directly, bypassing the id lookup activate() does.
AppsProvider(QStringList directories, QString locale, QStringList currentDesktop, QObject *parent=nullptr)
static constexpr int SecondaryFieldPenalty
Definition AppsProvider.h:89
QString iconName() const override
void setMaximumResults(int count)
Retunable by a host, though no host in this repo does: the default is what the shell ships with.
QString displayName() const override
static constexpr int ScoreMatch
Definition FuzzyMatcher.h:63
Definition AppsProvider.h:19
Definition DesktopEntry.h:24