1 #ifndef __DALI_TOOLKIT_KEYBOARD_FOCUS_MANAGER_H__
2 #define __DALI_TOOLKIT_KEYBOARD_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>
27 #include <dali-toolkit/public-api/controls/control.h>
29 namespace Dali DALI_IMPORT_API
35 namespace Internal DALI_INTERNAL
37 class KeyboardFocusManager;
41 * @brief Provides the functionality of handling keyboard navigation
42 * and maintaining the two dimensional keyboard focus chain.
44 * It provides functionality of setting the focus and moving the focus
45 * in four directions (i.e. Left, Right, Up and Down). It also draws a
46 * highlight for the focused actor and emits a signal when the focus
49 class KeyboardFocusManager : public BaseHandle
53 static const char* const SIGNAL_PRE_FOCUS_CHANGE; ///< name "keyboard-pre-focus-change"
54 static const char* const SIGNAL_FOCUS_CHANGED; ///< name "keyboard-focus-changed"
55 static const char* const SIGNAL_FOCUS_GROUP_CHANGED; ///< name "keyboard-focus-group-changed"
56 static const char* const SIGNAL_FOCUSED_ACTOR_ACTIVATED; ///< name "keyboard-focused-actor-activated"
60 /// @brief Pre focus change signal
61 typedef SignalV2< Actor ( Actor, Actor, Control::KeyboardFocusNavigationDirection ) > PreFocusChangeSignalV2;
63 /// @brief Focus changed signal
64 typedef SignalV2< void ( Actor, Actor ) > FocusChangedSignalV2;
66 /// @brief Focus group changed signal
67 typedef SignalV2< void ( Actor, bool ) > FocusGroupChangedSignalV2;
69 /// @brief Focused actor activated signal
70 typedef SignalV2< void ( Actor ) > FocusedActorActivatedSignalV2;
73 * @brief Create a KeyboardFocusManager handle; this can be initialised with KeyboardFocusManager::New().
75 * Calling member functions with an uninitialised handle is not allowed.
77 KeyboardFocusManager();
80 * @brief Virtual destructor.
82 virtual ~KeyboardFocusManager();
85 * @brief Get the singleton of KeyboardFocusManager object.
87 * @return A handle to the KeyboardFocusManager control.
89 static KeyboardFocusManager Get();
92 * @brief Move the keyboard focus to the given actor.
94 * Only one actor can be focused at the same time. The actor must
95 * be in the stage already and keyboard focusable.
97 * @pre The KeyboardFocusManager has been initialized.
98 * @pre The Actor has been initialized.
99 * @param actor The actor to be focused
100 * @return Whether the focus is successful or not
102 bool SetCurrentFocusActor(Actor actor);
105 * @brief Get the current focused actor.
107 * @pre The KeyboardFocusManager has been initialized.
108 * @return A handle to the current focused actor or an empty handle if no actor is focused.
110 Actor GetCurrentFocusActor();
113 * @brief Move the focus to the next focusable actor in the focus
114 * chain in the given direction (according to the focus traversal
117 * @pre The KeyboardFocusManager has been initialized.
118 * @param direction The direction of focus movement
119 * @return true if the movement was successful
121 bool MoveFocus(Control::KeyboardFocusNavigationDirection direction);
124 * @brief Clear the focus from the current focused actor if any, so
125 * that no actor is focused in the focus chain.
127 * It will emit focus changed signal without current focused actor
128 * @pre The KeyboardFocusManager has been initialized.
133 * @brief Set whether the focus movement should be looped within the same focus group.
135 * The focus movement is not looped by default.
136 * @pre The KeyboardFocusManager has been initialized.
137 * @param enabled Whether the focus movement should be looped
139 void SetFocusGroupLoop(bool enabled);
142 * @brief Get whether the focus movement should be looped within the same focus group.
144 * @pre The KeyboardFocusManager has been initialized.
145 * @return Whether the focus movement should be looped
147 bool GetFocusGroupLoop() const;
150 * @brief Set whether an actor is a focus group that can limit the
151 * scope of focus movement to its child actors in the focus chain.
153 * Layout controls set themselves as focus groups by default.
155 * @pre The KeyboardFocusManager has been initialized.
156 * @pre The Actor has been initialized.
157 * @param actor The actor to be set as a focus group.
158 * @param isFocusGroup Whether to set the actor as a focus group or not.
160 void SetAsFocusGroup(Actor actor, bool isFocusGroup);
163 * @brief Check whether the actor is set as a focus group or not.
165 * @pre The KeyboardFocusManager has been initialized.
166 * @pre The Actor has been initialized.
167 * @param actor The actor to be checked.
168 * @return Whether the actor is set as a focus group.
170 bool IsFocusGroup(Actor actor) const;
173 * @brief Returns the closest ancestor of the given actor that is a focus group.
175 * @param actor The actor to be checked for its focus group
176 * @return The focus group the given actor belongs to or an empty handle if the given actor
177 * doesn't belong to any focus group
179 Actor GetFocusGroup(Actor actor);
182 * @brief Set the focus indicator actor.
184 * This will replace the default focus indicator actor in
185 * KeyboardFocusManager and will be added to the focused actor as a
188 * @pre The KeyboardFocusManager has been initialized.
189 * @pre The indicator actor has been initialized.
190 * @param indicator The indicator actor to be added
192 void SetFocusIndicatorActor(Actor indicator);
195 * @brief Get the focus indicator actor.
197 * @pre The KeyboardFocusManager has been initialized.
198 * @return A handle to the focus indicator actor
200 Actor GetFocusIndicatorActor();
205 * @brief This signal is emitted before the focus is going to be changed.
207 * KeyboardFocusManager makes the best guess for which actor to
208 * focus towards the given direction, but applications might want to
209 * change that. By connecting with this signal, they can check the
210 * proposed actor to focus and return a different actor if they
211 * wish. This signal is only emitted when the navigation key is
212 * pressed and KeyboardFocusManager tries to move the focus
213 * automatically. It won't be emitted for focus movement by calling
214 * SetCurrentFocusActor directly.
216 * A callback of the following type may be connected:
218 * Actor YourCallbackName(Actor currentFocusedActor, Actor proposedActorToFocus, Control::KeyboardFocusNavigationDirection direction);
220 * @pre The Object has been initialized.
221 * @return The signal to connect to.
223 PreFocusChangeSignalV2& PreFocusChangeSignal();
226 * @brief This signal is emitted after the current focused actor has been changed.
228 * A callback of the following type may be connected:
230 * void YourCallbackName(Actor originalFocusedActor, Actor currentFocusedActor);
232 * @pre The Object has been initialized.
233 * @return The signal to connect to.
235 FocusChangedSignalV2& FocusChangedSignal();
238 * @brief This signal is emitted when the focus group has been changed.
240 * If the current focus group has a parent layout control,
241 * KeyboardFocusManager will make the best guess for the next focus
242 * group to move the focus to in the given direction (forward or
243 * backward). If not, the application has to set the new focus.
245 * A callback of the following type may be connected:
247 * void YourCallbackName(Actor currentFocusedActor, bool forward);
249 * @pre The Object has been initialized.
250 * @return The signal to connect to.
252 FocusGroupChangedSignalV2& FocusGroupChangedSignal();
255 * @brief This signal is emitted when the current focused actor is activated.
257 * A callback of the following type may be connected:
259 * void YourCallbackName(Actor activatedActor);
261 * @pre The Object has been initialized.
262 * @return The signal to connect to.
264 FocusedActorActivatedSignalV2& FocusedActorActivatedSignal();
266 // Not intended for application developers
269 * @brief Creates a new handle from the implementation.
271 * @param[in] impl A pointer to the object.
273 explicit DALI_INTERNAL KeyboardFocusManager(Internal::KeyboardFocusManager *impl);
275 }; // class KeyboardFocusManager
277 } // namespace Toolkit
284 #endif // __DALI_TOOLKIT_KEYBOARD_FOCUS_MANAGER_H__