581 lines
17 KiB
C++
581 lines
17 KiB
C++
/**
|
|
* @file include/ActivMiddleware/ActivFramework/UiMenu.h
|
|
*
|
|
* @brief Header file for the ui menu class.
|
|
*/
|
|
|
|
#if (!defined ACTIV_FRAMEWORK_UI_MENU_H)
|
|
#define ACTIV_FRAMEWORK_UI_MENU_H
|
|
|
|
#include "ActivMiddleware/ActivFramework/External.h"
|
|
#include "ActivMiddleware/ActivFramework/UiPermissions.h"
|
|
#include "ActivMiddleware/CxxYZ/functional.h"
|
|
|
|
#include <vector>
|
|
|
|
//! Activ namespace.
|
|
namespace Activ
|
|
{
|
|
|
|
class UiUser;
|
|
class UiIo;
|
|
|
|
//! Section name when creating a menu option.
|
|
class UiSectionName : public String
|
|
{
|
|
public:
|
|
//! Default constructor.
|
|
UiSectionName();
|
|
|
|
/**
|
|
* @brief Constructor.
|
|
*
|
|
* @param sectionName
|
|
*/
|
|
UiSectionName(const String §ionName);
|
|
};
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
//! Help text when creating a menu option.
|
|
class UiHelpText : public String
|
|
{
|
|
public:
|
|
//! Default constructor.
|
|
UiHelpText();
|
|
|
|
/**
|
|
* @brief Constructor.
|
|
*
|
|
* @param helpText
|
|
*/
|
|
UiHelpText(const String &helpText);
|
|
};
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
/**
|
|
* @brief Ui menu class.
|
|
*/
|
|
class UiMenu
|
|
{
|
|
public:
|
|
/**
|
|
* @brief Option attributes.
|
|
*
|
|
* Currently supported attributes are:
|
|
* * permissioning
|
|
* * section heading for grouping options
|
|
* * help text displayed if the user enters "help <option number>"
|
|
*/
|
|
class OptionAttributes
|
|
{
|
|
public:
|
|
/**
|
|
* @brief Default constructor.
|
|
*
|
|
* UiPermissions::READ, no section name or help text.
|
|
*/
|
|
OptionAttributes();
|
|
|
|
/**
|
|
* @brief Constructor.
|
|
*
|
|
* @param uiPermissions user permissions for the option.
|
|
*/
|
|
OptionAttributes(const UiPermissions &uiPermissions);
|
|
|
|
/**
|
|
* @brief Constructor.
|
|
*
|
|
* @param sectionName start a new section in the menu with this name.
|
|
*/
|
|
OptionAttributes(const String §ionName);
|
|
|
|
/**
|
|
* @brief Constructor.
|
|
*
|
|
* @param uiPermissions user permissions for the option.
|
|
* @param sectionName start a new section in the menu with this name.
|
|
*/
|
|
OptionAttributes(const UiPermissions &uiPermissions, const String §ionName);
|
|
|
|
/**
|
|
* @brief << operator to create a new OptionAttributes with provided UiPermissions.
|
|
*
|
|
* @param uiPermissions
|
|
*
|
|
* @return Copy of *this but with the permissions set to @a uiPermissions.
|
|
*/
|
|
const OptionAttributes operator<<(const UiPermissions &uiPermissions) const;
|
|
|
|
/**
|
|
* @brief << operator to create a new OptionAttributes with provided UiSectionName.
|
|
*
|
|
* @param uiSectionName
|
|
*
|
|
* @return Copy of *this but with the section name set to @a uiSectionName.
|
|
*/
|
|
const OptionAttributes operator<<(const UiSectionName &uiSectionName) const;
|
|
|
|
/**
|
|
* @brief << operator to create a new OptionAttributes with provided UiHelpText.
|
|
*
|
|
* @param uiHelpText
|
|
*
|
|
* @return Copy of *this but with the help text set to @a uiHelpText.
|
|
*/
|
|
const OptionAttributes operator<<(const UiHelpText &uiHelpText) const;
|
|
|
|
const UiPermissions m_uiPermissions; ///< The ui permissions required to use this option.
|
|
const String m_sectionName;
|
|
const String m_helpText;
|
|
|
|
private:
|
|
//! Constructor for all members.
|
|
OptionAttributes(const UiPermissions &uiPermissions, const String §ionName, const String &helpText);
|
|
};
|
|
|
|
/**
|
|
* @brief Constructor.
|
|
*
|
|
* Use this constructor for a top level menu.
|
|
*
|
|
* @param name name of the menu.
|
|
* @param uiUser user using this menu.
|
|
* @param showQuitOption show a quit option to move back to a parent menu.
|
|
*/
|
|
ACTIV_FRAMEWORK_API UiMenu(const String &name, UiUser &uiUser, const bool showQuitOption = true);
|
|
|
|
/**
|
|
* @brief Constructor.
|
|
*
|
|
* Use this constructor for a sub-menu. Note a sub-menu always has a quit option.
|
|
*
|
|
* @param name name of the sub-menu.
|
|
* @param uiIo as passed to the menu option that is creating the sub-menu.
|
|
*/
|
|
ACTIV_FRAMEWORK_API UiMenu(const String &name, const UiIo &uiIo);
|
|
|
|
/**
|
|
* @brief Destructor.
|
|
*/
|
|
ACTIV_FRAMEWORK_API virtual ~UiMenu();
|
|
|
|
/**
|
|
* @brief Get the name of the menu.
|
|
*
|
|
* @return The name of the menu.
|
|
*/
|
|
ACTIV_FRAMEWORK_API String GetName() const;
|
|
|
|
/**
|
|
* @brief Set the name of the section for the next option added.
|
|
*
|
|
* If a section name is provided in the next option added then the section name added with this option will be ignored.
|
|
*
|
|
* @param sectionName name of the section to apply to the next option added.
|
|
*/
|
|
ACTIV_FRAMEWORK_API void SetSectionName(const String §ionName);
|
|
|
|
/**
|
|
* @brief Add a member function menu option.
|
|
*
|
|
* @param name name of the menu option.
|
|
* @param object reference to the object the function is to be run on.
|
|
* @param pFunction member function in class T.
|
|
* @param optionAttributes optional option attributes.
|
|
*/
|
|
template<typename T>
|
|
void AddOption(const String &name, T &object, void (T::*pFunction)(const UiIo &),
|
|
const OptionAttributes &optionAttributes = OptionAttributes())
|
|
{
|
|
Option *pOption = MakeOptionTemplate(CxxYZ::bind(pFunction, CxxYZ::ref(object), CxxYZ::_1), name, optionAttributes);
|
|
if (0 == pOption)
|
|
return;
|
|
|
|
m_optionVector.push_back(pOption);
|
|
}
|
|
|
|
/**
|
|
* @brief Add a const member function menu option.
|
|
*
|
|
* @param name name of the menu option.
|
|
* @param object reference to the object the function is to be run on.
|
|
* @param pFunction member function in class T.
|
|
* @param optionAttributes optional option attributes.
|
|
*/
|
|
template<typename T>
|
|
void AddOption(const String &name, const T &object, void (T::*pFunction)(const UiIo &) const,
|
|
const OptionAttributes &optionAttributes = OptionAttributes())
|
|
{
|
|
Option *pOption = MakeOptionTemplate(CxxYZ::bind(pFunction, CxxYZ::cref(object), CxxYZ::_1), name, optionAttributes);
|
|
if (0 == pOption)
|
|
return;
|
|
|
|
m_optionVector.push_back(pOption);
|
|
}
|
|
|
|
/**
|
|
* @brief Add a function object menu option.
|
|
*
|
|
* @param name name of the menu option.
|
|
* @param functionObject reference to a unary function object (where the parameter is const UiIo &) of the menu option.
|
|
* @param optionAttributes optional option attributes.
|
|
*/
|
|
template<typename T>
|
|
void AddOption(const String &name, const T &functionObject, const OptionAttributes &optionAttributes = OptionAttributes())
|
|
{
|
|
Option *pOption = MakeOptionTemplate(functionObject, name, optionAttributes);
|
|
if (0 == pOption)
|
|
return;
|
|
|
|
m_optionVector.push_back(pOption);
|
|
}
|
|
|
|
/**
|
|
* @brief Add a global function menu option.
|
|
*
|
|
* @param name name of the menu option.
|
|
* @param pFunction pointer to a global function to run.
|
|
* @param optionAttributes optional option attributes.
|
|
*/
|
|
void AddOption(const String &name, void (*pFunction)(const UiIo &uiIo),
|
|
const OptionAttributes &optionAttributes = OptionAttributes())
|
|
{
|
|
Option *pOption = MakeOptionTemplate(CxxYZ::bind(pFunction, CxxYZ::_1), name, optionAttributes);
|
|
if (0 == pOption)
|
|
return;
|
|
|
|
m_optionVector.push_back(pOption);
|
|
}
|
|
|
|
/**
|
|
* @brief Run the menu.
|
|
*/
|
|
ACTIV_FRAMEWORK_API void Run();
|
|
|
|
protected:
|
|
/**
|
|
* @brief Display a menu title.
|
|
*
|
|
* Default is "<name> options:". Override to change.
|
|
*
|
|
* @param uiIo to read / write to / from the user.
|
|
*/
|
|
ACTIV_FRAMEWORK_API virtual void DisplayTitle(const UiIo &uiIo) const;
|
|
|
|
/**
|
|
* @brief Display an option.
|
|
*
|
|
* Override this to change the format of menu option displays.
|
|
*
|
|
* @param uiIo to read / write to / from the user.
|
|
* @param optionIndex the index of the option.
|
|
* @param name the name of the option.
|
|
* @param optionAttributes attributes for this option.
|
|
*/
|
|
ACTIV_FRAMEWORK_API virtual void DisplayOption(const UiIo &uiIo, const size_t optionIndex, const String &name,
|
|
const OptionAttributes &optionAttributes) const;
|
|
|
|
/**
|
|
* @brief Display message after options.
|
|
*
|
|
* @param uiIo to read / write to / from the user.
|
|
*/
|
|
ACTIV_FRAMEWORK_API virtual void DisplayFooter(const UiIo &uiIo) const;
|
|
|
|
/**
|
|
* @brief Display the prompt that is used when selecting a menu option.
|
|
*
|
|
* Default is "# ". Override to change.
|
|
*
|
|
* @param uiIo to read / write to / from the user.
|
|
*/
|
|
ACTIV_FRAMEWORK_API virtual void DisplayOptionPrompt(const UiIo &uiIo) const;
|
|
|
|
/**
|
|
* @brief Get an option from the user.
|
|
*
|
|
* @param uiIo to read / write to / from the user.
|
|
* @param timeoutPeriod to pass to the UiIo option used to get input.
|
|
* @param optionString to receive the option.
|
|
*
|
|
* @retval STATUS_CODE_SUCCESS optionString populated.
|
|
* @retval STATUS_CODE_UNCHANGED enter hit with no input.
|
|
* @retval STATUS_CODE_TIMEOUT
|
|
* @retval ...
|
|
*/
|
|
ACTIV_FRAMEWORK_API virtual StatusCode GetOption(const UiIo &uiIo, const TimeoutPeriod timeoutPeriod,
|
|
String &optionString) const;
|
|
|
|
/**
|
|
* @brief User has entered an option; run it.
|
|
*
|
|
* Checks for quit (if the menu was constructed with a quit option),
|
|
* then for an unsigned integer in the range 1 ... number of options in menu, running the option if in range.
|
|
*
|
|
* @param uiIo to read / write to / from the user.
|
|
* @param optionString the entered option string.
|
|
*
|
|
* @retval STATUS_CODE_SUCCESS option has been run.
|
|
* @retval ...
|
|
*
|
|
* @throw UiMenuQuitException to leave the menu.
|
|
*/
|
|
ACTIV_FRAMEWORK_API virtual StatusCode ProcessOption(const UiIo &uiIo, const String &optionString);
|
|
|
|
private:
|
|
/**
|
|
* @brief Option class.
|
|
*/
|
|
class Option
|
|
{
|
|
public:
|
|
/**
|
|
* @brief Constructor.
|
|
*
|
|
* @param name name of the menu option.
|
|
* @param optionAttributes attributes for the menu option.
|
|
*/
|
|
ACTIV_FRAMEWORK_API Option(const String &name, const OptionAttributes &optionAttributes);
|
|
|
|
/**
|
|
* @brief Destructor.
|
|
*/
|
|
ACTIV_FRAMEWORK_API virtual ~Option();
|
|
|
|
/**
|
|
* @brief Run the option.
|
|
*
|
|
* @param uiIo to read / write to / from the user.
|
|
*/
|
|
virtual void Run(const UiIo &uiIo) const = 0;
|
|
|
|
String m_name;
|
|
OptionAttributes m_attributes;
|
|
};
|
|
|
|
/**
|
|
* @brief Template for member function options.
|
|
*/
|
|
template <typename T>
|
|
class OptionTemplate : public Option
|
|
{
|
|
public:
|
|
/**
|
|
* @brief Constructor.
|
|
*
|
|
* @param functionObject function object wrapping the member function to be run.
|
|
* @param name name of the menu option.
|
|
* @param optionAttributes attributes for the menu option.
|
|
*/
|
|
OptionTemplate(const T &functionObject, const String &name, const OptionAttributes &optionAttributes) :
|
|
Option(name, optionAttributes),
|
|
m_functionObject(functionObject)
|
|
{
|
|
}
|
|
|
|
private:
|
|
virtual void Run(const UiIo &uiIo) const ACTIV_OVERRIDE
|
|
{
|
|
m_functionObject(uiIo);
|
|
}
|
|
|
|
T m_functionObject; ///< Function object wrapping the ui function to run.
|
|
};
|
|
|
|
/**
|
|
* @brief Common construction code.
|
|
*/
|
|
void CommonCtor();
|
|
|
|
/**
|
|
* @brief Helper to create OptionTemplate from a function object.
|
|
*
|
|
* @param functionObject the function object.
|
|
* @param name name of the menu option.
|
|
* @param optionAttributes attributes for the menu option.
|
|
*
|
|
* @return Pointer to new OptionTemplate.
|
|
*/
|
|
template<typename T>
|
|
OptionTemplate<T> *MakeOptionTemplate(const T &functionObject, const String &name,
|
|
const OptionAttributes &optionAttributes)
|
|
{
|
|
OptionTemplate<T> *pOption = ACTIV_NULLPTR;
|
|
|
|
if ((!m_nextSectionName.empty()) && optionAttributes.m_sectionName.empty())
|
|
{
|
|
pOption = new (std::nothrow) OptionTemplate<T>(
|
|
functionObject, name, optionAttributes << UiSectionName(m_nextSectionName));
|
|
}
|
|
else
|
|
{
|
|
pOption = new (std::nothrow) OptionTemplate<T>(functionObject, name, optionAttributes);
|
|
}
|
|
|
|
m_nextSectionName.clear();
|
|
|
|
return pOption;
|
|
}
|
|
|
|
/**
|
|
* @brief Display the menu.
|
|
*
|
|
* @param uiIo to read / write to / from the user.
|
|
*/
|
|
void Display(const UiIo &uiIo) const;
|
|
|
|
/**
|
|
* @brief Display the list of options.
|
|
*
|
|
* @param uiIo to read / write to / from the user.
|
|
*/
|
|
void DisplayOptions(const UiIo &uiIo) const;
|
|
|
|
/**
|
|
* @brief Display the list of options that have help.
|
|
*
|
|
* @param uiIo to read / write to / from the user.
|
|
*/
|
|
void DisplayAvailableHelpOptions(const UiIo &uiIo) const;
|
|
|
|
/**
|
|
* @brief Run an option.
|
|
*
|
|
* @param uiIo to read / write to / from the user.
|
|
* @param optionIndex the index of the option (0 .. number of options - 1).
|
|
*
|
|
* @retval STATUS_CODE_SUCCESS option has been run.
|
|
* @retval STATUS_CODE_INVALID_INDEX @a optionIndex is null in m_optionVector.
|
|
* @retval STATUS_CODE_ACCESS_DENIED user is not permissioned for the option.
|
|
* @retval STATUS_CODE_EXIT to leave a menu.
|
|
* @retval ... current menu is redisplayed.
|
|
*/
|
|
StatusCode RunOption(const UiIo &uiIo, const size_t optionIndex);
|
|
|
|
/**
|
|
* @brief Display help for an option, if available.
|
|
*
|
|
* @param uiIo to read / write to / from the user.
|
|
* @param optionIndex the index of the option (0 .. number of options - 1).
|
|
*
|
|
* @retval STATUS_CODE_SUCCESS
|
|
* @retval STATUS_CODE_INVALID_INDEX @a optionIndex is null in m_optionVector.
|
|
*/
|
|
StatusCode HelpOption(const UiIo &uiIo, const size_t optionIndex) const;
|
|
|
|
/**
|
|
* @brief Check if the user is sufficiently permissioned to use an option.
|
|
*
|
|
* @return true if the user meets the permissioning requirements to use the option.
|
|
*/
|
|
bool IsUserPermissionedForOption(const UiPermissions &optionUiPermissions) const;
|
|
|
|
typedef std::vector<Option *> OptionVector; ///< Option vector type.
|
|
|
|
const String m_name; ///< The name of the menu.
|
|
UiUser & m_uiUser; ///< The user of this menu.
|
|
UiMenu * const m_pParentMenu; ///< Parent menu, or 0.
|
|
const bool m_showQuitOption; ///< Show quit menu option.
|
|
OptionVector m_optionVector; ///< Vector of menu options.
|
|
String m_nextSectionName; ///< Name of the section to apply to the next option added.
|
|
|
|
friend class UiIo;
|
|
};
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
inline UiSectionName::UiSectionName()
|
|
{
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
inline UiSectionName::UiSectionName(const String §ionName) :
|
|
String(sectionName)
|
|
{
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
inline UiHelpText::UiHelpText()
|
|
{
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
inline UiHelpText::UiHelpText(const String &helpText) :
|
|
String(helpText)
|
|
{
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
inline UiMenu::OptionAttributes::OptionAttributes() :
|
|
m_uiPermissions(UiPermissions::READ)
|
|
{
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
inline UiMenu::OptionAttributes::OptionAttributes(const UiPermissions &uiPermissions) :
|
|
m_uiPermissions(uiPermissions)
|
|
{
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
inline UiMenu::OptionAttributes::OptionAttributes(const String §ionName) :
|
|
m_uiPermissions(UiPermissions::READ),
|
|
m_sectionName(sectionName)
|
|
{
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
inline UiMenu::OptionAttributes::OptionAttributes(const UiPermissions &uiPermissions, const String §ionName) :
|
|
m_uiPermissions(uiPermissions),
|
|
m_sectionName(sectionName)
|
|
{
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
inline const UiMenu::OptionAttributes UiMenu::OptionAttributes::operator<<(const UiPermissions &uiPermissions) const
|
|
{
|
|
return OptionAttributes(uiPermissions, m_sectionName, m_helpText);
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
inline const UiMenu::OptionAttributes UiMenu::OptionAttributes::operator<<(const UiSectionName &uiSectionName) const
|
|
{
|
|
return OptionAttributes(m_uiPermissions, uiSectionName, m_helpText);
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
inline const UiMenu::OptionAttributes UiMenu::OptionAttributes::operator<<(const UiHelpText &uiHelpText) const
|
|
{
|
|
return OptionAttributes(m_uiPermissions, m_sectionName, uiHelpText);
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
inline UiMenu::OptionAttributes::OptionAttributes(const UiPermissions &uiPermissions, const String §ionName,
|
|
const String &helpText) :
|
|
m_uiPermissions(uiPermissions),
|
|
m_sectionName(sectionName),
|
|
m_helpText(helpText)
|
|
{
|
|
}
|
|
|
|
} // namespace Activ
|
|
|
|
#endif // (!defined ACTIV_FRAMEWORK_UI_MENU_H)
|