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

Abstract base for anything that holds staged user changes pending an Apply. More...

#include <PhosphorControl/StagingDomain.h>

Inheritance diagram for PhosphorControl::StagingDomain:
[legend]

Public Slots

virtual void apply ()=0
 Persist staged changes to the backing store.
virtual void discard ()=0
 Drop staged changes; reload from the backing store.
virtual void resetToDefaults ()
 Load factory defaults into the staged area.

Signals

void dirtyChanged ()
void applyResult (bool ok, const QString &error)
 Async-completion signal — REQUIRED for use with ApplicationController::applyAllAsync.
void discardResult (bool ok, const QString &error)
 Companion to applyResult for discard() — separate signal so the chrome can wire distinct user-visible states.

Public Member Functions

 StagingDomain (QObject *parent=nullptr)
 ~StagingDomain () override
virtual bool isDirty () const =0

Detailed Description

Abstract base for anything that holds staged user changes pending an Apply.

A staging domain is the unit ApplicationController orchestrates: it asks each domain whether it is dirty, then dispatches applyAll() / discardAll() across all registered domains in one transaction.

The two intended implementations are:

  • PageController — a domain that also has a QML page (a row in the sidebar).
  • Headless domains — cross-cutting state that spans multiple pages (e.g. per-screen assignment maps) and is registered directly with the ApplicationController without a sidebar entry.

Implementers must emit dirtyChanged() whenever isDirty() flips. The ApplicationController connects to it to recompute the global dirty flag.

Constructor & Destructor Documentation

◆ StagingDomain()

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

◆ ~StagingDomain()

PhosphorControl::StagingDomain::~StagingDomain ( )
override

Member Function Documentation

◆ apply

virtual void PhosphorControl::StagingDomain::apply ( )
pure virtualslot

Persist staged changes to the backing store.

ApplicationController only invokes apply() on domains whose isDirty() returns true, so implementations may assume there is staged work to do. Must not rely on side effects ("stamp last-applied timestamp", "fire notification") that need to run even when clean.

Implemented in PhosphorControl::ModulePlaceholderPage.

◆ applyResult

void PhosphorControl::StagingDomain::applyResult ( bool ok,
const QString & error )
signal

Async-completion signal — REQUIRED for use with ApplicationController::applyAllAsync.

The async batch driver tracks per-domain completion through this signal: pending counter only ticks down on applyResult, so a domain that never emits parks the chrome's "Saving…" state until the 60 s batch timeout fires.

Synchronous domains MUST emit applyResult(true, {}) at the end of apply() (and similarly discardResult in discard()). Async domains (D-Bus call, file I/O on a worker thread, etc.) emit when the out-of-band work finishes, with the success bool reflecting the daemon / worker outcome.

The bool return on apply() is too coarse for this shape — it pins success at function return but cannot signal a later daemon error or a partial-failure the user can retry. applyResult is what the chrome actually waits on.

ok true on a clean apply / discard. error user-readable error message (empty when ok). Caller owns translation context — emit translated text.

◆ dirtyChanged

void PhosphorControl::StagingDomain::dirtyChanged ( )
signal

◆ discard

virtual void PhosphorControl::StagingDomain::discard ( )
pure virtualslot

Drop staged changes; reload from the backing store.

ApplicationController only invokes discard() on dirty domains — same side-effect-free contract as apply().

Implemented in PhosphorControl::ModulePlaceholderPage.

◆ discardResult

void PhosphorControl::StagingDomain::discardResult ( bool ok,
const QString & error )
signal

Companion to applyResult for discard() — separate signal so the chrome can wire distinct user-visible states.

Same emit requirements as applyResult: synchronous domains MUST emit discardResult(true, {}) at end-of-discard().

◆ isDirty()

virtual bool PhosphorControl::StagingDomain::isDirty ( ) const
pure virtual

◆ resetToDefaults

virtual void PhosphorControl::StagingDomain::resetToDefaults ( )
virtualslot

Load factory defaults into the staged area.

Caller still needs apply() to persist. Default implementation is a no-op for domains that do not support resetting to defaults.


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