Merge changes Icccc1ca3,Ia32ce8ab into devel/master
[platform/core/uifw/dali-toolkit.git] / dali-toolkit / public-api / focus-manager / accessibility-focus-manager.h
1 #ifndef __DALI_TOOLKIT_ACCESSIBILITY_FOCUS_MANAGER_H__
2 #define __DALI_TOOLKIT_ACCESSIBILITY_FOCUS_MANAGER_H__
3
4 /*
5  * Copyright (c) 2015 Samsung Electronics Co., Ltd.
6  *
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
10  *
11  * http://www.apache.org/licenses/LICENSE-2.0
12  *
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.
18  *
19  */
20
21 // EXTERNAL INCLUDES
22 #include <dali/public-api/actors/actor.h>
23 #include <dali/public-api/actors/image-actor.h>
24
25 namespace Dali
26 {
27
28 namespace Toolkit
29 {
30
31 namespace Internal DALI_INTERNAL
32 {
33 class AccessibilityFocusManager;
34 }
35
36 /**
37  * @brief Manages registration of actors in a accessibility focus chain and changing the
38  * focused actor within that chain.
39  *
40  * This class provides the functionality of registering the focus order and description
41  * of actors and maintaining the focus chain.
42  *
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.
46  *
47  * Signals
48  * | %Signal Name            | Method                             |
49  * |-------------------------|------------------------------------|
50  * | focus-changed           | @ref FocusChangedSignal()          |
51  * | focus-overshot          | @ref FocusOvershotSignal()         |
52  * | focused-actor-activated | @ref FocusedActorActivatedSignal() |
53  */
54 class DALI_IMPORT_API AccessibilityFocusManager : public BaseHandle
55 {
56 public:
57
58   /**
59    * @brief Accessibility needs four information which will be read by screen-reader.
60    *
61    * Reading order : Label -> Trait -> Optional (Value and Hint)
62    */
63   enum AccessibilityAttribute
64   {
65     ACCESSIBILITY_LABEL = 0, ///< Simple text which contained in ui-control
66     ACCESSIBILITY_TRAIT,     ///< Description of ui-control trait
67     ACCESSIBILITY_VALUE,     ///< Current value of ui-control (Optional)
68     ACCESSIBILITY_HINT,      ///< Hint for action (Optional)
69     ACCESSIBILITY_ATTRIBUTE_NUM ///< Number of attributes
70   };
71
72    /**
73     * @brief Overshoot direction.
74     */
75   enum FocusOvershotDirection
76   {
77     OVERSHOT_PREVIOUS = -1, ///< Try to move previous of the first actor
78     OVERSHOT_NEXT = 1,      ///< Try to move next of the last actor
79   };
80
81  public:
82
83   /// @brief Focus changed signal
84   typedef Signal< void ( Actor, Actor ) > FocusChangedSignalType;
85
86   /// @brief Focus overshooted signal
87   typedef Signal< void ( Actor, FocusOvershotDirection ) > FocusOvershotSignalType;
88
89   /// @brief Focused actor activated signal
90   typedef Signal< void ( Actor ) > FocusedActorActivatedSignalType;
91
92   /**
93    * @brief Create a AccessibilityFocusManager handle; this can be initialised with AccessibilityFocusManager::New().
94    *
95    * Calling member functions with an uninitialised handle is not allowed.
96    */
97   AccessibilityFocusManager();
98
99   /**
100    * @brief Destructor
101    *
102    * This is non-virtual since derived Handle types must not contain data or virtual methods.
103    */
104   ~AccessibilityFocusManager();
105
106   /**
107    * @brief Get the singleton of AccessibilityFocusManager object.
108    *
109    * @return A handle to the AccessibilityFocusManager control.
110    */
111   static AccessibilityFocusManager Get();
112
113   /**
114    * @brief Set the information of the specified actor's accessibility attribute.
115    *
116    * @pre The AccessibilityFocusManager has been initialized.
117    * @pre The Actor has been initialized.
118    * @param actor The actor the text to be set with
119    * @param type The attribute type the text to be set with
120    * @param text The text for the actor's accessibility information
121    */
122   void SetAccessibilityAttribute(Actor actor, AccessibilityAttribute type, const std::string& text);
123
124   /**
125    * @brief Get the text of the specified actor's accessibility attribute.
126    *
127    * @pre The AccessibilityFocusManager has been initialized.
128    * @pre The Actor has been initialized.
129    * @param actor The actor to be queried
130    * @param type The attribute type to be queried
131    * @return The text of the actor's accessibility information
132    */
133   std::string GetAccessibilityAttribute(Actor actor, AccessibilityAttribute type) const;
134
135   /**
136    * @brief Set the focus order of the actor.
137    *
138    * The focus order of each actor in the focus chain is unique. If
139    * there is another actor assigned with the same focus order
140    * already, the new actor will be inserted to the focus chain with
141    * that focus order, and the focus order of the original actor and
142    * all the actors followed in the focus chain will be increased
143    * accordingly. If the focus order assigned to the actor is 0, it
144    * means that actor's focus order is undefined (e.g. the actor has a
145    * description but with no focus order being set yet) and therefore
146    * that actor is not focusable.
147    *
148    * @pre The AccessibilityFocusManager has been initialized.
149    * @pre The Actor has been initialized.
150    * @param actor The actor the focus order to be set with
151    * @param order The focus order of the actor
152    */
153   void SetFocusOrder(Actor actor, const unsigned int order);
154
155   /**
156    * @brief Get the focus order of the actor.
157    *
158    * When the focus order is 0, it means the focus order of the actor
159    * is undefined.
160    *
161    * @pre The AccessibilityFocusManager has been initialized.
162    * @pre The Actor has been initialized.
163    * @param actor The actor to be queried
164    * @return The focus order of the actor
165    */
166   unsigned int GetFocusOrder(Actor actor) const;
167
168   /**
169    * @brief Generates a new focus order number which can be used to
170    * assign to actors which need to be appended to the end of the
171    * current focus order chain.
172    *
173    * The new number will be an increment over the very last focus
174    * order number in the focus chain. If the focus chain is empty then
175    * the function returns 1, else the number returned will be FOLast +
176    * 1 where FOLast is the focus order of the very last control in the
177    * focus chain.
178    *
179    * @pre The AccessibilityFocusManager has been initialized.
180    * @return The focus order of the actor
181    */
182   unsigned int GenerateNewFocusOrder() const;
183
184   /**
185    * @brief Get the actor that has the specified focus order.
186    *
187    * It will return an empty handle if the actor is not in the stage
188    * or has a focus order of 0.
189    *
190    * @pre The AccessibilityFocusManager has been initialized.
191    * @param order The focus order of the actor
192    *
193    * @return The actor that has the specified focus order or an empty
194    * handle if no actor in the stage has the specified focus order.
195    */
196   Actor GetActorByFocusOrder(const unsigned int order);
197
198   /**
199    * @brief Move the focus to the specified actor.
200    *
201    * Only one actor can be focused at the same time.  The actor must
202    * have a defined focus order and must be focusable, visible and in
203    * the stage.
204    *
205    * @pre The AccessibilityFocusManager has been initialized.
206    * @pre The Actor has been initialized.
207    * @param actor The actor to be focused
208    * @return Whether the focus is successful or not
209    */
210   bool SetCurrentFocusActor(Actor actor);
211
212   /**
213    * @brief Get the current focused actor.
214    *
215    * @pre The AccessibilityFocusManager has been initialized.
216    * @return A handle to the current focused actor or an empty handle if no actor is focused.
217    */
218   Actor GetCurrentFocusActor();
219
220   /**
221    * @brief Get the focus group of current focused actor.
222    *
223    * @pre The AccessibilityFocusManager has been initialized.
224    *
225    * @return A handle to the immediate parent of the current focused
226    * actor which is also a focus group, or an empty handle if no actor
227    * is focused.
228    */
229   Actor GetCurrentFocusGroup();
230
231   /**
232    * @brief Get the focus order of currently focused actor.
233    * @pre The AccessibilityFocusManager has been initialized.
234    *
235    * @return The focus order of the currently focused actor or 0 if no
236    * actor is in focus.
237    */
238   unsigned int GetCurrentFocusOrder();
239
240   /**
241    * @brief Move the focus to the next focusable actor in the focus
242    * chain (according to the focus traversal order).
243    *
244    * When the focus movement is wrapped around, the focus will be moved
245    * to the first focusable actor when it reaches the end of the focus chain.
246    *
247    * @pre The AccessibilityFocusManager has been initialized.
248    * @return true if the moving was successful
249    */
250   bool MoveFocusForward();
251
252   /**
253    * @brief Move the focus to the previous focusable actor in the
254    * focus chain (according to the focus traversal order).
255    *
256    * When the focus movement is wrapped around, the focus will be
257    * moved to the last focusable actor when it reaches the beginning
258    * of the focus chain.
259    *
260    * @pre The AccessibilityFocusManager has been initialized.
261    * @return true if the moving was successful
262    */
263   bool MoveFocusBackward();
264
265   /**
266    * @brief Clear the focus from the current focused actor if any, so
267    * that no actor is focused in the focus chain.
268    *
269    * It will emit focus changed signal without current focused actor
270    * @pre The AccessibilityFocusManager has been initialized.
271    */
272   void ClearFocus();
273
274   /**
275    * @brief Clear the every registered focusable actor from focus-manager.
276    * @pre The AccessibilityFocusManager has been initialized.
277    */
278   void Reset();
279
280   /**
281    * @brief Set whether an actor is a focus group that can limit the
282    * scope of focus movement to its child actors in the focus chain.
283    *
284    * @pre The AccessibilityFocusManager has been initialized.
285    * @pre The Actor has been initialized.
286    * @param actor The actor to be set as a focus group.
287    * @param isFocusGroup Whether to set the actor to be a focus group or not.
288    */
289   void SetFocusGroup(Actor actor, bool isFocusGroup);
290
291   /**
292    * @brief Check whether the actor is set as a focus group or not.
293    *
294    * @pre The AccessibilityFocusManager has been initialized.
295    * @pre The Actor has been initialized.
296    * @param actor The actor to be checked.
297    * @return Whether the actor is set as a focus group.
298    */
299   bool IsFocusGroup(Actor actor) const;
300
301   /**
302    * @brief Set whether the group mode is enabled or not.
303    *
304    * When the group mode is enabled, the focus movement will be limited to the child actors
305    * of the current focus group including the current focus group itself. The current focus
306    * group is the closest ancestor of the current focused actor that set as a focus group.
307    * @pre The AccessibilityFocusManager has been initialized.
308    * @param enabled Whether the group mode is enabled or not
309    */
310   void SetGroupMode(bool enabled);
311
312   /**
313    * @brief Get whether the group mode is enabled or not.
314    *
315    * @pre The AccessibilityFocusManager has been initialized.
316    * @return Whether the group mode is enabled or not.
317    */
318   bool GetGroupMode() const;
319
320   /**
321    * @brief Set whether focus will be moved to the beginning of the
322    * focus chain when it reaches the end or vice versa.
323    *
324    * When both the wrap mode and the group mode are enabled, focus will be
325    * wrapped within the current focus group. Focus will not be wrapped in default.
326    * @pre The AccessibilityFocusManager has been initialized.
327    * @param wrapped Whether the focus movement is wrapped around or not
328    */
329   void SetWrapMode(bool wrapped);
330
331   /**
332    * @brief Get whether the wrap mode is enabled or not.
333    *
334    * @pre The AccessibilityFocusManager has been initialized.
335    * @return Whether the wrap mode is enabled or not.
336    */
337   bool GetWrapMode() const;
338
339   /**
340    * @brief Set the focus indicator actor.
341    *
342    * This will replace the default focus indicator actor in
343    * AccessibilityFocusManager and will be added to the focused actor as a
344    * highlight.
345    *
346    * @pre The AccessibilityFocusManager has been initialized.
347    * @pre The indicator actor has been initialized.
348    * @param indicator The indicator actor to be added
349    */
350   void SetFocusIndicatorActor(Actor indicator);
351
352   /**
353    * @brief Get the focus indicator actor.
354    *
355    * @pre The AccessibilityFocusManager has been initialized.
356    * @return A handle to the focus indicator actor
357    */
358   Actor GetFocusIndicatorActor();
359
360   /**
361    * @brief Returns the closest ancestor of the given actor that is a focus group.
362    *
363    * @param actor The actor to be checked for its focus group
364    * @return The focus group the given actor belongs to or an empty handle if the given actor doesn't belong to any focus group
365    */
366   Actor GetFocusGroup(Actor actor);
367
368  public: // Signals
369
370   /**
371    * @brief This signal is emitted when the current focused actor is changed.
372    *
373    * A callback of the following type may be connected:
374    * @code
375    *   void YourCallbackName(Actor originalFocusedActor, Actor currentFocusedActor);
376    * @endcode
377    * @pre The Object has been initialized.
378    * @return The signal to connect to.
379    */
380   FocusChangedSignalType& FocusChangedSignal();
381
382   /**
383    * @brief This signal is emitted when there is no way to move focus further.
384    *
385    * A callback of the following type may be connected:
386    * @code
387    *   void YourCallbackName(Actor currentFocusedActor, FocusOvershotDirection direction);
388    * @endcode
389    * @pre The Object has been initialized.
390    * @return The signal to connect to.
391    */
392   FocusOvershotSignalType& FocusOvershotSignal();
393
394   /**
395    * @brief This signal is emitted when the current focused actor is activated.
396    *
397    * A callback of the following type may be connected:
398    * @code
399    *   void YourCallbackName(Actor activatedActor);
400    * @endcode
401    * @pre The Object has been initialized.
402    * @return The signal to connect to.
403    */
404   FocusedActorActivatedSignalType& FocusedActorActivatedSignal();
405
406 private:
407
408   explicit DALI_INTERNAL AccessibilityFocusManager(Internal::AccessibilityFocusManager *impl);
409
410 }; // class AccessibilityFocusManager
411
412 } // namespace Toolkit
413
414 } // namespace Dali
415
416 #endif // __DALI_TOOLKIT_FOCUS_MANAGER_H__