vreLoadingPage.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file vreLoadingPage.h
//! \brief Defines the loading page UI component for VR-Engage
//!
//! This file contains the DtVreLoadingPage class which provides the UI component
//! for displaying loading progress during resource-intensive operations.
//! It presents a progress bar, status messages, and visual elements to inform
//! the user about the current loading status and estimated completion time.
 
#pragma once
 
#include "vrePlayerStation/export.h"
#include "vrePlayerStation/vreHeaderFooterUIBase.h"
 
#include <QObject>
 
class QQuickItem;
class QTcpServer;
class QTcpSocket;
 
namespace makVre
{
//! \brief Forward declaration of the player station application class
class DtPlayerStationApp;
 
//! \brief UI component for displaying loading progress in VR-Engage
//!
//! DtVreLoadingPage provides a user interface for displaying loading progress
//! during resource-intensive operations like terrain or scenario loading.
//! It includes a progress bar, status text, and timer functionality to show
//! both current progress and estimated time remaining. The page inherits from
//! DtVreHeaderFooterUIBase to maintain consistent UI styling with the rest
//! of the application.
class PLAYERSTATION_DLL DtVreLoadingPage : 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 loading page UI component associated with the given application
   //! and target window. The component starts hidden and must be shown explicitly.
   DtVreLoadingPage(DtPlayerStationApp& app, const std::string& target_window = "");
 
   //! \brief Virtual destructor
   //!
   //! Ensures proper cleanup of loading page resources.
   virtual ~DtVreLoadingPage() override;
 
   //! \brief Updates the loading page each frame
   //! \param dt Time in seconds since the last update
   //!
   //! Called once per frame to update the loading page UI elements.
   //! This may include progress bar animations, timer updates, and
   //! any other time-dependent visual effects.
   virtual void tick(double dt) override;
 
   //! \brief Initializes the loading page UI
   //!
   //! Sets up the UI elements, connects signals and slots, and prepares
   //! the loading page for display. This is called automatically during
   //! construction but can be called again if the UI needs to be reset.
   virtual void initMain() override;
 
   //! \brief Sets the visibility of the loading page
   //! \param visible True to show the page, false to hide it
   //!
   //! Controls whether the loading page is visible to the user.
   //! This override ensures any updated information about the page
   //! is properly handled when visibility changes.
   virtual void setVisibility(bool visible) override;
 
   //! \brief Sets the maximum expected loading time
   //! \param ms Maximum loading time in milliseconds
   //!
   //! Sets the maximum time value for the progress bar, establishing the scale
   //! against which elapsed time is measured. This affects the visual width
   //! of the progress bar and any time remaining calculations.
   virtual void setMaximumTime(int ms);
 
   //! \brief Sets the current elapsed loading time
   //! \param ms Current elapsed time in milliseconds
   //!
   //! Updates the elapsed time displayed on the loading page and the current
   //! position of the progress bar. This should be a value between 0 and the
   //! maximum time set with setMaximumTime().
   virtual void setElapsedTime(int ms);
 
   //! \brief Sets the progress bar percentage directly
   //! \param percent Progress percentage (0-100)
   //!
   //! Updates the progress bar to display the specified percentage of completion.
   //! This is an alternative to setElapsedTime() that allows setting the progress
   //! directly as a percentage rather than calculating it from elapsed time.
   virtual void setProgress(int percent = 100);
 
   //! \brief Sets the text displayed on the loading bar
   //! \param msg Text message to display
   //!
   //! Updates the status text displayed on or near the loading bar.
   //! This is typically used to indicate the current operation being performed,
   //! such as "Loading terrain..." or "Initializing entities...".
   virtual void setLoadingBarText(const QString& msg);
 
   //! \brief Resets the progress bar to initial state
   //!
   //! Resets the position of the progress bar and the elapsed time to zero.
   //! This is typically called when starting a new loading operation or
   //! when restarting the current one.
   virtual void resetProgressBar();
 
   //! \brief Gets the current elapsed loading time
   //! \return Current elapsed time in milliseconds
   //!
   //! Returns the current elapsed time being displayed on the loading page.
   //! This may be used to calculate progress percentages or time remaining.
   virtual int getElapsedTime() const;
 
   //! \brief Gets the random seed for loading screen imagery
   //! \return Seed value for random image generation
   //!
   //! Returns the random seed value used for generating visual elements
   //! on the loading screen. This allows for consistent visuals across
   //! multiple instances or loading operations.
   virtual int getImageSeed() const;
 
   //! \brief Starts the loading timer
   //!
   //! Begins the timer that tracks elapsed loading time. This is typically
   //! called when a loading operation begins to provide accurate timing.
   virtual void startTimer();
 
   //! \brief Restarts the loading timer
   //!
   //! Resets and restarts the timer that tracks elapsed loading time.
   //! This is useful when a loading operation is restarted or when
   //! switching between different loading phases.
   virtual void restartTimer();
 
   //! \brief Stops the loading timer
   //!
   //! Pauses the timer that tracks elapsed loading time. This is typically
   //! called when a loading operation completes or is paused.
   virtual void stopTimer();
};
} // namespace makVre