Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
PageRegistry.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 <QHash>
6#include <QList>
7#include <QObject>
8#include <QPointer>
9#include <QSet>
10#include <QString>
11#include <QStringList>
12#include <QUrl>
13#include <QVariantList>
14#include <QVariantMap>
15#include <QtQml/qqmlregistration.h>
16
17#include "phosphorcontrol_export.h"
18
19namespace PhosphorControl {
20
21class PageController;
22
45class PHOSPHORCONTROL_EXPORT PageRegistry : public QObject
46{
47 Q_OBJECT
48 QML_NAMED_ELEMENT(PageRegistry)
49 QML_UNCREATABLE("PageRegistry is owned by ApplicationController.")
59 Q_PROPERTY(bool showAdvanced READ showAdvanced WRITE setShowAdvanced NOTIFY showAdvancedChanged)
60
61public:
70 enum class PageVisibility {
71 Always,
72 AdvancedOnly,
73 SimpleOnly,
74 };
75 Q_ENUM(PageVisibility)
76
77
84 static constexpr int MaxParentChainHops = 32;
85
103 struct Entry
104 {
105 QString id;
106 QString parentId; // empty == top-level
107 QString title; // already translated by caller
108 QString iconSource; // freedesktop icon name or QML asset URL; optional
109 QUrl qmlSource; // page QML file URL
110 // QPointer guards against dangling lookups if a consumer destroys
111 // the controller out-of-order relative to the registry. Symmetric
112 // with ApplicationController::m_domains.
113 QPointer<PageController> controller;
119 bool isCollapsible = false;
125 bool hasDividerAfter = false;
146 QString counterpartId{};
160 bool passesContext = false;
161 };
162
163 explicit PageRegistry(QObject* parent = nullptr);
164 ~PageRegistry() override;
165
187 bool registerPage(Entry entry, qsizetype siblingPosition);
188
204 bool bindPage(const QString& id, PageController* controller, const QUrl& qmlSource);
205
213 void setPassesContext(const QString& id, bool passesContext);
214
223 void setPageVisibility(const QString& id, PageVisibility visibility);
224
225 bool showAdvanced() const;
227
228 Q_INVOKABLE bool hasPage(const QString& id) const;
235 bool hasNavigablePage(const QString& id) const;
250 bool pageAllowedInCurrentMode(const QString& id) const;
256 bool allowedInMode(const QString& id, bool advanced) const;
286 bool validateCounterparts(const QStringList& ids) const;
295 Q_INVOKABLE QString firstVisibleLeafId(const QString& parentId) const;
296 Q_INVOKABLE PhosphorControl::PageController* controller(const QString& id) const;
301 Entry entry(const QString& id) const;
306 QString parentIdOf(const QString& id) const;
307
308 QList<Entry> topLevelPages() const;
309 QList<Entry> childPages(const QString& parentId) const;
315 QList<Entry> visibleChildPages(const QString& parentId) const;
316 QList<Entry> allPages() const;
326 const QList<Entry>& allPagesRef() const;
332 QList<const Entry*> pagesInTreeOrder() const;
333
334 // QML-facing accessors. Return dicts whose canonical key set lives in
335 // entryToVariant() (pageregistry.cpp): id, parentId, title, iconSource,
336 // qmlSource, isCollapsible, hasDividerAfter, hasQmlSource, passesContext.
337 // PageHost reads passesContext to decide how it creates the page.
338 // `visibility` and `counterpartId` are deliberately C++-only: tier
339 // filtering is applied here, inside the tree accessors, so QML never needs
340 // to re-derive it, and the counterpart is navigation policy the app owns.
341 //
342 // The rail moved to SidebarRows and Breadcrumbs uses pageData /
343 // firstVisibleLeafId, so the list accessors here serve the app's own QML
344 // (the settings app's drill restore asks childPagesData whether a page
345 // has visible children) and out-of-tree consumers. Callers are QML, which
346 // no build checks, so grep before treating one as unused. Covered by tests
347 // so the serialization contract cannot rot.
348 Q_INVOKABLE QVariantList topLevelPagesData() const;
349 Q_INVOKABLE QVariantList childPagesData(const QString& parentId) const;
350 Q_INVOKABLE QVariantMap pageData(const QString& id) const;
353 Q_INVOKABLE QVariantList allPagesData() const;
354
362 static QLatin1String titleKey();
363
364Q_SIGNALS:
365 void pageRegistered(const QString& id);
367 void pageBound(const QString& id);
379
380private:
383 bool modeAllows(PageVisibility v) const;
387 static bool modeAllowsIn(PageVisibility v, bool advanced);
396 bool isEntryVisible(const Entry& entry) const;
400 bool isLiveRegisteredController(PageController* controller) const;
403 bool counterpartResolves(const Entry& e) const;
404
405 QList<Entry> m_pages;
408 bool m_showAdvanced = true;
409 // qsizetype matches QList::size()'s return type; avoids -Wnarrowing
410 // when stricter build flags land. Settings registries are never
411 // anywhere near 2^31 pages, but the narrowing is unnecessary.
412 QHash<QString, qsizetype> m_indexById;
413 // Child indices grouped by parentId (the empty key holds the top-level
414 // entries), in sibling order: registration order, unless registerPage was
415 // given a sibling position. Every tree accessor here descends through this
416 // rather than rescanning m_pages, so finding a node's children costs the
417 // size of that list. visibleChildPages(p) still costs the subtree below
418 // p, since isEntryVisible descends a virtual child until it finds a
419 // visible descendant: that is the empty-category rule, not a rescan.
420 // Built in registerPage and never invalidated: the catalogue only grows,
421 // and no in-place change moves an entry.
422 QHash<QString, QList<qsizetype>> m_childrenByParent;
423 // Controller-pointer dedup set — registerPage previously did an
424 // O(N) linear scan of m_pages per registration to reject a
425 // duplicate controller, which compounded to O(K²) for K page
426 // registrations. The set lookup keeps registration O(1) for
427 // catalogues that grow to dozens of pages.
428 QSet<PageController*> m_controllerSet;
432 QList<int> m_depths;
433};
434
435} // namespace PhosphorControl
Base class for a settings page: a staging domain backed by a QML page that appears in the sidebar.
Definition PageController.h:24
QVariantList childPagesData(const QString &parentId) const
static QLatin1String titleKey()
Key under which the page-data dicts above carry the title.
void pageBound(const QString &id)
A registered page got a new controller and QML source (bindPage).
Entry entry(const QString &id) const
Look up an Entry by id.
bool hasPage(const QString &id) const
QList< const Entry * > pagesInTreeOrder() const
Every entry in the order the sidebar draws the tree: each page, then its children in their sibling or...
QList< Entry > allPages() const
QVariantMap pageData(const QString &id) const
const QList< Entry > & allPagesRef() const
The catalogue by reference, for whole-list walks that only READ, such as ApplicationController::dirty...
bool registerPage(Entry entry)
Register a page.
bool registerPage(Entry entry, qsizetype siblingPosition)
registerPage, placing the entry at siblingPosition among its parent's children instead of after them.
PageVisibility
Master toggle for the two-tier "simple vs advanced" sidebar.
Definition PageRegistry.h:70
@ Always
Definition PageRegistry.h:71
QList< Entry > childPages(const QString &parentId) const
bool hasNavigablePage(const QString &id) const
True iff id is a registered page that carries its own QML body, i.e.
QString parentIdOf(const QString &id) const
The parentId of id, or an empty string when the id is unknown or the entry is top-level.
bool validateCounterparts(const QStringList &ids) const
validateCounterparts for the entries ids alone, with the same checks and warnings.
QList< Entry > visibleChildPages(const QString &parentId) const
Children of parentId that survive the current mode's filter, including the empty-category rule (a vir...
QVariantList allPagesData() const
Full flat list of every registered page, in registration order, unfiltered.
bool pageAllowedInCurrentMode(const QString &id) const
True iff the page is reachable under the current showAdvanced mode: its own visibility tier passes AN...
bool validateCounterparts() const
Log a warning for every entry whose counterpartId is broken.
static constexpr int MaxParentChainHops
The most ancestors a page may have.
Definition PageRegistry.h:84
void visibleSetChanged()
The set of entries visible under the current mode may have changed — either the mode flipped or an en...
void setShowAdvanced(bool showAdvanced)
QVariantList topLevelPagesData() const
void setPageVisibility(const QString &id, PageVisibility visibility)
Restamp a page's simple/advanced tier after it has been registered.
PhosphorControl::PageController * controller(const QString &id) const
bool allowedInMode(const QString &id, bool advanced) const
pageAllowedInCurrentMode against an EXPLICIT mode rather than the current one.
bool bindPage(const QString &id, PageController *controller, const QUrl &qmlSource)
Replace the controller and QML source of the registered page id, keeping its place in the tree,...
void pageRegistered(const QString &id)
QString firstVisibleLeafId(const QString &parentId) const
Depth-first search (sibling order) below parentId for the first navigable page visible under the curr...
PageRegistry(QObject *parent=nullptr)
QList< Entry > topLevelPages() const
void setPassesContext(const QString &id, bool passesContext)
Mark page id as one whose QML is created with controller and settingsApp already set (Entry::passesCo...
Definition ApplicationController.h:21
Public-by-value view of a registry entry.
Definition PageRegistry.h:104
QString iconSource
Definition PageRegistry.h:108
QString counterpartId
Optional id of this page's other-mode counterpart.
Definition PageRegistry.h:146
bool isCollapsible
When true, the Sidebar renders this entry as an inline-expandable category header rather than a drill...
Definition PageRegistry.h:119
PageVisibility visibility
Simple/advanced tier for this page.
Definition PageRegistry.h:136
QString title
Definition PageRegistry.h:107
QString id
Definition PageRegistry.h:105
QPointer< PageController > controller
Definition PageRegistry.h:113
QString parentId
Definition PageRegistry.h:106
QUrl qmlSource
Definition PageRegistry.h:109
bool hasDividerAfter
When true, the Sidebar draws a horizontal divider line in the row slot immediately after this entry.
Definition PageRegistry.h:125
bool passesContext
The page's QML root declares controller and settingsApp, and PageHost sets them when it creates the p...
Definition PageRegistry.h:160