2 // Open Service Platform
3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
5 // Licensed under the Apache License, Version 2.0 (the License);
6 // you may not use this file except in compliance with the License.
7 // You may obtain a copy of the License at
9 // http://www.apache.org/licenses/LICENSE-2.0/
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
18 * @file FUiIPropagatedKeyEventListener.h
19 * @brief This is the header file for the %IPropagatedKeyEventListener interface.
21 * This header file contains the declarations of the %IPropagatedKeyEventListener interface.
24 #ifndef _FUI_IPROPAGATED_KEY_EVENT_LISTENER_H_
25 #define _FUI_IPROPAGATED_KEY_EVENT_LISTENER_H_
27 namespace Tizen { namespace Ui
34 * @interface IPropagatedKeyEventListener
35 * @brief This interface is used as an argument for the propagated key event listener.
39 * The %IPropagatedKeyEventListener interface is the listener interface for receiving propagated key events.
40 * The class that processes a propagated key event implements this interface, and the instance created with that class is registered with a
41 * UI control, using the Control::SetPropagatedKeyEventListener() method. When the key event occurs, a method of that instance that is derived from %IPropagatedKeyEventListener is
43 * The propagated key event listeners work according to the event previewing and bubbling concept. @n
44 * When a key event occurs, as a previewing notification it is routed from the top-most Window, which is usually a Frame,
45 * to a control which is the parent of the control where the event occurs. Then, as a bubbling notification it is routed from
46 * the control to the top-most Window.
47 * In both previewing and bubbling paths, event routing can be controlled by the value returned by the listener. Returning @c true, which means
48 * the event is processed in the listener of the notified control, stops further routing. Returning @c false allows the next event listener
49 * to listen to the event.
51 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/event_listener.htm">Event Listeners</a>.
53 class _OSP_EXPORT_ IPropagatedKeyEventListener
57 * This polymorphic destructor should be overridden if required.
58 * This way, the destructors of the derived classes are called when the destructor of this interface is called.
62 virtual ~IPropagatedKeyEventListener(void){}
65 * Called during the bubbling step when a key is pressed.
69 * @return Whether the key event is processed by the listener or not
70 * @param[in] source The source of the event
71 * @param[in] keyEventInfo The key event information
73 virtual bool OnKeyPressed(Control& source, const KeyEventInfo& keyEventInfo) = 0;
76 * Called during the bubbling step when a key is released.
80 * @return Whether the key event is processed by the listener or not
81 * @param[in] source The source of the event
82 * @param[in] keyEventInfo The key event information
84 virtual bool OnKeyReleased(Control& source, const KeyEventInfo& keyEventInfo) = 0;
87 * Called during the previewing step when a key is pressed.
91 * @return Whether the key event is processed by the listener or not
92 * @param[in] source The source of the event
93 * @param[in] keyEventInfo The key event information
95 virtual bool OnPreviewKeyPressed(Control& source, const KeyEventInfo& keyEventInfo) = 0;
98 * Called during the previewing step when a key is released.
102 * @return Whether the key event is processed by the listener or not
103 * @param[in] source The source of the event
104 * @param[in] keyEventInfo The key event information
106 virtual bool OnPreviewKeyReleased(Control& source, const KeyEventInfo& keyEventInfo) = 0;
109 * Called before the OnPreviewKeyPressed() or OnPreviewKeyReleased() method is called, allowing the application to modify the KeyEventInfo instance. @n
110 * Before previewing and bubbling paths, the %TranslateKeyEventInfo() method is called once.
114 * @return Whether the KeyEventInfo instance is modified or not
115 * @param[in] source The source of the event
116 * @param[in,out] keyEventInfo The key event information that can be converted by this method
118 virtual bool TranslateKeyEventInfo(Control& source, KeyEventInfo& keyEventInfo) { return false; }
121 // Reserved virtual methods for later extension
123 // The following methods are reserved and may change its name at any time without prior notice.
125 virtual void IPropagatedKeyEventListener_Reserved1(void) {}
127 // Reserved virtual methods for later extension
129 // The following methods are reserved and may change its name at any time without prior notice.
131 virtual void IPropagatedKeyEventListener_Reserved2(void) {}
133 // Reserved virtual methods for later extension
135 // The following methods are reserved and may change its name at any time without prior notice.
137 virtual void IPropagatedKeyEventListener_Reserved3(void) {}
139 // Reserved virtual methods for later extension
141 // The following methods are reserved and may change its name at any time without prior notice.
143 virtual void IPropagatedKeyEventListener_Reserved4(void) {}
145 // Reserved virtual methods for later extension
147 // The following methods are reserved and may change its name at any time without prior notice.
149 virtual void IPropagatedKeyEventListener_Reserved5(void) {}
150 }; //IPropagatedKeyEventListener
153 #endif // _FUI_IPROPAGATED_KEY_EVENT_LISTENER_H_