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