exampleQtQuick.h

Go to the documentation of this file.

/******************************************************************************
 * Copyright (c) 2025 MAK Technologies, Inc.
 * All rights reserved.
 ******************************************************************************/
 
//! \file exampleQtQuick.h
//! \brief Qt Quick chat window demonstrating Qt Model/View integration with VR-Engage
 
#pragma once
 
#include "export.h"
#include "vrvUtil/signalslib.h"
 
#include <QObject>
#include <QAbstractListModel>
 
class QQuickItem;
 
namespace makVre
{
//! \brief Data container for a single chat message entry.
//!
//! This simple data class demonstrates the pattern for Qt-compatible data objects.
//! All fields use Qt types (QString, double) for seamless integration with Qt models.
class DtChatEntry
{
public:
   //! \brief Default constructor initializing empty chat entry.
   DtChatEntry();
 
   //! \brief Constructor with all chat entry fields.
   //!
   //! \param sender Entity name (marking text) who sent the message
   //! \param receiver Entity name (marking text) who received the message
   //! \param time Simulation time when message was sent
   //! \param message The text content of the message
   DtChatEntry(const QString& sender, const QString& receiver, const double time, const QString& message);
 
   //! \brief Gets the sender's entity name.
   QString getSender() const;
 
   //! \brief Sets the sender's entity name.
   void setSender(const QString& sender);
 
   //! \brief Gets the receiver's entity name.
   QString getReceiver() const;
 
   //! \brief Sets the receiver's entity name.
   void setReceiver(const QString& receiver);
 
   //! \brief Gets the simulation time of the message.
   double getTime() const;
 
   //! \brief Sets the simulation time of the message.
   void setTime(const double time);
 
   //! \brief Gets the message text content.
   QString getMessage() const;
 
   //! \brief Sets the message text content.
   void setMessage(const QString& message);
 
protected:
   QString mySender;   //!< Entity name of message sender
   QString myReceiver; //!< Entity name of message receiver
   double myTime;      //!< Simulation time of message
   QString myMessage;  //!< Text content of message
};
 
//! \brief Qt model for chat messages providing data to QML ListView.
//!
//! This class demonstrates the REUSABLE pattern for creating custom Qt models
//! that expose C++ data to QML user interfaces. Key concepts:
//! - Inheriting from QAbstractListModel for list-based data
//! - Defining custom roles for QML property access
//! - Implementing required virtual methods (rowCount, data, roleNames)
//! - Proper model change notifications (beginInsertRows, endInsertRows, etc.)
//!
//! This pattern can be adapted for any list-based data that needs to be
//! displayed in a QML ListView or Repeater.
class DtChatQmlModel : public QAbstractListModel
{
   Q_OBJECT;
 
public:
   //! \brief Custom roles for accessing chat entry fields from QML.
   //!
   //! Qt roles allow QML to access C++ data using named properties.
   //! Start at Qt::UserRole + 1 to avoid conflicts with standard roles.
   enum ChatRoles
   {
      SenderRole = Qt::UserRole + 1, //!< Access sender name via "sender" in QML
      ReceiverRole,                  //!< Access receiver name via "receiver" in QML
      TimeRole,                      //!< Access message time via "time" in QML
      MessageRole                    //!< Access message text via "msg" in QML
   };
 
   //! \brief Constructor initializing the model.
   //!
   //! \param parent Optional parent QObject for Qt ownership hierarchy
   DtChatQmlModel(QObject* parent = nullptr);
 
   //! \brief Adds a new chat entry to the model.
   //!
   //! This demonstrates proper model update notifications:
   //! - beginInsertRows notifies views that data is being added
   //! - Actual data modification
   //! - endInsertRows triggers view updates
   //!
   //! \param entry The chat entry to add to the model
   virtual void addChatEntry(const DtChatEntry& entry);
 
   //! \brief Clears all chat entries from the model.
   //!
   //! Uses beginResetModel/endResetModel for bulk changes.
   virtual void clear();
 
   //! \brief Finds the index of a message by its text content.
   //!
   //! \param messageName The message text to search for
   //! \return Index of the message, or -1 if not found
   virtual int getIndexOfName(const QString& messageName);
 
   //! \brief Gets the message text at a specific index.
   //!
   //! \param idx The index of the message
   //! \return The message text
   virtual QString getMessage(const int idx);
 
   // Required QAbstractListModel overrides for Qt Model/View framework
 
   //! \brief Removes rows from the model.
   //!
   //! \param row The row index to remove
   //! \param column Unused for list models (default 0)
   //! \param parent Unused for list models
   //! \return true if removal succeeded
   virtual bool removeRows(int row, int column = 0, const QModelIndex& parent = QModelIndex()) override;
 
   //! \brief Returns the number of entries in the model.
   //!
   //! \param parent Unused for list models
   //! \return Number of chat entries
   virtual int rowCount(const QModelIndex& parent = QModelIndex()) const override;
 
   //! \brief Returns data for a specific role at a given index.
   //!
   //! This is the core method QML uses to access data.
   //!
   //! \param index The model index of the item
   //! \param role The data role being requested (SenderRole, MessageRole, etc.)
   //! \return The requested data as a QVariant
   virtual QVariant data(const QModelIndex& index, int role = Qt::DisplayRole) const override;
 
   //! \brief Sets data for a specific role at a given index.
   //!
   //! \param index The model index of the item
   //! \param value The new value to set
   //! \param role The data role being modified
   //! \return true if data was successfully set
   virtual bool setData(const QModelIndex& index, const QVariant& value, int role) override;
 
protected:
   //! \brief Maps role enum values to QML property names.
   //!
   //! This method tells Qt how to expose roles as named properties in QML.
   //! For example, SenderRole becomes accessible as "sender" in QML.
   //!
   //! \return Hash mapping role integers to QML property names
   virtual QHash<int, QByteArray> roleNames() const override;
 
   QList<DtChatEntry> myChatEntries; //!< Storage for all chat entries
};
 
//! \brief Qt Quick window managing the chat UI.
//!
//! This class demonstrates the REUSABLE pattern for integrating Qt Quick (QML)
//! windows into VR-Engage. Key aspects:
//! - Loading QML files using DtQtQuickRenderer
//! - Exposing C++ objects to QML via context properties
//! - Managing window visibility and lifecycle
//! - Using Q_INVOKABLE for QML-callable methods
//!
//! This pattern applies to any custom Qt Quick UI that needs to be integrated
//! with VR-Engage player stations.
class DtExampleChatWindow : public QObject
{
   Q_OBJECT;
 
public:
   //! \brief Constructor that loads and initializes the QML chat window.
   DtExampleChatWindow();
 
   //! \brief Destructor for cleanup.
   virtual ~DtExampleChatWindow() override;
 
   //! \brief Sets the visibility of the chat window.
   //!
   //! \param visible true to show the window, false to hide it
   virtual void setVisibility(bool visible);
 
   //! \brief Checks if the chat window is currently visible.
   //!
   //! \return true if visible, false if hidden
   virtual bool isVisible();
 
   //! \brief Closes the chat window (hides it).
   virtual void close();
 
   //! \brief Opens the chat window (shows it).
   virtual void open();
 
   //! \brief Initializes the QML root item after loading.
   //!
   //! Called by the QML loader callback once the QML file is loaded.
   virtual void initMain();
 
   //! \brief Clears all messages from the chat window.
   //!
   //! Q_INVOKABLE makes this method callable from QML, allowing the UI
   //! to trigger C++ functionality (e.g., a "Clear" button in QML).
   Q_INVOKABLE virtual void clearChat();
 
   //! \brief Adds a new message to the chat window.
   //!
   //! \param entry The chat entry to add
   virtual void addNewMessage(const DtChatEntry& entry);
 
   //! \brief Adds a new message to the chat window.
   //!
   //! Convenience overload that constructs a DtChatEntry from individual fields.
   //!
   //! \param sender Entity name of message sender
   //! \param receiver Entity name of message receiver
   //! \param time Simulation time of message
   //! \param message Text content of message
   virtual void addNewMessage(
      const QString& sender, const QString& receiver, const double time, const QString& message);
 
protected:
   QQuickItem* myRoot;         //!< Root QML item loaded from QML file
   DtChatQmlModel myChatModel; //!< Qt model exposed to QML for data binding
   std::string myTargetWindow; //!< Target window name (empty for standalone)
   std::string myTargetFile;   //!< QML file path relative to VR-Engage data directory
};
 
} // namespace makVre