vreChatWindow.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file vreChatWindow.h
//! \brief Defines the chat window component for in-application communication
//!
//! This file contains the classes that implement the chat functionality in VR-Engage,
//! including the chat window UI, message handling, channel management, and text
//! formatting. The chat system allows users to communicate with other participants
//! in a simulation session through configurable channels.
 
#pragma once
 
#include "vrePlayerStation/export.h"
#include "vrePlayerStation/vreChatWindowModel.h"
 
#include "vreMessageManager/vreMessage.h"
 
#include "vreUtil/attribute.h"
 
#include <QObject>
 
class QQuickItem;
 
namespace makVre
{
class DtPlayerStationApp;
 
//! \brief Structure defining a chat communication channel
//!
//! ChannelInfo represents a communication channel in the chat system,
//! characterized by a name, associated force (friendly, enemy, etc.),
//! and activation status. This structure is designed to be accessible from QML
//! through the Q_PROPERTY mechanism, allowing the UI to display and interact
//! with channel information.
struct ChannelInfo
{
   Q_GADGET;
   //! \brief Channel name property exposed to QML
   Q_PROPERTY(QString channel MEMBER myChannelName);
 
   //! \brief Force identifier property exposed to QML
   Q_PROPERTY(int force MEMBER myForce);
 
   //! \brief Channel activation status property exposed to QML
   Q_PROPERTY(bool active MEMBER myActive);
 
   //! \brief List of entities in this channel property exposed to QML
   Q_PROPERTY(QStringList entities MEMBER myEntities);
 
public:
   //! \brief Default constructor
   ChannelInfo() = default;
 
   //! \brief Constructor with parameters
   //! \param ch Channel name
   //! \param f Force identifier (friendly=1, enemy=2, neutral=3, etc.)
   //! \param a Activation status (true if channel is currently active)
   ChannelInfo(QString ch, int f, bool a)
      : myChannelName(ch)
      , myForce(f)
      , myActive(a) {};
 
   //! \brief Name of the communication channel
   QString myChannelName;
 
   //! \brief Force identifier associated with this channel
   //! (Typically: 1=friendly, 2=enemy, 3=neutral, etc.)
   int myForce = 0;
 
   //! \brief Flag indicating if this channel is currently active
   bool myActive = false;
 
   //! \brief List of entities (participants) in this channel
   QStringList myEntities;
};
Q_DECLARE_METATYPE(makVre::ChannelInfo);
 
//! \brief QML interface for the VR-Engage chat system
//!
//! DtVreChatQML provides the bridge between the C++ chat functionality and
//! the QML-based UI. It exposes properties and methods that can be accessed
//! from QML to display chat messages, manage channels, and send/receive
//! communications. This class handles the business logic of the chat system,
//! including message formatting, channel management, and command processing.
class PLAYERSTATION_DLL DtVreChatQML : public QObject
{
   // Needed QT Objects
   Q_OBJECT;
 
   // Q_PROPERTY that can be set from qml
   //! \brief Index of the currently active chat channel
   Q_PROPERTY(int currentChannelIdx MEMBER myCurrentChannelIdx NOTIFY currentChannelIdxChanged);
 
   //! \brief Flag indicating if the chat window is pinned (always visible)
   Q_PROPERTY(bool pinChat MEMBER myPinChat NOTIFY pinChatChanged);
 
   //! \brief Current username for the chat system
   Q_PROPERTY(QString currentUsername READ getCurrentUsername WRITE setCurrentUsername NOTIFY currentUsernameChanged);
 
   //! \brief Model containing chat messages for display
   Q_PROPERTY(DtVreChatModel* chatModel READ getChat WRITE setChat NOTIFY chatChanged)
 
public: // General Items
   //! \brief Constructor
   //! \param app Reference to the player station application
   //! \param parent Parent QObject (default: nullptr)
   //!
   //! Creates a new chat QML interface associated with the specified application.
   //! The interface will be initialized with default settings and an empty chat model.
   explicit DtVreChatQML(DtPlayerStationApp& app, QObject* parent = nullptr);
 
   //! \brief Virtual destructor
   //!
   //! Ensures proper cleanup of chat resources.
   virtual ~DtVreChatQML() override;
 
   //! \brief Sends a message to the system channel
   //! \param message Text message to send to the system channel
   //!
   //! Sends a text message to the system notification channel, which is
   //! typically used for system events, errors, and information messages.
   //! These messages are visible to all users regardless of their channel settings.
   virtual void sendToSystemChannel(const std::string& message);
 
   //! \brief Converts plain text to HTML format for QML display
   //! \param inputText Plain text to convert
   //! \return HTML-formatted string
   //!
   //! Converts a plain text string to HTML format, handling special characters,
   //! links, and other formatting needed for proper display in QML text components.
   static std::string convertTextToHTML(const std::string& inputText);
 
   //! \brief Adds a channel to the available channels list
   //! \param channelInfo Information about the channel to add
   //! \param updateAvailableChannels Whether to update the UI after adding the channel
   //! \return True if channel was added successfully, false otherwise
   //!
   //! Adds a new communication channel to the chat system. If a channel with the
   //! same name and force already exists, it will be updated instead.
   virtual bool addChannel(const makVre::ChannelInfo& channelInfo, bool updateAvailableChannels = false);
 
   //! \brief Updates the list of available channels in the UI
   //!
   //! Refreshes the available channels list in the QML interface to reflect
   //! current channel state and availability.
   virtual void updateAvailableChannels();
 
   //! \brief Removes all channels from the chat system
   //!
   //! Clears all channels from the chat system, typically used when
   //! disconnecting from a session or changing scenarios.
   virtual void clearChannels();
 
   //! \brief Checks if a channel is currently active
   //! \param channelName Name of the channel to check
   //! \param force Force identifier of the channel
   //! \return True if the channel is active, false otherwise
   virtual bool isChannelActive(const QString& channelName, int force);
 
   //! \brief Gets the list of all available channels
   //! \return Constant reference to the vector of channel information
   virtual const std::vector<ChannelInfo>& getChannels() const { return myChannels; }
 
   //! \brief Switches to the first available channel
   //!
   //! Selects the first available channel as the active channel.
   //! Used when initializing the chat or when the current channel becomes unavailable.
   virtual void switchToFirstAvailableChannel();
 
   //! \brief Sets whether to use a custom username instead of entity name
   //! \param usingCustom True to use custom username, false to use entity name
   //!
   //! Controls whether the chat system uses a custom username specified by the user
   //! or automatically generates a username based on the entity information.
   virtual void setUsingCustomUsername(bool usingCustom) { myUsingCustomUsername = usingCustom; }
 
   //! \brief Checks if a custom username is being used
   //! \return True if using custom username, false if using auto-generated name
   virtual bool isUsingCustomUsername() const { return myUsingCustomUsername; }
 
   //! \brief Gets the entity marking text for username generation
   //! \return Current entity marking (call sign) text
   virtual QString entityMarkingText() const { return myEntityMarkingText; }
 
   //! \brief Sets the entity marking text for username generation
   //! \param val New entity marking (call sign) text
   virtual void setEntityMarkingText(QString val) { myEntityMarkingText = val; }
 
   //! \brief Gets the entity force identifier for username generation
   //! \return Current entity force identifier
   virtual int entityForce() const { return myEntityForce; }
 
   //! \brief Sets the entity force identifier for username generation
   //! \param val New entity force identifier
   virtual void setEntityForce(int val) { myEntityForce = val; }
 
   //! \brief Gets the entity role text for username generation
   //! \return Current entity role description
   QString entityRole() const { return myEntityRole; }
 
   //! \brief Sets the entity role text for username generation
   //! \param val New entity role description
   void setEntityRole(QString val) { myEntityRole = val; }
 
   //! \brief Updates the username based on current settings
   //!
   //! Regenerates the username based on the current settings (custom or auto-generated).
   //! Auto-generated usernames typically combine entity marking, force, and role.
   virtual void updateUsername();
 
   //! \brief Processes a slash command
   //! \param message Command message starting with a slash (/)
   //!
   //! Handles special commands that begin with a slash character, such as
   //! /help, /clear, /who, etc. This method is called from the send() method
   //! when a message begins with a slash.
   virtual void sendSlashCommand(const QString& message);
 
   //! \brief Sends a regular chat message to a specific channel
   //! \param message Text message to send
   //! \param channel Target channel name
   //! \param force Force identifier for the channel
   //!
   //! Sends a chat message to the specified channel. This method is called
   //! from the send() method for regular (non-command) messages.
   virtual void sendChatMessage(const QString& message, const QString& channel, const int force);
 
   //! \brief Processes a channel switching command
   //! \param channelCommand Command to switch channels (typically channel name)
   //! \return True if channel switch was successful, false otherwise
   //!
   //! Handles commands to switch between communication channels. This can be
   //! called directly or from a slash command like /channel [name].
   virtual bool sendChannelCommand(const QString& channelCommand);
 
public: // Invokable things
   //! \brief Processes and sends a message or command
   //! \param message Text message or command to process
   //!
   //! Main entry point for processing messages entered by the user. This method
   //! determines whether the message is a command (starts with slash) or a regular
   //! message, and routes it to the appropriate handler.
   //! This method is invokable from QML.
   Q_INVOKABLE virtual void send(const QString& message);
 
   //! \brief Cycles through available channels
   //! \param direction True to cycle forward, false to cycle backward
   //!
   //! Switches to the next or previous channel in the channel list based on the
   //! direction parameter. This method is invokable from QML.
   Q_INVOKABLE virtual void cycleChannels(bool direction);
 
   //! \brief Gets information about a specific channel
   //! \param idx Index of the channel to retrieve information for
   //! \return QVariant containing the channel information
   //!
   //! Retrieves detailed information about a channel at the specified index.
   //! The returned QVariant can be used in QML to display channel properties.
   //! This method is invokable from QML.
   Q_INVOKABLE virtual QVariant getChannelInfo(int idx);
 
   //! \brief Toggles the pinned state of the chat window
   //!
   //! Switches between pinned (always visible) and unpinned (auto-hide) states
   //! for the chat window. This method is invokable from QML.
   Q_INVOKABLE virtual void togglePinChat();
 
public:
   //! \brief Gets the current username
   //! \return Current username used in chat
   virtual QString getCurrentUsername();
 
   //! \brief Gets the chat message model
   //! \return Pointer to the current chat model
   virtual DtVreChatModel* getChat();
 
public slots:
   //! \brief Sets the current username
   //! \param username New username to use in chat
   void setCurrentUsername(QString username);
 
   //! \brief Sets the chat message model
   //! \param model New chat model to use
   void setChat(DtVreChatModel* model);
 
signals:
   //! \brief Signal emitted when the username changes
   //! \param username New username
   void currentUsernameChanged(QString username);
 
   //! \brief Signal emitted when the active channel changes
   //! \param channelIdx Index of the new active channel
   void currentChannelIdxChanged(int channelIdx);
 
   //! \brief Signal emitted when the chat model changes
   void chatChanged();
 
   //! \brief Signal emitted when the pinned state changes
   //! \param pinned New pinned state
   void pinChatChanged(bool pinned);
 
protected:
   // For entities engaged
   QString myCurrentUsername;
   bool myUsingCustomUsername;
   QString myEntityMarkingText;
   QString myEntityRole;
   int myEntityForce;
 
   // For channels
   DtFilename myCurrentChatConfigFile;
   DtFilename myDefaultChatConfigFile;
   std::vector<ChannelInfo> myChannels;
   int myCurrentChannelIdx;
 
   // For pinning chat.
   bool myPinChat;
 
   // The actual chat model
   QScopedPointer<DtVreChatModel> myChatModel;
 
   // reference to the playstationapp
   DtPlayerStationApp& myApp;
};
 
//! \brief Main chat window manager for VR-Engage
//!
//! DtVreChatWindow manages the chat window user interface in VR-Engage,
//! including its visibility, position, and content. It serves as the primary
//! interface between the application and the chat functionality, coordinating
//! message handling, configuration loading, and UI state management. This class
//! uses the DtVreChatQML class to bridge between C++ and the QML-based UI.
class PLAYERSTATION_DLL DtVreChatWindow : public QObject
{
   Q_OBJECT;
 
public:
   //! \brief Constructor
   //! \param app Reference to the player station application
   //!
   //! Creates a new chat window manager associated with the specified application.
   //! The constructor initializes the chat UI and establishes necessary connections
   //! to the message system for handling chat-related messages.
   DtVreChatWindow(DtPlayerStationApp& app);
 
   //! \brief Virtual destructor
   //!
   //! Ensures proper cleanup of chat window resources.
   virtual ~DtVreChatWindow() override;
 
   //! \brief Sets the visibility of the chat window
   //! \param visible True to show the window, false to hide it
   //!
   //! Controls the visibility of the entire chat window. This affects the
   //! root object of the chat UI, not individual components within it.
   virtual void setVisibility(bool visible);
 
   //! \brief Checks if the chat window is currently visible
   //! \return True if the chat window is visible, false otherwise
   virtual bool isVisible();
 
   //! \brief Checks if the full chat window is visible
   //! \return True if the full chat window is visible, false if minimized or hidden
   //!
   //! Determines if the chat window is fully visible, as opposed to being
   //! minimized or showing only a notification area.
   virtual bool isFullChatVisible();
 
   //! \brief Closes the chat window
   //!
   //! Hides the chat window and performs any necessary cleanup.
   virtual void close();
 
   //! \brief Opens the chat window
   //!
   //! Shows the chat window and ensures it's properly initialized.
   virtual void open();
 
   //! \brief Opens the chat window or gives it focus if already open
   //!
   //! If the chat window is already open, this gives it focus. Otherwise,
   //! it opens the window. This is typically used when the user invokes
   //! the chat functionality through a hotkey or menu option.
   virtual void openOrFocus();
 
   //! \brief Toggles the pinned state of the chat window
   //!
   //! Switches between pinned (always visible) and unpinned (auto-hide) states
   //! for the chat window. This affects how the chat behaves when the user
   //! interacts with other parts of the application.
   virtual void togglePinChat();
 
   //! \brief Gets the chat QML object
   //! \return Pointer to the chat QML interface, or nullptr if not available
   //!
   //! Provides access to the underlying DtVreChatQML object that manages
   //! the chat functionality. The caller does not take ownership of the
   //! returned pointer and should not delete it.
   DtVreChatQML* getChatObject();
 
   //! \brief Updates the chat window position based on application state
   //! \param state Current application state identifier
   //!
   //! Adjusts the position of the chat window based on the current state
   //! of the application. Different states may require different positioning
   //! to avoid interfering with other UI elements.
   virtual void updatePositionFromState(const std::string& state);
 
   //! \brief Gets the chat configuration file for a scenario
   //! \param scenarioFilename Filename of the scenario (can be empty)
   //! \return Path to the appropriate chat configuration file
   //!
   //! Determines the appropriate chat configuration file to use based on the
   //! scenario name. If a scenario-specific chat configuration exists, it will
   //! be returned; otherwise, the default chat configuration file is returned.
   virtual DtFilename getChatConfigFile(const DtFilename& scenarioFilename);
 
   //! \brief Updates chat channels based on a scenario file
   //! \param scenario Filename of the scenario
   //! \return True if the chat configuration changed, false otherwise
   //!
   //! Updates the available chat channels based on the specified scenario.
   //! Returns true if the chat configuration changed as a result of this update.
   virtual bool updateChatChannelsFromScenario(const DtFilename& scenario);
 
   //! \brief Updates chat channels from a configuration file
   //! \param chatConfigFile Path to the chat configuration file
   //! \return True if the chat configuration changed, false otherwise
   //!
   //! Loads chat channel definitions from the specified configuration file
   //! and updates the available channels. Returns true if the configuration
   //! changed as a result of this update.
   virtual bool updateChatChannelsFromConfigFile(const DtFilename& chatConfigFile);
 
protected:
   //! \brief Handles messages about player entity creation
   //! \param msg Pointer to the player created message
   //! \return Message handling result
   //!
   //! Processes notifications about new player entities being created,
   //! updating channel participant lists and potentially adjusting the
   //! current username if this is the local player.
   makVre::DtVreMessageResult handlePlayerCreatedMessage(DtVreMessage* msg);
 
   //! \brief Handles messages about player entity destruction
   //! \param msg Pointer to the player destroyed message
   //! \return Message handling result
   //!
   //! Processes notifications about player entities being removed,
   //! updating channel participant lists accordingly.
   makVre::DtVreMessageResult handlePlayerDestroyedMessage(DtVreMessage* msg);
 
   //! \brief Handles incoming chat messages
   //! \param msg Pointer to the incoming chat message
   //! \return Message handling result
   //!
   //! Processes incoming chat messages from other participants or the system,
   //! adding them to the appropriate channel and updating the UI.
   makVre::DtVreMessageResult handleIncomingChatMessage(DtVreMessage* msg);
 
   //! \brief Handles session status messages
   //! \param msg Pointer to the session status message
   //! \return Message handling result
   //!
   //! Processes notifications about changes to the VRF session status,
   //! adjusting the chat system's state accordingly.
   makVre::DtVreMessageResult handleVrfSessionStatusMessage(DtVreMessage* msg);
 
   //! \brief Handles changes to the current application state
   //! \param state New application state identifier
   //!
   //! Called when the application state changes, allowing the chat window
   //! to adjust its appearance, position, and behavior to suit the new state.
   virtual void onCurrentStateChanged(std::string state);
 
protected:
   //! \brief Chat QML interface object
   //!
   //! Manages the bridge between C++ and QML for chat functionality.
   std::unique_ptr<DtVreChatQML> myChatObject;
 
   //! \brief Root QML item for the chat window
   //!
   //! The top-level QML item that contains the entire chat window UI.
   QQuickItem* myRoot;
 
   //! \brief Reference to the player station application
   //!
   //! Provides access to application services during chat operations.
   DtPlayerStationApp& myApp;
 
   //! \brief Path to the default chat configuration file
   DtFilename myDefaultChatConfigFile;
 
   //! \brief Path to the current chat configuration file in use
   DtFilename myCurrentChatConfigFile;
 
protected:
   //! \brief Default configuration filename
   DtFilename myDefaultConfigFilename = "defaultChatConfig.mtl";
 
   //! \brief Directory containing default configuration files
   DtFilename myDefaultConfigDirectory = "$(APP_DIR)/settings";
 
   //! \brief Filename postfix for user-specific chat configurations
   DtFilename myDefaultChatConfigUserFilenamePostfix = "_ChatConfig.mtl";
 
   //! \brief Directory containing user-specific chat configurations
   DtFilename myDefaultChatConfigUserDirectory = "$(USER_DIR)/chatConfigs";
 
   //! \brief Member-scope instance of Attribute callback manager
   //!
   //! Used to manage Attribute change callback connections and ensure that all
   //! callbacks are unregistered when this class instance is destroyed.
   DtAttributeCallbackManager myAttributeCallbacks;
};
 
} // namespace makVre