A tiling algorithm backed by a user-provided Luau script. More...

#include <phosphor-tiles/include/PhosphorTiles/LuauTileAlgorithm.h>

Inheritance diagram for PhosphorTiles::LuauTileAlgorithm:

Public Member Functions
	LuauTileAlgorithm (const QString &filePath, std::shared_ptr< PhosphorScripting::LuauWatchdog > watchdog=nullptr, QObject *parent=nullptr)
	Owned-engine ctor: creates an isolated, per-engine-capped VM for this script.

	LuauTileAlgorithm (const QString &filePath, std::shared_ptr< PhosphorScripting::LuauEngine > sharedEngine, std::shared_ptr< PhosphorScripting::LuauWatchdog > watchdog, QObject *parent=nullptr)
	Shared-engine ctor: loads this script's module into `sharedEngine` (an already init+prelude+sandbox'd VM) instead of creating its own.

	~LuauTileAlgorithm () override

bool	isValid () const
	Whether the script loaded and exposes a callable tile() function.

QString	filePath () const

QString	id () const
	Optional algorithm id declared in metadata (empty if unset).

void	setUserScript (bool isUser)

QString	name () const override
	Human-readable name of the algorithm.

QString	description () const override
	Description of the algorithm behavior.

QVector< QRect >	calculateZones (const TilingParams &params) const override
	Calculate zone geometries for N windows.

int	masterZoneIndex () const override
	Get the index of the "master" zone (if applicable)

bool	supportsMasterCount () const override
	Check if algorithm supports variable master count.

bool	supportsSplitRatio () const override
	Check if algorithm supports split ratio adjustment.

qreal	defaultSplitRatio () const override
	Get default split ratio for this algorithm.

int	minimumWindows () const override
	Get minimum number of windows for meaningful tiling.

int	defaultMaxWindows () const override
	Get default maximum number of windows for this algorithm.

bool	producesOverlappingZones () const override
	Whether this algorithm intentionally produces overlapping zones.

bool	supportsMinSizes () const noexcept override
	Whether this algorithm supports per-window minimum size constraints.

bool	supportsMemory () const noexcept override
	Whether this algorithm maintains persistent state across retiles.

QString	zoneNumberDisplay () const noexcept override
	How zone numbers should be displayed in previews.

bool	centerLayout () const override
	Whether this algorithm uses a center layout.

bool	isScripted () const noexcept override
	Whether this algorithm is a user-provided scripted algorithm.

bool	isUserScript () const noexcept override
	Whether this scripted algorithm was loaded from a user directory.

void	prepareTilingState (TilingState *state) const override
	Prepare the TilingState before calculateZones() is called.

bool	supportsLifecycleHooks () const noexcept override
	Whether this algorithm implements any lifecycle hooks.

void	onWindowAdded (TilingState *state, int windowIndex) override
	Called when a window is added to the tiling before retile.

void	onWindowRemoved (TilingState *state, int windowIndex) override
	Called when a window is removed from the tiling before retile.

bool	supportsResizeHook () const noexcept override
	Whether this algorithm reacts to interactive window resizes.

void	onWindowResized (TilingState *state, const ResizeEvent &resize) override
	Called when a tiled window finished an interactive resize.

bool	supportsScriptState () const noexcept override
	Whether this algorithm persists an opaque per-screen script-state bag (TilingState::scriptState) across retiles and sessions.

bool	supportsCustomParams () const noexcept override
	Whether this algorithm declares custom parameters.

QVariantList	customParamDefList () const override
	Get custom parameter definitions as a QVariantList for QML.

bool	hasCustomParam (const QString &name) const override
	Check if a named custom parameter is declared by this algorithm.

Public Member Functions inherited from PhosphorTiles::TilingAlgorithm
	TilingAlgorithm (QObject *parent=nullptr)

	~TilingAlgorithm () override=default

	TilingAlgorithm (const TilingAlgorithm &)=delete

TilingAlgorithm &	operator= (const TilingAlgorithm &)=delete

void	setAppIdResolver (std::function< QString(const QString &)> resolver)
	Inject a resolver that maps an opaque instance id to its live app class.

std::function< QString(const QString &)>	appIdResolver () const
	Access the current resolver.

QString	registryId () const
	The id this algorithm is registered under.

void	setRegistryId (const QString &id)
	Registry-internal setter.

Static Public Member Functions
static std::shared_ptr< PhosphorScripting::LuauEngine >	createSandboxedEngine (std::shared_ptr< PhosphorScripting::LuauWatchdog > watchdog, QString *error=nullptr)
	Build a sandboxed VM with the `pluau` standard library installed and frozen, ready for loadModule().

Additional Inherited Members
Signals inherited from PhosphorTiles::TilingAlgorithm
void	configurationChanged ()
	Emitted when algorithm parameters change.

Static Protected Member Functions inherited from PhosphorTiles::TilingAlgorithm
static QRect	innerRect (const QRect &screenGeometry, int outerGap)
	Compute the usable area after subtracting uniform outer gap from screen edges.

static QRect	innerRect (const QRect &screenGeometry, const EdgeGaps &gaps)
	Compute the usable area after subtracting per-side outer gaps from screen edges.

Protected Attributes inherited from PhosphorTiles::TilingAlgorithm
std::function< QString(const QString &)>	m_appIdResolver

QString	m_registryId

Detailed Description

A tiling algorithm backed by a user-provided Luau script.

The script's module is loaded into a PhosphorScripting::LuauEngine whose pluau standard library has been injected and frozen. There are two engine modes, chosen by which constructor is used:

Owned engine (single-arg ctor): the instance creates and owns its own sandboxed VM. Used for untrusted user scripts so each gets its own fault-isolated heap and per-engine memory cap — a runaway script can only exhaust its own VM.
Shared engine (engine-arg ctor): the module is loaded into a VM shared across many trusted bundled scripts, so the ~per-VM baseline + 42 KB pluau prelude is paid once instead of per script. The shared engine is held by shared_ptr so a deferred-deleted algorithm keeps it alive until its own teardown (which releases just this algorithm's module handle).

The script is a Luau chunk that returns a module table, conventionally via pluau.algorithm{...}:

return pluau.algorithm {
    metadata = { id = "columns", name = "Columns" },
    tile = function(ctx) return ctx.area:columns(ctx.count, ctx.gap) end,
}

Params/state are marshalled to/from the script as nested QVariant structures; no Lua types cross into this class. Runaway scripts are bounded by a shared LuauWatchdog.

Not thread-safe — all calls must occur on the owning (main) thread.

Constructor & Destructor Documentation

◆ LuauTileAlgorithm() [1/2]

PhosphorTiles::LuauTileAlgorithm::LuauTileAlgorithm	(	const QString &	filePath,
		std::shared_ptr< PhosphorScripting::LuauWatchdog >	watchdog = `nullptr`,
		QObject *	parent = `nullptr`
	)

explicit

Owned-engine ctor: creates an isolated, per-engine-capped VM for this script.

Use for untrusted user scripts.

◆ LuauTileAlgorithm() [2/2]

PhosphorTiles::LuauTileAlgorithm::LuauTileAlgorithm	(	const QString &	filePath,
		std::shared_ptr< PhosphorScripting::LuauEngine >	sharedEngine,
		std::shared_ptr< PhosphorScripting::LuauWatchdog >	watchdog,
		QObject *	parent = `nullptr`
	)

Shared-engine ctor: loads this script's module into sharedEngine (an already init+prelude+sandbox'd VM) instead of creating its own.

Use for trusted bundled scripts so the VM baseline + prelude are shared. The engine must be created via createSandboxedEngine().

◆ ~LuauTileAlgorithm()

PhosphorTiles::LuauTileAlgorithm::~LuauTileAlgorithm ( )

override

Member Function Documentation

◆ calculateZones()

QVector< QRect > PhosphorTiles::LuauTileAlgorithm::calculateZones ( const TilingParams & params ) const

overridevirtual

Calculate zone geometries for N windows.

This is the core algorithm method. Given tiling parameters (window count, screen geometry, state, gaps, min sizes), generate zone rectangles.

Parameters

params Tiling parameters (see TilingParams)

Returns: Vector of zone geometries in absolute pixel coordinates

Note: The returned vector should have exactly params.windowCount elements. For windowCount == 0, return an empty vector. For windowCount == 1, typically return a single zone inset by outerGap.

Implements PhosphorTiles::TilingAlgorithm.

◆ centerLayout()

bool PhosphorTiles::LuauTileAlgorithm::centerLayout ( ) const

overridevirtual

Whether this algorithm uses a center layout.

Center layout algorithms (e.g., ThreeColumn, CenteredMaster) have a center column whose width is controlled by the split ratio. The UI labels the ratio/count controls as "Center" instead of "Master".

Returns: true if this is a center layout algorithm (default: false)

Reimplemented from PhosphorTiles::TilingAlgorithm.

◆ createSandboxedEngine()

static std::shared_ptr< PhosphorScripting::LuauEngine > PhosphorTiles::LuauTileAlgorithm::createSandboxedEngine	(	std::shared_ptr< PhosphorScripting::LuauWatchdog >	watchdog,
		QString *	error = `nullptr`
	)

static

Build a sandboxed VM with the pluau standard library installed and frozen, ready for loadModule().

Returns nullptr (and sets error) on failure. Shared by the owned-engine path and the shared-engine factory in ScriptedAlgorithmLoader so the prelude is loaded identically.

◆ customParamDefList()

QVariantList PhosphorTiles::LuauTileAlgorithm::customParamDefList ( ) const

overridevirtual

Get custom parameter definitions as a QVariantList for QML.

Each entry is a QVariantMap with keys: name, type, defaultValue, description, minValue, maxValue, enumOptions (as applicable).

Returns: List of param definition maps, or empty if none declared

Reimplemented from PhosphorTiles::TilingAlgorithm.

◆ defaultMaxWindows()

int PhosphorTiles::LuauTileAlgorithm::defaultMaxWindows ( ) const

overridevirtual

Get default maximum number of windows for this algorithm.

Used as the initial value of the "Max Windows" slider in the KCM, and reported as the zone count on layout previews (LayoutGridDelegate, zone selector). The slider resets to this value when switching algorithms.

Returns: Default max window count for this algorithm (typically 4-10)

Reimplemented from PhosphorTiles::TilingAlgorithm.

◆ defaultSplitRatio()

qreal PhosphorTiles::LuauTileAlgorithm::defaultSplitRatio ( ) const

overridevirtual

Get default split ratio for this algorithm.

Used when creating initial tiling state.

Returns: Default ratio (0.0-1.0), typically 0.5-0.6

Reimplemented from PhosphorTiles::TilingAlgorithm.

◆ description()

QString PhosphorTiles::LuauTileAlgorithm::description ( ) const

overridevirtual

Description of the algorithm behavior.

Returns: Description suitable for tooltips/help text

Implements PhosphorTiles::TilingAlgorithm.

◆ filePath()

QString PhosphorTiles::LuauTileAlgorithm::filePath ( ) const

◆ hasCustomParam()

bool PhosphorTiles::LuauTileAlgorithm::hasCustomParam ( const QString & name ) const

overridevirtual

Check if a named custom parameter is declared by this algorithm.

Lighter-weight alternative to customParamDefList() for filtering stale params on the retile hot path — avoids QVariantList/QVariantMap allocation.

Parameters

name	Parameter name to check

Returns: true if the algorithm declares a

Parameters

with this name

Reimplemented from PhosphorTiles::TilingAlgorithm.

◆ id()

QString PhosphorTiles::LuauTileAlgorithm::id ( ) const

Optional algorithm id declared in metadata (empty if unset).

◆ isScripted()

bool PhosphorTiles::LuauTileAlgorithm::isScripted ( ) const

overridevirtualnoexcept

Whether this algorithm is a user-provided scripted algorithm.

Scripted algorithms are loaded from Luau (.luau) files at runtime. Used by the UI to group algorithms into "Built-in" vs "Custom" sections.

Returns: true if this is a LuauTileAlgorithm (default: false)

Reimplemented from PhosphorTiles::TilingAlgorithm.

◆ isUserScript()

bool PhosphorTiles::LuauTileAlgorithm::isUserScript ( ) const

overridevirtualnoexcept

Whether this scripted algorithm was loaded from a user directory.

System-installed scripts (shipped with Phosphor) return false. User-created scripts in ~/.local/share/plasmazones/algorithms/ return true. Non-scripted algorithms always return false.

Returns: true if loaded from user's writable data directory (default: false)

Reimplemented from PhosphorTiles::TilingAlgorithm.

◆ isValid()

bool PhosphorTiles::LuauTileAlgorithm::isValid ( ) const

Whether the script loaded and exposes a callable tile() function.

◆ masterZoneIndex()

int PhosphorTiles::LuauTileAlgorithm::masterZoneIndex ( ) const

overridevirtual

Get the index of the "master" zone (if applicable)

For algorithms with a master/stack concept, this returns the index of the primary window zone. Used for "focus master" and "swap with master".

Returns: Master zone index (0-based), or -1 if no master concept

Reimplemented from PhosphorTiles::TilingAlgorithm.

◆ minimumWindows()

int PhosphorTiles::LuauTileAlgorithm::minimumWindows ( ) const

overridevirtual

Get minimum number of windows for meaningful tiling.

Some algorithms (like Three Column) need a minimum number of windows to produce a sensible layout.

Returns: Minimum window count (typically 1)

Reimplemented from PhosphorTiles::TilingAlgorithm.

◆ name()

QString PhosphorTiles::LuauTileAlgorithm::name ( ) const

overridevirtual

Human-readable name of the algorithm.

Returns: Algorithm name (e.g., "Master + Stack", "BSP")

Implements PhosphorTiles::TilingAlgorithm.

◆ onWindowAdded()

void PhosphorTiles::LuauTileAlgorithm::onWindowAdded	(	TilingState *	state,
		int	windowIndex
	)

overridevirtual

Called when a window is added to the tiling before retile.

Algorithms can use this to update internal state (e.g., BSP tree insertion) instead of rebuilding from scratch in calculateZones().

Unlike calculateZones() (which receives a const TilingState*), lifecycle hooks receive a mutable pointer so algorithms can update internal structures (e.g., split trees) incrementally.

Parameters

state	Current tiling state (mutable for tree updates)
windowIndex	Index where the window was inserted

Reimplemented from PhosphorTiles::TilingAlgorithm.

◆ onWindowRemoved()

void PhosphorTiles::LuauTileAlgorithm::onWindowRemoved	(	TilingState *	state,
		int	windowIndex
	)

overridevirtual

Called when a window is removed from the tiling before retile.

The window is still present in state when this hook fires; it will be removed immediately after the hook returns. This means state->tiledWindowCount() still includes the departing window. Algorithms should use windowIndex to identify the departing window but must not assume the tiled window list will remain unchanged after the call. Hooks must NOT reorder or mutate the tiled window list — the engine relies on list stability for the subsequent removal.

Unlike calculateZones() (which receives a const TilingState*), lifecycle hooks receive a mutable pointer so algorithms can update internal structures (e.g., split trees) incrementally.

Parameters

state	Current tiling state (window still present, count not yet decremented)
windowIndex	Index the window occupied before removal

Reimplemented from PhosphorTiles::TilingAlgorithm.

◆ onWindowResized()

void PhosphorTiles::LuauTileAlgorithm::onWindowResized	(	TilingState *	state,
		const ResizeEvent &	resize
	)

overridevirtual

Called when a tiled window finished an interactive resize.

Only invoked for non-memory algorithms that return true from supportsResizeHook. The algorithm may mutate state (e.g. write TilingState::scriptState) so the immediately-following retile lays the windows out to honour the resize. Default no-op.

Parameters

state	Mutable tiling state (window list unchanged by the resize)
resize	Which window/edges moved, with old/new frames

Reimplemented from PhosphorTiles::TilingAlgorithm.

◆ prepareTilingState()

void PhosphorTiles::LuauTileAlgorithm::prepareTilingState ( TilingState * state ) const

overridevirtual

Prepare the TilingState before calculateZones() is called.

Memory-based algorithms override this to lazily create their SplitTree. The engine calls this unconditionally before calculateZones(), removing the need for concrete algorithm casts in the engine.

The method is const on the algorithm (it doesn't mutate algorithm state) but mutates the TilingState argument — the engine owns that mutation.

Parameters

state TilingState to prepare (may be nullptr, implementations must check)

Reimplemented from PhosphorTiles::TilingAlgorithm.

◆ producesOverlappingZones()

bool PhosphorTiles::LuauTileAlgorithm::producesOverlappingZones ( ) const

overridevirtual

Whether this algorithm intentionally produces overlapping zones.

Algorithms like Cascade, Stair, and Monocle overlap zones by design. When true, the post-layout enforceMinSizes pass is skipped to avoid removeRectOverlaps destroying the intended layout.

Returns: true if zones intentionally overlap (default: false)

Reimplemented from PhosphorTiles::TilingAlgorithm.

◆ setUserScript()

void PhosphorTiles::LuauTileAlgorithm::setUserScript ( bool isUser )

◆ supportsCustomParams()

bool PhosphorTiles::LuauTileAlgorithm::supportsCustomParams ( ) const

overridevirtualnoexcept

Whether this algorithm declares custom parameters.

Algorithms that support custom parameters (e.g., scripted algorithms with

Parameters

declarations) return true. Used to avoid downcasting.

Returns: true if the algorithm has custom parameter definitions (default: false)

Reimplemented from PhosphorTiles::TilingAlgorithm.

◆ supportsLifecycleHooks()

bool PhosphorTiles::LuauTileAlgorithm::supportsLifecycleHooks ( ) const

overridevirtualnoexcept

Whether this algorithm implements any lifecycle hooks.

When true, the engine calls onWindowAdded/onWindowRemoved before the next calculateZones() call, giving the algorithm a chance to update internal state incrementally.

Returns: true if the algorithm defines lifecycle hooks (default: false)

Reimplemented from PhosphorTiles::TilingAlgorithm.

◆ supportsMasterCount()

bool PhosphorTiles::LuauTileAlgorithm::supportsMasterCount ( ) const

overridevirtual

Check if algorithm supports variable master count.

If true, the algorithm can handle multiple windows in the master area.

Returns: true if master count can be adjusted

Reimplemented from PhosphorTiles::TilingAlgorithm.

◆ supportsMemory()

bool PhosphorTiles::LuauTileAlgorithm::supportsMemory ( ) const

overridevirtualnoexcept

Whether this algorithm maintains persistent state across retiles.

Memory algorithms (like DwindleMemory) remember per-split ratios and tree structure. The UI shows an indicator for memory-enabled algorithms.

Returns: true if the algorithm uses a persistent SplitTree (default: false)

Reimplemented from PhosphorTiles::TilingAlgorithm.

◆ supportsMinSizes()

bool PhosphorTiles::LuauTileAlgorithm::supportsMinSizes ( ) const

overridevirtualnoexcept

Whether this algorithm supports per-window minimum size constraints.

Most algorithms respect the minSizes parameter. Algorithms that ignore it (e.g., Floating Center, Tatami) return false so the settings UI can disable min-size controls for them.

Returns: true if the algorithm honors minSizes (default: true)

Reimplemented from PhosphorTiles::TilingAlgorithm.

◆ supportsResizeHook()

bool PhosphorTiles::LuauTileAlgorithm::supportsResizeHook ( ) const

overridevirtualnoexcept

Whether this algorithm reacts to interactive window resizes.

When true, the engine calls onWindowResized for a non-tree algorithm after the user finishes resizing a tiled window, letting the algorithm record the adjustment (typically into TilingState::scriptState) before the follow-up retile. Tree/memory algorithms do not use this — the engine reflows their SplitTree directly. Default false.

Reimplemented from PhosphorTiles::TilingAlgorithm.

◆ supportsScriptState()

bool PhosphorTiles::LuauTileAlgorithm::supportsScriptState ( ) const

overridevirtualnoexcept

Whether this algorithm persists an opaque per-screen script-state bag (TilingState::scriptState) across retiles and sessions.

Scripted algorithms opt in via their metadata so the engine sanitizes and round-trips the bag (e.g. an aligned grid remembering column widths). Built-in algorithms do not use it. Used by the picker to surface a "remembers script state" filter/indicator. Default false.

Reimplemented from PhosphorTiles::TilingAlgorithm.

◆ supportsSplitRatio()

bool PhosphorTiles::LuauTileAlgorithm::supportsSplitRatio ( ) const

overridevirtual

Check if algorithm supports split ratio adjustment.

If true, the master/stack ratio can be dynamically adjusted.

Returns: true if split ratio can be adjusted

Reimplemented from PhosphorTiles::TilingAlgorithm.

◆ zoneNumberDisplay()

QString PhosphorTiles::LuauTileAlgorithm::zoneNumberDisplay ( ) const

overridevirtualnoexcept

How zone numbers should be displayed in previews.

Controls which zones show their number label in layout cards and previews. Values: "all" (default), "last", "first", "firstAndLast", "none"

Returns: Display mode string

Reimplemented from PhosphorTiles::TilingAlgorithm.

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

phosphor-tiles/include/PhosphorTiles/LuauTileAlgorithm.h

Phosphor Qt6 / Wayland library suite for window-management tools

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ LuauTileAlgorithm() [1/2]

◆ LuauTileAlgorithm() [2/2]

◆ ~LuauTileAlgorithm()

Member Function Documentation

◆ calculateZones()

◆ centerLayout()

◆ createSandboxedEngine()

◆ customParamDefList()

◆ defaultMaxWindows()

◆ defaultSplitRatio()

◆ description()

◆ filePath()

◆ hasCustomParam()

◆ id()

◆ isScripted()

◆ isUserScript()

◆ isValid()

◆ masterZoneIndex()

◆ minimumWindows()

◆ name()

◆ onWindowAdded()

◆ onWindowRemoved()

◆ onWindowResized()

◆ prepareTilingState()

◆ producesOverlappingZones()

◆ setUserScript()

◆ supportsCustomParams()

◆ supportsLifecycleHooks()

◆ supportsMasterCount()

◆ supportsMemory()

◆ supportsMinSizes()

◆ supportsResizeHook()

◆ supportsScriptState()

◆ supportsSplitRatio()

◆ zoneNumberDisplay()