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_TOOLKIT_FOCUS_MANAGER_MODULE
26 #include <dali/dali.h>
28 namespace Dali DALI_IMPORT_API
34 namespace Internal DALI_INTERNAL
40 * @brief Manages registration of actors in a focus chain and changing the focused
41 * actor within that chain.
43 * This class provides the functionality of registering the focus order and description
44 * of actors and maintaining the focus chain.
46 * It provides functionality of setting the
47 * focus and moving the focus forward and backward. It also draws a highlight for the
48 * focused actor and emits a signal when the focus is changed.
51 class FocusManager : public BaseHandle
55 static const char* const SIGNAL_FOCUS_CHANGED; ///< name "focus-changed"
56 static const char* const SIGNAL_FOCUS_OVERSHOT; ///< name "focus-overshot"
57 static const char* const SIGNAL_FOCUSED_ACTOR_ACTIVATED; ///< name "focused-actor-activated"
60 * @brief Accessibility needs four information which will be read by screen-reader.
62 * Reading order : Label -> Trait -> Optional (Value and Hint)
64 enum AccessibilityAttribute
66 ACCESSIBILITY_LABEL = 0, ///< Simple text which contained in ui-control
67 ACCESSIBILITY_TRAIT, ///< Description of ui-control trait
68 ACCESSIBILITY_VALUE, ///< Current value of ui-control (Optional)
69 ACCESSIBILITY_HINT, ///< Hint for action (Optional)
70 ACCESSIBILITY_ATTRIBUTE_NUM ///< Number of attributes
74 * @brief Overshoot direction.
76 enum FocusOvershotDirection
78 OVERSHOT_PREVIOUS = -1, ///< Try to move previous of the first actor
79 OVERSHOT_NEXT = 1, ///< Try to move next of the last actor
84 /// @brief Focus changed signal
85 typedef SignalV2< void ( Actor, Actor ) > FocusChangedSignalV2;
87 /// @brief Focus overshooted signal
88 typedef SignalV2< void ( Actor, FocusOvershotDirection ) > FocusOvershotSignalV2;
90 /// @brief Focused actor activated signal
91 typedef SignalV2< void ( Actor ) > FocusedActorActivatedSignalV2;
94 * @brief Create a FocusManager handle; this can be initialised with FocusManager::New().
96 * Calling member functions with an uninitialised handle is not allowed.
101 * @brief Virtual destructor.
103 virtual ~FocusManager();
106 * @brief Get the singleton of FocusManager object.
108 * @return A handle to the FocusManager control.
110 static FocusManager Get();
113 * @brief Set the information of the specified actor's accessibility attribute.
115 * @pre The FocusManager has been initialized.
116 * @pre The Actor has been initialized.
117 * @param actor The actor the text to be set with
118 * @param type The attribute type the text to be set with
119 * @param text The text for the actor's accessibility information
121 void SetAccessibilityAttribute(Actor actor, AccessibilityAttribute type, const std::string& text);
124 * @brief Get the text of the specified actor's accessibility attribute.
126 * @pre The FocusManager has been initialized.
127 * @pre The Actor has been initialized.
128 * @param actor The actor to be queried
129 * @param type The attribute type to be queried
130 * @return The text of the actor's accessibility information
132 std::string GetAccessibilityAttribute(Actor actor, AccessibilityAttribute type) const;
135 * @brief Set the focus order of the actor.
137 * The focus order of each actor in the focus chain is unique. If
138 * there is another actor assigned with the same focus order
139 * already, the new actor will be inserted to the focus chain with
140 * that focus order, and the focus order of the original actor and
141 * all the actors followed in the focus chain will be increased
142 * accordingly. If the focus order assigned to the actor is 0, it
143 * means that actor's focus order is undefined (e.g. the actor has a
144 * description but with no focus order being set yet) and therefore
145 * that actor is not focusable.
147 * @pre The FocusManager has been initialized.
148 * @pre The Actor has been initialized.
149 * @param actor The actor the focus order to be set with
150 * @param order The focus order of the actor
152 void SetFocusOrder(Actor actor, const unsigned int order);
155 * @brief Get the focus order of the actor.
157 * When the focus order is 0, it means the focus order of the actor
160 * @pre The FocusManager has been initialized.
161 * @pre The Actor has been initialized.
162 * @param actor The actor to be queried
163 * @return The focus order of the actor
165 unsigned int GetFocusOrder(Actor actor) const;
168 * @brief Generates a new focus order number which can be used to
169 * assign to actors which need to be appended to the end of the
170 * current focus order chain.
172 * The new number will be an increment over the very last focus
173 * order number in the focus chain. If the focus chain is empty then
174 * the function returns 1, else the number returned will be FOLast +
175 * 1 where FOLast is the focus order of the very last control in the
178 * @pre The FocusManager has been initialized.
179 * @return The focus order of the actor
181 unsigned int GenerateNewFocusOrder() const;
184 * @brief Get the actor that has the specified focus order.
186 * It will return an empty handle if the actor is not in the stage
187 * or has a focus order of 0.
189 * @pre The FocusManager has been initialized.
190 * @param order The focus order of the actor
192 * @return The actor that has the specified focus order or an empty
193 * handle if no actor in the stage has the specified focus order.
195 Actor GetActorByFocusOrder(const unsigned int order);
198 * @brief Move the focus to the specified actor.
200 * Only one actor can be focused at the same time. The actor must
201 * have a defined focus order and must be focusable, visible and in
204 * @pre The FocusManager has been initialized.
205 * @pre The Actor has been initialized.
206 * @param actor The actor to be focused
207 * @return Whether the focus is successful or not
209 bool SetCurrentFocusActor(Actor actor);
212 * @brief Get the current focused actor.
214 * @pre The FocusManager has been initialized.
215 * @return A handle to the current focused actor or an empty handle if no actor is focused.
217 Actor GetCurrentFocusActor();
220 * @brief Get the focus group of current focused actor.
222 * @pre The FocusManager has been initialized.
224 * @return A handle to the immediate parent of the current focused
225 * actor which is also a focus group, or an empty handle if no actor
228 Actor GetCurrentFocusGroup();
231 * @brief Get the focus order of currently focused actor.
232 * @pre The FocusManager has been initialized.
234 * @return The focus order of the currently focused actor or 0 if no
237 unsigned int GetCurrentFocusOrder();
240 * @brief Move the focus to the next focusable actor in the focus
241 * chain (according to the focus traversal order).
243 * When the focus movement is wrapped around, the focus will be moved
244 * to the first focusable actor when it reaches the end of the focus chain.
246 * @pre The FocusManager has been initialized.
247 * @return true if the moving was successful
249 bool MoveFocusForward();
252 * @brief Move the focus to the previous focusable actor in the
253 * focus chain (according to the focus traversal order).
255 * When the focus movement is wrapped around, the focus will be
256 * moved to the last focusable actor when it reaches the beginning
257 * of the focus chain.
259 * @pre The FocusManager has been initialized.
260 * @return true if the moving was successful
262 bool MoveFocusBackward();
265 * @brief Clear the focus from the current focused actor if any, so
266 * that no actor is focused in the focus chain.
268 * It will emit focus changed signal without current focused actor
269 * @pre The FocusManager has been initialized.
274 * @brief Clear the every registered focusable actor from focus-manager.
275 * @pre The FocusManager has been initialized.
280 * @brief Set whether an actor is a focus group that can limit the
281 * scope of focus movement to its child actors in the focus chain.
283 * @pre The FocusManager has been initialized.
284 * @pre The Actor has been initialized.
285 * @param actor The actor to be set as a focus group.
286 * @param isFocusGroup Whether to set the actor to be a focus group or not.
288 void SetFocusGroup(Actor actor, bool isFocusGroup);
291 * @brief Check whether the actor is set as a focus group or not.
293 * @pre The FocusManager has been initialized.
294 * @pre The Actor has been initialized.
295 * @param actor The actor to be checked.
296 * @return Whether the actor is set as a focus group.
298 bool IsFocusGroup(Actor actor) const;
301 * @brief Set whether the group mode is enabled or not.
303 * When the group mode is enabled, the focus movement will be limited to the child actors
304 * of the current focus group including the current focus group itself. The current focus
305 * group is the closest ancestor of the current focused actor that set as a focus group.
306 * @pre The FocusManager has been initialized.
307 * @param enabled Whether the group mode is enabled or not
309 void SetGroupMode(bool enabled);
312 * @brief Get whether the group mode is enabled or not.
314 * @pre The FocusManager has been initialized.
315 * @return Whether the group mode is enabled or not.
317 bool GetGroupMode() const;
320 * @brief Set whether focus will be moved to the beginning of the
321 * focus chain when it reaches the end or vice versa.
323 * When both the wrap mode and the group mode are enabled, focus will be
324 * wrapped within the current focus group. Focus will not be wrapped in default.
325 * @pre The FocusManager has been initialized.
326 * @param wrapped Whether the focus movement is wrapped around or not
328 void SetWrapMode(bool wrapped);
331 * @brief Get whether the wrap mode is enabled or not.
333 * @pre The FocusManager has been initialized.
334 * @return Whether the wrap mode is enabled or not.
336 bool GetWrapMode() const;
339 * @brief Set whether focus manager will play a feedback when the focus leaves the end or vice versa.
341 * If wrap mode is enabled, the feedback will be played once. In next time, focus will move continueously.
342 * Otherwise, feedback will be played with overshot signal
344 * @pre The FocusManager has been initialized.
345 * @param enabled Whether the endcap feedback is enabled or not
347 void SetEndCapFeedbackEnabled(bool enabled);
350 * @brief Get whether the endcap feedback is enabled or not.
352 * @pre The FocusManager has been initialized.
353 * @return Whether the endcap feedback is enabled or not.
355 bool GetEndCapFeedbackEnabled() const;
358 * @brief Set the focus indicator actor.
360 * This will replace the default focus indicator actor in
361 * FocusManager and will be added to the focused actor as a
364 * @pre The FocusManager has been initialized.
365 * @pre The indicator actor has been initialized.
366 * @param indicator The indicator actor to be added
368 void SetFocusIndicatorActor(Actor indicator);
371 * @brief Get the focus indicator actor.
373 * @pre The FocusManager has been initialized.
374 * @return A handle to the focus indicator actor
376 Actor GetFocusIndicatorActor();
379 * @brief Returns the closest ancestor of the given actor that is a focus group.
381 * @param actor The actor to be checked for its focus group
382 * @return The focus group the given actor belongs to or an empty handle if the given actor doesn't belong to any focus group
384 Actor GetFocusGroup(Actor actor);
389 * @brief This signal is emitted when the current focused actor is changed.
391 * A callback of the following type may be connected:
393 * void YourCallbackName(Actor originalFocusedActor, Actor currentFocusedActor);
395 * @pre The Object has been initialized.
396 * @return The signal to connect to.
398 FocusChangedSignalV2& FocusChangedSignal();
401 * @brief This signal is emitted when there is no way to move focus further.
403 * A callback of the following type may be connected:
405 * void YourCallbackName(Actor currentFocusedActor, FocusOvershotDirection direction);
407 * @pre The Object has been initialized.
408 * @return The signal to connect to.
410 FocusOvershotSignalV2& FocusOvershotSignal();
413 * @brief This signal is emitted when the current focused actor is activated.
415 * A callback of the following type may be connected:
417 * void YourCallbackName(Actor activatedActor);
419 * @pre The Object has been initialized.
420 * @return The signal to connect to.
422 FocusedActorActivatedSignalV2& FocusedActorActivatedSignal();
426 FocusManager(Internal::FocusManager *impl);
428 }; // class FocusManager
430 } // namespace Toolkit
437 #endif // __DALI_TOOLKIT_FOCUS_MANAGER_H__