chooseRolePanel.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file chooseRolePanel.h
//! \brief Defines the DtChooseRolePanel class for selecting entity roles
//!
//! This file contains the DtChooseRolePanel class, which provides the user interface
//! for selecting and engaging with entities in VR-Engage. It displays available
//! entities, their roles, and various filtering options to help users find and
//! select appropriate roles to play.
 
#pragma once
 
#include "vrePlayerStation/export.h"
 
#include "vrePlayerStation/chooseRolePanelUI.hpp"
#include "vrePlayerStation/chooseRoleState.h"
#include "vrePlayerStation/optimizingVRPerformanceDialog.h"
 
#include <vrvCoreQt/DtDockable.h>
 
#include <vrvCore/DtUniqueID.h>
#include <vrvCore/DtElementData.h>
#include <vrvCore/DtSelectionManager.h>
#include <vrvCore/DtElementAttributeManager.h>
 
#include <vrvUtil/DtSignalConnectionManager.h>
 
namespace makVrv
{
class DtSceneObject;
class DtQtDeMainWindow;
} // namespace makVrv
 
namespace makVre
{
//! \brief Forward declaration of the player station application class
class DtPlayerStationApp;
 
//! \brief Forward declaration of the entity event processor class
class DtCreateNewEntityEventProcessor;
 
//! \brief Forward declaration of the VR performance dialog class
class DtOptimizingVRPerformanceDialog;
 
//! \brief UI panel for selecting and engaging with entities and roles
//!
//! DtChooseRolePanel provides the main user interface for selecting entities
//! and roles in VR-Engage. It displays lists of available entities, filtering
//! options, role selections, and controls for engaging with the simulation.
//!
//! This panel manages the transition between the role selection state and the
//! engaged state, handling UI interactions, entity selection, and role configuration.
class PLAYERSTATION_DLL DtChooseRolePanel : public QWidget
   //, public makVrv::DtDockable
   ,
                                            public Ui::DtChooseRolePanelUI
{
   Q_OBJECT;
 
public:
   //! \brief Constructor
   //! \param de Reference to the display engine
   //! \param mainWindow Pointer to the main application window
   //! \param app Reference to the player station application
   //!
   //! Creates a new role selection panel, initializing UI components and
   //! connecting signals and slots for event handling.
   DtChooseRolePanel(makVrv::DtDe& de, makVrv::DtQtDeMainWindow* mainWindow, DtPlayerStationApp& app);
 
   //! \brief Destructor
   //!
   //! Cleans up resources and disconnects signals.
   virtual ~DtChooseRolePanel() override;
 
   //! \brief Determines initial visibility of the panel
   //! \return False to indicate the panel should initially be hidden
   //!
   //! Virtual function needed for controlling if the widget is initially
   //! visible when docked. Returns false by default, as the panel is typically
   //! shown only when entering the role selection state.
   virtual bool initiallyVisible() const { return false; }
 
   //! \brief Shows the panel container
   //!
   //! Makes the role selection panel visible to the user.
   virtual void showContainer();
 
   //! \brief Hides the panel container
   //!
   //! Makes the role selection panel invisible to the user.
   virtual void hideContainer();
 
   //! \brief Updates the panel state
   //! \param dt Time in seconds since the last update
   //!
   //! Called once per frame to update the panel's state, handle deferred operations,
   //! and refresh the UI as needed.
   virtual void tick(double dt);
 
   //! \brief Sets the ready state of the panel
   //! \param ready True if the panel is ready, false otherwise
   //!
   //! Indicates whether the panel is fully initialized and ready for interaction.
   //! When ready, certain UI elements become enabled and data loading completes.
   virtual void setReady(bool ready);
 
   //! \brief Element signal handlers
   //! @{
 
   //! \brief Handles the addition of new elements to the scene
   //! \param elements List of IDs for the added elements
   //!
   //! Called when new elements are added to the display engine scene.
   //! Updates the entity list with the new elements that can be engaged.
   virtual void onElementsAdded(const makVrv::DtElementData::ElementIdList& elements);
 
   //! \brief Handles the removal of elements from the scene
   //! \param keys List of IDs for the removed elements
   //!
   //! Called when elements are removed from the display engine scene.
   //! Removes the corresponding entries from the entity list.
   virtual void onElementsRemoved(const makVrv::DtElementData::ElementIdList& keys);
 
   //! \brief Handles changes to element attributes
   //! \param attributes List of attribute changes for elements
   //!
   //! Called when element attributes change in the display engine.
   //! Updates the entity list with the modified information.
   virtual void onElementsChanged(const makVrv::DtElementAttributeManager::EntryAttributesList& attributes);
   //! @}
 
   //! \brief Entity message handlers
   //! @{
 
   //! \brief Handles simulation state messages
   //! \param msg Pointer to the simulation state message
   //! \return Message handling result
   //!
   //! Processes messages about entity simulation state changes,
   //! updating the UI with the latest information about entities.
   virtual DtVreMessageResult handleSimState(DtVreMessage* msg);
   //! @}
 
   //! \brief Scene signal handlers
   //! @{
 
   //! \brief Handles scene selection changes
   //! \param selected Set of IDs for newly selected elements
   //! \param deselected Set of IDs for deselected elements
   //!
   //! Called when the user changes the selection in the 3D scene.
   //! Updates the UI to reflect the currently selected entities.
   virtual void onSceneSelectionChanged(
      const makVrv::DtSelectionManager::IdSet& selected, const makVrv::DtSelectionManager::IdSet& deselected);
 
   //! \brief Handles scene clicks
   //! \param id Unique ID of the clicked element (if any)
   //! \param location 3D position of the click
   //! \param altAboveGround Altitude above ground at the click position
   //!
   //! Called when the user clicks in the 3D scene. Used for selecting
   //! entities or determining locations for entity creation.
   virtual void onSceneClicked(makVrv::DtUniqueID id, const DtVector& location, double altAboveGround);
   //! @}
 
   //! \brief Handles SMS load completion messages
   //! \param msg Pointer to the SMS load complete message
   //! \return Message handling result
   //!
   //! Processes messages indicating that loading of Simulation Model Sets (SMS)
   //! has completed, triggering UI updates with the new data.
   DtVreMessageResult handleSmsLoadComplete(DtVreMessage* msg);
 
   //! \brief Handles SMS changes
   //!
   //! Called when the list of active Simulation Model Sets (SMS) changes.
   //! Updates the entity lists and filtering options accordingly.
   virtual void onSmsChanged();
 
   //! \brief Handles creation of new entities
   //!
   //! Called when a new entity is created in the simulation.
   //! Updates the entity list and may select the new entity.
   virtual void onNewEntityCreated();
 
   //! \brief Resets the panel to its initial state
   //!
   //! Clears all selections, filters, and cached data, returning the panel
   //! to its initial state as if it was just opened. This is typically called
   //! when disengaging from a role or when the application state changes.
   virtual void resetPanel();
 
   //! \brief Handles pre-tick events from the display engine
   //! \param de Reference to the display engine
   //!
   //! Called before the display engine updates each frame.
   //! Used for time-sensitive operations that need to occur before rendering.
   void onDePreTick(makVrv::DtDe& de);
 
   //! \brief Handles post-tick events from the display engine
   //!
   //! Called after the display engine updates each frame.
   //! Used for operations that should occur after rendering is complete.
   void onDePostTick();
 
   //! \brief Sets the entity state update interval
   //! \param seconds Number of seconds between updates
   //!
   //! Sets the number of seconds between entity simulation state update cycles.
   //! The default value is 5 seconds. Shorter intervals provide more frequent
   //! updates but may impact performance.
   virtual void setEntityStateUpdateTime(double seconds);
 
   //! \brief Application event handling
   //! @{
 
   //! \brief Filters application-level events
   //! \param p Object that received the event
   //! \param e Event that was received
   //! \return True if the event was handled, false to pass it on
   //!
   //! Intercepts application-level events for custom processing, such as
   //! keyboard shortcuts or mouse events outside the normal widget hierarchy.
   virtual bool eventFilter(QObject* p, QEvent* e) override;
 
   //! \brief Installs event filters for application-level event handling
   //!
   //! Sets up the event filters to intercept application events before
   //! they reach their normal destination widgets.
   virtual void installEventFilters();
 
   //! \brief Removes previously installed event filters
   //!
   //! Removes the event filters, restoring normal event handling.
   virtual void removeEventFilters();
   //! @}
 
   //! \brief Checks if the observer views button is active
   //! \return True if the observer views button is checked, false otherwise
   //!
   //! Determines whether the observer views button in the UI is currently
   //! in the active (checked) state. This affects whether observer views
   //! are shown alongside the role selection panel.
   virtual bool isObserverViewsButtonActive() const;
 
   //! \brief Enables or disables the create entity option
   //! \param enabled True to enable entity creation, false to disable it
   //!
   //! Controls whether the UI allows users to create new entities.
   //! This might be disabled in certain contexts or configurations.
   virtual void enableCreateEntity(bool enabled);
 
   //! \brief Clears all entity selections
   //!
   //! Deselects all currently selected entities in both the UI and the scene.
   //! This resets the selection state without affecting other panel settings.
   virtual void clearSelectedEntities();
 
public slots:
   //! \brief UI event handlers (slots)
   //! @{
 
   //! \brief Handles clicks on the "Take Control" (Engage) button
   //! \param checked Whether the button is now checked
   virtual void slot_onTakeControlClicked(bool checked);
 
   //! \brief Handles clicks on the "Create New" button
   //! \param checked Whether the button is now checked
   virtual void slot_onCreateNewClicked(bool checked);
 
   //! \brief Handles changes to the category filter
   //! \param category New category filter value
   virtual void slot_onCategoryFilterChanged(const QString& category);
 
   //! \brief Handles changes to the country filter
   //! \param country New country filter value
   virtual void slot_onCountryFilterChanged(const QString& country);
 
   //! \brief Handles changes to the force filter
   //! \param force New force filter value
   virtual void slot_onForceFilterChanged(const QString& force);
 
   //! \brief Handles selection of a different role
   //! \param role Name of the selected role
   virtual void slot_onRoleSelectionChanged(const QString& role);
 
   //! \brief Handles selection of a different display configuration
   //! \param config Name of the selected configuration
   virtual void slot_onConfigurationSelectionChanged(const QString& config);
 
   //! \brief Handles clicks on the "Reset Filters" button
   virtual void slot_onResetFiltersClicked();
 
   //! \brief Handles changes to the search filter text
   //! \param text New search filter text
   virtual void slot_onSearchFilterChanged(const QString& text);
 
   //! \brief Handles clicks on the "Reset Search" button
   virtual void slot_onResetSearchClicked();
 
   //! \brief Handles clicks on items in the entity list
   //! \param item The tree widget item that was clicked
   //! \param column The column that was clicked
   virtual void slot_onEntityItemClicked(QTreeWidgetItem* item, int column);
 
   //! \brief Handles double-clicks on items in the entity list
   //! \param item The tree widget item that was double-clicked
   //! \param column The column that was double-clicked
   virtual void slot_onEntityItemDoubleClicked(QTreeWidgetItem*, int);
 
   //! \brief Handles changes in entity selection in the entity list
   //!
   //! Called when the user selects a different entity in the entity list.
   //! Updates the role and display layout lists based on the new selection,
   //! and may also update the view to focus on the selected entity.
   virtual void slot_onEntitySelectionChanged();
 
   //! \brief Handles clicks on items in the create entity list
   //! \param item The tree widget item that was clicked
   //! \param column The column that was clicked
   //!
   //! Called when the user clicks on an item in the create entity list.
   //! Updates the selected entity type and role options based on the clicked item.
   virtual void slot_onCreateItemClicked(QTreeWidgetItem* item, int column);
 
   //! \brief Handles double-clicks on items in the create entity list
   //! \param item The tree widget item that was double-clicked
   //! \param column The column that was double-clicked
   //!
   //! Called when the user double-clicks on an item in the create entity list.
   //! May automatically select the item and begin the entity creation process.
   virtual void slot_onCreateItemDoubleClicked(QTreeWidgetItem* item, int column);
 
   //! \brief Handles changes in entity selection in the create entity list
   //!
   //! Called when the user selects a different entity type in the create entity list.
   //! Updates the role and display layout lists based on the new selection.
   virtual void slot_onCreateSelectionChanged();
 
   //! \brief Handles edits to the entity name field
   //! \param name The new entity name
   //!
   //! Called when the user edits the name field for a new entity.
   //! Updates the stored name for the entity being created.
   virtual void slot_onNameEdited(const QString& name);
 
   //! \brief Handles toggling of the "at altitude" option
   //! \param on True if the option is turned on, false otherwise
   //!
   //! Called when the user toggles the option to place an entity at a specific altitude.
   //! Enables or disables the altitude input field based on the toggle state.
   virtual void slot_onAtAltitudeToggled(bool on);
 
   //! \brief Handles changes to the altitude value
   //! \param altitude The new altitude value
   //!
   //! Called when the user changes the altitude value for entity placement.
   //! Updates the stored altitude for the entity being created.
   virtual void slot_onAltitudeChanged(int altitude);
 
   //! \brief Handles changes to the entity heading
   //! \param heading The new heading value as a string
   //!
   //! Called when the user changes the heading value for entity placement.
   //! Updates the stored heading for the entity being created.
   virtual void slot_onHeadingChanged(const QString& heading);
 
   //! \brief Handles changes to the entity pitch
   //! \param pitch The new pitch value as a string
   //!
   //! Called when the user changes the pitch value for entity placement.
   //! Updates the stored pitch for the entity being created.
   virtual void slot_onPitchChanged(const QString& pitch);
 
   //! \brief Handles clicks on the "Reset View" button
   //!
   //! Called when the user clicks the Reset View button. Resets the
   //! observer view to show all entities in the scene, providing an
   //! overview of the available entities.
   virtual void slot_onResetViewClicked();
 
   //! \brief Handles toggling of the observer views panel
   //! \param visible True if the panel should be visible, false otherwise
   //!
   //! Called when the user toggles the observer views panel button.
   //! Shows or hides the observer views panel based on the toggle state.
   virtual void slot_onObserverViewsPanelToggled(bool visible);
 
   //! \brief Handles toggling of the map view
   //! \param on True if map view should be enabled, false otherwise
   //!
   //! Called when the user toggles the map view button. Switches the
   //! view mode between 2D map view and 3D perspective view.
   virtual void slot_onMapViewToggled(bool on);
 
   //! \brief Handles toggling of the entity view
   //! \param on True if entity view should be enabled, false otherwise
   //!
   //! Called when the user toggles the entity view button. Controls
   //! whether the view focuses on the selected entity.
   virtual void slot_onEntityViewToggled(bool on);
 
   //! \brief Handles clicks on the "Play" button
   //!
   //! Called when the user clicks the Play button. This engages the
   //! user with the selected entity using the chosen role and display layout,
   //! transitioning from the role selection state to the playing state.
   virtual void slot_onPlayClicked();
 
   //! \brief Handles context menu requests in the entity list
   //! \param pos Position where the context menu was requested
   //!
   //! Called when the user right-clicks on an item in the entity list.
   //! Shows a context menu with entity-specific actions.
   virtual void slot_onEntityContextMenu(const QPoint& pos);
 
   //! \brief Handles context menu requests in the create entity list
   //! \param pos Position where the context menu was requested
   //!
   //! Called when the user right-clicks on an item in the create entity list.
   //! Shows a context menu with actions specific to entity creation.
   virtual void slot_onCreateContextMenu(const QPoint& pos);
 
   //! \brief Handles the "Copy ID" action from the entity context menu
   //!
   //! Called when the user selects the Copy ID action from the entity
   //! context menu. Copies the selected entity's ID to the clipboard.
   virtual void slot_onEntityContextMenuActionCopyId();
 
   //! \brief Handles the "Copy Type" action from the entity context menu
   //!
   //! Called when the user selects the Copy Type action from the entity
   //! context menu. Copies the selected entity's type to the clipboard.
   virtual void slot_onEntityContextMenuActionCopyType();
 
   //! \brief Handles the "Copy Type" action from the create entity context menu
   //!
   //! Called when the user selects the Copy Type action from the create entity
   //! context menu. Copies the selected entity type to the clipboard.
   virtual void slot_onCreateContextMenuActionCopyType();
 
protected:
   //! \brief Repositions the choose role panel
   //!
   //! Adjusts the position and size of the panel within the application window.
   //! This is typically called when the window size changes or when the panel
   //! is first shown.
   virtual void repositionChooseRolePanel();
 
   //! \brief Provides debugging information
   //!
   //! Called during debugging to output information about the panel's state.
   //! This is used for diagnostic purposes during development and testing.
   virtual void debugCallback();
 
   //! \brief List building methods
   //! @{
 
   //! \brief Builds the list of entity types that can be created
   //!
   //! Populates the create entity list with all available entity types
   //! from the current simulation model sets.
   virtual void buildCreateEntityList();
 
   //! \brief Builds the list of existing entities in the simulation
   //!
   //! Populates the existing entity list with all entities currently
   //! present in the simulation that can be engaged with.
   virtual void buildExistingEntityList();
 
   //! \brief Builds the list of entity categories for filtering
   //!
   //! Populates the category filter dropdown with all unique categories
   //! found in the available entity types.
   virtual void buildCategoriesList();
 
   //! \brief Builds the list of countries for filtering
   //!
   //! Populates the country filter dropdown with all unique countries
   //! found in the available entity types.
   virtual void buildCountriesList();
 
   //! \brief Builds the list of force types for filtering
   //!
   //! Populates the force filter dropdown with all available force types
   //! (Friendly, Hostile, Neutral, etc.).
   virtual void buildForcesList();
 
   //! \brief Builds the list of available roles for an entity type
   //! \param entityType The entity type to get roles for
   //!
   //! Populates the role dropdown with all available roles for the
   //! specified entity type.
   virtual void buildRolesList(const DtEntityType& entityType);
 
   //! \brief Finds available roles for an entity type
   //! \param entityType The entity type to find roles for
   //! \param box Optional combo box to populate with the roles
   //! \return True if roles were found, false otherwise
   //!
   //! Searches for available roles for the specified entity type and
   //! optionally populates a combo box with the results.
   virtual bool findRoles(const DtEntityType& entityType, QComboBox* box = NULL);
 
   //! @}
 
   //! \brief Entity list management methods
   //! @{
 
   //! \brief Removes an element from the entity list
   //! \param id ID of the element to remove
   //!
   //! Removes an entity from the list of existing entities based on its element ID.
   virtual void removeElementFromEntityList(makVrv::DtElementID id);
 
   //! \brief Adds an element to the entity list
   //! \param data Element data to add
   //!
   //! Adds a new entity to the list of existing entities based on its element data.
   virtual void addElementToEntityList(const makVrv::DtElementEntry& data);
 
   //! \brief Finds an item in the entity list by element ID
   //! \param id Element ID to search for
   //! \return Pointer to the found item, or NULL if not found
   //!
   //! Searches the entity list for an item with the specified element ID.
   virtual QTreeWidgetItem* findEntityListItem(const makVrv::DtElementID& id);
 
   //! \brief Finds an item in the entity list by entity ID
   //! \param id Entity ID to search for
   //! \return Pointer to the found item, or NULL if not found
   //!
   //! Searches the entity list for an item with the specified entity ID.
   virtual QTreeWidgetItem* findEntityListItem(const DtEntityIdentifier& id);
   //! @}
 
   //! \brief Filter application methods
   //! @{
 
   //! \brief Applies all filters to both entity lists
   //!
   //! Applies the current search text and category/country/force filters
   //! to both the existing entity list and the create entity list.
   virtual void applyFilters();
 
   //! \brief Applies filters to a specific tree widget
   //! \param tree The tree widget to apply filters to
   //!
   //! Applies the current filters to the specified tree widget, showing
   //! only items that match all filter criteria.
   virtual void applyFilter(QTreeWidget* tree);
   //! @}
 
   //! \brief View manipulation methods
   //! @{
 
   //! \brief Centers the view on all entities
   //! \return True if the view was adjusted successfully, false otherwise
   //!
   //! Adjusts the observer view to show all entities in the scene.
   virtual bool viewAllEntities();
 
   //! \brief Centers the view on the currently selected entity
   //! \return True if the view was adjusted successfully, false otherwise
   //!
   //! Adjusts the observer view to focus on the currently selected entity.
   virtual bool viewCurrentEntity();
   //! @}
 
   //! \brief Updates the list of available display layouts
   //! \param sceneObject Pointer to the scene object representing the selected entity
   //!
   //! Updates the display layout dropdown with layouts available for the
   //! selected entity and role combination.
   virtual void updateDisplayLayoutsList(const makVrv::DtSceneObject* sceneObject);
 
   //! \brief Converts the altitude spinbox value to meters
   //! \return Altitude value in meters
   //!
   //! Uses VR-Vantage's display units manager to convert the altitude spinbox's
   //! value from the current display units to meters for internal calculations.
   virtual int altitudeSpinboxValueInMeters();
 
   //! \brief Shows the VR performance optimization dialog
   //!
   //! Displays a dialog offering performance tips for VR display configurations.
   //! Called when the user clicks on the "Engage" button and the selected display
   //! configuration is a VR configuration. The user can optionally choose to never
   //! show the dialog again, in which case it will be suppressed in future sessions.
   void showOptimizingVRPerformanceDialog();
 
   //! \brief Updates the altitude box's unit suffix
   //!
   //! Changes the altitude spinbox's suffix to match the current display units.
   //! Called when the display unit settings change in the application.
   virtual void on_displayUnitChanged();
 
   //! \brief Pointer to the main application window
   //!
   //! References the main application window, used for determining panel placement,
   //! accessing application-wide resources, and coordinating UI interactions.
   //! This is typically the parent widget for the panel.
   QMainWindow* myMainWindow;
 
   //! \brief Context menu for the entity list
   //!
   //! Context menu displayed when right-clicking on items in the entity list.
   //! Contains actions related to the selected entity, such as copying its ID
   //! or type information.
   QMenu* myEntityTreeContextMenu;
 
   //! \brief Context menu for the create entity list
   //!
   //! Context menu displayed when right-clicking on items in the create entity list.
   //! Contains actions related to the selected entity type, such as copying type
   //! information or accessing additional entity creation options.
   QMenu* myCreateTreeContextMenu;
 
   //! \brief Action for copying entity IDs
   //!
   //! Menu action for copying the selected entity's unique identifier to the clipboard.
   //! Useful for developers and testers who need to reference specific entities.
   QAction* myCopyEntityIdAction;
 
   //! \brief Action for copying entity types
   //!
   //! Menu action for copying the selected entity's type string to the clipboard.
   //! Useful for developers and scenario designers working with entity definitions.
   QAction* myCopyEntityTypeAction;
 
   //! \brief Action for copying entity types from the creation list
   //!
   //! Menu action for copying the selected entity type from the create entity list
   //! to the clipboard. Useful for referencing available entity types during
   //! scenario development or testing.
   QAction* myCopyCreateTypeAction;
 
   //! \brief Enumeration of available view modes
   //!
   //! Defines the supported viewing modes for the observer during role selection.
   //! These modes control how the simulation environment is visualized.
   enum ViewModes
   {
      ViewMode_Map, //!< 2D map view mode (top-down orthographic projection)
      ViewMode_3D   //!< 3D perspective view mode (configurable camera angle)
   };
 
   //! \brief Sets the current view mode
   //! \param mode View mode to set (default: 3D view)
   //! \return True if the view mode was changed successfully, false otherwise
   //!
   //! Changes the current view mode between map view (2D) and 3D view.
   //! Updates UI elements and observer settings accordingly, including camera
   //! position, orientation, projection type, and control sensitivity.
   //! The map view is useful for precise placement and spatial awareness,
   //! while the 3D view provides better depth perception and visual context.
   virtual void setViewMode(ViewModes mode = ViewMode_3D);
 
   //! \brief Data fields for entity list items
   //!
   //! Defines the data fields stored in each entity list item. These fields
   //! provide metadata about the entity and are used for filtering, display,
   //! and selection logic. Fields are stored as item data in the QTreeWidgetItem.
   enum EntityListItemDataFields
   {
      DataField_ElementId,    //!< Display engine element ID from the scene graph
      DataField_EntityId,     //!< Simulation entity ID used in network messages
      DataField_Type,         //!< Entity type (e.g., "T-72", "M1A2", "Infantry")
      DataField_Force,        //!< Force type (friendly, hostile, neutral, etc.)
      DataField_Categories,   //!< Categories the entity belongs to (e.g., "Ground", "Air")
      DataField_Countries,    //!< Countries associated with the entity (e.g., "USA", "UK")
      DataField_Name,         //!< Display name of the entity shown in the UI
      DataField_OwnThis,      //!< Whether this entity is owned by the current player
      DataField_EmbarkedRole, //!< Role this entity is embarked as (if applicable)
      DataField_EngagedBy,    //!< Player name who is currently engaged with this entity
   };
 
   //! \brief Column identifiers for the entity list
   //!
   //! Defines the columns displayed in the entity list tree widget. These columns
   //! present entity information to the user and can be used for sorting and navigation.
   enum EntityListItemColumns
   {
      ColumnId_Name,    //!< Name column showing entity display name
      ColumnId_Type,    //!< Type column showing entity type designation
      ColumnId_Host,    //!< Host column showing containing entity (if embarked)
      ColumnId_Engaged, //!< Engaged column showing engagement status and player
   };
 
   //! \brief Event processor for creating new entities
   //!
   //! Handles mouse clicks and other events for entity creation, such as
   //! determining placement location and orientations based on user input.
   DtCreateNewEntityEventProcessor* myEventProcessor;
 
   //! \brief Manager for signal connections
   //!
   //! Manages connections to Qt signals and slots, ensuring proper cleanup
   //! when the panel is destroyed or connections need to be broken.
   makVrv::DtSignalConnectionManager mySignals;
 
   //! \brief Reference to the player station application
   //!
   //! Provides access to application-level functionality and state,
   //! such as entity creation, player station management, and state transitions.
   DtPlayerStationApp& myApp;
 
   //! \brief Reference to the display engine
   //!
   //! Provides access to the 3D scene, rendering capabilities, and scene manipulation,
   //! used for visualization and entity placement during role selection.
   makVrv::DtDe& myDe;
 
   //! \brief Flag indicating whether spectator mode was requested
   //!
   //! When true, indicates that the user has requested to enter spectator mode,
   //! which allows observation without directly controlling an entity.
   bool myWantedSpectator;
 
   //! \brief Flag indicating whether an initial view of all entities was performed
   //!
   //! When true, indicates that the panel has already performed an initial
   //! camera adjustment to show all entities when first opened.
   bool myDidInitialViewAll;
 
   //! \brief Last known count of entities in the scene
   //!
   //! Stores the number of entities present in the scene during the last update.
   //! Used to detect changes in entity count for triggering UI updates.
   int myLastEntityCount;
 
   //! \brief Timer for tracking scene clicks
   //!
   //! Tracks time since the last scene click, used for debouncing rapid clicks
   //! and preventing accidental double selections.
   double mySceneClickTimer;
 
   //! \brief Index for cycling through entity updates
   //!
   //! Current index in the entity list for progressive updates. Used to
   //! distribute update processing across multiple frames for better performance.
   int myEntityStateUpdateIndex;
 
   //! \brief Time of the last entity state update
   //!
   //! Stores the time when the last entity state update was performed, used
   //! to control the frequency of state updates based on the update interval.
   double myEntityStateLastUpdateTime;
 
   //! \brief Interval between entity state updates
   //!
   //! Number of seconds between entity state update cycles. Controls how
   //! frequently the panel refreshes entity information from the simulation.
   double myEntityStateUpdateTime;
 
   //! \brief Currently selected entity type
   //!
   //! Stores the entity type that is currently selected in the create entity list.
   //! Used for populating role options and other type-specific UI elements.
   DtEntityType mySelectedEntityType;
 
   //! \brief Flag indicating that the display list needs updating
   //!
   //! When true, the UI needs to refresh the display layouts list based on
   //! changes to entity selection, role selection, or other factors.
   bool myDisplayListNeedsUpdate;
 
   //! \brief Cache of role settings by entity type
   //!
   //! Stores display layouts for when switching entity selections
   //! or disengaging, allowing the UI to remember previous selections.
   //! Maps entity type names to previously selected roles for those types.
   std::map<std::string, std::string> myPreviousRoleSettings;
 
   //! \brief Dialog for VR performance optimization tips
   //!
   //! Shows performance optimization tips when controlling an
   //! entity in a VR display configuration. This dialog appears
   //! the first time a user selects a VR display layout, with an
   //! option to suppress future appearances.
   DtOptimizingVRPerformanceDialog* myOptimizingVRPerformanceDialog;
 
   //! \brief Additional manager for signal connections
   //!
   //! Manages a separate set of signal connections, primarily used
   //! for temporary connections that need different lifecycle management
   //! than the primary signal connections.
   makVrv::DtSignalConnectionManager myConnections;
};
} // namespace makVre