extendedEngagedState.h

Go to the documentation of this file.

/******************************************************************************
 * Copyright (c) 2025 MAK Technologies, Inc.
 * All rights reserved.
 ******************************************************************************/
 
//! \file extendedEngagedState.h
//! \brief Extended engaged state demonstrating custom player station state extension
//!
//! This example shows how to extend VR-Engage's built-in engaged state with
//! custom UI elements, message handling, and Qt Quick integration. It demonstrates
//! the player station state machine extension pattern.
 
#pragma once
 
#include "vrePlayerStation/engagedState.h"
#include "vrePlayerStation/playerStationState.h"
#include "vreMessageManager/vreMessage.h"
 
class QQuickItem;
 
namespace makVre
{
class DtExampleChatWindow;
 
//! \brief Extended engaged state demonstrating custom UI and message handling.
//!
//! This class shows how to extend VR-Engage's built-in DtEngagedState with custom
//! functionality. It demonstrates proper integration with the Qt framework, state
//! lifecycle management, and VR-Engage message handling patterns.
//!
//! Key patterns demonstrated:
//! - Player station state extension and registration
//! - State lifecycle methods (onEnter, onExit, onStacked, onExposed)
//! - Qt Quick window management within a state
//! - VR-Engage message handler registration and cleanup
//! - Proper resource lifecycle management
//!
//! This is a REUSABLE pattern for any custom player station state that needs to:
//! - Add custom UI elements during specific states
//! - Handle simulation messages specific to a state
//! - Manage Qt-based windows with proper show/hide on state transitions
class DtExtendedEngagedState : public DtEngagedState
{
public:
   //! \brief Constructs the extended engaged state.
   //!
   //! \param app The player station application instance managing this state
   DtExtendedEngagedState(DtPlayerStationApp& app);
 
   //! \brief Destructor for cleanup of state resources.
   virtual ~DtExtendedEngagedState() override;
 
   //! \brief Called when transitioning into this state.
   //!
   //! This override demonstrates the proper pattern for state initialization:
   //! - Creating or showing custom UI windows
   //! - Registering message handlers specific to this state
   //! - Calling base class onEnter to maintain proper state chain
   //!
   //! \param args Optional state transition arguments
   virtual void onEnter(const DtPlayerStationStateArgs* args) override;
 
   //! \brief Called when transitioning out of this state.
   //!
   //! This override demonstrates proper cleanup patterns:
   //! - Hiding or closing custom UI windows
   //! - Unregistering message handlers to prevent leaks
   //! - Calling base class onExit to maintain proper state chain
   virtual void onExit() override;
 
   //! \brief Called each frame while this state is active.
   //!
   //! \param dt Delta time in seconds since last tick
   virtual void tick(double dt) override;
 
   //! \brief Called when this state becomes the active state after being stacked.
   //!
   //! This demonstrates showing UI elements when the state becomes visible again.
   virtual void onExposed() override;
 
   //! \brief Called when another state is pushed on top of this state.
   //!
   //! This demonstrates hiding UI elements when the state is no longer visible.
   virtual void onStacked() override;
 
   //! \brief Handles incoming text messages from the simulation.
   //!
   //! This method demonstrates the VR-Engage message handler pattern:
   //! - Type-safe message casting using ASSERT_TYPE
   //! - Accessing message data fields
   //! - Using entity resolver for display names
   //! - Returning HANDLED to indicate message was processed
   //!
   //! \param message The VR-Engage message to handle
   //! \return HANDLED if message was processed, UNHANDLED otherwise
   virtual DtVreMessageResult handleTextMessage(DtVreMessage* message);
 
protected:
   //! \brief Custom Qt Quick chat window managed by this state.
   //!
   //! Lifecycle: Created on first onEnter, reused on subsequent enters.
   //! The state is responsible for showing/hiding this window appropriately.
   DtExampleChatWindow* myChatWindow;
};
} // namespace makVre