Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
IControlCenterTileFactory.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
16namespace PhosphorRegistry {
17
18// Factory for one tile inside the Control Center popout (network,
19// bluetooth, audio sliders, brightness, night-mode, etc.). Mirrors
20// IBarWidgetFactory's shape — the host (Control Center QML) iterates
21// the registry and instantiates each tile via createTile().
22//
23// Phase 1.3 shipped this interface as a documented header, and the
24// consuming Control Center surface has since landed, so tile factories
25// authored against this contract are driven by a real host:
26// phosphor-shell-libs/libs/phosphor-shell-control-center's ControlCenter.qml, over the registry that
27// phosphor-shell/src/ControlCenterController populates.
28class PHOSPHORREGISTRY_EXPORT IControlCenterTileFactory : public IFactoryBase
29{
30public:
32 ~IControlCenterTileFactory() override = default;
33 Q_DISABLE_COPY_MOVE(IControlCenterTileFactory)
34
35 // Construct a tile QQuickItem rooted at parent. engine MUST NOT
36 // be null (same contract as IBarWidgetFactory::createWidget).
37 // The factory does not retain the item.
38 // Returning nullptr is allowed and means "this tile is
39 // unavailable in the current environment" (no underlying
40 // service, missing hardware, etc.).
41 //
42 // OWNERSHIP, and note this is the OPPOSITE of IBarWidgetFactory. The
43 // control-center surface destroys the tiles it materialised when it
44 // rebuilds, from QML. A QObject-parented item defaults to
45 // CppOwnership, and calling destroy() on one of those throws
46 // "indestructible object" and leaks the old tile behind the new one.
47 // An implementation MUST therefore hand the returned item to the JS
48 // engine before returning it:
49 //
50 // QQmlEngine::setObjectOwnership(item, QQmlEngine::JavaScriptOwnership);
51 //
52 // The bar host never destroys its widgets, so IBarWidgetFactory
53 // deliberately keeps CppOwnership. The two contracts differ on
54 // purpose; do not unify them.
55 [[nodiscard]] virtual QQuickItem* createTile(QQmlEngine* engine, QObject* parent) = 0;
56};
57
58} // namespace PhosphorRegistry
virtual QQuickItem * createTile(QQmlEngine *engine, QObject *parent)=0
Definition IBarWidgetFactory.h:16