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 * Accessibility needs four information which will be read by screen-reader.
57 * Reading order : Label -> Trait -> Optional (Value and Hint)
59 enum AccessibilityAttribute
61 ACCESSIBILITY_LABEL = 0, ///< Simple text which contained in ui-control
62 ACCESSIBILITY_TRAIT, ///< Description of ui-control trait
63 ACCESSIBILITY_VALUE, ///< Current value of ui-control (Optional)
64 ACCESSIBILITY_HINT, ///< Hint for action (Optional)
65 ACCESSIBILITY_ATTRIBUTE_NUM
68 enum FocusOvershotDirection
70 OVERSHOT_PREVIOUS = -1, ///< Try to move previous of the first actor
71 OVERSHOT_NEXT = 1, ///< Try to move next of the last actor
76 //Focus changed signal
77 typedef SignalV2< void ( Actor, Actor ) > FocusChangedSignalV2;
79 //Focus overshooted signal
80 typedef SignalV2< void ( Actor, FocusOvershotDirection ) > FocusOvershotSignalV2;
82 //Focused actor activated signal
83 typedef SignalV2< void ( Actor ) > FocusedActorActivatedSignalV2;
86 * Create a FocusManager handle; this can be initialised with FocusManager::New()
87 * Calling member functions with an uninitialised handle is not allowed.
94 virtual ~FocusManager();
97 * Get the singleton of FocusManager object.
98 * @return A handle to the FocusManager control.
100 static FocusManager Get();
103 * Set the information of the specified actor's accessibility attribute.
104 * @pre The FocusManager has been initialized.
105 * @pre The Actor has been initialized.
106 * @param actor The actor the text to be set with
107 * @param type The attribute type the text to be set with
108 * @param text The text for the actor's accessibility information
110 void SetAccessibilityAttribute(Actor actor, AccessibilityAttribute type, const std::string& text);
113 * Get the text of the specified actor's accessibility attribute.
114 * @pre The FocusManager has been initialized.
115 * @pre The Actor has been initialized.
116 * @param actor The actor to be queried
117 * @param type The attribute type to be queried
118 * @return The text of the actor's accessibility information
120 std::string GetAccessibilityAttribute(Actor actor, AccessibilityAttribute type) const;
123 * Set the focus order of the actor. The focus order of each actor in the focus chain
124 * is unique. If there is another actor assigned with the same focus order already,
125 * the new actor will be inserted to the focus chain with that focus order, and the
126 * focus order of the original actor and all the actors followed in the focus chain
127 * will be increased accordingly. If the focus order assigned to the actor is 0, it
128 * means that actor's focus order is undefined (e.g. the actor has a description but
129 * with no focus order being set yet) and therefore that actor is not focusable.
130 * @pre The FocusManager has been initialized.
131 * @pre The Actor has been initialized.
132 * @param actor The actor the focus order to be set with
133 * @param order The focus order of the actor
135 void SetFocusOrder(Actor actor, const unsigned int order);
138 * Get the focus order of the actor. When the focus order is 0, it means the focus order
139 * of the actor is undefined.
140 * @pre The FocusManager has been initialized.
141 * @pre The Actor has been initialized.
142 * @param actor The actor to be queried
143 * @return The focus order of the actor
145 unsigned int GetFocusOrder(Actor actor) const;
148 * Generates a new focus order number which can be used to assign to actors which need to be
149 * appended to the end of the current focus order chain. The new number will be an increment
150 * over the very last focus order number in the focus chain. If the focus chain is empty then
151 * the function returns 1, else the number returned will be FOLast + 1 where FOLast is the focus
152 * order of the very last control in the focus chain.
153 * @pre The FocusManager has been initialized.
154 * @return The focus order of the actor
156 unsigned int GenerateNewFocusOrder() const;
159 * Get the actor that has the specified focus order. It will return an empty handle if the
160 * actor is not in the stage or has a focus order of 0.
161 * @pre The FocusManager has been initialized.
162 * @param order The focus order of the actor
163 * @return The actor that has the specified focus order or an empty handle if no actor in the stage has the specified focus order.
165 Actor GetActorByFocusOrder(const unsigned int order);
168 * Move the focus to the specified actor. Only one actor can be focused at the same time.
169 * The actor must have a defined focus order and must be focusable, visible and in the stage.
170 * @pre The FocusManager has been initialized.
171 * @pre The Actor has been initialized.
172 * @param actor The actor to be focused
173 * @return Whether the focus is successful or not
175 bool SetCurrentFocusActor(Actor actor);
178 * Get the current focused actor.
179 * @pre The FocusManager has been initialized.
180 * @return A handle to the current focused actor or an empty handle if no actor is focused.
182 Actor GetCurrentFocusActor();
185 * Get the focus group of current focused actor.
186 * @pre The FocusManager has been initialized.
187 * @return A handle to the immediate parent of the current focused actor which is also a focus group,
188 * or an empty handle if no actor is focused.
190 Actor GetCurrentFocusGroup();
193 * Get the focus order of currently focused actor.
194 * @pre The FocusManager has been initialized.
195 * @return The focus order of the currently focused actor or 0 if no actor is in focus.
197 unsigned int GetCurrentFocusOrder();
200 * Move the focus to the next focusable actor in the focus chain (according to the focus
201 * traversal order). When the focus movement is wrapped around, the focus will be moved
202 * to the first focusable actor when it reaches the end of the focus chain.
203 * @pre The FocusManager has been initialized.
204 * @return true if the moving was successful
206 bool MoveFocusForward();
209 * Move the focus to the previous focusable actor in the focus chain (according to the
210 * focus traversal order). When the focus movement is wrapped around, the focus will be
211 * moved to the last focusable actor when it reaches the beginning of the focus chain.
212 * @pre The FocusManager has been initialized.
213 * @return true if the moving was successful
215 bool MoveFocusBackward();
218 * Clear the focus from the current focused actor if any, so that no actor is focused
219 * in the focus chain.
220 * It will emit focus changed signal without current focused actor
221 * @pre The FocusManager has been initialized.
226 * Clear the every registered focusable actor from focus-manager.
227 * @pre The FocusManager has been initialized.
232 * Set whether an actor is a focus group that can limit the scope of focus movement to
233 * its child actors in the focus chain.
234 * @pre The FocusManager has been initialized.
235 * @pre The Actor has been initialized.
236 * @param actor The actor to be set as a focus group.
237 * @param isFocusGroup Whether to set the actor to be a focus group or not.
239 void SetFocusGroup(Actor actor, bool isFocusGroup);
242 * Check whether the actor is set as a focus group or not.
243 * @pre The FocusManager has been initialized.
244 * @pre The Actor has been initialized.
245 * @param actor The actor to be checked.
246 * @return Whether the actor is set as a focus group.
248 bool IsFocusGroup(Actor actor) const;
251 * Set whether the group mode is enabled or not.
252 * When the group mode is enabled, the focus movement will be limited to the child actors
253 * of the current focus group including the current focus group itself. The current focus
254 * group is the closest ancestor of the current focused actor that set as a focus group.
255 * @pre The FocusManager has been initialized.
256 * @param enabled Whether the group mode is enabled or not
258 void SetGroupMode(bool enabled);
261 * Get whether the group mode is enabled or not.
262 * @pre The FocusManager has been initialized.
263 * @return Whether the group mode is enabled or not.
265 bool GetGroupMode() const;
268 * Set whether focus will be moved to the beginning of the focus chain when it reaches the
269 * end or vice versa. When both the wrap mode and the group mode are enabled, focus will be
270 * wrapped within the current focus group. Focus will not be wrapped in default.
271 * @pre The FocusManager has been initialized.
272 * @param wrapped Whether the focus movement is wrapped around or not
274 void SetWrapMode(bool wrapped);
277 * Get whether the wrap mode is enabled or not.
278 * @pre The FocusManager has been initialized.
279 * @return Whether the wrap mode is enabled or not.
281 bool GetWrapMode() const;
284 * Set the focus indicator actor. This will replace the default focus indicator actor
285 * in FocusManager and will be added to the focused actor as a highlight.
286 * @pre The FocusManager has been initialized.
287 * @pre The indicator actor has been initialized.
288 * @param indicator The indicator actor to be added
290 void SetFocusIndicatorActor(Actor indicator);
293 * Get the focus indicator actor.
294 * @pre The FocusManager has been initialized.
295 * @return A handle to the focus indicator actor
297 Actor GetFocusIndicatorActor();
300 * Returns the closest ancestor of the given actor that is a focus group.
301 * @param actor The actor to be checked for its focus group
302 * @return The focus group the given actor belongs to or an empty handle if the given actor doesn't belong to any focus group
304 Actor GetFocusGroup(Actor actor);
309 * This signal is emitted when the current focused actor is changed.
310 * A callback of the following type may be connected:
312 * void YourCallbackName(Actor originalFocusedActor, Actor currentFocusedActor);
314 * @pre The Object has been initialized.
315 * @return The signal to connect to.
317 FocusChangedSignalV2& FocusChangedSignal();
320 * This signal is emitted when there is no way to move focus further.
321 * A callback of the following type may be connected:
323 * void YourCallbackName(Actor currentFocusedActor, FocusOvershotDirection direction);
325 * @pre The Object has been initialized.
326 * @return The signal to connect to.
328 FocusOvershotSignalV2& FocusOvershotSignal();
331 * This signal is emitted when the current focused actor is activated.
332 * A callback of the following type may be connected:
334 * void YourCallbackName(Actor activatedActor);
336 * @pre The Object has been initialized.
337 * @return The signal to connect to.
339 FocusedActorActivatedSignalV2& FocusedActorActivatedSignal();
343 FocusManager(Internal::FocusManager *impl);
345 }; // class FocusManager
347 } // namespace Toolkit
354 #endif // __DALI_TOOLKIT_FOCUS_MANAGER_H__