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 #include <dali/dali.h>
22 #include <dali-toolkit/public-api/controls/control.h>
24 namespace Dali DALI_IMPORT_API
30 namespace Internal DALI_INTERNAL
32 class KeyboardFocusManager;
36 * KeyboardFocusManager
37 * This class provides the functionality of handling keyboard navigation and maintaining
38 * the two dimensional keyboard focus chain. It provides functionality of setting the
39 * focus and moving the focus in four directions (i.e. Left, Right, Up and Down). It also
40 * draws a highlight for the focused actor and emits a signal when the focus is changed.
43 class KeyboardFocusManager : public BaseHandle
47 static const char* const SIGNAL_PRE_FOCUS_CHANGE;
48 static const char* const SIGNAL_FOCUS_CHANGED;
49 static const char* const SIGNAL_FOCUS_GROUP_CHANGED;
50 static const char* const SIGNAL_FOCUSED_ACTOR_ACTIVATED;
54 //Pre focus change signal
55 typedef SignalV2< Actor ( Actor, Actor, Control::KeyboardFocusNavigationDirection ) > PreFocusChangeSignalV2;
57 //Focus changed signal
58 typedef SignalV2< void ( Actor, Actor ) > FocusChangedSignalV2;
60 //Focus group changed signal
61 typedef SignalV2< void ( Actor, bool ) > FocusGroupChangedSignalV2;
63 //Focused actor activated signal
64 typedef SignalV2< void ( Actor ) > FocusedActorActivatedSignalV2;
67 * Create a KeyboardFocusManager handle; this can be initialised with KeyboardFocusManager::New()
68 * Calling member functions with an uninitialised handle is not allowed.
70 KeyboardFocusManager();
75 virtual ~KeyboardFocusManager();
78 * Get the singleton of KeyboardFocusManager object.
79 * @return A handle to the KeyboardFocusManager control.
81 static KeyboardFocusManager Get();
84 * Move the keyboard focus to the given actor. Only one actor can be focused at the same time.
85 * The actor must be in the stage already and keyboard focusable.
86 * @pre The KeyboardFocusManager has been initialized.
87 * @pre The Actor has been initialized.
88 * @param actor The actor to be focused
89 * @return Whether the focus is successful or not
91 bool SetCurrentFocusActor(Actor actor);
94 * Get the current focused actor.
95 * @pre The KeyboardFocusManager has been initialized.
96 * @return A handle to the current focused actor or an empty handle if no actor is focused.
98 Actor GetCurrentFocusActor();
101 * Move the focus to the next focusable actor in the focus chain in the given direction
102 * (according to the focus traversal order).
103 * @pre The KeyboardFocusManager has been initialized.
104 * @param direction The direction of focus movement
105 * @return true if the movement was successful
107 bool MoveFocus(Control::KeyboardFocusNavigationDirection direction);
110 * Clear the focus from the current focused actor if any, so that no actor is focused
111 * in the focus chain.
112 * It will emit focus changed signal without current focused actor
113 * @pre The KeyboardFocusManager has been initialized.
118 * Set whether the focus movement should be looped within the same focus group.
119 * The focus movement is not looped by default.
120 * @pre The KeyboardFocusManager has been initialized.
121 * @param enabled Whether the focus movement should be looped
123 void SetFocusGroupLoop(bool enabled);
126 * Get whether the focus movement should be looped within the same focus group.
127 * @pre The KeyboardFocusManager has been initialized.
128 * @return Whether the focus movement should be looped
130 bool GetFocusGroupLoop() const;
133 * Set whether an actor is a focus group that can limit the scope of focus movement to
134 * its child actors in the focus chain. Layout controls set themselves as focus groups
136 * @pre The KeyboardFocusManager has been initialized.
137 * @pre The Actor has been initialized.
138 * @param actor The actor to be set as a focus group.
139 * @param isFocusGroup Whether to set the actor as a focus group or not.
141 void SetAsFocusGroup(Actor actor, bool isFocusGroup);
144 * Check whether the actor is set as a focus group or not.
145 * @pre The KeyboardFocusManager has been initialized.
146 * @pre The Actor has been initialized.
147 * @param actor The actor to be checked.
148 * @return Whether the actor is set as a focus group.
150 bool IsFocusGroup(Actor actor) const;
153 * Returns the closest ancestor of the given actor that is a focus group.
154 * @param actor The actor to be checked for its focus group
155 * @return The focus group the given actor belongs to or an empty handle if the given actor
156 * doesn't belong to any focus group
158 Actor GetFocusGroup(Actor actor);
161 * Set the focus indicator actor. This will replace the default focus indicator actor
162 * in KeyboardFocusManager and will be added to the focused actor as a highlight.
163 * @pre The KeyboardFocusManager has been initialized.
164 * @pre The indicator actor has been initialized.
165 * @param indicator The indicator actor to be added
167 void SetFocusIndicatorActor(Actor indicator);
170 * Get the focus indicator actor.
171 * @pre The KeyboardFocusManager has been initialized.
172 * @return A handle to the focus indicator actor
174 Actor GetFocusIndicatorActor();
179 * This signal is emitted before the focus is going to be changed.
180 * KeyboardFocusManager makes the best guess for which actor to focus towards the given direction,
181 * but applications might want to change that. By connecting with this signal, they can check the
182 * proposed actor to focus and return a different actor if they wish.
183 * This signal is only emitted when the navigation key is pressed and KeyboardFocusManager tries to
184 * move the focus automatically. It won't be emitted for focus movement by calling SetCurrentFocusActor
186 * A callback of the following type may be connected:
188 * Actor YourCallbackName(Actor currentFocusedActor, Actor proposedActorToFocus, Control::KeyboardFocusNavigationDirection direction);
190 * @pre The Object has been initialized.
191 * @return The signal to connect to.
193 PreFocusChangeSignalV2& PreFocusChangeSignal();
196 * This signal is emitted after the current focused actor has been changed.
197 * A callback of the following type may be connected:
199 * void YourCallbackName(Actor originalFocusedActor, Actor currentFocusedActor);
201 * @pre The Object has been initialized.
202 * @return The signal to connect to.
204 FocusChangedSignalV2& FocusChangedSignal();
207 * This signal is emitted when the focus group has been changed.
208 * If the current focus group has a parent layout control, KeyboardFocusManager will make the best guess
209 * for the next focus group to move the focus to in the given direction (forward or backward). If not,
210 * the application has to set the new focus.
211 * A callback of the following type may be connected:
213 * void YourCallbackName(Actor currentFocusedActor, bool forward);
215 * @pre The Object has been initialized.
216 * @return The signal to connect to.
218 FocusGroupChangedSignalV2& FocusGroupChangedSignal();
221 * This signal is emitted when the current focused actor is activated.
222 * A callback of the following type may be connected:
224 * void YourCallbackName(Actor activatedActor);
226 * @pre The Object has been initialized.
227 * @return The signal to connect to.
229 FocusedActorActivatedSignalV2& FocusedActorActivatedSignal();
231 // Not intended for application developers
234 * Creates a new handle from the implementation.
235 * @param[in] impl A pointer to the object.
237 explicit DALI_INTERNAL KeyboardFocusManager(Internal::KeyboardFocusManager *impl);
239 }; // class KeyboardFocusManager
241 } // namespace Toolkit
245 #endif // __DALI_TOOLKIT_KEYBOARD_FOCUS_MANAGER_H__