menuState.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file menuState.h
//! \brief Defines the DtMenuState class for menu-based application states
//!
//! This file contains the DtMenuState class which serves as a base class for
//! all states that display a menu interface to the user. It manages the common
//! functionality shared by menu-based states, including visual effects, input
//! handling, and UI page management.
 
#pragma once
 
#include "vrePlayerStation/export.h"
#include "vrePlayerStation/playerStationState.h"
 
#include "vreMessageManager/vreMessage.h"
 
namespace makVrv
{
class DtObserver;
}
 
namespace makVre
{
class DtPlayerStationApp;
class DtVreAppPage;
 
//! \brief Structure for storing depth of field camera settings
//!
//! DtDepthOfFieldSettings stores depth of field camera settings that control
//! the visual blur effect applied when menu states are active. These settings
//! are cached when entering a menu state and restored when exiting.
struct DtDepthOfFieldSettings
{
   //! \brief Whether auto-focus is enabled
   bool myDofUseAutoFocus;
 
   //! \brief Focal depth value in meters
   //!
   //! Distance at which objects are in perfect focus
   double myDofFocalDepth;
 
   //! \brief Focal range value in meters
   //!
   //! Distance range around the focal point where objects remain in focus
   double myDofFocalRange;
};
 
//! \brief Base class for all menu-based application states
//!
//! DtMenuState provides common functionality for states that display a menu
//! interface to the user. It manages the application page that contains the menu,
//! handles input events like Escape key and Back button clicks, and applies
//! visual effects like depth of field blur to emphasize the menu.
//!
//! Derived states implement specific menu interfaces, such as the main menu,
//! settings menu, role selection menu, or session selection menu.
class PLAYERSTATION_DLL DtMenuState : virtual public DtPlayerStationState
{
public:
   //! \brief Constructor
   //! \param app Reference to the player station application
   //!
   //! Initializes a new menu state with a reference to the application.
   //! Registers message handlers for input events.
   DtMenuState(DtPlayerStationApp& app);
 
   //! \brief Virtual destructor
   //!
   //! Ensures proper cleanup of derived menu state classes.
   virtual ~DtMenuState() override;
 
   //! \brief Updates the menu state each frame
   //! \param dt Time elapsed since the last update in seconds
   //!
   //! Called once per frame to update the menu state. This handles animation
   //! updates, timed transitions, and other continuous operations for the menu.
   virtual void tick(double dt) override;
 
   //! \brief Called when entering this state
   //! \param args Arguments passed from the previous state
   //!
   //! Initializes the menu state when it is pushed onto the state stack.
   //! This typically involves creating the UI page, caching camera settings,
   //! applying depth of field effects, and setting up the menu environment.
   virtual void onEnter(const DtPlayerStationStateArgs* args) override;
 
   //! \brief Called when exiting this state
   //!
   //! Cleans up resources when the menu state is removed from the state stack.
   //! This typically involves hiding the UI page, restoring cached camera settings,
   //! and removing depth of field effects.
   virtual void onExit() override;
 
   //! \brief Called when this state becomes the top state again
   //! \param args Arguments passed when exposing this state
   //!
   //! Handles the case when a state that was pushed on top of this one is popped,
   //! making this menu state the active state again. This typically refreshes the
   //! UI to reflect any changes made while this state was covered.
   virtual void onExposed(const DtPlayerStationStateArgs* args) override;
 
   //! \brief Called when another state is pushed on top of this one
   //!
   //! Handles the case when a new state is pushed on top of this menu state.
   //! This typically involves pausing menu animations or temporarily hiding
   //! UI elements that would otherwise be visible underneath.
   virtual void onStacked() override;
 
protected:
   //! \brief Handles Escape key press messages
   //! \param message The escape key message to process
   //! \return Message handling result
   //!
   //! Processes escape key press events, typically used to navigate back
   //! or close the current menu. The default implementation pops this state
   //! from the stack, returning to the previous state.
   virtual DtVreMessageResult handleEscKey(DtVreMessage* message);
 
   //! \brief Handles application mode change messages
   //! \param message The application mode message to process
   //! \return Message handling result
   //!
   //! Processes notifications about application mode changes, such as
   //! transitioning between normal, admin, or lockdown modes. Updates the
   //! UI and available options based on the new mode.
   virtual DtVreMessageResult handleAppModeUpdated(DtVreMessage* message);
 
   //! \brief Handles back button click messages
   //! \param message The back button message to process
   //! \return Message handling result
   //!
   //! Processes click events from the back button in the UI. Similar to the
   //! escape key handler, this typically pops the current state from the stack.
   virtual DtVreMessageResult handleBackButtonClicked(DtVreMessage* message);
 
   //! \brief Updates the state of UI buttons in the application page
   //!
   //! Updates the enabled/disabled state of buttons in the UI based on
   //! current application state and context. This is called when the state
   //! changes or becomes visible again after being covered by another state.
   virtual void updateAppPageButtons();
 
protected:
   //! \brief Shared pointer to the UI page
   //!
   //! Reference to the QML-based UI page that displays the menu interface.
   //! This page is created when entering the state and destroyed when exiting.
   std::shared_ptr<DtVreAppPage> myAppPage;
 
   //! \brief Cached observer mode value
   //!
   //! Stores the original observer mode that was active before entering this state.
   //! This value is saved in onEnter() and restored in onExit() to ensure the
   //! application returns to its previous visual state when the menu is closed.
   int myCachedObserverMode;
 
   //! \brief Cached sensor mode value
   //!
   //! Stores the original sensor mode that was active before entering this state.
   //! This value is saved in onEnter() and restored in onExit() to ensure the
   //! application returns to its previous visual state when the menu is closed.
   std::string myCachedSensorMode;
 
   //! \brief Cached depth of field settings
   //!
   //! Stores the original depth of field camera settings that were active before
   //! entering this state. When a menu is shown, a depth of field blur effect
   //! is typically applied to the 3D scene to emphasize the menu interface.
   //! These settings are restored when exiting the menu state.
   DtDepthOfFieldSettings myCachedDepthOfFieldSettings;
};
 
} // namespace makVre