inc/FBaseRtEvent.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   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
   8 //
   9 // http://www.apache.org/licenses/LICENSE-2.0
  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 /**
  19  * @file        FBaseRtEvent.h
  20  * @brief       This is the header file for the %Event class.
  21  *
  22  * This file contains the declarations of the %Event class.
  23  */
  24
  25 #ifndef _FBASE_RT_EVENT_H_
  26 #define _FBASE_RT_EVENT_H_
  27
  28 #include <FBaseObject.h>
  29
  30 namespace Tizen { namespace Base { namespace Runtime
  31 {
  32
  33 class IEventArg;
  34 class IEventListener;
  35 /**
  36 * @class Event
  37 * @brief This class provides methods for delivering an event with an argument synchronously and asynchronously.
  38 * @since 2.0
  39 *
  40 * @code
  41 *
  42 * #include <FBase.h>
  43 *
  44 * using namespace Tizen::Base::Runtime;
  45 *
  46 * class MyEventArg : public IEventArg
  47 * {
  48 * public:
  49 *       MyEventArg(int t);
  50 *       int type;
  51 * };
  52 *
  53 * MyEventArg::MyEventArg(int t)
  54 * {
  55 *       type = t;
  56 * }
  57 *
  58 * class MyEventListener : public IEventListener
  59 * {
  60 * public:
  61 *       void OnEventReceived(const IEventArg& arg);
  62 * };
  63 *
  64 * void
  65 * MyEventListener::OnEventReceived(const IEventArg& arg)
  66 * {
  67 *       const MyEventArg* myarg = dynamic_cast<const MyEventArg*> (&arg);
  68 * }
  69 *
  70 * class MyEvent : public Event
  71 * {
  72 * protected:
  73 *     virtual void FireImpl(IEventListener& listener, const IEventArg& arg);
  74 * };
  75 *
  76 * void
  77 * MyEvent::FireImpl(IEventListener& listener, const IEventArg& arg)
  78 * {
  79 *       MyEventListener* plistener = dynamic_cast<MyEventListener*> (&listener);
  80 *       plistener->OnEventReceived(arg);
  81 * }
  82 *
  83 * void
  84 * MyApplication::Test Code(void)
  85 * {
  86 *       MyEventListener* mylistener = new MyEventListener();
  87 *       MyEvent* my = new MyEvent();
  88 *       MyEventArg* myarg = new MyEventArg(3);
  89 *       my->AddListener(*mylistener);
  90 *       my->Fire(*myarg);
  91 * }
  92 *
  93 * @endcode
  94 */
  95 class _OSP_EXPORT_ Event
  96         : virtual public Tizen::Base::Object
  97 {
  98 public:
  99         /**
 100          * This is the default constructor for this class.
 101          *
 102          * @since 2.0
 103          */
 104         Event(void);
 105
 106         /**
 107          * This is the destructor for this class.
 108          *
 109          * @since 2.0
 110          */
 111         virtual ~Event(void);
 112
 113         /**
 114          * Adds the listener object.
 115          * The added listener can listen to events when they are fired.
 116          *
 117          * @since 2.0
 118          *
 119          * @return      An error code
 120          * @param[in]   listener  Listener to add
 121          * @param[in]   calledByCallerThread        true, to call the listener on the caller thread of this method
 122          *                                          false, to call the listener on the thread in which the event is fired.
 123          * @exception   E_SUCCESS        This method is successful.
 124          * @exception   E_OBJ_ALREADY_EXIST     The listener already exists.
 125          * @exception   E_INVALID_OPERATION calledByCallerThread is set to true but the caller thread is a worker thread.
 126          */
 127         result AddListener(IEventListener& listener, bool calledByCallerThread = true);
 128
 129         /**
 130          * Removes the listener object.
 131          * The removed listener cannot listen to events when they are fired.
 132          *
 133          * @since 2.0
 134          *
 135          * @return       An error code
 136          * @param[in]    listener  Listener to remove
 137          * @exception    E_SUCCESS        This method is successful.
 138          * @exception    E_OBJ_NOT_FOUND        The listener is not found.
 139          */
 140         result RemoveListener(IEventListener& listener);
 141
 142         /**
 143          * Fires the event with an argument.
 144          *
 145          * @since 2.0
 146          *
 147          * @return       An error code
 148          * @param[in]    arg       The event argument.
 149          * @exception    E_SUCCESS                   This method is successful.
 150          * @exception    E_INVALID_STATE                     This event has not been initialized.
 151          *
 152          * @remark This takes the ownership of @c arg. So arg should be created on a heap and should not be deleted by caller.
 153          */
 154         result Fire(IEventArg& arg);
 155
 156 protected:
 157         /**
 158          * Implement to call the corresponding event listener's method.
 159          *
 160          * @since 2.0
 161          *
 162          * @param[in]    listener  The listener instance which is currently processing
 163          * @param[in]    arg                 The event argument that is fired
 164          *
 165          * @remark A derived class must override this method.
 166          */
 167         virtual void FireImpl(IEventListener& listener, const IEventArg& arg) = 0;
 168
 169 private:
 170         friend class _EventImpl;
 171         class _EventImpl* __pEventImpl;
 172
 173 }; // Event
 174
 175 } } } // Tizen::Base::Runtime
 176
 177 #endif // _FBASE_RT_EVENT_H_