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() |
58 class DALI_IMPORT_API AccessibilityManager : public BaseHandle
65 * @brief Accessibility Action Signal.
67 * The connected signal callback should return true if handled.
69 typedef Signal< bool ( AccessibilityManager& ) > AccessibilityActionSignalType; ///< Generic signal type
70 typedef Signal< bool ( AccessibilityManager&, const Dali::TouchEvent& )> AccessibilityActionScrollSignalType; ///< Scroll signal type
73 * @brief Accessibility needs four information which will be read by screen-reader.
75 * Reading order : Label -> Trait -> Optional (Value and Hint)
77 enum AccessibilityAttribute
79 ACCESSIBILITY_LABEL = 0, ///< Simple text which contained in ui-control
80 ACCESSIBILITY_TRAIT, ///< Description of ui-control trait
81 ACCESSIBILITY_VALUE, ///< Current value of ui-control (Optional)
82 ACCESSIBILITY_HINT, ///< Hint for action (Optional)
83 ACCESSIBILITY_ATTRIBUTE_NUM ///< Number of attributes
87 * @brief Overshoot direction.
89 enum FocusOvershotDirection
91 OVERSHOT_PREVIOUS = -1, ///< Try to move previous of the first actor
92 OVERSHOT_NEXT = 1, ///< Try to move next of the last actor
97 /// @brief Focus changed signal
98 typedef Signal< void ( Actor, Actor ) > FocusChangedSignalType;
100 /// @brief Focus overshooted signal
101 typedef Signal< void ( Actor, FocusOvershotDirection ) > FocusOvershotSignalType;
103 /// @brief Focused actor activated signal
104 typedef Signal< void ( Actor ) > FocusedActorActivatedSignalType;
107 * @brief Create a AccessibilityManager handle; this can be initialised with AccessibilityManager::New().
109 * Calling member functions with an uninitialised handle is not allowed.
111 AccessibilityManager();
116 * This is non-virtual since derived Handle types must not contain data or virtual methods.
118 ~AccessibilityManager();
121 * @brief Get the singleton of AccessibilityManager object.
123 * @return A handle to the AccessibilityManager control.
125 static AccessibilityManager Get();
128 * @brief Set the information of the specified actor's accessibility attribute.
130 * @pre The AccessibilityManager has been initialized.
131 * @pre The Actor has been initialized.
132 * @param actor The actor the text to be set with
133 * @param type The attribute type the text to be set with
134 * @param text The text for the actor's accessibility information
136 void SetAccessibilityAttribute(Actor actor, AccessibilityAttribute type, const std::string& text);
139 * @brief Get the text of the specified actor's accessibility attribute.
141 * @pre The AccessibilityManager has been initialized.
142 * @pre The Actor has been initialized.
143 * @param actor The actor to be queried
144 * @param type The attribute type to be queried
145 * @return The text of the actor's accessibility information
147 std::string GetAccessibilityAttribute(Actor actor, AccessibilityAttribute type) const;
150 * @brief Set the focus order of the actor.
152 * The focus order of each actor in the focus chain is unique. If
153 * there is another actor assigned with the same focus order
154 * already, the new actor will be inserted to the focus chain with
155 * that focus order, and the focus order of the original actor and
156 * all the actors followed in the focus chain will be increased
157 * accordingly. If the focus order assigned to the actor is 0, it
158 * means that actor's focus order is undefined (e.g. the actor has a
159 * description but with no focus order being set yet) and therefore
160 * that actor is not focusable.
162 * @pre The AccessibilityManager has been initialized.
163 * @pre The Actor has been initialized.
164 * @param actor The actor the focus order to be set with
165 * @param order The focus order of the actor
167 void SetFocusOrder(Actor actor, const unsigned int order);
170 * @brief Get the focus order of the actor.
172 * When the focus order is 0, it means the focus order of the actor
175 * @pre The AccessibilityManager has been initialized.
176 * @pre The Actor has been initialized.
177 * @param actor The actor to be queried
178 * @return The focus order of the actor
180 unsigned int GetFocusOrder(Actor actor) const;
183 * @brief Generates a new focus order number which can be used to
184 * assign to actors which need to be appended to the end of the
185 * current focus order chain.
187 * The new number will be an increment over the very last focus
188 * order number in the focus chain. If the focus chain is empty then
189 * the function returns 1, else the number returned will be FOLast +
190 * 1 where FOLast is the focus order of the very last control in the
193 * @pre The AccessibilityManager has been initialized.
194 * @return The focus order of the actor
196 unsigned int GenerateNewFocusOrder() const;
199 * @brief Get the actor that has the specified focus order.
201 * It will return an empty handle if the actor is not in the stage
202 * or has a focus order of 0.
204 * @pre The AccessibilityManager has been initialized.
205 * @param order The focus order of the actor
207 * @return The actor that has the specified focus order or an empty
208 * handle if no actor in the stage has the specified focus order.
210 Actor GetActorByFocusOrder(const unsigned int order);
213 * @brief Move the focus to the specified actor.
215 * Only one actor can be focused at the same time. The actor must
216 * have a defined focus order and must be focusable, visible and in
219 * @pre The AccessibilityManager has been initialized.
220 * @pre The Actor has been initialized.
221 * @param actor The actor to be focused
222 * @return Whether the focus is successful or not
224 bool SetCurrentFocusActor(Actor actor);
227 * @brief Get the current focused actor.
229 * @pre The AccessibilityManager has been initialized.
230 * @return A handle to the current focused actor or an empty handle if no actor is focused.
232 Actor GetCurrentFocusActor();
235 * @brief Get the focus group of current focused actor.
237 * @pre The AccessibilityManager has been initialized.
239 * @return A handle to the immediate parent of the current focused
240 * actor which is also a focus group, or an empty handle if no actor
243 Actor GetCurrentFocusGroup();
246 * @brief Get the focus order of currently focused actor.
247 * @pre The AccessibilityManager has been initialized.
249 * @return The focus order of the currently focused actor or 0 if no
252 unsigned int GetCurrentFocusOrder();
255 * @brief Move the focus to the next focusable actor in the focus
256 * chain (according to the focus traversal order).
258 * When the focus movement is wrapped around, the focus will be moved
259 * to the first focusable actor when it reaches the end of the focus chain.
261 * @pre The AccessibilityManager has been initialized.
262 * @return true if the moving was successful
264 bool MoveFocusForward();
267 * @brief Move the focus to the previous focusable actor in the
268 * focus chain (according to the focus traversal order).
270 * When the focus movement is wrapped around, the focus will be
271 * moved to the last focusable actor when it reaches the beginning
272 * of the focus chain.
274 * @pre The AccessibilityManager has been initialized.
275 * @return true if the moving was successful
277 bool MoveFocusBackward();
280 * @brief Clear the focus from the current focused actor if any, so
281 * that no actor is focused in the focus chain.
283 * It will emit focus changed signal without current focused actor
284 * @pre The AccessibilityManager has been initialized.
289 * @brief Clear the every registered focusable actor from focus-manager.
290 * @pre The AccessibilityManager has been initialized.
295 * @brief Set whether an actor is a focus group that can limit the
296 * scope of focus movement to its child actors in the focus chain.
298 * @pre The AccessibilityManager has been initialized.
299 * @pre The Actor has been initialized.
300 * @param actor The actor to be set as a focus group.
301 * @param isFocusGroup Whether to set the actor to be a focus group or not.
303 void SetFocusGroup(Actor actor, bool isFocusGroup);
306 * @brief Check whether the actor is set as a focus group or not.
308 * @pre The AccessibilityManager has been initialized.
309 * @pre The Actor has been initialized.
310 * @param actor The actor to be checked.
311 * @return Whether the actor is set as a focus group.
313 bool IsFocusGroup(Actor actor) const;
316 * @brief Set whether the group mode is enabled or not.
318 * When the group mode is enabled, the focus movement will be limited to the child actors
319 * of the current focus group including the current focus group itself. The current focus
320 * group is the closest ancestor of the current focused actor that set as a focus group.
321 * @pre The AccessibilityManager has been initialized.
322 * @param enabled Whether the group mode is enabled or not
324 void SetGroupMode(bool enabled);
327 * @brief Get whether the group mode is enabled or not.
329 * @pre The AccessibilityManager has been initialized.
330 * @return Whether the group mode is enabled or not.
332 bool GetGroupMode() const;
335 * @brief Set whether focus will be moved to the beginning of the
336 * focus chain when it reaches the end or vice versa.
338 * When both the wrap mode and the group mode are enabled, focus will be
339 * wrapped within the current focus group. Focus will not be wrapped in default.
340 * @pre The AccessibilityManager has been initialized.
341 * @param wrapped Whether the focus movement is wrapped around or not
343 void SetWrapMode(bool wrapped);
346 * @brief Get whether the wrap mode is enabled or not.
348 * @pre The AccessibilityManager has been initialized.
349 * @return Whether the wrap mode is enabled or not.
351 bool GetWrapMode() const;
354 * @brief Set the focus indicator actor.
356 * This will replace the default focus indicator actor in
357 * AccessibilityManager and will be added to the focused actor as a
360 * @pre The AccessibilityManager has been initialized.
361 * @pre The indicator actor has been initialized.
362 * @param indicator The indicator actor to be added
364 void SetFocusIndicatorActor(Actor indicator);
367 * @brief Get the focus indicator actor.
369 * @pre The AccessibilityManager has been initialized.
370 * @return A handle to the focus indicator actor
372 Actor GetFocusIndicatorActor();
375 * @brief Returns the closest ancestor of the given actor that is a focus group.
377 * @param actor The actor to be checked for its focus group
378 * @return The focus group the given actor belongs to or an empty handle if the given actor doesn't belong to any focus group
380 Actor GetFocusGroup(Actor actor);
383 * @brief Returns the current position of the read action.
384 * @return The current event position.
386 Vector2 GetReadPosition() const;
391 * @brief This signal is emitted when the current focused actor is changed.
393 * A callback of the following type may be connected:
395 * void YourCallbackName(Actor originalFocusedActor, Actor currentFocusedActor);
397 * @pre The Object has been initialized.
398 * @return The signal to connect to.
400 FocusChangedSignalType& FocusChangedSignal();
403 * @brief This signal is emitted when there is no way to move focus further.
405 * A callback of the following type may be connected:
407 * void YourCallbackName(Actor currentFocusedActor, FocusOvershotDirection direction);
409 * @pre The Object has been initialized.
410 * @return The signal to connect to.
412 FocusOvershotSignalType& FocusOvershotSignal();
415 * @brief This signal is emitted when the current focused actor is activated.
417 * A callback of the following type may be connected:
419 * void YourCallbackName(Actor activatedActor);
421 * @pre The Object has been initialized.
422 * @return The signal to connect to.
424 FocusedActorActivatedSignalType& FocusedActorActivatedSignal();
426 public: // Accessibility action signals.
429 * @brief This is emitted when accessibility(screen-reader) feature turned on or off.
431 * A callback of the following type may be connected:
433 * bool YourCallback( AccessibilityManager& manager );
435 * @return The signal to connect to.
437 AccessibilityActionSignalType& StatusChangedSignal();
440 * @brief This is emitted when accessibility action is received to move focus to the next
441 * focusable actor (by one finger flick down).
443 * A callback of the following type may be connected:
445 * bool YourCallback( AccessibilityManager& manager );
447 * @return The signal to connect to.
449 AccessibilityActionSignalType& ActionNextSignal();
452 * @brief This is emitted when accessibility action is received to move focus to the previous
453 * focusable actor (by one finger flick up).
455 * A callback of the following type may be connected:
457 * bool YourCallback( AccessibilityManager& manager );
459 * @return The signal to connect to.
461 AccessibilityActionSignalType& ActionPreviousSignal();
464 * @brief This is emitted when accessibility action is received to activate the current focused
465 * actor (by one finger double tap).
467 * A callback of the following type may be connected:
469 * bool YourCallback( AccessibilityManager& manager );
471 * @return The signal to connect to.
473 AccessibilityActionSignalType& ActionActivateSignal();
476 * @brief This is emitted when accessibility action is received to focus and read the actor
477 * (by one finger tap).
479 * A callback of the following type may be connected:
481 * bool YourCallback( AccessibilityManager& manager );
483 * @return The signal to connect to.
485 AccessibilityActionSignalType& ActionReadSignal();
488 * @brief This is emitted when accessibility action is received to focus and read the actor
489 * (by one finger move).
491 * A callback of the following type may be connected:
493 * bool YourCallback( AccessibilityManager& manager );
495 * @return The signal to connect to.
497 AccessibilityActionSignalType& ActionOverSignal();
500 * @brief This is emitted when accessibility action is received to move focus to the next
501 * focusable actor (by one finger flick right).
503 * A callback of the following type may be connected:
505 * bool YourCallback( AccessibilityManager& manager );
507 * @return The signal to connect to.
509 AccessibilityActionSignalType& ActionReadNextSignal();
512 * @brief This is emitted when accessibility action is received to move focus to the previous
513 * focusable actor (by one finger flick left).
515 * A callback of the following type may be connected:
517 * bool YourCallback( AccessibilityManager& manager );
519 * @return The signal to connect to.
521 AccessibilityActionSignalType& ActionReadPreviousSignal();
524 * @brief This is emitted when accessibility action is received to change the value when the
525 * current focused actor is a slider (by double finger down and move up and right).
527 * A callback of the following type may be connected:
529 * bool YourCallback( AccessibilityManager& manager );
531 * @return The signal to connect to.
533 AccessibilityActionSignalType& ActionUpSignal();
536 * @brief This is emitted when accessibility action is received to change the value when the
537 * current focused actor is a slider (by double finger down and move down and left).
539 * A callback of the following type may be connected:
541 * bool YourCallback( AccessibilityManager& manager );
543 * @return The signal to connect to.
545 AccessibilityActionSignalType& ActionDownSignal();
548 * @brief This is emitted when accessibility action is received to clear the focus from the
549 * current focused actor if any, so that no actor is focused in the focus chain.
551 * A callback of the following type may be connected:
553 * bool YourCallback( AccessibilityManager& manager );
555 * @return The signal to connect to.
557 AccessibilityActionSignalType& ActionClearFocusSignal();
560 * @brief This is emitted when accessibility action is received to navigate back (by two
561 * fingers circle draw).
563 * A callback of the following type may be connected:
565 * bool YourCallback( AccessibilityManager& manager );
567 * @return The signal to connect to.
569 AccessibilityActionSignalType& ActionBackSignal();
572 * @brief This is emitted when accessibility action is received to scroll up the list
573 * (by two finger swipe up).
575 * A callback of the following type may be connected:
577 * bool YourCallback( AccessibilityManager& manager );
579 * @return The signal to connect to.
581 AccessibilityActionSignalType& ActionScrollUpSignal();
584 * @brief This is emitted when accessibility action is received to scroll down the list
585 * (by two finger swipe down).
587 * A callback of the following type may be connected:
589 * bool YourCallback( AccessibilityManager& manager );
591 * @return The signal to connect to.
593 AccessibilityActionSignalType& ActionScrollDownSignal();
596 * @brief This is emitted when accessibility action is received to scroll left to the
597 * previous page (by two finger swipe left)
599 * A callback of the following type may be connected:
601 * bool YourCallback( AccessibilityManager& manager );
603 * @return The signal to connect to.
605 AccessibilityActionSignalType& ActionPageLeftSignal();
608 * @brief This is emitted when accessibility action is received to scroll right to the
609 * next page (by two finger swipe right)
611 * A callback of the following type may be connected:
613 * bool YourCallback( AccessibilityManager& manager );
615 * @return The signal to connect to.
617 AccessibilityActionSignalType& ActionPageRightSignal();
620 * @brief This is emitted when accessibility action is received to scroll up to the
621 * previous page (by one finger swipe left and right)
623 * A callback of the following type may be connected:
625 * bool YourCallback( AccessibilityManager& manager );
627 * @return The signal to connect to.
629 AccessibilityActionSignalType& ActionPageUpSignal();
632 * @brief This is emitted when accessibility action is received to scroll down to the
633 * next page (by one finger swipe right and left)
635 * A callback of the following type may be connected:
637 * bool YourCallback( AccessibilityManager& manager );
639 * @return The signal to connect to.
641 AccessibilityActionSignalType& ActionPageDownSignal();
644 * @brief This is emitted when accessibility action is received to move the focus to
645 * the first item on the screen (by one finger swipe up and down)
647 * A callback of the following type may be connected:
649 * bool YourCallback( AccessibilityManager& manager );
651 * @return The signal to connect to.
653 AccessibilityActionSignalType& ActionMoveToFirstSignal();
656 * @brief This is emitted when accessibility action is received to move the focus to
657 * the last item on the screen (by one finger swipe down and up)
659 * A callback of the following type may be connected:
661 * bool YourCallback( AccessibilityManager& manager );
663 * @return The signal to connect to.
665 AccessibilityActionSignalType& ActionMoveToLastSignal();
668 * @brief This is emitted when accessibility action is received to focus and read from the
669 * first item on the top continously (by three fingers single tap)
671 * A callback of the following type may be connected:
673 * bool YourCallback( AccessibilityManager& manager );
675 * @return The signal to connect to.
677 AccessibilityActionSignalType& ActionReadFromTopSignal();
680 * @brief This is emitted when accessibility action is received to move the focus to and
681 * read from the next item continously (by three fingers double tap)
683 * A callback of the following type may be connected:
685 * bool YourCallback( AccessibilityManager& manager );
687 * @return The signal to connect to.
689 AccessibilityActionSignalType& ActionReadFromNextSignal();
692 * @brief This is emitted when accessibility action is received to zoom (by one finger
695 * A callback of the following type may be connected:
697 * bool YourCallback( AccessibilityManager& manager );
699 * @return The signal to connect to.
701 AccessibilityActionSignalType& ActionZoomSignal();
704 * @brief This is emitted when accessibility action is received to read the information
705 * in the indicator (by two fingers triple tap).
707 * A callback of the following type may be connected:
709 * bool YourCallback( AccessibilityManager& manager );
711 * @return The signal to connect to.
713 AccessibilityActionSignalType& ActionReadIndicatorInformationSignal();
716 * @brief This is emitted when accessibility action is received to pause/resume the
717 * current speech (by two fingers single tap).
719 * A callback of the following type may be connected:
721 * bool YourCallback( AccessibilityManager& manager );
723 * @return The signal to connect to.
725 AccessibilityActionSignalType& ActionReadPauseResumeSignal();
728 * @brief This is emitted when accessibility action is received to start/stop the
729 * current action (by two fingers double tap).
731 * A callback of the following type may be connected:
733 * bool YourCallback( AccessibilityManager& manager );
735 * @return The signal to connect to.
737 AccessibilityActionSignalType& ActionStartStopSignal();
740 * @brief This is emitted when accessibility action is received to handle scroll event (by two
743 * A callback of the following type may be connected:
745 * bool YourCallback( AccessibilityManager& manager, const TouchEvent& event );
747 * @return The signal to connect to.
749 AccessibilityActionScrollSignalType& ActionScrollSignal();
753 explicit DALI_INTERNAL AccessibilityManager( Internal::AccessibilityManager *impl );
755 }; // class AccessibilityManager
760 } // namespace Toolkit
764 #endif // __DALI_TOOLKIT_ACCESSIBILITY_MANAGER_H__