Files

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 &sectionName);
};
// ---------------------------------------------------------------------------------------------------------------------------------
//! 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 &sectionName);
/**
* @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 &sectionName);
/**
* @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 &sectionName, 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 &sectionName);
/**
* @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 &sectionName) :
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 &sectionName) :
m_uiPermissions(UiPermissions::READ),
m_sectionName(sectionName)
{
}
// ---------------------------------------------------------------------------------------------------------------------------------
inline UiMenu::OptionAttributes::OptionAttributes(const UiPermissions &uiPermissions, const String &sectionName) :
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 &sectionName,
const String &helpText) :
m_uiPermissions(uiPermissions),
m_sectionName(sectionName),
m_helpText(helpText)
{
}
} // namespace Activ
#endif // (!defined ACTIV_FRAMEWORK_UI_MENU_H)