1 #ifndef __DALI_TOOLKIT_ACCESSIBILITY_MANAGER_H__
2 #define __DALI_TOOLKIT_ACCESSIBILITY_MANAGER_H__
5 * Copyright (c) 2015 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>
23 #include <dali/public-api/actors/image-actor.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_IMPORT_API AccessibilityManager : public BaseHandle
66 * @brief Accessibility Action Signal.
68 * The connected signal callback should return true if handled.
71 typedef Signal< bool ( AccessibilityManager& ) > AccessibilityActionSignalType; ///< Generic signal type @SINCE_1_0.0
72 typedef Signal< bool ( AccessibilityManager&, const Dali::TouchEvent& )> AccessibilityActionScrollSignalType; ///< Scroll signal type @SINCE_1_0.0
75 * @brief Accessibility needs four information which will be read by screen-reader.
77 * Reading order : Label -> Trait -> Optional (Value and Hint)
80 enum AccessibilityAttribute
82 ACCESSIBILITY_LABEL = 0, ///< Simple text which contained in ui-control @SINCE_1_0.0
83 ACCESSIBILITY_TRAIT, ///< Description of ui-control trait @SINCE_1_0.0
84 ACCESSIBILITY_VALUE, ///< Current value of ui-control (Optional) @SINCE_1_0.0
85 ACCESSIBILITY_HINT, ///< Hint for action (Optional) @SINCE_1_0.0
86 ACCESSIBILITY_ATTRIBUTE_NUM ///< Number of attributes @SINCE_1_0.0
90 * @brief Overshoot direction.
93 enum FocusOvershotDirection
95 OVERSHOT_PREVIOUS = -1, ///< Try to move previous of the first actor @SINCE_1_0.0
96 OVERSHOT_NEXT = 1, ///< Try to move next of the last actor @SINCE_1_0.0
101 /// @brief Focus changed signal
103 typedef Signal< void ( Actor, Actor ) > FocusChangedSignalType;
105 /// @brief Focus overshooted signal
107 typedef Signal< void ( Actor, FocusOvershotDirection ) > FocusOvershotSignalType;
109 /// @brief Focused actor activated signal
111 typedef Signal< void ( Actor ) > FocusedActorActivatedSignalType;
114 * @brief Create a AccessibilityManager handle; this can be initialised with AccessibilityManager::New().
116 * Calling member functions with an uninitialised handle is not allowed.
119 AccessibilityManager();
124 * This is non-virtual since derived Handle types must not contain data or virtual methods.
127 ~AccessibilityManager();
130 * @brief Get the singleton of AccessibilityManager object.
133 * @return A handle to the AccessibilityManager control.
135 static AccessibilityManager Get();
138 * @brief Set the information of the specified actor's accessibility attribute.
141 * @param actor The actor the text to be set with
142 * @param type The attribute type the text to be set with
143 * @param text The text for the actor's accessibility information
144 * @pre The AccessibilityManager has been initialized.
145 * @pre The Actor has been initialized.
147 void SetAccessibilityAttribute(Actor actor, AccessibilityAttribute type, const std::string& text);
150 * @brief Get the text of the specified actor's accessibility attribute.
153 * @param actor The actor to be queried
154 * @param type The attribute type to be queried
155 * @return The text of the actor's accessibility information
156 * @pre The AccessibilityManager has been initialized.
157 * @pre The Actor has been initialized.
159 std::string GetAccessibilityAttribute(Actor actor, AccessibilityAttribute type) const;
162 * @brief Set the focus order of the actor.
164 * The focus order of each actor in the focus chain is unique. If
165 * there is another actor assigned with the same focus order
166 * already, the new actor will be inserted to the focus chain with
167 * that focus order, and the focus order of the original actor and
168 * all the actors followed in the focus chain will be increased
169 * accordingly. If the focus order assigned to the actor is 0, it
170 * means that actor's focus order is undefined (e.g. the actor has a
171 * description but with no focus order being set yet) and therefore
172 * that actor is not focusable.
175 * @param actor The actor the focus order to be set with
176 * @param order The focus order of the actor
177 * @pre The AccessibilityManager has been initialized.
178 * @pre The Actor has been initialized.
180 void SetFocusOrder(Actor actor, const unsigned int order);
183 * @brief Get the focus order of the actor.
185 * When the focus order is 0, it means the focus order of the actor
189 * @param actor The actor to be queried
190 * @return The focus order of the actor
191 * @pre The AccessibilityManager has been initialized.
192 * @pre The Actor has been initialized.
194 unsigned int GetFocusOrder(Actor actor) const;
197 * @brief Generates a new focus order number which can be used to
198 * assign to actors which need to be appended to the end of the
199 * current focus order chain.
201 * The new number will be an increment over the very last focus
202 * order number in the focus chain. If the focus chain is empty then
203 * the function returns 1, else the number returned will be FOLast +
204 * 1 where FOLast is the focus order of the very last control in the
208 * @return The focus order of the actor
209 * @pre The AccessibilityManager has been initialized.
211 unsigned int GenerateNewFocusOrder() const;
214 * @brief Get the actor that has the specified focus order.
216 * It will return an empty handle if no actor in the stage
217 * has the specified focus order.
220 * @param order The focus order of the actor
222 * @return The actor that has the specified focus order or an empty
223 * handle if no actor in the stage has the specified focus order.
224 * @pre The AccessibilityManager has been initialized.
226 Actor GetActorByFocusOrder(const unsigned int order);
229 * @brief Move the focus to the specified actor.
231 * Only one actor can be focused at the same time. The actor must
232 * have a defined focus order and must be focusable, visible and in
236 * @param actor The actor to be focused
237 * @return Whether the focus is successful or not
238 * @pre The AccessibilityManager has been initialized.
239 * @pre The Actor has been initialized.
241 bool SetCurrentFocusActor(Actor actor);
244 * @brief Get the current focused actor.
247 * @return A handle to the current focused actor or an empty handle if no actor is focused.
248 * @pre The AccessibilityManager has been initialized.
250 Actor GetCurrentFocusActor();
253 * @brief Get the focus group of current focused actor.
256 * @return A handle to the immediate parent of the current focused
257 * actor which is also a focus group, or an empty handle if no actor
259 * @pre The AccessibilityManager has been initialized.
262 Actor GetCurrentFocusGroup();
265 * @brief Get the focus order of currently focused actor.
267 * @return The focus order of the currently focused actor or 0 if no
269 * @pre The AccessibilityManager has been initialized.
272 unsigned int GetCurrentFocusOrder();
275 * @brief Move the focus to the next focusable actor in the focus
276 * chain (according to the focus traversal order).
278 * When the focus movement is wrapped around, the focus will be moved
279 * to the first focusable actor when it reaches the end of the focus chain.
282 * @return true if the moving was successful
283 * @pre The AccessibilityManager has been initialized.
285 bool MoveFocusForward();
288 * @brief Move the focus to the previous focusable actor in the
289 * focus chain (according to the focus traversal order).
291 * When the focus movement is wrapped around, the focus will be
292 * moved to the last focusable actor when it reaches the beginning
293 * of the focus chain.
296 * @return true if the moving was successful
297 * @pre The AccessibilityManager has been initialized.
299 bool MoveFocusBackward();
302 * @brief Clear the focus from the current focused actor if any, so
303 * that no actor is focused in the focus chain.
305 * It will emit focus changed signal without current focused actor.
307 * @pre The AccessibilityManager has been initialized.
312 * @brief Clear the every registered focusable actor from focus-manager.
314 * @pre The AccessibilityManager has been initialized.
319 * @brief Set whether an actor is a focus group that can limit the
320 * scope of focus movement to its child actors in the focus chain.
323 * @param actor The actor to be set as a focus group.
324 * @param isFocusGroup Whether to set the actor to be a focus group or not.
325 * @pre The AccessibilityManager has been initialized.
326 * @pre The Actor has been initialized.
328 void SetFocusGroup(Actor actor, bool isFocusGroup);
331 * @brief Check whether the actor is set as a focus group or not.
334 * @param actor The actor to be checked.
335 * @return Whether the actor is set as a focus group.
336 * @pre The AccessibilityManager has been initialized.
337 * @pre The Actor has been initialized.
339 bool IsFocusGroup(Actor actor) const;
342 * @brief Set whether the group mode is enabled or not.
344 * When the group mode is enabled, the focus movement will be limited to the child actors
345 * of the current focus group including the current focus group itself. The current focus
346 * group is the closest ancestor of the current focused actor that set as a focus group.
348 * @param enabled Whether the group mode is enabled or not
349 * @pre The AccessibilityManager has been initialized.
351 void SetGroupMode(bool enabled);
354 * @brief Get whether the group mode is enabled or not.
357 * @return Whether the group mode is enabled or not.
358 * @pre The AccessibilityManager has been initialized.
360 bool GetGroupMode() const;
363 * @brief Set whether focus will be moved to the beginning of the
364 * focus chain when it reaches the end or vice versa.
366 * When both the wrap mode and the group mode are enabled, focus will be
367 * wrapped within the current focus group. Focus will not be wrapped in default.
369 * @param wrapped Whether the focus movement is wrapped around or not
370 * @pre The AccessibilityManager has been initialized.
372 void SetWrapMode(bool wrapped);
375 * @brief Get whether the wrap mode is enabled or not.
378 * @return Whether the wrap mode is enabled or not.
379 * @pre The AccessibilityManager has been initialized.
381 bool GetWrapMode() const;
384 * @brief Set the focus indicator actor.
386 * This will replace the default focus indicator actor in
387 * AccessibilityManager and will be added to the focused actor as a
391 * @param indicator The indicator actor to be added
392 * @pre The AccessibilityManager has been initialized.
393 * @pre The indicator actor has been initialized.
395 void SetFocusIndicatorActor(Actor indicator);
398 * @brief Get the focus indicator actor.
401 * @return A handle to the focus indicator actor
402 * @pre The AccessibilityManager has been initialized.
404 Actor GetFocusIndicatorActor();
407 * @brief Returns the closest ancestor of the given actor that is a focus group.
410 * @param actor The actor to be checked for its focus group
411 * @return The focus group the given actor belongs to or an empty handle if the given actor doesn't belong to any focus group
413 Actor GetFocusGroup(Actor actor);
416 * @brief Returns the current position of the read action.
418 * @return The current event position.
420 Vector2 GetReadPosition() const;
425 * @brief This signal is emitted when the current focused actor is changed.
427 * A callback of the following type may be connected:
429 * void YourCallbackName(Actor originalFocusedActor, Actor currentFocusedActor);
432 * @return The signal to connect to.
433 * @pre The Object has been initialized.
435 FocusChangedSignalType& FocusChangedSignal();
438 * @brief This signal is emitted when there is no way to move focus further.
440 * A callback of the following type may be connected:
442 * void YourCallbackName(Actor currentFocusedActor, FocusOvershotDirection direction);
445 * @return The signal to connect to.
446 * @pre The Object has been initialized.
448 FocusOvershotSignalType& FocusOvershotSignal();
451 * @brief This signal is emitted when the current focused actor is activated.
453 * A callback of the following type may be connected:
455 * void YourCallbackName(Actor activatedActor);
458 * @return The signal to connect to.
459 * @pre The Object has been initialized.
461 FocusedActorActivatedSignalType& FocusedActorActivatedSignal();
463 public: // Accessibility action signals
466 * @brief This is emitted when accessibility(screen-reader) feature turned on or off.
468 * A callback of the following type may be connected:
470 * bool YourCallback( AccessibilityManager& manager );
473 * @return The signal to connect to.
475 AccessibilityActionSignalType& StatusChangedSignal();
478 * @brief This is emitted when accessibility action is received to move focus to the next
479 * focusable actor (by one finger flick down).
481 * A callback of the following type may be connected:
483 * bool YourCallback( AccessibilityManager& manager );
486 * @return The signal to connect to.
488 AccessibilityActionSignalType& ActionNextSignal();
491 * @brief This is emitted when accessibility action is received to move focus to the previous
492 * focusable actor (by one finger flick up).
494 * A callback of the following type may be connected:
496 * bool YourCallback( AccessibilityManager& manager );
499 * @return The signal to connect to.
501 AccessibilityActionSignalType& ActionPreviousSignal();
504 * @brief This is emitted when accessibility action is received to activate the current focused
505 * actor (by one finger double tap).
507 * A callback of the following type may be connected:
509 * bool YourCallback( AccessibilityManager& manager );
512 * @return The signal to connect to.
514 AccessibilityActionSignalType& ActionActivateSignal();
517 * @brief This is emitted when accessibility action is received to focus and read the actor
518 * (by one finger tap).
520 * A callback of the following type may be connected:
522 * bool YourCallback( AccessibilityManager& manager );
525 * @return The signal to connect to.
527 AccessibilityActionSignalType& ActionReadSignal();
530 * @brief This is emitted when accessibility action is received to focus and read the actor
531 * (by one finger move).
533 * A callback of the following type may be connected:
535 * bool YourCallback( AccessibilityManager& manager );
538 * @return The signal to connect to.
540 AccessibilityActionSignalType& ActionOverSignal();
543 * @brief This is emitted when accessibility action is received to move focus to the next
544 * focusable actor (by one finger flick right).
546 * A callback of the following type may be connected:
548 * bool YourCallback( AccessibilityManager& manager );
551 * @return The signal to connect to.
553 AccessibilityActionSignalType& ActionReadNextSignal();
556 * @brief This is emitted when accessibility action is received to move focus to the previous
557 * focusable actor (by one finger flick left).
559 * A callback of the following type may be connected:
561 * bool YourCallback( AccessibilityManager& manager );
564 * @return The signal to connect to.
566 AccessibilityActionSignalType& ActionReadPreviousSignal();
569 * @brief This is emitted when accessibility action is received to change the value when the
570 * current focused actor is a slider (by double finger down and move up and right).
572 * A callback of the following type may be connected:
574 * bool YourCallback( AccessibilityManager& manager );
577 * @return The signal to connect to.
579 AccessibilityActionSignalType& ActionUpSignal();
582 * @brief This is emitted when accessibility action is received to change the value when the
583 * current focused actor is a slider (by double finger down and move down and left).
585 * A callback of the following type may be connected:
587 * bool YourCallback( AccessibilityManager& manager );
590 * @return The signal to connect to.
592 AccessibilityActionSignalType& ActionDownSignal();
595 * @brief This is emitted when accessibility action is received to clear the focus from the
596 * current focused actor if any, so that no actor is focused in the focus chain.
598 * A callback of the following type may be connected:
600 * bool YourCallback( AccessibilityManager& manager );
603 * @return The signal to connect to.
605 AccessibilityActionSignalType& ActionClearFocusSignal();
608 * @brief This is emitted when accessibility action is received to navigate back (by two
609 * fingers circle draw).
611 * A callback of the following type may be connected:
613 * bool YourCallback( AccessibilityManager& manager );
616 * @return The signal to connect to.
618 AccessibilityActionSignalType& ActionBackSignal();
621 * @brief This is emitted when accessibility action is received to scroll up the list
622 * (by two finger swipe up).
624 * A callback of the following type may be connected:
626 * bool YourCallback( AccessibilityManager& manager );
629 * @return The signal to connect to.
631 AccessibilityActionSignalType& ActionScrollUpSignal();
634 * @brief This is emitted when accessibility action is received to scroll down the list
635 * (by two finger swipe down).
637 * A callback of the following type may be connected:
639 * bool YourCallback( AccessibilityManager& manager );
642 * @return The signal to connect to.
644 AccessibilityActionSignalType& ActionScrollDownSignal();
647 * @brief This is emitted when accessibility action is received to scroll left to the
648 * previous page (by two finger swipe left).
650 * A callback of the following type may be connected:
652 * bool YourCallback( AccessibilityManager& manager );
655 * @return The signal to connect to.
657 AccessibilityActionSignalType& ActionPageLeftSignal();
660 * @brief This is emitted when accessibility action is received to scroll right to the
661 * next page (by two finger swipe right).
663 * A callback of the following type may be connected:
665 * bool YourCallback( AccessibilityManager& manager );
668 * @return The signal to connect to.
670 AccessibilityActionSignalType& ActionPageRightSignal();
673 * @brief This is emitted when accessibility action is received to scroll up to the
674 * previous page (by one finger swipe left and right).
676 * A callback of the following type may be connected:
678 * bool YourCallback( AccessibilityManager& manager );
681 * @return The signal to connect to.
683 AccessibilityActionSignalType& ActionPageUpSignal();
686 * @brief This is emitted when accessibility action is received to scroll down to the
687 * next page (by one finger swipe right and left).
689 * A callback of the following type may be connected:
691 * bool YourCallback( AccessibilityManager& manager );
694 * @return The signal to connect to.
696 AccessibilityActionSignalType& ActionPageDownSignal();
699 * @brief This is emitted when accessibility action is received to move the focus to
700 * the first item on the screen (by one finger swipe up and down).
702 * A callback of the following type may be connected:
704 * bool YourCallback( AccessibilityManager& manager );
707 * @return The signal to connect to.
709 AccessibilityActionSignalType& ActionMoveToFirstSignal();
712 * @brief This is emitted when accessibility action is received to move the focus to
713 * the last item on the screen (by one finger swipe down and up).
715 * A callback of the following type may be connected:
717 * bool YourCallback( AccessibilityManager& manager );
720 * @return The signal to connect to.
722 AccessibilityActionSignalType& ActionMoveToLastSignal();
725 * @brief This is emitted when accessibility action is received to focus and read from the
726 * first item on the top continously (by three fingers single tap).
728 * A callback of the following type may be connected:
730 * bool YourCallback( AccessibilityManager& manager );
733 * @return The signal to connect to.
735 AccessibilityActionSignalType& ActionReadFromTopSignal();
738 * @brief This is emitted when accessibility action is received to move the focus to and
739 * read from the next item continously (by three fingers double tap).
741 * A callback of the following type may be connected:
743 * bool YourCallback( AccessibilityManager& manager );
746 * @return The signal to connect to.
748 AccessibilityActionSignalType& ActionReadFromNextSignal();
751 * @brief This is emitted when accessibility action is received to zoom (by one finger
754 * A callback of the following type may be connected:
756 * bool YourCallback( AccessibilityManager& manager );
759 * @return The signal to connect to.
761 AccessibilityActionSignalType& ActionZoomSignal();
764 * @brief This is emitted when accessibility action is received to read the information
765 * in the indicator (by two fingers triple tap).
767 * A callback of the following type may be connected:
769 * bool YourCallback( AccessibilityManager& manager );
772 * @return The signal to connect to.
774 AccessibilityActionSignalType& ActionReadIndicatorInformationSignal();
777 * @brief This is emitted when accessibility action is received to pause/resume the
778 * current speech (by two fingers single tap).
780 * A callback of the following type may be connected:
782 * bool YourCallback( AccessibilityManager& manager );
785 * @return The signal to connect to.
787 AccessibilityActionSignalType& ActionReadPauseResumeSignal();
790 * @brief This is emitted when accessibility action is received to start/stop the
791 * current action (by two fingers double tap).
793 * A callback of the following type may be connected:
795 * bool YourCallback( AccessibilityManager& manager );
798 * @return The signal to connect to.
800 AccessibilityActionSignalType& ActionStartStopSignal();
803 * @brief This is emitted when accessibility action is received to handle scroll event (by two
806 * A callback of the following type may be connected:
808 * bool YourCallback( AccessibilityManager& manager, const TouchEvent& event );
811 * @return The signal to connect to.
813 AccessibilityActionScrollSignalType& ActionScrollSignal();
817 explicit DALI_INTERNAL AccessibilityManager( Internal::AccessibilityManager *impl );
819 }; // class AccessibilityManager
824 } // namespace Toolkit
828 #endif // __DALI_TOOLKIT_ACCESSIBILITY_MANAGER_H__