1 #ifndef __DALI_TOOLKIT_FOCUS_MANAGER_H__
2 #define __DALI_TOOLKIT_FOCUS_MANAGER_H__
5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
7 // Licensed under the Flora License, Version 1.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://floralicense.org/license/
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.
21 * @addtogroup CAPI_DALI_FRAMEWORK
26 #include <dali/dali.h>
28 namespace Dali DALI_IMPORT_API
34 namespace Internal DALI_INTERNAL
41 * This class provides the functionality of registering the focus order and description
42 * of actors and maintaining the focus chain. It provides functionality of setting the
43 * focus and moving the focus forward and backward. It also draws a highlight for the
44 * focused actor and emits a signal when the focus is changed.
47 class FocusManager : public BaseHandle
51 static const char* const SIGNAL_FOCUS_CHANGED;
52 static const char* const SIGNAL_FOCUS_OVERSHOT;
53 static const char* const SIGNAL_FOCUSED_ACTOR_ACTIVATED;
56 static const std::string ACTOR_FOCUSABLE; ///< name "focusable", type bool
57 static const std::string IS_FOCUS_GROUP; ///< name "is-focus-group", type bool
60 * Accessibility needs four information which will be read by screen-reader.
61 * Reading order : Label -> Trait -> Optional (Value and Hint)
63 enum AccessibilityAttribute
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
72 enum FocusOvershotDirection
74 OVERSHOT_PREVIOUS = -1, ///< Try to move previous of the first actor
75 OVERSHOT_NEXT = 1, ///< Try to move next of the last actor
80 //Focus changed signal
81 typedef SignalV2< void ( Actor, Actor ) > FocusChangedSignalV2;
83 //Focus overshooted signal
84 typedef SignalV2< void ( Actor, FocusOvershotDirection ) > FocusOvershotSignalV2;
86 //Focused actor activated signal
87 typedef SignalV2< void ( Actor ) > FocusedActorActivatedSignalV2;
90 * Create a FocusManager handle; this can be initialised with FocusManager::New()
91 * Calling member functions with an uninitialised handle is not allowed.
98 virtual ~FocusManager();
101 * Get the singleton of FocusManager object.
102 * @return A handle to the FocusManager control.
104 static FocusManager Get();
107 * Set the information of the specified actor's accessibility attribute.
108 * @pre The FocusManager has been initialized.
109 * @pre The Actor has been initialized.
110 * @param actor The actor the text to be set with
111 * @param type The attribute type the text to be set with
112 * @param text The text for the actor's accessibility information
114 void SetAccessibilityAttribute(Actor actor, AccessibilityAttribute type, const std::string& text);
117 * Get the text of the specified actor's accessibility attribute.
118 * @pre The FocusManager has been initialized.
119 * @pre The Actor has been initialized.
120 * @param actor The actor to be queried
121 * @param type The attribute type to be queried
122 * @return The text of the actor's accessibility information
124 std::string GetAccessibilityAttribute(Actor actor, AccessibilityAttribute type) const;
127 * Set the focus order of the actor. The focus order of each actor in the focus chain
128 * is unique. If there is another actor assigned with the same focus order already,
129 * the new actor will be inserted to the focus chain with that focus order, and the
130 * focus order of the original actor and all the actors followed in the focus chain
131 * will be increased accordingly. If the focus order assigned to the actor is 0, it
132 * means that actor's focus order is undefined (e.g. the actor has a description but
133 * with no focus order being set yet) and therefore that actor is not focusable.
134 * @pre The FocusManager has been initialized.
135 * @pre The Actor has been initialized.
136 * @param actor The actor the focus order to be set with
137 * @param order The focus order of the actor
139 void SetFocusOrder(Actor actor, const unsigned int order);
142 * Get the focus order of the actor. When the focus order is 0, it means the focus order
143 * of the actor is undefined.
144 * @pre The FocusManager has been initialized.
145 * @pre The Actor has been initialized.
146 * @param actor The actor to be queried
147 * @return The focus order of the actor
149 unsigned int GetFocusOrder(Actor actor) const;
152 * Generates a new focus order number which can be used to assign to actors which need to be
153 * appended to the end of the current focus order chain. The new number will be an increment
154 * over the very last focus order number in the focus chain. If the focus chain is empty then
155 * the function returns 1, else the number returned will be FOLast + 1 where FOLast is the focus
156 * order of the very last control in the focus chain.
157 * @pre The FocusManager has been initialized.
158 * @return The focus order of the actor
160 unsigned int GenerateNewFocusOrder() const;
163 * Get the actor that has the specified focus order. It will return an empty handle if the
164 * actor is not in the stage or has a focus order of 0.
165 * @pre The FocusManager has been initialized.
166 * @param order The focus order of the actor
167 * @return The actor that has the specified focus order or an empty handle if no actor in the stage has the specified focus order.
169 Actor GetActorByFocusOrder(const unsigned int order);
172 * Move the focus to the specified actor. Only one actor can be focused at the same time.
173 * The actor must have a defined focus order and must be focusable, visible and in the stage.
174 * @pre The FocusManager has been initialized.
175 * @pre The Actor has been initialized.
176 * @param actor The actor to be focused
177 * @return Whether the focus is successful or not
179 bool SetCurrentFocusActor(Actor actor);
182 * Get the current focused actor.
183 * @pre The FocusManager has been initialized.
184 * @return A handle to the current focused actor or an empty handle if no actor is focused.
186 Actor GetCurrentFocusActor();
189 * Get the focus group of current focused actor.
190 * @pre The FocusManager has been initialized.
191 * @return A handle to the immediate parent of the current focused actor which is also a focus group,
192 * or an empty handle if no actor is focused.
194 Actor GetCurrentFocusGroup();
197 * Get the focus order of currently focused actor.
198 * @pre The FocusManager has been initialized.
199 * @return The focus order of the currently focused actor or 0 if no actor is in focus.
201 unsigned int GetCurrentFocusOrder();
204 * Move the focus to the next focusable actor in the focus chain (according to the focus
205 * traversal order). When the focus movement is wrapped around, the focus will be moved
206 * to the first focusable actor when it reaches the end of the focus chain.
207 * @pre The FocusManager has been initialized.
208 * @return true if the moving was successful
210 bool MoveFocusForward();
213 * Move the focus to the previous focusable actor in the focus chain (according to the
214 * focus traversal order). When the focus movement is wrapped around, the focus will be
215 * moved to the last focusable actor when it reaches the beginning of the focus chain.
216 * @pre The FocusManager has been initialized.
217 * @return true if the moving was successful
219 bool MoveFocusBackward();
222 * Clear the focus from the current focused actor if any, so that no actor is focused
223 * in the focus chain.
224 * It will emit focus changed signal without current focused actor
225 * @pre The FocusManager has been initialized.
230 * Clear the every registered focusable actor from focus-manager.
231 * @pre The FocusManager has been initialized.
236 * Set whether an actor is a focus group that can limit the scope of focus movement to
237 * its child actors in the focus chain.
238 * @pre The FocusManager has been initialized.
239 * @pre The Actor has been initialized.
240 * @param actor The actor to be set as a focus group.
241 * @param isFocusGroup Whether to set the actor to be a focus group or not.
243 void SetFocusGroup(Actor actor, bool isFocusGroup);
246 * Check whether the actor is set as a focus group or not.
247 * @pre The FocusManager has been initialized.
248 * @pre The Actor has been initialized.
249 * @param actor The actor to be checked.
250 * @return Whether the actor is set as a focus group.
252 bool IsFocusGroup(Actor actor) const;
255 * Set whether the group mode is enabled or not.
256 * When the group mode is enabled, the focus movement will be limited to the child actors
257 * of the current focus group including the current focus group itself. The current focus
258 * group is the closest ancestor of the current focused actor that set as a focus group.
259 * @pre The FocusManager has been initialized.
260 * @param enabled Whether the group mode is enabled or not
262 void SetGroupMode(bool enabled);
265 * Get whether the group mode is enabled or not.
266 * @pre The FocusManager has been initialized.
267 * @return Whether the group mode is enabled or not.
269 bool GetGroupMode() const;
272 * Set whether focus will be moved to the beginning of the focus chain when it reaches the
273 * end or vice versa. When both the wrap mode and the group mode are enabled, focus will be
274 * wrapped within the current focus group. Focus will not be wrapped in default.
275 * @pre The FocusManager has been initialized.
276 * @param wrapped Whether the focus movement is wrapped around or not
278 void SetWrapMode(bool wrapped);
281 * Get whether the wrap mode is enabled or not.
282 * @pre The FocusManager has been initialized.
283 * @return Whether the wrap mode is enabled or not.
285 bool GetWrapMode() const;
288 * Set the focus indicator actor. This will replace the default focus indicator actor
289 * in FocusManager and will be added to the focused actor as a highlight.
290 * @pre The FocusManager has been initialized.
291 * @pre The indicator actor has been initialized.
292 * @param indicator The indicator actor to be added
294 void SetFocusIndicatorActor(Actor indicator);
297 * Get the focus indicator actor.
298 * @pre The FocusManager has been initialized.
299 * @return A handle to the focus indicator actor
301 Actor GetFocusIndicatorActor();
304 * Returns the closest ancestor of the given actor that is a focus group.
305 * @param actor The actor to be checked for its focus group
306 * @return The focus group the given actor belongs to or an empty handle if the given actor doesn't belong to any focus group
308 Actor GetFocusGroup(Actor actor);
313 * This signal is emitted when the current focused actor is changed.
314 * A callback of the following type may be connected:
316 * void YourCallbackName(Actor originalFocusedActor, Actor currentFocusedActor);
318 * @pre The Object has been initialized.
319 * @return The signal to connect to.
321 FocusChangedSignalV2& FocusChangedSignal();
324 * This signal is emitted when there is no way to move focus further.
325 * A callback of the following type may be connected:
327 * void YourCallbackName(Actor currentFocusedActor, FocusOvershotDirection direction);
329 * @pre The Object has been initialized.
330 * @return The signal to connect to.
332 FocusOvershotSignalV2& FocusOvershotSignal();
335 * This signal is emitted when the current focused actor is activated.
336 * A callback of the following type may be connected:
338 * void YourCallbackName(Actor activatedActor);
340 * @pre The Object has been initialized.
341 * @return The signal to connect to.
343 FocusedActorActivatedSignalV2& FocusedActorActivatedSignal();
347 FocusManager(Internal::FocusManager *impl);
349 }; // class FocusManager
351 } // namespace Toolkit
358 #endif // __DALI_TOOLKIT_FOCUS_MANAGER_H__