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