X-Git-Url: http://review.tizen.org/git/?p=platform%2Fcore%2Fuifw%2Fdali-toolkit.git;a=blobdiff_plain;f=dali-toolkit%2Fpublic-api%2Faccessibility-manager%2Faccessibility-manager.h;h=ac61e9ee9e6eeee5a58b3ec5e37726ced5254910;hp=b244acabb46a53e8a2888d65abe25d9fb8b3e86b;hb=0b5d20c961476797f7ffcdfb67026aac3253f94d;hpb=bea7b708b28cb38349ff99c3a656d40c065a8c54 diff --git a/dali-toolkit/public-api/accessibility-manager/accessibility-manager.h b/dali-toolkit/public-api/accessibility-manager/accessibility-manager.h index b244aca..ac61e9e 100644 --- a/dali-toolkit/public-api/accessibility-manager/accessibility-manager.h +++ b/dali-toolkit/public-api/accessibility-manager/accessibility-manager.h @@ -20,7 +20,6 @@ // EXTERNAL INCLUDES #include -#include namespace Dali { @@ -33,12 +32,12 @@ namespace Internal DALI_INTERNAL class AccessibilityManager; } /** - * @addtogroup dali_toolkit_accessibility_manager + * @addtogroup dali_toolkit_managers * @{ */ /** - * @brief Manages registration of actors in a accessibility focus chain and changing the + * @brief Manages registration of actors in an accessibility focus chain and changing the * focused actor within that chain. * * This class provides the functionality of registering the focus order and description @@ -49,11 +48,12 @@ class AccessibilityManager; * focused actor and emits a signal when the focus is changed. * * Signals - * | %Signal Name | Method | - * |-------------------------|------------------------------------| - * | focus-changed | @ref FocusChangedSignal() | - * | focus-overshot | @ref FocusOvershotSignal() | - * | focused-actor-activated | @ref FocusedActorActivatedSignal() | + * | %Signal Name | Method | + * |-----------------------|------------------------------------| + * | focusChanged | @ref FocusChangedSignal() | + * | focusOvershot | @ref FocusOvershotSignal() | + * | focusedActorActivated | @ref FocusedActorActivatedSignal() | + * @SINCE_1_0.0 */ class DALI_IMPORT_API AccessibilityManager : public BaseHandle { @@ -65,48 +65,55 @@ public: * @brief Accessibility Action Signal. * * The connected signal callback should return true if handled. + * @SINCE_1_0.0 */ - typedef Signal< bool ( AccessibilityManager& ) > AccessibilityActionSignalType; ///< Generic signal type - typedef Signal< bool ( AccessibilityManager&, const Dali::TouchEvent& )> AccessibilityActionScrollSignalType; ///< Scroll signal type + typedef Signal< bool ( AccessibilityManager& ) > AccessibilityActionSignalType; ///< Generic signal type @SINCE_1_0.0 + typedef Signal< bool ( AccessibilityManager&, const Dali::TouchEvent& )> AccessibilityActionScrollSignalType; ///< Scroll signal type @SINCE_1_0.0 /** * @brief Accessibility needs four information which will be read by screen-reader. * * Reading order : Label -> Trait -> Optional (Value and Hint) + * @SINCE_1_0.0 */ enum AccessibilityAttribute { - ACCESSIBILITY_LABEL = 0, ///< Simple text which contained in ui-control - ACCESSIBILITY_TRAIT, ///< Description of ui-control trait - ACCESSIBILITY_VALUE, ///< Current value of ui-control (Optional) - ACCESSIBILITY_HINT, ///< Hint for action (Optional) - ACCESSIBILITY_ATTRIBUTE_NUM ///< Number of attributes + ACCESSIBILITY_LABEL = 0, ///< Simple text which contained in ui-control @SINCE_1_0.0 + ACCESSIBILITY_TRAIT, ///< Description of ui-control trait @SINCE_1_0.0 + ACCESSIBILITY_VALUE, ///< Current value of ui-control (Optional) @SINCE_1_0.0 + ACCESSIBILITY_HINT, ///< Hint for action (Optional) @SINCE_1_0.0 + ACCESSIBILITY_ATTRIBUTE_NUM ///< Number of attributes @SINCE_1_0.0 }; /** * @brief Overshoot direction. + * @SINCE_1_0.0 */ enum FocusOvershotDirection { - OVERSHOT_PREVIOUS = -1, ///< Try to move previous of the first actor - OVERSHOT_NEXT = 1, ///< Try to move next of the last actor + OVERSHOT_PREVIOUS = -1, ///< Try to move previous of the first actor @SINCE_1_0.0 + OVERSHOT_NEXT = 1, ///< Try to move next of the last actor @SINCE_1_0.0 }; public: /// @brief Focus changed signal + /// @SINCE_1_0.0 typedef Signal< void ( Actor, Actor ) > FocusChangedSignalType; /// @brief Focus overshooted signal + /// @SINCE_1_0.0 typedef Signal< void ( Actor, FocusOvershotDirection ) > FocusOvershotSignalType; /// @brief Focused actor activated signal + /// @SINCE_1_0.0 typedef Signal< void ( Actor ) > FocusedActorActivatedSignalType; /** * @brief Create a AccessibilityManager handle; this can be initialised with AccessibilityManager::New(). * * Calling member functions with an uninitialised handle is not allowed. + * @SINCE_1_0.0 */ AccessibilityManager(); @@ -114,12 +121,14 @@ public: * @brief Destructor * * This is non-virtual since derived Handle types must not contain data or virtual methods. + * @SINCE_1_0.0 */ ~AccessibilityManager(); /** * @brief Get the singleton of AccessibilityManager object. * + * @SINCE_1_0.0 * @return A handle to the AccessibilityManager control. */ static AccessibilityManager Get(); @@ -127,22 +136,24 @@ public: /** * @brief Set the information of the specified actor's accessibility attribute. * - * @pre The AccessibilityManager has been initialized. - * @pre The Actor has been initialized. + * @SINCE_1_0.0 * @param actor The actor the text to be set with * @param type The attribute type the text to be set with * @param text The text for the actor's accessibility information + * @pre The AccessibilityManager has been initialized. + * @pre The Actor has been initialized. */ void SetAccessibilityAttribute(Actor actor, AccessibilityAttribute type, const std::string& text); /** * @brief Get the text of the specified actor's accessibility attribute. * - * @pre The AccessibilityManager has been initialized. - * @pre The Actor has been initialized. + * @SINCE_1_0.0 * @param actor The actor to be queried * @param type The attribute type to be queried * @return The text of the actor's accessibility information + * @pre The AccessibilityManager has been initialized. + * @pre The Actor has been initialized. */ std::string GetAccessibilityAttribute(Actor actor, AccessibilityAttribute type) const; @@ -159,10 +170,11 @@ public: * description but with no focus order being set yet) and therefore * that actor is not focusable. * - * @pre The AccessibilityManager has been initialized. - * @pre The Actor has been initialized. + * @SINCE_1_0.0 * @param actor The actor the focus order to be set with * @param order The focus order of the actor + * @pre The AccessibilityManager has been initialized. + * @pre The Actor has been initialized. */ void SetFocusOrder(Actor actor, const unsigned int order); @@ -172,10 +184,11 @@ public: * When the focus order is 0, it means the focus order of the actor * is undefined. * - * @pre The AccessibilityManager has been initialized. - * @pre The Actor has been initialized. + * @SINCE_1_0.0 * @param actor The actor to be queried * @return The focus order of the actor + * @pre The AccessibilityManager has been initialized. + * @pre The Actor has been initialized. */ unsigned int GetFocusOrder(Actor actor) const; @@ -190,22 +203,24 @@ public: * 1 where FOLast is the focus order of the very last control in the * focus chain. * - * @pre The AccessibilityManager has been initialized. + * @SINCE_1_0.0 * @return The focus order of the actor + * @pre The AccessibilityManager has been initialized. */ unsigned int GenerateNewFocusOrder() const; /** * @brief Get the actor that has the specified focus order. * - * It will return an empty handle if the actor is not in the stage - * or has a focus order of 0. + * It will return an empty handle if no actor in the stage + * has the specified focus order. * - * @pre The AccessibilityManager has been initialized. + * @SINCE_1_0.0 * @param order The focus order of the actor * * @return The actor that has the specified focus order or an empty * handle if no actor in the stage has the specified focus order. + * @pre The AccessibilityManager has been initialized. */ Actor GetActorByFocusOrder(const unsigned int order); @@ -216,38 +231,42 @@ public: * have a defined focus order and must be focusable, visible and in * the stage. * - * @pre The AccessibilityManager has been initialized. - * @pre The Actor has been initialized. + * @SINCE_1_0.0 * @param actor The actor to be focused * @return Whether the focus is successful or not + * @pre The AccessibilityManager has been initialized. + * @pre The Actor has been initialized. */ bool SetCurrentFocusActor(Actor actor); /** * @brief Get the current focused actor. * - * @pre The AccessibilityManager has been initialized. + * @SINCE_1_0.0 * @return A handle to the current focused actor or an empty handle if no actor is focused. + * @pre The AccessibilityManager has been initialized. */ Actor GetCurrentFocusActor(); /** * @brief Get the focus group of current focused actor. * - * @pre The AccessibilityManager has been initialized. - * + * @SINCE_1_0.0 * @return A handle to the immediate parent of the current focused * actor which is also a focus group, or an empty handle if no actor * is focused. + * @pre The AccessibilityManager has been initialized. + * */ Actor GetCurrentFocusGroup(); /** * @brief Get the focus order of currently focused actor. - * @pre The AccessibilityManager has been initialized. - * + * @SINCE_1_0.0 * @return The focus order of the currently focused actor or 0 if no * actor is in focus. + * @pre The AccessibilityManager has been initialized. + * */ unsigned int GetCurrentFocusOrder(); @@ -258,8 +277,9 @@ public: * When the focus movement is wrapped around, the focus will be moved * to the first focusable actor when it reaches the end of the focus chain. * - * @pre The AccessibilityManager has been initialized. + * @SINCE_1_0.0 * @return true if the moving was successful + * @pre The AccessibilityManager has been initialized. */ bool MoveFocusForward(); @@ -271,8 +291,9 @@ public: * moved to the last focusable actor when it reaches the beginning * of the focus chain. * - * @pre The AccessibilityManager has been initialized. + * @SINCE_1_0.0 * @return true if the moving was successful + * @pre The AccessibilityManager has been initialized. */ bool MoveFocusBackward(); @@ -280,13 +301,15 @@ public: * @brief Clear the focus from the current focused actor if any, so * that no actor is focused in the focus chain. * - * It will emit focus changed signal without current focused actor + * It will emit focus changed signal without current focused actor. + * @SINCE_1_0.0 * @pre The AccessibilityManager has been initialized. */ void ClearFocus(); /** * @brief Clear the every registered focusable actor from focus-manager. + * @SINCE_1_0.0 * @pre The AccessibilityManager has been initialized. */ void Reset(); @@ -295,20 +318,22 @@ public: * @brief Set whether an actor is a focus group that can limit the * scope of focus movement to its child actors in the focus chain. * - * @pre The AccessibilityManager has been initialized. - * @pre The Actor has been initialized. + * @SINCE_1_0.0 * @param actor The actor to be set as a focus group. * @param isFocusGroup Whether to set the actor to be a focus group or not. + * @pre The AccessibilityManager has been initialized. + * @pre The Actor has been initialized. */ void SetFocusGroup(Actor actor, bool isFocusGroup); /** * @brief Check whether the actor is set as a focus group or not. * - * @pre The AccessibilityManager has been initialized. - * @pre The Actor has been initialized. + * @SINCE_1_0.0 * @param actor The actor to be checked. * @return Whether the actor is set as a focus group. + * @pre The AccessibilityManager has been initialized. + * @pre The Actor has been initialized. */ bool IsFocusGroup(Actor actor) const; @@ -318,16 +343,18 @@ public: * When the group mode is enabled, the focus movement will be limited to the child actors * of the current focus group including the current focus group itself. The current focus * group is the closest ancestor of the current focused actor that set as a focus group. - * @pre The AccessibilityManager has been initialized. + * @SINCE_1_0.0 * @param enabled Whether the group mode is enabled or not + * @pre The AccessibilityManager has been initialized. */ void SetGroupMode(bool enabled); /** * @brief Get whether the group mode is enabled or not. * - * @pre The AccessibilityManager has been initialized. + * @SINCE_1_0.0 * @return Whether the group mode is enabled or not. + * @pre The AccessibilityManager has been initialized. */ bool GetGroupMode() const; @@ -337,16 +364,18 @@ public: * * When both the wrap mode and the group mode are enabled, focus will be * wrapped within the current focus group. Focus will not be wrapped in default. - * @pre The AccessibilityManager has been initialized. + * @SINCE_1_0.0 * @param wrapped Whether the focus movement is wrapped around or not + * @pre The AccessibilityManager has been initialized. */ void SetWrapMode(bool wrapped); /** * @brief Get whether the wrap mode is enabled or not. * - * @pre The AccessibilityManager has been initialized. + * @SINCE_1_0.0 * @return Whether the wrap mode is enabled or not. + * @pre The AccessibilityManager has been initialized. */ bool GetWrapMode() const; @@ -357,23 +386,26 @@ public: * AccessibilityManager and will be added to the focused actor as a * highlight. * + * @SINCE_1_0.0 + * @param indicator The indicator actor to be added * @pre The AccessibilityManager has been initialized. * @pre The indicator actor has been initialized. - * @param indicator The indicator actor to be added */ void SetFocusIndicatorActor(Actor indicator); /** * @brief Get the focus indicator actor. * - * @pre The AccessibilityManager has been initialized. + * @SINCE_1_0.0 * @return A handle to the focus indicator actor + * @pre The AccessibilityManager has been initialized. */ Actor GetFocusIndicatorActor(); /** * @brief Returns the closest ancestor of the given actor that is a focus group. * + * @SINCE_1_0.0 * @param actor The actor to be checked for its focus group * @return The focus group the given actor belongs to or an empty handle if the given actor doesn't belong to any focus group */ @@ -381,6 +413,7 @@ public: /** * @brief Returns the current position of the read action. + * @SINCE_1_0.0 * @return The current event position. */ Vector2 GetReadPosition() const; @@ -394,8 +427,9 @@ public: * @code * void YourCallbackName(Actor originalFocusedActor, Actor currentFocusedActor); * @endcode - * @pre The Object has been initialized. + * @SINCE_1_0.0 * @return The signal to connect to. + * @pre The Object has been initialized. */ FocusChangedSignalType& FocusChangedSignal(); @@ -406,8 +440,9 @@ public: * @code * void YourCallbackName(Actor currentFocusedActor, FocusOvershotDirection direction); * @endcode - * @pre The Object has been initialized. + * @SINCE_1_0.0 * @return The signal to connect to. + * @pre The Object has been initialized. */ FocusOvershotSignalType& FocusOvershotSignal(); @@ -418,12 +453,13 @@ public: * @code * void YourCallbackName(Actor activatedActor); * @endcode - * @pre The Object has been initialized. + * @SINCE_1_0.0 * @return The signal to connect to. + * @pre The Object has been initialized. */ FocusedActorActivatedSignalType& FocusedActorActivatedSignal(); - public: // Accessibility action signals. + public: // Accessibility action signals /** * @brief This is emitted when accessibility(screen-reader) feature turned on or off. @@ -432,6 +468,7 @@ public: * @code * bool YourCallback( AccessibilityManager& manager ); * @endcode + * @SINCE_1_0.0 * @return The signal to connect to. */ AccessibilityActionSignalType& StatusChangedSignal(); @@ -444,6 +481,7 @@ public: * @code * bool YourCallback( AccessibilityManager& manager ); * @endcode + * @SINCE_1_0.0 * @return The signal to connect to. */ AccessibilityActionSignalType& ActionNextSignal(); @@ -456,6 +494,7 @@ public: * @code * bool YourCallback( AccessibilityManager& manager ); * @endcode + * @SINCE_1_0.0 * @return The signal to connect to. */ AccessibilityActionSignalType& ActionPreviousSignal(); @@ -468,6 +507,7 @@ public: * @code * bool YourCallback( AccessibilityManager& manager ); * @endcode + * @SINCE_1_0.0 * @return The signal to connect to. */ AccessibilityActionSignalType& ActionActivateSignal(); @@ -480,6 +520,7 @@ public: * @code * bool YourCallback( AccessibilityManager& manager ); * @endcode + * @SINCE_1_0.0 * @return The signal to connect to. */ AccessibilityActionSignalType& ActionReadSignal(); @@ -492,6 +533,7 @@ public: * @code * bool YourCallback( AccessibilityManager& manager ); * @endcode + * @SINCE_1_0.0 * @return The signal to connect to. */ AccessibilityActionSignalType& ActionOverSignal(); @@ -504,6 +546,7 @@ public: * @code * bool YourCallback( AccessibilityManager& manager ); * @endcode + * @SINCE_1_0.0 * @return The signal to connect to. */ AccessibilityActionSignalType& ActionReadNextSignal(); @@ -516,6 +559,7 @@ public: * @code * bool YourCallback( AccessibilityManager& manager ); * @endcode + * @SINCE_1_0.0 * @return The signal to connect to. */ AccessibilityActionSignalType& ActionReadPreviousSignal(); @@ -528,6 +572,7 @@ public: * @code * bool YourCallback( AccessibilityManager& manager ); * @endcode + * @SINCE_1_0.0 * @return The signal to connect to. */ AccessibilityActionSignalType& ActionUpSignal(); @@ -540,6 +585,7 @@ public: * @code * bool YourCallback( AccessibilityManager& manager ); * @endcode + * @SINCE_1_0.0 * @return The signal to connect to. */ AccessibilityActionSignalType& ActionDownSignal(); @@ -552,6 +598,7 @@ public: * @code * bool YourCallback( AccessibilityManager& manager ); * @endcode + * @SINCE_1_0.0 * @return The signal to connect to. */ AccessibilityActionSignalType& ActionClearFocusSignal(); @@ -564,6 +611,7 @@ public: * @code * bool YourCallback( AccessibilityManager& manager ); * @endcode + * @SINCE_1_0.0 * @return The signal to connect to. */ AccessibilityActionSignalType& ActionBackSignal(); @@ -576,6 +624,7 @@ public: * @code * bool YourCallback( AccessibilityManager& manager ); * @endcode + * @SINCE_1_0.0 * @return The signal to connect to. */ AccessibilityActionSignalType& ActionScrollUpSignal(); @@ -588,114 +637,124 @@ public: * @code * bool YourCallback( AccessibilityManager& manager ); * @endcode + * @SINCE_1_0.0 * @return The signal to connect to. */ AccessibilityActionSignalType& ActionScrollDownSignal(); /** * @brief This is emitted when accessibility action is received to scroll left to the - * previous page (by two finger swipe left) + * previous page (by two finger swipe left). * * A callback of the following type may be connected: * @code * bool YourCallback( AccessibilityManager& manager ); * @endcode + * @SINCE_1_0.0 * @return The signal to connect to. */ AccessibilityActionSignalType& ActionPageLeftSignal(); /** * @brief This is emitted when accessibility action is received to scroll right to the - * next page (by two finger swipe right) + * next page (by two finger swipe right). * * A callback of the following type may be connected: * @code * bool YourCallback( AccessibilityManager& manager ); * @endcode + * @SINCE_1_0.0 * @return The signal to connect to. */ AccessibilityActionSignalType& ActionPageRightSignal(); /** * @brief This is emitted when accessibility action is received to scroll up to the - * previous page (by one finger swipe left and right) + * previous page (by one finger swipe left and right). * * A callback of the following type may be connected: * @code * bool YourCallback( AccessibilityManager& manager ); * @endcode + * @SINCE_1_0.0 * @return The signal to connect to. */ AccessibilityActionSignalType& ActionPageUpSignal(); /** * @brief This is emitted when accessibility action is received to scroll down to the - * next page (by one finger swipe right and left) + * next page (by one finger swipe right and left). * * A callback of the following type may be connected: * @code * bool YourCallback( AccessibilityManager& manager ); * @endcode + * @SINCE_1_0.0 * @return The signal to connect to. */ AccessibilityActionSignalType& ActionPageDownSignal(); /** * @brief This is emitted when accessibility action is received to move the focus to - * the first item on the screen (by one finger swipe up and down) + * the first item on the screen (by one finger swipe up and down). * * A callback of the following type may be connected: * @code * bool YourCallback( AccessibilityManager& manager ); * @endcode + * @SINCE_1_0.0 * @return The signal to connect to. */ AccessibilityActionSignalType& ActionMoveToFirstSignal(); /** * @brief This is emitted when accessibility action is received to move the focus to - * the last item on the screen (by one finger swipe down and up) + * the last item on the screen (by one finger swipe down and up). * * A callback of the following type may be connected: * @code * bool YourCallback( AccessibilityManager& manager ); * @endcode + * @SINCE_1_0.0 * @return The signal to connect to. */ AccessibilityActionSignalType& ActionMoveToLastSignal(); /** * @brief This is emitted when accessibility action is received to focus and read from the - * first item on the top continously (by three fingers single tap) + * first item on the top continously (by three fingers single tap). * * A callback of the following type may be connected: * @code * bool YourCallback( AccessibilityManager& manager ); * @endcode + * @SINCE_1_0.0 * @return The signal to connect to. */ AccessibilityActionSignalType& ActionReadFromTopSignal(); /** * @brief This is emitted when accessibility action is received to move the focus to and - * read from the next item continously (by three fingers double tap) + * read from the next item continously (by three fingers double tap). * * A callback of the following type may be connected: * @code * bool YourCallback( AccessibilityManager& manager ); * @endcode + * @SINCE_1_0.0 * @return The signal to connect to. */ AccessibilityActionSignalType& ActionReadFromNextSignal(); /** * @brief This is emitted when accessibility action is received to zoom (by one finger - * triple tap) + * triple tap). * * A callback of the following type may be connected: * @code * bool YourCallback( AccessibilityManager& manager ); * @endcode + * @SINCE_1_0.0 * @return The signal to connect to. */ AccessibilityActionSignalType& ActionZoomSignal(); @@ -708,6 +767,7 @@ public: * @code * bool YourCallback( AccessibilityManager& manager ); * @endcode + * @SINCE_1_0.0 * @return The signal to connect to. */ AccessibilityActionSignalType& ActionReadIndicatorInformationSignal(); @@ -720,6 +780,7 @@ public: * @code * bool YourCallback( AccessibilityManager& manager ); * @endcode + * @SINCE_1_0.0 * @return The signal to connect to. */ AccessibilityActionSignalType& ActionReadPauseResumeSignal(); @@ -732,6 +793,7 @@ public: * @code * bool YourCallback( AccessibilityManager& manager ); * @endcode + * @SINCE_1_0.0 * @return The signal to connect to. */ AccessibilityActionSignalType& ActionStartStopSignal(); @@ -744,6 +806,7 @@ public: * @code * bool YourCallback( AccessibilityManager& manager, const TouchEvent& event ); * @endcode + * @SINCE_1_0.0 * @return The signal to connect to. */ AccessibilityActionScrollSignalType& ActionScrollSignal();