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