cutter/src/common/RefreshDeferrer.h

#ifndef REFRESHDEFERRER_H
#define REFRESHDEFERRER_H

#include <QObject>

class CutterDockWidget;
class RefreshDeferrer;

using RefreshDeferrerParams = void *;
using RefreshDeferrerParamsResult = void *;

/**
 * @brief Abstract class for accumulating params in RefreshDeferrer
 */
class RefreshDeferrerAccumulator
{
    friend class RefreshDeferrer;

public:
    virtual ~RefreshDeferrerAccumulator() = default;

protected:
    /**
     * @brief Add a new param to the accumulator
     */
    virtual void accumulate(RefreshDeferrerParams params) = 0;

    /**
     * @brief Ignore the incoming params. Useful for freeing if necessary.
     */
    virtual void ignoreParams(RefreshDeferrerParams params) = 0;

    /**
     * @brief Clear the current accumulator
     */
    virtual void clear() = 0;

    /**
     * @brief Return the final result of the accumulation
     */
    virtual RefreshDeferrerParamsResult result() = 0;
};

/**
 * @brief Accumulator which simply replaces the current value by an incoming new one
 * @tparam T The type of the param to store
 *
 * This accumulator takes the ownership of all params passed to it and deletes them automatically if
 * not needed anymore!
 */
template<class T>
class ReplacingRefreshDeferrerAccumulator : public RefreshDeferrerAccumulator
{
private:
    T *value = nullptr;
    bool replaceIfNull;

public:
    /**
     * \param Determines whether, if nullptr is passed, the current value should be replaced or
     * kept.
     */
    explicit ReplacingRefreshDeferrerAccumulator(bool replaceIfNull = true)
        : replaceIfNull(replaceIfNull)
    {
    }

    ~ReplacingRefreshDeferrerAccumulator() override { delete value; }

protected:
    void accumulate(RefreshDeferrerParams params) override
    {
        if (!replaceIfNull && !params) {
            return;
        }
        delete value;
        value = static_cast<T *>(params);
    }

    void ignoreParams(RefreshDeferrerParams params) override { delete static_cast<T *>(params); }

    void clear() override
    {
        delete value;
        value = nullptr;
    }

    virtual RefreshDeferrerParamsResult result() override { return value; }
};

/**
 * @brief Helper class for deferred refreshing in Widgets
 *
 * This class can handle the logic necessary to defer the refreshing of widgets when they are not
 * visible. It contains an optional RefreshDeferrerAccumulator, which can be used to accumulate
 * incoming events while refreshing is deferred.
 *
 * Example (don't write it like this in practice, use the convenience methods in CutterDockWidget):
 * ```
 * // in the constructor of a widget
 * this->refreshDeferrer = new RefreshDeferrer(new ReplacingRefreshDeferrerAccumulator(false),
 * this); this->refreshDeferrer->registerFor(this); connect(this->refreshDeferrer,
 * &RefreshDeferrer::refreshNow, this, [this](MyParam *param) {
 *      // We attempted a refresh some time before, but it got deferred.
 *      // Now the RefreshDeferrer tells us to do the refresh and gives us the accumulated param.
 *      this->doRefresh(*param);
 * }
 *
 * // ...
 *
 * void MyWidget::doRefresh(MyParam param)
 * {
 *      if (!this->refreshDeferrer->attemptRefresh(new MyParam(param))) {
 *          // We shouldn't refresh right now.
 *          // The RefreshDeferrer takes over the param we passed it in attemptRefresh()
 *          // and gives it to the ReplacingRefreshDeferrerAccumulator.
 *          return;
 *      }
 *      // do the actual refresh depending on param
 * }
 * ```
 *
 */
class RefreshDeferrer : public QObject
{
    Q_OBJECT

private:
    CutterDockWidget *dockWidget = nullptr;
    RefreshDeferrerAccumulator *acc;
    bool dirty = false;

public:
    /**
     * @param acc The accumulator (can be nullptr). The RefreshDeferrer takes the ownership!
     */
    explicit RefreshDeferrer(RefreshDeferrerAccumulator *acc, QObject *parent = nullptr);
    ~RefreshDeferrer() override;

    bool attemptRefresh(RefreshDeferrerParams params);
    void registerFor(CutterDockWidget *dockWidget);

signals:
    void refreshNow(const RefreshDeferrerParamsResult paramsResult);
};

#endif // REFRESHDEFERRER_H