1 #ifndef DALI_TOOLKIT_KEYBOARD_FOCUS_MANAGER_H
2 #define DALI_TOOLKIT_KEYBOARD_FOCUS_MANAGER_H
5 * Copyright (c) 2020 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>
28 namespace Internal DALI_INTERNAL
30 class KeyboardFocusManager;
33 * @addtogroup dali_toolkit_managers
38 * @brief Provides the functionality of handling keyboard navigation
39 * and maintaining the two dimensional keyboard focus chain.
41 * It provides functionality of setting the focus and moving the focus
42 * in four directions (i.e. Left, Right, Up and Down). It also draws a
43 * highlight for the focused actor and emits a signal when the focus
47 * | %Signal Name | Method |
48 * |------------------------------|------------------------------------|
49 * | keyboardPreFocusChange | @ref PreFocusChangeSignal() |
50 * | keyboardFocusChanged | @ref FocusChangedSignal() |
51 * | keyboardFocusGroupChanged | @ref FocusGroupChangedSignal() |
52 * | keyboardFocusedActorEnterKey | @ref FocusedActorEnterKeySignal() |
55 class DALI_TOOLKIT_API KeyboardFocusManager : public BaseHandle
58 /// @brief Pre focus change signal
59 typedef Signal<Actor(Actor, Actor, Control::KeyboardFocus::Direction)> PreFocusChangeSignalType;
61 /// @brief Focus changed signal
62 typedef Signal<void(Actor, Actor)> FocusChangedSignalType;
64 /// @brief Focus group changed signal
65 typedef Signal<void(Actor, bool)> FocusGroupChangedSignalType;
67 /// @brief Focused actor has the enter key pressed signal
68 typedef Signal<void(Actor)> FocusedActorEnterKeySignalType;
71 * @brief Creates a KeyboardFocusManager handle; this can be initialized with KeyboardFocusManager::New().
73 * Calling member functions with an uninitialized handle is not allowed.
76 KeyboardFocusManager();
81 * This is non-virtual since derived Handle types must not contain data or virtual methods.
84 ~KeyboardFocusManager();
87 * @brief Gets the singleton of KeyboardFocusManager object.
90 * @return A handle to the KeyboardFocusManager control
92 static KeyboardFocusManager Get();
95 * @brief Moves the keyboard focus to the given actor.
97 * Only one actor can be focused at the same time. The actor must
98 * be in the stage already and keyboard focusable.
101 * @param actor The actor to be focused
102 * @return Whether the focus is successful or not
103 * @pre The KeyboardFocusManager has been initialized.
104 * @pre The Actor has been initialized.
105 * @note If the parent of this actor has the KEYBOARD FOCUSABLE CHILDREN property set to false, it will not be focused.
107 bool SetCurrentFocusActor(Actor actor);
110 * @brief Gets the current focused actor.
113 * @return A handle to the current focused actor or an empty handle if no actor is focused
114 * @pre The KeyboardFocusManager has been initialized.
116 Actor GetCurrentFocusActor();
119 * @brief Moves the focus to the next focusable actor in the focus
120 * chain in the given direction (according to the focus traversal
124 * @param direction The direction of focus movement
125 * @return true if the movement was successful
126 * @pre The KeyboardFocusManager has been initialized.
128 bool MoveFocus(Control::KeyboardFocus::Direction direction);
131 * @brief Clears the focus from the current focused actor if any, so
132 * that no actor is focused in the focus chain.
134 * It will emit focus changed signal without current focused actor.
136 * @pre The KeyboardFocusManager has been initialized.
141 * @brief Sets whether the focus movement should be looped within the same focus group.
143 * The focus movement is not looped by default.
145 * @param enabled Whether the focus movement should be looped
146 * @pre The KeyboardFocusManager has been initialized.
148 void SetFocusGroupLoop(bool enabled);
151 * @brief Gets whether the focus movement should be looped within the same focus group.
154 * @return Whether the focus movement should be looped
155 * @pre The KeyboardFocusManager has been initialized.
157 bool GetFocusGroupLoop() const;
160 * @brief Sets whether an actor is a focus group that can limit the
161 * scope of focus movement to its child actors in the focus chain.
163 * Layout controls set themselves as focus groups by default.
166 * @param actor The actor to be set as a focus group
167 * @param isFocusGroup Whether to set the actor as a focus group or not
168 * @pre The KeyboardFocusManager has been initialized.
169 * @pre The Actor has been initialized.
171 void SetAsFocusGroup(Actor actor, bool isFocusGroup);
174 * @brief Checks whether the actor is set as a focus group or not.
177 * @param actor The actor to be checked
178 * @return Whether the actor is set as a focus group
179 * @pre The KeyboardFocusManager has been initialized.
180 * @pre The Actor has been initialized.
182 bool IsFocusGroup(Actor actor) const;
185 * @brief Returns the closest ancestor of the given actor that is a focus group.
188 * @param actor The actor to be checked for its focus group
189 * @return The focus group the given actor belongs to or an empty handle if the given actor
190 * doesn't belong to any focus group
192 Actor GetFocusGroup(Actor actor);
195 * @brief Sets the focus indicator actor.
197 * This will replace the default focus indicator actor in
198 * KeyboardFocusManager and will be added to the focused actor as a
202 * @param indicator The indicator actor to be added
203 * @pre The KeyboardFocusManager has been initialized.
204 * @pre The indicator actor has been initialized.
206 void SetFocusIndicatorActor(Actor indicator);
209 * @brief Gets the focus indicator actor.
212 * @return A handle to the focus indicator actor
213 * @pre The KeyboardFocusManager has been initialized.
215 Actor GetFocusIndicatorActor();
218 * @brief Move the focus to prev focused actor
222 void MoveFocusBackward();
226 * @brief This signal is emitted before the focus is going to be changed.
228 * KeyboardFocusManager makes the best guess for which actor to
229 * focus towards the given direction, but applications might want to
230 * change that. By connecting with this signal, they can check the
231 * proposed actor to focus and return a different actor if they
232 * wish. This signal is only emitted when the navigation key is
233 * pressed and KeyboardFocusManager tries to move the focus
234 * automatically. It won't be emitted for focus movement by calling
235 * SetCurrentFocusActor directly.
237 * A callback of the following type may be connected:
239 * Actor YourCallbackName(Actor currentFocusedActor, Actor proposedActorToFocus, Control::KeyboardFocus::Direction direction);
242 * @return The signal to connect to
243 * @pre The Object has been initialized.
245 PreFocusChangeSignalType& PreFocusChangeSignal();
248 * @brief This signal is emitted after the current focused actor has been changed.
250 * A callback of the following type may be connected:
252 * void YourCallbackName(Actor originalFocusedActor, Actor currentFocusedActor);
255 * @return The signal to connect to
256 * @pre The Object has been initialized.
258 FocusChangedSignalType& FocusChangedSignal();
261 * @brief This signal is emitted when the focus group has been changed.
263 * If the current focus group has a parent layout control,
264 * KeyboardFocusManager will make the best guess for the next focus
265 * group to move the focus to in the given direction (forward or
266 * backward). If not, the application has to set the new focus.
268 * A callback of the following type may be connected:
270 * void YourCallbackName(Actor currentFocusedActor, bool forward);
273 * @return The signal to connect to
274 * @pre The Object has been initialized.
276 FocusGroupChangedSignalType& FocusGroupChangedSignal();
279 * @brief This signal is emitted when the current focused actor has the enter key pressed on it.
281 * A callback of the following type may be connected:
283 * void YourCallbackName(Actor enterPressedActor);
286 * @return The signal to connect to
287 * @pre The Object has been initialized.
289 FocusedActorEnterKeySignalType& FocusedActorEnterKeySignal();
291 // Not intended for application developers
295 * @brief Creates a new handle from the implementation.
298 * @param[in] impl A pointer to the object
300 explicit DALI_INTERNAL KeyboardFocusManager(Internal::KeyboardFocusManager* impl);
303 }; // class KeyboardFocusManager
308 } // namespace Toolkit
312 #endif // DALI_TOOLKIT_KEYBOARD_FOCUS_MANAGER_H