Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
IBarWidgetFactory.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 <PhosphorRegistry/phosphorregistry_export.h>
7
8#include <QtCore/qtclasshelpermacros.h>
9
10QT_BEGIN_NAMESPACE
11class QObject;
12class QQmlEngine;
13class QQuickItem;
14QT_END_NAMESPACE
15
17
18// Factory for a single top-bar widget (clock, workspaces, focused-app,
19// tray, media, battery, etc.). Each consumed by the bar's host QML
20// via Registry<IBarWidgetFactory>::factory(id)->createWidget(...).
21//
22// createWidget() returns a freshly-constructed QQuickItem the bar
23// host parents into its layout. The factory does not retain
24// ownership — the returned item lives under the parent argument and
25// is destroyed when that parent is destroyed (typical QQuickItem
26// parent-child lifetime).
27class PHOSPHORREGISTRY_EXPORT IBarWidgetFactory : public IFactoryBase
28{
29public:
30 IBarWidgetFactory() = default;
31 ~IBarWidgetFactory() override = default;
32 Q_DISABLE_COPY_MOVE(IBarWidgetFactory)
33
34 // Construct a new QQuickItem for this factory.
35 //
36 // engine MUST NOT be null. The contract is "the shell's QML
37 // engine the widget should be instantiated against" — callers
38 // that lose their engine (e.g., during shutdown) must skip the
39 // createWidget call rather than pass nullptr. Factories may
40 // qWarning + return nullptr defensively, but the call-site
41 // contract is non-null.
42 //
43 // parent becomes the item's QObject parent so the bar host's
44 // destruction cascades through. The factory does not retain
45 // ownership — the returned item lives under parent.
46 //
47 // Like engine, the call-site contract is non-null: an item created
48 // with no parent has no owner at all (the returned item is
49 // CppOwnership), so nothing would ever delete it. Factories MAY
50 // qWarning + return nullptr defensively, as the shell's own
51 // QmlComponentBarWidgetFactory does, but test fakes and plugin
52 // examples deliberately hand back an unrooted item instead and leave
53 // disposal to the caller.
54 //
55 // Returns nullptr if the factory cannot construct a widget right
56 // now (e.g., a required external service is unavailable). The
57 // bar host treats nullptr as "skip this slot, leave a gap or
58 // suppress the layout entry" — never as an error to log/abort.
59 [[nodiscard]] virtual QQuickItem* createWidget(QQmlEngine* engine, QObject* parent) = 0;
60};
61
62} // namespace PhosphorRegistry
virtual QQuickItem * createWidget(QQmlEngine *engine, QObject *parent)=0
~IBarWidgetFactory() override=default
Definition IBarWidgetFactory.h:16