Abstract base class for tiling algorithms. More...

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

Inheritance diagram for PhosphorTiles::TilingAlgorithm:

Signals
void	configurationChanged ()
	Emitted when algorithm parameters change.

Public Member Functions
	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.

virtual QString	name () const =0
	Human-readable name of the algorithm.

virtual QString	description () const =0
	Description of the algorithm behavior.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Static Protected Member Functions
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
std::function< QString(const QString &)>	m_appIdResolver

QString	m_registryId

Detailed Description

Abstract base class for tiling algorithms.

Each algorithm generates zone geometries based on:

Number of windows to tile
Screen geometry (available area)
Algorithm-specific parameters (master ratio, gaps, etc.)

Zone geometries are returned as absolute pixel coordinates matching the provided screen geometry. This matches KWin's setFrameGeometry() API.

Subclasses must implement:

name(), description() for UI display
calculateZones() for the actual algorithm

Optionally override capability methods to indicate support for:

Master count adjustment
Split ratio adjustment

Note: Thread Safety: All algorithms are stateless — their const public methods can be called concurrently on the same instance. The TilingState parameter must not be modified during the call.

Constructor & Destructor Documentation

◆ TilingAlgorithm() [1/2]

PhosphorTiles::TilingAlgorithm::TilingAlgorithm ( QObject * parent = nullptr )

explicit

◆ ~TilingAlgorithm()

PhosphorTiles::TilingAlgorithm::~TilingAlgorithm ( )

overridedefault

◆ TilingAlgorithm() [2/2]

PhosphorTiles::TilingAlgorithm::TilingAlgorithm ( const TilingAlgorithm & )

delete

Member Function Documentation

◆ appIdResolver()

std::function< QString(const QString &)> PhosphorTiles::TilingAlgorithm::appIdResolver ( ) const

inline

Access the current resolver.

Returns a no-op (empty-string) resolver if none has been injected.

◆ calculateZones()

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

pure virtual

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.

Implemented in PhosphorTiles::LuauTileAlgorithm.

◆ centerLayout()

virtual bool PhosphorTiles::TilingAlgorithm::centerLayout ( ) const

virtual

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 in PhosphorTiles::LuauTileAlgorithm.

◆ configurationChanged

void PhosphorTiles::TilingAlgorithm::configurationChanged ( )

signal

Emitted when algorithm parameters change.

Connect to this signal to trigger retiling when algorithm configuration is modified at runtime.

◆ customParamDefList()

virtual QVariantList PhosphorTiles::TilingAlgorithm::customParamDefList ( ) const

virtual

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 in PhosphorTiles::LuauTileAlgorithm.

◆ defaultMaxWindows()

virtual int PhosphorTiles::TilingAlgorithm::defaultMaxWindows ( ) const

virtual

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 in PhosphorTiles::LuauTileAlgorithm.

◆ defaultSplitRatio()

virtual qreal PhosphorTiles::TilingAlgorithm::defaultSplitRatio ( ) const

virtual

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 in PhosphorTiles::LuauTileAlgorithm.

◆ description()

virtual QString PhosphorTiles::TilingAlgorithm::description ( ) const

pure virtual

Description of the algorithm behavior.

Returns: Description suitable for tooltips/help text

Implemented in PhosphorTiles::LuauTileAlgorithm.

◆ hasCustomParam()

virtual bool PhosphorTiles::TilingAlgorithm::hasCustomParam ( const QString & name ) const

virtual

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 in PhosphorTiles::LuauTileAlgorithm.

◆ innerRect() [1/2]

static QRect PhosphorTiles::TilingAlgorithm::innerRect	(	const QRect &	screenGeometry,
		const EdgeGaps &	gaps
	)

staticprotected

Compute the usable area after subtracting per-side outer gaps from screen edges.

Parameters

screenGeometry	Full screen rectangle
gaps	Per-side gap values

Returns: Inset rectangle (clamped to at least 1x1)

◆ innerRect() [2/2]

static QRect PhosphorTiles::TilingAlgorithm::innerRect	(	const QRect &	screenGeometry,
		int	outerGap
	)

staticprotected

Compute the usable area after subtracting uniform outer gap from screen edges.

Parameters

screenGeometry	Full screen rectangle
outerGap	Gap at each edge in pixels

Returns: Inset rectangle (clamped to at least 1x1)

◆ isScripted()

virtual bool PhosphorTiles::TilingAlgorithm::isScripted ( ) const

virtualnoexcept

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 in PhosphorTiles::LuauTileAlgorithm.

◆ isUserScript()

virtual bool PhosphorTiles::TilingAlgorithm::isUserScript ( ) const

virtualnoexcept

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 in PhosphorTiles::LuauTileAlgorithm.

◆ masterZoneIndex()

virtual int PhosphorTiles::TilingAlgorithm::masterZoneIndex ( ) const

virtual

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 in PhosphorTiles::LuauTileAlgorithm.

◆ minimumWindows()

virtual int PhosphorTiles::TilingAlgorithm::minimumWindows ( ) const

virtual

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 in PhosphorTiles::LuauTileAlgorithm.

◆ name()

virtual QString PhosphorTiles::TilingAlgorithm::name ( ) const

pure virtual

Human-readable name of the algorithm.

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

Implemented in PhosphorTiles::LuauTileAlgorithm.

◆ onWindowAdded()

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

virtual

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 in PhosphorTiles::LuauTileAlgorithm.

◆ onWindowRemoved()

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

virtual

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 in PhosphorTiles::LuauTileAlgorithm.

◆ onWindowResized()

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

virtual

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 in PhosphorTiles::LuauTileAlgorithm.

◆ operator=()

TilingAlgorithm & PhosphorTiles::TilingAlgorithm::operator= ( const TilingAlgorithm & )

delete

◆ prepareTilingState()

virtual void PhosphorTiles::TilingAlgorithm::prepareTilingState ( TilingState * state ) const

virtual

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 in PhosphorTiles::LuauTileAlgorithm.

◆ producesOverlappingZones()

virtual bool PhosphorTiles::TilingAlgorithm::producesOverlappingZones ( ) const

virtual

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 in PhosphorTiles::LuauTileAlgorithm.

◆ registryId()

QString PhosphorTiles::TilingAlgorithm::registryId ( ) const

inline

The id this algorithm is registered under.

Populated by AlgorithmRegistry::registerAlgorithm at registration time and unset when the algorithm is removed. Empty for algorithms that exist but aren't currently registered (fixture stubs, transient instances). Lets callers that have only a TilingAlgorithm* recover the id without the O(N) reverse lookup through the registry.

◆ setAppIdResolver()

void PhosphorTiles::TilingAlgorithm::setAppIdResolver ( std::function< QString(const QString &)> resolver )

inline

Inject a resolver that maps an opaque instance id to its live app class.

Used by algorithms that need per-window class info (currently only LuauTileAlgorithm, which exposes it to user-authored Luau scripts). Built-in geometry algorithms don't care and ignore the resolver.

Injected by AutotileEngine::setWindowRegistry() so every algorithm returned from AlgorithmRegistry::algorithm() is seeded with the live registry's lookup before any lifecycle hook fires. The resolver is a std::function rather than a raw WindowRegistry* so tests can plug in canned answers without constructing a real registry.

Thread safety: setter must be called from the main thread; the resolver itself is invoked only from algorithm methods that already run on the main thread (buildStateMap / onWindowAdded / etc.).

◆ setRegistryId()

void PhosphorTiles::TilingAlgorithm::setRegistryId ( const QString & id )

inline

Registry-internal setter.

Not intended for direct use; AlgorithmRegistry calls this from registerAlgorithm / unregisterAlgorithm.

◆ supportsCustomParams()

virtual bool PhosphorTiles::TilingAlgorithm::supportsCustomParams ( ) const

virtualnoexcept

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 in PhosphorTiles::LuauTileAlgorithm.

◆ supportsLifecycleHooks()

virtual bool PhosphorTiles::TilingAlgorithm::supportsLifecycleHooks ( ) const

virtualnoexcept

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 in PhosphorTiles::LuauTileAlgorithm.

◆ supportsMasterCount()

virtual bool PhosphorTiles::TilingAlgorithm::supportsMasterCount ( ) const

virtual

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 in PhosphorTiles::LuauTileAlgorithm.

◆ supportsMemory()

virtual bool PhosphorTiles::TilingAlgorithm::supportsMemory ( ) const

virtualnoexcept

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 in PhosphorTiles::LuauTileAlgorithm.

◆ supportsMinSizes()

virtual bool PhosphorTiles::TilingAlgorithm::supportsMinSizes ( ) const

virtualnoexcept

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 in PhosphorTiles::LuauTileAlgorithm.

◆ supportsResizeHook()

virtual bool PhosphorTiles::TilingAlgorithm::supportsResizeHook ( ) const

virtualnoexcept

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 in PhosphorTiles::LuauTileAlgorithm.

◆ supportsScriptState()

virtual bool PhosphorTiles::TilingAlgorithm::supportsScriptState ( ) const

virtualnoexcept

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 in PhosphorTiles::LuauTileAlgorithm.

◆ supportsSplitRatio()

virtual bool PhosphorTiles::TilingAlgorithm::supportsSplitRatio ( ) const

virtual

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 in PhosphorTiles::LuauTileAlgorithm.

◆ zoneNumberDisplay()

virtual QString PhosphorTiles::TilingAlgorithm::zoneNumberDisplay ( ) const

virtualnoexcept

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 in PhosphorTiles::LuauTileAlgorithm.

Member Data Documentation

◆ m_appIdResolver

std::function<QString(const QString&)> PhosphorTiles::TilingAlgorithm::m_appIdResolver

protected

◆ m_registryId

QString PhosphorTiles::TilingAlgorithm::m_registryId

protected

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

phosphor-tiles/include/PhosphorTiles/TilingAlgorithm.h

Phosphor Qt6 / Wayland library suite for window-management tools

Signals

Public Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ TilingAlgorithm() [1/2]

◆ ~TilingAlgorithm()

◆ TilingAlgorithm() [2/2]

Member Function Documentation

◆ appIdResolver()

◆ calculateZones()

◆ centerLayout()

◆ configurationChanged

◆ customParamDefList()

◆ defaultMaxWindows()

◆ defaultSplitRatio()

◆ description()

◆ hasCustomParam()

◆ innerRect() [1/2]

◆ innerRect() [2/2]

◆ isScripted()

◆ isUserScript()

◆ masterZoneIndex()

◆ minimumWindows()

◆ name()

◆ onWindowAdded()

◆ onWindowRemoved()

◆ onWindowResized()

◆ operator=()

◆ prepareTilingState()

◆ producesOverlappingZones()

◆ registryId()

◆ setAppIdResolver()

◆ setRegistryId()

◆ supportsCustomParams()

◆ supportsLifecycleHooks()

◆ supportsMasterCount()

◆ supportsMemory()

◆ supportsMinSizes()

◆ supportsResizeHook()

◆ supportsScriptState()

◆ supportsSplitRatio()

◆ zoneNumberDisplay()

Member Data Documentation

◆ m_appIdResolver

◆ m_registryId