[dali_2.0.37] Merge branch 'devel/master'
[platform/core/uifw/dali-toolkit.git] / dali-toolkit / public-api / focus-manager / keyboard-focus-manager.h
1 #ifndef DALI_TOOLKIT_KEYBOARD_FOCUS_MANAGER_H
2 #define DALI_TOOLKIT_KEYBOARD_FOCUS_MANAGER_H
3
4 /*
5  * Copyright (c) 2020 Samsung Electronics Co., Ltd.
6  *
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
10  *
11  * http://www.apache.org/licenses/LICENSE-2.0
12  *
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.
18  *
19  */
20
21 // INTERNAL INCLUDES
22 #include <dali-toolkit/public-api/controls/control.h>
23
24 namespace Dali
25 {
26 namespace Toolkit
27 {
28 namespace Internal DALI_INTERNAL
29 {
30 class KeyboardFocusManager;
31 }
32 /**
33  * @addtogroup dali_toolkit_managers
34  * @{
35  */
36
37 /**
38  * @brief Provides the functionality of handling keyboard navigation
39  * and maintaining the two dimensional keyboard focus chain.
40  *
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
44  * is changed.
45  *
46  * Signals
47  * | %Signal Name                 | Method                             |
48  * |------------------------------|------------------------------------|
49  * | keyboardPreFocusChange       | @ref PreFocusChangeSignal()        |
50  * | keyboardFocusChanged         | @ref FocusChangedSignal()          |
51  * | keyboardFocusGroupChanged    | @ref FocusGroupChangedSignal()     |
52  * | keyboardFocusedActorEnterKey | @ref FocusedActorEnterKeySignal()  |
53  * @SINCE_1_0.0
54  */
55 class DALI_TOOLKIT_API KeyboardFocusManager : public BaseHandle
56 {
57 public:
58   /// @brief Pre focus change signal
59   typedef Signal<Actor(Actor, Actor, Control::KeyboardFocus::Direction)> PreFocusChangeSignalType;
60
61   /// @brief Focus changed signal
62   typedef Signal<void(Actor, Actor)> FocusChangedSignalType;
63
64   /// @brief Focus group changed signal
65   typedef Signal<void(Actor, bool)> FocusGroupChangedSignalType;
66
67   /// @brief Focused actor has the enter key pressed signal
68   typedef Signal<void(Actor)> FocusedActorEnterKeySignalType;
69
70   /**
71    * @brief Creates a KeyboardFocusManager handle; this can be initialized with KeyboardFocusManager::New().
72    *
73    * Calling member functions with an uninitialized handle is not allowed.
74    * @SINCE_1_0.0
75    */
76   KeyboardFocusManager();
77
78   /**
79    * @brief Destructor.
80    *
81    * This is non-virtual since derived Handle types must not contain data or virtual methods.
82    * @SINCE_1_0.0
83    */
84   ~KeyboardFocusManager();
85
86   /**
87    * @brief Gets the singleton of KeyboardFocusManager object.
88    *
89    * @SINCE_1_0.0
90    * @return A handle to the KeyboardFocusManager control
91    */
92   static KeyboardFocusManager Get();
93
94   /**
95    * @brief Moves the keyboard focus to the given actor.
96    *
97    * Only one actor can be focused at the same time.  The actor must
98    * be in the stage already and keyboard focusable.
99    *
100    * @SINCE_1_0.0
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    */
106   bool SetCurrentFocusActor(Actor actor);
107
108   /**
109    * @brief Gets the current focused actor.
110    *
111    * @SINCE_1_0.0
112    * @return A handle to the current focused actor or an empty handle if no actor is focused
113    * @pre The KeyboardFocusManager has been initialized.
114    */
115   Actor GetCurrentFocusActor();
116
117   /**
118    * @brief Moves the focus to the next focusable actor in the focus
119    * chain in the given direction (according to the focus traversal
120    * order).
121    *
122    * @SINCE_1_0.0
123    * @param direction The direction of focus movement
124    * @return true if the movement was successful
125    * @pre The KeyboardFocusManager has been initialized.
126    */
127   bool MoveFocus(Control::KeyboardFocus::Direction direction);
128
129   /**
130    * @brief Clears the focus from the current focused actor if any, so
131    * that no actor is focused in the focus chain.
132    *
133    * It will emit focus changed signal without current focused actor.
134    * @SINCE_1_0.0
135    * @pre The KeyboardFocusManager has been initialized.
136    */
137   void ClearFocus();
138
139   /**
140    * @brief Sets whether the focus movement should be looped within the same focus group.
141    *
142    * The focus movement is not looped by default.
143    * @SINCE_1_0.0
144    * @param enabled Whether the focus movement should be looped
145    * @pre The KeyboardFocusManager has been initialized.
146    */
147   void SetFocusGroupLoop(bool enabled);
148
149   /**
150    * @brief Gets whether the focus movement should be looped within the same focus group.
151    *
152    * @SINCE_1_0.0
153    * @return Whether the focus movement should be looped
154    * @pre The KeyboardFocusManager has been initialized.
155    */
156   bool GetFocusGroupLoop() const;
157
158   /**
159    * @brief Sets whether an actor is a focus group that can limit the
160    * scope of focus movement to its child actors in the focus chain.
161    *
162    * Layout controls set themselves as focus groups by default.
163    *
164    * @SINCE_1_0.0
165    * @param actor The actor to be set as a focus group
166    * @param isFocusGroup Whether to set the actor as a focus group or not
167    * @pre The KeyboardFocusManager has been initialized.
168    * @pre The Actor has been initialized.
169    */
170   void SetAsFocusGroup(Actor actor, bool isFocusGroup);
171
172   /**
173    * @brief Checks whether the actor is set as a focus group or not.
174    *
175    * @SINCE_1_0.0
176    * @param actor The actor to be checked
177    * @return Whether the actor is set as a focus group
178    * @pre The KeyboardFocusManager has been initialized.
179    * @pre The Actor has been initialized.
180    */
181   bool IsFocusGroup(Actor actor) const;
182
183   /**
184    * @brief Returns the closest ancestor of the given actor that is a focus group.
185    *
186    * @SINCE_1_0.0
187    * @param actor The actor to be checked for its focus group
188    * @return The focus group the given actor belongs to or an empty handle if the given actor
189    * doesn't belong to any focus group
190    */
191   Actor GetFocusGroup(Actor actor);
192
193   /**
194    * @brief Sets the focus indicator actor.
195    *
196    * This will replace the default focus indicator actor in
197    * KeyboardFocusManager and will be added to the focused actor as a
198    * highlight.
199    *
200    * @SINCE_1_0.0
201    * @param indicator The indicator actor to be added
202    * @pre The KeyboardFocusManager has been initialized.
203    * @pre The indicator actor has been initialized.
204    */
205   void SetFocusIndicatorActor(Actor indicator);
206
207   /**
208    * @brief Gets the focus indicator actor.
209    *
210    * @SINCE_1_0.0
211    * @return A handle to the focus indicator actor
212    * @pre The KeyboardFocusManager has been initialized.
213    */
214   Actor GetFocusIndicatorActor();
215
216   /**
217    * @brief Move the focus to prev focused actor
218    *
219    * @SINCE_1_2.19
220    */
221   void MoveFocusBackward();
222
223 public: // Signals
224   /**
225    * @brief This signal is emitted before the focus is going to be changed.
226    *
227    * KeyboardFocusManager makes the best guess for which actor to
228    * focus towards the given direction, but applications might want to
229    * change that. By connecting with this signal, they can check the
230    * proposed actor to focus and return a different actor if they
231    * wish. This signal is only emitted when the navigation key is
232    * pressed and KeyboardFocusManager tries to move the focus
233    * automatically. It won't be emitted for focus movement by calling
234    * SetCurrentFocusActor directly.
235    *
236    * A callback of the following type may be connected:
237    * @code
238    *   Actor YourCallbackName(Actor currentFocusedActor, Actor proposedActorToFocus, Control::KeyboardFocus::Direction direction);
239    * @endcode
240    * @SINCE_1_0.0
241    * @return The signal to connect to
242    * @pre The Object has been initialized.
243    */
244   PreFocusChangeSignalType& PreFocusChangeSignal();
245
246   /**
247    * @brief This signal is emitted after the current focused actor has been changed.
248    *
249    * A callback of the following type may be connected:
250    * @code
251    *   void YourCallbackName(Actor originalFocusedActor, Actor currentFocusedActor);
252    * @endcode
253    * @SINCE_1_0.0
254    * @return The signal to connect to
255    * @pre The Object has been initialized.
256    */
257   FocusChangedSignalType& FocusChangedSignal();
258
259   /**
260    * @brief This signal is emitted when the focus group has been changed.
261    *
262    * If the current focus group has a parent layout control,
263    * KeyboardFocusManager will make the best guess for the next focus
264    * group to move the focus to in the given direction (forward or
265    * backward). If not, the application has to set the new focus.
266    *
267    * A callback of the following type may be connected:
268    * @code
269    *   void YourCallbackName(Actor currentFocusedActor, bool forward);
270    * @endcode
271    * @SINCE_1_0.0
272    * @return The signal to connect to
273    * @pre The Object has been initialized.
274    */
275   FocusGroupChangedSignalType& FocusGroupChangedSignal();
276
277   /**
278    * @brief This signal is emitted when the current focused actor has the enter key pressed on it.
279    *
280    * A callback of the following type may be connected:
281    * @code
282    *   void YourCallbackName(Actor enterPressedActor);
283    * @endcode
284    * @SINCE_1_0.0
285    * @return The signal to connect to
286    * @pre The Object has been initialized.
287    */
288   FocusedActorEnterKeySignalType& FocusedActorEnterKeySignal();
289
290   // Not intended for application developers
291
292   /// @cond internal
293   /**
294    * @brief Creates a new handle from the implementation.
295    *
296    * @SINCE_1_0.0
297    * @param[in] impl A pointer to the object
298    */
299   explicit DALI_INTERNAL KeyboardFocusManager(Internal::KeyboardFocusManager* impl);
300   /// @endcond
301
302 }; // class KeyboardFocusManager
303
304 /**
305  * @}
306  */
307 } // namespace Toolkit
308
309 } // namespace Dali
310
311 #endif // DALI_TOOLKIT_KEYBOARD_FOCUS_MANAGER_H