Skip to content
Phosphor
/
API Reference
Search
PlasmaZones
Libraries
Guides
Brand
Palette
About
GitHub
Discord
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
19
namespace
PhosphorControl
{
20
21
class
PageController
;
22
45
class
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
61
public
:
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
;
136
PageVisibility
visibility
=
PageVisibility::Always
;
146
QString
counterpartId
{};
160
bool
passesContext
=
false
;
161
};
162
163
explicit
PageRegistry
(QObject* parent =
nullptr
);
164
~PageRegistry
()
override
;
165
182
bool
registerPage
(
Entry
entry
);
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
;
226
void
setShowAdvanced
(
bool
showAdvanced
);
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
;
280
bool
validateCounterparts
()
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
364
Q_SIGNALS:
365
void
pageRegistered
(
const
QString&
id
);
367
void
pageBound
(
const
QString&
id
);
368
void
showAdvancedChanged
();
378
void
visibleSetChanged
();
379
380
private
:
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
PhosphorControl::PageController
Base class for a settings page: a staging domain backed by a QML page that appears in the sidebar.
Definition
PageController.h:24
PhosphorControl::PageRegistry::childPagesData
QVariantList childPagesData(const QString &parentId) const
PhosphorControl::PageRegistry::titleKey
static QLatin1String titleKey()
Key under which the page-data dicts above carry the title.
PhosphorControl::PageRegistry::pageBound
void pageBound(const QString &id)
A registered page got a new controller and QML source (bindPage).
PhosphorControl::PageRegistry::entry
Entry entry(const QString &id) const
Look up an Entry by id.
PhosphorControl::PageRegistry::hasPage
bool hasPage(const QString &id) const
PhosphorControl::PageRegistry::showAdvanced
bool showAdvanced() const
PhosphorControl::PageRegistry::pagesInTreeOrder
QList< const Entry * > pagesInTreeOrder() const
Every entry in the order the sidebar draws the tree: each page, then its children in their sibling or...
PhosphorControl::PageRegistry::allPages
QList< Entry > allPages() const
PhosphorControl::PageRegistry::pageData
QVariantMap pageData(const QString &id) const
PhosphorControl::PageRegistry::allPagesRef
const QList< Entry > & allPagesRef() const
The catalogue by reference, for whole-list walks that only READ, such as ApplicationController::dirty...
PhosphorControl::PageRegistry::showAdvancedChanged
void showAdvancedChanged()
PhosphorControl::PageRegistry::registerPage
bool registerPage(Entry entry)
Register a page.
PhosphorControl::PageRegistry::registerPage
bool registerPage(Entry entry, qsizetype siblingPosition)
registerPage, placing the entry at siblingPosition among its parent's children instead of after them.
PhosphorControl::PageRegistry::PageVisibility
PageVisibility
Master toggle for the two-tier "simple vs advanced" sidebar.
Definition
PageRegistry.h:70
PhosphorControl::PageRegistry::PageVisibility::Always
@ Always
Definition
PageRegistry.h:71
PhosphorControl::PageRegistry::childPages
QList< Entry > childPages(const QString &parentId) const
PhosphorControl::PageRegistry::~PageRegistry
~PageRegistry() override
PhosphorControl::PageRegistry::hasNavigablePage
bool hasNavigablePage(const QString &id) const
True iff id is a registered page that carries its own QML body, i.e.
PhosphorControl::PageRegistry::parentIdOf
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.
PhosphorControl::PageRegistry::validateCounterparts
bool validateCounterparts(const QStringList &ids) const
validateCounterparts for the entries ids alone, with the same checks and warnings.
PhosphorControl::PageRegistry::visibleChildPages
QList< Entry > visibleChildPages(const QString &parentId) const
Children of parentId that survive the current mode's filter, including the empty-category rule (a vir...
PhosphorControl::PageRegistry::allPagesData
QVariantList allPagesData() const
Full flat list of every registered page, in registration order, unfiltered.
PhosphorControl::PageRegistry::pageAllowedInCurrentMode
bool pageAllowedInCurrentMode(const QString &id) const
True iff the page is reachable under the current showAdvanced mode: its own visibility tier passes AN...
PhosphorControl::PageRegistry::validateCounterparts
bool validateCounterparts() const
Log a warning for every entry whose counterpartId is broken.
PhosphorControl::PageRegistry::MaxParentChainHops
static constexpr int MaxParentChainHops
The most ancestors a page may have.
Definition
PageRegistry.h:84
PhosphorControl::PageRegistry::visibleSetChanged
void visibleSetChanged()
The set of entries visible under the current mode may have changed — either the mode flipped or an en...
PhosphorControl::PageRegistry::setShowAdvanced
void setShowAdvanced(bool showAdvanced)
PhosphorControl::PageRegistry::topLevelPagesData
QVariantList topLevelPagesData() const
PhosphorControl::PageRegistry::setPageVisibility
void setPageVisibility(const QString &id, PageVisibility visibility)
Restamp a page's simple/advanced tier after it has been registered.
PhosphorControl::PageRegistry::controller
PhosphorControl::PageController * controller(const QString &id) const
PhosphorControl::PageRegistry::allowedInMode
bool allowedInMode(const QString &id, bool advanced) const
pageAllowedInCurrentMode against an EXPLICIT mode rather than the current one.
PhosphorControl::PageRegistry::bindPage
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,...
PhosphorControl::PageRegistry::pageRegistered
void pageRegistered(const QString &id)
PhosphorControl::PageRegistry::firstVisibleLeafId
QString firstVisibleLeafId(const QString &parentId) const
Depth-first search (sibling order) below parentId for the first navigable page visible under the curr...
PhosphorControl::PageRegistry::PageRegistry
PageRegistry(QObject *parent=nullptr)
PhosphorControl::PageRegistry::topLevelPages
QList< Entry > topLevelPages() const
PhosphorControl::PageRegistry::setPassesContext
void setPassesContext(const QString &id, bool passesContext)
Mark page id as one whose QML is created with controller and settingsApp already set (Entry::passesCo...
PhosphorControl
Definition
ApplicationController.h:21
PhosphorControl::PageRegistry::Entry
Public-by-value view of a registry entry.
Definition
PageRegistry.h:104
PhosphorControl::PageRegistry::Entry::iconSource
QString iconSource
Definition
PageRegistry.h:108
PhosphorControl::PageRegistry::Entry::counterpartId
QString counterpartId
Optional id of this page's other-mode counterpart.
Definition
PageRegistry.h:146
PhosphorControl::PageRegistry::Entry::isCollapsible
bool isCollapsible
When true, the Sidebar renders this entry as an inline-expandable category header rather than a drill...
Definition
PageRegistry.h:119
PhosphorControl::PageRegistry::Entry::visibility
PageVisibility visibility
Simple/advanced tier for this page.
Definition
PageRegistry.h:136
PhosphorControl::PageRegistry::Entry::title
QString title
Definition
PageRegistry.h:107
PhosphorControl::PageRegistry::Entry::id
QString id
Definition
PageRegistry.h:105
PhosphorControl::PageRegistry::Entry::controller
QPointer< PageController > controller
Definition
PageRegistry.h:113
PhosphorControl::PageRegistry::Entry::parentId
QString parentId
Definition
PageRegistry.h:106
PhosphorControl::PageRegistry::Entry::qmlSource
QUrl qmlSource
Definition
PageRegistry.h:109
PhosphorControl::PageRegistry::Entry::hasDividerAfter
bool hasDividerAfter
When true, the Sidebar draws a horizontal divider line in the row slot immediately after this entry.
Definition
PageRegistry.h:125
PhosphorControl::PageRegistry::Entry::passesContext
bool passesContext
The page's QML root declares controller and settingsApp, and PageHost sets them when it creates the p...
Definition
PageRegistry.h:160
phosphor-control
include
PhosphorControl
PageRegistry.h
Generated by
1.15.0