actionMenuElement.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file actionMenuElement.h
//! \brief Defines the menu element classes for interactive menus
//!
//! This file contains the DtMenuElement class which represents individual
//! entries in menus used throughout VR-Engage. It also includes observer classes
//! that dynamically generate menu elements based on attribute changes.
 
#pragma once
 
#include "vrePlayerStation/export.h"
 
#include "vreUtil/attribute.h"
 
#include <vector>
#include <string>
 
namespace makVre
{
class DtMenuManager;
class DtMenuCursor;
class DtMenu;
class DtInitTable;
class DtMenuAttributeListObserver;
 
//! \brief Menu element class for interactive menus
//!
//! DtMenuElement represents a single selectable item in a menu. It can represent
//! an action to be executed, or a submenu to be displayed. Each element has a label
//! that is shown to the user, and attributes that control its behavior, such as
//! an action to be taken when selected, display conditions, and visual properties.
//!
//! Menu elements can be dynamically enabled or disabled based on conditions defined
//! in the player attribute store, allowing for context-sensitive menu options.
class PLAYERSTATION_DLL DtMenuElement
{
public:
   //! \brief Types of menu elements
   //!
   //! Defines the behavior of the menu element when selected.
   enum ElementType
   {
      ACTION, //!< Performs an action when selected
      MENU    //!< Opens a submenu when selected
   };
 
   //! \brief Constructor for a menu element
   //! \param label Text displayed for this menu element
   //! \param action Action identifier to execute when selected
   //! \param param Parameter to pass with the action
   //! \param displayConditions List of conditions that determine when this element is enabled
   //! \param openMenuOnDisplayConditionMet Whether to automatically open a submenu when conditions are met
   //! \param hasSubMenu Whether this element has a submenu
   //! \param cursor Cursor name to display when this element is selected
   //! \param valueMapping List of values for variable substitution
   //! \param isValid Whether this element is valid and can be displayed
   //!
   //! Creates a new menu element with the specified properties. The element's type
   //! (ACTION or MENU) is determined automatically based on the action parameter.
   //! If action is "selectMenu", the type will be MENU, otherwise ACTION.
   DtMenuElement(const std::string& label, const std::string& action, const std::string& param = "",
      const std::vector<std::pair<std::string, bool>>& displayConditions = std::vector<std::pair<std::string, bool>>(),
      bool openMenuOnDisplayConditionMet = false, bool hasSubMenu = false, const std::string& cursor = "",
      std::vector<std::string> valueMapping = std::vector<std::string>(), bool isValid = true);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the menu element and disconnects from attribute callbacks.
   virtual ~DtMenuElement();
 
   //! \brief Sets the parent menu for this element
   //! \param menu Pointer to the parent menu
   //!
   //! Associates this element with a menu and sets up attribute callbacks for
   //! dynamic state tracking. When the parent menu is set, the element will look for
   //! relevant state attributes in the player attribute store and connect to them.
   virtual void setMenu(DtMenu* menu);
 
   //! \brief Gets the element type
   //! \return Type of this menu element (ACTION or MENU)
   //!
   //! Retrieves the type of this menu element, which determines its behavior
   //! when selected (performing an action or opening a submenu).
   virtual ElementType type() { return myType; }
 
   //! \brief Sets the element's selected state
   //! \param select True to select this element, false to deselect it
   //!
   //! Called when the selection state of this element changes. When an element
   //! is selected, it updates the active cursor to match its specified cursor.
   virtual void setSelected(bool select);
 
   //! \brief Checks if this element is currently enabled
   //! \return True if enabled, false if disabled
   //!
   //! Determines whether this menu element is currently enabled based on its
   //! display conditions. Disabled elements cannot be selected and may be
   //! visually grayed out or hidden depending on the menu implementation.
   virtual bool isEnabled();
 
   //! \brief Gets the previous enabled state
   //! \return True if previously enabled, false otherwise
   //!
   //! Returns the previously cached enabled state of the element.
   //! Used to detect changes in enabled state for updating menus.
   virtual bool previouslyEnabled() { return myPreviouslyEnabled; }
 
   //! \brief Checks if the menu should open automatically when conditions are met
   //! \return True if menu should open automatically, false otherwise
   //!
   //! If true and if this menu item has display conditions, open the item's menu
   //! when the conditions become true. Useful for context-sensitive actions like
   //! open a nearby door when you walk up to it.
   virtual bool openMenuOnDisplayConditionMet() { return myOpenMenuOnDisplayConditionMet; }
 
   //! \brief Sets the label text for this menu element
   //! \param newLabel The new label text
   //!
   //! Updates the text that is displayed for this menu element.
   virtual void setLabel(const std::string& newLabel) { myLabel = newLabel; }
 
   //! \brief Gets the label for this menu element
   //! \return Label text with any variables resolved
   //!
   //! Retrieves the display text for this menu element, resolving any
   //! variable references in the process. Variables are replaced with
   //! values from the player attribute store.
   virtual std::string label();
 
   //! \brief Gets the action identifier
   //! \return Reference to the action string
   //!
   //! Returns the action identifier that will be executed when this element is selected.
   virtual const std::string& action() { return myAction; }
 
   //! \brief Sets the action identifier
   //! \param newAction The new action string
   //!
   //! Updates the action that will be executed when this element is selected.
   virtual void setAction(const std::string& newAction) { myAction = newAction; }
 
   //! \brief Gets the action parameter
   //! \return Reference to the parameter string
   //!
   //! Returns the parameter that will be passed with the action when executed.
   virtual const std::string& parameter() { return myParameter; }
 
   //! \brief Sets the action parameter
   //! \param newParam The new parameter string
   //!
   //! Updates the parameter that will be passed with the action when executed.
   virtual void setParameter(const std::string& newParam) { myParameter = newParam; }
 
   //! \brief Gets the decorator text
   //! \return Decorator text with variables resolved
   //!
   //! Retrieves additional text displayed alongside the label, such as
   //! a current value or state information. This may include resolved
   //! variable references to show dynamic information.
   virtual std::string decoratorText();
 
   //! \brief Checks if this element has a submenu
   //! \return True if element has a submenu, false otherwise
   //!
   //! Determines whether selecting this element will open a submenu.
   virtual bool hasSubMenu() const { return myHasSubMenu; }
 
   //! \brief Sets whether this element has a submenu
   //! \param val True if element should have a submenu, false otherwise
   //!
   //! Updates whether selecting this element will open a submenu.
   virtual void setHasSubMenu(bool val) { myHasSubMenu = val; }
 
   //! \brief Sets the cursor for this element
   //! \param cursor Name of the cursor to display when selected
   //!
   //! Updates the cursor that will be shown when this element is selected.
   virtual void setCursor(const std::string& cursor);
 
   //! \brief Gets the cursor name
   //! \return Reference to the cursor name string
   //!
   //! Returns the name of the cursor to display when this element is selected.
   virtual const std::string& cursor() { return myCursor; }
 
   //! \brief Gets the value mapping list
   //! \return Reference to the value mapping vector
   //!
   //! Returns the list of values used for substituting variables in labels and parameters.
   virtual const std::vector<std::string>& valueMapping() { return myValueMapping; }
 
   //! \brief Checks if this element is valid
   //! \return True if valid, false otherwise
   //!
   //! Determines whether this element is valid and should be displayed.
   //! Invalid elements are excluded from menus entirely.
   virtual bool isValid() const { return myIsValid; };
 
   //! \brief Sets the validity of this element
   //! \param val True to mark as valid, false to mark as invalid
   //!
   //! Updates whether this element is valid and should be displayed.
   virtual void setIsValid(bool val) { myIsValid = val; };
 
   //! \brief Executes this element's action
   //!
   //! Performs the action associated with this menu element. For ACTION type elements,
   //! this creates and sends a MenuActionMessage with the element's action and parameter.
   //! For MENU type elements, this creates and sends a MenuSetStateMessage to show
   //! the specified submenu and closes the current menu.
   virtual void doAction();
 
   //! \brief Creates a menu element from configuration data
   //! \param config Configuration table containing element properties
   //! \return Newly created menu element, or NULL if creation failed
   //!
   //! Factory method that creates a menu element from a configuration table.
   //! This is used when loading menu definitions from files or dynamic sources.
   static DtMenuElement* create(DtInitTable& config);
 
   //! \brief Resets the element's state
   //!
   //! Disconnects all attribute callbacks and clears state attributes.
   //! Called during cleanup or when the element needs to be completely reset.
   virtual void reset();
 
protected:
   //! \brief Resolves variables in a string with values from attributes
   //! \param str String containing variables to resolve
   //! \return String with variables replaced by their values
   //!
   //! Processes a string and replaces variable references (marked with $)
   //! with values from the player attribute store. This is used to create
   //! dynamic labels and parameters based on current state.
   std::string resolveVars(const std::string& str);
 
   //! \brief Handles attribute change notifications
   //! \param attribute The attribute that changed
   //!
   //! Called when an attribute this element is monitoring changes. Triggers
   //! an update of the parent menu to reflect the changed state.
   void handleAttributeChanged(const DtAttributeHandle& attribute);
 
   //! \brief Finds a state attribute referenced in a string
   //! \param str String potentially containing a state attribute reference
   //! \return Name of the referenced state attribute, or empty string if none
   //!
   //! Parses a string to find embedded state attribute references.
   //! These references can be used to create labels or parameters that
   //! dynamically reflect the current state.
   std::string findStateAttribute(const std::string& str);
 
   //! \brief Checks whether this element should be enabled
   //! \return True if all display conditions are satisfied, false otherwise
   //!
   //! Evaluates all display conditions for this element to determine if it
   //! should be enabled. Each condition refers to a boolean attribute in the
   //! player attribute store, optionally inverted.
   bool checkEnabled();
 
   //! \brief Configuration data for this element
   DtInitTable* myConfig;
 
   //! \brief Parent menu containing this element
   DtMenu* myMenu;
 
   //! \brief Type of element (ACTION or MENU)
   ElementType myType;
 
   //! \brief List of display conditions for this element
   //!
   //! Each pair contains the name of a boolean state attribute and a flag
   //! indicating whether the condition should be inverted. The element is
   //! enabled only when all conditions are satisfied.
   std::vector<std::pair<std::string, bool>> myDisplayConditions;
 
   //! \brief Label text displayed for this element
   std::string myLabel;
 
   //! \brief Action identifier executed when selected
   std::string myAction;
 
   //! \brief Parameter passed with the action
   std::string myParameter;
 
   //! \brief Cursor name to display when selected
   std::string myCursor;
 
   //! \brief Handle to a state attribute for dynamic content
   DtAttributeHandle myStateAttribute;
 
   //! \brief List of values for variable substitution
   std::vector<std::string> myValueMapping;
 
   //! \brief Callback for attribute change notifications
   DtAttributeChangeCallback myAttributeCallback;
 
   //! \brief Whether this element has a submenu
   bool myHasSubMenu;
 
   //! \brief Whether this element is valid and should be displayed
   bool myIsValid;
 
   //! \brief Previously cached enabled state
   bool myPreviouslyEnabled;
 
   //! \brief Whether to open submenu automatically when conditions are met
   bool myOpenMenuOnDisplayConditionMet;
 
   //! \brief Friend classes that need access to internals
   friend class DtMenuAttributeObserver;
};
 
//! \brief Generates menu elements from a list of attributes
//!
//! DtMenuAttributeListObserver monitors a list attribute in the player attribute
//! store and generates a menu element for each item in the list. This is used to
//! create dynamic menus where the available options depend on the current state,
//! such as a list of available weapons or targets.
class PLAYERSTATION_DLL DtMenuAttributeObserver
{
public:
   //! \brief Constructor
   //! \param menu Pointer to the menu to populate with elements
   //! \param state Attribute handle to the player attribute store
   //! \param attributeName Name of the attribute to observe
   //! \param prototype Prototype menu element to clone for each generated element
   //!
   //! Creates a new instance that will monitor the specified attribute and
   //! generate menu elements using the prototype element as a template.
   //!
   //! A new menu element is generated for each item in the attribute list.
   //! If the attribute is a vector of strings, the keyword "$EACH" in the
   //! prototype's label and param fields is replaced with the string.
   //! If the attribute is a map of key/value string pairs, the keyword "$KEY"
   //! in the prototype's label and param fields is replaced with the key, and
   //! the keyword "$VALUE" is replaced with the associated sting value.
 
   DtMenuAttributeObserver(
      DtMenu* menu, DtAttributeHandle state, const std::string& attributeName, DtMenuElement* prototype);
 
   //! \brief Virtual destructor
   //!
   //! Ensures proper cleanup of derived observer classes.
   virtual ~DtMenuAttributeObserver();
 
protected:
   //! \brief Handles attribute change notifications
   //! \param attribute The attribute that changed
   //!
   //! Called when the observed list attribute changes. Regenerates the menu elements
   //! based on the new list content, removing old elements and creating new ones as needed.
   virtual void handleAttributeChanged(const DtAttributeHandle& attribute);
 
   //! \brief Replaces a key with a value in a string
   //! \param string Source string to search
   //! \param key Key to find and replace
   //! \param value Value to substitute for the key
   //! \return String with all instances of the key replaced by the value
   //!
   //! Utility method for substituting a specific key with a value in a string.
   //! Used for generating dynamic element labels and parameters from templates.
   static std::string replaceEach(const std::string& string, std::string const& key, std::string const& value);
 
   //! \brief Creates a new menu element from the prototype
   //! \param label Label string for the new menu element
   //! \param param Param string for the new menu element
   //!
   //! Instantiates a new DtMenuElement using the prototype template and the
   //! given label and param strings and adds the new element to the menu.
   virtual void createMenuElement(const std::string& label, const std::string& param);
 
   //! \brief Menu to populate with generated elements
   DtMenu* myMenu;
 
   //! \brief Attribute handle to the player attribute store
   DtAttributeHandle myState;
 
   //! \brief Callback for attribute change notifications
   DtAttributeChangeCallback myChangeCallback;
 
   //! \brief Prototype element to clone for each generated element
   DtMenuElement* myPrototype;
 
   //! \brief List of elements generated by this observer
   std::vector<DtMenuElement*> myElements;
};
 
} // namespace makVre