Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
ModuleHost.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
6#include "phosphorcontrol_export.h"
7
9
10#include <QCollator>
11#include <QHash>
12#include <QList>
13#include <QLocale>
14#include <QObject>
15#include <QPointer>
16#include <QSet>
17#include <QString>
18#include <QStringList>
19#include <QUrl>
20#include <QVariantList>
21
22#include <functional>
23#include <memory>
24#include <optional>
25
26namespace PhosphorConfig {
27class IBackend;
28}
29
30namespace PhosphorControl {
31
33class ModuleConfigBackends;
34class ModuleContext;
35class ModuleLoadRecord;
36class ISearchProvider;
38class StagingDomain;
39
130class PHOSPHORCONTROL_EXPORT ModuleHost : public QObject
131{
132 Q_OBJECT
133public:
134 enum class ModuleState : quint8 {
136 Available,
137 Loaded,
143 Failed,
145 DisabledAfterCrash,
146 };
147 Q_ENUM(ModuleState)
148
149
151 [[nodiscard]] static PhosphorRegistry::PluginSeam seam();
152
154 [[nodiscard]] static QString pageId(const QString& moduleId, const QString& localPageId);
156 [[nodiscard]] static QString categoryNodeId(const QString& categoryId);
160 [[nodiscard]] static QUrl placeholderPageSource();
161
162 explicit ModuleHost(ApplicationController* controller, QObject* parent = nullptr);
163 ~ModuleHost() override;
164
168 void setSearchPaths(const QList<PhosphorRegistry::PluginSearchPath>& paths);
177 void setSentinelPath(const QString& path);
192 void setConfigRedirect(const QString& directory);
198 void setLocale(const QLocale& locale);
200 void setLiveReload(bool enabled);
223
225 void start();
226
237 bool loadModule(const QString& moduleId, QString* errorString = nullptr);
247 bool retryModule(const QString& moduleId, QString* errorString = nullptr);
272 [[nodiscard]] bool canRetry(const QString& moduleId) const;
273
280 [[nodiscard]] QStringList moduleIds() const;
283 [[nodiscard]] std::optional<ModuleState> state(const QString& moduleId) const;
284 [[nodiscard]] QString stateReason(const QString& moduleId) const;
288 [[nodiscard]] std::optional<ModuleMetadata> metadata(const QString& moduleId) const;
290 [[nodiscard]] QList<PhosphorRegistry::RefusedPlugin> refusedModules() const;
291
298 {
300 QString id;
301 QString reason;
302 };
303
305 [[nodiscard]] QList<RefusedExtension> refusedExtensions() const;
308 [[nodiscard]] QStringList extensionsOn(const QString& pageId) const;
309
313 {
315 QString id;
318 };
319
323 [[nodiscard]] QList<StagingDomain*> moduleDomains(const QString& moduleId) const;
326 [[nodiscard]] QList<ModuleExtension> moduleExtensions(const QString& moduleId) const;
328 [[nodiscard]] QStringList boundPages(const QString& moduleId) const;
331 [[nodiscard]] QList<ISearchProvider*> searchProviders(const QString& moduleId) const;
332
340 [[nodiscard]] PhosphorConfig::IBackend* configBackend(const QString& path) const;
341
342Q_SIGNALS:
343 void moduleLoaded(const QString& moduleId);
344 void moduleFailed(const QString& moduleId, const QString& reason);
351
352private:
353 // For sharedConfigBackend.
354 friend class ModuleContext;
355 struct Module;
356 class ModuleSearch;
357 struct SearchBatch;
359 struct ActiveExtension
360 {
361 QString moduleId;
362 QString localId;
363 QString slot;
364 QString name;
365 int order = 0;
366 };
367
368 std::shared_ptr<Module> parseModule(const QString& moduleId);
369 void mergeCategories(const Module& module);
374 void addModule(const QString& moduleId, const Module* previous = nullptr);
375 void onPluginAdded(const QString& moduleId);
376 void onPluginRemoved(const QString& moduleId);
379 void withdrawModule(Module& module);
380 void placeModules(QList<std::shared_ptr<Module>> modules);
383 bool registerPlaceholder(const QString& id, const QString& parentId, const QString& title, const QString& icon,
384 const QUrl& qmlSource, bool isCollapsible, const Module& module,
385 const ModulePageMetadata* page, qsizetype pageSlot = -1);
390 void validateCounterpartsOf(const QList<std::shared_ptr<Module>>& modules) const;
394 void indexModule(const Module& module);
401 void loadOwedSearchProviders();
404 void invalidateSearch();
409 sharedConfigBackend(const QString& path,
410 const std::function<std::unique_ptr<PhosphorConfig::IBackend>(const QString&)>& create);
411 void ensureCategoryNode(const QString& categoryId);
412 [[nodiscard]] qsizetype siblingSlot(const QString& parentId,
413 const std::function<bool(const QString& siblingId)>& sortsAfter) const;
414 [[nodiscard]] bool moduleSortsBefore(const Module& a, const Module& b) const;
415 [[nodiscard]] bool categorySortsBefore(const ModuleCategoryMetadata& a, const ModuleCategoryMetadata& b) const;
416 void onNavigation(const QString& pageId);
421 void openPage(const QString& pageId, const QString& landing, quint64 navigations);
426 void loadOwedNavigation();
434 void loadExtenders(const QString& pageId, const QString& landing, quint64 navigations);
439 void loadOwedExtenders();
442 [[nodiscard]] bool navigatedElsewhere(const QString& landing, quint64 navigations, const QString& pageId) const;
445 void showSectionsOn(const Module& owner);
446 [[nodiscard]] QString owningModule(const QString& pageId) const;
450 bool canLoadNow(const QString& moduleId, QString* errorString) const;
451 void transition(Module& module, ModuleState state, const QString& reason, bool retryable = true);
452 void disableAfterCrash(Module& module);
453 void resolveExtensions();
457 void updateExtensions();
460 void attachExtensions(Module& module);
461 void notifyExtendedPages(const QString& moduleId);
462 [[nodiscard]] QHash<QString, QStringList> extensionIdsByPage() const;
464 [[nodiscard]] QString firstPlacedPage(const Module& module) const;
465 [[nodiscard]] QVariantList extensionsFor(const QString& pageId, const QString& slot) const;
466
467 QPointer<ApplicationController> m_controller;
468 QPointer<SearchController> m_search;
470 std::unique_ptr<ModuleSearch> m_searchProvider;
472 bool m_loadingSearchProviders = false;
476 bool m_searchProvidersOwed = false;
478 bool m_placingModules = false;
481 int m_searchBatches = 0;
482 bool m_searchStale = false;
483 std::unique_ptr<PhosphorRegistry::PluginCatalog> m_catalog;
486 std::unique_ptr<ModuleLoadRecord> m_loadRecord;
488 std::optional<QLocale> m_locale;
490 QCollator m_collator;
491 bool m_started = false;
494 bool m_starting = false;
497 bool m_holdsNavigationHook = false;
502 bool m_holdsExtensionProvider = false;
505 QString m_openingPage;
508 quint64 m_navigations = 0;
513 QString m_loadingModule;
518 bool m_extendersOwed = false;
523 std::optional<QString> m_navigationOwed;
524 QHash<QString, std::shared_ptr<Module>> m_modules;
525 QHash<QString, ModuleCategoryMetadata> m_categories;
526 QSet<QString> m_registeredCategoryNodes;
528 QHash<QString, QList<ActiveExtension>> m_extensionsByPage;
529 QList<RefusedExtension> m_refusedExtensions;
531 QHash<QString, QString> m_warnedExtensions;
536 QPointer<ModuleConfigBackends> m_configBackends;
537};
538
539} // namespace PhosphorControl
Pluggable configuration backend.
Definition IBackend.h:151
Top-level orchestrator for a phosphor-control application.
Definition ApplicationController.h:47
Source of dynamic (content) search entries — rules, shaders, layouts, virtual screens,...
Definition ISearchProvider.h:23
What the host hands a module while it loads (IControlModule::registerInto).
Definition ModuleContext.h:53
QList< RefusedExtension > refusedExtensions() const
Sorted by id.
void setConfigRedirect(const QString &directory)
Make every config file a module opens (ModuleContext::configBackend) under directory instead of where...
void moduleFailed(const QString &moduleId, const QString &reason)
static QString pageId(const QString &moduleId, const QString &localPageId)
The scoped page id of localPageId in moduleId.
QStringList boundPages(const QString &moduleId) const
The page ids the module of moduleId registered while loading.
ModuleHost(ApplicationController *controller, QObject *parent=nullptr)
friend class ModuleContext
Definition ModuleHost.h:354
bool loadModule(const QString &moduleId, QString *errorString=nullptr)
Load moduleId now.
void setLiveReload(bool enabled)
Turn the catalog's live reload off, for tests. Before start().
void refusedExtensionsChanged()
refusedExtensions() changed.
bool retryModule(const QString &moduleId, QString *errorString=nullptr)
Clear DisabledAfterCrash, or a Failed state that canRetry() allows, for moduleId and load it again.
void start()
Find the modules and build the placeholder sidebar. Call once.
QList< PhosphorRegistry::RefusedPlugin > refusedModules() const
Module files the catalog refused, with the reason.
bool canRetry(const QString &moduleId) const
True when retryModule() would try to load moduleId again: it is DisabledAfterCrash,...
static PhosphorRegistry::PluginSeam seam()
The control seam: <root>/control/, PhosphorControlModule_iid, ControlModuleApiVersion.
void setLocale(const QLocale &locale)
The locale module metadata is read and sorted in.
void moduleStateChanged(const QString &moduleId, PhosphorControl::ModuleHost::ModuleState state)
Every change of a module's state or reason, including the ones start() finds (invalid metadata,...
QList< ISearchProvider * > searchProviders(const QString &moduleId) const
The search providers the module of moduleId registered while loading, but for one that is a QObject a...
QStringList extensionsOn(const QString &pageId) const
The scoped ids of the active extensions on pageId, across all its slots, sorted by Order,...
QStringList moduleIds() const
Every module the host knows, sorted: the ones on offer, and the ones the catalog stopped offering,...
QString stateReason(const QString &moduleId) const
static QString categoryNodeId(const QString &categoryId)
The page id of category categoryId's node.
static QUrl placeholderPageSource()
The QML page a module page shows while its module is not loaded.
ModuleState
Definition ModuleHost.h:134
void setSearchController(SearchController *search)
Make search find every module's pages and Search entries, and each active extension as a section of t...
std::optional< ModuleMetadata > metadata(const QString &moduleId) const
moduleId's metadata exactly as parsed.
QList< StagingDomain * > moduleDomains(const QString &moduleId) const
The headless domains moduleId registered while loading, in the order it registered them.
std::optional< ModuleState > state(const QString &moduleId) const
The state of moduleId, or nullopt for a module the host does not know.
void moduleLoaded(const QString &moduleId)
void setSentinelPath(const QString &path)
The load record: the file that holds the module being loaded and the modules disabled after a crash.
PhosphorConfig::IBackend * configBackend(const QString &path) const
The config backend modules share for the file at path, an absolute path in any spelling of the file (...
QList< ModuleExtension > moduleExtensions(const QString &moduleId) const
The sections moduleId registered while loading, in its metadata's order, whether or not they are acti...
void setSearchPaths(const QList< PhosphorRegistry::PluginSearchPath > &paths)
Directories to search for modules, highest priority first.
Global settings search: builds a ranked result list for a query.
Definition SearchController.h:50
Abstract base for anything that holds staged user changes pending an Apply.
Definition StagingDomain.h:30
Definition HostDirectory.h:19
Definition ApplicationController.h:21
A top-level sidebar category a module defines.
Definition ModuleMetadata.h:18
A section a module registered while loading (ModuleContext:: registerExtension).
Definition ModuleHost.h:313
QString id
The local extension id.
Definition ModuleHost.h:315
StagingDomain * domain
Definition ModuleHost.h:317
QUrl qmlSource
Definition ModuleHost.h:316
An extension that will not be shown, and why: its target module is installed but could not be placed,...
Definition ModuleHost.h:298
QString id
<module>:<extension>.
Definition ModuleHost.h:300
QString reason
Definition ModuleHost.h:301
One page of a module, as its metadata describes it.
Definition ModuleMetadata.h:27
One kind of plugin the suite loads, such as bar widgets.
Definition PluginCatalog.h:37