Files

205 lines
5.9 KiB
C++

/**
* @file include/ActivMiddleware/ActivFramework/UiComponent.h
*
* @brief Header file for the ui component class.
*/
#if (!defined ACTIV_FRAMEWORK_UI_COMPONENT_H)
#define ACTIV_FRAMEWORK_UI_COMPONENT_H
#include "ActivMiddleware/ActivFramework/External.h"
#include "ActivMiddleware/ActivFramework/Component.h"
#include "ActivMiddleware/ActivFramework/Application.h"
//! Activ namespace.
namespace Activ
{
class UiUser;
class UiIo;
class UiComponentMap;
class UiMainComponent;
// ---------------------------------------------------------------------------------------------------------------------------------
/**
* @brief Ui component class.
*
* Note a ui component cannot be attached to the ui service endpoint.
*/
class UiComponent : public Component
{
public:
//! Ui component type enumeration.
enum UnderlyingType
{
TYPE_STANDARD, ///< Normal user uis.
TYPE_MAIN, ///< For main menu component.
TYPE_MIDDLEWARE, ///< For core service / middleware provided uis.
TYPE_LITE, ///< Lite ui.
TYPE_TAGGED ///< Distinguished by a string. For grouping, for example, worker thread uis of some service.
};
//! Ui component type.
class Type
{
public:
//! Default constructor to TYPE_STANDARD.
ACTIV_FRAMEWORK_API Type();
/**
* @brief Constructor.
*
* @param type the UnderlyinType for the ui, except TYPE_TAGGED.
*/
ACTIV_FRAMEWORK_API Type(const UnderlyingType type);
/**
* @brief Constructor for TYPE_TAGGED.
*
* @param tag string to associate with the type TYPE_TAGGED.
*/
ACTIV_FRAMEWORK_API explicit Type(const String &tag);
//! Equality operator.
ACTIV_FRAMEWORK_API bool operator==(const Type &rhs) const;
UnderlyingType m_value;
String m_tag;
};
/**
* @brief Constructor.
*
* @param managedEndPoint endpoint to attach to - must be singly threaded.
* @param uiComponentName name of the ui component. This name is used to register the component with the main menu.
* @param type the type to register as.
* @param uiServiceName name of the ui service.
*
* @throw Exception.
*/
ACTIV_FRAMEWORK_API UiComponent(ManagedEndPoint &managedEndPoint, const String &uiComponentName,
const Type type = TYPE_STANDARD, const String &uiServiceName = Application::GetUiServiceName());
/**
* @brief Constructor.
*
* @param managedEndPoint endpoint to attach to - must be singly threaded.
* @param uiComponentName name of the ui component. This name is used to register the component with parent UiComponent.
* @param parentUiComponent UiComponent that will allow switching to this ui.
* @param type the type to register as.
* @param uiServiceName name of the ui service.
*
* @throw Exception.
*/
ACTIV_FRAMEWORK_API UiComponent(ManagedEndPoint &managedEndPoint, const String &uiComponentName,
const UiComponent &parentUiComponent, const Type type, const String &uiServiceName = Application::GetUiServiceName());
//! Destructor.
ACTIV_FRAMEWORK_API ~UiComponent();
/**
* @brief Run the component.
*
* An override of this function must construct a menu using uiUser, and call Run() on the menu object.
*
* @param uiUser the user wishing to communicate with this component.
*/
virtual void Run(UiUser &uiUser) = 0;
//! Get the name of the ui service this component is attached to.
ACTIV_FRAMEWORK_API const String &GetUiServiceName() const;
//! Get the name of this ui component.
ACTIV_FRAMEWORK_API const String &GetName() const;
// Component overrides.
ACTIV_FRAMEWORK_API virtual void Enable() ACTIV_OVERRIDE;
ACTIV_FRAMEWORK_API virtual void Disable() ACTIV_OVERRIDE;
//! Convert component type to string.
ACTIV_FRAMEWORK_API static const String UiComponentTypeToString(const Type type);
/**
* @brief Display registered UiComponents.
*
* @param uiIo
* @param type optional type to filter the display by.
*/
ACTIV_FRAMEWORK_API void UiDisplayComponentMenu(const UiIo &uiIo, const Boost::optional<Type> &type);
/**
* @brief Switch to a registered UiComponent.
*
* @param uiIo
* @param uiComponentAddress
*
* @return True if @a uiComponentAddress was a valid UiComponent and a message was sent to the UiService to switch this
* user to it.
*/
ACTIV_FRAMEWORK_API bool UiSwitchToUiComponent(const UiIo &uiIo, const Address &uiComponentAddress);
protected:
ACTIV_FRAMEWORK_API StatusCode OnMessage(HeapMessage &heapMessage) ACTIV_OVERRIDE;
/**
* @brief Is the type of a ui component that is attemting to register with us one we'll accept?
*
* The default implementation allows:
* TYPE_STANDARD
* TYPE_MIDDLEWARE
* TYPE_TAGGED
* Override to allow other types.
*
* @param type
*
* @return Boolean.
*/
ACTIV_FRAMEWORK_API virtual bool IsValidRegistrationType(const UnderlyingType type) const;
const Type m_type; ///< Ui component type.
const Address m_uiServiceAddress;
private:
/**
* @brief Register the ui component with the main menu.
*
* @retval STATUS_CODE_SUCCESS
* @retval ...
*/
StatusCode Register() const;
/**
* @brief Deregister the ui component.
*
* @retval STATUS_CODE_SUCCESS
* @retval ...
*/
StatusCode Deregister() const;
// Component overrides.
ACTIV_FRAMEWORK_API virtual StatusCode OnRequest(HeapMessage &request) ACTIV_OVERRIDE;
/**
* @brief Process a new user request.
*
* @param request the request HeapMessage.
*/
void ProcessNewUserRequest(HeapMessage &request);
const String m_uiServiceName; ///< Name of ui service.
const String m_name; ///< Name of the component as provided to constructor.
const String m_hierarchicalName; ///< Name decorated by any parent UiComponent names.
const Address m_parentUiComponentAddress;
const Address m_registrationAddress;
Boost::scoped_ptr<UiComponentMap> m_pUiComponentMap;
friend class UiComponentMap;
friend class UiMainComponent;
};
} // namespace Activ
#endif // (!defined ACTIV_FRAMEWORK_UI_COMPONENT_H)