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;
37 * @brief Manages registration of actors in a accessibility focus chain and changing the
38 * focused actor within that chain.
40 * This class provides the functionality of registering the focus order and description
41 * of actors and maintaining the focus chain.
43 * It provides functionality of setting the
44 * focus and moving the focus forward and backward. It also draws a highlight for the
45 * focused actor and emits a signal when the focus is changed.
48 * | %Signal Name | Method |
49 * |-------------------------|------------------------------------|
50 * | focus-changed | @ref FocusChangedSignal() |
51 * | focus-overshot | @ref FocusOvershotSignal() |
52 * | focused-actor-activated | @ref FocusedActorActivatedSignal() |
54 class DALI_IMPORT_API AccessibilityManager : public BaseHandle
61 * @brief Accessibility Action Signal.
63 * The connected signal callback should return true if handled.
65 typedef Signal< bool ( AccessibilityManager& ) > AccessibilityActionSignalType; ///< Generic signal type
66 typedef Signal< bool ( AccessibilityManager&, const Dali::TouchEvent& )> AccessibilityActionScrollSignalType; ///< Scroll signal type
69 * @brief Accessibility needs four information which will be read by screen-reader.
71 * Reading order : Label -> Trait -> Optional (Value and Hint)
73 enum AccessibilityAttribute
75 ACCESSIBILITY_LABEL = 0, ///< Simple text which contained in ui-control
76 ACCESSIBILITY_TRAIT, ///< Description of ui-control trait
77 ACCESSIBILITY_VALUE, ///< Current value of ui-control (Optional)
78 ACCESSIBILITY_HINT, ///< Hint for action (Optional)
79 ACCESSIBILITY_ATTRIBUTE_NUM ///< Number of attributes
83 * @brief Overshoot direction.
85 enum FocusOvershotDirection
87 OVERSHOT_PREVIOUS = -1, ///< Try to move previous of the first actor
88 OVERSHOT_NEXT = 1, ///< Try to move next of the last actor
93 /// @brief Focus changed signal
94 typedef Signal< void ( Actor, Actor ) > FocusChangedSignalType;
96 /// @brief Focus overshooted signal
97 typedef Signal< void ( Actor, FocusOvershotDirection ) > FocusOvershotSignalType;
99 /// @brief Focused actor activated signal
100 typedef Signal< void ( Actor ) > FocusedActorActivatedSignalType;
103 * @brief Create a AccessibilityManager handle; this can be initialised with AccessibilityManager::New().
105 * Calling member functions with an uninitialised handle is not allowed.
107 AccessibilityManager();
112 * This is non-virtual since derived Handle types must not contain data or virtual methods.
114 ~AccessibilityManager();
117 * @brief Get the singleton of AccessibilityManager object.
119 * @return A handle to the AccessibilityManager control.
121 static AccessibilityManager Get();
124 * @brief Set the information of the specified actor's accessibility attribute.
126 * @pre The AccessibilityManager has been initialized.
127 * @pre The Actor has been initialized.
128 * @param actor The actor the text to be set with
129 * @param type The attribute type the text to be set with
130 * @param text The text for the actor's accessibility information
132 void SetAccessibilityAttribute(Actor actor, AccessibilityAttribute type, const std::string& text);
135 * @brief Get the text of the specified actor's accessibility attribute.
137 * @pre The AccessibilityManager has been initialized.
138 * @pre The Actor has been initialized.
139 * @param actor The actor to be queried
140 * @param type The attribute type to be queried
141 * @return The text of the actor's accessibility information
143 std::string GetAccessibilityAttribute(Actor actor, AccessibilityAttribute type) const;
146 * @brief Set the focus order of the actor.
148 * The focus order of each actor in the focus chain is unique. If
149 * there is another actor assigned with the same focus order
150 * already, the new actor will be inserted to the focus chain with
151 * that focus order, and the focus order of the original actor and
152 * all the actors followed in the focus chain will be increased
153 * accordingly. If the focus order assigned to the actor is 0, it
154 * means that actor's focus order is undefined (e.g. the actor has a
155 * description but with no focus order being set yet) and therefore
156 * that actor is not focusable.
158 * @pre The AccessibilityManager has been initialized.
159 * @pre The Actor has been initialized.
160 * @param actor The actor the focus order to be set with
161 * @param order The focus order of the actor
163 void SetFocusOrder(Actor actor, const unsigned int order);
166 * @brief Get the focus order of the actor.
168 * When the focus order is 0, it means the focus order of the actor
171 * @pre The AccessibilityManager has been initialized.
172 * @pre The Actor has been initialized.
173 * @param actor The actor to be queried
174 * @return The focus order of the actor
176 unsigned int GetFocusOrder(Actor actor) const;
179 * @brief Generates a new focus order number which can be used to
180 * assign to actors which need to be appended to the end of the
181 * current focus order chain.
183 * The new number will be an increment over the very last focus
184 * order number in the focus chain. If the focus chain is empty then
185 * the function returns 1, else the number returned will be FOLast +
186 * 1 where FOLast is the focus order of the very last control in the
189 * @pre The AccessibilityManager has been initialized.
190 * @return The focus order of the actor
192 unsigned int GenerateNewFocusOrder() const;
195 * @brief Get the actor that has the specified focus order.
197 * It will return an empty handle if the actor is not in the stage
198 * or has a focus order of 0.
200 * @pre The AccessibilityManager has been initialized.
201 * @param order The focus order of the actor
203 * @return The actor that has the specified focus order or an empty
204 * handle if no actor in the stage has the specified focus order.
206 Actor GetActorByFocusOrder(const unsigned int order);
209 * @brief Move the focus to the specified actor.
211 * Only one actor can be focused at the same time. The actor must
212 * have a defined focus order and must be focusable, visible and in
215 * @pre The AccessibilityManager has been initialized.
216 * @pre The Actor has been initialized.
217 * @param actor The actor to be focused
218 * @return Whether the focus is successful or not
220 bool SetCurrentFocusActor(Actor actor);
223 * @brief Get the current focused actor.
225 * @pre The AccessibilityManager has been initialized.
226 * @return A handle to the current focused actor or an empty handle if no actor is focused.
228 Actor GetCurrentFocusActor();
231 * @brief Get the focus group of current focused actor.
233 * @pre The AccessibilityManager has been initialized.
235 * @return A handle to the immediate parent of the current focused
236 * actor which is also a focus group, or an empty handle if no actor
239 Actor GetCurrentFocusGroup();
242 * @brief Get the focus order of currently focused actor.
243 * @pre The AccessibilityManager has been initialized.
245 * @return The focus order of the currently focused actor or 0 if no
248 unsigned int GetCurrentFocusOrder();
251 * @brief Move the focus to the next focusable actor in the focus
252 * chain (according to the focus traversal order).
254 * When the focus movement is wrapped around, the focus will be moved
255 * to the first focusable actor when it reaches the end of the focus chain.
257 * @pre The AccessibilityManager has been initialized.
258 * @return true if the moving was successful
260 bool MoveFocusForward();
263 * @brief Move the focus to the previous focusable actor in the
264 * focus chain (according to the focus traversal order).
266 * When the focus movement is wrapped around, the focus will be
267 * moved to the last focusable actor when it reaches the beginning
268 * of the focus chain.
270 * @pre The AccessibilityManager has been initialized.
271 * @return true if the moving was successful
273 bool MoveFocusBackward();
276 * @brief Clear the focus from the current focused actor if any, so
277 * that no actor is focused in the focus chain.
279 * It will emit focus changed signal without current focused actor
280 * @pre The AccessibilityManager has been initialized.
285 * @brief Clear the every registered focusable actor from focus-manager.
286 * @pre The AccessibilityManager has been initialized.
291 * @brief Set whether an actor is a focus group that can limit the
292 * scope of focus movement to its child actors in the focus chain.
294 * @pre The AccessibilityManager has been initialized.
295 * @pre The Actor has been initialized.
296 * @param actor The actor to be set as a focus group.
297 * @param isFocusGroup Whether to set the actor to be a focus group or not.
299 void SetFocusGroup(Actor actor, bool isFocusGroup);
302 * @brief Check whether the actor is set as a focus group or not.
304 * @pre The AccessibilityManager has been initialized.
305 * @pre The Actor has been initialized.
306 * @param actor The actor to be checked.
307 * @return Whether the actor is set as a focus group.
309 bool IsFocusGroup(Actor actor) const;
312 * @brief Set whether the group mode is enabled or not.
314 * When the group mode is enabled, the focus movement will be limited to the child actors
315 * of the current focus group including the current focus group itself. The current focus
316 * group is the closest ancestor of the current focused actor that set as a focus group.
317 * @pre The AccessibilityManager has been initialized.
318 * @param enabled Whether the group mode is enabled or not
320 void SetGroupMode(bool enabled);
323 * @brief Get whether the group mode is enabled or not.
325 * @pre The AccessibilityManager has been initialized.
326 * @return Whether the group mode is enabled or not.
328 bool GetGroupMode() const;
331 * @brief Set whether focus will be moved to the beginning of the
332 * focus chain when it reaches the end or vice versa.
334 * When both the wrap mode and the group mode are enabled, focus will be
335 * wrapped within the current focus group. Focus will not be wrapped in default.
336 * @pre The AccessibilityManager has been initialized.
337 * @param wrapped Whether the focus movement is wrapped around or not
339 void SetWrapMode(bool wrapped);
342 * @brief Get whether the wrap mode is enabled or not.
344 * @pre The AccessibilityManager has been initialized.
345 * @return Whether the wrap mode is enabled or not.
347 bool GetWrapMode() const;
350 * @brief Set the focus indicator actor.
352 * This will replace the default focus indicator actor in
353 * AccessibilityManager and will be added to the focused actor as a
356 * @pre The AccessibilityManager has been initialized.
357 * @pre The indicator actor has been initialized.
358 * @param indicator The indicator actor to be added
360 void SetFocusIndicatorActor(Actor indicator);
363 * @brief Get the focus indicator actor.
365 * @pre The AccessibilityManager has been initialized.
366 * @return A handle to the focus indicator actor
368 Actor GetFocusIndicatorActor();
371 * @brief Returns the closest ancestor of the given actor that is a focus group.
373 * @param actor The actor to be checked for its focus group
374 * @return The focus group the given actor belongs to or an empty handle if the given actor doesn't belong to any focus group
376 Actor GetFocusGroup(Actor actor);
379 * @brief Returns the current position of the read action.
380 * @return The current event position.
382 Vector2 GetReadPosition() const;
387 * @brief This signal is emitted when the current focused actor is changed.
389 * A callback of the following type may be connected:
391 * void YourCallbackName(Actor originalFocusedActor, Actor currentFocusedActor);
393 * @pre The Object has been initialized.
394 * @return The signal to connect to.
396 FocusChangedSignalType& FocusChangedSignal();
399 * @brief This signal is emitted when there is no way to move focus further.
401 * A callback of the following type may be connected:
403 * void YourCallbackName(Actor currentFocusedActor, FocusOvershotDirection direction);
405 * @pre The Object has been initialized.
406 * @return The signal to connect to.
408 FocusOvershotSignalType& FocusOvershotSignal();
411 * @brief This signal is emitted when the current focused actor is activated.
413 * A callback of the following type may be connected:
415 * void YourCallbackName(Actor activatedActor);
417 * @pre The Object has been initialized.
418 * @return The signal to connect to.
420 FocusedActorActivatedSignalType& FocusedActorActivatedSignal();
422 public: // Accessibility action signals.
425 * @brief This is emitted when accessibility(screen-reader) feature turned on or off.
427 * A callback of the following type may be connected:
429 * bool YourCallback( AccessibilityManager& manager );
431 * @return The signal to connect to.
433 AccessibilityActionSignalType& StatusChangedSignal();
436 * @brief This is emitted when accessibility action is received to move focus to the next
437 * focusable actor (by one finger flick down).
439 * A callback of the following type may be connected:
441 * bool YourCallback( AccessibilityManager& manager );
443 * @return The signal to connect to.
445 AccessibilityActionSignalType& ActionNextSignal();
448 * @brief This is emitted when accessibility action is received to move focus to the previous
449 * focusable actor (by one finger flick up).
451 * A callback of the following type may be connected:
453 * bool YourCallback( AccessibilityManager& manager );
455 * @return The signal to connect to.
457 AccessibilityActionSignalType& ActionPreviousSignal();
460 * @brief This is emitted when accessibility action is received to activate the current focused
461 * actor (by one finger double tap).
463 * A callback of the following type may be connected:
465 * bool YourCallback( AccessibilityManager& manager );
467 * @return The signal to connect to.
469 AccessibilityActionSignalType& ActionActivateSignal();
472 * @brief This is emitted when accessibility action is received to focus and read the actor
473 * (by one finger tap).
475 * A callback of the following type may be connected:
477 * bool YourCallback( AccessibilityManager& manager );
479 * @return The signal to connect to.
481 AccessibilityActionSignalType& ActionReadSignal();
484 * @brief This is emitted when accessibility action is received to focus and read the actor
485 * (by one finger move).
487 * A callback of the following type may be connected:
489 * bool YourCallback( AccessibilityManager& manager );
491 * @return The signal to connect to.
493 AccessibilityActionSignalType& ActionOverSignal();
496 * @brief This is emitted when accessibility action is received to move focus to the next
497 * focusable actor (by one finger flick right).
499 * A callback of the following type may be connected:
501 * bool YourCallback( AccessibilityManager& manager );
503 * @return The signal to connect to.
505 AccessibilityActionSignalType& ActionReadNextSignal();
508 * @brief This is emitted when accessibility action is received to move focus to the previous
509 * focusable actor (by one finger flick left).
511 * A callback of the following type may be connected:
513 * bool YourCallback( AccessibilityManager& manager );
515 * @return The signal to connect to.
517 AccessibilityActionSignalType& ActionReadPreviousSignal();
520 * @brief This is emitted when accessibility action is received to change the value when the
521 * current focused actor is a slider (by double finger down and move up and right).
523 * A callback of the following type may be connected:
525 * bool YourCallback( AccessibilityManager& manager );
527 * @return The signal to connect to.
529 AccessibilityActionSignalType& ActionUpSignal();
532 * @brief This is emitted when accessibility action is received to change the value when the
533 * current focused actor is a slider (by double finger down and move down and left).
535 * A callback of the following type may be connected:
537 * bool YourCallback( AccessibilityManager& manager );
539 * @return The signal to connect to.
541 AccessibilityActionSignalType& ActionDownSignal();
544 * @brief This is emitted when accessibility action is received to clear the focus from the
545 * current focused actor if any, so that no actor is focused in the focus chain.
547 * A callback of the following type may be connected:
549 * bool YourCallback( AccessibilityManager& manager );
551 * @return The signal to connect to.
553 AccessibilityActionSignalType& ActionClearFocusSignal();
556 * @brief This is emitted when accessibility action is received to navigate back (by two
557 * fingers circle draw).
559 * A callback of the following type may be connected:
561 * bool YourCallback( AccessibilityManager& manager );
563 * @return The signal to connect to.
565 AccessibilityActionSignalType& ActionBackSignal();
568 * @brief This is emitted when accessibility action is received to scroll up the list
569 * (by two finger swipe up).
571 * A callback of the following type may be connected:
573 * bool YourCallback( AccessibilityManager& manager );
575 * @return The signal to connect to.
577 AccessibilityActionSignalType& ActionScrollUpSignal();
580 * @brief This is emitted when accessibility action is received to scroll down the list
581 * (by two finger swipe down).
583 * A callback of the following type may be connected:
585 * bool YourCallback( AccessibilityManager& manager );
587 * @return The signal to connect to.
589 AccessibilityActionSignalType& ActionScrollDownSignal();
592 * @brief This is emitted when accessibility action is received to scroll left to the
593 * previous page (by two finger swipe left)
595 * A callback of the following type may be connected:
597 * bool YourCallback( AccessibilityManager& manager );
599 * @return The signal to connect to.
601 AccessibilityActionSignalType& ActionPageLeftSignal();
604 * @brief This is emitted when accessibility action is received to scroll right to the
605 * next page (by two finger swipe right)
607 * A callback of the following type may be connected:
609 * bool YourCallback( AccessibilityManager& manager );
611 * @return The signal to connect to.
613 AccessibilityActionSignalType& ActionPageRightSignal();
616 * @brief This is emitted when accessibility action is received to scroll up to the
617 * previous page (by one finger swipe left and right)
619 * A callback of the following type may be connected:
621 * bool YourCallback( AccessibilityManager& manager );
623 * @return The signal to connect to.
625 AccessibilityActionSignalType& ActionPageUpSignal();
628 * @brief This is emitted when accessibility action is received to scroll down to the
629 * next page (by one finger swipe right and left)
631 * A callback of the following type may be connected:
633 * bool YourCallback( AccessibilityManager& manager );
635 * @return The signal to connect to.
637 AccessibilityActionSignalType& ActionPageDownSignal();
640 * @brief This is emitted when accessibility action is received to move the focus to
641 * the first item on the screen (by one finger swipe up and down)
643 * A callback of the following type may be connected:
645 * bool YourCallback( AccessibilityManager& manager );
647 * @return The signal to connect to.
649 AccessibilityActionSignalType& ActionMoveToFirstSignal();
652 * @brief This is emitted when accessibility action is received to move the focus to
653 * the last item on the screen (by one finger swipe down and up)
655 * A callback of the following type may be connected:
657 * bool YourCallback( AccessibilityManager& manager );
659 * @return The signal to connect to.
661 AccessibilityActionSignalType& ActionMoveToLastSignal();
664 * @brief This is emitted when accessibility action is received to focus and read from the
665 * first item on the top continously (by three fingers single tap)
667 * A callback of the following type may be connected:
669 * bool YourCallback( AccessibilityManager& manager );
671 * @return The signal to connect to.
673 AccessibilityActionSignalType& ActionReadFromTopSignal();
676 * @brief This is emitted when accessibility action is received to move the focus to and
677 * read from the next item continously (by three fingers double tap)
679 * A callback of the following type may be connected:
681 * bool YourCallback( AccessibilityManager& manager );
683 * @return The signal to connect to.
685 AccessibilityActionSignalType& ActionReadFromNextSignal();
688 * @brief This is emitted when accessibility action is received to zoom (by one finger
691 * A callback of the following type may be connected:
693 * bool YourCallback( AccessibilityManager& manager );
695 * @return The signal to connect to.
697 AccessibilityActionSignalType& ActionZoomSignal();
700 * @brief This is emitted when accessibility action is received to read the information
701 * in the indicator (by two fingers triple tap).
703 * A callback of the following type may be connected:
705 * bool YourCallback( AccessibilityManager& manager );
707 * @return The signal to connect to.
709 AccessibilityActionSignalType& ActionReadIndicatorInformationSignal();
712 * @brief This is emitted when accessibility action is received to pause/resume the
713 * current speech (by two fingers single tap).
715 * A callback of the following type may be connected:
717 * bool YourCallback( AccessibilityManager& manager );
719 * @return The signal to connect to.
721 AccessibilityActionSignalType& ActionReadPauseResumeSignal();
724 * @brief This is emitted when accessibility action is received to start/stop the
725 * current action (by two fingers double tap).
727 * A callback of the following type may be connected:
729 * bool YourCallback( AccessibilityManager& manager );
731 * @return The signal to connect to.
733 AccessibilityActionSignalType& ActionStartStopSignal();
736 * @brief This is emitted when accessibility action is received to handle scroll event (by two
739 * A callback of the following type may be connected:
741 * bool YourCallback( AccessibilityManager& manager, const TouchEvent& event );
743 * @return The signal to connect to.
745 AccessibilityActionScrollSignalType& ActionScrollSignal();
749 explicit DALI_INTERNAL AccessibilityManager( Internal::AccessibilityManager *impl );
751 }; // class AccessibilityManager
753 } // namespace Toolkit
757 #endif // __DALI_TOOLKIT_ACCESSIBILITY_MANAGER_H__