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_accessibility_manager
41 * @brief Manages registration of actors in a 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.
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 Accessibility 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 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
101 typedef Signal< void ( Actor, Actor ) > FocusChangedSignalType;
103 /// @brief Focus overshooted signal
104 typedef Signal< void ( Actor, FocusOvershotDirection ) > FocusOvershotSignalType;
106 /// @brief Focused actor activated signal
107 typedef Signal< void ( Actor ) > FocusedActorActivatedSignalType;
110 * @brief Create a AccessibilityManager handle; this can be initialised with AccessibilityManager::New().
112 * Calling member functions with an uninitialised handle is not allowed.
115 AccessibilityManager();
120 * This is non-virtual since derived Handle types must not contain data or virtual methods.
123 ~AccessibilityManager();
126 * @brief Get the singleton of AccessibilityManager object.
129 * @return A handle to the AccessibilityManager control.
131 static AccessibilityManager Get();
134 * @brief Set the information of the specified actor's accessibility attribute.
137 * @param actor The actor the text to be set with
138 * @param type The attribute type the text to be set with
139 * @param text The text for the actor's accessibility information
140 * @pre The AccessibilityManager has been initialized.
141 * @pre The Actor has been initialized.
143 void SetAccessibilityAttribute(Actor actor, AccessibilityAttribute type, const std::string& text);
146 * @brief Get the text of the specified actor's accessibility attribute.
149 * @param actor The actor to be queried
150 * @param type The attribute type to be queried
151 * @return The text of the actor's accessibility information
152 * @pre The AccessibilityManager has been initialized.
153 * @pre The Actor has been initialized.
155 std::string GetAccessibilityAttribute(Actor actor, AccessibilityAttribute type) const;
158 * @brief Set the focus order of the actor.
160 * The focus order of each actor in the focus chain is unique. If
161 * there is another actor assigned with the same focus order
162 * already, the new actor will be inserted to the focus chain with
163 * that focus order, and the focus order of the original actor and
164 * all the actors followed in the focus chain will be increased
165 * accordingly. If the focus order assigned to the actor is 0, it
166 * means that actor's focus order is undefined (e.g. the actor has a
167 * description but with no focus order being set yet) and therefore
168 * that actor is not focusable.
171 * @param actor The actor the focus order to be set with
172 * @param order The focus order of the actor
173 * @pre The AccessibilityManager has been initialized.
174 * @pre The Actor has been initialized.
176 void SetFocusOrder(Actor actor, const unsigned int order);
179 * @brief Get the focus order of the actor.
181 * When the focus order is 0, it means the focus order of the actor
185 * @param actor The actor to be queried
186 * @return The focus order of the actor
187 * @pre The AccessibilityManager has been initialized.
188 * @pre The Actor has been initialized.
190 unsigned int GetFocusOrder(Actor actor) const;
193 * @brief Generates a new focus order number which can be used to
194 * assign to actors which need to be appended to the end of the
195 * current focus order chain.
197 * The new number will be an increment over the very last focus
198 * order number in the focus chain. If the focus chain is empty then
199 * the function returns 1, else the number returned will be FOLast +
200 * 1 where FOLast is the focus order of the very last control in the
204 * @return The focus order of the actor
205 * @pre The AccessibilityManager has been initialized.
207 unsigned int GenerateNewFocusOrder() const;
210 * @brief Get the actor that has the specified focus order.
212 * It will return an empty handle if the actor is not in the stage
213 * or has a focus order of 0.
216 * @param order The focus order of the actor
218 * @return The actor that has the specified focus order or an empty
219 * handle if no actor in the stage has the specified focus order.
220 * @pre The AccessibilityManager has been initialized.
222 Actor GetActorByFocusOrder(const unsigned int order);
225 * @brief Move the focus to the specified actor.
227 * Only one actor can be focused at the same time. The actor must
228 * have a defined focus order and must be focusable, visible and in
232 * @param actor The actor to be focused
233 * @return Whether the focus is successful or not
234 * @pre The AccessibilityManager has been initialized.
235 * @pre The Actor has been initialized.
237 bool SetCurrentFocusActor(Actor actor);
240 * @brief Get the current focused actor.
243 * @return A handle to the current focused actor or an empty handle if no actor is focused.
244 * @pre The AccessibilityManager has been initialized.
246 Actor GetCurrentFocusActor();
249 * @brief Get the focus group of current focused actor.
252 * @return A handle to the immediate parent of the current focused
253 * actor which is also a focus group, or an empty handle if no actor
255 * @pre The AccessibilityManager has been initialized.
258 Actor GetCurrentFocusGroup();
261 * @brief Get the focus order of currently focused actor.
263 * @return The focus order of the currently focused actor or 0 if no
265 * @pre The AccessibilityManager has been initialized.
268 unsigned int GetCurrentFocusOrder();
271 * @brief Move the focus to the next focusable actor in the focus
272 * chain (according to the focus traversal order).
274 * When the focus movement is wrapped around, the focus will be moved
275 * to the first focusable actor when it reaches the end of the focus chain.
278 * @return true if the moving was successful
279 * @pre The AccessibilityManager has been initialized.
281 bool MoveFocusForward();
284 * @brief Move the focus to the previous focusable actor in the
285 * focus chain (according to the focus traversal order).
287 * When the focus movement is wrapped around, the focus will be
288 * moved to the last focusable actor when it reaches the beginning
289 * of the focus chain.
292 * @return true if the moving was successful
293 * @pre The AccessibilityManager has been initialized.
295 bool MoveFocusBackward();
298 * @brief Clear the focus from the current focused actor if any, so
299 * that no actor is focused in the focus chain.
301 * It will emit focus changed signal without current focused actor
303 * @pre The AccessibilityManager has been initialized.
308 * @brief Clear the every registered focusable actor from focus-manager.
310 * @pre The AccessibilityManager has been initialized.
315 * @brief Set whether an actor is a focus group that can limit the
316 * scope of focus movement to its child actors in the focus chain.
319 * @param actor The actor to be set as a focus group.
320 * @param isFocusGroup Whether to set the actor to be a focus group or not.
321 * @pre The AccessibilityManager has been initialized.
322 * @pre The Actor has been initialized.
324 void SetFocusGroup(Actor actor, bool isFocusGroup);
327 * @brief Check whether the actor is set as a focus group or not.
330 * @param actor The actor to be checked.
331 * @return Whether the actor is set as a focus group.
332 * @pre The AccessibilityManager has been initialized.
333 * @pre The Actor has been initialized.
335 bool IsFocusGroup(Actor actor) const;
338 * @brief Set whether the group mode is enabled or not.
340 * When the group mode is enabled, the focus movement will be limited to the child actors
341 * of the current focus group including the current focus group itself. The current focus
342 * group is the closest ancestor of the current focused actor that set as a focus group.
344 * @param enabled Whether the group mode is enabled or not
345 * @pre The AccessibilityManager has been initialized.
347 void SetGroupMode(bool enabled);
350 * @brief Get whether the group mode is enabled or not.
353 * @return Whether the group mode is enabled or not.
354 * @pre The AccessibilityManager has been initialized.
356 bool GetGroupMode() const;
359 * @brief Set whether focus will be moved to the beginning of the
360 * focus chain when it reaches the end or vice versa.
362 * When both the wrap mode and the group mode are enabled, focus will be
363 * wrapped within the current focus group. Focus will not be wrapped in default.
365 * @param wrapped Whether the focus movement is wrapped around or not
366 * @pre The AccessibilityManager has been initialized.
368 void SetWrapMode(bool wrapped);
371 * @brief Get whether the wrap mode is enabled or not.
374 * @return Whether the wrap mode is enabled or not.
375 * @pre The AccessibilityManager has been initialized.
377 bool GetWrapMode() const;
380 * @brief Set the focus indicator actor.
382 * This will replace the default focus indicator actor in
383 * AccessibilityManager and will be added to the focused actor as a
387 * @param indicator The indicator actor to be added
388 * @pre The AccessibilityManager has been initialized.
389 * @pre The indicator actor has been initialized.
391 void SetFocusIndicatorActor(Actor indicator);
394 * @brief Get the focus indicator actor.
397 * @return A handle to the focus indicator actor
398 * @pre The AccessibilityManager has been initialized.
400 Actor GetFocusIndicatorActor();
403 * @brief Returns the closest ancestor of the given actor that is a focus group.
406 * @param actor The actor to be checked for its focus group
407 * @return The focus group the given actor belongs to or an empty handle if the given actor doesn't belong to any focus group
409 Actor GetFocusGroup(Actor actor);
412 * @brief Returns the current position of the read action.
414 * @return The current event position.
416 Vector2 GetReadPosition() const;
421 * @brief This signal is emitted when the current focused actor is changed.
423 * A callback of the following type may be connected:
425 * void YourCallbackName(Actor originalFocusedActor, Actor currentFocusedActor);
428 * @return The signal to connect to.
429 * @pre The Object has been initialized.
431 FocusChangedSignalType& FocusChangedSignal();
434 * @brief This signal is emitted when there is no way to move focus further.
436 * A callback of the following type may be connected:
438 * void YourCallbackName(Actor currentFocusedActor, FocusOvershotDirection direction);
441 * @return The signal to connect to.
442 * @pre The Object has been initialized.
444 FocusOvershotSignalType& FocusOvershotSignal();
447 * @brief This signal is emitted when the current focused actor is activated.
449 * A callback of the following type may be connected:
451 * void YourCallbackName(Actor activatedActor);
454 * @return The signal to connect to.
455 * @pre The Object has been initialized.
457 FocusedActorActivatedSignalType& FocusedActorActivatedSignal();
459 public: // Accessibility action signals.
462 * @brief This is emitted when accessibility(screen-reader) feature turned on or off.
464 * A callback of the following type may be connected:
466 * bool YourCallback( AccessibilityManager& manager );
469 * @return The signal to connect to.
471 AccessibilityActionSignalType& StatusChangedSignal();
474 * @brief This is emitted when accessibility action is received to move focus to the next
475 * focusable actor (by one finger flick down).
477 * A callback of the following type may be connected:
479 * bool YourCallback( AccessibilityManager& manager );
482 * @return The signal to connect to.
484 AccessibilityActionSignalType& ActionNextSignal();
487 * @brief This is emitted when accessibility action is received to move focus to the previous
488 * focusable actor (by one finger flick up).
490 * A callback of the following type may be connected:
492 * bool YourCallback( AccessibilityManager& manager );
495 * @return The signal to connect to.
497 AccessibilityActionSignalType& ActionPreviousSignal();
500 * @brief This is emitted when accessibility action is received to activate the current focused
501 * actor (by one finger double tap).
503 * A callback of the following type may be connected:
505 * bool YourCallback( AccessibilityManager& manager );
508 * @return The signal to connect to.
510 AccessibilityActionSignalType& ActionActivateSignal();
513 * @brief This is emitted when accessibility action is received to focus and read the actor
514 * (by one finger tap).
516 * A callback of the following type may be connected:
518 * bool YourCallback( AccessibilityManager& manager );
521 * @return The signal to connect to.
523 AccessibilityActionSignalType& ActionReadSignal();
526 * @brief This is emitted when accessibility action is received to focus and read the actor
527 * (by one finger move).
529 * A callback of the following type may be connected:
531 * bool YourCallback( AccessibilityManager& manager );
534 * @return The signal to connect to.
536 AccessibilityActionSignalType& ActionOverSignal();
539 * @brief This is emitted when accessibility action is received to move focus to the next
540 * focusable actor (by one finger flick right).
542 * A callback of the following type may be connected:
544 * bool YourCallback( AccessibilityManager& manager );
547 * @return The signal to connect to.
549 AccessibilityActionSignalType& ActionReadNextSignal();
552 * @brief This is emitted when accessibility action is received to move focus to the previous
553 * focusable actor (by one finger flick left).
555 * A callback of the following type may be connected:
557 * bool YourCallback( AccessibilityManager& manager );
560 * @return The signal to connect to.
562 AccessibilityActionSignalType& ActionReadPreviousSignal();
565 * @brief This is emitted when accessibility action is received to change the value when the
566 * current focused actor is a slider (by double finger down and move up and right).
568 * A callback of the following type may be connected:
570 * bool YourCallback( AccessibilityManager& manager );
573 * @return The signal to connect to.
575 AccessibilityActionSignalType& ActionUpSignal();
578 * @brief This is emitted when accessibility action is received to change the value when the
579 * current focused actor is a slider (by double finger down and move down and left).
581 * A callback of the following type may be connected:
583 * bool YourCallback( AccessibilityManager& manager );
586 * @return The signal to connect to.
588 AccessibilityActionSignalType& ActionDownSignal();
591 * @brief This is emitted when accessibility action is received to clear the focus from the
592 * current focused actor if any, so that no actor is focused in the focus chain.
594 * A callback of the following type may be connected:
596 * bool YourCallback( AccessibilityManager& manager );
599 * @return The signal to connect to.
601 AccessibilityActionSignalType& ActionClearFocusSignal();
604 * @brief This is emitted when accessibility action is received to navigate back (by two
605 * fingers circle draw).
607 * A callback of the following type may be connected:
609 * bool YourCallback( AccessibilityManager& manager );
612 * @return The signal to connect to.
614 AccessibilityActionSignalType& ActionBackSignal();
617 * @brief This is emitted when accessibility action is received to scroll up the list
618 * (by two finger swipe up).
620 * A callback of the following type may be connected:
622 * bool YourCallback( AccessibilityManager& manager );
625 * @return The signal to connect to.
627 AccessibilityActionSignalType& ActionScrollUpSignal();
630 * @brief This is emitted when accessibility action is received to scroll down the list
631 * (by two finger swipe down).
633 * A callback of the following type may be connected:
635 * bool YourCallback( AccessibilityManager& manager );
638 * @return The signal to connect to.
640 AccessibilityActionSignalType& ActionScrollDownSignal();
643 * @brief This is emitted when accessibility action is received to scroll left to the
644 * previous page (by two finger swipe left)
646 * A callback of the following type may be connected:
648 * bool YourCallback( AccessibilityManager& manager );
651 * @return The signal to connect to.
653 AccessibilityActionSignalType& ActionPageLeftSignal();
656 * @brief This is emitted when accessibility action is received to scroll right to the
657 * next page (by two finger swipe right)
659 * A callback of the following type may be connected:
661 * bool YourCallback( AccessibilityManager& manager );
664 * @return The signal to connect to.
666 AccessibilityActionSignalType& ActionPageRightSignal();
669 * @brief This is emitted when accessibility action is received to scroll up to the
670 * previous page (by one finger swipe left and right)
672 * A callback of the following type may be connected:
674 * bool YourCallback( AccessibilityManager& manager );
677 * @return The signal to connect to.
679 AccessibilityActionSignalType& ActionPageUpSignal();
682 * @brief This is emitted when accessibility action is received to scroll down to the
683 * next page (by one finger swipe right and left)
685 * A callback of the following type may be connected:
687 * bool YourCallback( AccessibilityManager& manager );
690 * @return The signal to connect to.
692 AccessibilityActionSignalType& ActionPageDownSignal();
695 * @brief This is emitted when accessibility action is received to move the focus to
696 * the first item on the screen (by one finger swipe up and down)
698 * A callback of the following type may be connected:
700 * bool YourCallback( AccessibilityManager& manager );
703 * @return The signal to connect to.
705 AccessibilityActionSignalType& ActionMoveToFirstSignal();
708 * @brief This is emitted when accessibility action is received to move the focus to
709 * the last item on the screen (by one finger swipe down and up)
711 * A callback of the following type may be connected:
713 * bool YourCallback( AccessibilityManager& manager );
716 * @return The signal to connect to.
718 AccessibilityActionSignalType& ActionMoveToLastSignal();
721 * @brief This is emitted when accessibility action is received to focus and read from the
722 * first item on the top continously (by three fingers single tap)
724 * A callback of the following type may be connected:
726 * bool YourCallback( AccessibilityManager& manager );
729 * @return The signal to connect to.
731 AccessibilityActionSignalType& ActionReadFromTopSignal();
734 * @brief This is emitted when accessibility action is received to move the focus to and
735 * read from the next item continously (by three fingers double tap)
737 * A callback of the following type may be connected:
739 * bool YourCallback( AccessibilityManager& manager );
742 * @return The signal to connect to.
744 AccessibilityActionSignalType& ActionReadFromNextSignal();
747 * @brief This is emitted when accessibility action is received to zoom (by one finger
750 * A callback of the following type may be connected:
752 * bool YourCallback( AccessibilityManager& manager );
755 * @return The signal to connect to.
757 AccessibilityActionSignalType& ActionZoomSignal();
760 * @brief This is emitted when accessibility action is received to read the information
761 * in the indicator (by two fingers triple tap).
763 * A callback of the following type may be connected:
765 * bool YourCallback( AccessibilityManager& manager );
768 * @return The signal to connect to.
770 AccessibilityActionSignalType& ActionReadIndicatorInformationSignal();
773 * @brief This is emitted when accessibility action is received to pause/resume the
774 * current speech (by two fingers single tap).
776 * A callback of the following type may be connected:
778 * bool YourCallback( AccessibilityManager& manager );
781 * @return The signal to connect to.
783 AccessibilityActionSignalType& ActionReadPauseResumeSignal();
786 * @brief This is emitted when accessibility action is received to start/stop the
787 * current action (by two fingers double tap).
789 * A callback of the following type may be connected:
791 * bool YourCallback( AccessibilityManager& manager );
794 * @return The signal to connect to.
796 AccessibilityActionSignalType& ActionStartStopSignal();
799 * @brief This is emitted when accessibility action is received to handle scroll event (by two
802 * A callback of the following type may be connected:
804 * bool YourCallback( AccessibilityManager& manager, const TouchEvent& event );
807 * @return The signal to connect to.
809 AccessibilityActionScrollSignalType& ActionScrollSignal();
813 explicit DALI_INTERNAL AccessibilityManager( Internal::AccessibilityManager *impl );
815 }; // class AccessibilityManager
820 } // namespace Toolkit
824 #endif // __DALI_TOOLKIT_ACCESSIBILITY_MANAGER_H__