vreStartPage.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file vreStartPage.h
//! \brief Defines the start page UI component for VR-Engage
//!
//! This file contains the DtVreStartPage class and supporting classes which
//! provide the UI for the application's start menu. It includes functionality
//! for listing and selecting scenarios, displaying scenario information, and
//! initiating session hosting or joining. The UI dynamically updates as new
//! scenarios are added to the scenario directory.
#pragma once
 
#include "vrePlayerStation/export.h"
#include "vrePlayerStation/vreHeaderFooterUIBase.h"
 
#include <QObject>
#include <QScopedPointer>
#include <QAbstractListModel>
 
class QQuickItem;
 
namespace makVre
{
//! \brief Forward declaration of the player station application class
class DtPlayerStationApp;
 
//! \brief Class representing a file entry in the file selection models
//!
//! DtFileEntry encapsulates information about a single file in the
//! file selection lists, storing both the display name and the full path.
//! This is used for scenarios and terrain files displayed in the start page.
class PLAYERSTATION_DLL DtFileEntry
{
public:
   //! \brief Default constructor
   //!
   //! Creates an empty file entry with blank name and path.
   DtFileEntry();
 
   //! \brief Constructor with name and path
   //! \param fileName Display name of the file
   //! \param filePath Full path to the file
   //!
   //! Creates a file entry with the specified name and path.
   DtFileEntry(const QString& fileName, const QString& filePath);
 
   //! \brief Gets the display name of the file
   //! \return File name as a QString
   //!
   //! Returns the display name of this file entry.
   QString getFileName() const;
 
   //! \brief Sets the display name of the file
   //! \param name New file name
   //!
   //! Updates the display name of this file entry.
   void setFileName(const QString& name);
 
   //! \brief Gets the full path to the file
   //! \return File path as a QString
   //!
   //! Returns the full path to this file entry.
   QString getFilePath() const;
 
   //! \brief Sets the full path to the file
   //! \param name New file path
   //!
   //! Updates the full path to this file entry.
   void setFilePath(const QString& name);
 
protected:
   //! \brief Display name of the file
   QString myFileName;
 
   //! \brief Full path to the file
   QString myFilePath;
};
 
//! \brief Model for displaying files in a list view
//!
//! DtRecursiveFileModel is a Qt model class that provides a list of files
//! to QML list views. It manages a collection of file entries and exposes
//! them through the Qt model-view framework, making them accessible to the UI.
class PLAYERSTATION_DLL DtRecursiveFileModel : public QAbstractListModel
{
   Q_OBJECT;
 
public:
   //! \brief Enumeration of data roles for the model
   //!
   //! Defines the custom roles used to access different aspects of the file entries.
   enum FileModelRoles
   {
      FileNameRole = Qt::UserRole + 1, //!< Role for accessing the file name
      FilePathRole                     //!< Role for accessing the file path
   };
 
   //! \brief Constructor
   //! \param parent Optional parent QObject for memory management
   //!
   //! Creates a new empty file model.
   DtRecursiveFileModel(QObject* parent = 0);
 
   //! \brief Adds a file entry to the model
   //! \param entry File entry to add
   //!
   //! Adds a new file entry to the end of the model's file list.
   virtual void addFile(const DtFileEntry& entry);
 
   //! \brief Clears all file entries from the model
   //!
   //! Removes all file entries from the model, leaving it empty.
   virtual void clear();
 
   //! \brief Sorts the file entries
   //! \param column Column index to sort by (ignored in this implementation)
   //! \param order Sort order (ascending or descending)
   //!
   //! Sorts the file entries case-insensitively using QCollator.
   //! This ensures proper alphabetical sorting regardless of locale.
   virtual void sort(int column, Qt::SortOrder order = Qt::AscendingOrder) override;
 
   //! \brief Removes rows from the model
   //! \param row Starting row index
   //! \param column Number of columns to remove (ignored in this implementation)
   //! \param parent Parent model index (ignored in this implementation)
   //! \return True if rows were successfully removed
   //!
   //! Implementation of QAbstractItemModel::removeRows for removing file entries.
   virtual bool removeRows(int row, int column = 0, const QModelIndex& parent = QModelIndex()) override;
 
   //! \brief Gets the number of rows in the model
   //! \param parent Parent model index (ignored in this implementation)
   //! \return Number of file entries in the model
   //!
   //! Implementation of QAbstractItemModel::rowCount that returns the number of file entries.
   virtual int rowCount(const QModelIndex& parent = QModelIndex()) const override;
 
   //! \brief Gets data for a specific index and role
   //! \param index Model index to get data for
   //! \param role Data role to retrieve
   //! \return Requested data as a QVariant
   //!
   //! Implementation of QAbstractItemModel::data that provides access to file entry data.
   virtual QVariant data(const QModelIndex& index, int role = Qt::DisplayRole) const override;
 
   //! \brief Sets data for a specific index and role
   //! \param index Model index to set data for
   //! \param value New value to set
   //! \param role Data role to set
   //! \return True if data was successfully set
   //!
   //! Implementation of QAbstractItemModel::setData for updating file entry data.
   virtual bool setData(const QModelIndex& index, const QVariant& value, int role) override;
 
protected:
   //! \brief Gets the mapping from role IDs to role names
   //! \return Hash mapping role IDs to their name strings
   //!
   //! Implementation of QAbstractItemModel::roleNames that provides the mapping
   //! from role enum values to the string names used in QML.
   virtual QHash<int, QByteArray> roleNames() const override;
 
   //! \brief List of file entries in the model
   //!
   //! Storage for all the file entries managed by this model.
   QList<DtFileEntry> myFiles;
};
 
//! \brief QML interface for the start page
//!
//! DtVreStartPageQml provides the interface between the C++ backend
//! and the QML frontend of the start page. It manages the selection state,
//! scenario descriptions, SMS information, and button actions, exposing these
//! to QML for the user interface.
class PLAYERSTATION_DLL DtVreStartPageQml : public QObject
{
   Q_OBJECT;
 
   //! \brief Current button action state
   //!
   //! QML property that exposes the current button action state (HOST, UNHOST, NONE).
   //! This determines which actions are available in the UI.
   Q_PROPERTY(ButtonAction buttonAction READ getButtonAction WRITE setButtonAction NOTIFY buttonClicked);
 
   //! \brief Scenario description
   //!
   //! QML property that exposes the description text for the selected scenario.
   Q_PROPERTY(QString description READ getDescription WRITE setDescription NOTIFY descriptionChanged);
 
   //! \brief SMS configuration information
   //!
   //! QML property that exposes the SMS (System Management Status) information.
   Q_PROPERTY(QString sms READ getSMS WRITE setSMS NOTIFY smsChanged);
 
   //! \brief Currently selected file
   //!
   //! QML property that exposes the path of the currently selected file.
   Q_PROPERTY(QString selectedFile READ getSelectedFile WRITE setSelectedFile NOTIFY fileSelected);
 
public:
   //! \brief Constructor
   //! \param parent Optional parent QObject for memory management
   //!
   //! Creates a new QML interface for the start page.
   explicit DtVreStartPageQml(QObject* parent = nullptr);
 
   //! \brief Destructor
   //!
   //! Cleans up resources used by the QML interface.
   virtual ~DtVreStartPageQml() override;
 
   //! \brief Updates the description information from the selected file
   //!
   //! Loads and sets the description text based on the currently selected file.
   //! This is called automatically when a new file is selected.
   void setDescriptionInformation();
 
public:
   //! \brief Enumeration of possible button actions
   //!
   //! Defines the possible states for the main action button in the UI.
   enum ButtonAction
   {
      HOST,   //!< Host a new session with the selected scenario
      UNHOST, //!< Stop hosting the current session
      NONE    //!< No action available
   };
   Q_ENUM(ButtonAction);
 
   //! \brief Gets the current button action state
   //! \return Current button action state
   //!
   //! Returns the current button action state for the UI.
   virtual ButtonAction getButtonAction() const;
 
   //! \brief Gets the currently selected file
   //! \return Path to the selected file
   //!
   //! Returns the path to the currently selected file.
   virtual QString getSelectedFile() const;
 
   //! \brief Gets the current description text
   //! \return Description text
   //!
   //! Returns the description text for the selected scenario.
   virtual QString getDescription() const;
 
   //! \brief Gets the current SMS information
   //! \return SMS information text
   //!
   //! Returns the SMS (System Management Status) information.
   virtual QString getSMS() const;
 
   //! \brief Starts a new session as host
   //!
   //! QML-invokable method that initiates a new session using the selected scenario,
   //! with this instance as the host. Emits the sessionStarted signal.
   Q_INVOKABLE virtual void startSession();
 
   //! \brief Joins an existing session
   //!
   //! QML-invokable method that joins an existing session using the current settings.
   //! Emits the sessionJoined signal.
   Q_INVOKABLE virtual void joinSession();
 
   //! \brief Resets properties to their default values
   //!
   //! QML-invokable method that resets all property values to their defaults.
   //! Emits the propertiesChanged signal.
   Q_INVOKABLE virtual void resetProperties();
 
public slots:
   //! \brief Sets the button action state
   //! \param ba New button action state
   //!
   //! Updates the button action state and emits the buttonClicked signal.
   virtual void setButtonAction(ButtonAction ba);
 
   //! \brief Sets the selected file
   //! \param file Path to the newly selected file
   //!
   //! Updates the selected file and emits the fileSelected signal.
   //! Also triggers a description update.
   virtual void setSelectedFile(QString file);
 
   //! \brief Sets the description text
   //! \param description New description text
   //!
   //! Updates the description text and emits the descriptionChanged signal.
   virtual void setDescription(QString description);
 
   //! \brief Sets the SMS information
   //! \param sms New SMS information text
   //!
   //! Updates the SMS information and emits the smsChanged signal.
   virtual void setSMS(QString sms);
 
signals:
   //! \brief Signal emitted when the button action changes
   //! \param btnAction New button action state
   void buttonClicked(ButtonAction btnAction);
 
   //! \brief Signal emitted when a file is selected
   //! \param file Path to the selected file
   void fileSelected(QString file);
 
   //! \brief Signal emitted when the description changes
   //! \param description New description text
   void descriptionChanged(QString description);
 
   //! \brief Signal emitted when the SMS information changes
   //! \param sms New SMS information text
   void smsChanged(QString sms);
 
   //! \brief Signal emitted when a session is started
   void sessionStarted();
 
   //! \brief Signal emitted when a session is joined
   void sessionJoined();
 
   //! \brief Signal emitted when properties are reset
   void propertiesChanged();
 
protected:
   //! \brief Path to the selected file
   QString mySelectedFile;
 
   //! \brief Current button action state
   ButtonAction myButtonAction;
 
   //! \brief Current description text
   QString myDescription;
 
   //! \brief Current SMS information text
   QString mySms;
 
   //! \brief Pointer to the player station application
   //!
   //! Provides access to application services and state. Not owned
   //! by this class, simply a convenience pointer.
   DtPlayerStationApp* myApp;
};
 
//! \brief Start page UI component for VR-Engage
//!
//! DtVreStartPage provides the main start page UI for VR-Engage, which includes
//! scenario selection, scenario information display, and session control.
//! It manages the models for scenarios and terrain files, and coordinates
//! the interaction between the UI and the application backend.
class PLAYERSTATION_DLL DtVreStartPage : public DtVreHeaderFooterUIBase
{
   Q_OBJECT;
 
public:
   //! \brief Constructor
   //! \param app Reference to the player station application
   //! \param target_window Name of the window to display in (empty for default)
   //!
   //! Creates a new start page UI for the specified application and target window.
   DtVreStartPage(DtPlayerStationApp& app, const std::string& target_window = "");
 
   //! \brief Destructor
   //!
   //! Cleans up resources used by the start page.
   virtual ~DtVreStartPage() override;
 
   //! \brief Updates the start page each frame
   //! \param dt Time in seconds since the last update
   //!
   //! Called once per frame to update the start page UI elements.
   virtual void tick(double dt) override;
 
   //! \brief Initializes the main content of the page
   //!
   //! Sets up the main content area of the page, including the file models
   //! and QML components. Called during initialization.
   virtual void initMain() override;
 
   //! \brief Controls the background video playback
   //! \param visible True to play the video, false to pause it
   //!
   //! Controls whether the background video is playing or paused.
   virtual void setVideoPlaying(bool visible);
 
   //! \brief Sets the visibility of the start page
   //! \param visible True to show the page, false to hide it
   //!
   //! Controls whether the start page is visible. This override adds
   //! additional page-specific handling when visibility changes.
   virtual void setVisibility(bool visible) override;
 
   //! \brief Sets the visibility of the menu part of the page
   //! \param visible True to show the menu, false to hide it
   //!
   //! Controls whether the menu portion of the start page is visible.
   //! This allows showing/hiding just the menu while keeping the rest
   //! of the page visible.
   virtual void setMenuVisibility(bool visible);
 
   //! \brief Gets the QML interface singleton
   //! \return Pointer to the QML interface singleton
   //!
   //! Returns a pointer to the QML interface singleton used by this page.
   virtual DtVreStartPageQml* getSingleton() const;
 
protected:
   //! \brief Handles application mode changes
   //! \param newAppMode Identifier of the new application mode
   //! \param oldAppMode Identifier of the previous application mode
   //!
   //! Updates the page when the application mode changes, ensuring the UI
   //! reflects the current mode appropriately.
   virtual void appModeUpdated(const std::string& newAppMode, const std::string& oldAppMode) override;
 
protected:
   //! \brief QML interface singleton
   //!
   //! Managed pointer to the QML interface singleton for this page.
   QScopedPointer<DtVreStartPageQml> myQmlSingleton;
 
   //! \brief Model containing available scenarios
   //!
   //! File model for the list of available scenarios.
   DtRecursiveFileModel myScenariosModel;
 
   //! \brief Model containing available terrain files
   //!
   //! File model for the list of available terrain files.
   DtRecursiveFileModel myTerrainsModel;
};
 
} // namespace makVre