inc/FUiIPropagatedTouchEventListener.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Flora License, Version 1.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
   8 //
   9 //     http://floralicense.org/license/
  10 //
  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.
  16 //
  17 /**
  18  * @file FUiIPropagatedTouchEventListener.h
  19  * @brief          This is the header file for the %IPropagatedTouchEventListener interface.
  20  *
  21  * This header file contains the declarations of the %IPropagatedTouchEventListener interface.
  22  */
  23
  24 #ifndef _FUI_IPROPAGATED_TOUCH_EVENT_LISTENER_H_
  25 #define _FUI_IPROPAGATED_TOUCH_EVENT_LISTENER_H_
  26
  27 namespace Tizen { namespace Ui {
  28
  29 class Control;
  30 class TouchEventInfo;
  31
  32 /**
  33  * @interface   IPropagatedTouchEventListener
  34  * @brief               This interface is used as an argument for the propagated touch event listener.
  35  *
  36  * @since                              2.1
  37  *
  38  * The %IPropagatedTouchEventListener interface is the listener interface for receiving propagated touch events. @n
  39  * The class that processes a propagated touch event implements this interface, and the instance created with that class is registered with a
  40  * UI control, using the Control::SetPropagatedTouchEventListener() method. When the touch event occurs, a method of that instance which is derived from %IPropagatedTouchEventListener is
  41  * invoked.
  42  * The propagated touch event listeners work according to the event previewing and bubbling concept. @n
  43  * When a touch event occurs, as a previewing notification it is routed from the top-most Window, which is usually a Frame,
  44  * to a control which is the parent of the control where the event occurs. Then, as a bubbling notification it is routed from
  45  * the control to the top-most Window.
  46  * In both previewing and bubbling paths, event routing can be controlled by the value returned by the listener. Returning @c true, which means
  47  * the event is processed in the listener of the notified control, stops further routing. Returning @c false allows the next event listener
  48  * to listen to the event.
  49  * @n
  50  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/event_listener.htm">Event Listeners</a>.
  51  */
  52 class _OSP_EXPORT_ IPropagatedTouchEventListener
  53 {
  54 public:
  55         /**
  56          * This polymorphic destructor should be overridden if required.
  57          * This way, the destructors of the derived classes are called when the destructor of this interface is called.
  58          *
  59          * @since       2.1
  60          */
  61         virtual ~IPropagatedTouchEventListener(void){}
  62
  63         /**
  64          * Called during the bubbling step when a touch is pressed.
  65          *
  66          * @since                     2.1
  67          *
  68          * @return                              Whether the touch event is processed by the listener or not
  69          * @param[in]    source                        The source of the event
  70          * @param[in]    touchEventInfo                    The touch event information
  71          */
  72         virtual bool OnTouchPressed(Control& source, const TouchEventInfo& touchEventInfo) = 0;
  73
  74         /**
  75          * Called during the bubbling step when a touch is released.
  76          *
  77          * @since                     2.1
  78          *
  79          * @return                              Whether the touch event is processed by the listener or not
  80          * @param[in]    source                        The source of the event
  81          * @param[in]    touchEventInfo                    The touch event information
  82          */
  83         virtual bool OnTouchReleased(Control& source, const TouchEventInfo& touchEventInfo) = 0;
  84
  85         /**
  86          * Called during the bubbling step when a touch is moved.
  87          *
  88          * @since                     2.1
  89          *
  90          * @return                              Whether the touch event is processed by the listener or not
  91          * @param[in]    source                        The source of the event
  92          * @param[in]    touchEventInfo                    The touch event information
  93          */
  94         virtual bool OnTouchMoved(Control& source, const TouchEventInfo& touchEventInfo) = 0;
  95
  96         /**
  97          * Called during the bubbling step when a touch is canceled.
  98          *
  99          * @since                     2.1
 100          *
 101          * @return                              Whether the touch event is processed by the listener or not
 102          * @param[in]    source                        The source of the event
 103          * @param[in]    touchEventInfo                    The touch event information
 104          */
 105         virtual bool OnTouchCanceled(Control& source, const TouchEventInfo& touchEventInfo) = 0;
 106
 107         /**
 108          * Called during the previewing step when a touch is pressed.
 109          *
 110          * @since                                         2.1
 111          *
 112          * @return                              Whether the touch event is processed by the listener or not
 113          * @param[in]   source                        The source of the event
 114          * @param[in]   touchEventInfo                    The touch event information
 115          */
 116         virtual bool OnPreviewTouchPressed(Control& source, const TouchEventInfo& touchEventInfo) = 0;
 117
 118
 119         /**
 120          * Called during the previewing step when a touch is released.
 121          *
 122          * @since                                         2.1
 123          *
 124          * @return                              Whether the touch event is processed by the listener or not
 125          * @param[in]   source                        The source of the event
 126          * @param[in]   touchEventInfo                    The touch event information
 127          */
 128         virtual bool OnPreviewTouchReleased(Control& source, const TouchEventInfo& touchEventInfo) = 0;
 129
 130         /**
 131          * Called during the previewing step when a touch is moved.
 132          *
 133          * @since                                         2.1
 134          *
 135          * @return                              Whether the touch event is processed by the listener or not
 136          * @param[in]   source                        The source of the event
 137          * @param[in]   touchEventInfo                    The touch event information
 138          */
 139         virtual bool OnPreviewTouchMoved(Control& source, const TouchEventInfo& touchEventInfo) = 0;
 140
 141 protected:
 142         // Reserved virtual methods for later extension
 143         //
 144         // The following methods are reserved and may change its name at any time without prior notice.
 145         //
 146         virtual void IPropagatedTouchEventListener_Reserved1(void) {}
 147
 148         // Reserved virtual methods for later extension
 149         //
 150         // The following methods are reserved and may change its name at any time without prior notice.
 151         //
 152         virtual void IPropagatedTouchEventListener_Reserved2(void) {}
 153
 154         // Reserved virtual methods for later extension
 155         //
 156         // The following methods are reserved and may change its name at any time without prior notice.
 157         //
 158         virtual void IPropagatedTouchEventListener_Reserved3(void) {}
 159
 160         // Reserved virtual methods for later extension
 161         //
 162         // The following methods are reserved and may change its name at any time without prior notice.
 163         //
 164         virtual void IPropagatedTouchEventListener_Reserved4(void) {}
 165
 166         // Reserved virtual methods for later extension
 167         //
 168         // The following methods are reserved and may change its name at any time without prior notice.
 169         //
 170         virtual void IPropagatedTouchEventListener_Reserved5(void) {}
 171 }; // IPropagatedTouchEventListener
 172
 173 }} // Tizen::Ui
 174 #endif // _FUI_IPROPAGATED_TOUCH_EVENT_LISTENER_H_