Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
ILauncherProvider.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 <PhosphorRegistry/phosphorregistry_export.h>
6
7#include <QList>
8#include <QMetaType>
9#include <QObject>
10#include <QString>
11
12namespace PhosphorRegistry {
13
14// One row a launcher provider contributes for the current query.
15//
16// A plain value: the launcher surface copies these into its own ranked
17// model, so a provider may rebuild its list wholesale on every query
18// without anything holding references into it. `id` is the handle the
19// surface passes back to activate(); it only has to be unique within the
20// provider that issued it.
21struct PHOSPHORREGISTRY_EXPORT LauncherResult
22{
23 Q_GADGET
24 Q_PROPERTY(QString id MEMBER id)
25 Q_PROPERTY(QString title MEMBER title)
26 Q_PROPERTY(QString subtitle MEMBER subtitle)
27 Q_PROPERTY(QString iconName MEMBER iconName)
28 Q_PROPERTY(int score MEMBER score)
29 Q_PROPERTY(QString primaryActionLabel MEMBER primaryActionLabel)
30 Q_PROPERTY(QString alternateActionLabel MEMBER alternateActionLabel)
31
32public:
33 QString id;
34 QString title;
35 QString subtitle;
36 // Freedesktop icon name, resolved by the surface through the icon
37 // theme. Empty means the surface draws the provider's own glyph.
38 //
39 // A name, not a path. Kirigami.Icon does accept a file path or a URL
40 // here and the surface does not reject one, so a provider whose source
41 // is client-controlled must refuse path-shaped values itself rather
42 // than pass them through: the windows provider does exactly that with
43 // an app id, since a client could otherwise have the shell load an
44 // arbitrary file.
45 QString iconName;
46 // Whether the ALTERNATE action can sensibly be performed again on the
47 // same list. A destructive prune (removing clipboard entries one by
48 // one) is: the user usually wants several, and closing after the first
49 // means reopening and retyping. Launching something is not.
50 //
51 // Only the alternate action has this. A primary action is the reason
52 // the user opened the launcher, so it always finishes the interaction.
54 // Ranking score, higher is better. Providers that fuzzy-match should
55 // return the matcher's score so rows from different providers rank
56 // against each other on one scale; a provider that answers a query
57 // exactly (the calculator) should return a large fixed score.
58 int score = 0;
59 // What Enter does ("Open", "Run", "Copy"). Shown beside the selected row.
61 // What Alt+Enter does, or empty when the row has no second action.
63
64 [[nodiscard]] bool hasAlternateAction() const
65 {
66 return !alternateActionLabel.isEmpty();
67 }
68
69 // So a provider can tell whether a recompute actually changed anything
70 // before announcing it. Without this every provider emits on every
71 // recompute, and each emission costs the model a full reset, which drops
72 // the surface's selected row.
73 [[nodiscard]] bool operator==(const LauncherResult& other) const = default;
74};
75
76// The provider contract the launcher surface drives. This is the concrete
77// type ILauncherProviderFactory::createProvider() promised in Phase 1.3.
78//
79// A provider is a pure data source: it is handed the query and answers
80// with rows. It owns no UI. The surface owns ranking across providers,
81// grouping, selection and keyboard handling.
82//
83// Query flow is push-then-pull. setQuery() hands over the new text and
84// returns; the provider recomputes (synchronously, or asynchronously for
85// one that has to hit a bus or a disk) and emits resultsChanged() whenever
86// results() would now answer differently, including for the query that
87// was just set. A synchronous provider emits it from inside setQuery.
88// The surface reads results() on that signal and never caches across
89// queries.
90// THREAD AFFINITY. Every provider lives on the thread that constructed
91// it, and the surface drives them from the GUI thread. That is not
92// incidental: one implementation owns a QFileSystemWatcher whose
93// notifications are delivered on its own thread, and another reaches
94// QGuiApplication::clipboard(), which is GUI-thread-only. A host must
95// construct and drive providers from one thread, and a provider that
96// wants to work off it has to marshal back before touching results().
97//
98// id() MUST be unique across the providers a host registers, and stable for
99// the life of the process: the model buckets rows and counts by it, so two
100// providers sharing an id collapse into one bucket and the pill for it
101// reports their sum while the filter shows only one of them. The registry
102// refuses a duplicate FACTORY id, which is what a host registers through, so
103// this is enforced for anything built that way and is a bare contract for a
104// provider added to the model directly.
105class PHOSPHORREGISTRY_EXPORT ILauncherProvider : public QObject
106{
107 Q_OBJECT
108
109public:
110 // What the user asked for. Primary is Enter; Alternate is Alt+Enter
111 // and only valid for a result whose alternateActionLabel is set.
112 enum class Activation {
113 Primary,
114 Alternate,
115 };
116 Q_ENUM(Activation)
117
118 explicit ILauncherProvider(QObject* parent = nullptr)
119 : QObject(parent)
120 {
121 }
122 ~ILauncherProvider() override = default;
123
124 // Stable id, matching the factory that created this provider.
125 [[nodiscard]] virtual QString id() const = 0;
126 // Header / pill text ("Apps", "Windows").
127 [[nodiscard]] virtual QString displayName() const = 0;
128 // Glyph for the header and for rows that supply no icon of their own.
129 [[nodiscard]] virtual QString iconName() const = 0;
130
131 // Whether this provider has anything to say for an EMPTY query. Most
132 // do not (Spotlight shows nothing until typed); a window switcher or
133 // clipboard history reasonably lists everything.
134 [[nodiscard]] virtual bool listsOnEmptyQuery() const
135 {
136 return false;
137 }
138
139 virtual void setQuery(const QString& query) = 0;
140 [[nodiscard]] virtual QList<LauncherResult> results() const = 0;
141
142 // Perform the action for `resultId`. Returns false when the id is
143 // unknown, the action is not offered, or the action failed to start;
144 // the surface then stays open rather than closing on a no-op.
145 [[nodiscard]] virtual bool activate(const QString& resultId, Activation activation) = 0;
146
147Q_SIGNALS:
149};
150
151} // namespace PhosphorRegistry
152
153Q_DECLARE_METATYPE(PhosphorRegistry::LauncherResult)
virtual void setQuery(const QString &query)=0
virtual QList< LauncherResult > results() const =0
Activation
Definition ILauncherProvider.h:112
virtual bool listsOnEmptyQuery() const
Definition ILauncherProvider.h:134
virtual QString displayName() const =0
~ILauncherProvider() override=default
virtual QString id() const =0
virtual bool activate(const QString &resultId, Activation activation)=0
virtual QString iconName() const =0
ILauncherProvider(QObject *parent=nullptr)
Definition ILauncherProvider.h:118
Definition IBarWidgetFactory.h:16
Definition ILauncherProvider.h:22
bool hasAlternateAction() const
Definition ILauncherProvider.h:64
int score
Definition ILauncherProvider.h:58
QString subtitle
Definition ILauncherProvider.h:35
QString iconName
Definition ILauncherProvider.h:45
bool alternateIsRepeatable
Definition ILauncherProvider.h:53
QString title
Definition ILauncherProvider.h:34
bool operator==(const LauncherResult &other) const =default
QString id
Definition ILauncherProvider.h:33
QString primaryActionLabel
Definition ILauncherProvider.h:60
QString alternateActionLabel
Definition ILauncherProvider.h:62