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 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 #include <dali/dali.h>
23 #include <dali-toolkit/public-api/controls/control.h>
25 namespace Dali DALI_IMPORT_API
31 namespace Internal DALI_INTERNAL
33 class KeyboardFocusManager;
37 * @brief Provides the functionality of handling keyboard navigation
38 * and maintaining the two dimensional keyboard focus chain.
40 * It provides functionality of setting the focus and moving the focus
41 * in four directions (i.e. Left, Right, Up and Down). It also draws a
42 * highlight for the focused actor and emits a signal when the focus
45 class KeyboardFocusManager : public BaseHandle
49 static const char* const SIGNAL_PRE_FOCUS_CHANGE; ///< name "keyboard-pre-focus-change"
50 static const char* const SIGNAL_FOCUS_CHANGED; ///< name "keyboard-focus-changed"
51 static const char* const SIGNAL_FOCUS_GROUP_CHANGED; ///< name "keyboard-focus-group-changed"
52 static const char* const SIGNAL_FOCUSED_ACTOR_ACTIVATED; ///< name "keyboard-focused-actor-activated"
56 /// @brief Pre focus change signal
57 typedef SignalV2< Actor ( Actor, Actor, Control::KeyboardFocusNavigationDirection ) > PreFocusChangeSignalV2;
59 /// @brief Focus changed signal
60 typedef SignalV2< void ( Actor, Actor ) > FocusChangedSignalV2;
62 /// @brief Focus group changed signal
63 typedef SignalV2< void ( Actor, bool ) > FocusGroupChangedSignalV2;
65 /// @brief Focused actor activated signal
66 typedef SignalV2< void ( Actor ) > FocusedActorActivatedSignalV2;
69 * @brief Create a KeyboardFocusManager handle; this can be initialised with KeyboardFocusManager::New().
71 * Calling member functions with an uninitialised handle is not allowed.
73 KeyboardFocusManager();
78 * This is non-virtual since derived Handle types must not contain data or virtual methods.
80 ~KeyboardFocusManager();
83 * @brief Get the singleton of KeyboardFocusManager object.
85 * @return A handle to the KeyboardFocusManager control.
87 static KeyboardFocusManager Get();
90 * @brief Move the keyboard focus to the given actor.
92 * Only one actor can be focused at the same time. The actor must
93 * be in the stage already and keyboard focusable.
95 * @pre The KeyboardFocusManager has been initialized.
96 * @pre The Actor has been initialized.
97 * @param actor The actor to be focused
98 * @return Whether the focus is successful or not
100 bool SetCurrentFocusActor(Actor actor);
103 * @brief Get the current focused actor.
105 * @pre The KeyboardFocusManager has been initialized.
106 * @return A handle to the current focused actor or an empty handle if no actor is focused.
108 Actor GetCurrentFocusActor();
111 * @brief Move the focus to the next focusable actor in the focus
112 * chain in the given direction (according to the focus traversal
115 * @pre The KeyboardFocusManager has been initialized.
116 * @param direction The direction of focus movement
117 * @return true if the movement was successful
119 bool MoveFocus(Control::KeyboardFocusNavigationDirection direction);
122 * @brief Clear the focus from the current focused actor if any, so
123 * that no actor is focused in the focus chain.
125 * It will emit focus changed signal without current focused actor
126 * @pre The KeyboardFocusManager has been initialized.
131 * @brief Set whether the focus movement should be looped within the same focus group.
133 * The focus movement is not looped by default.
134 * @pre The KeyboardFocusManager has been initialized.
135 * @param enabled Whether the focus movement should be looped
137 void SetFocusGroupLoop(bool enabled);
140 * @brief Get whether the focus movement should be looped within the same focus group.
142 * @pre The KeyboardFocusManager has been initialized.
143 * @return Whether the focus movement should be looped
145 bool GetFocusGroupLoop() const;
148 * @brief Set whether an actor is a focus group that can limit the
149 * scope of focus movement to its child actors in the focus chain.
151 * Layout controls set themselves as focus groups by default.
153 * @pre The KeyboardFocusManager has been initialized.
154 * @pre The Actor has been initialized.
155 * @param actor The actor to be set as a focus group.
156 * @param isFocusGroup Whether to set the actor as a focus group or not.
158 void SetAsFocusGroup(Actor actor, bool isFocusGroup);
161 * @brief Check whether the actor is set as a focus group or not.
163 * @pre The KeyboardFocusManager has been initialized.
164 * @pre The Actor has been initialized.
165 * @param actor The actor to be checked.
166 * @return Whether the actor is set as a focus group.
168 bool IsFocusGroup(Actor actor) const;
171 * @brief Returns the closest ancestor of the given actor that is a focus group.
173 * @param actor The actor to be checked for its focus group
174 * @return The focus group the given actor belongs to or an empty handle if the given actor
175 * doesn't belong to any focus group
177 Actor GetFocusGroup(Actor actor);
180 * @brief Set the focus indicator actor.
182 * This will replace the default focus indicator actor in
183 * KeyboardFocusManager and will be added to the focused actor as a
186 * @pre The KeyboardFocusManager has been initialized.
187 * @pre The indicator actor has been initialized.
188 * @param indicator The indicator actor to be added
190 void SetFocusIndicatorActor(Actor indicator);
193 * @brief Get the focus indicator actor.
195 * @pre The KeyboardFocusManager has been initialized.
196 * @return A handle to the focus indicator actor
198 Actor GetFocusIndicatorActor();
203 * @brief This signal is emitted before the focus is going to be changed.
205 * KeyboardFocusManager makes the best guess for which actor to
206 * focus towards the given direction, but applications might want to
207 * change that. By connecting with this signal, they can check the
208 * proposed actor to focus and return a different actor if they
209 * wish. This signal is only emitted when the navigation key is
210 * pressed and KeyboardFocusManager tries to move the focus
211 * automatically. It won't be emitted for focus movement by calling
212 * SetCurrentFocusActor directly.
214 * A callback of the following type may be connected:
216 * Actor YourCallbackName(Actor currentFocusedActor, Actor proposedActorToFocus, Control::KeyboardFocusNavigationDirection direction);
218 * @pre The Object has been initialized.
219 * @return The signal to connect to.
221 PreFocusChangeSignalV2& PreFocusChangeSignal();
224 * @brief This signal is emitted after the current focused actor has been changed.
226 * A callback of the following type may be connected:
228 * void YourCallbackName(Actor originalFocusedActor, Actor currentFocusedActor);
230 * @pre The Object has been initialized.
231 * @return The signal to connect to.
233 FocusChangedSignalV2& FocusChangedSignal();
236 * @brief This signal is emitted when the focus group has been changed.
238 * If the current focus group has a parent layout control,
239 * KeyboardFocusManager will make the best guess for the next focus
240 * group to move the focus to in the given direction (forward or
241 * backward). If not, the application has to set the new focus.
243 * A callback of the following type may be connected:
245 * void YourCallbackName(Actor currentFocusedActor, bool forward);
247 * @pre The Object has been initialized.
248 * @return The signal to connect to.
250 FocusGroupChangedSignalV2& FocusGroupChangedSignal();
253 * @brief This signal is emitted when the current focused actor is activated.
255 * A callback of the following type may be connected:
257 * void YourCallbackName(Actor activatedActor);
259 * @pre The Object has been initialized.
260 * @return The signal to connect to.
262 FocusedActorActivatedSignalV2& FocusedActorActivatedSignal();
264 // Not intended for application developers
267 * @brief Creates a new handle from the implementation.
269 * @param[in] impl A pointer to the object.
271 explicit DALI_INTERNAL KeyboardFocusManager(Internal::KeyboardFocusManager *impl);
273 }; // class KeyboardFocusManager
275 } // namespace Toolkit
279 #endif // __DALI_TOOLKIT_KEYBOARD_FOCUS_MANAGER_H__