Generic factory-by-name registry for the five UI extension seams the phosphor-shell exposes (bar widgets, control center tiles, launcher providers, OSDs and desktop widgets), the plugin catalog every plugin seam of the suite shares, and the bar-widget plugin loader built on it.
Phosphor used to ship several hand-rolled registries (phosphor-layout-api/ILayoutSourceFactory, phosphor-tiles/AlgorithmRegistry, phosphor-shaders/ShaderRegistry, phosphor-animation/AnimationShaderRegistry), each designed on its own for its domain. phosphor-registry generalises the pattern into a single template. All four now store their entries in a Registry<T>, and the shell instantiates the same template once per UI seam.
| Type | Purpose |
|---|---|
| PhosphorRegistry::Registry<T> | Template registry. Stores factories of type T keyed by T::id(). Instance-per-composition-root. Emits factoryRegistered / factoryUnregistered via its RegistryNotifier. |
| PhosphorRegistry::RegistryNotifier | QObject signal carrier the template owns. The template itself can't be Q_OBJECT, so signals route through this. Reached via registry.notifier(). |
| PhosphorRegistry::IFactoryBase | Common base for the five interface families. Declares id(), displayName(), capabilities(). |
| PhosphorRegistry::IBarWidgetFactory | Factory for one top-bar widget (clock, workspaces, tray, etc.). Adds createWidget(QQmlEngine*, QObject*). |
| PhosphorRegistry::IControlCenterTileFactory | Factory for one tile inside the Control Center popout. Adds createTile(QQmlEngine*, QObject*). Consumed by phosphor-shell-libs/libs/phosphor-shell-control-center, over the registry phosphor-shell/src/ControlCenterController populates. The returned item must be handed to JavaScriptOwnership, because the surface destroys the tiles it built. |
| PhosphorRegistry::ILauncherProvider | The launcher's query contract, implemented by each provider. Declares setQuery(), results(), resultsChanged() and activate(id, Primary\|Alternate). Returning false from activate leaves the surface open. |
| PhosphorRegistry::ILauncherProviderFactory | Factory for a launcher query provider (apps, calculator, etc.). Adds createProvider(QObject*) -> ILauncherProvider*. Consumed by phosphor-shell-libs/libs/phosphor-shell-launcher, over the registry phosphor-shell/src/LauncherController populates. |
| PhosphorRegistry::IOSDFactory | Factory for an on-screen display (volume / mic / brightness). Adds createOSD(QQmlEngine*, QObject*). No consumer yet, reserved for a future OSD surface. |
| PhosphorRegistry::IDesktopWidgetFactory | Factory for a desktop card / widget. Adds createWidget(QQmlEngine*, QObject*). No consumer yet, reserved for a future desktop-widget surface. |
| PhosphorRegistry::PluginCatalog | Finds the plugins of one PluginSeam across the search paths, offers their PluginMetadata without loading them, records RefusedPlugins with the reason, and loads one on load(id). Hot-reloads on filesystem change. |
| PhosphorRegistry::IBarWidgetPlugin | The interface a bar-widget plugin's root object implements: createFactory() -> std::unique_ptr<IBarWidgetFactory>. |
| PhosphorRegistry::PluginLoader | The bar-widget seam (barWidgetSeam()): loads every bar-widget plugin as soon as it is found and registers its factory in a Registry<IBarWidgetFactory>, unregistering it when the catalog withdraws the plugin. |
C++ shell composition root: register built-ins explicitly, then arm the plugin loader for any third-party plugins.
#include <PhosphorRegistry/PhosphorRegistry.h>
using namespace PhosphorRegistry;
Registry<IBarWidgetFactory> barRegistry;
// Built-ins: explicit register
barRegistry.registerFactory(std::make_shared<ClockFactory>());
barRegistry.registerFactory(std::make_shared<WorkspacesFactory>());
barRegistry.registerFactory(std::make_shared<MediaFactory>());
// Connect first: the first scan loads every plugin before it returns.
QObject::connect(barRegistry.notifier(), &RegistryNotifier::factoryRegistered,
[&](const QString& id) { qDebug() << "registered" << id; });
// Plugins, into the same registry:
PluginLoader loader(&barRegistry); // searches PluginCatalog::defaultSearchPaths("bar-widget")
loader.scanAndLoad();Glue layer: the shell wraps the registry in a QObject controller that exposes the factory ids as a Q_PROPERTY(QStringList) and the widget construction as a Q_INVOKABLE. The library stays QML-free so consumers own their own facade. This controller pattern is what both phosphor-registry demos use. The snippets below name it BarController to match the production-shell shape (a top-bar widget controller). phosphor-shell-libs/examples/phosphor-registry-demo/Main.qml wires the same pattern under the context-property name demoController to keep the demo's QML self-describing.
// barcontroller.h
class BarController : public QObject
{
Q_OBJECT
Q_PROPERTY(QStringList factoryIds READ factoryIds NOTIFY factoryIdsChanged)
public:
explicit BarController(QObject* parent = nullptr);
void setEngine(QQmlEngine* engine); // call once from main()
Q_INVOKABLE QQuickItem* createWidgetFor(const QString& id, QQuickItem* parent);
[[nodiscard]] QStringList factoryIds() const;
Q_SIGNALS:
void factoryIdsChanged();
private:
QPointer<QQmlEngine> m_engine;
PhosphorRegistry::Registry<PhosphorRegistry::IBarWidgetFactory> m_registry;
};
// barcontroller.cpp: forward the registry's signals as one factoryIdsChanged
QObject::connect(m_registry.notifier(),
&PhosphorRegistry::RegistryNotifier::factoryRegistered,
this, &BarController::factoryIdsChanged);
QObject::connect(m_registry.notifier(),
&PhosphorRegistry::RegistryNotifier::factoryUnregistered,
this, &BarController::factoryIdsChanged);
QStringList BarController::factoryIds() const
{
// Registry::ids() returns registration (insertion) order, which is
// already deterministic. We sort here only to present an alphabetical
// bar layout (a real shell would persist a user-configured order; the
// demos sort alphabetically for simplicity).
QStringList ids = m_registry.ids();
ids.sort();
return ids;
}
QQuickItem* BarController::createWidgetFor(const QString& id, QQuickItem* parent)
{
if (!m_engine) return nullptr;
auto factory = m_registry.factory(id);
if (!factory) return nullptr;
return factory->createWidget(m_engine.data(), parent);
}Bar QML: a Repeater drives factoryIds and parents each widget under its own delegate Item. Repeater destroys old delegates on model change, and QObject's parent-cascade takes the C++-owned widgets with them (no manual child.destroy(), which fails on C++-owned QQuickItems with "indestructible object" errors).
Row {
spacing: 8
Repeater {
model: barController ? barController.factoryIds : []
delegate: Item {
id: slot
required property string modelData
property Item widget: null
implicitWidth: widget ? widget.implicitWidth : 0
implicitHeight: widget ? widget.implicitHeight : 0
Component.onCompleted: {
slot.widget = barController.createWidgetFor(slot.modelData, slot)
}
}
}
}The bar refreshes automatically when plugins load or unload because factoryIdsChanged re-evaluates the Repeater's model binding. See phosphor-shell-libs/examples/phosphor-registry-demo/ for the in-process variant and phosphor-shell-libs/examples/phosphor-registry-plugin-demo/ for the same pattern with a third widget loaded from a separate plugin.
Plugin author side: a plugin is a Qt plugin whose root object implements IBarWidgetPlugin, installed in a bar-widget directory on the search path.
// myplugin.cpp
#include <PhosphorRegistry/IBarWidgetPlugin.h>
#include <new>
class MyFactory : public PhosphorRegistry::IBarWidgetFactory { /* id() returns "my-plugin" */ };
class MyPlugin : public QObject, public PhosphorRegistry::IBarWidgetPlugin
{
Q_OBJECT
Q_PLUGIN_METADATA(IID PhosphorRegistryBarWidgetPlugin_iid FILE "metadata.json")
Q_INTERFACES(PhosphorRegistry::IBarWidgetPlugin)
public:
std::unique_ptr<PhosphorRegistry::IBarWidgetFactory> createFactory() override
{
// createFactory must not throw, so allocate without throwing and
// return nullptr when that fails.
return std::unique_ptr<PhosphorRegistry::IBarWidgetFactory>(new (std::nothrow) MyFactory);
}
};
#include "myplugin.moc"
{
"Id": "my-plugin",
"ApiVersion": 1
}
qt_add_plugin(my-plugin SHARED myplugin.cpp)
target_link_libraries(my-plugin PRIVATE PhosphorRegistry::PhosphorRegistry Qt6::Core Qt6::Quick)
install(TARGETS my-plugin LIBRARY DESTINATION ${KDE_INSTALL_PLUGINDIR}/phosphor-works/bar-widget)The library and its directory must be writable by their owner alone. A umask of 002, the default for user-private groups on several distributions, leaves both group-writable, and the catalog then refuses the plugin. Run chmod go-w on both, in a build tree too when it is on PHOSPHOR_WORKS_PLUGIN_PATH. The linker writes a new file on every relink, so a build tree needs that after each build.