TilingAlgorithm.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 fuddlesworth
// SPDX-License-Identifier: LGPL-2.1-or-later
 
#pragma once
 
#include <phosphortiles_export.h>
#include "AutotileConstants.h"
// TilingParams, TilingScreenInfo, WindowInfo, buildWindowInfos, EdgeGaps and
// the static helper structs (ThreeColumnWidths, CumulativeMinDims) used to be
// declared inline in this header. They have moved to dedicated headers to
// keep responsibilities split:
//   - TilingParams.h           — per-call parameter bundles + WindowInfo builder
//   - TilingAlgorithmHelpers.h — POD helper result types
// Both are included here so existing callers that only include
// <PhosphorTiles/TilingAlgorithm.h> continue to compile unchanged.
#include "TilingAlgorithmHelpers.h"
#include "TilingParams.h"
 
#include <QObject>
#include <QRect>
#include <QString>
#include <QSize>
#include <QVariant>
#include <QVariantMap>
#include <QVector>
#include <functional>
 
namespace PhosphorTiles {
 
class TilingState;
 
class PHOSPHORTILES_EXPORT TilingAlgorithm : public QObject
{
    Q_OBJECT
 
    Q_PROPERTY(QString name READ name CONSTANT)
    Q_PROPERTY(QString description READ description CONSTANT)
    Q_PROPERTY(bool supportsMasterCount READ supportsMasterCount CONSTANT)
    Q_PROPERTY(bool supportsSplitRatio READ supportsSplitRatio CONSTANT)
 
public:
    explicit TilingAlgorithm(QObject* parent = nullptr);
    ~TilingAlgorithm() override = default;
 
    // Prevent copying (QObject rule)
    TilingAlgorithm(const TilingAlgorithm&) = delete;
    TilingAlgorithm& operator=(const TilingAlgorithm&) = delete;
 
    void setAppIdResolver(std::function<QString(const QString&)> resolver)
    {
        m_appIdResolver = std::move(resolver);
    }
 
    std::function<QString(const QString&)> appIdResolver() const
    {
        if (m_appIdResolver) {
            return m_appIdResolver;
        }
        return [](const QString&) {
            return QString();
        };
    }
 
    QString registryId() const
    {
        return m_registryId;
    }
    void setRegistryId(const QString& id)
    {
        m_registryId = id;
    }
 
    virtual QString name() const = 0;
 
    virtual QString description() const = 0;
 
    virtual QVector<QRect> calculateZones(const TilingParams& params) const = 0;
 
    virtual int masterZoneIndex() const;
 
    virtual bool supportsMasterCount() const;
 
    virtual bool supportsSplitRatio() const;
 
    virtual qreal defaultSplitRatio() const;
 
    virtual int minimumWindows() const;
 
    virtual int defaultMaxWindows() const;
 
    virtual bool producesOverlappingZones() const;
 
    // ── noexcept convention for virtual methods ──────────────────────────
    // Methods below are noexcept because they only read cached POD fields.
    // Methods above (supportsMasterCount, supportsSplitRatio, etc.) are NOT
    // noexcept because ScriptedAlgorithm overrides may allocate QStrings or
    // invoke cached JS values. When adding new virtuals, use noexcept only
    // if the implementation is guaranteed to never allocate or throw.
 
    virtual QString zoneNumberDisplay() const noexcept;
 
    virtual bool centerLayout() const;
 
    virtual bool isScripted() const noexcept;
 
    virtual bool supportsMinSizes() const noexcept;
 
    virtual bool supportsMemory() const noexcept;
 
    virtual void prepareTilingState(TilingState* state) const;
 
    virtual bool isUserScript() const noexcept;
 
    // ── Lifecycle Hooks (optional, v2) ──────────────────────────────────
 
    virtual bool supportsLifecycleHooks() const noexcept;
 
    virtual void onWindowAdded(TilingState* state, int windowIndex);
 
    virtual void onWindowRemoved(TilingState* state, int windowIndex);
 
    // ── Custom Parameters (optional, v2) ──────────────────────────────────
 
    virtual bool supportsCustomParams() const noexcept;
 
    virtual QVariantList customParamDefList() const;
 
    virtual bool hasCustomParam(const QString& name) const;
 
protected:
    // Resolver from instance id → live app class. Set by AutotileEngine via
    // setAppIdResolver after constructing/looking up the algorithm. Default
    // is an empty std::function; appIdResolver() returns a no-op lambda in
    // that case so call sites can invoke it unconditionally.
    std::function<QString(const QString&)> m_appIdResolver;
 
    // Registry id — populated by AlgorithmRegistry at registration time so
    // preview / serialisation code holding only a TilingAlgorithm* can
    // recover the id without walking the registry.
    QString m_registryId;
 
    static QVector<int> distributeEvenly(int total, int count);
 
    static QRect innerRect(const QRect& screenGeometry, int outerGap);
 
    static QRect innerRect(const QRect& screenGeometry, const EdgeGaps& gaps);
 
    static QVector<int> distributeWithGaps(int total, int count, int gap);
 
    static QVector<int> distributeWithMinSizes(int total, int count, int gap, const QVector<int>& minDims);
 
    static int minWidthAt(const QVector<QSize>& minSizes, int index);
 
    static int minHeightAt(const QVector<QSize>& minSizes, int index);
 
    static void solveTwoPartMinSizes(int contentDim, int& firstDim, int& secondDim, int minFirst, int minSecond);
 
    static void applyPerWindowMinSize(int& width, int& height, const QVector<QSize>& minSizes, int index);
 
    using ThreeColumnWidths = ::PhosphorTiles::ThreeColumnWidths;
 
    static ThreeColumnWidths solveThreeColumnWidths(int areaX, int contentWidth, int innerGap, qreal splitRatio,
                                                    int minLeftWidth, int minCenterWidth, int minRightWidth);
 
    using CumulativeMinDims = ::PhosphorTiles::CumulativeMinDims;
 
    static CumulativeMinDims computeAlternatingCumulativeMinDims(int windowCount, const QVector<QSize>& minSizes,
                                                                 int innerGap);
 
    static void appendGracefulDegradation(QVector<QRect>& zones, const QRect& remaining, int leftover, int innerGap);
 
    static qreal clampOrProportionalFallback(qreal ratio, qreal minFirstRatio, qreal maxFirstRatio, int firstDim,
                                             int secondDim);
 
Q_SIGNALS:
    void configurationChanged();
};
 
} // namespace PhosphorTiles