PhosphorZones::ScrollingTemplate Class Reference

A scrolling screen's first-class sizing template. More...

#include <phosphor-zones/include/PhosphorZones/ScrollingTemplate.h>

Public Member Functions
bool	isValid () const
bool	normalize ()
	Clamp every fraction into legal range, drop degenerate entries, sort and dedupe the preset lists, and cap the blueprint AND both preset vocabularies at MaxTemplateColumns.
QJsonObject	toJson () const
bool	operator== (const ScrollingTemplate &) const =default

Static Public Member Functions
static QList< qreal >	normalizePresetList (QList< qreal > values)
	The preset-list half of normalize() (floor at MinTemplateFraction, ascending sort, dedupe within FractionDedupeEpsilon, cap at MaxTemplateColumns), exposed so authoring surfaces can enforce the same contract at their own write boundaries instead of mirroring the rules by hand.
static ScrollingTemplate	fromJson (const QJsonObject &json)
	Parses and normalizes.

Public Attributes
QUuid	id
QString	name
QString	description
	Optional user-facing description (plain prose).
QList< ScrollingTemplateColumn >	columns
	Seed blueprint, ordered left to right.
int	defaultColumnWidthKind = DefaultWidthKindPreset
	Default column width for columns beyond the blueprint, spelled in the engine's settings-channel trio (see class doc for the kind values).
qreal	defaultColumnWidthValue = 0.5
	Proportion fraction / Fixed px.
int	defaultColumnWidthPresetIndex = 1
	Kind Preset: index into presetColumnWidths.
int	defaultColumnDisplay = 0
	Mirrors ColumnDisplay: 0 Normal, 1 Tabbed.
QList< qreal >	presetColumnWidths
	Cycle stops for the preset width/height shortcuts.
QList< qreal >	presetWindowHeights
bool	isSystem = false
	True when the loaded file came from a read-only system location (bundled starter).
bool	hasSystemOrigin = false
	True for a USER copy whose id also exists in a system directory (the shadow the isSystem doc describes).
QString	sourcePath
	Absolute path of the file this template was loaded from.

Detailed Description

A scrolling screen's first-class sizing template.

Scrolling's own template object — the peer of snapping's zone Layout and autotile's algorithm. It describes how a scrolling screen's strip behaves:

• columns is the SEED BLUEPRINT: as a strip grows, each new column takes the next UNSPENT entry's width and display. An entry is spent once a column has taken it, so closing a column does not hand its entry back to the next window that opens, and a column the user re-shaped by hand keeps that shape. The seed restarts when the strip empties or the screen is given a different blueprint. The blueprint never resizes an existing column (a template change affects only columns created after it — the niri principle that opening or configuring never reshapes what you have). The engine holds the consumption cursor; see PhosphorScrollEngine::ScrollState::blueprintCursor.
• The default width trio and defaultColumnDisplay answer for columns BEYOND the blueprint. They mirror the engine's settings-channel wire values (DefaultWidthKind: 0 Proportion, 1 Fixed, 2 ClientDecides, 3 Preset) so the daemon push writes them into the existing per-screen keys verbatim.
• presetColumnWidths / presetWindowHeights are the cycle stops the preset shortcuts step through while this template is assigned; they replace the compiled defaults WHOLESALE (no merge).

Version-free additive is the PARSER's policy: an absent key reads as its default, so an older build loads a newer file, matching the layout JSON policy. The authoring schema (data/schemas/scrolling-template.schema.json) is deliberately CLOSED so a typo in a bundled file fails validation, and a later axis (per-column scroll direction, overflow policies) adds a field to the parser and the schema in the same change.

Assignment rides the existing cascade: AssignmentEntry's scrollingTemplateLayout field stores this object's id (QUuid-shaped, same canonical braced form as layout ids).

Member Function Documentation

fromJson()

static ScrollingTemplate PhosphorZones::ScrollingTemplate::fromJson ( const QJsonObject &  json )

static

Parses and normalizes.

Returns an invalid template (isValid() false) on a malformed document.

isValid()

bool PhosphorZones::ScrollingTemplate::isValid ( ) const

inline

normalize()

bool PhosphorZones::ScrollingTemplate::normalize

(

)

Clamp every fraction into legal range, drop degenerate entries, sort and dedupe the preset lists, and cap the blueprint AND both preset vocabularies at MaxTemplateColumns.

The preset cap applies after the sort and dedupe, so what survives is the smallest N distinct stops, matching what the engine keeps out of the same pushed list. A Preset default width with an empty preset vocabulary (the bare-defaults shape) demotes to Proportion, so the width trio the daemon pushes as a unit is always self-consistent. Returns false when the template is unusable even after normalization (invalid id / empty name).

normalizePresetList()

static QList< qreal > PhosphorZones::ScrollingTemplate::normalizePresetList ( QList< qreal >  values )

static

The preset-list half of normalize() (floor at MinTemplateFraction, ascending sort, dedupe within FractionDedupeEpsilon, cap at MaxTemplateColumns), exposed so authoring surfaces can enforce the same contract at their own write boundaries instead of mirroring the rules by hand.

operator==()

bool PhosphorZones::ScrollingTemplate::operator== ( const ScrollingTemplate &  ) const

default

toJson()

QJsonObject PhosphorZones::ScrollingTemplate::toJson

(

)

const

Member Data Documentation

columns

QList<ScrollingTemplateColumn> PhosphorZones::ScrollingTemplate::columns

Seed blueprint, ordered left to right.

May be empty: a template can carry only vocabularies and defaults.

defaultColumnDisplay

int PhosphorZones::ScrollingTemplate::defaultColumnDisplay = 0

Mirrors ColumnDisplay: 0 Normal, 1 Tabbed.

defaultColumnWidthKind

int PhosphorZones::ScrollingTemplate::defaultColumnWidthKind = DefaultWidthKindPreset

Default column width for columns beyond the blueprint, spelled in the engine's settings-channel trio (see class doc for the kind values).

defaultColumnWidthPresetIndex

int PhosphorZones::ScrollingTemplate::defaultColumnWidthPresetIndex = 1

Kind Preset: index into presetColumnWidths.

defaultColumnWidthValue

qreal PhosphorZones::ScrollingTemplate::defaultColumnWidthValue = 0.5

Proportion fraction / Fixed px.

description

QString PhosphorZones::ScrollingTemplate::description

Optional user-facing description (plain prose).

hasSystemOrigin

bool PhosphorZones::ScrollingTemplate::hasSystemOrigin = false

True for a USER copy whose id also exists in a system directory (the shadow the isSystem doc describes).

Not serialized; stamped by the store at load and on a shadowing save. Lets the UI mark an edited bundled template as "the built-in one still exists underneath".

id

QUuid PhosphorZones::ScrollingTemplate::id

isSystem

bool PhosphorZones::ScrollingTemplate::isSystem = false

True when the loaded file came from a read-only system location (bundled starter).

Not serialized; stamped by the store at load. A user edit shadows the bundled file with a same-id user copy, and deleting that copy resurfaces the bundled original.

name

QString PhosphorZones::ScrollingTemplate::name

presetColumnWidths

QList<qreal> PhosphorZones::ScrollingTemplate::presetColumnWidths

Cycle stops for the preset width/height shortcuts.

Fractions 0..1, ascending after normalization.

presetWindowHeights

QList<qreal> PhosphorZones::ScrollingTemplate::presetWindowHeights

sourcePath

QString PhosphorZones::ScrollingTemplate::sourcePath

Absolute path of the file this template was loaded from.

Not serialized; stamped by the store at load (empty for a template that was never persisted). Feeds the open-in-text-editor affordance.

---

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

• phosphor-zones/include/PhosphorZones/ScrollingTemplate.h