Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
PhosphorControl::PageRegistry Class Reference

Holds the catalogue of pages an application has registered. More...

#include <PhosphorControl/PageRegistry.h>

Inheritance diagram for PhosphorControl::PageRegistry:
[legend]

Classes

struct  Entry
 Public-by-value view of a registry entry. More...

Public Types

enum class  PageVisibility { Always , AdvancedOnly , SimpleOnly }
 Master toggle for the two-tier "simple vs advanced" sidebar. More...

Signals

void pageRegistered (const QString &id)
void pageBound (const QString &id)
 A registered page got a new controller and QML source (bindPage).
void showAdvancedChanged ()
void visibleSetChanged ()
 The set of entries visible under the current mode may have changed — either the mode flipped or an entry was restamped.

Public Member Functions

 PageRegistry (QObject *parent=nullptr)
 ~PageRegistry () override
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.
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, title, icon, tier and counterpart.
void setPassesContext (const QString &id, bool passesContext)
 Mark page id as one whose QML is created with controller and settingsApp already set (Entry::passesContext).
void setPageVisibility (const QString &id, PageVisibility visibility)
 Restamp a page's simple/advanced tier after it has been registered.
bool showAdvanced () const
void setShowAdvanced (bool showAdvanced)
bool hasPage (const QString &id) const
bool hasNavigablePage (const QString &id) const
 True iff id is a registered page that carries its own QML body, i.e.
bool pageAllowedInCurrentMode (const QString &id) const
 True iff the page is reachable under the current showAdvanced mode: its own visibility tier passes AND so does every ancestor's.
bool allowedInMode (const QString &id, bool advanced) const
 pageAllowedInCurrentMode against an EXPLICIT mode rather than the current one.
bool validateCounterparts () const
 Log a warning for every entry whose counterpartId is broken.
bool validateCounterparts (const QStringList &ids) const
 validateCounterparts for the entries ids alone, with the same checks and warnings.
QString firstVisibleLeafId (const QString &parentId) const
 Depth-first search (sibling order) below parentId for the first navigable page visible under the current mode; empty string when nothing below the parent survives filtering.
PhosphorControl::PageController * controller (const QString &id) const
Entry entry (const QString &id) const
 Look up an Entry by id.
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.
QList< Entry > topLevelPages () const
QList< Entry > childPages (const QString &parentId) const
QList< Entry > visibleChildPages (const QString &parentId) const
 Children of parentId that survive the current mode's filter, including the empty-category rule (a virtual node with no surviving descendant drops out).
QList< Entry > allPages () const
const QList< Entry > & allPagesRef () const
 The catalogue by reference, for whole-list walks that only READ, such as ApplicationController::dirtyPageIds.
QList< const Entry * > pagesInTreeOrder () const
 Every entry in the order the sidebar draws the tree: each page, then its children in their sibling order, depth first.
QVariantList topLevelPagesData () const
QVariantList childPagesData (const QString &parentId) const
QVariantMap pageData (const QString &id) const
QVariantList allPagesData () const
 Full flat list of every registered page, in registration order, unfiltered.

Static Public Member Functions

static QLatin1String titleKey ()
 Key under which the page-data dicts above carry the title.

Static Public Attributes

static constexpr int MaxParentChainHops = 32
 The most ancestors a page may have.

Detailed Description

Holds the catalogue of pages an application has registered.

Pages are organised as a tree: each entry has an optional parentId. Top-level pages (parentId empty) are the entries the sidebar root displays; child pages are listed under their parent for drill-down.

The registry stores QPointer<PageController> weak references — ownership lives with whoever constructed the controller (typically the ApplicationController owning a parent QObject chain), and lookups via controller(id) return nullptr if the controller has been destroyed out-of-order. The catalogue only ever GROWS: entries are never removed at runtime, but dynamic page registration (post-startup registerPage calls) is supported and fires pageRegistered. An entry also changes in place, keeping its place in the tree: setPageVisibility restamps its simple/advanced tier (visibleSetChanged); bindPage replaces its controller and QML source and sets its passesContext flag (pageBound, plus visibleSetChanged when the entry gains or loses its QML); setPassesContext sets that flag alone, and announces nothing. None of them fires pageRegistered. Dynamic removal is intentionally NOT supported — apps that need plugin-style hot-unload should rebuild the controller.

Member Enumeration Documentation

◆ PageVisibility

Master toggle for the two-tier "simple vs advanced" sidebar.

When false, entries marked AdvancedOnly are filtered out of the tree accessors (visibleChildPages / firstVisibleLeafId / topLevelPagesData / childPagesData) and any virtual category left with no visible descendant vanishes with them; when true, SimpleOnly entries are hidden instead. Defaults to true so an app that never marks a page keeps the classic "show everything" behaviour. The value is app UI state — the app drives it (persisted however the app likes); the registry only consumes it for filtering. Per-entry visibility tier for the simple/advanced split. Always (the default) shows the page in both modes; AdvancedOnly hides it while showAdvanced is false; SimpleOnly hides it while showAdvanced is true (for purpose-built simplified pages that a richer advanced page supersedes). Filtering happens only in the QML-facing tree accessors — pageData / allPagesData / controller stay unfiltered so a currently-shown or dirty page always resolves regardless of mode.

Enumerator
Always 
AdvancedOnly 
SimpleOnly 

Constructor & Destructor Documentation

◆ PageRegistry()

PhosphorControl::PageRegistry::PageRegistry ( QObject * parent = nullptr)
explicit

◆ ~PageRegistry()

PhosphorControl::PageRegistry::~PageRegistry ( )
override

Member Function Documentation

◆ allowedInMode()

bool PhosphorControl::PageRegistry::allowedInMode ( const QString & id,
bool advanced ) const

pageAllowedInCurrentMode against an EXPLICIT mode rather than the current one.

Same ancestor walk and same unknown-id semantics. Public so SearchController can classify an entry's reachability in BOTH modes (its per-result simple/advanced tag) without flipping the live mode back and forth.

◆ allPages()

QList< Entry > PhosphorControl::PageRegistry::allPages ( ) const

◆ allPagesData()

QVariantList PhosphorControl::PageRegistry::allPagesData ( ) const

Full flat list of every registered page, in registration order, unfiltered.

◆ allPagesRef()

const QList< Entry > & PhosphorControl::PageRegistry::allPagesRef ( ) const

The catalogue by reference, for whole-list walks that only READ, such as ApplicationController::dirtyPageIds.

allPages() deep-copies every Entry, which such a walk would pay on every call for a list it only iterates. The list is in REGISTRATION order, not the order the sidebar draws; use pagesInTreeOrder() for anything the user sees in sequence. The reference stays valid until the next registry mutation that changes something (registerPage, bindPage, setPageVisibility, setPassesContext), any of which may reallocate or detach the list — do not hold it across one.

◆ bindPage()

bool PhosphorControl::PageRegistry::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, title, icon, tier and counterpart.

This is how a page registered with a placeholder controller (a control module that has not loaded yet) gets its real one. Refuses an unknown id, a null controller, a controller whose id() is not id, or a controller already registered for another page. Emits pageBound when the controller or QML source changes, and visibleSetChanged as well when the page gains or loses its QML source. Rebinding the same controller and source is accepted silently.

Every accepted bind, the silent one included, also sets the entry's passesContext: a bound page is created with controller and settingsApp already set, as the control module contract has it. That is announced by nothing of its own; PageHost reads the flag when a pageBound for a new QML source makes it create the page.

◆ childPages()

QList< Entry > PhosphorControl::PageRegistry::childPages ( const QString & parentId) const

◆ childPagesData()

QVariantList PhosphorControl::PageRegistry::childPagesData ( const QString & parentId) const

◆ controller()

PhosphorControl::PageController * PhosphorControl::PageRegistry::controller ( const QString & id) const

◆ entry()

Entry PhosphorControl::PageRegistry::entry ( const QString & id) const

Look up an Entry by id.

Returns a default-constructed (empty) Entry when the id is unknown — callers that need to distinguish "no such page" from "page exists with empty optional fields" should call hasPage() first.

◆ firstVisibleLeafId()

QString PhosphorControl::PageRegistry::firstVisibleLeafId ( const QString & parentId) const

Depth-first search (sibling order) below parentId for the first navigable page visible under the current mode; empty string when nothing below the parent survives filtering.

Pass an empty parentId to search from the root. This is the mode-aware replacement for a static "parent redirects to its first leaf" table. Q_INVOKABLE: Breadcrumbs.qml routes a non-navigable ancestor crumb through this to avoid navigating into an empty page body.

◆ hasNavigablePage()

bool PhosphorControl::PageRegistry::hasNavigablePage ( const QString & id) const

True iff id is a registered page that carries its own QML body, i.e.

a navigable destination. False for an unknown id AND for a registered virtual CATEGORY (empty qmlSource), which has no page body to land on. Folds the "registered and navigable" test into one index lookup so a caller filtering by reachability need not copy a whole Entry to read two isEmpty() bits.

◆ hasPage()

bool PhosphorControl::PageRegistry::hasPage ( const QString & id) const

◆ pageAllowedInCurrentMode()

bool PhosphorControl::PageRegistry::pageAllowedInCurrentMode ( const QString & id) const

True iff the page is reachable under the current showAdvanced mode: its own visibility tier passes AND so does every ancestor's.

The ancestor walk matters because hiding a category hides its whole subtree in the rail, so a page whose own tier passes under a filtered parent has no row and no drill path — answering "yes" for it would send search, keyboard next/prev and the mode gate somewhere the user cannot navigate back from. Unknown ids return true: this is a tier filter, not an existence check; validate with hasPage() first. It does NOT apply the empty-category descendant rule the tree accessors use — that asks "is this category worth drawing", not "may the user navigate here".

The walk always reaches a root: registerPage refuses an unknown parent and a page more than MaxParentChainHops levels down.

◆ pageBound

void PhosphorControl::PageRegistry::pageBound ( const QString & id)
signal

A registered page got a new controller and QML source (bindPage).

◆ pageData()

QVariantMap PhosphorControl::PageRegistry::pageData ( const QString & id) const

◆ pageRegistered

void PhosphorControl::PageRegistry::pageRegistered ( const QString & id)
signal

◆ pagesInTreeOrder()

QList< const Entry * > PhosphorControl::PageRegistry::pagesInTreeOrder ( ) const

Every entry in the order the sidebar draws the tree: each page, then its children in their sibling order, depth first.

This is the order keyboard next/previous and search walk, so they agree with the rail however the pages were registered. The pointers stay valid until the next registry mutation, like allPagesRef().

◆ parentIdOf()

QString PhosphorControl::PageRegistry::parentIdOf ( const QString & id) const

The parentId of id, or an empty string when the id is unknown or the entry is top-level.

Exists so an upward parent walk (ApplicationController::parentChainFor) can read one field per hop instead of copying a whole Entry to throw all but one field away.

◆ registerPage() [1/2]

bool PhosphorControl::PageRegistry::registerPage ( Entry entry)

Register a page.

Emits pageRegistered(id) and returns true on success. Warns and returns false on any of, in the order the code checks them: empty id, duplicate id, unknown parentId, a parent so deep that the page would have more than MaxParentChainHops ancestors, null controller, or the same controller already registered under another id. The intent is to surface programmer errors in the log without aborting startup; the PageRegistry's tree just won't contain the misconfigured entry — downstream Sidebar / Breadcrumbs / page-router lookups for it will return empty.

Callers that perform additional bookkeeping per registered page (e.g. ApplicationController tracking the page as a staging domain) must gate that bookkeeping on the returned bool — otherwise a rejected page leaks into half-registered state where downstream systems mutate it but the UI cannot see it.

◆ registerPage() [2/2]

bool PhosphorControl::PageRegistry::registerPage ( Entry entry,
qsizetype siblingPosition )

registerPage, placing the entry at siblingPosition among its parent's children instead of after them.

A negative or out-of-range position appends. For a host that registers late but wants the entry where a registration at startup would have put it.

◆ setPageVisibility()

void PhosphorControl::PageRegistry::setPageVisibility ( const QString & id,
PageVisibility visibility )

Restamp a page's simple/advanced tier after it has been registered.

No-op (with a warning) for an unknown id, and a no-op when the tier is already what you are setting. Declaring the tier at registration (Entry::visibility) is the canonical path; this is for a host that registers a page before it knows the tier. A real change emits visibleSetChanged() so consumers that cache a tier-filtered view stay correct whenever it is called. It does NOT emit showAdvancedChanged: the mode itself is untouched, only this one entry's tier.

◆ setPassesContext()

void PhosphorControl::PageRegistry::setPassesContext ( const QString & id,
bool passesContext )

Mark page id as one whose QML is created with controller and settingsApp already set (Entry::passesContext).

Warns for an unknown id. Emits nothing: PageHost reads the flag only when it creates the page, so set it before the page is first shown. Set later, or cleared on a page bound with bindPage(), it does nothing to a page already built, and clearing it breaks the next creation of a page that declares the properties required (see Entry::passesContext).

◆ setShowAdvanced()

void PhosphorControl::PageRegistry::setShowAdvanced ( bool showAdvanced)

◆ showAdvanced()

bool PhosphorControl::PageRegistry::showAdvanced ( ) const

◆ showAdvancedChanged

void PhosphorControl::PageRegistry::showAdvancedChanged ( )
signal

◆ titleKey()

QLatin1String PhosphorControl::PageRegistry::titleKey ( )
static

Key under which the page-data dicts above carry the title.

Exposed so SidebarRows::flatPageData can override that field through the SAME constant the registry writes it with, rather than its own independent "title" literal — two spellings of one schema key means a rename here would silently ADD a second key over there instead of overriding, and the assertion on the literal would stay green while the UI read the un-overridden value.

◆ topLevelPages()

QList< Entry > PhosphorControl::PageRegistry::topLevelPages ( ) const

◆ topLevelPagesData()

QVariantList PhosphorControl::PageRegistry::topLevelPagesData ( ) const

◆ validateCounterparts() [1/2]

bool PhosphorControl::PageRegistry::validateCounterparts ( ) const

Log a warning for every entry whose counterpartId is broken.

Listed in the order the warnings are emitted, which the tests assert: the counterpart is this entry ITSELF; it names a page that does not exist; it does not name this entry back (a one-way declaration dead-ends the RETURN flip on the app fallback); it sits in the SAME tier (so a mode flip would redirect to something equally hidden); it is not navigable (a category with no QML of its own, so the redirect would land on an empty page body); or it is itself unreachable in the mode that hides this entry (an ancestor category filters it out, so the redirect falls back anyway).

Reciprocity is checked BEFORE the tier fault and does not share its skip, because the two are independent: a pair that is both same-tier and one-way has two faults and must report both.

NOT exhaustive for the runtime gate: the app additionally requires the counterpart to be in its own valid-page set, which this cannot see. Counterparts are stored unvalidated at registration because the target may be registered later, and nothing else ever checks them: a typo silently degrades every affected mode flip and deep link to the fallback page, and looks exactly like correct operation. Call once after registration completes. Returns true when every counterpart resolves.

◆ validateCounterparts() [2/2]

bool PhosphorControl::PageRegistry::validateCounterparts ( const QStringList & ids) const

validateCounterparts for the entries ids alone, with the same checks and warnings.

An unknown id, or an entry with no counterpart, passes. For a host that registers pages after the application checked its own (ModuleHost, as modules take their place), so the application's pages are not warned about again.

◆ visibleChildPages()

QList< Entry > PhosphorControl::PageRegistry::visibleChildPages ( const QString & parentId) const

Children of parentId that survive the current mode's filter, including the empty-category rule (a virtual node with no surviving descendant drops out).

The Entry-returning twin of childPagesData(); childPages() above is deliberately UNFILTERED, so anything building a navigable view wants this one.

◆ visibleSetChanged

void PhosphorControl::PageRegistry::visibleSetChanged ( )
signal

The set of entries visible under the current mode may have changed — either the mode flipped or an entry was restamped.

Consumers that cache a tier-filtered view (SearchController's index, any external tree mirror) should rebuild on this rather than on showAdvancedChanged, which fires only for a genuine mode flip. Kept distinct because showAdvancedChanged is the NOTIFY of the showAdvanced Q_PROPERTY: firing it when the property has not changed would re-evaluate every binding on it and mislead any consumer that reasonably reads it as "the user switched modes".

Member Data Documentation

◆ MaxParentChainHops

int PhosphorControl::PageRegistry::MaxParentChainHops = 32
staticconstexpr

The most ancestors a page may have.

registerPage refuses a page any deeper, and refuses a parent that is not registered yet, so the catalogue is a forest no deeper than this, and every upward walk (allowedInMode, ApplicationController::parentChainFor, Breadcrumbs) reaches a root within this many parent links. Declared here rather than per walk: they have to agree with the registration bound, and a comment asking a human to keep constants in step is not a mechanism.


The documentation for this class was generated from the following file: