PhosphorTiles::ScriptedHelpers Namespace Reference

JS builtin sources loaded from the :/builtins/ Qt resource at ScriptedAlgorithm::loadScript() time. More...

Classes
struct	CustomParamDef
	Definition of a custom algorithm parameter. More...
struct	ScriptMetadata
	Parsed script metadata from a JS-exported metadata object. More...

Functions
PHOSPHORTILES_EXPORT QVector< CustomParamDef >	parseCustomParamsFromJs (const QJSValue &jsCustomParams, const QString &filePath)
	Parse custom parameter definitions from a JS-exported customParams array.
PHOSPHORTILES_EXPORT ScriptMetadata	parseMetadataFromJs (const QJSValue &jsMetadata, const QString &filePath)
	Parse full algorithm metadata from a JS-exported metadata object.
QVector< QRect >	jsArrayToRects (const QJSValue &result, const QString &scriptId, int maxZones)
	Convert a JS array of {x, y, width, height} objects to QRects.
QVector< QRect >	clampZonesToArea (const QVector< QRect > &zones, const QRect &area, const QString &scriptId)
	Clamp zones to the given area, using full area as fallback for zones entirely outside.
QString	distributeWithGapsJs ()
	JS source for distributeWithGaps(total, count, gap) built-in helper.
QString	distributeWithMinSizesJs ()
	JS source for distributeWithMinSizes(total, count, gap, minDims) built-in helper.
QString	solveTwoPartJs ()
	JS source for solveTwoPart(contentDim, firstDim, secondDim, minFirst, minSecond) built-in helper.
QString	solveThreeColumnJs ()
	JS source for solveThreeColumn(...) built-in helper.
QString	cumulativeMinDimsJs ()
	JS source for computeCumulativeMinDims(windowCount, minSizes, innerGap) built-in helper.
QString	gracefulDegradationJs ()
	JS source for appendGracefulDegradation(zones, remaining, leftover, innerGap) built-in helper.
QString	dwindleLayoutJs ()
	JS source for dwindleLayout(area, count, splitRatio, innerGap, minSizes) built-in helper.
QString	extractMinDimsJs ()
	JS source for extractMinWidths(minSizes, count) and extractMinHeights(minSizes, count) helpers.
QString	interleaveStacksJs ()
	JS source for stack interleaving helpers shared by centered-master and three-column.
QString	applyPerWindowMinSizeJs ()
	JS source for applyPerWindowMinSize(w, h, minSizes, i) built-in helper.
QString	extractRegionMaxMinJs ()
	JS source for extractRegionMaxMin(minSizes, startIdx, endIdx, axis) built-in helper.
QString	fillAreaJs ()
	JS source for fillArea(area, count) built-in helper.
QString	masterStackLayoutJs ()
	JS source for masterStackLayout(area, count, gap, splitRatio, masterCount, minSizes, horizontal) helper.
QString	applyTreeGeometryJs ()
	JS source for applyTreeGeometry(node, rect, gap, _depth) built-in helper.
QString	lShapeLayoutJs ()
	JS source for lShapeLayout(area, count, gap, splitRatio, distribute, bottomWidth, rightHeight) helper.
QString	deckLayoutJs ()
	JS source for deckLayout(area, count, focusedFraction, horizontal) built-in helper.
QString	distributeEvenlyJs ()
	JS source for distributeEvenly(start, total, count, gap) built-in helper.
QString	equalColumnsLayoutJs ()
	JS source for equalColumnsLayout(area, count, gap, minSizes) built-in helper.
QString	fillRegionJs ()
	JS source for fillRegion(x, y, w, h, count) built-in helper.
QString	distributeWithOptionalMinsJs ()
	JS source for distributeWithOptionalMins(total, count, gap, minDims) built-in helper.
QString	threeColumnLayoutJs ()
	JS source for threeColumnLayout(area, count, gap, splitRatio, masterCount, minSizes) helper.
QString	clampSplitRatioJs ()
	JS source for clampSplitRatio(ratio) built-in helper.

Detailed Description

JS builtin sources loaded from the :/builtins/ Qt resource at ScriptedAlgorithm::loadScript() time.

Each helper below returns the source text of one builtin; the sandbox injects + freezes them before a user script runs.

Pre-injected JS globals available inside every builtin and user script

These constants are injected by ScriptedAlgorithmSandbox alongside the builtin functions and are in scope for every script. Keep this list in sync with the injection points in scriptedalgorithmjsbuiltins.cpp.

• PZ_MIN_ZONE_SIZE — integer, per-zone minimum dimension (pixels). Mirrors AutotileDefaults::MinZoneSize.
• PZ_MIN_SPLIT — float, lower bound for split ratios. Mirrors AutotileDefaults::MinSplitRatio.
• PZ_MAX_SPLIT — float, upper bound for split ratios. Mirrors AutotileDefaults::MaxSplitRatio.
• MAX_TREE_DEPTH — integer, recursion guard for tree-walking builtins (e.g. applyTreeGeometry). Mirrors AutotileDefaults::MaxRuntimeTreeDepth.

Builtin authors should prefer these names over re-introducing local constants, so values stay in exactly one place (the C++ defaults header).

Function Documentation

applyPerWindowMinSizeJs()

QString PhosphorTiles::ScriptedHelpers::applyPerWindowMinSizeJs

(

)

JS source for applyPerWindowMinSize(w, h, minSizes, i) built-in helper.

Applies per-window minimum size constraints from the minSizes array. Returns {w, h} with dimensions clamped to minimums. Loaded from Qt resource :/builtins/applyPerWindowMinSize.js

applyTreeGeometryJs()

QString PhosphorTiles::ScriptedHelpers::applyTreeGeometryJs

(

)

JS source for applyTreeGeometry(node, rect, gap, _depth) built-in helper.

Recursively computes zone rectangles from a binary split tree. Depth-limited to MAX_TREE_DEPTH (must match AutotileDefaults::MaxRuntimeTreeDepth). Loaded from Qt resource :/builtins/applyTreeGeometry.js

clampSplitRatioJs()

QString PhosphorTiles::ScriptedHelpers::clampSplitRatioJs

(

)

JS source for clampSplitRatio(ratio) built-in helper.

Clamps a ratio to [PZ_MIN_SPLIT, PZ_MAX_SPLIT]. Eliminates the repeated Math.max(PZ_MIN_SPLIT, Math.min(PZ_MAX_SPLIT, ratio)) pattern. Loaded from Qt resource :/builtins/clampSplitRatio.js

clampZonesToArea()

QVector< QRect > PhosphorTiles::ScriptedHelpers::clampZonesToArea	(	const QVector< QRect > &	zones,
		const QRect &	area,
		const QString &	scriptId
	)

Clamp zones to the given area, using full area as fallback for zones entirely outside.

Parameters

zones	Input zones from JS
area	Bounding area to clamp to
scriptId	Script identifier for warning messages

Returns

Vector of clamped QRects

cumulativeMinDimsJs()

QString PhosphorTiles::ScriptedHelpers::cumulativeMinDimsJs

(

)

JS source for computeCumulativeMinDims(windowCount, minSizes, innerGap) built-in helper.

Port of TilingAlgorithm::computeAlternatingCumulativeMinDims. Returns {minW: [], minH: []}. Loaded from Qt resource :/builtins/computeCumulativeMinDims.js

deckLayoutJs()

QString PhosphorTiles::ScriptedHelpers::deckLayoutJs

(

)

JS source for deckLayout(area, count, focusedFraction, horizontal) built-in helper.

Deck (monocle-with-peek) layout where the focused window takes a large fraction and background windows peek from the remainder. Loaded from Qt resource :/builtins/deckLayout.js

distributeEvenlyJs()

QString PhosphorTiles::ScriptedHelpers::distributeEvenlyJs

(

)

JS source for distributeEvenly(start, total, count, gap) built-in helper.

Distributes items evenly along a 1D axis with gaps. Returns array of {pos, size} objects with the last item absorbing rounding remainder. Loaded from Qt resource :/builtins/distributeEvenly.js

distributeWithGapsJs()

QString PhosphorTiles::ScriptedHelpers::distributeWithGapsJs

(

)

JS source for distributeWithGaps(total, count, gap) built-in helper.

Port of TilingAlgorithm::distributeWithGaps. Deducts (count-1)*gap from total, distributes remainder evenly. Returns array of int sizes. Loaded from Qt resource :/builtins/distributeWithGaps.js

distributeWithMinSizesJs()

QString PhosphorTiles::ScriptedHelpers::distributeWithMinSizesJs

(

)

JS source for distributeWithMinSizes(total, count, gap, minDims) built-in helper.

Port of TilingAlgorithm::distributeWithMinSizes. Complex distribution with proportional fallback when unsatisfiable, unconstrained-surplus optimization. Returns array of int sizes. Loaded from Qt resource :/builtins/distributeWithMinSizes.js

distributeWithOptionalMinsJs()

QString PhosphorTiles::ScriptedHelpers::distributeWithOptionalMinsJs

(

)

JS source for distributeWithOptionalMins(total, count, gap, minDims) built-in helper.

Wraps the repeated ternary pattern that branches on minDims.length, delegating to distributeWithGaps when empty or distributeWithMinSizes otherwise. Loaded from Qt resource :/builtins/distributeWithOptionalMins.js

dwindleLayoutJs()

QString PhosphorTiles::ScriptedHelpers::dwindleLayoutJs

(

)

JS source for dwindleLayout(area, count, splitRatio, innerGap, minSizes) built-in helper.

Port of DwindleAlgorithm::calculateZones core logic (without outer gap/ single-window handling). Returns array of zone objects. Loaded from Qt resource :/builtins/dwindleLayout.js

equalColumnsLayoutJs()

QString PhosphorTiles::ScriptedHelpers::equalColumnsLayoutJs

(

)

JS source for equalColumnsLayout(area, count, gap, minSizes) built-in helper.

Equal-width columns layout with gap-aware distribution. Used as a standalone layout (columns algorithm) and as a fallback when other algorithms produce degenerate zones. Loaded from Qt resource :/builtins/equalColumnsLayout.js

extractMinDimsJs()

QString PhosphorTiles::ScriptedHelpers::extractMinDimsJs

(

)

JS source for extractMinWidths(minSizes, count) and extractMinHeights(minSizes, count) helpers.

Convenience functions that extract per-element minimum width/height values from a minSizes array. Returns empty array when minSizes is empty, allowing callers to branch between distributeWithGaps and distributeWithMinSizes. Loaded from Qt resource :/builtins/extractMinDims.js

extractRegionMaxMinJs()

QString PhosphorTiles::ScriptedHelpers::extractRegionMaxMinJs

(

)

JS source for extractRegionMaxMin(minSizes, startIdx, endIdx, axis) built-in helper.

Scans a region of the minSizes array for the maximum minimum dimension on the given axis ('w' or 'h'). Used by master-stack layouts. Loaded from Qt resource :/builtins/extractRegionMaxMin.js

fillAreaJs()

QString PhosphorTiles::ScriptedHelpers::fillAreaJs

(

)

JS source for fillArea(area, count) built-in helper.

Creates an array of identical zones covering the full area. Used as a degenerate-screen fallback. Loaded from Qt resource :/builtins/fillArea.js

fillRegionJs()

QString PhosphorTiles::ScriptedHelpers::fillRegionJs

(

)

JS source for fillRegion(x, y, w, h, count) built-in helper.

Creates an array of identical zones covering the same region. Used as a degenerate-gap fallback when gaps exceed available space. Unlike fillArea(), this takes explicit x/y/w/h for partial regions. Loaded from Qt resource :/builtins/fillRegion.js

gracefulDegradationJs()

QString PhosphorTiles::ScriptedHelpers::gracefulDegradationJs

(

)

JS source for appendGracefulDegradation(zones, remaining, leftover, innerGap) built-in helper.

Port of TilingAlgorithm::appendGracefulDegradation. Modifies zones array in place. Loaded from Qt resource :/builtins/appendGracefulDegradation.js

interleaveStacksJs()

QString PhosphorTiles::ScriptedHelpers::interleaveStacksJs

(

)

JS source for stack interleaving helpers shared by centered-master and three-column.

Provides buildStackIsLeft(), interleaveMinWidths(), interleaveMinHeights(), and assignInterleavedStacks() for DRY left/right column interleaving. Loaded from Qt resource :/builtins/interleaveStacks.js

jsArrayToRects()

QVector< QRect > PhosphorTiles::ScriptedHelpers::jsArrayToRects	(	const QJSValue &	result,
		const QString &	scriptId,
		int	maxZones
	)

Convert a JS array of {x, y, width, height} objects to QRects.

Parameters

result	JS value (should be an array)
scriptId	Script identifier for warning messages
maxZones	Maximum number of zones to accept

Returns

Vector of validated QRects

lShapeLayoutJs()

QString PhosphorTiles::ScriptedHelpers::lShapeLayoutJs

(

)

JS source for lShapeLayout(area, count, gap, splitRatio, distribute, bottomWidth, rightHeight) helper.

L-shaped tiling with master in top-left and secondary zones along right/bottom edges. Uses injected PZ_MIN_SPLIT/PZ_MAX_SPLIT globals. Loaded from Qt resource :/builtins/lShapeLayout.js

masterStackLayoutJs()

QString PhosphorTiles::ScriptedHelpers::masterStackLayoutJs

(

)

JS source for masterStackLayout(area, count, gap, splitRatio, masterCount, minSizes, horizontal) helper.

Shared implementation for master-stack and wide layouts. horizontal=false: master left, stack right. horizontal=true: master top, stack bottom. Loaded from Qt resource :/builtins/masterStackLayout.js

parseCustomParamsFromJs()

PHOSPHORTILES_EXPORT QVector< CustomParamDef > PhosphorTiles::ScriptedHelpers::parseCustomParamsFromJs	(	const QJSValue &	jsCustomParams,
		const QString &	filePath
	)

Parse custom parameter definitions from a JS-exported customParams array.

parseMetadataFromJs()

PHOSPHORTILES_EXPORT ScriptMetadata PhosphorTiles::ScriptedHelpers::parseMetadataFromJs	(	const QJSValue &	jsMetadata,
		const QString &	filePath
	)

Parse full algorithm metadata from a JS-exported metadata object.

solveThreeColumnJs()

QString PhosphorTiles::ScriptedHelpers::solveThreeColumnJs

(

)

JS source for solveThreeColumn(...) built-in helper.

Port of TilingAlgorithm::solveThreeColumnWidths. Uses injected constants PZ_MIN_ZONE_SIZE, PZ_MIN_SPLIT, PZ_MAX_SPLIT. Returns object with leftWidth, centerWidth, rightWidth, leftX, centerX, rightX. Loaded from Qt resource :/builtins/solveThreeColumn.js

solveTwoPartJs()

QString PhosphorTiles::ScriptedHelpers::solveTwoPartJs

(

)

JS source for solveTwoPart(contentDim, firstDim, secondDim, minFirst, minSecond) built-in helper.

Port of TilingAlgorithm::solveTwoPartMinSizes. Returns {first, second}. Loaded from Qt resource :/builtins/solveTwoPart.js

threeColumnLayoutJs()

QString PhosphorTiles::ScriptedHelpers::threeColumnLayoutJs

(

)

JS source for threeColumnLayout(area, count, gap, splitRatio, masterCount, minSizes) helper.

Shared implementation for centered-master and three-column layouts. masterCount=1: three-column behavior. masterCount>1: centered-master behavior. Loaded from Qt resource :/builtins/threeColumnLayout.js