src/base/inc/FBaseRtIEvent.h

   1 //
   2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   3 //
   4 // Licensed under the Apache License, Version 2.0 (the License);
   5 // you may not use this file except in compliance with the License.
   6 // You may obtain a copy of the License at
   7 //
   8 // http://www.apache.org/licenses/LICENSE-2.0
   9 //
  10 // Unless required by applicable law or agreed to in writing, software
  11 // distributed under the License is distributed on an "AS IS" BASIS,
  12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 // See the License for the specific language governing permissions and
  14 // limitations under the License.
  15 //
  16
  17 /**
  18  * @file                FBaseRtIEvent.h
  19  * @brief               This is the header file for IEvent.
  20  */
  21 #ifndef _FRT_IEVENT_H_
  22 #define _FRT_IEVENT_H_
  23
  24 #include <FBaseResult.h>
  25 #include <FBaseRtIEventListener.h>
  26
  27 #include "FBaseRtIEventFilter.h"
  28 #include "FBaseRtIEventArg.h"
  29
  30 namespace Tizen { namespace Base { namespace Runtime
  31 {
  32
  33 // forward declaration
  34 class _EventDispatcher;
  35
  36 /**
  37  * @interface   IEvent
  38  * @brief       This interface is the root class for all event types.
  39  *
  40  * This interface is used for defining the kind of the occurrences. For example, one of the sub-classes
  41  * of this interface can be the key event, and it represents there can be the occurrences about the key.
  42  * An occurrence is represented by the event arguments. The event argument keeps the information
  43  * about the occurrence of the key event. You can get the information about what key is pressed or released from the
  44  * event argument of the key event.
  45  *
  46  * The event instance may have some event filters and event listeners.
  47  * The event filters are the filtering mechanism for fired event. It can modify or consume the event argument.
  48  * Modified event argument is passed to the next event filter, and finally event listeners listen with modified event
  49  * argument. Consumed event argument is neither passed to the next event filter nor to the event listeners.
  50  * When you want to get the numeric keys or remap the keys, you can add the filter to the key event for filtering
  51  * the non-numeric keys or changing the key codes.
  52  *
  53  * The event listener listens to the event argument which is fired at the event.
  54  * Listening event argument is passed by event filters. The event listener is called with
  55  * its corresponding method by passing event argument's value.
  56  * The sample of the event listener is in the Event class' description.
  57  *
  58  * @remarks     The default implementation of this interface is Event class.
  59  * @see         Event
  60  */
  61 class _OSP_EXPORT_ IEvent
  62 {
  63 public:
  64         //
  65         // This is a virtual destructor.
  66         //
  67         virtual ~IEvent(void) {}
  68
  69         /**
  70          * Adds a filter object.
  71          * Added filter can process all the fired events before event listening.
  72          *
  73          * @param[in]   filter  Filter to be added
  74          * @return              Error code.
  75          * @exception   E_SUCCESS                       - This method is successful.
  76          * @exception   E_OUT_OF_MEMORY - Failed to allocate required/requested memory.
  77          * @remark              It is not forced how to implement this method. It depends on the implementation of
  78          *                              the inherited classes. But in general Event class which is the default implementation
  79          *                              of this interface is used
  80          *                              in many cases.
  81          * @see                 RemoveFilter
  82          */
  83         virtual result AddFilter(const IEventFilter& filter) = 0;
  84
  85         /**
  86          * Removes a filter object.
  87          *
  88          * @param[in]   filter  Filter to be removed
  89          * @return              Error code.
  90          * @exception   E_SUCCESS                       - This method is successful.
  91          * @exception   E_OBJ_NOT_FOUND - The specified object is not found within the indicated range.
  92          * @remark              It is not forced how to implement this method. It depends on the implementation of
  93          *                              the inherited classes. But in general Event class which is the default implementation
  94          *                              of this interface is used
  95          *                              in many cases.
  96          * @see                 AddFilter
  97          */
  98         virtual result RemoveFilter(const IEventFilter& filter) = 0;
  99
 100         /**
 101          * Adds a listener object.
 102          * Added listener can listen to events when they are fired.
 103          *
 104          * @param[in]   listener        Listener to be added
 105          * @return              Error code.
 106          * @exception   E_SUCCESS                       - This method is successful.
 107          * @exception   E_OUT_OF_MEMORY - Failed to allocate required/requested memory.
 108          * @remark              It is not forced how to implement this method. It depends on the implementation of
 109          *                              the inherited classes. But in general Event class which is the default implementation
 110          *                              of this interface is used in many cases.
 111          * @see                 RemoveListener
 112          */
 113         virtual result AddListener(const IEventListener& listener) = 0;
 114
 115         /**
 116          * Removes a listener object.
 117          * Removed listener cannot listen to events when they are fired.
 118          *
 119          * @param[in]   listener Listener to be removed
 120          * @return              Error code.
 121          * @exception   E_SUCCESS                       - This method is successful.
 122          * @exception   E_OBJ_NOT_FOUND - The specified object is not found within the indicated range.
 123          * @remark              It is not forced how to implement this method. It depends on the implementation of
 124          *                              the inherited classes. But in general Event class which is the default implementation
 125          *                              of this interface is used
 126          *                              in many cases.
 127          * @see                 AddListener
 128          */
 129         virtual result RemoveListener(const IEventListener& listener) = 0;
 130
 131         /**
 132         * Fires the event with event argument.
 133         * All listeners that are added to this method listen when it is called.
 134         *
 135         * @param[in]    arg     The event argument.
 136         * @return               true, if the event has been fired without filtering. false, otherwise.
 137         */
 138         virtual bool Fire(const IEventArg& arg) = 0;
 139
 140         /**
 141         * Fires the event with event argument.
 142         * All listeners that are added to this method listen when it is called.
 143         *
 144         * @param[in]    arg     The event argument.
 145         * @return               true, if the event has been fired without filtering. false, otherwise.
 146         */
 147         virtual bool Fire(const IEventArg& arg, bool async) = 0;
 148
 149         virtual int AddRef(void) = 0;
 150
 151         virtual int Release(void) = 0;
 152 };
 153 }}} // Tizen::Runtime
 154 #endif