actionInputMenu.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file actionInputMenu.h
//! \brief Defines a text input menu for VR-Engage
//!
//! This file contains the DtActionInputMenu class which provides text input
//! functionality within the VR-Engage menu system. It allows users to enter
//! and edit text with keyboard input, validate that input according to specific
//! format requirements, and send the entered text as an action parameter when
//! the input is completed.
 
#pragma once
 
#include "vrePlayerStation/export.h"
#include "vrePlayerStation/actionMenuManager.h"
#include "vrePlayerStation/actionMenuElement.h"
#include "vrePlayerStation/actionMenu.h"
 
#include <vrvCore/DtKeyState.h>
 
#include <string>
 
namespace makVrv
{
class DtDe;
class DtQuadProxy;
class DtTextProxy;
class DtOverlayRenderer;
class DtOsgChannel;
} // namespace makVrv
 
namespace makVre
{
//! \brief Menu subclass for text input functionality
//!
//! DtActionInputMenu provides a specialized menu for text input in VR-Engage.
//! It captures keyboard input, displays the entered text, validates it according
//! to format requirements, and sends the completed text as an action parameter
//! when the user finalizes their input. This class is used for various text entry
//! needs such as coordinates, radio frequencies, names, and other text-based inputs.
class PLAYERSTATION_DLL DtActionInputMenu : public DtMenu
{
public:
   //! \brief Constructor
   //! \param mgr Reference to the menu manager
   //!
   //! Creates a new input menu associated with the specified menu manager.
   //! The menu starts with empty input text and uses the default null validator
   //! which accepts any input text as valid.
   DtActionInputMenu(DtMenuManager& mgr);
 
   //! \brief Virtual destructor
   //!
   //! Ensures proper cleanup of derived input menu classes.
   virtual ~DtActionInputMenu() override;
 
   //! \brief Sets the current input text
   //! \param input The text to set as the current input
   //!
   //! Updates the current input text and refreshes the visual display.
   //! This can be used to preset the input field with existing text.
   virtual void setInputText(const std::string& input);
 
   //! \brief Gets the current input text
   //! \return The current input text
   //!
   //! Retrieves the text currently entered in the input field.
   virtual std::string inputText() const;
 
   //! \brief Sets the input validator function
   //! \param validator The validator delegate function to use
   //!
   //! Sets the function used to validate input text. The validator function
   //! receives the current input text and returns true if it is valid according
   //! to the expected format, or false if it is invalid.
   virtual void setInputValidator(DtInputValidator validator);
 
   //! \brief Gets the current input validator
   //! \return The current input validator function
   //!
   //! Retrieves the validator function currently being used to validate input.
   virtual DtInputValidator inputValidator() const;
 
   //! \brief Sets the action type for this input menu
   //! \param actionType The action type identifier
   //!
   //! Sets the action type that will be sent when the user completes their input.
   //! This identifier helps the receiving component determine how to handle the input.
   //! The default action type is "InputMenuAccept".
   virtual void setActionType(const std::string& actionType);
 
   //! \brief Gets the current action type
   //! \return The current action type identifier
   //!
   //! Retrieves the action type that will be sent when input is completed.
   virtual std::string actionType() const;
 
   //! \brief Sets the default string to use when input is empty
   //! \param defaultString The default string to use
   //!
   //! Sets a default string that will be used if the user submits an empty input.
   //! This allows for pre-defined values to be used when no specific input is provided.
   virtual void setDefaultString(const std::string& defaultString);
 
   //! \brief Gets the current default string
   //! \return The current default string
   //!
   //! Retrieves the default string that will be used for empty input.
   virtual std::string defaultString() const;
 
   //! \brief Handles selection of the input menu
   //! \param val Input value (typically 1.0 for full selection)
   //!
   //! Called when the input is completed by the user. This sends the entered text
   //! (or default text if empty) as an action with the specified action type,
   //! then returns to the parent menu or closes if no parent exists.
   virtual void select(float val = 1) override;
 
   //! \brief Default validator that accepts any input
   //!
   //! A static input validator that always returns true, accepting any input.
   //! This is used as the default validator when no specific validation is needed.
   static DtInputValidator theNullInputValidator;
 
   //! \brief Sets the active state of the input menu
   //! \param active True to activate the menu, false to deactivate
   //! \param saveSelection Whether to save the current selection state
   //! \param closeOnElementSelected Whether to close after selection (unused)
   //!
   //! Overrides DtMenu::setActive to reset the input text when the menu is activated
   //! and display the default string hint if one is set.
   virtual void setActive(bool active, bool saveSelection = false, bool closeOnElementSelected = false) override;
 
   //! \brief Activates the input handling logic
   //!
   //! Overrides DtMenu::activateInputLogic to set up raw input handling
   //! for keyboard input. This allows the menu to capture keyboard events
   //! directly for text entry.
   virtual void activateInputLogic() override;
 
protected:
   //! \brief Handles raw input data for text entry
   //! \param inputData The input data event to process
   //! \return True if the input was handled, false otherwise
   //!
   //! Processes keyboard input events for text entry. This method handles
   //! special keys (backspace, enter, escape) and passes regular characters
   //! to addCharacter for text building. It's registered as a raw input handler
   //! when the menu is activated.
   virtual bool handleInputData(const DtInputData& inputData);
 
   //! \brief Adds a character to the input text
   //! \param key The keyboard key type to add
   //!
   //! Converts a keyboard key code to a character and adds it to the input text
   //! if the resulting string passes validation. Updates the visual display
   //! after adding the character.
   virtual void addCharacter(makVrv::DtKeyState::KeyType key);
 
   //! \brief Removes the last character from the input text
   //!
   //! Removes the last character from the input text (backspace functionality).
   //! If the input becomes empty, displays the default string hint if one is set.
   //! Updates the visual display after removing the character.
   virtual void removeCharacter();
 
   //! \brief Sends the completed input text as an action
   //!
   //! Creates and queues a MenuActionMessage with the current action type and
   //! the input text (or default text if input is empty) as the parameter.
   //! This is called when the user completes their input by pressing Enter.
   virtual void sendText();
 
   //! \brief Current input text string
   //!
   //! Stores the text currently entered by the user.
   std::string myInputString;
 
   //! \brief Action type identifier for this input menu
   //!
   //! The action type that will be sent when the user completes their input.
   //! Default is "InputMenuAccept".
   std::string myActionType;
 
   //! \brief Validator function for input validation
   //!
   //! Function delegate used to validate input text against format requirements.
   DtInputValidator myInputValidator;
 
   //! \brief Menu element that displays the input text
   //!
   //! The menu element used to display the current input text to the user.
   DtMenuElement* myInputElement;
 
   //! \brief Default string to use when input is empty
   //!
   //! String that will be used if the user submits an empty input.
   //! Also displayed as a hint when the input field is empty.
   std::string myDefaultString;
};
 
} // namespace makVre