sync with tizen_2.0
[platform/framework/native/appfw.git] / 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_