Top-level orchestrator for a phosphor-control application. More...
#include <PhosphorControl/ApplicationController.h>
Public Types | |
| using | NavigationHook = std::function<void(const QString& pageId)> |
| Called with the target page id when setCurrentPageId moves to a known page other than the current one, before the move is recorded and before currentPageIdChanged is emitted. | |
| using | ExtensionProvider = std::function<QVariantList(const QString& pageId, const QString& slot)> |
Public Slots | |
| void | applyAll () |
| void | discardAll () |
| void | resetCurrentPage () |
| void | applyAllAsync () |
| Async variant of applyAll — collects each dirty domain's applyResult signal and emits applyAllComplete(ok, errors) when all responses have landed. | |
| void | discardAllAsync () |
| Symmetric to applyAllAsync; emits discardAllComplete(ok, errors). | |
| void | forceResetAsyncState () |
| Force-reset the async-batch state machine to idle. | |
Signals | |
| void | dirtyChanged () |
| void | currentPageIdChanged () |
| void | historyChanged () |
| Emitted when canGoBack / canGoForward may have flipped (shared NOTIFY for both properties — they always change together or not at all from the QML binding system's perspective). | |
| void | pendingAnchorChanged () |
| Emitted when the deep-link pending anchor is set or cleared. | |
| void | applyingChanged () |
| Emitted on every applying-state transition (false→true at the start of applyAllAsync, true→false when the last applyResult has landed). | |
| void | discardingChanged () |
| Symmetric to applyingChanged for discardAllAsync. | |
| void | applyAllComplete (bool ok, const QStringList &errors) |
| Emitted exactly once per applyAllAsync invocation, when every dirty domain's applyResult has been received. | |
| void | discardAllComplete (bool ok, const QStringList &errors) |
| Symmetric to applyAllComplete for discardAllAsync. | |
| void | extensionsChanged (const QString &pageId) |
The sections added to page pageId changed (notifyExtensionsChanged). | |
Public Member Functions | |
| ApplicationController (QObject *parent=nullptr) | |
| ~ApplicationController () override | |
| PageRegistry * | registry () const |
| bool | isDirty () const |
| bool | isApplying () const |
| True while applyAllAsync is in flight (at least one domain's applyResult hasn't landed yet). | |
| bool | isDiscarding () const |
| True while discardAllAsync is in flight — symmetric with isApplying. | |
| QString | currentPageId () const |
| void | setCurrentPageId (const QString &id) |
| bool | canGoBack () const |
| Browser-style navigation history over currentPageId. | |
| bool | canGoForward () const |
| QString | goBack () |
| QString | goForward () |
| void | setPendingAnchor (const QString &pageId, const QString &anchor) |
| Deep-link reveal latch (generic — every settings app built on this shell gets deep-link-to-anchor for free). | |
| QString | takePendingAnchor (const QString &pageId) |
| Returns + clears the pending anchor iff it targets pageId; otherwise returns an empty string (consume-once). | |
| void | registerPage (PageController *page, const QString &parentId, const QString &title, const QUrl &qmlSource, const QString &iconSource=QString(), bool isCollapsible=false, bool hasDividerAfter=false, PageRegistry::PageVisibility visibility=PageRegistry::PageVisibility::Always, const QString &counterpartId=QString()) |
| Register a page in the sidebar. | |
| bool | registerDomain (StagingDomain *domain) |
| Register a headless staging domain (no sidebar entry). | |
| bool | isTrackedDomain (const StagingDomain *domain) const |
True iff domain is tracked: a registered page's controller or a registered headless domain. | |
| bool | bindPage (const QString &id, PageController *controller, const QUrl &qmlSource) |
Give the already-registered page id its real controller and QML source (PageRegistry::bindPage, which also refuses a controller whose id() is not id), and track the controller like a registered page. | |
| bool | setNavigationHook (QObject *owner, NavigationHook hook) |
Install hook on behalf of owner. | |
| void | clearNavigationHook (const QObject *owner) |
Remove the hook if owner installed it. A no-op otherwise. | |
| void | attachDomainToPage (StagingDomain *domain, const QString &pageId) |
Count domain as part of page pageId: dirtyPageIds() lists the page while the domain is dirty, and resetCurrentPage() on the page resets the domain too. | |
| QVariantList | extensionsFor (const QString &pageId, const QString &slot) const |
The sections other modules add to slot slot of page pageId, for the QML ExtensionSlot. | |
| bool | setExtensionProvider (QObject *owner, ExtensionProvider provider) |
Install provider on behalf of owner. | |
| void | clearExtensionProvider (const QObject *owner) |
Remove the provider if owner installed it. | |
| void | notifyExtensionsChanged (const QString &pageId) |
Tell ExtensionSlots on page pageId to read extensionsFor again. | |
| QString | gotoPreviousPage () |
| Navigate to the previous / next navigable page (one with a qmlSource) in the order the sidebar draws the tree (PageRegistry::pagesInTreeOrder). | |
| QString | gotoNextPage () |
| QStringList | parentChainFor (const QString &id) const |
| Walk the parent chain from the registered entry for id to the top level. | |
| QString | titlePathFor (const QString &id) const |
| The page's title path: every ancestor title root-first, then the page's own title, joined with titlePathSeparator(), which search results use too. | |
| QStringList | dirtyPageIds () const |
| Ids of every registered page whose controller, or a domain attached to it (attachDomainToPage), is still dirty. | |
| int | asyncBatchTimeoutMs () const |
| Async-batch timeout in milliseconds, DefaultAsyncBatchTimeoutMs by default: generous for D-Bus round trips but tight enough to surface a wedged backend instead of pinning the chrome's "Saving…" state indefinitely. | |
| void | setAsyncBatchTimeoutMs (int ms) |
Static Public Member Functions | |
| static QString | titlePathSeparator () |
| The separator between the titles of a page path (U+203A), shared by titlePathFor and SearchController's result breadcrumbs. | |
Top-level orchestrator for a phosphor-control application.
Owns the PageRegistry, the set of registered StagingDomains (including the ones embedded in PageControllers), and the current page selection.
Recomputes a global dirty flag whenever any domain's dirtyChanged() fires, drives applyAll() / discardAll() across all domains, and dispatches a per-page resetToDefaults() to the current page only: its controller and the domains attached to it (attachDomainToPage).
Apps typically subclass this to declare their pages in the constructor. Note that titles passed to registerPage must already be translated by the caller (the subclass uses its own QObject::tr() context — this library deliberately does not provide a translation context for app strings):
auto *page = new MyPage(this); registerPage(page, {}, MyApp::tr("My Page"), QUrl(QStringLiteral("qrc:/MyPage.qml")));
| using PhosphorControl::ApplicationController::ExtensionProvider = std::function<QVariantList(const QString& pageId, const QString& slot)> |
| using PhosphorControl::ApplicationController::NavigationHook = std::function<void(const QString& pageId)> |
Called with the target page id when setCurrentPageId moves to a known page other than the current one, before the move is recorded and before currentPageIdChanged is emitted.
ModuleHost uses it to load a page's module synchronously, so the page host sees the real page. When the hook (or anything it reaches) navigates on its own, that newer navigation stands and the one that called the hook is dropped.
|
explicit |
|
override |
|
slot |
|
slot |
Async variant of applyAll — collects each dirty domain's applyResult signal and emits applyAllComplete(ok, errors) when all responses have landed.
Chrome should prefer this over applyAll so a stuck D-Bus call doesn't freeze the GUI thread. Domains whose apply() is fully synchronous still emit applyResult immediately, so they complete on the same event- loop turn — the async path degenerates to "sync + one tail signal" for them.
|
signal |
Emitted exactly once per applyAllAsync invocation, when every dirty domain's applyResult has been received.
ok is true iff every domain reported success. errors is a list of user-readable messages (one per failed domain). A domain that times out is named by its objectName when it has one, so give a domain a translated, human-readable objectName or none.
|
signal |
Emitted on every applying-state transition (false→true at the start of applyAllAsync, true→false when the last applyResult has landed).
UnsavedChangesFooter binds Save button text + enabled state to this.
| int PhosphorControl::ApplicationController::asyncBatchTimeoutMs | ( | ) | const |
Async-batch timeout in milliseconds, DefaultAsyncBatchTimeoutMs by default: generous for D-Bus round trips but tight enough to surface a wedged backend instead of pinning the chrome's "Saving…" state indefinitely.
Consumers that want faster feedback, or run longer migrations, can adjust it before the first applyAllAsync. Must be > 0.
| void PhosphorControl::ApplicationController::attachDomainToPage | ( | StagingDomain * | domain, |
| const QString & | pageId ) |
Count domain as part of page pageId: dirtyPageIds() lists the page while the domain is dirty, and resetCurrentPage() on the page resets the domain too.
Used for a section another module adds to the page (a module extension). Refused, with a warning, for a domain that is not tracked (registerDomain) or a page that is not registered. The attachment lasts while the domain is tracked.
| bool PhosphorControl::ApplicationController::bindPage | ( | const QString & | id, |
| PageController * | controller, | ||
| const QUrl & | qmlSource ) |
Give the already-registered page id its real controller and QML source (PageRegistry::bindPage, which also refuses a controller whose id() is not id), and track the controller like a registered page.
The controller it replaces stops being tracked as a staging domain, since it no longer has a page; its QObject parent is left alone. A parentless controller is adopted on success only. Used when a control module loads into placeholder pages. Like PageRegistry::bindPage, an accepted bind also sets the page's PageRegistry::Entry::passesContext, so the page's QML must declare controller and settingsApp.
| bool PhosphorControl::ApplicationController::canGoBack | ( | ) | const |
Browser-style navigation history over currentPageId.
Every ORDINARY page change (sidebar click, deep link, CLI –page, gotoPrevious/NextPage, …) pushes the page it left onto the back stack and clears the forward stack — exactly the browser model. goBack() / goForward() move along the recorded trail without re-recording (they shuffle entries between the two stacks instead). Both return the page id landed on, or an empty string when there was nowhere to go. Stale entries are skipped and dropped: pages the current simple/advanced tier hides (landing on one lets the app's mode gate bounce the user to a different page, so the returned id would not match where they ended up). The cap of MaxHistoryEntries applies when RECORDING ordinary navigation — the oldest entry falls off first; a history move only transfers an entry between the two stacks, so it conserves total depth.
| bool PhosphorControl::ApplicationController::canGoForward | ( | ) | const |
| void PhosphorControl::ApplicationController::clearExtensionProvider | ( | const QObject * | owner | ) |
Remove the provider if owner installed it.
A no-op otherwise. It does not notify, since only the owner knows which pages had sections.
| void PhosphorControl::ApplicationController::clearNavigationHook | ( | const QObject * | owner | ) |
Remove the hook if owner installed it. A no-op otherwise.
| QString PhosphorControl::ApplicationController::currentPageId | ( | ) | const |
|
signal |
|
signal |
| QStringList PhosphorControl::ApplicationController::dirtyPageIds | ( | ) | const |
Ids of every registered page whose controller, or a domain attached to it (attachDomainToPage), is still dirty.
Read on demand: nothing notifies when one page's dirty state changes.
Lives here rather than as a QML walk over allPagesData() + controller(id): isDirty() is NOT Q_INVOKABLE (StagingDomain exposes it only through the dirty Q_PROPERTY, deliberately, to avoid a duplicate metaobject entry), so the QML form threw a TypeError on the first non-null controller. The lib has no QML test harness, so that shipped green and silently swallowed the apply-on-close failure path it fed. In C++ the compiler checks it and a unit test covers it.
|
slot |
|
slot |
Symmetric to applyAllAsync; emits discardAllComplete(ok, errors).
|
signal |
Symmetric to applyAllComplete for discardAllAsync.
|
signal |
Symmetric to applyingChanged for discardAllAsync.
|
signal |
The sections added to page pageId changed (notifyExtensionsChanged).
| QVariantList PhosphorControl::ApplicationController::extensionsFor | ( | const QString & | pageId, |
| const QString & | slot ) const |
The sections other modules add to slot slot of page pageId, for the QML ExtensionSlot.
Each entry is a map with id, moduleId, moduleName, name and modulePageId (a page of the section's module, empty when it has none in the sidebar), plus either qmlSource and domain for a section that can be shown, or error for one that cannot, with moduleFailed set when the reason is that its module did not load and disabledAfterCrash when that module is turned off after a crash. Empty without an extension provider.
|
slot |
Force-reset the async-batch state machine to idle.
Recovers from the (hopefully-impossible) case where a domain failed to emit applyResult/discardResult AND its destroyed() signal also never fired (e.g. an exception unwound past Qt's child-deletion). Emits the matching *Complete signal with ok=false so observers are notified. QML escape hatch.
| QString PhosphorControl::ApplicationController::goBack | ( | ) |
| QString PhosphorControl::ApplicationController::goForward | ( | ) |
| QString PhosphorControl::ApplicationController::gotoNextPage | ( | ) |
| QString PhosphorControl::ApplicationController::gotoPreviousPage | ( | ) |
Navigate to the previous / next navigable page (one with a qmlSource) in the order the sidebar draws the tree (PageRegistry::pagesInTreeOrder).
The current page is skipped; the list wraps at boundaries. Returns the id we landed on, or an empty string if there's nowhere to go, including when the current page is the only navigable one.
When the current page is not in the navigable list (e.g. unset at startup or pointing at a non-navigable category), gotoPrevious wraps to the last page and gotoNext wraps to the first.
|
signal |
Emitted when canGoBack / canGoForward may have flipped (shared NOTIFY for both properties — they always change together or not at all from the QML binding system's perspective).
| bool PhosphorControl::ApplicationController::isApplying | ( | ) | const |
True while applyAllAsync is in flight (at least one domain's applyResult hasn't landed yet).
UnsavedChangesFooter binds to this to swap "Save" → "Saving…" with the action disabled.
| bool PhosphorControl::ApplicationController::isDirty | ( | ) | const |
| bool PhosphorControl::ApplicationController::isDiscarding | ( | ) | const |
True while discardAllAsync is in flight — symmetric with isApplying.
|
nodiscard |
True iff domain is tracked: a registered page's controller or a registered headless domain.
| void PhosphorControl::ApplicationController::notifyExtensionsChanged | ( | const QString & | pageId | ) |
Tell ExtensionSlots on page pageId to read extensionsFor again.
| QStringList PhosphorControl::ApplicationController::parentChainFor | ( | const QString & | id | ) | const |
Walk the parent chain from the registered entry for id to the top level.
Returns the chain ordered root-first, EXCLUDING id itself. Used by consumers to restore sidebar drill state at startup (e.g. given a restored activePage of "snapping-behavior", produces ["snapping"]).
|
signal |
Emitted when the deep-link pending anchor is set or cleared.
PageHost listens so an already-current page reveals immediately.
| bool PhosphorControl::ApplicationController::registerDomain | ( | StagingDomain * | domain | ) |
Register a headless staging domain (no sidebar entry).
Used for cross-cutting state shared across multiple pages. Returns false, with a warning, for a null domain, one from another thread, or one already tracked (a registered page's controller is tracked already).
| void PhosphorControl::ApplicationController::registerPage | ( | PageController * | page, |
| const QString & | parentId, | ||
| const QString & | title, | ||
| const QUrl & | qmlSource, | ||
| const QString & | iconSource = QString(), | ||
| bool | isCollapsible = false, | ||
| bool | hasDividerAfter = false, | ||
| PageRegistry::PageVisibility | visibility = PageRegistry::PageVisibility::Always, | ||
| const QString & | counterpartId = QString() ) |
Register a page in the sidebar.
The page is also tracked as a staging domain. The controller's parent is reassigned to this ApplicationController if it has none.
When isCollapsible is true the sidebar renders this entry as an inline-expandable category header rather than a drill-down target — children appear indented under it instead of replacing the list.
When hasDividerAfter is true the sidebar draws a horizontal divider line immediately after this row (suppressed while a search filter is active). Used for visual grouping of long flat sections.
visibility declares the page's simple/advanced tier at registration — the canonical way to classify a page (see PageRegistry::PageVisibility). counterpartId names the page's other-mode equivalent for mode-flip redirects (see PageRegistry::Entry::counterpartId); it may reference a page registered later, so it is stored unvalidated.
| PageRegistry * PhosphorControl::ApplicationController::registry | ( | ) | const |
|
slot |
| void PhosphorControl::ApplicationController::setAsyncBatchTimeoutMs | ( | int | ms | ) |
| void PhosphorControl::ApplicationController::setCurrentPageId | ( | const QString & | id | ) |
| bool PhosphorControl::ApplicationController::setExtensionProvider | ( | QObject * | owner, |
| ExtensionProvider | provider ) |
Install provider on behalf of owner.
There is one provider: while another live owner holds it, this warns and returns false. The provider is never called once owner is destroyed.
| bool PhosphorControl::ApplicationController::setNavigationHook | ( | QObject * | owner, |
| NavigationHook | hook ) |
Install hook on behalf of owner.
There is one hook: while another live owner holds it, this warns and returns false. The hook is never called once owner is destroyed.
| void PhosphorControl::ApplicationController::setPendingAnchor | ( | const QString & | pageId, |
| const QString & | anchor ) |
Deep-link reveal latch (generic — every settings app built on this shell gets deep-link-to-anchor for free).
setPendingAnchor stashes a transient "reveal this anchor once its page is built and current" request. PageHost consumes it via takePendingAnchor() when the target page's Loader is ready + current (and immediately when the page is already active, via the pendingAnchorChanged signal), then invokes the page item's revealAnchor(anchor) contract. The pending request is cleared automatically when navigation moves to a different page (discard-on-navigate-away), so a never-reached deep link never fires on the wrong page. The fragment is NOT part of currentPageId — page identity stays fragment-free so existing id comparisons are unaffected.
| QString PhosphorControl::ApplicationController::takePendingAnchor | ( | const QString & | pageId | ) |
Returns + clears the pending anchor iff it targets pageId; otherwise returns an empty string (consume-once).
| QString PhosphorControl::ApplicationController::titlePathFor | ( | const QString & | id | ) | const |
The page's title path: every ancestor title root-first, then the page's own title, joined with titlePathSeparator(), which search results use too.
A bare title is not enough to name a page in a toast once several pages share one. Unknown ids and ancestors with no title contribute nothing, so an unregistered id yields an empty string.
|
static |
The separator between the titles of a page path (U+203A), shared by titlePathFor and SearchController's result breadcrumbs.