vreHeaderFooterUIBase.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file vreHeaderFooterUIBase.h
//! \brief Defines the base class for UI components with header and footer
//!
//! This file contains the DtVreHeaderFooterUIBase class which provides a common
//! foundation for UI components that have a standard header and footer layout.
//! It manages the visibility, initialization, and event handling for these UI elements.
 
#pragma once
 
#include <vrePlayerStation/export.h>
#include "vreQtQuickRenderer/DtQtQuickRenderer.h"
#include "vreMessageManager/vreMessage.h"
 
#include <QObject>
 
class QQuickItem;
 
namespace makVre
{
//! \brief Forward declaration of the player station application class
class DtPlayerStationApp;
 
//! \brief Base class for UI components with header and footer
//!
//! DtVreHeaderFooterUIBase provides a foundation for UI components that use
//! a standard header and footer layout. It manages the visibility, initialization,
//! and event handling for these UI elements, as well as common dialogs like
//! settings and exit confirmation. This class simplifies the creation of
//! consistent UI components throughout the application.
class PLAYERSTATION_DLL DtVreHeaderFooterUIBase : public QObject
{
   Q_OBJECT
 
public:
   //! \brief Simple constructor
   //! \param app Reference to the player station application
   //! \param file Path to the QML file defining the UI
   //! \param target_window Name of the window to display in (empty for default)
   //!
   //! Creates a new UI component using the specified QML file for the given window.
   //! Uses default IDs for header, footer, and main content elements.
   DtVreHeaderFooterUIBase(DtPlayerStationApp& app, const std::string& file, const std::string& target_window = "");
 
   //! \brief Detailed constructor
   //! \param app Reference to the player station application
   //! \param file Path to the QML file defining the UI
   //! \param headerId ID of the header element in the QML
   //! \param footerId ID of the footer element in the QML
   //! \param mainContentId ID of the main content element in the QML
   //! \param target_window Name of the window to display in
   //!
   //! Creates a new UI component using the specified QML file with custom IDs
   //! for the header, footer, and main content elements. This allows for more
   //! fine-grained control over UI structure and appearance.
   DtVreHeaderFooterUIBase(DtPlayerStationApp& app, const std::string& file, const std::string& headerId,
      const std::string& footerId, const std::string& mainContentId, const std::string& target_window);
 
   //! \brief Virtual destructor
   //!
   //! Ensures proper cleanup of UI component resources.
   virtual ~DtVreHeaderFooterUIBase() override;
 
   //! \brief Core functionality methods
   //! @{
 
   //! \brief Initializes the main UI component
   //!
   //! Pure virtual method that must be implemented by derived classes to initialize
   //! the UI component. This typically involves setting up signals/slots connections,
   //! initial state, and other component-specific initialization.
   virtual void initMain() = 0;
 
   //! \brief Updates the UI component each frame
   //! \param dt Time in seconds since the last update
   //!
   //! Pure virtual method that must be implemented by derived classes to handle
   //! per-frame updates for the UI component. This is called once per frame
   //! and allows for animations, state updates, and other time-based operations.
   virtual void tick(double dt) = 0;
   //! @}
 
   //! \brief Visibility control methods
   //! @{
 
   //! \brief Sets the visibility of the entire UI component
   //! \param visible True to show the component, false to hide it
   //!
   //! Controls the visibility of the root object of this UI component.
   //! This affects the entire component, not individual elements within it.
   virtual void setVisibility(bool visible);
 
   //! \brief Checks if the UI component is visible
   //! \return True if the component is visible, false otherwise
   //!
   //! Determines whether the UI component is currently visible to the user.
   virtual bool isVisible();
 
   //! \brief Closes the UI component
   //!
   //! Convenience method that hides the UI component by calling setVisibility(false).
   virtual void close();
 
   //! \brief Opens the UI component
   //!
   //! Convenience method that shows the UI component by calling setVisibility(true).
   virtual void open();
   //! @}
 
   //! \brief Header control methods
   //! @{
 
   //! \brief Initializes the header portion of the UI
   //!
   //! Sets up the header elements and their initial state.
   //! This is typically called during component initialization.
   virtual void initHeader();
 
   //! \brief Checks if the header is visible
   //! \return True if the header is visible, false otherwise
   //!
   //! Determines whether the header portion of the UI is currently visible.
   virtual bool isHeaderVisible();
 
   //! \brief Sets the visibility of the header
   //! \param visible True to show the header, false to hide it
   //!
   //! Controls the visibility of the header portion of the UI.
   virtual void setHeaderVisiblility(bool visible);
 
   //! \brief Sets the title displayed in the header
   //! \param title Text to display as the menu title
   //!
   //! Updates the title text shown in the header area of the UI.
   virtual void setMenuTitle(const QString& title);
 
   //! \brief Sets the visibility of the cutout area in the header
   //! \param visible True to show the cutout area, false to hide it
   //!
   //! Controls the visibility of the cutout area in the header,
   //! which typically contains action buttons or status information.
   virtual void setShowCutoutVisible(bool visible);
 
   //! \brief Enables or disables a specific button in the header
   //! \param id Identifier of the button to modify
   //! \param enabled True to enable the button, false to disable it
   //!
   //! Controls whether a specific button in the header is enabled or disabled.
   //! Disabled buttons are typically grayed out and do not respond to clicks.
   virtual void setButtonEnabled(const std::string& id, bool enabled);
 
   //! \brief Checks if a specific button is enabled
   //! \param id Identifier of the button to check
   //! \return True if the button is enabled, false if disabled
   //!
   //! Determines whether a specific button in the header is currently enabled.
   virtual bool isButtonEnabled(const std::string& id);
 
   //! \brief Enables or disables all cutout controls
   //! \param enabled True to enable all controls, false to disable them
   //!
   //! Controls whether all buttons and controls in the cutout area are enabled or disabled.
   virtual void setAllCutoutControlsEnabled(bool enabled);
 
   //! \brief Sets the visibility of top-right controls
   //! \param visible True to show the controls, false to hide them
   //!
   //! Controls the visibility of controls located in the top-right area of the header.
   virtual void setShowTopRightControlsVisible(bool visible);
   //! @}
 
   //! \brief Footer control methods
   //! @{
 
   //! \brief Initializes the footer portion of the UI
   //!
   //! Sets up the footer elements and their initial state.
   //! This is typically called during component initialization.
   virtual void initFooter();
 
   //! \brief Checks if the footer is visible
   //! \return True if the footer is visible, false otherwise
   //!
   //! Determines whether the footer portion of the UI is currently visible.
   virtual bool isFooterVisible();
 
   //! \brief Sets the visibility of the footer
   //! \param visible True to show the footer, false to hide it
   //!
   //! Controls the visibility of the footer portion of the UI.
   virtual void setFooterVisiblility(bool visible);
 
   //! \brief Sets the visibility of the back button in the footer
   //! \param visible True to show the back button, false to hide it
   //!
   //! Controls the visibility of the back button located in the footer area.
   virtual void setShowBottomBackButtonVisible(bool visible);
   //! @}
 
   //! \brief Main content control methods
   //! @{
 
   //! \brief Checks if the main content is visible
   //! \return True if the main content is visible, false otherwise
   //!
   //! Determines whether the main content area of the UI is currently visible.
   virtual bool isMainContentVisible();
 
   //! \brief Sets the visibility of the main content
   //! \param visible True to show the main content, false to hide it
   //!
   //! Controls the visibility of the main content area of the UI.
   virtual void setMainContentVisibility(bool visible);
   //! @}
 
   //! \brief Message handling methods
   //! @{
 
   //! \brief Registers message handlers for this UI component
   //!
   //! Sets up handlers for messages that this UI component needs to process.
   //! This is typically called during initialization or when the component becomes active.
   virtual void registerMessageHandlers();
 
   //! \brief Deregisters message handlers for this UI component
   //!
   //! Removes handlers for messages that this UI component was processing.
   //! This is typically called during cleanup or when the component becomes inactive.
   virtual void deregisterMessageHandlers();
 
   //! \brief Handles back button click messages
   //! \param msg Pointer to the button click message
   //! \return Message handling result
   //!
   //! Processes messages generated when the back button is clicked.
   //! This typically navigates back to a previous screen or state.
   DtVreMessageResult handleBackButtonClicked(DtVreMessage* msg);
 
   //! \brief Handles escape key press messages
   //! \param msg Pointer to the key press message
   //! \return Message handling result
   //!
   //! Processes messages generated when the escape key is pressed.
   //! This typically closes dialogs or navigates back.
   DtVreMessageResult handleEscapeMessage(DtVreMessage* msg);
   //! @}
 
   //! \brief Gets the root UI element
   //! \return Pointer to the root QQuickItem
   //!
   //! Provides access to the root QQuickItem of this UI component.
   //! This can be used to directly manipulate the UI element tree if needed.
   QQuickItem* root();
 
public slots:
   //! \brief Settings dialog slots
   //! @{
 
   //! \brief Called when the settings dialog is opened
   //!
   //! Handles the opening of the settings dialog, performing any necessary
   //! initialization for the settings UI.
   virtual void slot_settingsOpened();
 
   //! \brief Called when the settings dialog is closed
   //!
   //! Handles the closing of the settings dialog, performing any necessary
   //! cleanup or state updates.
   virtual void slot_settingsClosed();
 
   //! \brief Called when display engine configuration is clicked
   //!
   //! Handles navigation to the display engine configuration settings page.
   virtual void slot_displayEngineConfigClicked();
 
   //! \brief Called when weather and environment settings are clicked
   //!
   //! Handles navigation to the weather and environment settings page.
   virtual void slot_weatherAndEnvClicked();
 
   //! \brief Called when advanced visual settings are clicked
   //!
   //! Handles navigation to the advanced visual settings page.
   virtual void slot_advancedVisualSettingsClicked();
 
   //! \brief Called when the about option is clicked
   //!
   //! Handles navigation to the about dialog or page.
   virtual void slot_aboutClicked();
 
   //! \brief Called when the sound volume is changed
   //! \param volume New volume level (typically 0.0 to 1.0)
   //!
   //! Handles changes to the sound volume setting.
   virtual void slot_soundVolumeChanged(qreal volume);
 
   //! \brief Called when sound enabled state is changed
   //! \param enabled True if sound is enabled, false otherwise
   //!
   //! Handles changes to the sound enabled/disabled setting.
   virtual void slot_soundEnabledChanged(bool enabled);
   //! @}
 
   //! \brief Exit confirmation dialog slots
   //! @{
 
   //! \brief Called when the exit confirmation dialog is opened
   //!
   //! Handles the opening of the exit confirmation dialog, preparing
   //! the UI and any state needed for the confirmation process.
   virtual void slot_exitOpened();
 
   //! \brief Called when the exit confirmation dialog is closed
   //!
   //! Handles the closing of the exit confirmation dialog, performing
   //! any necessary cleanup regardless of the user's choice.
   virtual void slot_exitClosed();
 
   //! \brief Called when exit is confirmed (Yes/OK clicked)
   //!
   //! Handles the user confirming the exit action, typically by
   //! initiating the actual exit process.
   virtual void slot_exitAccepted();
 
   //! \brief Called when exit is rejected (No/Cancel clicked)
   //!
   //! Handles the user rejecting the exit action, typically by
   //! returning to the previous state.
   virtual void slot_exitRejected();
   //! @}
 
   //! \brief Playback control slots
   //! @{
 
   //! \brief Called when the play button is clicked
   //!
   //! Handles requests to start or resume playback of the simulation.
   virtual void slot_playClicked();
 
   //! \brief Called when the pause button is clicked
   //!
   //! Handles requests to pause the simulation.
   virtual void slot_pauseClicked();
 
   //! \brief Called when the rewind button is clicked
   //!
   //! Handles requests to rewind or reset the simulation to a starting point.
   virtual void slot_rewindClicked();
   //! @}
 
   //! \brief Connection control slots
   //! @{
 
   //! \brief Called when the connection button is clicked
   //!
   //! Handles requests to manage connection settings or status.
   virtual void slot_connectionClicked();
   //! @}
 
   //! \brief Help system slots
   //! @{
 
   //! \brief Called when the help system is opened
   //!
   //! Handles the opening of the help dialog or overlay.
   virtual void slot_helpOpened();
 
   //! \brief Called when the help system is closed
   //!
   //! Handles the closing of the help dialog or overlay.
   virtual void slot_helpClosed();
   //! @}
 
   //! \brief Navigation control slots
   //! @{
 
   //! \brief Called when the back button is clicked
   //!
   //! Handles navigation requests to go back to a previous screen or state.
   virtual void slot_backClicked();
   //! @}
 
protected:
   //! \brief Updates the running state
   //! \param runState True if the simulation is running, false if paused
   //!
   //! Updates the UI to reflect the current running state of the simulation.
   //! This base implementation does nothing and should be overridden by derived classes.
   virtual void runningStateUpdated(bool runState) {};
 
   //! \brief Closes settings pages
   //! \param pageName Name of the page to keep open (empty to close all)
   //!
   //! Closes all settings pages, optionally keeping one specified page open.
   //! If no page name is passed, all pages are closed. If a page name is
   //! provided, every page except the specified one is closed.
   virtual void closeAllSettingsPages(std::string pageName = "");
 
   //! \brief Handles application mode updates
   //! \param newAppMode Identifier of the new application mode
   //! \param oldAppMode Identifier of the previous application mode
   //!
   //! Called when the application mode changes, allowing the UI
   //! to update its state appropriately for the new mode.
   virtual void appModeUpdated(const std::string& newAppMode, const std::string& oldAppMode);
 
   //! \brief Updates the modal dialog state
   //! \param open True if a modal dialog is open, false otherwise
   //!
   //! Notifies the system about the presence of a modal dialog or popup.
   //! This allows other components to adjust their behavior appropriately
   //! when modal dialogs are active.
   virtual void updateModalState(bool open);
 
   //! \brief Internal message handlers
   //! @{
 
   //! \brief Handles application mode change messages
   //! \param msg Pointer to the application mode message
   //! \return Message handling result
   //!
   //! Processes messages about changes to the application mode.
   DtVreMessageResult handleApplicationMode(DtVreMessage* msg);
 
   //! \brief Handles session play state messages
   //! \param msg Pointer to the play state message
   //! \return Message handling result
   //!
   //! Processes messages about changes to the session play state
   //! (playing, paused, etc.).
   DtVreMessageResult handleSessionPlayState(DtVreMessage* msg);
 
   //! \brief Handles help toggle messages
   //! \param msg Pointer to the help toggle message
   //! \return Message handling result
   //!
   //! Processes messages requesting to show or hide the help system.
   DtVreMessageResult handleToggleHelp(DtVreMessage* msg);
   //! @}
 
protected:
   //! \brief Reference to the player station application
   //!
   //! Provides access to application services and state.
   DtPlayerStationApp& myApp;
 
   //! \brief Pointer to the root QML item
   //!
   //! Reference to the root UI element for this component.
   QQuickItem* myRoot;
 
   //! \brief Name of the target window
   //!
   //! Identifies which window the UI should be displayed in.
   std::string myTargetWindow;
 
   //! \brief Path to the QML file
   //!
   //! Specifies the QML file that defines this UI component.
   std::string myTargetFile;
 
   //! \brief ID of the header element
   //!
   //! Identifies the header element in the QML structure.
   std::string myHeaderId;
 
   //! \brief ID of the footer element
   //!
   //! Identifies the footer element in the QML structure.
   std::string myFooterId;
 
   //! \brief ID of the main content element
   //!
   //! Identifies the main content element in the QML structure.
   std::string myMainContentId;
};
} // namespace makVre