appLauncherComponent.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file appLauncherComponent.h
//! \brief Defines the DtAppLauncherComponent class that launches external applications when a player engages in a role.
//!
//! The component provides functionality to launch, position, and control external applications within the VR
//! environment. It can be configured to specify application paths, window geometry, and behavior when disengaging from
//! roles.
//!
//! \ingroup vreCommonComponents
 
#pragma once
 
#include "vreCommonComponents/export.h"
#include "vrePlayerStation/playerComponent.h"
 
// Must be included before any Qt header
 
#include <QObject>
#include <QProcess>
 
#include <string>
 
namespace makVrv
{
class DtDe;
}
 
namespace makVre
{
class DtInitTable;
class DtPlayerStation;
 
namespace AppLauncherComponentConfig
{
//! \ingroup RoleConfigParams
//! \defgroup AppLauncherComponentRoleParams App Launcher Component Role Parameters
//! \roleInherits{PlayerComponentRoleParams}
//! Configuration Options for app launcher component role.
//! @{
 
//! \vreRoleParam{application,string,"",appLauncherComponent,Path to the application executable to launch when engaging in the role.}
constexpr const char* application = "application";
 
//! \vreRoleParam{arguments,string,"",appLauncherComponent,Command-line arguments to pass to the launched application.}
constexpr const char* arguments = "arguments";
 
//! \vreRoleParam{height,int,768,appLauncherComponent,Desired height in pixels for the launched application window.}
constexpr const char* height = "height";
 
//! \vreRoleParam{positionX,int,100,appLauncherComponent,Desired X position in pixels for the launched application window.}
constexpr const char* positionX = "positionX";
 
//! \vreRoleParam{positionY,int,300,appLauncherComponent,Desired Y position in pixels for the launched application window.}
constexpr const char* positionY = "positionY";
 
//! \vreRoleParam{shutdownOnDisengage,bool,true,appLauncherComponent,Whether to terminate the launched application when disengaging from the role.}
constexpr const char* shutdownOnDisengage = "shutdownOnDisengage";
 
//! \vreRoleParam{vreBackOnTopDelay,float,8.0,appLauncherComponent,Delay in seconds before bringing the VR Engage window back to the foreground after launching the application.}
constexpr const char* vreBackOnTopDelay = "vreBackOnTopDelay";
 
//! \vreRoleParam{width,int,1024,appLauncherComponent,Desired width in pixels for the launched application window.}
constexpr const char* width = "width";
 
//! \vreRoleParam{windowTitle,string,"",appLauncherComponent,Window title of the launched application used for finding and positioning the window.}
constexpr const char* windowTitle = "windowTitle";
 
//! \vreRoleParam{workingDirectory,string,"",appLauncherComponent,Working directory for the launched application process.}
constexpr const char* workingDirectory = "workingDirectory";
 
//! @}
} // namespace AppLauncherComponentConfig
 
//! \brief Type identifier for DtAppLauncherComponent component
constexpr const char* DtAppLauncherComponentType = "DtAppLauncherComponent";
 
//! \brief Component for launching and managing external applications within the VR engagement environment
//!
//! DtAppLauncherComponent allows the system to launch external applications when a player engages in a role.
//! It provides capabilities to configure application paths, working directories, command-line arguments,
//! as well as control the window positioning, sizing, and lifecycle management of the launched application.
class VRECOMMONCOMPONENTS_DLL DtAppLauncherComponent : public QObject, public DtPlayerComponent
{
   Q_OBJECT
 
public:
   //! \brief Constructor for DtAppLauncherComponent
   //!
   //! Initializes component properties with default values.
   DtAppLauncherComponent();
 
   //! \brief Virtual destructor for DtAppLauncherComponent
   //!
   //! Ensures proper cleanup of resources when the component is destroyed.
   virtual ~DtAppLauncherComponent() override;
 
   //! \brief Initializes the component with configuration from Lua
   //!
   //! Sets up the component based on provided configuration, including application path,
   //! working directory, command-line arguments, window geometry, and behavior settings.
   //! Launches the configured application and sets up signal connections for process events.
   //!
   //! \param station Pointer to the player station this component belongs to
   //! \param config Configuration table containing initialization parameters
   //! \return True if initialization succeeds, false otherwise
   virtual bool initialize(DtPlayerStation* station, DtInitTable& config) override;
 
   //! \brief Updates the component state
   //!
   //! Called each frame to handle component logic. Manages window positioning
   //! and ensures the VR Engage window returns to foreground after a configured delay.
   //!
   //! \param dt Delta time in seconds since the last tick
   virtual void tick(double dt) override;
 
   //! \brief Repositions and resizes the launched application window
   //!
   //! Attempts to find the window by title and applies the configured position and size.
   //!
   //! \return True if the window was found and positioned, false otherwise
   virtual bool repositionAndResizeWindow();
 
   //! \brief Shuts down the component
   //!
   //! Removes attribute callbacks and terminates the launched process
   //! if configured to do so when disengaging.
   virtual void shutdown() override;
 
   //! \brief Returns the component type identifier
   //! \return The component type string
   virtual const char* type() const override;
 
public slots:
   //! \brief Slot called when the launched process has started
   //!
   //! Logs a success message when the external process starts successfully.
   void handleProcessStarted();
 
   //! \brief Slot called when the launched process fails to start
   //!
   //! Logs a warning when the external process fails to start.
   //!
   //! \param error The process error that occurred
   void handleProcessFailed(QProcess::ProcessError error);
 
   //! \brief Slot called when the launched process finishes execution
   //!
   //! Cleans up resources and removes the process reference from the attribute store.
   //!
   //! \param exitCode The exit code returned by the process
   //! \param exitStatus The exit status of the process
   void handleProcessFinished(int exitCode, QProcess::ExitStatus exitStatus);
 
protected:
   //! \brief Called when the current application-level state changes
   //!
   //! Handles state transitions, particularly when entering the ENGAGED state.
   //!
   //! \param state The new application state
   virtual void onCurrentStateChanged(std::string state);
 
protected:
   //! \brief Flag indicating whether to shut down the launched application when disengaging
   bool myShutdownOnDisengage;
 
   //! \brief Pointer to the QProcess object representing the launched application
   QProcess* myProcess;
 
   //! \brief Flag indicating whether the window has been positioned
   bool myWindowPositioned;
 
   //! \brief Desired height for the launched application window in pixels
   int myHeight;
 
   //! \brief Desired width for the launched application window in pixels
   int myWidth;
 
   //! \brief Desired X position for the launched application window
   int myPositionX;
 
   //! \brief Desired Y position for the launched application window
   int myPositionY;
 
   //! \brief Window title of the launched application used for finding the window handle
   std::string myWindowTitle;
 
   //! \brief Delay in seconds before bringing the VR Engage window back to the foreground
   float myBackOnTopDelay;
};
 
} // namespace makVre