1 #ifndef __DALI_TOOLKIT_KEYINPUT_FOCUS_MANAGER_H__
2 #define __DALI_TOOLKIT_KEYINPUT_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 KeyInputFocusManager;
36 * KeyInputFocusManager
37 * This class provides the functionality of registering for keyboard events for controls.
38 * The keyinput focus manager maintains a stack of controls, With the last added control receiving
39 * all the keyboard events first. And if the conrol doesn't consume the event it is passed to
40 * the next control in the stack. If none of the controls in the stack consume the key event then
41 * UnhandledKeyEventSignal() is emitted.
44 class KeyInputFocusManager : public BaseHandle
48 static const char* const SIGNAL_KEY_INPUT_FOCUS_CHANGED;
49 static const char* const SIGNAL_UNHANDLED_KEY_EVENT;
51 // KeyInputFocusChanged
52 typedef SignalV2< void (Control, Control) > KeyInputFocusChangedSignalV2;
54 // Unhandled Key Event
55 typedef SignalV2< void (const KeyEvent&) > UnhandledKeyEventSignalV2;
60 * Create a KeyInputFocusManager handle; this can be initialised with KeyInputFocusManager::Get()
61 * Calling member functions with an uninitialised handle is not allowed.
63 KeyInputFocusManager();
68 virtual ~KeyInputFocusManager();
71 * Get the singleton of KeyInputFocusManager object.
72 * @return A handle to the KeyInputFocusManager control.
74 static KeyInputFocusManager Get();
77 * Sets keyboard focus for a control.
78 * 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.
79 * As the key input focus mechanism works like a stack, the top most control receives all the key events, and passes on the
80 * unhandled events to the controls below in the stack. A control in the stack will regain key input focus when there are no more
81 * controls above it in the focus stack.
83 * @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
84 * present in the stack but not on the top of the stack, then the control is moved to the top of the focus stack.
85 * @param[in] control The Control to receive keyboard input
87 void SetFocus(Control control);
90 * Query for the control that is currently set to be on top of the fcous stack and receives all
91 * keyboard input events first.
92 * @return Pointer to the control set to receive keyboard inputs.
94 Control GetCurrentFocusControl() const;
97 * Removes focus for the given control, The control will no longer receive events from keyboard.
98 * @param [in] control which should be removed from focus.
100 void RemoveFocus(Control control);
103 * Queries whether a control is currently part of the focus stack.
104 * @param [in] control which should be queried.
105 * @return True if it is part of the foucus stack False otherwise.
107 bool IsKeyboardListener(Control control);
112 * This signal is emitted when the key input focus control changes.
113 * Two control parameters are sent as part of this signal, the first being the signal that now has the focus, the second
114 * being the one that has lost focus.
115 * A callback of the following type may be connected:
117 * void YourCallback(Control focusGainedControl, Control focusLostActor);
119 * @return The signal to connect to.
121 KeyInputFocusChangedSignalV2& KeyInputFocusChangedSignal();
124 * This signal is emitted when a key event was received, and none of the focused controls on the stage have consumed it.
125 * A callback of the following type may be connected:
127 * void YourCallbackName(const KeyEvent& event);
129 * @return The signal to connect to.
131 UnhandledKeyEventSignalV2& UnhandledKeyEventSignal();
135 KeyInputFocusManager(Internal::KeyInputFocusManager *impl);
137 }; // class KeyInputFocusManager
139 } // namespace Toolkit
143 #endif // __DALI_TOOLKIT_KEYINPUT_FOCUS_MANAGER_H__