StepEngineCore.h

Go to the documentation of this file.

// Copyright 2015 - 2026, GIBIS-UNIFESP and the wiRedPanda contributors
// SPDX-License-Identifier: GPL-3.0-or-later

 
#pragma once
 
#include <QFile>
#include <QJsonArray>
#include <QJsonDocument>
#include <QJsonObject>
#include <QString>
#include <QVector>
 
#include "App/Core/ExerciseTourResources.h"

template <typename StepType>
class StepEngineCore
{
public:
    using FillStep = void (*)(const QString &id, const QJsonObject &stepObj, StepType &step);

    struct Persistence {
        int (*getProgress)(const QString &);
        void (*setProgress)(const QString &, int);
        QStringList (*getCompleted)();
        void (*setCompleted)(const QStringList &);
    };

    struct AdvanceResult {
        bool advanced = false;   
        bool reachedEnd = false; 
        int completedStep = -1;  
    };
 
    StepEngineCore(FillStep fillStep, Persistence persistence)
        : m_fillStep(fillStep)
        , m_persistence(persistence)
    {
    }

    bool loadFromResource(const QString &resourcePath)
    {
        m_active = false;
        m_steps.clear();
        m_currentStep = 0;
        m_id.clear();
        m_title.clear();
        m_resourcePath = resourcePath;
 
        QFile file(resourcePath);
        if (!file.open(QIODevice::ReadOnly)) {
            return false;
        }
 
        const QJsonDocument doc = QJsonDocument::fromJson(file.readAll());
        if (doc.isNull() || !doc.isObject()) {
            return false;
        }
 
        const QJsonObject root = doc.object();
        m_id = root.value("id").toString();
        const QString rawTitle = root.value("title").toString();
 
        if (m_id.isEmpty() || rawTitle.isEmpty()) {
            return false;
        }
 
        m_title = ExerciseTourResources::translate(m_id + QStringLiteral(".title"), rawTitle);
 
        const QJsonArray stepsArray = root.value("steps").toArray();
        if (stepsArray.isEmpty()) {
            return false;
        }
 
        for (const QJsonValue &stepVal : stepsArray) {
            StepType step;
            m_fillStep(m_id, stepVal.toObject(), step);
            m_steps.append(step);
        }
 
        return true;
    }

    bool start()
    {
        if (m_steps.isEmpty()) {
            return false;
        }
        m_currentStep = m_persistence.getProgress(m_id);
        if (m_currentStep < 0 || m_currentStep >= m_steps.size()) {
            m_currentStep = 0;
        }
        m_active = true;
        return true;
    }

    bool stop()
    {
        if (!m_active) {
            return false;
        }
        m_active = false;
        return true;
    }

    bool goToPreviousStep()
    {
        if (!m_active || m_currentStep <= 0) {
            return false;
        }
        --m_currentStep;
        m_persistence.setProgress(m_id, m_currentStep);
        return true;
    }

    AdvanceResult advance()
    {
        if (!m_active || m_steps.isEmpty()) {
            return {};
        }
        if (m_currentStep >= m_steps.size() - 1) {
            return {.reachedEnd = true};
        }
        const int completed = m_currentStep;
        ++m_currentStep;
        m_persistence.setProgress(m_id, m_currentStep);
        return {.advanced = true, .completedStep = completed};
    }

    bool retranslate()
    {
        if (m_resourcePath.isEmpty() || !m_active) {
            return false;
        }
        const int savedStep = m_currentStep;
 
        if (!loadFromResource(m_resourcePath)) {
            return false;
        }
 
        m_currentStep = qBound(0, savedStep, static_cast<int>(m_steps.size()) - 1);
        m_active = true;
        return true;
    }

    void markCompleted()
    {
        m_active = false;
 
        QStringList completed = m_persistence.getCompleted();
        if (!completed.contains(m_id)) {
            completed.append(m_id);
            m_persistence.setCompleted(completed);
        }
        m_persistence.setProgress(m_id, 0);
    }
 
    const StepType &currentStepData() const
    {
        static StepType empty;
        if (m_steps.isEmpty() || m_currentStep < 0 || m_currentStep >= m_steps.size()) {
            return empty;
        }
        return m_steps.at(m_currentStep);
    }
 
    QString id() const { return m_id; }
    QString title() const { return m_title; }
    int currentStep() const { return m_currentStep; }
    int totalSteps() const { return static_cast<int>(m_steps.size()); }
    bool isActive() const { return m_active; }
 
private:
    FillStep m_fillStep;
    Persistence m_persistence;
 
    QString m_id;
    QString m_title;
    QString m_resourcePath;
    QVector<StepType> m_steps;
    int m_currentStep = 0;
    bool m_active = false;
};