Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
TilingAlgorithm.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: 2026 fuddlesworth
2// SPDX-License-Identifier: LGPL-2.1-or-later
3
4#pragma once
5
6#include "phosphortiles_export.h"
7#include "AutotileConstants.h"
8// TilingParams, TilingScreenInfo, WindowInfo, buildWindowInfos and EdgeGaps used
9// to be declared inline in this header. They now live in TilingParams.h
10// (per-call parameter bundles + WindowInfo builder), included here so existing
11// callers that only include <PhosphorTiles/TilingAlgorithm.h> compile unchanged.
12#include "TilingParams.h"
13
14#include <QObject>
15#include <QRect>
16#include <QString>
17#include <QSize>
18#include <QVariant>
19#include <QVariantMap>
20#include <QVector>
21#include <functional>
22
23namespace PhosphorTiles {
24
25class TilingState;
26
53class PHOSPHORTILES_EXPORT TilingAlgorithm : public QObject
54{
55 Q_OBJECT
56
57 Q_PROPERTY(QString name READ name CONSTANT)
58 Q_PROPERTY(QString description READ description CONSTANT)
59 Q_PROPERTY(bool supportsMasterCount READ supportsMasterCount CONSTANT)
60 Q_PROPERTY(bool supportsSplitRatio READ supportsSplitRatio CONSTANT)
61
62public:
63 explicit TilingAlgorithm(QObject* parent = nullptr);
64 ~TilingAlgorithm() override = default;
65
66 // Prevent copying (QObject rule)
69
87 void setAppIdResolver(std::function<QString(const QString&)> resolver)
88 {
89 m_appIdResolver = std::move(resolver);
90 }
91
96 std::function<QString(const QString&)> appIdResolver() const
97 {
98 if (m_appIdResolver) {
99 return m_appIdResolver;
100 }
101 return [](const QString&) {
102 return QString();
103 };
104 }
105
115 QString registryId() const
116 {
117 return m_registryId;
118 }
119
121 void setRegistryId(const QString& id)
122 {
123 m_registryId = id;
124 }
125
130 virtual QString name() const = 0;
131
136 virtual QString description() const = 0;
137
151 virtual QVector<QRect> calculateZones(const TilingParams& params) const = 0;
152
168 virtual int masterZoneIndex() const;
169
177 virtual bool supportsMasterCount() const;
178
186 virtual bool supportsSplitRatio() const;
187
195 virtual qreal defaultSplitRatio() const;
196
205 virtual int minimumWindows() const;
206
216 virtual int defaultMaxWindows() const;
217
227 virtual bool producesOverlappingZones() const;
228
229 // ── noexcept convention for virtual methods ──────────────────────────
230 // Methods below are noexcept because they only read cached POD fields.
231 // Methods above (supportsMasterCount, supportsSplitRatio, etc.) are NOT
232 // noexcept because LuauTileAlgorithm overrides may allocate QStrings or
233 // marshal cached script values. When adding new virtuals, use noexcept only
234 // if the implementation is guaranteed to never allocate or throw.
235
244 virtual QString zoneNumberDisplay() const noexcept;
245
255 virtual bool centerLayout() const;
256
268 virtual bool supportsSingleWindow() const noexcept;
269
280 virtual bool retilesOnFocusChange() const noexcept;
281
290 virtual bool isScripted() const noexcept;
291
311 virtual bool supportsMinSizes() const noexcept;
312
332 virtual QString overlapStacking() const noexcept;
333
342 virtual bool supportsMemory() const noexcept;
343
356 virtual void prepareTilingState(TilingState* state) const;
357
368 virtual bool isUserScript() const noexcept;
369
370 // ── Lifecycle Hooks (optional, v2) ──────────────────────────────────
371
381 virtual bool supportsLifecycleHooks() const noexcept;
382
396 virtual void onWindowAdded(TilingState* state, int windowIndex);
397
416 virtual void onWindowRemoved(TilingState* state, int windowIndex);
417
427 virtual bool supportsResizeHook() const noexcept;
428
440 virtual void onWindowResized(TilingState* state, const ResizeEvent& resize);
441
451 virtual bool supportsScriptState() const noexcept;
452
453 // ── Custom Parameters (optional, v2) ──────────────────────────────────
454
463 virtual bool supportsCustomParams() const noexcept;
464
473 virtual QVariantList customParamDefList() const;
474
484 virtual bool hasCustomParam(const QString& name) const;
485
486protected:
487 // Resolver from instance id → live app class. Set by AutotileEngine via
488 // setAppIdResolver after constructing/looking up the algorithm. Default
489 // is an empty std::function; appIdResolver() returns a no-op lambda in
490 // that case so call sites can invoke it unconditionally.
491 std::function<QString(const QString&)> m_appIdResolver;
492
493 // Registry id — populated by AlgorithmRegistry at registration time so
494 // preview / serialisation code holding only a TilingAlgorithm* can
495 // recover the id without walking the registry.
497
505 static QRect innerRect(const QRect& screenGeometry, int outerGap);
506
514 static QRect innerRect(const QRect& screenGeometry, const EdgeGaps& gaps);
515
516Q_SIGNALS:
524};
525
526} // namespace PhosphorTiles
Algorithm-layer constants for the autotile/tile primitives.
void setAppIdResolver(std::function< QString(const QString &)> resolver)
Inject a resolver that maps an opaque instance id to its live app class.
Definition TilingAlgorithm.h:87
virtual bool supportsMemory() const noexcept
Whether this algorithm maintains persistent state across retiles.
virtual bool supportsSplitRatio() const
Check if algorithm supports split ratio adjustment.
TilingAlgorithm(const TilingAlgorithm &)=delete
virtual void onWindowRemoved(TilingState *state, int windowIndex)
Called when a window is removed from the tiling before retile.
virtual void onWindowAdded(TilingState *state, int windowIndex)
Called when a window is added to the tiling before retile.
virtual void prepareTilingState(TilingState *state) const
Prepare the TilingState before calculateZones() is called.
virtual int minimumWindows() const
Get minimum number of windows for meaningful tiling.
TilingAlgorithm(QObject *parent=nullptr)
static QRect innerRect(const QRect &screenGeometry, int outerGap)
Compute the usable area after subtracting uniform outer gap from screen edges.
std::function< QString(const QString &)> m_appIdResolver
Definition TilingAlgorithm.h:491
virtual bool centerLayout() const
Whether this algorithm uses a center layout.
~TilingAlgorithm() override=default
virtual QVector< QRect > calculateZones(const TilingParams &params) const =0
Calculate zone geometries for N windows.
virtual bool supportsLifecycleHooks() const noexcept
Whether this algorithm implements any lifecycle hooks.
TilingAlgorithm & operator=(const TilingAlgorithm &)=delete
virtual void onWindowResized(TilingState *state, const ResizeEvent &resize)
Called when a tiled window finished an interactive resize.
virtual bool isScripted() const noexcept
Whether this algorithm is a user-provided scripted algorithm.
virtual qreal defaultSplitRatio() const
Get default split ratio for this algorithm.
QString registryId() const
The id this algorithm is registered under.
Definition TilingAlgorithm.h:115
virtual bool isUserScript() const noexcept
Whether this scripted algorithm was loaded from a user directory.
virtual QString overlapStacking() const noexcept
Stacking direction for overlap layouts.
virtual bool supportsSingleWindow() const noexcept
Whether this algorithm lays out the single-window case itself.
void setRegistryId(const QString &id)
Registry-internal setter.
Definition TilingAlgorithm.h:121
void configurationChanged()
Emitted when algorithm parameters change.
virtual bool hasCustomParam(const QString &name) const
Check if a named custom parameter is declared by this algorithm.
virtual QString description() const =0
Description of the algorithm behavior.
virtual bool supportsResizeHook() const noexcept
Whether this algorithm reacts to interactive window resizes.
QString m_registryId
Definition TilingAlgorithm.h:496
virtual QVariantList customParamDefList() const
Get custom parameter definitions as a QVariantList for QML.
virtual QString zoneNumberDisplay() const noexcept
How zone numbers should be displayed in previews.
virtual int defaultMaxWindows() const
Get default maximum number of windows for this algorithm.
virtual int masterZoneIndex() const
Get the index of the "master" zone (if applicable).
virtual bool supportsMinSizes() const noexcept
Whether this algorithm supports per-window minimum size constraints.
virtual bool supportsCustomParams() const noexcept
Whether this algorithm declares custom parameters.
virtual bool retilesOnFocusChange() const noexcept
Whether the layout must be recomputed when focus moves.
virtual bool producesOverlappingZones() const
Whether this algorithm intentionally produces overlapping zones.
virtual bool supportsMasterCount() const
Check if algorithm supports variable master count.
virtual QString name() const =0
Human-readable name of the algorithm.
std::function< QString(const QString &)> appIdResolver() const
Access the current resolver.
Definition TilingAlgorithm.h:96
virtual bool supportsScriptState() const noexcept
Whether this algorithm persists an opaque per-screen script-state bag (TilingState::scriptState) acro...
Tracks tiling state for a single screen.
Definition TilingState.h:40
Definition AutotileEngine.h:52
::PhosphorLayout::EdgeGaps EdgeGaps
Definition TilingParams.h:25
Describes an interactive resize that triggered a retile.
Definition TilingParams.h:51
Parameters for zone calculation.
Definition TilingParams.h:84