[dali_2.0.15] Merge branch 'devel/master'
[platform/core/uifw/dali-toolkit.git] / dali-toolkit / devel-api / focus-manager / keyinput-focus-manager.h
1 #ifndef DALI_TOOLKIT_KEYINPUT_FOCUS_MANAGER_H
2 #define DALI_TOOLKIT_KEYINPUT_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 KeyInputFocusManager;
31 }
32
33 /**
34  * KeyInputFocusManager
35  * This class provides the functionality of registering for keyboard events for controls.
36  * The keyinput focus manager maintains a stack of controls, With the last added control receiving
37  * all the keyboard events first. And if the conrol doesn't consume the event it is passed to
38  * the next control in the stack. If none of the controls in the stack consume the key event then
39  * UnhandledKeyEventSignal() is emitted.
40  *
41  * Signals
42  * | %Signal Name         | Method                            |
43  * |----------------------|-----------------------------------|
44  * | keyInputFocusChanged | @ref KeyInputFocusChangedSignal() |
45  */
46 class DALI_TOOLKIT_API KeyInputFocusManager : public BaseHandle
47 {
48 public:
49   // KeyInputFocusChanged
50   typedef Signal<void(Control, Control)> KeyInputFocusChangedSignalType;
51
52 public:
53   /**
54    * Create a KeyInputFocusManager handle; this can be initialised with KeyInputFocusManager::Get()
55    * Calling member functions with an uninitialised handle is not allowed.
56    */
57   KeyInputFocusManager();
58
59   /**
60    * @brief Destructor
61    *
62    * This is non-virtual since derived Handle types must not contain data or virtual methods.
63    */
64   ~KeyInputFocusManager();
65
66   /**
67    * Get the singleton of KeyInputFocusManager object.
68    * @return A handle to the KeyInputFocusManager control.
69    */
70   static KeyInputFocusManager Get();
71
72   /**
73    * Sets keyboard focus for a control.
74    * Note: A control can be set to be in focus and still not receive all the key events if another control has over ridden it.
75    * As the key input focus mechanism works like a stack, the top most control receives all the key events, and passes on the
76    * unhandled events to the controls below in the stack. A control in the stack will regain key input focus when there are no more
77    * controls above it in the focus stack.
78    *
79    * @pre The Control is not in the focus stack. If it is allready present in the top of the stack it results in a no-op, If it is
80    * present in the stack but not on the top of the stack, then the control is moved to the top of the focus stack.
81    * @param[in] control The Control to receive keyboard input
82    */
83   void SetFocus(Control control);
84
85   /**
86    * Query for the control that is currently set to be on top of the fcous stack and receives all
87    * keyboard input events first.
88    * @return Pointer to the control set to receive keyboard inputs.
89    */
90   Control GetCurrentFocusControl() const;
91
92   /**
93    * Removes focus for the given control, The control will no longer receive events from keyboard.
94    * @param [in] control which should be removed from focus.
95    */
96   void RemoveFocus(Control control);
97
98 public: // Signals
99   /**
100    * This signal is emitted when the key input focus control changes.
101    * Two control parameters are sent as part of this signal, the first being the signal that now has the focus, the second
102    * being the one that has lost focus.
103    * A callback of the following type may be connected:
104    * @code
105    *   void YourCallback(Control focusGainedControl, Control focusLostActor);
106    * @endcode
107    * @return The signal to connect to.
108    */
109   KeyInputFocusChangedSignalType& KeyInputFocusChangedSignal();
110
111 private:
112   explicit DALI_INTERNAL KeyInputFocusManager(Internal::KeyInputFocusManager* impl);
113
114 }; // class KeyInputFocusManager
115
116 } // namespace Toolkit
117
118 } // namespace Dali
119
120 #endif // DALI_TOOLKIT_KEYINPUT_FOCUS_MANAGER_H