Merge "Size negotiation patch 3: Scope size negotiation enums" into tizen
[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) 2014 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
27 namespace Toolkit
28 {
29
30 namespace Internal DALI_INTERNAL
31 {
32 class KeyboardFocusManager;
33 }
34
35 /**
36  * @brief Provides the functionality of handling keyboard navigation
37  * and maintaining the two dimensional keyboard focus chain.
38  *
39  * It provides functionality of setting the focus and moving the focus
40  * in four directions (i.e. Left, Right, Up and Down). It also draws a
41  * highlight for the focused actor and emits a signal when the focus
42  * is changed.
43  *
44  * Signals
45  * | %Signal Name                     | Method                             |
46  * |----------------------------------|------------------------------------|
47  * | keyboard-pre-focus-change        | @ref PreFocusChangeSignal()        |
48  * | keyboard-focus-changed           | @ref FocusChangedSignal()          |
49  * | keyboard-focus-group-changed     | @ref FocusGroupChangedSignal()     |
50  * | keyboard-focused-actor-activated | @ref FocusedActorActivatedSignal() |
51  */
52 class DALI_IMPORT_API KeyboardFocusManager : public BaseHandle
53 {
54
55 public:
56
57   /// @brief Pre focus change signal
58   typedef Signal< Actor ( Actor, Actor, Control::KeyboardFocusNavigationDirection ) > PreFocusChangeSignalType;
59
60   /// @brief Focus changed signal
61   typedef Signal< void ( Actor, Actor ) > FocusChangedSignalType;
62
63   /// @brief Focus group changed signal
64   typedef Signal< void ( Actor, bool ) > FocusGroupChangedSignalType;
65
66   /// @brief Focused actor activated signal
67   typedef Signal< void ( Actor ) > FocusedActorActivatedSignalType;
68
69   /**
70    * @brief Create a KeyboardFocusManager handle; this can be initialised with KeyboardFocusManager::New().
71    *
72    * Calling member functions with an uninitialised handle is not allowed.
73    */
74   KeyboardFocusManager();
75
76   /**
77    * @brief Destructor
78    *
79    * This is non-virtual since derived Handle types must not contain data or virtual methods.
80    */
81   ~KeyboardFocusManager();
82
83   /**
84    * @brief Get the singleton of KeyboardFocusManager object.
85    *
86    * @return A handle to the KeyboardFocusManager control.
87    */
88   static KeyboardFocusManager Get();
89
90   /**
91    * @brief Move the keyboard focus to the given actor.
92    *
93    * Only one actor can be focused at the same time.  The actor must
94    * be in the stage already and keyboard focusable.
95    *
96    * @pre The KeyboardFocusManager has been initialized.
97    * @pre The Actor has been initialized.
98    * @param actor The actor to be focused
99    * @return Whether the focus is successful or not
100    */
101   bool SetCurrentFocusActor(Actor actor);
102
103   /**
104    * @brief Get the current focused actor.
105    *
106    * @pre The KeyboardFocusManager has been initialized.
107    * @return A handle to the current focused actor or an empty handle if no actor is focused.
108    */
109   Actor GetCurrentFocusActor();
110
111   /**
112    * @brief Move the focus to the next focusable actor in the focus
113    * chain in the given direction (according to the focus traversal
114    * order).
115    *
116    * @pre The KeyboardFocusManager has been initialized.
117    * @param direction The direction of focus movement
118    * @return true if the movement was successful
119    */
120   bool MoveFocus(Control::KeyboardFocusNavigationDirection direction);
121
122   /**
123    * @brief Clear the focus from the current focused actor if any, so
124    * that no actor is focused in the focus chain.
125    *
126    * It will emit focus changed signal without current focused actor
127    * @pre The KeyboardFocusManager has been initialized.
128    */
129   void ClearFocus();
130
131   /**
132    * @brief Set whether the focus movement should be looped within the same focus group.
133    *
134    * The focus movement is not looped by default.
135    * @pre The KeyboardFocusManager has been initialized.
136    * @param enabled Whether the focus movement should be looped
137    */
138   void SetFocusGroupLoop(bool enabled);
139
140   /**
141    * @brief Get whether the focus movement should be looped within the same focus group.
142    *
143    * @pre The KeyboardFocusManager has been initialized.
144    * @return Whether the focus movement should be looped
145    */
146   bool GetFocusGroupLoop() const;
147
148   /**
149    * @brief Set whether an actor is a focus group that can limit the
150    * scope of focus movement to its child actors in the focus chain.
151    *
152    * Layout controls set themselves as focus groups by default.
153    *
154    * @pre The KeyboardFocusManager has been initialized.
155    * @pre The Actor has been initialized.
156    * @param actor The actor to be set as a focus group.
157    * @param isFocusGroup Whether to set the actor as a focus group or not.
158    */
159   void SetAsFocusGroup(Actor actor, bool isFocusGroup);
160
161   /**
162    * @brief Check whether the actor is set as a focus group or not.
163    *
164    * @pre The KeyboardFocusManager has been initialized.
165    * @pre The Actor has been initialized.
166    * @param actor The actor to be checked.
167    * @return Whether the actor is set as a focus group.
168    */
169   bool IsFocusGroup(Actor actor) const;
170
171   /**
172    * @brief Returns the closest ancestor of the given actor that is a focus group.
173    *
174    * @param actor The actor to be checked for its focus group
175    * @return The focus group the given actor belongs to or an empty handle if the given actor
176    * doesn't belong to any focus group
177    */
178   Actor GetFocusGroup(Actor actor);
179
180   /**
181    * @brief Set the focus indicator actor.
182    *
183    * This will replace the default focus indicator actor in
184    * KeyboardFocusManager and will be added to the focused actor as a
185    * highlight.
186    *
187    * @pre The KeyboardFocusManager has been initialized.
188    * @pre The indicator actor has been initialized.
189    * @param indicator The indicator actor to be added
190    */
191   void SetFocusIndicatorActor(Actor indicator);
192
193   /**
194    * @brief Get the focus indicator actor.
195    *
196    * @pre The KeyboardFocusManager has been initialized.
197    * @return A handle to the focus indicator actor
198    */
199   Actor GetFocusIndicatorActor();
200
201 public: // Signals
202
203   /**
204    * @brief This signal is emitted before the focus is going to be changed.
205    *
206    * KeyboardFocusManager makes the best guess for which actor to
207    * focus towards the given direction, but applications might want to
208    * change that. By connecting with this signal, they can check the
209    * proposed actor to focus and return a different actor if they
210    * wish.  This signal is only emitted when the navigation key is
211    * pressed and KeyboardFocusManager tries to move the focus
212    * automatically. It won't be emitted for focus movement by calling
213    * SetCurrentFocusActor directly.
214    *
215    * A callback of the following type may be connected:
216    * @code
217    *   Actor YourCallbackName(Actor currentFocusedActor, Actor proposedActorToFocus, Control::KeyboardFocusNavigationDirection direction);
218    * @endcode
219    * @pre The Object has been initialized.
220    * @return The signal to connect to.
221    */
222   PreFocusChangeSignalType& PreFocusChangeSignal();
223
224   /**
225    * @brief This signal is emitted after the current focused actor has been changed.
226    *
227    * A callback of the following type may be connected:
228    * @code
229    *   void YourCallbackName(Actor originalFocusedActor, Actor currentFocusedActor);
230    * @endcode
231    * @pre The Object has been initialized.
232    * @return The signal to connect to.
233    */
234   FocusChangedSignalType& FocusChangedSignal();
235
236   /**
237    * @brief This signal is emitted when the focus group has been changed.
238    *
239    * If the current focus group has a parent layout control,
240    * KeyboardFocusManager will make the best guess for the next focus
241    * group to move the focus to in the given direction (forward or
242    * backward). If not, the application has to set the new focus.
243    *
244    * A callback of the following type may be connected:
245    * @code
246    *   void YourCallbackName(Actor currentFocusedActor, bool forward);
247    * @endcode
248    * @pre The Object has been initialized.
249    * @return The signal to connect to.
250    */
251   FocusGroupChangedSignalType& FocusGroupChangedSignal();
252
253   /**
254    * @brief This signal is emitted when the current focused actor is activated.
255    *
256    * A callback of the following type may be connected:
257    * @code
258    *   void YourCallbackName(Actor activatedActor);
259    * @endcode
260    * @pre The Object has been initialized.
261    * @return The signal to connect to.
262    */
263   FocusedActorActivatedSignalType& FocusedActorActivatedSignal();
264
265   // Not intended for application developers
266
267   /**
268    * @brief Creates a new handle from the implementation.
269    *
270    * @param[in] impl A pointer to the object.
271    */
272   explicit DALI_INTERNAL KeyboardFocusManager(Internal::KeyboardFocusManager *impl);
273
274 }; // class KeyboardFocusManager
275
276 } // namespace Toolkit
277
278 } // namespace Dali
279
280 #endif // __DALI_TOOLKIT_KEYBOARD_FOCUS_MANAGER_H__