|
| | 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.
|
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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.