PhosphorZones Namespace Reference

Namespaces
namespace	GeometryUtils
namespace	LayoutUtils
	Zone/layout primitive utilities — pure Layout / Zone operations.
namespace	TemplateJsonKeys
	The template JSON keys other modules have to spell.
namespace	ZoneDefaults
	Library-owned default values for zone presentation.
namespace	ZoneJsonKeys
	JSON wire-format keys for zone & layout serialisation.

Classes
struct	AssignmentEntry
	Explicit per-context assignment entry storing every mode's payload. More...
struct	CombinedAssignmentKey
	Triple-axis key for the Combined-context batch API. More...
struct	ComputedZoneGeometry
struct	ContextGapOverride
	Per-context gap override resolved from rules. More...
struct	ContextOverlayOverride
	Per-context overlay-property overrides resolved from window-rule actions. More...
struct	ContextResolveKey
	Lookup key for the LayoutRegistry context-resolver caches. More...
struct	ContextScrollingParams
	Per-context scrolling parameter overrides resolved from context rules. More...
struct	ContextTilingParams
	Per-context autotile parameter overrides resolved from context rules. More...
class	IZoneDetection
	Pure-query subset of zone detection — read-only geometry lookup. More...
class	IZoneDetector
	Abstract interface for zone detection + highlight lifecycle. More...
class	IZoneLayoutRegistry
	Enumeration + mutation surface for the in-memory zone-layout catalog. More...
class	Layout
	Represents a collection of zones that form a layout. More...
struct	LayoutAssignmentKey
	Key for layout assignment (screen + desktop + activity) More...
struct	LayoutComputeResult
class	LayoutComputeService
class	LayoutFactory
class	LayoutRegistry
	Manual zone-layout registry + per-context assignment store. More...
class	LayoutSettingsStore
	Persists per-layout SETTINGS in a sidecar, keyed by layout UUID, separately from the structural layout files. More...
struct	LayoutSnapshot
class	LayoutWorker
class	ScrollingTemplate
	A scrolling screen's first-class sizing template. More...
struct	ScrollingTemplateColumn
	One column of a scrolling template's seed blueprint. More...
class	ScrollingTemplateSource
	ILayoutSource over a ScrollingTemplateStore — the third card family beside manual zone layouts and autotile algorithms. More...
class	ScrollingTemplateSourceFactory
	Factory + registrar anchor, mirroring ZonesLayoutSourceFactory. More...
class	ScrollingTemplateStore
	Load/save store for scrolling templates. More...
class	Zone
	Represents a single zone within a layout. More...
struct	ZoneDetectionResult
	Result of zone detection. More...
class	ZoneDetector
	Efficient zone detection for window snapping. More...
class	ZoneHighlighter
	Manages zone highlighting state. More...
class	ZonesLayoutSource
	ILayoutSource adapter wrapping an IZoneLayoutRegistry. More...
class	ZonesLayoutSourceFactory
	Factory for ZonesLayoutSource. More...
struct	ZoneSnapshot

Enumerations
enum class	LayoutCategory { Manual = 0 , Autotile = 1 , ScrollingTemplate = 2 }
	Category for layout type. More...
enum class	ZoneField {   None = 0 , Name = 1 << 0 , Appearance = 1 << 1 , Minimal = None ,   Full = Name | Appearance }
	Flags controlling which zone fields to include in conversion (OCP-compliant) More...
enum class	ZoneGeometryMode { Relative = 0 , Fixed = 1 }
	Geometry mode for individual zones. More...

Functions
size_t	qHash (const LayoutAssignmentKey &key, size_t seed=0)
QString	modeToWireString (AssignmentEntry::Mode mode)
	Canonical wire-string for an AssignmentEntry::Mode.
std::optional< AssignmentEntry::Mode >	modeFromWireString (const QString &wire)
	Inverse of modeToWireString.
QList< AssignmentEntry::Mode >	allModes ()
	Iteration order for every AssignmentEntry::Mode value.
size_t	qHash (const ContextResolveKey &key, size_t seed=0) noexcept
size_t	qHash (const CombinedAssignmentKey &key, size_t seed=0) noexcept
PHOSPHORZONES_EXPORT PhosphorLayout::LayoutPreview	previewFromScrollingTemplate (const ScrollingTemplate &templ, bool verticalAxis=false)
	Project a native scrolling template into the shared LayoutPreview shape: the blueprint columns (or, for a vocabulary-only template, its preset widths) become band zones laid along the strip axis, so the shared thumbnail renderer draws a strip snapshot with no template-specific code.
PHOSPHORZONES_EXPORT void	ensureScrollingTemplateSourceProviderLinked ()
	Linker anchor — reference from every composition root that expects the self-registered provider (see ZonesLayoutSourceFactory's rationale).
PHOSPHORZONES_EXPORT PhosphorLayout::LayoutPreview	previewFromLayout (PhosphorZones::Layout *layout, const QSize &canvas={})
	Convert a single Layout into a renderer-ready LayoutPreview.
PHOSPHORZONES_EXPORT void	ensureZonesLayoutSourceProviderLinked ()
	Anchor symbol that forces the translation unit owning the static LayoutSourceProviderRegistrar for this provider to be linked in.

Variables
constexpr QLatin1String	NoScrollingTemplate {"none"}
	Reserved value of AssignmentEntry::scrollingTemplateLayout meaning "this context explicitly uses NO scrolling template", as opposed to an empty field, which means "not chosen here" and inherits the configured default template.
constexpr QLatin1String	NoSnappingLayout {"none"}
	Reserved value of AssignmentEntry::snappingLayout meaning "this context explicitly uses NO snapping layout", as opposed to an empty field, which means "not chosen here" and falls back to the registry-wide default layout.
constexpr QLatin1String	NoTilingAlgorithm {"none"}
	Reserved value of AssignmentEntry::tilingAlgorithm meaning "this context explicitly uses NO tiling algorithm": the context stays in Autotile mode but nothing tiles there — windows float.
constexpr qreal	MinTemplateFraction = 0.05
	Smallest fraction of the work area a template may express, mirroring the scroll engine's PhosphorScrollEngine::MinColumnWidthFraction (ScrollTypes.h).
constexpr int	MaxTemplateColumns = 16
	Most blueprint columns a template may carry, mirroring the scroll engine's kMaxTemplateEntries (enginelimits.h) the same hand-written way MinTemplateFraction mirrors its floor.
constexpr int	DefaultWidthKindProportion = 0
	The engine's DefaultWidthKind wire values, mirrored the same hand-written way MinTemplateFraction mirrors its floor: this library deliberately does not depend on phosphor-scroll-engine, so the vocabulary is repeated by documented value and is append-only on both sides.
constexpr int	DefaultWidthKindFixed = 1
constexpr int	DefaultWidthKindClientDecides = 2
constexpr int	DefaultWidthKindPreset = 3
constexpr qreal	FractionDedupeEpsilon = 0.01
	Two preset stops closer together than this are the same stop: the normalization dedupe drops the later one.

Enumeration Type Documentation

LayoutCategory

enum class PhosphorZones::LayoutCategory

strong

Category for layout type.

QML Note: Passed as int to QML. Values: 0 = Manual, 1 = Autotile, 2 = ScrollingTemplate.

Enumerator
Manual	Traditional zone-based layout.
Autotile	Dynamic auto-tiling algorithm.
ScrollingTemplate	Native scrolling template (preview family only)

ZoneField

enum class PhosphorZones::ZoneField

strong

Flags controlling which zone fields to include in conversion (OCP-compliant)

These flags allow callers to request minimal or full zone data without duplicating conversion logic. Use Minimal for preview thumbnails, Full for overlay rendering.

Enumerator
None
Name	Include zone name.
Appearance	Include colors, opacities, border properties.
Minimal	Id, ZoneNumber, RelativeGeometry only (for previews)
Full	All fields (for overlay rendering)

ZoneGeometryMode

enum class PhosphorZones::ZoneGeometryMode

strong

Geometry mode for individual zones.

Relative: 0.0–1.0 normalized coordinates (default, resolution-independent). Fixed: Absolute pixel coordinates relative to reference screen origin.

Owned by phosphor-zones because it's a per-zone shape; the former Phosphor-side using-alias in src/core/ was removed when the decoupling sweep landed — all callers now reference PhosphorZones::ZoneGeometryMode directly.

Enumerator
Relative
Fixed

Function Documentation

allModes()

QList< AssignmentEntry::Mode > PhosphorZones::allModes ( )

inline

Iteration order for every AssignmentEntry::Mode value.

The order doubles as the UI tab order (Snapping first, Autotile second, Scrolling last). Returns a QList<Mode> so range-for over modes is a one-liner — a consumer's bulk save/reset paths and its settings-page builders loop over this instead of hand-coding the {Snapping, Autotile, ...} pair literally. Adding a Mode in the enum and extending this list is all that is required to fan out every (Mode, Family)-keyed routine.

ensureScrollingTemplateSourceProviderLinked()

PHOSPHORZONES_EXPORT void PhosphorZones::ensureScrollingTemplateSourceProviderLinked

(

)

Linker anchor — reference from every composition root that expects the self-registered provider (see ZonesLayoutSourceFactory's rationale).

ensureZonesLayoutSourceProviderLinked()

PHOSPHORZONES_EXPORT void PhosphorZones::ensureZonesLayoutSourceProviderLinked

(

)

Anchor symbol that forces the translation unit owning the static LayoutSourceProviderRegistrar for this provider to be linked in.

Under SHARED builds (today's default) every TU of the loaded library has its static initialisers run, so this anchor is a no-op. The function exists so that STATIC builds + linker GC (--gc-sections, --as-needed) can't drop zoneslayoutsourcefactory.cpp silently — at which point the static registrar never runs and the bundle ships without the zones provider. Composition-root glue (buildStandardLayoutSourceBundle) calls this once during bundle wiring. The body is an empty no-op; only the symbol reference matters. See the @todo(plugin-compositor) note in PhosphorLayoutApi/LayoutSourceProviderRegistry.h.

modeFromWireString()

std::optional< AssignmentEntry::Mode > PhosphorZones::modeFromWireString ( const QString &  wire )

inline

Inverse of modeToWireString.

Returns std::nullopt for an unrecognised token — callers must treat that as a load failure (drop the rule / use the default). NEVER coerce an unknown token to a default mode: a typo would silently re-route a disable rule from "this engine only" to "all engines off".

modeToWireString()

QString PhosphorZones::modeToWireString ( AssignmentEntry::Mode  mode )

inline

Canonical wire-string for an AssignmentEntry::Mode.

The wire vocabulary lives next to the enum so every persister/consumer (rule store via ContextRuleBridge::makeDisableRule, KCM debugging, D-Bus enums) reads from one source of truth. Adding a new mode means extending this switch and modeFromWireString together. NEVER rename an existing token — the rule store records them verbatim and a rename would orphan every persisted disable rule.

previewFromLayout()

PHOSPHORZONES_EXPORT PhosphorLayout::LayoutPreview PhosphorZones::previewFromLayout	(	PhosphorZones::Layout *	layout,
		const QSize &	canvas = {}
	)

Convert a single Layout into a renderer-ready LayoutPreview.

Pure projection — no Qt object lifecycle, no signals. Manual layouts have a fixed shape, so the windowCount param from ILayoutSource is ignored here. Provided as a free function so consumers that already hold a Layout* can build a preview without going through ILayoutSource.

canvas (optional) — reference geometry used when projecting zones that were authored in fixed-pixel mode. When empty (the default), the projection falls back to Layout::lastRecalcGeometry(), which holds whichever screen most recently triggered a recalc — fine for caller topologies with a single monitor, but stale if two different screens share a Layout* and query their previews in alternation. Passing the caller's own canvas makes the projection deterministic per-call.

previewFromScrollingTemplate()

PHOSPHORZONES_EXPORT PhosphorLayout::LayoutPreview PhosphorZones::previewFromScrollingTemplate	(	const ScrollingTemplate &	templ,
		bool	verticalAxis = false
	)

Project a native scrolling template into the shared LayoutPreview shape: the blueprint columns (or, for a vocabulary-only template, its preset widths) become band zones laid along the strip axis, so the shared thumbnail renderer draws a strip snapshot with no template-specific code.

isScrollingTemplate marks the family.

verticalAxis picks the axis the bands run along. False (the default) lays full-HEIGHT bands left to right, the shape a horizontal strip adopts. True lays full-WIDTH bands top to bottom, which is what the engine actually produces on a screen whose strip runs vertically — a card drawn the other way depicts a shape that screen will never show. A template carries no axis of its own (a column vocabulary is fractions along the strip, whichever way it runs), so the axis comes from the SCREEN, and the callers that have no screen in scope (the screen-agnostic management catalogue, this file's ILayoutSource) keep the horizontal default deliberately.

PRECONDITION: templ is normalized (every template the store hands out is, and ScrollingTemplate::fromJson normalizes on parse). The width fallback for a template with neither blueprint columns nor a preset vocabulary relies on normalize() having demoted a Preset default kind that has nothing to index; an un-normalized Preset kind previews at half width rather than at the width it names.

qHash() [1/3]

size_t PhosphorZones::qHash ( const CombinedAssignmentKey &  key, size_t  seed = 0  )

inlinenoexcept

qHash() [2/3]

size_t PhosphorZones::qHash ( const ContextResolveKey &  key, size_t  seed = 0  )

inlinenoexcept

qHash() [3/3]

size_t PhosphorZones::qHash ( const LayoutAssignmentKey &  key, size_t  seed = 0  )

inline

Variable Documentation

DefaultWidthKindClientDecides

constexpr int PhosphorZones::DefaultWidthKindClientDecides = 2

inlineconstexpr

DefaultWidthKindFixed

constexpr int PhosphorZones::DefaultWidthKindFixed = 1

inlineconstexpr

DefaultWidthKindPreset

constexpr int PhosphorZones::DefaultWidthKindPreset = 3

inlineconstexpr

DefaultWidthKindProportion

constexpr int PhosphorZones::DefaultWidthKindProportion = 0

inlineconstexpr

The engine's DefaultWidthKind wire values, mirrored the same hand-written way MinTemplateFraction mirrors its floor: this library deliberately does not depend on phosphor-scroll-engine, so the vocabulary is repeated by documented value and is append-only on both sides.

Every site in this library that compares or coerces a default-width kind reads these rather than a bare integer.

FractionDedupeEpsilon

constexpr qreal PhosphorZones::FractionDedupeEpsilon = 0.01

inlineconstexpr

Two preset stops closer together than this are the same stop: the normalization dedupe drops the later one.

Exported to authoring UIs through EditorTemplateModel::scrollingConstants() (the layout editor's template mode) and SettingsController::scrollingConstants() (the settings pages) so both mirror the store exactly.

MaxTemplateColumns

constexpr int PhosphorZones::MaxTemplateColumns = 16

inlineconstexpr

Most blueprint columns a template may carry, mirroring the scroll engine's kMaxTemplateEntries (enginelimits.h) the same hand-written way MinTemplateFraction mirrors its floor.

The engine truncates a pushed blueprint at this many entries, so columns beyond it could never seed anything, and it keeps the same number out of a pushed preset vocabulary. Normalization drops the excess from all three lists, and the value is exported to the settings UI through SettingsController::scrollingConstants().

MinTemplateFraction

constexpr qreal PhosphorZones::MinTemplateFraction = 0.05

inlineconstexpr

Smallest fraction of the work area a template may express, mirroring the scroll engine's PhosphorScrollEngine::MinColumnWidthFraction (ScrollTypes.h).

The dependency runs the other way, so the value is repeated here the same way ConfigDefaults and PhosphorRules repeat it. Every place this library clamps or floors a template fraction reads this constant.

NoScrollingTemplate

constexpr QLatin1String PhosphorZones::NoScrollingTemplate {"none"}

inlineconstexpr

Reserved value of AssignmentEntry::scrollingTemplateLayout meaning "this context explicitly uses NO scrolling template", as opposed to an empty field, which means "not chosen here" and inherits the configured default template.

See that field for why the third state exists.

A deliberately non-UUID word. Every consumer that RESOLVES the field to a template parses it with QUuid::fromString, so a resolver that has not been taught about the token degrades to a null UUID, which is the no-template answer anyway. That safety argument covers behaviour and NOT presentation: a reader that displays the field without parsing shows the word itself, so any new display surface has to translate it (see the ones that already do, below).

Only two places may TRANSLATE it, both in LayoutRegistry: the resolver (scrollingTemplateForContext), because it is the one that would otherwise substitute the default, and the write choke point (assignScrollingTemplate), because its UUID normalization would flatten the token back to empty on the way in. Everywhere else passes it through.

The pass-through sites are not few, so treat this as the list to check when the spelling changes rather than as a claim that nothing else knows it: the D-Bus setter skips its UUID validation for it (a refusal, not a rewrite), the purge writes it when a Scrolling context's template is deleted, assignScrollingTemplate writes it for an id that does not resolve, scrollingTemplateExplicitlyNone and scrollingDisplayIdForContext test it, the unified layout list builds the picker's None row around it and sorts on it, the daemon's UnifiedLayoutController carries it through its apply and current-selection answers, the picker's apply path compares against it, the daemon's scrolling signal path and the rules label renderer each translate it for display, and the QML files listed on NoSnappingLayout hardcode the literal against this declaration — the three sentinels share one spelling, so they share one QML risk list.

Only that last group is at RISK from a respelling. Every C++ site above reaches the token through this constant, so they follow a change here for free; they are listed because the doc is a map of who reasons about the third state, not only of who would break.

NoSnappingLayout

constexpr QLatin1String PhosphorZones::NoSnappingLayout {"none"}

inlineconstexpr

Reserved value of AssignmentEntry::snappingLayout meaning "this context explicitly uses NO snapping layout", as opposed to an empty field, which means "not chosen here" and falls back to the registry-wide default layout.

The same third state NoScrollingTemplate carved out for templates, for the same reason: with only empty and a UUID, a context could never opt out of the default layout every cascade miss resolves to.

The same deliberately non-UUID word, with the same safety argument: every consumer that RESOLVES the field parses it with QUuid::fromString, so an untaught resolver degrades it to a null id — the no-layout answer anyway. Only two places TRANSLATE it: the resolver (LayoutRegistry::layoutForScreen, which short-circuits to nullptr BEFORE its defaultLayout() fallback) and the classification choke point (fromLayoutId below, whose non-UUID arm passes the word through untouched — deliberate, and load-bearing: normalizing it would flatten "explicitly none" back to "inherit"). Pass-through sites to check on a respelling: the D-Bus setAssignmentEntry validator and canonicalizer skip it, the purge writes it when a Snapping context's layout is deleted, the unified layout list builds the picker's None row around the word and sorts on it, UnifiedLayoutController's apply and display-id paths carry it, and the rules label/pill renderers translate it for display.

The QML sites are the ones actually AT RISK from a respelling, because they spell the literal rather than reaching this constant. All of them, for all three sentinels:

• LayoutPickerContent (the overlay picker's None card)
• MonitorStatePage (per-screen selectors and staging)
• MonitorModePreviews (the per-mode preview captions)
• ActionParamEditors (the rule action's own None row)
• ActionListView (that action's read-only pill)
• LayoutComboBox (the shared selector's None wording)
• LayoutContextMenu (Clear Default — these WRITE the word)
• ProfileRow (the profile-diff cell)
• TilingAlgorithmPage (the cleared-default guard and caption)
• TilingSimplePage (the same guard on the simple page)
• AlgorithmPreviewCard (the cleared-default combo caption) Keep this list current: it is the only safety net for those sites, and the two LayoutContextMenu occurrences are the highest-stakes of them because they author the stored value rather than merely reading it.

NoTilingAlgorithm

constexpr QLatin1String PhosphorZones::NoTilingAlgorithm {"none"}

inlineconstexpr

Reserved value of AssignmentEntry::tilingAlgorithm meaning "this context explicitly uses NO tiling algorithm": the context stays in Autotile mode but nothing tiles there — windows float.

An empty field still means "not chosen here", which inherits the configured default algorithm. The wire id for the state is "autotile:none" (makeAutotileId over this word), so it rides every existing string path.

Unlike the two UUID fields there is no parse-degrade safety net — bare algorithm ids are words already — so the consumers that resolve an algorithm gate on the token explicitly: the daemon's updateEngineScreens skips the screen (the tile engine itself never sees the word; its setAlgorithm coerces unknown ids to the registry default, which is the exact opposite of what the opt-out means). The D-Bus setAssignmentEntry validator exempts it from the registry existence check, and the same display surfaces listed on NoSnappingLayout translate it.