qml_bridge.hpp

Go to the documentation of this file.

#ifndef QML_BRIDGE_HPP
#define QML_BRIDGE_HPP
 
/**
 * \file qml_bridge.hpp
 * \brief Bridge class to expose C++ functionality to QML.
 * \author Le Bars, Yoann
 * \ingroup UIWindows
 *
 * This file is part of the pure C++ benchmark.
 *
 * This program is free software: you can redistribute it and/or modify it
 * under the terms of the GNU General Public License as published by the Free
 * Software Foundation, either version 3 of the License, or (at your option)
 * any later version.
 *
 * This program is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
 * more details.
 *
 * You should have received a copy of the GNU General Public License along with
 * this program. If not, see <https://www.gnu.org/licenses/>.
 */
 
#include <QObject>
#include <QPointer>
#include <QString>
#include <QWidget>
#include <memory>
#include <optional>
 
#include "config.hpp"
#include "display.hpp"
 
namespace Window {
    /**
     * \brief Bridge class to expose C++ functionality to QML.
     *
     * This class acts as an interface between QML and the C++ backend,
     * exposing the Display widget and application actions (About, Quit).
     * \ingroup UIWindows
     */
    class QmlBridge : public QObject {
        Q_OBJECT
        Q_PROPERTY(QWidget* displayContainer READ displayContainer NOTIFY
                       displayContainerChanged)
        Q_PROPERTY(QString aboutText READ aboutText NOTIFY aboutTextChanged)
 
       public:
        /**
         * \brief Constructs the QML bridge.
         * \param config The simulation configuration object.
         * \param parent The parent QObject.
         */
        explicit QmlBridge(const Configuration::SimulationConfig& config,
                           QObject* parent = nullptr);
 
        /**
         * \brief Destructor.
         */
        ~QmlBridge() override;
 
        /**
         * \brief Gets the widget container for the 3D display.
         * \return A pointer to the widget container, or nullptr if not created.
         */
        QWidget* displayContainer() const;
 
        /**
         * \brief Gets the "About" page text.
         * \return The about text as a QString.
         */
        QString aboutText() const;
 
        /**
         * \brief Starts the simulation after the window is shown.
         */
        Q_INVOKABLE void startSimulation();
 
        /**
         * \brief Stops the physics thread and prints profiling reports.
         *
         * UI teardown is handled separately by releaseDisplayDeferred() or
         * releaseDisplayStrict(), depending on --cleanup-mode.
         */
        Q_INVOKABLE void shutdownSimulation();
 
        /**
         * \brief Schedules deferred destruction of Display and its container.
         *
         * Used in fast cleanup mode (benchmark-friendly, similar to async
         * Python GC). Display is destroyed first; the container follows via a
         * queued connection.
         */
        void releaseDisplayDeferred(QWidget* container_for_deferred_delete);
 
        /**
         * \brief Synchronously destroys the display container and its window.
         *
         * Used in strict cleanup mode (Valgrind and conservative teardown).
         */
        void releaseDisplayStrict(QWidget* container);
 
       public slots:
        /**
         * \brief Slot to display the "About" dialogue.
         */
        void showAbout();
 
        /**
         * \brief Slot to display the "About Qt" dialogue.
         */
        void showAboutQt();
 
        /**
         * \brief Slot to quit the application.
         */
        void quit();
 
       signals:
        /**
         * \brief Emitted when the display container is created.
         */
        void displayContainerChanged();
 
        /**
         * \brief Emitted when the about text changes.
         */
        void aboutTextChanged();
 
        /**
         * \brief Emitted when the simulation finishes.
         */
        void simulationFinished();
 
       private:
        /**
         * \brief Loads the "About" page content from resources.
         * \return The content of the about page as a QString, or
         *         `std::nullopt` if loading fails.
         */
        std::optional<QString> loadAboutText();
 
        /// \brief The 3D display view for the simulation.
        QPointer<Display> display_;
 
        /// \brief The widget container for the 3D display.
        QPointer<QWidget> container_;
 
        /// \brief The cached about text.
        QString aboutText_;
 
        /// \brief True after UI resources have been released.
        bool uiReleased_ = false;
    };
}  // namespace Window
 
#endif  // QML_BRIDGE_HPP