/** * @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); /** * @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 m_pUiComponentMap; friend class UiComponentMap; friend class UiMainComponent; }; } // namespace Activ #endif // (!defined ACTIV_FRAMEWORK_UI_COMPONENT_H)