1 #ifndef __DALI_TOOLKIT_KEYBOARD_FOCUS_MANAGER_H__
2 #define __DALI_TOOLKIT_KEYBOARD_FOCUS_MANAGER_H__
5 * Copyright (c) 2015 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-toolkit/public-api/controls/control.h>
30 namespace Internal DALI_INTERNAL
32 class KeyboardFocusManager;
35 * @addtogroup dali_toolkit_managers
40 * @brief Provides the functionality of handling keyboard navigation
41 * and maintaining the two dimensional keyboard focus chain.
43 * It provides functionality of setting the focus and moving the focus
44 * in four directions (i.e. Left, Right, Up and Down). It also draws a
45 * highlight for the focused actor and emits a signal when the focus
49 * | %Signal Name | Method |
50 * |-------------------------------|------------------------------------|
51 * | keyboardPreFocusChange | @ref PreFocusChangeSignal() |
52 * | keyboardFocusChanged | @ref FocusChangedSignal() |
53 * | keyboardFocusGroupChanged | @ref FocusGroupChangedSignal() |
54 * | keyboardFocusedActorAenterKey | @ref FocusedActorEnterKeySignal() |
57 class DALI_IMPORT_API KeyboardFocusManager : public BaseHandle
62 /// @brief Pre focus change signal
63 typedef Signal< Actor ( Actor, Actor, Control::KeyboardFocus::Direction ) > PreFocusChangeSignalType;
65 /// @brief Focus changed signal
66 typedef Signal< void ( Actor, Actor ) > FocusChangedSignalType;
68 /// @brief Focus group changed signal
69 typedef Signal< void ( Actor, bool ) > FocusGroupChangedSignalType;
71 /// @brief Focused actor has the enter key pressed signal
72 typedef Signal< void ( Actor ) > FocusedActorEnterKeySignalType;
75 * @brief Create a KeyboardFocusManager handle; this can be initialised with KeyboardFocusManager::New().
77 * Calling member functions with an uninitialised handle is not allowed.
80 KeyboardFocusManager();
85 * This is non-virtual since derived Handle types must not contain data or virtual methods.
88 ~KeyboardFocusManager();
91 * @brief Get the singleton of KeyboardFocusManager object.
94 * @return A handle to the KeyboardFocusManager control.
96 static KeyboardFocusManager Get();
99 * @brief Move the keyboard focus to the given actor.
101 * Only one actor can be focused at the same time. The actor must
102 * be in the stage already and keyboard focusable.
105 * @param actor The actor to be focused
106 * @return Whether the focus is successful or not
107 * @pre The KeyboardFocusManager has been initialized.
108 * @pre The Actor has been initialized.
110 bool SetCurrentFocusActor(Actor actor);
113 * @brief Get the current focused actor.
116 * @return A handle to the current focused actor or an empty handle if no actor is focused.
117 * @pre The KeyboardFocusManager has been initialized.
119 Actor GetCurrentFocusActor();
122 * @brief Move the focus to the next focusable actor in the focus
123 * chain in the given direction (according to the focus traversal
127 * @param direction The direction of focus movement
128 * @return true if the movement was successful
129 * @pre The KeyboardFocusManager has been initialized.
131 bool MoveFocus(Control::KeyboardFocus::Direction direction);
134 * @brief Clear the focus from the current focused actor if any, so
135 * that no actor is focused in the focus chain.
137 * It will emit focus changed signal without current focused actor.
139 * @pre The KeyboardFocusManager has been initialized.
144 * @brief Set whether the focus movement should be looped within the same focus group.
146 * The focus movement is not looped by default.
148 * @param enabled Whether the focus movement should be looped
149 * @pre The KeyboardFocusManager has been initialized.
151 void SetFocusGroupLoop(bool enabled);
154 * @brief Get whether the focus movement should be looped within the same focus group.
157 * @return Whether the focus movement should be looped
158 * @pre The KeyboardFocusManager has been initialized.
160 bool GetFocusGroupLoop() const;
163 * @brief Set whether an actor is a focus group that can limit the
164 * scope of focus movement to its child actors in the focus chain.
166 * Layout controls set themselves as focus groups by default.
169 * @param actor The actor to be set as a focus group.
170 * @param isFocusGroup Whether to set the actor as a focus group or not.
171 * @pre The KeyboardFocusManager has been initialized.
172 * @pre The Actor has been initialized.
174 void SetAsFocusGroup(Actor actor, bool isFocusGroup);
177 * @brief Check whether the actor is set as a focus group or not.
180 * @param actor The actor to be checked.
181 * @return Whether the actor is set as a focus group.
182 * @pre The KeyboardFocusManager has been initialized.
183 * @pre The Actor has been initialized.
185 bool IsFocusGroup(Actor actor) const;
188 * @brief Returns the closest ancestor of the given actor that is a focus group.
191 * @param actor The actor to be checked for its focus group
192 * @return The focus group the given actor belongs to or an empty handle if the given actor
193 * doesn't belong to any focus group
195 Actor GetFocusGroup(Actor actor);
198 * @brief Set the focus indicator actor.
200 * This will replace the default focus indicator actor in
201 * KeyboardFocusManager and will be added to the focused actor as a
205 * @param indicator The indicator actor to be added
206 * @pre The KeyboardFocusManager has been initialized.
207 * @pre The indicator actor has been initialized.
209 void SetFocusIndicatorActor(Actor indicator);
212 * @brief Get the focus indicator actor.
215 * @return A handle to the focus indicator actor
216 * @pre The KeyboardFocusManager has been initialized.
218 Actor GetFocusIndicatorActor();
223 * @brief This signal is emitted before the focus is going to be changed.
225 * KeyboardFocusManager makes the best guess for which actor to
226 * focus towards the given direction, but applications might want to
227 * change that. By connecting with this signal, they can check the
228 * proposed actor to focus and return a different actor if they
229 * wish. This signal is only emitted when the navigation key is
230 * pressed and KeyboardFocusManager tries to move the focus
231 * automatically. It won't be emitted for focus movement by calling
232 * SetCurrentFocusActor directly.
234 * A callback of the following type may be connected:
236 * Actor YourCallbackName(Actor currentFocusedActor, Actor proposedActorToFocus, Control::KeyboardFocus::Direction direction);
239 * @return The signal to connect to.
240 * @pre The Object has been initialized.
242 PreFocusChangeSignalType& PreFocusChangeSignal();
245 * @brief This signal is emitted after the current focused actor has been changed.
247 * A callback of the following type may be connected:
249 * void YourCallbackName(Actor originalFocusedActor, Actor currentFocusedActor);
252 * @return The signal to connect to.
253 * @pre The Object has been initialized.
255 FocusChangedSignalType& FocusChangedSignal();
258 * @brief This signal is emitted when the focus group has been changed.
260 * If the current focus group has a parent layout control,
261 * KeyboardFocusManager will make the best guess for the next focus
262 * group to move the focus to in the given direction (forward or
263 * backward). If not, the application has to set the new focus.
265 * A callback of the following type may be connected:
267 * void YourCallbackName(Actor currentFocusedActor, bool forward);
270 * @return The signal to connect to.
271 * @pre The Object has been initialized.
273 FocusGroupChangedSignalType& FocusGroupChangedSignal();
276 * @brief This signal is emitted when the current focused actor has the enter key pressed on it.
278 * A callback of the following type may be connected:
280 * void YourCallbackName(Actor enterPressedActor);
283 * @return The signal to connect to.
284 * @pre The Object has been initialized.
286 FocusedActorEnterKeySignalType& FocusedActorEnterKeySignal();
288 // Not intended for application developers
291 * @brief Creates a new handle from the implementation.
294 * @param[in] impl A pointer to the object.
296 explicit DALI_INTERNAL KeyboardFocusManager(Internal::KeyboardFocusManager *impl);
298 }; // class KeyboardFocusManager
303 } // namespace Toolkit
307 #endif // __DALI_TOOLKIT_KEYBOARD_FOCUS_MANAGER_H__