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 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 * @addtogroup CAPI_DALI_TOOLKIT_FOCUS_MANAGER_MODULE
27 #include <dali/dali.h>
29 namespace Dali DALI_IMPORT_API
35 namespace Internal DALI_INTERNAL
41 * @brief Manages registration of actors in a focus chain and changing the focused
42 * 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 class FocusManager : public BaseHandle
56 static const char* const SIGNAL_FOCUS_CHANGED; ///< name "focus-changed"
57 static const char* const SIGNAL_FOCUS_OVERSHOT; ///< name "focus-overshot"
58 static const char* const SIGNAL_FOCUSED_ACTOR_ACTIVATED; ///< name "focused-actor-activated"
61 * @brief Accessibility needs four information which will be read by screen-reader.
63 * Reading order : Label -> Trait -> Optional (Value and Hint)
65 enum AccessibilityAttribute
67 ACCESSIBILITY_LABEL = 0, ///< Simple text which contained in ui-control
68 ACCESSIBILITY_TRAIT, ///< Description of ui-control trait
69 ACCESSIBILITY_VALUE, ///< Current value of ui-control (Optional)
70 ACCESSIBILITY_HINT, ///< Hint for action (Optional)
71 ACCESSIBILITY_ATTRIBUTE_NUM ///< Number of attributes
75 * @brief Overshoot direction.
77 enum FocusOvershotDirection
79 OVERSHOT_PREVIOUS = -1, ///< Try to move previous of the first actor
80 OVERSHOT_NEXT = 1, ///< Try to move next of the last actor
85 /// @brief Focus changed signal
86 typedef SignalV2< void ( Actor, Actor ) > FocusChangedSignalV2;
88 /// @brief Focus overshooted signal
89 typedef SignalV2< void ( Actor, FocusOvershotDirection ) > FocusOvershotSignalV2;
91 /// @brief Focused actor activated signal
92 typedef SignalV2< void ( Actor ) > FocusedActorActivatedSignalV2;
95 * @brief Create a FocusManager handle; this can be initialised with FocusManager::New().
97 * Calling member functions with an uninitialised handle is not allowed.
104 * This is non-virtual since derived Handle types must not contain data or virtual methods.
109 * @brief Get the singleton of FocusManager object.
111 * @return A handle to the FocusManager control.
113 static FocusManager Get();
116 * @brief Set the information 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 the text to be set with
121 * @param type The attribute type the text to be set with
122 * @param text The text for the actor's accessibility information
124 void SetAccessibilityAttribute(Actor actor, AccessibilityAttribute type, const std::string& text);
127 * @brief Get the text of the specified actor's accessibility attribute.
129 * @pre The FocusManager has been initialized.
130 * @pre The Actor has been initialized.
131 * @param actor The actor to be queried
132 * @param type The attribute type to be queried
133 * @return The text of the actor's accessibility information
135 std::string GetAccessibilityAttribute(Actor actor, AccessibilityAttribute type) const;
138 * @brief Set the focus order of the actor.
140 * The focus order of each actor in the focus chain is unique. If
141 * there is another actor assigned with the same focus order
142 * already, the new actor will be inserted to the focus chain with
143 * that focus order, and the focus order of the original actor and
144 * all the actors followed in the focus chain will be increased
145 * accordingly. If the focus order assigned to the actor is 0, it
146 * means that actor's focus order is undefined (e.g. the actor has a
147 * description but with no focus order being set yet) and therefore
148 * that actor is not focusable.
150 * @pre The FocusManager has been initialized.
151 * @pre The Actor has been initialized.
152 * @param actor The actor the focus order to be set with
153 * @param order The focus order of the actor
155 void SetFocusOrder(Actor actor, const unsigned int order);
158 * @brief Get the focus order of the actor.
160 * When the focus order is 0, it means the focus order of the actor
163 * @pre The FocusManager has been initialized.
164 * @pre The Actor has been initialized.
165 * @param actor The actor to be queried
166 * @return The focus order of the actor
168 unsigned int GetFocusOrder(Actor actor) const;
171 * @brief Generates a new focus order number which can be used to
172 * assign to actors which need to be appended to the end of the
173 * current focus order chain.
175 * The new number will be an increment over the very last focus
176 * order number in the focus chain. If the focus chain is empty then
177 * the function returns 1, else the number returned will be FOLast +
178 * 1 where FOLast is the focus order of the very last control in the
181 * @pre The FocusManager has been initialized.
182 * @return The focus order of the actor
184 unsigned int GenerateNewFocusOrder() const;
187 * @brief Get the actor that has the specified focus order.
189 * It will return an empty handle if the actor is not in the stage
190 * or has a focus order of 0.
192 * @pre The FocusManager has been initialized.
193 * @param order The focus order of the actor
195 * @return The actor that has the specified focus order or an empty
196 * handle if no actor in the stage has the specified focus order.
198 Actor GetActorByFocusOrder(const unsigned int order);
201 * @brief Move the focus to the specified actor.
203 * Only one actor can be focused at the same time. The actor must
204 * have a defined focus order and must be focusable, visible and in
207 * @pre The FocusManager has been initialized.
208 * @pre The Actor has been initialized.
209 * @param actor The actor to be focused
210 * @return Whether the focus is successful or not
212 bool SetCurrentFocusActor(Actor actor);
215 * @brief Get the current focused actor.
217 * @pre The FocusManager has been initialized.
218 * @return A handle to the current focused actor or an empty handle if no actor is focused.
220 Actor GetCurrentFocusActor();
223 * @brief Get the focus group of current focused actor.
225 * @pre The FocusManager has been initialized.
227 * @return A handle to the immediate parent of the current focused
228 * actor which is also a focus group, or an empty handle if no actor
231 Actor GetCurrentFocusGroup();
234 * @brief Get the focus order of currently focused actor.
235 * @pre The FocusManager has been initialized.
237 * @return The focus order of the currently focused actor or 0 if no
240 unsigned int GetCurrentFocusOrder();
243 * @brief Move the focus to the next focusable actor in the focus
244 * chain (according to the focus traversal order).
246 * When the focus movement is wrapped around, the focus will be moved
247 * to the first focusable actor when it reaches the end of the focus chain.
249 * @pre The FocusManager has been initialized.
250 * @return true if the moving was successful
252 bool MoveFocusForward();
255 * @brief Move the focus to the previous focusable actor in the
256 * focus chain (according to the focus traversal order).
258 * When the focus movement is wrapped around, the focus will be
259 * moved to the last focusable actor when it reaches the beginning
260 * of the focus chain.
262 * @pre The FocusManager has been initialized.
263 * @return true if the moving was successful
265 bool MoveFocusBackward();
268 * @brief Clear the focus from the current focused actor if any, so
269 * that no actor is focused in the focus chain.
271 * It will emit focus changed signal without current focused actor
272 * @pre The FocusManager has been initialized.
277 * @brief Clear the every registered focusable actor from focus-manager.
278 * @pre The FocusManager has been initialized.
283 * @brief Set whether an actor is a focus group that can limit the
284 * scope of focus movement to its child actors in the focus chain.
286 * @pre The FocusManager has been initialized.
287 * @pre The Actor has been initialized.
288 * @param actor The actor to be set as a focus group.
289 * @param isFocusGroup Whether to set the actor to be a focus group or not.
291 void SetFocusGroup(Actor actor, bool isFocusGroup);
294 * @brief Check whether the actor is set as a focus group or not.
296 * @pre The FocusManager has been initialized.
297 * @pre The Actor has been initialized.
298 * @param actor The actor to be checked.
299 * @return Whether the actor is set as a focus group.
301 bool IsFocusGroup(Actor actor) const;
304 * @brief Set whether the group mode is enabled or not.
306 * When the group mode is enabled, the focus movement will be limited to the child actors
307 * of the current focus group including the current focus group itself. The current focus
308 * group is the closest ancestor of the current focused actor that set as a focus group.
309 * @pre The FocusManager has been initialized.
310 * @param enabled Whether the group mode is enabled or not
312 void SetGroupMode(bool enabled);
315 * @brief Get whether the group mode is enabled or not.
317 * @pre The FocusManager has been initialized.
318 * @return Whether the group mode is enabled or not.
320 bool GetGroupMode() const;
323 * @brief Set whether focus will be moved to the beginning of the
324 * focus chain when it reaches the end or vice versa.
326 * When both the wrap mode and the group mode are enabled, focus will be
327 * wrapped within the current focus group. Focus will not be wrapped in default.
328 * @pre The FocusManager has been initialized.
329 * @param wrapped Whether the focus movement is wrapped around or not
331 void SetWrapMode(bool wrapped);
334 * @brief Get whether the wrap mode is enabled or not.
336 * @pre The FocusManager has been initialized.
337 * @return Whether the wrap mode is enabled or not.
339 bool GetWrapMode() const;
342 * @brief Set the focus indicator actor.
344 * This will replace the default focus indicator actor in
345 * FocusManager and will be added to the focused actor as a
348 * @pre The FocusManager has been initialized.
349 * @pre The indicator actor has been initialized.
350 * @param indicator The indicator actor to be added
352 void SetFocusIndicatorActor(Actor indicator);
355 * @brief Get the focus indicator actor.
357 * @pre The FocusManager has been initialized.
358 * @return A handle to the focus indicator actor
360 Actor GetFocusIndicatorActor();
363 * @brief Returns the closest ancestor of the given actor that is a focus group.
365 * @param actor The actor to be checked for its focus group
366 * @return The focus group the given actor belongs to or an empty handle if the given actor doesn't belong to any focus group
368 Actor GetFocusGroup(Actor actor);
373 * @brief This signal is emitted when the current focused actor is changed.
375 * A callback of the following type may be connected:
377 * void YourCallbackName(Actor originalFocusedActor, Actor currentFocusedActor);
379 * @pre The Object has been initialized.
380 * @return The signal to connect to.
382 FocusChangedSignalV2& FocusChangedSignal();
385 * @brief This signal is emitted when there is no way to move focus further.
387 * A callback of the following type may be connected:
389 * void YourCallbackName(Actor currentFocusedActor, FocusOvershotDirection direction);
391 * @pre The Object has been initialized.
392 * @return The signal to connect to.
394 FocusOvershotSignalV2& FocusOvershotSignal();
397 * @brief This signal is emitted when the current focused actor is activated.
399 * A callback of the following type may be connected:
401 * void YourCallbackName(Actor activatedActor);
403 * @pre The Object has been initialized.
404 * @return The signal to connect to.
406 FocusedActorActivatedSignalV2& FocusedActorActivatedSignal();
410 FocusManager(Internal::FocusManager *impl);
412 }; // class FocusManager
414 } // namespace Toolkit
421 #endif // __DALI_TOOLKIT_FOCUS_MANAGER_H__