1 #ifndef DALI_TOOLKIT_ACCESSIBILITY_MANAGER_H
2 #define DALI_TOOLKIT_ACCESSIBILITY_MANAGER_H
5 * Copyright (c) 2020 Samsung Electronics Co., Ltd.
7 * Licensed under the Apache License, Version 2.0 (the "License");
8 * you may not use this file except in compliance with the License.
9 * You may obtain a copy of the License at
11 * http://www.apache.org/licenses/LICENSE-2.0
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS,
15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
22 #include <dali/public-api/actors/actor.h>
25 #include <dali-toolkit/public-api/dali-toolkit-common.h>
31 namespace Internal DALI_INTERNAL
33 class AccessibilityManager;
36 * @addtogroup dali_toolkit_managers
41 * @brief Manages registration of actors in an accessibility focus chain and changing the
42 * focused actor within that chain.
44 * This class provides the functionality of registering the focus order and description
45 * of actors and maintaining the focus chain.
47 * It provides functionality of setting the
48 * focus and moving the focus forward and backward. It also draws a highlight for the
49 * focused actor and emits a signal when the focus is changed.
52 * | %Signal Name | Method |
53 * |-----------------------|------------------------------------|
54 * | focusChanged | @ref FocusChangedSignal() |
55 * | focusOvershot | @ref FocusOvershotSignal() |
56 * | focusedActorActivated | @ref FocusedActorActivatedSignal() |
59 class DALI_TOOLKIT_API AccessibilityManager : public BaseHandle
65 * @brief Accessibility Action Signal.
67 * The connected signal callback should return true if handled.
70 typedef Signal<bool(AccessibilityManager&)> AccessibilityActionSignalType; ///< Generic signal type @SINCE_1_0.0
71 typedef Signal<bool(AccessibilityManager&, const Dali::TouchEvent&)> AccessibilityActionScrollSignalType; ///< Scroll signal type @SINCE_1_0.0
74 * @brief Enumeration for accessibility that needs four information which will be read by screen-reader.
76 * Reading order : Label -> Trait -> Optional (Value and Hint)
79 enum AccessibilityAttribute
81 ACCESSIBILITY_LABEL = 0, ///< Simple text which contained in ui-control @SINCE_1_0.0
82 ACCESSIBILITY_TRAIT, ///< Description of ui-control trait @SINCE_1_0.0
83 ACCESSIBILITY_VALUE, ///< Current value of ui-control (Optional) @SINCE_1_0.0
84 ACCESSIBILITY_HINT, ///< Hint for action (Optional) @SINCE_1_0.0
85 ACCESSIBILITY_ATTRIBUTE_NUM ///< Number of attributes @SINCE_1_0.0
89 * @brief Enumeration for overshoot direction.
92 enum FocusOvershotDirection
94 OVERSHOT_PREVIOUS = -1, ///< Try to move previous of the first actor @SINCE_1_0.0
95 OVERSHOT_NEXT = 1, ///< Try to move next of the last actor @SINCE_1_0.0
99 /// @brief Focus changed signal
101 typedef Signal<void(Actor, Actor)> FocusChangedSignalType;
103 /// @brief Focus overshooted signal
105 typedef Signal<void(Actor, FocusOvershotDirection)> FocusOvershotSignalType;
107 /// @brief Focused actor activated signal
109 typedef Signal<void(Actor)> FocusedActorActivatedSignalType;
112 * @brief Creates an AccessibilityManager handle; this can be initialised with AccessibilityManager::New().
114 * Calling member functions with an uninitialized handle is not allowed.
117 AccessibilityManager();
122 * This is non-virtual since derived Handle types must not contain data or virtual methods.
125 ~AccessibilityManager();
128 * @brief Gets the singleton of AccessibilityManager object.
131 * @return A handle to the AccessibilityManager control
133 static AccessibilityManager Get();
136 * @brief Sets the information of the specified actor's accessibility attribute.
139 * @param actor The actor, the text to be set with
140 * @param type The attribute type the text to be set with
141 * @param text The text for the actor's accessibility information
142 * @pre The AccessibilityManager has been initialized.
143 * @pre The Actor has been initialized.
145 void SetAccessibilityAttribute(Actor actor, AccessibilityAttribute type, const std::string& text);
148 * @brief Delete the information of the specified actor's accessibility attribute.
151 * @param actor The actor to delete
153 void DeleteAccessibilityAttribute(Actor actor);
156 * @brief Gets the text of the specified actor's accessibility attribute.
159 * @param actor The actor to be queried
160 * @param type The attribute type to be queried
161 * @return The text of the actor's accessibility information
162 * @pre The AccessibilityManager has been initialized.
163 * @pre The Actor has been initialized.
165 std::string GetAccessibilityAttribute(Actor actor, AccessibilityAttribute type) const;
168 * @brief Sets the focus order of the actor.
170 * The focus order of each actor in the focus chain is unique.
171 * If there is another actor assigned with the same focus order
172 * already, the new actor will be inserted to the focus chain with
173 * that focus order, and the focus order of the original actor and
174 * all the actors followed in the focus chain will be increased
175 * accordingly. If the focus order assigned to the actor is 0, it
176 * means that actor's focus order is undefined (e.g. the actor has a
177 * description but with no focus order being set yet) and therefore
178 * that actor is not focusable.
181 * @param actor The actor the focus order to be set with
182 * @param order The focus order of the actor
183 * @pre The AccessibilityManager has been initialized.
184 * @pre The Actor has been initialized.
186 void SetFocusOrder(Actor actor, const unsigned int order);
189 * @brief Gets the focus order of the actor.
191 * When the focus order is 0, it means the focus order of the actor
195 * @param actor The actor to be queried
196 * @return The focus order of the actor
197 * @pre The AccessibilityManager has been initialized.
198 * @pre The Actor has been initialized.
200 unsigned int GetFocusOrder(Actor actor) const;
203 * @brief Generates a new focus order number which can be used to
204 * assign to actors which need to be appended to the end of the
205 * current focus order chain.
207 * The new number will be an increment over the very last focus
208 * order number in the focus chain. If the focus chain is empty then
209 * the function returns 1, else the number returned will be FOLast +
210 * 1 where FOLast is the focus order of the very last control in the
214 * @return The focus order of the actor
215 * @pre The AccessibilityManager has been initialized.
217 unsigned int GenerateNewFocusOrder() const;
220 * @brief Gets the actor that has the specified focus order.
222 * It will return an empty handle if no actor in the stage
223 * has the specified focus order.
226 * @param order The focus order of the actor
228 * @return The actor that has the specified focus order or an empty
229 * handle if no actor in the stage has the specified focus order
230 * @pre The AccessibilityManager has been initialized.
232 Actor GetActorByFocusOrder(const unsigned int order);
235 * @brief Moves the focus to the specified actor.
237 * Only one actor can be focused at the same time. The actor must
238 * have a defined focus order and must be focusable, visible and in
242 * @param actor The actor to be focused
243 * @return Whether the focus is successful or not
244 * @pre The AccessibilityManager has been initialized.
245 * @pre The Actor has been initialized.
247 bool SetCurrentFocusActor(Actor actor);
250 * @brief Gets the current focused actor.
253 * @return A handle to the current focused actor or an empty handle if no actor is focused
254 * @pre The AccessibilityManager has been initialized.
256 Actor GetCurrentFocusActor();
259 * @brief Gets the focus group of current focused actor.
262 * @return A handle to the immediate parent of the current focused
263 * actor which is also a focus group, or an empty handle if no actor
265 * @pre The AccessibilityManager has been initialized.
268 Actor GetCurrentFocusGroup();
271 * @brief Gets the focus order of currently focused actor.
273 * @return The focus order of the currently focused actor or 0 if no
275 * @pre The AccessibilityManager has been initialized.
278 unsigned int GetCurrentFocusOrder();
281 * @brief Moves the focus to the next focusable actor in the focus
282 * chain (according to the focus traversal order).
284 * When the focus movement is wrapped around, the focus will be moved
285 * to the first focusable actor when it reaches the end of the focus chain.
288 * @return true if the moving was successful
289 * @pre The AccessibilityManager has been initialized.
291 bool MoveFocusForward();
294 * @brief Moves the focus to the previous focusable actor in the
295 * focus chain (according to the focus traversal order).
297 * When the focus movement is wrapped around, the focus will be
298 * moved to the last focusable actor when it reaches the beginning
299 * of the focus chain.
302 * @return true if the moving was successful
303 * @pre The AccessibilityManager has been initialized.
305 bool MoveFocusBackward();
308 * @brief Clears the focus from the current focused actor if any, so
309 * that no actor is focused in the focus chain.
311 * It will emit focus changed signal without current focused actor.
313 * @pre The AccessibilityManager has been initialized.
318 * @brief Clears every registered focusable actor from focus-manager.
320 * @pre The AccessibilityManager has been initialized.
325 * @brief Sets whether an actor is a focus group that can limit the
326 * scope of focus movement to its child actors in the focus chain.
329 * @param actor The actor to be set as a focus group
330 * @param isFocusGroup Whether to set the actor to be a focus group or not
331 * @pre The AccessibilityManager has been initialized.
332 * @pre The Actor has been initialized.
334 void SetFocusGroup(Actor actor, bool isFocusGroup);
337 * @brief Checks whether the actor is set as a focus group or not.
340 * @param actor The actor to be checked
341 * @return Whether the actor is set as a focus group
342 * @pre The AccessibilityManager has been initialized.
343 * @pre The Actor has been initialized.
345 bool IsFocusGroup(Actor actor) const;
348 * @brief Sets whether the group mode is enabled or not.
350 * When the group mode is enabled, the focus movement will be limited to the child actors
351 * of the current focus group including the current focus group itself. The current focus
352 * group is the closest ancestor of the current focused actor that is set as a focus group.
354 * @param enabled Whether the group mode is enabled or not
355 * @pre The AccessibilityManager has been initialized.
357 void SetGroupMode(bool enabled);
360 * @brief Gets whether the group mode is enabled or not.
363 * @return Whether the group mode is enabled or not.
364 * @pre The AccessibilityManager has been initialized.
366 bool GetGroupMode() const;
369 * @brief Sets whether focus will be moved to the beginning of the
370 * focus chain when it reaches the end or vice versa.
372 * When both the wrap mode and the group mode are enabled, focus will be
373 * wrapped within the current focus group. Focus will not be wrapped in default.
375 * @param wrapped Whether the focus movement is wrapped around or not
376 * @pre The AccessibilityManager has been initialized.
378 void SetWrapMode(bool wrapped);
381 * @brief Gets whether the wrap mode is enabled or not.
384 * @return Whether the wrap mode is enabled or not.
385 * @pre The AccessibilityManager has been initialized.
387 bool GetWrapMode() const;
390 * @brief Sets the focus indicator actor.
392 * This will replace the default focus indicator actor in
393 * AccessibilityManager and will be added to the focused actor as a
397 * @param indicator The indicator actor to be added
398 * @pre The AccessibilityManager has been initialized.
399 * @pre The indicator actor has been initialized.
401 void SetFocusIndicatorActor(Actor indicator);
404 * @brief Gets the focus indicator actor.
407 * @return A handle to the focus indicator actor
408 * @pre The AccessibilityManager has been initialized.
410 Actor GetFocusIndicatorActor();
413 * @brief Returns the closest ancestor of the given actor that is a focus group.
416 * @param actor The actor to be checked for its focus group
417 * @return The focus group the given actor belongs to or an empty handle if the given actor doesn't belong to any focus group
419 Actor GetFocusGroup(Actor actor);
422 * @brief Returns the current position of the read action.
424 * @return The current event position
426 Vector2 GetReadPosition() const;
429 * @brief Enables Accessibility or not.
430 * @param[in] enabled True if Accessibility should be enabled.
432 void EnableAccessibility( bool enabled );
435 * @brief Query whether the accessibility(screen-reader) is enabled.
437 * The accessibility will be enabled by system setting.
438 * @return True if the accessibility(screen-reader) is enabled.
440 bool IsEnabled() const;
444 * @brief This signal is emitted when the current focused actor is changed.
446 * A callback of the following type may be connected:
448 * void YourCallbackName(Actor originalFocusedActor, Actor currentFocusedActor);
451 * @return The signal to connect to
452 * @pre The Object has been initialized.
454 FocusChangedSignalType& FocusChangedSignal();
457 * @brief This signal is emitted when there is no way to move focus further.
459 * A callback of the following type may be connected:
461 * void YourCallbackName(Actor currentFocusedActor, FocusOvershotDirection direction);
464 * @return The signal to connect to
465 * @pre The Object has been initialized.
467 FocusOvershotSignalType& FocusOvershotSignal();
470 * @brief This signal is emitted when the current focused actor is activated.
472 * A callback of the following type may be connected:
474 * void YourCallbackName(Actor activatedActor);
477 * @return The signal to connect to
478 * @pre The Object has been initialized.
480 FocusedActorActivatedSignalType& FocusedActorActivatedSignal();
482 public: // Accessibility action signals
484 * @brief This is emitted when accessibility(screen-reader) feature turned on or off.
486 * A callback of the following type may be connected:
488 * bool YourCallback( AccessibilityManager& manager );
491 * @return The signal to connect to
493 AccessibilityActionSignalType& StatusChangedSignal();
496 * @brief This is emitted when accessibility action is received to move focus to the next
497 * focusable actor (by one finger flick down).
499 * A callback of the following type may be connected:
501 * bool YourCallback( AccessibilityManager& manager );
504 * @return The signal to connect to
506 AccessibilityActionSignalType& ActionNextSignal();
509 * @brief This is emitted when accessibility action is received to move focus to the previous
510 * focusable actor (by one finger flick up).
512 * A callback of the following type may be connected:
514 * bool YourCallback( AccessibilityManager& manager );
517 * @return The signal to connect to
519 AccessibilityActionSignalType& ActionPreviousSignal();
522 * @brief This is emitted when accessibility action is received to activate the current focused
523 * actor (by one finger double tap).
525 * A callback of the following type may be connected:
527 * bool YourCallback( AccessibilityManager& manager );
530 * @return The signal to connect to
532 AccessibilityActionSignalType& ActionActivateSignal();
535 * @brief This is emitted when accessibility action is received to focus and read the actor
536 * (by one finger tap).
538 * A callback of the following type may be connected:
540 * bool YourCallback( AccessibilityManager& manager );
543 * @return The signal to connect to
545 AccessibilityActionSignalType& ActionReadSignal();
548 * @brief This is emitted when accessibility action is received to focus and read the actor
549 * (by one finger move).
551 * A callback of the following type may be connected:
553 * bool YourCallback( AccessibilityManager& manager );
556 * @return The signal to connect to
558 AccessibilityActionSignalType& ActionOverSignal();
561 * @brief This is emitted when accessibility action is received to move focus to the next
562 * focusable actor (by one finger flick right).
564 * A callback of the following type may be connected:
566 * bool YourCallback( AccessibilityManager& manager );
569 * @return The signal to connect to
571 AccessibilityActionSignalType& ActionReadNextSignal();
574 * @brief This is emitted when accessibility action is received to move focus to the previous
575 * focusable actor (by one finger flick left).
577 * A callback of the following type may be connected:
579 * bool YourCallback( AccessibilityManager& manager );
582 * @return The signal to connect to
584 AccessibilityActionSignalType& ActionReadPreviousSignal();
587 * @brief This is emitted when accessibility action is received to change the value when the
588 * current focused actor is a slider (by double finger down and move up and right).
590 * A callback of the following type may be connected:
592 * bool YourCallback( AccessibilityManager& manager );
595 * @return The signal to connect to
597 AccessibilityActionSignalType& ActionUpSignal();
600 * @brief This is emitted when accessibility action is received to change the value when the
601 * current focused actor is a slider (by double finger down and move down and left).
603 * A callback of the following type may be connected:
605 * bool YourCallback( AccessibilityManager& manager );
608 * @return The signal to connect to
610 AccessibilityActionSignalType& ActionDownSignal();
613 * @brief This is emitted when accessibility action is received to clear the focus from the
614 * current focused actor if any, so that no actor is focused in the focus chain.
616 * A callback of the following type may be connected:
618 * bool YourCallback( AccessibilityManager& manager );
621 * @return The signal to connect to
623 AccessibilityActionSignalType& ActionClearFocusSignal();
626 * @brief This is emitted when accessibility action is received to navigate back (by two
627 * fingers circle draw).
629 * A callback of the following type may be connected:
631 * bool YourCallback( AccessibilityManager& manager );
634 * @return The signal to connect to
636 AccessibilityActionSignalType& ActionBackSignal();
639 * @brief This is emitted when accessibility action is received to scroll up the list
640 * (by two finger swipe up).
642 * A callback of the following type may be connected:
644 * bool YourCallback( AccessibilityManager& manager );
647 * @return The signal to connect to
649 AccessibilityActionSignalType& ActionScrollUpSignal();
652 * @brief This is emitted when accessibility action is received to scroll down the list
653 * (by two finger swipe down).
655 * A callback of the following type may be connected:
657 * bool YourCallback( AccessibilityManager& manager );
660 * @return The signal to connect to
662 AccessibilityActionSignalType& ActionScrollDownSignal();
665 * @brief This is emitted when accessibility action is received to scroll left to the
666 * previous page (by two finger swipe left).
668 * A callback of the following type may be connected:
670 * bool YourCallback( AccessibilityManager& manager );
673 * @return The signal to connect to
675 AccessibilityActionSignalType& ActionPageLeftSignal();
678 * @brief This is emitted when accessibility action is received to scroll right to the
679 * next page (by two finger swipe right).
681 * A callback of the following type may be connected:
683 * bool YourCallback( AccessibilityManager& manager );
686 * @return The signal to connect to
688 AccessibilityActionSignalType& ActionPageRightSignal();
691 * @brief This is emitted when accessibility action is received to scroll up to the
692 * previous page (by one finger swipe left and right).
694 * A callback of the following type may be connected:
696 * bool YourCallback( AccessibilityManager& manager );
699 * @return The signal to connect to
701 AccessibilityActionSignalType& ActionPageUpSignal();
704 * @brief This is emitted when accessibility action is received to scroll down to the
705 * next page (by one finger swipe right and left).
707 * A callback of the following type may be connected:
709 * bool YourCallback( AccessibilityManager& manager );
712 * @return The signal to connect to
714 AccessibilityActionSignalType& ActionPageDownSignal();
717 * @brief This is emitted when accessibility action is received to move the focus to
718 * the first item on the screen (by one finger swipe up and down).
720 * A callback of the following type may be connected:
722 * bool YourCallback( AccessibilityManager& manager );
725 * @return The signal to connect to
727 AccessibilityActionSignalType& ActionMoveToFirstSignal();
730 * @brief This is emitted when accessibility action is received to move the focus to
731 * the last item on the screen (by one finger swipe down and up).
733 * A callback of the following type may be connected:
735 * bool YourCallback( AccessibilityManager& manager );
738 * @return The signal to connect to
740 AccessibilityActionSignalType& ActionMoveToLastSignal();
743 * @brief This is emitted when accessibility action is received to focus and read from the
744 * first item on the top continuously (by three fingers single tap).
746 * A callback of the following type may be connected:
748 * bool YourCallback( AccessibilityManager& manager );
751 * @return The signal to connect to.
753 AccessibilityActionSignalType& ActionReadFromTopSignal();
756 * @brief This is emitted when accessibility action is received to move the focus to and
757 * read from the next item continuously (by three fingers double tap).
759 * A callback of the following type may be connected:
761 * bool YourCallback( AccessibilityManager& manager );
764 * @return The signal to connect to
766 AccessibilityActionSignalType& ActionReadFromNextSignal();
769 * @brief This is emitted when accessibility action is received to zoom (by one finger
772 * A callback of the following type may be connected:
774 * bool YourCallback( AccessibilityManager& manager );
777 * @return The signal to connect to
779 AccessibilityActionSignalType& ActionZoomSignal();
782 * @brief This is emitted when accessibility action is received to pause/resume the
783 * current speech (by two fingers single tap).
785 * A callback of the following type may be connected:
787 * bool YourCallback( AccessibilityManager& manager );
790 * @return The signal to connect to
792 AccessibilityActionSignalType& ActionReadPauseResumeSignal();
795 * @brief This is emitted when accessibility action is received to start/stop the
796 * current action (by two fingers double tap).
798 * A callback of the following type may be connected:
800 * bool YourCallback( AccessibilityManager& manager );
803 * @return The signal to connect to
805 AccessibilityActionSignalType& ActionStartStopSignal();
808 * @brief This is emitted when accessibility action is received to handle scroll event (by two
811 * A callback of the following type may be connected:
813 * bool YourCallback( AccessibilityManager& manager, const TouchEvent& event );
816 * @return The signal to connect to
818 AccessibilityActionScrollSignalType& ActionScrollSignal();
821 * @brief This is emitted when accessibility action is received to forward the event
822 * to the application (by one finger double tap and hold).
824 * A callback of the following type may be connected:
826 * bool YourCallback( AccessibilityManager& manager );
828 * @return The signal to connect to
830 AccessibilityActionSignalType& ActionForwardSignal();
833 explicit DALI_INTERNAL AccessibilityManager(Internal::AccessibilityManager* impl);
835 }; // class AccessibilityManager
840 } // namespace Toolkit
844 #endif // DALI_TOOLKIT_ACCESSIBILITY_MANAGER_H