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>
30 namespace Internal DALI_INTERNAL
32 class AccessibilityManager;
35 * @addtogroup dali_toolkit_managers
40 * @brief Manages registration of actors in an accessibility focus chain and changing the
41 * focused actor within that chain.
43 * This class provides the functionality of registering the focus order and description
44 * of actors and maintaining the focus chain.
46 * It provides functionality of setting the
47 * focus and moving the focus forward and backward. It also draws a highlight for the
48 * focused actor and emits a signal when the focus is changed.
51 * | %Signal Name | Method |
52 * |-----------------------|------------------------------------|
53 * | focusChanged | @ref FocusChangedSignal() |
54 * | focusOvershot | @ref FocusOvershotSignal() |
55 * | focusedActorActivated | @ref FocusedActorActivatedSignal() |
58 class DALI_IMPORT_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
100 /// @brief Focus changed signal
102 typedef Signal< void ( Actor, Actor ) > FocusChangedSignalType;
104 /// @brief Focus overshooted signal
106 typedef Signal< void ( Actor, FocusOvershotDirection ) > FocusOvershotSignalType;
108 /// @brief Focused actor activated signal
110 typedef Signal< void ( Actor ) > FocusedActorActivatedSignalType;
113 * @brief Creates an AccessibilityManager handle; this can be initialised with AccessibilityManager::New().
115 * Calling member functions with an uninitialized handle is not allowed.
118 AccessibilityManager();
123 * This is non-virtual since derived Handle types must not contain data or virtual methods.
126 ~AccessibilityManager();
129 * @brief Gets the singleton of AccessibilityManager object.
132 * @return A handle to the AccessibilityManager control
134 static AccessibilityManager Get();
137 * @brief Sets the information of the specified actor's accessibility attribute.
140 * @param actor The actor, the text to be set with
141 * @param type The attribute type the text to be set with
142 * @param text The text for the actor's accessibility information
143 * @pre The AccessibilityManager has been initialized.
144 * @pre The Actor has been initialized.
146 void SetAccessibilityAttribute(Actor actor, AccessibilityAttribute type, const std::string& text);
149 * @brief Gets the text of the specified actor's accessibility attribute.
152 * @param actor The actor to be queried
153 * @param type The attribute type to be queried
154 * @return The text of the actor's accessibility information
155 * @pre The AccessibilityManager has been initialized.
156 * @pre The Actor has been initialized.
158 std::string GetAccessibilityAttribute(Actor actor, AccessibilityAttribute type) const;
161 * @brief Sets the focus order of the actor.
163 * The focus order of each actor in the focus chain is unique.
164 * If there is another actor assigned with the same focus order
165 * already, the new actor will be inserted to the focus chain with
166 * that focus order, and the focus order of the original actor and
167 * all the actors followed in the focus chain will be increased
168 * accordingly. If the focus order assigned to the actor is 0, it
169 * means that actor's focus order is undefined (e.g. the actor has a
170 * description but with no focus order being set yet) and therefore
171 * that actor is not focusable.
174 * @param actor The actor the focus order to be set with
175 * @param order The focus order of the actor
176 * @pre The AccessibilityManager has been initialized.
177 * @pre The Actor has been initialized.
179 void SetFocusOrder(Actor actor, const unsigned int order);
182 * @brief Gets the focus order of the actor.
184 * When the focus order is 0, it means the focus order of the actor
188 * @param actor The actor to be queried
189 * @return The focus order of the actor
190 * @pre The AccessibilityManager has been initialized.
191 * @pre The Actor has been initialized.
193 unsigned int GetFocusOrder(Actor actor) const;
196 * @brief Generates a new focus order number which can be used to
197 * assign to actors which need to be appended to the end of the
198 * current focus order chain.
200 * The new number will be an increment over the very last focus
201 * order number in the focus chain. If the focus chain is empty then
202 * the function returns 1, else the number returned will be FOLast +
203 * 1 where FOLast is the focus order of the very last control in the
207 * @return The focus order of the actor
208 * @pre The AccessibilityManager has been initialized.
210 unsigned int GenerateNewFocusOrder() const;
213 * @brief Gets the actor that has the specified focus order.
215 * It will return an empty handle if no actor in the stage
216 * has the specified focus order.
219 * @param order The focus order of the actor
221 * @return The actor that has the specified focus order or an empty
222 * handle if no actor in the stage has the specified focus order
223 * @pre The AccessibilityManager has been initialized.
225 Actor GetActorByFocusOrder(const unsigned int order);
228 * @brief Moves the focus to the specified actor.
230 * Only one actor can be focused at the same time. The actor must
231 * have a defined focus order and must be focusable, visible and in
235 * @param actor The actor to be focused
236 * @return Whether the focus is successful or not
237 * @pre The AccessibilityManager has been initialized.
238 * @pre The Actor has been initialized.
240 bool SetCurrentFocusActor(Actor actor);
243 * @brief Gets the current focused actor.
246 * @return A handle to the current focused actor or an empty handle if no actor is focused
247 * @pre The AccessibilityManager has been initialized.
249 Actor GetCurrentFocusActor();
252 * @brief Gets the focus group of current focused actor.
255 * @return A handle to the immediate parent of the current focused
256 * actor which is also a focus group, or an empty handle if no actor
258 * @pre The AccessibilityManager has been initialized.
261 Actor GetCurrentFocusGroup();
264 * @brief Gets the focus order of currently focused actor.
266 * @return The focus order of the currently focused actor or 0 if no
268 * @pre The AccessibilityManager has been initialized.
271 unsigned int GetCurrentFocusOrder();
274 * @brief Moves the focus to the next focusable actor in the focus
275 * chain (according to the focus traversal order).
277 * When the focus movement is wrapped around, the focus will be moved
278 * to the first focusable actor when it reaches the end of the focus chain.
281 * @return true if the moving was successful
282 * @pre The AccessibilityManager has been initialized.
284 bool MoveFocusForward();
287 * @brief Moves the focus to the previous focusable actor in the
288 * focus chain (according to the focus traversal order).
290 * When the focus movement is wrapped around, the focus will be
291 * moved to the last focusable actor when it reaches the beginning
292 * of the focus chain.
295 * @return true if the moving was successful
296 * @pre The AccessibilityManager has been initialized.
298 bool MoveFocusBackward();
301 * @brief Clears the focus from the current focused actor if any, so
302 * that no actor is focused in the focus chain.
304 * It will emit focus changed signal without current focused actor.
306 * @pre The AccessibilityManager has been initialized.
311 * @brief Clears every registered focusable actor from focus-manager.
313 * @pre The AccessibilityManager has been initialized.
318 * @brief Sets whether an actor is a focus group that can limit the
319 * scope of focus movement to its child actors in the focus chain.
322 * @param actor The actor to be set as a focus group
323 * @param isFocusGroup Whether to set the actor to be a focus group or not
324 * @pre The AccessibilityManager has been initialized.
325 * @pre The Actor has been initialized.
327 void SetFocusGroup(Actor actor, bool isFocusGroup);
330 * @brief Checks whether the actor is set as a focus group or not.
333 * @param actor The actor to be checked
334 * @return Whether the actor is set as a focus group
335 * @pre The AccessibilityManager has been initialized.
336 * @pre The Actor has been initialized.
338 bool IsFocusGroup(Actor actor) const;
341 * @brief Sets whether the group mode is enabled or not.
343 * When the group mode is enabled, the focus movement will be limited to the child actors
344 * of the current focus group including the current focus group itself. The current focus
345 * group is the closest ancestor of the current focused actor that is set as a focus group.
347 * @param enabled Whether the group mode is enabled or not
348 * @pre The AccessibilityManager has been initialized.
350 void SetGroupMode(bool enabled);
353 * @brief Gets whether the group mode is enabled or not.
356 * @return Whether the group mode is enabled or not.
357 * @pre The AccessibilityManager has been initialized.
359 bool GetGroupMode() const;
362 * @brief Sets whether focus will be moved to the beginning of the
363 * focus chain when it reaches the end or vice versa.
365 * When both the wrap mode and the group mode are enabled, focus will be
366 * wrapped within the current focus group. Focus will not be wrapped in default.
368 * @param wrapped Whether the focus movement is wrapped around or not
369 * @pre The AccessibilityManager has been initialized.
371 void SetWrapMode(bool wrapped);
374 * @brief Gets whether the wrap mode is enabled or not.
377 * @return Whether the wrap mode is enabled or not.
378 * @pre The AccessibilityManager has been initialized.
380 bool GetWrapMode() const;
383 * @brief Sets the focus indicator actor.
385 * This will replace the default focus indicator actor in
386 * AccessibilityManager and will be added to the focused actor as a
390 * @param indicator The indicator actor to be added
391 * @pre The AccessibilityManager has been initialized.
392 * @pre The indicator actor has been initialized.
394 void SetFocusIndicatorActor(Actor indicator);
397 * @brief Gets the focus indicator actor.
400 * @return A handle to the focus indicator actor
401 * @pre The AccessibilityManager has been initialized.
403 Actor GetFocusIndicatorActor();
406 * @brief Returns the closest ancestor of the given actor that is a focus group.
409 * @param actor The actor to be checked for its focus group
410 * @return The focus group the given actor belongs to or an empty handle if the given actor doesn't belong to any focus group
412 Actor GetFocusGroup(Actor actor);
415 * @brief Returns the current position of the read action.
417 * @return The current event position
419 Vector2 GetReadPosition() const;
424 * @brief This signal is emitted when the current focused actor is changed.
426 * A callback of the following type may be connected:
428 * void YourCallbackName(Actor originalFocusedActor, Actor currentFocusedActor);
431 * @return The signal to connect to
432 * @pre The Object has been initialized.
434 FocusChangedSignalType& FocusChangedSignal();
437 * @brief This signal is emitted when there is no way to move focus further.
439 * A callback of the following type may be connected:
441 * void YourCallbackName(Actor currentFocusedActor, FocusOvershotDirection direction);
444 * @return The signal to connect to
445 * @pre The Object has been initialized.
447 FocusOvershotSignalType& FocusOvershotSignal();
450 * @brief This signal is emitted when the current focused actor is activated.
452 * A callback of the following type may be connected:
454 * void YourCallbackName(Actor activatedActor);
457 * @return The signal to connect to
458 * @pre The Object has been initialized.
460 FocusedActorActivatedSignalType& FocusedActorActivatedSignal();
462 public: // Accessibility action signals
465 * @brief This is emitted when accessibility(screen-reader) feature turned on or off.
467 * A callback of the following type may be connected:
469 * bool YourCallback( AccessibilityManager& manager );
472 * @return The signal to connect to
474 AccessibilityActionSignalType& StatusChangedSignal();
477 * @brief This is emitted when accessibility action is received to move focus to the next
478 * focusable actor (by one finger flick down).
480 * A callback of the following type may be connected:
482 * bool YourCallback( AccessibilityManager& manager );
485 * @return The signal to connect to
487 AccessibilityActionSignalType& ActionNextSignal();
490 * @brief This is emitted when accessibility action is received to move focus to the previous
491 * focusable actor (by one finger flick up).
493 * A callback of the following type may be connected:
495 * bool YourCallback( AccessibilityManager& manager );
498 * @return The signal to connect to
500 AccessibilityActionSignalType& ActionPreviousSignal();
503 * @brief This is emitted when accessibility action is received to activate the current focused
504 * actor (by one finger double tap).
506 * A callback of the following type may be connected:
508 * bool YourCallback( AccessibilityManager& manager );
511 * @return The signal to connect to
513 AccessibilityActionSignalType& ActionActivateSignal();
516 * @brief This is emitted when accessibility action is received to focus and read the actor
517 * (by one finger tap).
519 * A callback of the following type may be connected:
521 * bool YourCallback( AccessibilityManager& manager );
524 * @return The signal to connect to
526 AccessibilityActionSignalType& ActionReadSignal();
529 * @brief This is emitted when accessibility action is received to focus and read the actor
530 * (by one finger move).
532 * A callback of the following type may be connected:
534 * bool YourCallback( AccessibilityManager& manager );
537 * @return The signal to connect to
539 AccessibilityActionSignalType& ActionOverSignal();
542 * @brief This is emitted when accessibility action is received to move focus to the next
543 * focusable actor (by one finger flick right).
545 * A callback of the following type may be connected:
547 * bool YourCallback( AccessibilityManager& manager );
550 * @return The signal to connect to
552 AccessibilityActionSignalType& ActionReadNextSignal();
555 * @brief This is emitted when accessibility action is received to move focus to the previous
556 * focusable actor (by one finger flick left).
558 * A callback of the following type may be connected:
560 * bool YourCallback( AccessibilityManager& manager );
563 * @return The signal to connect to
565 AccessibilityActionSignalType& ActionReadPreviousSignal();
568 * @brief This is emitted when accessibility action is received to change the value when the
569 * current focused actor is a slider (by double finger down and move up and right).
571 * A callback of the following type may be connected:
573 * bool YourCallback( AccessibilityManager& manager );
576 * @return The signal to connect to
578 AccessibilityActionSignalType& ActionUpSignal();
581 * @brief This is emitted when accessibility action is received to change the value when the
582 * current focused actor is a slider (by double finger down and move down and left).
584 * A callback of the following type may be connected:
586 * bool YourCallback( AccessibilityManager& manager );
589 * @return The signal to connect to
591 AccessibilityActionSignalType& ActionDownSignal();
594 * @brief This is emitted when accessibility action is received to clear the focus from the
595 * current focused actor if any, so that no actor is focused in the focus chain.
597 * A callback of the following type may be connected:
599 * bool YourCallback( AccessibilityManager& manager );
602 * @return The signal to connect to
604 AccessibilityActionSignalType& ActionClearFocusSignal();
607 * @brief This is emitted when accessibility action is received to navigate back (by two
608 * fingers circle draw).
610 * A callback of the following type may be connected:
612 * bool YourCallback( AccessibilityManager& manager );
615 * @return The signal to connect to
617 AccessibilityActionSignalType& ActionBackSignal();
620 * @brief This is emitted when accessibility action is received to scroll up the list
621 * (by two finger swipe up).
623 * A callback of the following type may be connected:
625 * bool YourCallback( AccessibilityManager& manager );
628 * @return The signal to connect to
630 AccessibilityActionSignalType& ActionScrollUpSignal();
633 * @brief This is emitted when accessibility action is received to scroll down the list
634 * (by two finger swipe down).
636 * A callback of the following type may be connected:
638 * bool YourCallback( AccessibilityManager& manager );
641 * @return The signal to connect to
643 AccessibilityActionSignalType& ActionScrollDownSignal();
646 * @brief This is emitted when accessibility action is received to scroll left to the
647 * previous page (by two finger swipe left).
649 * A callback of the following type may be connected:
651 * bool YourCallback( AccessibilityManager& manager );
654 * @return The signal to connect to
656 AccessibilityActionSignalType& ActionPageLeftSignal();
659 * @brief This is emitted when accessibility action is received to scroll right to the
660 * next page (by two finger swipe right).
662 * A callback of the following type may be connected:
664 * bool YourCallback( AccessibilityManager& manager );
667 * @return The signal to connect to
669 AccessibilityActionSignalType& ActionPageRightSignal();
672 * @brief This is emitted when accessibility action is received to scroll up to the
673 * previous page (by one finger swipe left and right).
675 * A callback of the following type may be connected:
677 * bool YourCallback( AccessibilityManager& manager );
680 * @return The signal to connect to
682 AccessibilityActionSignalType& ActionPageUpSignal();
685 * @brief This is emitted when accessibility action is received to scroll down to the
686 * next page (by one finger swipe right and left).
688 * A callback of the following type may be connected:
690 * bool YourCallback( AccessibilityManager& manager );
693 * @return The signal to connect to
695 AccessibilityActionSignalType& ActionPageDownSignal();
698 * @brief This is emitted when accessibility action is received to move the focus to
699 * the first item on the screen (by one finger swipe up and down).
701 * A callback of the following type may be connected:
703 * bool YourCallback( AccessibilityManager& manager );
706 * @return The signal to connect to
708 AccessibilityActionSignalType& ActionMoveToFirstSignal();
711 * @brief This is emitted when accessibility action is received to move the focus to
712 * the last item on the screen (by one finger swipe down and up).
714 * A callback of the following type may be connected:
716 * bool YourCallback( AccessibilityManager& manager );
719 * @return The signal to connect to
721 AccessibilityActionSignalType& ActionMoveToLastSignal();
724 * @brief This is emitted when accessibility action is received to focus and read from the
725 * first item on the top continously (by three fingers single tap).
727 * A callback of the following type may be connected:
729 * bool YourCallback( AccessibilityManager& manager );
732 * @return The signal to connect to.
734 AccessibilityActionSignalType& ActionReadFromTopSignal();
737 * @brief This is emitted when accessibility action is received to move the focus to and
738 * read from the next item continously (by three fingers double tap).
740 * A callback of the following type may be connected:
742 * bool YourCallback( AccessibilityManager& manager );
745 * @return The signal to connect to
747 AccessibilityActionSignalType& ActionReadFromNextSignal();
750 * @brief This is emitted when accessibility action is received to zoom (by one finger
753 * A callback of the following type may be connected:
755 * bool YourCallback( AccessibilityManager& manager );
758 * @return The signal to connect to
760 AccessibilityActionSignalType& ActionZoomSignal();
763 * @brief This is emitted when accessibility action is received to read the information
764 * in the indicator (by two fingers triple tap).
766 * A callback of the following type may be connected:
768 * bool YourCallback( AccessibilityManager& manager );
771 * @return The signal to connect to
773 AccessibilityActionSignalType& ActionReadIndicatorInformationSignal();
776 * @brief This is emitted when accessibility action is received to pause/resume the
777 * current speech (by two fingers single tap).
779 * A callback of the following type may be connected:
781 * bool YourCallback( AccessibilityManager& manager );
784 * @return The signal to connect to
786 AccessibilityActionSignalType& ActionReadPauseResumeSignal();
789 * @brief This is emitted when accessibility action is received to start/stop the
790 * current action (by two fingers double tap).
792 * A callback of the following type may be connected:
794 * bool YourCallback( AccessibilityManager& manager );
797 * @return The signal to connect to
799 AccessibilityActionSignalType& ActionStartStopSignal();
802 * @brief This is emitted when accessibility action is received to handle scroll event (by two
805 * A callback of the following type may be connected:
807 * bool YourCallback( AccessibilityManager& manager, const TouchEvent& event );
810 * @return The signal to connect to
812 AccessibilityActionScrollSignalType& ActionScrollSignal();
816 explicit DALI_INTERNAL AccessibilityManager( Internal::AccessibilityManager *impl );
818 }; // class AccessibilityManager
823 } // namespace Toolkit
827 #endif // __DALI_TOOLKIT_ACCESSIBILITY_MANAGER_H__