1//------------------------------------------------------------------------------
2//	Copyright (c) 2001-2002, Haiku
3//
4//	Permission is hereby granted, free of charge, to any person obtaining a
5//	copy of this software and associated documentation files (the "Software"),
6//	to deal in the Software without restriction, including without limitation
7//	the rights to use, copy, modify, merge, publish, distribute, sublicense,
8//	and/or sell copies of the Software, and to permit persons to whom the
9//	Software is furnished to do so, subject to the following conditions:
10//
11//	The above copyright notice and this permission notice shall be included in
12//	all copies or substantial portions of the Software.
13//
14//	THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15//	IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16//	FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17//	AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18//	LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
19//	FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
20//	DEALINGS IN THE SOFTWARE.
21//
22//	File Name:		Event.cpp
23//	Author:			Ingo Weinhold (bonefish@users.sf.net)
24//					YellowBites (http://www.yellowbites.com)
25//	Description:	Base class for events as handled by EventQueue.
26//------------------------------------------------------------------------------
27
28#include "Event.h"
29
30/*!	\class Event
31	\brief Base class for events as handled by EventQueue.
32
33	Event features methods to set and get the event time and the "auto delete"
34	flag, and a Do() method invoked, when the event is executed.
35
36	If the "auto delete" flag is set to \c true, the event is deleted by the
37	event queue after it has been executed. The same happens, if Do() returns
38	\c true.
39*/
40
41/*!	\var bigtime_t Event::fTime
42	\brief The event time.
43*/
44
45/*!	\var bool Event::fAutoDelete
46	\brief The "auto delete" flag.
47*/
48
49// constructor
50/*!	\brief Creates a new event.
51
52	The event time is initialized to 0. That is, it should be set before
53	pushing the event into an event queue.
54
55	\param autoDelete Specifies whether the object shall automatically be
56		   deleted by the event queue after being executed.
57*/
58Event::Event(bool autoDelete)
59	: fTime(0),
60	  fAutoDelete(autoDelete)
61{
62}
63
64// constructor
65/*!	\brief Creates a new event.
66	\param time Time when the event shall be executed.
67	\param autoDelete Specifies whether the object shall automatically be
68		   deleted by the event queue after being executed.
69*/
70Event::Event(bigtime_t time, bool autoDelete)
71	: fTime(time),
72	  fAutoDelete(autoDelete)
73{
74}
75
76// destructor
77/*!	\brief Frees all resources associated with the object.
78
79	Does nothing.
80*/
81Event::~Event()
82{
83}
84
85// SetTime
86/*!	\brief Sets a new event time.
87
88	\note You must not call this method, when the event is in an event queue.
89		  Use EventQueue::ModifyEvent() instead.
90
91	\param time The new event time.
92*/
93void
94Event::SetTime(bigtime_t time)
95{
96	fTime = time;
97}
98
99// Time
100/*!	\brief Returns the time of the event.
101	\return Returns the time of the event.
102*/
103bigtime_t
104Event::Time() const
105{
106	return fTime;
107}
108
109// SetAutoDelete
110/*!	\brief Sets whether the event shall be deleted after execution.
111	\param autoDelete Specifies whether the object shall automatically be
112		   deleted by the event queue after being executed.
113*/
114void
115Event::SetAutoDelete(bool autoDelete)
116{
117	fAutoDelete = autoDelete;
118}
119
120// IsAutoDelete
121/*!	\brief Returns whether the event shall be deleted after execution.
122	\return Returns whether the object shall automatically be
123			deleted by the event queue after being executed.
124*/
125bool
126Event::IsAutoDelete() const
127{
128	return fAutoDelete;
129}
130
131// Do
132/*!	\brief Hook method invoked when the event time has arrived.
133
134	To be overridden by derived classes. As the method is executed in the
135	event queue's timer thread, the execution of the method should take
136	as little time as possible to keep the event queue precise.
137
138	The return value of this method indicates whether the event queue shall
139	delete the object. This does not override the IsAutoDelete() value. If
140	IsAutoDelete() is \c true, then the object is deleted regardless of this
141	method's return value, but if IsAutoDelete() is \c false, this method's
142	return value is taken into consideration. To be precise the logical OR
143	of IsAutoDelete() and the return value of Do() specifies whether the
144	object shall be deleted. The reason for this handling is that there are
145	usally two kind of events: "one-shot" events and those that are reused
146	periodically or from time to time. The first kind can simply be
147	constructed with "auto delete" set to \c true and doesn't need to care
148	about Do()'s return value. The second kind shall usually not be deleted,
149	but during the execution of Do() it might turn out, that it the would be
150	a good idea to let it be deleted by the event queue.
151	BTW, the event may as well delete itself in Do(); that is not a very
152	nice practice though.
153
154	\note IsAutoDelete() is checked by the event queue before Do() is invoked.
155		  Thus changing it in Do() won't have any effect.
156
157	If it is not deleted, the event can re-push itself into the queue
158	within Do().
159
160	\note The event queue is not locked when this method is invoked and it
161		  doesn't contain the event anymore.
162
163	\param queue The event queue executing the event.
164	\return \c true, if the event shall be deleted by the event queue,
165			\c false, if IsAutoDelete() shall be checked for this decision.
166*/
167bool
168Event::Do(EventQueue *queue)
169{
170	return fAutoDelete;
171}
172
173