actionMenuManager.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file actionMenuManager.h
//! \brief Defines the menu management system for VR-Engage
//!
//! This file contains the DtMenuManager and DtMenuCursor classes which handle
//! the creation, organization, and rendering of interactive menus in VR-Engage.
//! The menu manager coordinates multiple menus, handles cursor display, and
//! processes menu-related input and messages.
 
#pragma once
 
#include "vrePlayerStation/export.h"
 
#include "vreMessageManager/vreMessage.h"
 
#include "vreUtil/attribute.h"
 
#include <vrvGraphics/DtGlFontManager.h>
 
 
#include <map>
#include <string>
 
 
namespace makVrv
{
class DtDe;
class DtOsgChannel;
class DtSceneObjectAgent;
class DtModelAgent;
class DtTickable;
class DtOverlayRenderer;
} // namespace makVrv
 
namespace makVre
{
class DtActionMenuUpdater;
class DtQmlActionMenu;
class DtMenu;
class DtInitTable;
 
//! \brief Type definition for input validation delegate functions
//!
//! Defines a delegate function type for validating menu input strings.
//! These validators are used to check if user-entered text meets specific format
//! requirements for different input types like coordinates, numbers, etc.
using DtInputValidator = DtDelegate<bool, const std::string&>;
 
//! \brief Class for managing menu cursor visualization
//!
//! DtMenuCursor encapsulates the visual representation of a cursor in the menu system.
//! It manages the 3D scene object, model, and updating logic needed to display
//! a cursor at the current menu selection. Different cursor types can be used
//! to provide visual feedback about the current context or selection type.
class PLAYERSTATION_DLL DtMenuCursor
{
public:
   //! \brief Constructor
   //!
   //! Creates a new menu cursor with default (empty) state.
   DtMenuCursor();
 
   //! \brief Virtual destructor
   //!
   //! Ensures proper cleanup of derived cursor classes.
   virtual ~DtMenuCursor();
 
   //! \brief Clears the cursor state
   //!
   //! Resets the cursor to an empty state, cleaning up any associated
   //! scene objects, models, and updaters.
   void clear();
 
   //! \brief Scene object agent for the cursor visual
   //!
   //! Represents the cursor in the 3D scene graph, handling its position and visibility.
   makVrv::DtSceneObjectAgent* mySceneObject;
 
   //! \brief Model agent for the cursor visual
   //!
   //! Manages the 3D model used to represent the cursor visually.
   makVrv::DtModelAgent* myModel;
 
   //! \brief Tickable component for cursor updates
   //!
   //! Handles periodic updates to the cursor's position, orientation, and appearance.
   makVrv::DtTickable* myUpdater;
 
   //! \brief Name identifier for the cursor
   //!
   //! Unique name that identifies this cursor type in the cursor registry.
   std::string myName;
};
 
 
//! \brief Central manager for all menus in VR-Engage
//!
//! DtMenuManager serves as the central coordinating system for all menus in VR-Engage.
//! It manages the creation, organization, and interaction with menus, handling both
//! standard action menus and input menus. The manager maintains a registry of menus
//! by name, provides access to the player state store for dynamically updating menu
//! content, and coordinates cursor visualization for menu selections.
//!
//! This class also provides input validation functionality for text input fields
//! in menus, with a registry of validators for different data types and formats.
class PLAYERSTATION_DLL DtMenuManager
{
public:
   //! \brief Constructor
   //! \param updater Pointer to the action menu updater
   //! \param state Reference to the player state attribute handle
   //! \param de Pointer to the display engine
   //!
   //! Creates a new menu manager with references to the necessary components for
   //! menu management, including the updater for visual presentation, the player
   //! state store for dynamic content, and the display engine for rendering.
   DtMenuManager(DtActionMenuUpdater* updater, DtAttributeHandle& state, makVrv::DtDe* de);
 
   //! \brief Virtual destructor
   //!
   //! Ensures proper cleanup of all menu resources and derived manager classes.
   virtual ~DtMenuManager();
 
   //! \brief Gets the player state attribute store
   //! \return Reference to the player state attribute handle
   //!
   //! Provides access to the player state attribute store, which contains
   //! attributes used for dynamic menu content and conditional display.
   DtAttributeHandle& playerStore() { return myPlayerStore; }
 
   //! \brief Creates standard action menus from configuration
   //! \param config Configuration table with menu definitions
   //!
   //! Builds the standard menu system based on the provided configuration data.
   //! This includes the main action menu and its submenus, creating the menu
   //! hierarchy and registering all menus with the manager.
   void createMenus(DtInitTable& config);
 
   //! \brief Creates input menus from configuration
   //! \param config Configuration table with input menu definitions
   //!
   //! Builds special input menus based on the provided configuration data.
   //! Input menus are used for text and value entry, such as coordinates,
   //! radio frequencies, or other user-entered data.
   void createInputMenus(DtInitTable& config);
 
   //! \brief Creates the standard set of input validators
   //!
   //! Sets up the default input validators for various data types and formats,
   //! such as MGRS coordinates, laser codes, crypto keys, and numeric values.
   //! These validators are used to ensure user input meets format requirements.
   void createDefaultValidators();
 
   //! \brief Finds a validator for a specific input type
   //! \param type String identifier for the validator type
   //! \return The requested validator delegate, or an empty validator if not found
   //!
   //! Retrieves a validator function for the specified input type from the
   //! validator registry. This is used by input menus to validate user-entered text.
   DtInputValidator findValidator(const std::string& type);
 
   //! \brief Adds a menu to the manager
   //! \param menu Pointer to the menu to add
   //!
   //! Registers a menu with the manager and takes ownership of it.
   //! The menu manager becomes responsible for deleting the menu when it's
   //! no longer needed or when the manager is destroyed.
   void addMenu(DtMenu* menu);
 
   //! \brief Removes a menu from the manager
   //! \param menu Pointer to the menu to remove
   //!
   //! Unregisters a menu from the manager without deleting it.
   //! The caller becomes responsible for deleting the menu to avoid memory leaks.
   void removeMenu(DtMenu* menu);
 
   //! \brief Finds a menu by name
   //! \param name Name of the menu to find
   //! \return Pointer to the found menu, or NULL if not found
   //!
   //! Looks up a menu in the registry by its name identifier.
   //! This is used to access specific menus for operations like
   //! showing, hiding, or updating them.
   DtMenu* findMenu(const std::string& name);
 
   //! \brief Finds the currently active menu
   //! \return Pointer to the active menu, or NULL if no menu is active
   //!
   //! Searches for and returns the currently active (visible) menu.
   //! If multiple menus are active, behavior is undefined and typically
   //! returns the first active menu found.
   DtMenu* findActiveMenu();
 
   //! \brief Sets the active cursor by name
   //! \param name Name of the cursor to activate
   //!
   //! Activates a specific cursor design by name. Different cursors can
   //! provide visual feedback about the current context or selection type.
   //! An empty name deactivates the cursor display.
   void setActiveCursor(const std::string& name);
 
   //! \brief Gets the display engine
   //! \return Pointer to the display engine
   //!
   //! Provides access to the display engine used for rendering menus and cursors.
   makVrv::DtDe* de() { return myDe; }
 
   //! \brief Gets the QML action menu component
   //! \return Pointer to the QML action menu
   //!
   //! Provides access to the QML-based action menu implementation.
   //! This is used by components that need to directly interact with
   //! the modern UI representation of menus.
   virtual DtQmlActionMenu* qmlActionMenu() const;
 
protected:
   //! \brief Validates MGRS coordinate input
   //! \param input The string to validate
   //! \return True if the input is a valid MGRS coordinate
   //!
   //! Checks if the provided string is a valid Military Grid Reference System (MGRS)
   //! coordinate format. MGRS is a geocoordinate standard used by NATO military forces.
   bool validateMgrsInput(const std::string& input);
 
   //! \brief Validates laser code input
   //! \param input The string to validate
   //! \return True if the input is a valid laser code
   //!
   //! Checks if the provided string is a valid laser designator code format.
   //! Laser codes are used for targeting systems and typically follow specific formats.
   bool validateLaserInput(const std::string& input);
 
   //! \brief Validates cryptographic key input
   //! \param input The string to validate
   //! \return True if the input is a valid crypto key
   //!
   //! Checks if the provided string is a valid cryptographic key format.
   //! Crypto keys are used for secure communications and follow specific formats.
   bool validateCryptoKey(const std::string& input);
 
   //! \brief Validates integer input
   //! \param input The string to validate
   //! \return True if the input is a valid integer
   //!
   //! Checks if the provided string represents a valid integer number.
   bool validateIntegerInput(const std::string& input);
 
   //! \brief Always returns true for any input
   //! \param input The string to validate (unused)
   //! \return Always returns true
   //!
   //! Placeholder validator that accepts any input. This can be used for
   //! fields where no specific validation is needed or where validation
   //! will be performed later in the processing pipeline.
   bool validateTrue(const std::string& input);
 
   //! \brief Validates latitude/longitude coordinate input
   //! \param input The string to validate
   //! \return True if the input contains valid decimal lat/lon coordinates
   //!
   //! Validates input string for decimal latitude and longitude in degrees.
   //! Expected format is two numbers separated by a space, with the first
   //! number representing latitude (-90 to 90) and the second representing
   //! longitude (-180 to 180).
   bool validateDecimalLatLonInDegrees(const std::string& input);
 
   //! \brief Handles menu-related messages
   //! \param msg Pointer to the message to handle
   //! \return Message handling result
   //!
   //! Processes messages related to menu state changes, such as requests
   //! to show or hide specific menus, menu selection events, and menu
   //! configuration changes.
   DtVreMessageResult handleMenuMessage(DtVreMessage* msg);
 
protected:
   //! \brief Pointer to the display engine
   //!
   //! The display engine used for rendering menus and cursors.
   makVrv::DtDe* myDe;
 
   //! \brief Type definition for a map of menu names to menu pointers
   using MenuMap = std::map<std::string, DtMenu*>;
 
   //! \brief Registry of all menus managed by this manager
   //!
   //! Maps menu names to their corresponding menu objects for lookup and management.
   MenuMap myMenuMap;
 
   //! \brief Type definition for a map of validator names to validator functions
   using ValidatorMap = std::map<std::string, DtInputValidator>;
 
   //! \brief Registry of input validators
   //!
   //! Maps validator type names to their corresponding validator functions.
   //! Used to validate user input in text entry fields.
   ValidatorMap myValidatorMap;
 
   //! \brief Handle to the player attribute store
   //!
   //! Provides access to player state attributes used for dynamic menu content
   //! and conditional display logic.
   DtAttributeHandle myPlayerStore;
 
   //! \brief Global scale factor for menu elements
   //!
   //! Controls the overall size of menu elements for display scaling.
   float myScale;
 
   //! \brief Pointer to the current menu cursor
   //!
   //! Manages the visual representation of the cursor in menus.
   DtMenuCursor* myCursor;
 
   //! \brief Pointer to the action menu updater
   //!
   //! Handles the visual updating and rendering of menus.
   DtActionMenuUpdater* myUpdater;
};
 
} // namespace makVre