1 #ifndef __DALI_TOOLKIT_ACCESSIBILITY_MANAGER_H__
2 #define __DALI_TOOLKIT_ACCESSIBILITY_MANAGER_H__
5 * Copyright (c) 2018 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>
33 namespace Internal DALI_INTERNAL
35 class AccessibilityManager;
38 * @addtogroup dali_toolkit_managers
43 * @brief Manages registration of actors in an accessibility focus chain and changing the
44 * focused actor within that chain.
46 * This class provides the functionality of registering the focus order and description
47 * of actors and maintaining the focus chain.
49 * It provides functionality of setting the
50 * focus and moving the focus forward and backward. It also draws a highlight for the
51 * focused actor and emits a signal when the focus is changed.
54 * | %Signal Name | Method |
55 * |-----------------------|------------------------------------|
56 * | focusChanged | @ref FocusChangedSignal() |
57 * | focusOvershot | @ref FocusOvershotSignal() |
58 * | focusedActorActivated | @ref FocusedActorActivatedSignal() |
61 class DALI_TOOLKIT_API AccessibilityManager : public BaseHandle
68 * @brief Accessibility Action Signal.
70 * The connected signal callback should return true if handled.
73 typedef Signal< bool ( AccessibilityManager& ) > AccessibilityActionSignalType; ///< Generic signal type @SINCE_1_0.0
74 typedef Signal< bool ( AccessibilityManager&, const Dali::TouchEvent& )> AccessibilityActionScrollSignalType; ///< Scroll signal type @SINCE_1_0.0
77 * @brief Enumeration for accessibility that needs four information which will be read by screen-reader.
79 * Reading order : Label -> Trait -> Optional (Value and Hint)
82 enum AccessibilityAttribute
84 ACCESSIBILITY_LABEL = 0, ///< Simple text which contained in ui-control @SINCE_1_0.0
85 ACCESSIBILITY_TRAIT, ///< Description of ui-control trait @SINCE_1_0.0
86 ACCESSIBILITY_VALUE, ///< Current value of ui-control (Optional) @SINCE_1_0.0
87 ACCESSIBILITY_HINT, ///< Hint for action (Optional) @SINCE_1_0.0
88 ACCESSIBILITY_ATTRIBUTE_NUM ///< Number of attributes @SINCE_1_0.0
92 * @brief Enumeration for overshoot direction.
95 enum FocusOvershotDirection
97 OVERSHOT_PREVIOUS = -1, ///< Try to move previous of the first actor @SINCE_1_0.0
98 OVERSHOT_NEXT = 1, ///< Try to move next of the last actor @SINCE_1_0.0
103 /// @brief Focus changed signal
105 typedef Signal< void ( Actor, Actor ) > FocusChangedSignalType;
107 /// @brief Focus overshooted signal
109 typedef Signal< void ( Actor, FocusOvershotDirection ) > FocusOvershotSignalType;
111 /// @brief Focused actor activated signal
113 typedef Signal< void ( Actor ) > FocusedActorActivatedSignalType;
116 * @brief Creates an AccessibilityManager handle; this can be initialised with AccessibilityManager::New().
118 * Calling member functions with an uninitialized handle is not allowed.
121 AccessibilityManager();
126 * This is non-virtual since derived Handle types must not contain data or virtual methods.
129 ~AccessibilityManager();
132 * @brief Gets the singleton of AccessibilityManager object.
135 * @return A handle to the AccessibilityManager control
137 static AccessibilityManager Get();
140 * @brief Sets the information of the specified actor's accessibility attribute.
143 * @param actor The actor, the text to be set with
144 * @param type The attribute type the text to be set with
145 * @param text The text for the actor's accessibility information
146 * @pre The AccessibilityManager has been initialized.
147 * @pre The Actor has been initialized.
149 void SetAccessibilityAttribute(Actor actor, AccessibilityAttribute type, const std::string& text);
152 * @brief Gets the text of the specified actor's accessibility attribute.
155 * @param actor The actor to be queried
156 * @param type The attribute type to be queried
157 * @return The text of the actor's accessibility information
158 * @pre The AccessibilityManager has been initialized.
159 * @pre The Actor has been initialized.
161 std::string GetAccessibilityAttribute(Actor actor, AccessibilityAttribute type) const;
164 * @brief Sets the focus order of the actor.
166 * The focus order of each actor in the focus chain is unique.
167 * If there is another actor assigned with the same focus order
168 * already, the new actor will be inserted to the focus chain with
169 * that focus order, and the focus order of the original actor and
170 * all the actors followed in the focus chain will be increased
171 * accordingly. If the focus order assigned to the actor is 0, it
172 * means that actor's focus order is undefined (e.g. the actor has a
173 * description but with no focus order being set yet) and therefore
174 * that actor is not focusable.
177 * @param actor The actor the focus order to be set with
178 * @param order The focus order of the actor
179 * @pre The AccessibilityManager has been initialized.
180 * @pre The Actor has been initialized.
182 void SetFocusOrder(Actor actor, const unsigned int order);
185 * @brief Gets the focus order of the actor.
187 * When the focus order is 0, it means the focus order of the actor
191 * @param actor The actor to be queried
192 * @return The focus order of the actor
193 * @pre The AccessibilityManager has been initialized.
194 * @pre The Actor has been initialized.
196 unsigned int GetFocusOrder(Actor actor) const;
199 * @brief Generates a new focus order number which can be used to
200 * assign to actors which need to be appended to the end of the
201 * current focus order chain.
203 * The new number will be an increment over the very last focus
204 * order number in the focus chain. If the focus chain is empty then
205 * the function returns 1, else the number returned will be FOLast +
206 * 1 where FOLast is the focus order of the very last control in the
210 * @return The focus order of the actor
211 * @pre The AccessibilityManager has been initialized.
213 unsigned int GenerateNewFocusOrder() const;
216 * @brief Gets the actor that has the specified focus order.
218 * It will return an empty handle if no actor in the stage
219 * has the specified focus order.
222 * @param order The focus order of the actor
224 * @return The actor that has the specified focus order or an empty
225 * handle if no actor in the stage has the specified focus order
226 * @pre The AccessibilityManager has been initialized.
228 Actor GetActorByFocusOrder(const unsigned int order);
231 * @brief Moves the focus to the specified actor.
233 * Only one actor can be focused at the same time. The actor must
234 * have a defined focus order and must be focusable, visible and in
238 * @param actor The actor to be focused
239 * @return Whether the focus is successful or not
240 * @pre The AccessibilityManager has been initialized.
241 * @pre The Actor has been initialized.
243 bool SetCurrentFocusActor(Actor actor);
246 * @brief Gets the current focused actor.
249 * @return A handle to the current focused actor or an empty handle if no actor is focused
250 * @pre The AccessibilityManager has been initialized.
252 Actor GetCurrentFocusActor();
255 * @brief Gets the focus group of current focused actor.
258 * @return A handle to the immediate parent of the current focused
259 * actor which is also a focus group, or an empty handle if no actor
261 * @pre The AccessibilityManager has been initialized.
264 Actor GetCurrentFocusGroup();
267 * @brief Gets the focus order of currently focused actor.
269 * @return The focus order of the currently focused actor or 0 if no
271 * @pre The AccessibilityManager has been initialized.
274 unsigned int GetCurrentFocusOrder();
277 * @brief Moves the focus to the next focusable actor in the focus
278 * chain (according to the focus traversal order).
280 * When the focus movement is wrapped around, the focus will be moved
281 * to the first focusable actor when it reaches the end of the focus chain.
284 * @return true if the moving was successful
285 * @pre The AccessibilityManager has been initialized.
287 bool MoveFocusForward();
290 * @brief Moves the focus to the previous focusable actor in the
291 * focus chain (according to the focus traversal order).
293 * When the focus movement is wrapped around, the focus will be
294 * moved to the last focusable actor when it reaches the beginning
295 * of the focus chain.
298 * @return true if the moving was successful
299 * @pre The AccessibilityManager has been initialized.
301 bool MoveFocusBackward();
304 * @brief Clears the focus from the current focused actor if any, so
305 * that no actor is focused in the focus chain.
307 * It will emit focus changed signal without current focused actor.
309 * @pre The AccessibilityManager has been initialized.
314 * @brief Clears every registered focusable actor from focus-manager.
316 * @pre The AccessibilityManager has been initialized.
321 * @brief Sets whether an actor is a focus group that can limit the
322 * scope of focus movement to its child actors in the focus chain.
325 * @param actor The actor to be set as a focus group
326 * @param isFocusGroup Whether to set the actor to be a focus group or not
327 * @pre The AccessibilityManager has been initialized.
328 * @pre The Actor has been initialized.
330 void SetFocusGroup(Actor actor, bool isFocusGroup);
333 * @brief Checks whether the actor is set as a focus group or not.
336 * @param actor The actor to be checked
337 * @return Whether the actor is set as a focus group
338 * @pre The AccessibilityManager has been initialized.
339 * @pre The Actor has been initialized.
341 bool IsFocusGroup(Actor actor) const;
344 * @brief Sets whether the group mode is enabled or not.
346 * When the group mode is enabled, the focus movement will be limited to the child actors
347 * of the current focus group including the current focus group itself. The current focus
348 * group is the closest ancestor of the current focused actor that is set as a focus group.
350 * @param enabled Whether the group mode is enabled or not
351 * @pre The AccessibilityManager has been initialized.
353 void SetGroupMode(bool enabled);
356 * @brief Gets whether the group mode is enabled or not.
359 * @return Whether the group mode is enabled or not.
360 * @pre The AccessibilityManager has been initialized.
362 bool GetGroupMode() const;
365 * @brief Sets whether focus will be moved to the beginning of the
366 * focus chain when it reaches the end or vice versa.
368 * When both the wrap mode and the group mode are enabled, focus will be
369 * wrapped within the current focus group. Focus will not be wrapped in default.
371 * @param wrapped Whether the focus movement is wrapped around or not
372 * @pre The AccessibilityManager has been initialized.
374 void SetWrapMode(bool wrapped);
377 * @brief Gets whether the wrap mode is enabled or not.
380 * @return Whether the wrap mode is enabled or not.
381 * @pre The AccessibilityManager has been initialized.
383 bool GetWrapMode() const;
386 * @brief Sets the focus indicator actor.
388 * This will replace the default focus indicator actor in
389 * AccessibilityManager and will be added to the focused actor as a
393 * @param indicator The indicator actor to be added
394 * @pre The AccessibilityManager has been initialized.
395 * @pre The indicator actor has been initialized.
397 void SetFocusIndicatorActor(Actor indicator);
400 * @brief Gets the focus indicator actor.
403 * @return A handle to the focus indicator actor
404 * @pre The AccessibilityManager has been initialized.
406 Actor GetFocusIndicatorActor();
409 * @brief Returns the closest ancestor of the given actor that is a focus group.
412 * @param actor The actor to be checked for its focus group
413 * @return The focus group the given actor belongs to or an empty handle if the given actor doesn't belong to any focus group
415 Actor GetFocusGroup(Actor actor);
418 * @brief Returns the current position of the read action.
420 * @return The current event position
422 Vector2 GetReadPosition() const;
427 * @brief This signal is emitted when the current focused actor is changed.
429 * A callback of the following type may be connected:
431 * void YourCallbackName(Actor originalFocusedActor, Actor currentFocusedActor);
434 * @return The signal to connect to
435 * @pre The Object has been initialized.
437 FocusChangedSignalType& FocusChangedSignal();
440 * @brief This signal is emitted when there is no way to move focus further.
442 * A callback of the following type may be connected:
444 * void YourCallbackName(Actor currentFocusedActor, FocusOvershotDirection direction);
447 * @return The signal to connect to
448 * @pre The Object has been initialized.
450 FocusOvershotSignalType& FocusOvershotSignal();
453 * @brief This signal is emitted when the current focused actor is activated.
455 * A callback of the following type may be connected:
457 * void YourCallbackName(Actor activatedActor);
460 * @return The signal to connect to
461 * @pre The Object has been initialized.
463 FocusedActorActivatedSignalType& FocusedActorActivatedSignal();
465 public: // Accessibility action signals
468 * @brief This is emitted when accessibility(screen-reader) feature turned on or off.
470 * A callback of the following type may be connected:
472 * bool YourCallback( AccessibilityManager& manager );
475 * @return The signal to connect to
477 AccessibilityActionSignalType& StatusChangedSignal();
480 * @brief This is emitted when accessibility action is received to move focus to the next
481 * focusable actor (by one finger flick down).
483 * A callback of the following type may be connected:
485 * bool YourCallback( AccessibilityManager& manager );
488 * @return The signal to connect to
490 AccessibilityActionSignalType& ActionNextSignal();
493 * @brief This is emitted when accessibility action is received to move focus to the previous
494 * focusable actor (by one finger flick up).
496 * A callback of the following type may be connected:
498 * bool YourCallback( AccessibilityManager& manager );
501 * @return The signal to connect to
503 AccessibilityActionSignalType& ActionPreviousSignal();
506 * @brief This is emitted when accessibility action is received to activate the current focused
507 * actor (by one finger double tap).
509 * A callback of the following type may be connected:
511 * bool YourCallback( AccessibilityManager& manager );
514 * @return The signal to connect to
516 AccessibilityActionSignalType& ActionActivateSignal();
519 * @brief This is emitted when accessibility action is received to focus and read the actor
520 * (by one finger tap).
522 * A callback of the following type may be connected:
524 * bool YourCallback( AccessibilityManager& manager );
527 * @return The signal to connect to
529 AccessibilityActionSignalType& ActionReadSignal();
532 * @brief This is emitted when accessibility action is received to focus and read the actor
533 * (by one finger move).
535 * A callback of the following type may be connected:
537 * bool YourCallback( AccessibilityManager& manager );
540 * @return The signal to connect to
542 AccessibilityActionSignalType& ActionOverSignal();
545 * @brief This is emitted when accessibility action is received to move focus to the next
546 * focusable actor (by one finger flick right).
548 * A callback of the following type may be connected:
550 * bool YourCallback( AccessibilityManager& manager );
553 * @return The signal to connect to
555 AccessibilityActionSignalType& ActionReadNextSignal();
558 * @brief This is emitted when accessibility action is received to move focus to the previous
559 * focusable actor (by one finger flick left).
561 * A callback of the following type may be connected:
563 * bool YourCallback( AccessibilityManager& manager );
566 * @return The signal to connect to
568 AccessibilityActionSignalType& ActionReadPreviousSignal();
571 * @brief This is emitted when accessibility action is received to change the value when the
572 * current focused actor is a slider (by double finger down and move up and right).
574 * A callback of the following type may be connected:
576 * bool YourCallback( AccessibilityManager& manager );
579 * @return The signal to connect to
581 AccessibilityActionSignalType& ActionUpSignal();
584 * @brief This is emitted when accessibility action is received to change the value when the
585 * current focused actor is a slider (by double finger down and move down and left).
587 * A callback of the following type may be connected:
589 * bool YourCallback( AccessibilityManager& manager );
592 * @return The signal to connect to
594 AccessibilityActionSignalType& ActionDownSignal();
597 * @brief This is emitted when accessibility action is received to clear the focus from the
598 * current focused actor if any, so that no actor is focused in the focus chain.
600 * A callback of the following type may be connected:
602 * bool YourCallback( AccessibilityManager& manager );
605 * @return The signal to connect to
607 AccessibilityActionSignalType& ActionClearFocusSignal();
610 * @brief This is emitted when accessibility action is received to navigate back (by two
611 * fingers circle draw).
613 * A callback of the following type may be connected:
615 * bool YourCallback( AccessibilityManager& manager );
618 * @return The signal to connect to
620 AccessibilityActionSignalType& ActionBackSignal();
623 * @brief This is emitted when accessibility action is received to scroll up the list
624 * (by two finger swipe up).
626 * A callback of the following type may be connected:
628 * bool YourCallback( AccessibilityManager& manager );
631 * @return The signal to connect to
633 AccessibilityActionSignalType& ActionScrollUpSignal();
636 * @brief This is emitted when accessibility action is received to scroll down the list
637 * (by two finger swipe down).
639 * A callback of the following type may be connected:
641 * bool YourCallback( AccessibilityManager& manager );
644 * @return The signal to connect to
646 AccessibilityActionSignalType& ActionScrollDownSignal();
649 * @brief This is emitted when accessibility action is received to scroll left to the
650 * previous page (by two finger swipe left).
652 * A callback of the following type may be connected:
654 * bool YourCallback( AccessibilityManager& manager );
657 * @return The signal to connect to
659 AccessibilityActionSignalType& ActionPageLeftSignal();
662 * @brief This is emitted when accessibility action is received to scroll right to the
663 * next page (by two finger swipe right).
665 * A callback of the following type may be connected:
667 * bool YourCallback( AccessibilityManager& manager );
670 * @return The signal to connect to
672 AccessibilityActionSignalType& ActionPageRightSignal();
675 * @brief This is emitted when accessibility action is received to scroll up to the
676 * previous page (by one finger swipe left and right).
678 * A callback of the following type may be connected:
680 * bool YourCallback( AccessibilityManager& manager );
683 * @return The signal to connect to
685 AccessibilityActionSignalType& ActionPageUpSignal();
688 * @brief This is emitted when accessibility action is received to scroll down to the
689 * next page (by one finger swipe right and left).
691 * A callback of the following type may be connected:
693 * bool YourCallback( AccessibilityManager& manager );
696 * @return The signal to connect to
698 AccessibilityActionSignalType& ActionPageDownSignal();
701 * @brief This is emitted when accessibility action is received to move the focus to
702 * the first item on the screen (by one finger swipe up and down).
704 * A callback of the following type may be connected:
706 * bool YourCallback( AccessibilityManager& manager );
709 * @return The signal to connect to
711 AccessibilityActionSignalType& ActionMoveToFirstSignal();
714 * @brief This is emitted when accessibility action is received to move the focus to
715 * the last item on the screen (by one finger swipe down and up).
717 * A callback of the following type may be connected:
719 * bool YourCallback( AccessibilityManager& manager );
722 * @return The signal to connect to
724 AccessibilityActionSignalType& ActionMoveToLastSignal();
727 * @brief This is emitted when accessibility action is received to focus and read from the
728 * first item on the top continuously (by three fingers single tap).
730 * A callback of the following type may be connected:
732 * bool YourCallback( AccessibilityManager& manager );
735 * @return The signal to connect to.
737 AccessibilityActionSignalType& ActionReadFromTopSignal();
740 * @brief This is emitted when accessibility action is received to move the focus to and
741 * read from the next item continuously (by three fingers double tap).
743 * A callback of the following type may be connected:
745 * bool YourCallback( AccessibilityManager& manager );
748 * @return The signal to connect to
750 AccessibilityActionSignalType& ActionReadFromNextSignal();
753 * @brief This is emitted when accessibility action is received to zoom (by one finger
756 * A callback of the following type may be connected:
758 * bool YourCallback( AccessibilityManager& manager );
761 * @return The signal to connect to
763 AccessibilityActionSignalType& ActionZoomSignal();
766 * @brief This is emitted when accessibility action is received to read the information
767 * in the indicator (by two fingers triple tap).
769 * A callback of the following type may be connected:
771 * bool YourCallback( AccessibilityManager& manager );
774 * @return The signal to connect to
776 AccessibilityActionSignalType& ActionReadIndicatorInformationSignal();
779 * @brief This is emitted when accessibility action is received to pause/resume the
780 * current speech (by two fingers single tap).
782 * A callback of the following type may be connected:
784 * bool YourCallback( AccessibilityManager& manager );
787 * @return The signal to connect to
789 AccessibilityActionSignalType& ActionReadPauseResumeSignal();
792 * @brief This is emitted when accessibility action is received to start/stop the
793 * current action (by two fingers double tap).
795 * A callback of the following type may be connected:
797 * bool YourCallback( AccessibilityManager& manager );
800 * @return The signal to connect to
802 AccessibilityActionSignalType& ActionStartStopSignal();
805 * @brief This is emitted when accessibility action is received to handle scroll event (by two
808 * A callback of the following type may be connected:
810 * bool YourCallback( AccessibilityManager& manager, const TouchEvent& event );
813 * @return The signal to connect to
815 AccessibilityActionScrollSignalType& ActionScrollSignal();
819 explicit DALI_INTERNAL AccessibilityManager( Internal::AccessibilityManager *impl );
821 }; // class AccessibilityManager
826 } // namespace Toolkit
830 #endif // __DALI_TOOLKIT_ACCESSIBILITY_MANAGER_H__