//
// Event.h
//
// $Id: //poco/Main/XML/include/DOM/Event.h#5 $
//
// Definition of the DOM Event class.
//
// Copyright (c) 2004, Guenter Obiltschnig/Applied Informatics.
// All rights reserved.
// 
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions
// are met:
// 
// 1. Redistributions of source code must retain the above copyright
//    notice, this list of conditions and the following disclaimer.
// 
// 2. Redistributions in binary form must reproduce the above copyright
//    notice, this list of conditions and the following disclaimer in the
//    documentation and/or other materials provided with the distribution.
// 
// 3. Redistributions in any form must be accompanied by information on
//    how to obtain complete source code for this software and any
//    accompanying software that uses this software.  The source code
//    must either be included in the distribution or be available for no
//    more than the cost of distribution plus a nominal fee, and must be
//    freely redistributable under reasonable conditions.  For an
//    executable file, complete source code means the source code for all
//    modules it contains.  It does not include source code for modules or
//    files that typically accompany the major components of the operating
//    system on which the executable file runs.
// 
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
// FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
// COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
// INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
// BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
// LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
// CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
// LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
// ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
// POSSIBILITY OF SUCH DAMAGE.
//


#ifndef DOM_Event_INCLUDED
#define DOM_Event_INCLUDED


#ifndef XML_XML_INCLUDED
#include "XML/XML.h"
#endif
#ifndef XML_XMLString_INCLUDED
#include "XML/XMLString.h"
#endif
#ifndef DOM_DOMObject_INCLUDED
#include "DOM/DOMObject.h"
#endif


XML_BEGIN


class EventTarget;
class Document;


class XML_API Event: public DOMObject
	/// The Event interface is used to provide contextual information about an event
	/// to the handler processing the event. An object which implements the Event
	/// interface is generally passed as the first parameter to an event handler.
	/// More specific context information is passed to event handlers by deriving
	/// additional interfaces from Event which contain information directly relating
	/// to the type of event they accompany. These derived interfaces are also implemented
	/// by the object passed to the event listener.
{
public:
	enum PhaseType
	{
		CAPTURING_PHASE = 1, /// The event is currently being evaluated at the target EventTarget. 
		AT_TARGET       = 2, /// The current event phase is the bubbling phase. 
		BUBBLING_PHASE  = 3  /// The current event phase is the capturing phase. 
	};

	const XMLString& type() const;
		/// The name of the event (case-insensitive). The name must be an XML name.

	EventTarget* target() const;
		/// Used to indicate the EventTarget to which the event was originally dispatched.

	EventTarget* currentTarget() const;
		/// Used to indicate the EventTarget whose EventListeners are currently being 
		/// processed. This is particularly useful during capturing and bubbling.

	PhaseType eventPhase() const;
		/// Used to indicate which phase of event flow is currently being evaluated.

	bool bubbles() const;
		/// Used to indicate whether or not an event is a bubbling event. 
		/// If the event can bubble the value is true, else the value is false.

	bool cancelable() const;
		/// Used to indicate whether or not an event can have its default action 
		/// prevented. If the default action can be prevented the value is
		/// true, else the value is false.

	Foundation::UInt64 timeStamp() const;
		/// Used to specify the time (in milliseconds relative to the epoch) at 
		/// which the event was created. Due to the fact that some
		/// systems may not provide this information the value of timeStamp may 
		/// be not available for all events. When not available, a
		/// value of 0 will be returned. Examples of epoch time are the time of the 
		/// system start or 0:0:0 UTC 1st January 1970.
		/// This implementation always returns 0.

	void stopPropagation();
		/// The stopPropagation method is used prevent further propagation of an 
		/// event during event flow. If this method is called by
		/// any EventListener the event will cease propagating through the tree. 
		/// The event will complete dispatch to all listeners on the
		/// current EventTarget before event flow stops. This method may be used 
		/// during any stage of event flow. 

	void preventDefault();
		/// If an event is cancelable, the preventDefault method is used to signify 
		/// that the event is to be canceled, meaning any default
		/// action normally taken by the implementation as a result of 
		/// the event will not occur. If, during any stage of event flow, the
		/// preventDefault method is called the event is canceled. Any default 
		/// action associated with the event will not occur. Calling
		/// this method for a non-cancelable event has no effect. Once 
		/// preventDefault has been called it will remain in effect throughout
		/// the remainder of the event's propagation. This method may be 
		/// used during any stage of event flow. 

	void initEvent(const XMLString& eventType, bool canBubble, bool isCancelable);
		/// The initEvent method is used to initialize the value of an 
		/// Event created through the DocumentEvent interface. This method
		/// may only be called before the Event has been dispatched via the 
		/// dispatchEvent method, though it may be called multiple
		/// times during that phase if necessary. If called multiple 
		/// times the final invocation takes precedence. If called from 
		/// a subclass of Event interface only the values specified in the 
		/// initEvent method are modified, all other attributes are left unchanged. 

	void autoRelease();

protected:
	Event(Document* pOwnerDocument, const XMLString& type);
	Event(Document* pOwnerDocument, const XMLString& type, EventTarget* pTarget, bool canBubble, bool isCancelable);
	~Event();

	bool isCanceled() const;
		/// returns true if and only if the event has been cancelled.

	bool isStopped() const;
		/// returns true if and only if propagation of the event has been stopped.

	void setTarget(EventTarget* pTarget);
		/// sets the target

	void setCurrentPhase(PhaseType phase);
		/// sets the current phase

	void setCurrentTarget(EventTarget* pTarget);
		/// sets the current target

private:
	Document*    _pOwner;
	XMLString    _type;
	EventTarget* _pTarget;
	EventTarget* _pCurrentTarget;
	PhaseType    _currentPhase;
	bool         _bubbles;
	bool         _cancelable;
	bool         _canceled;
	bool         _stopped;
	
	friend class AbstractNode;
};


//
// inlines
//
inline const XMLString& Event::type() const
{
	return _type;
}


inline EventTarget* Event::target() const
{
	return _pTarget;
}


inline EventTarget* Event::currentTarget() const
{
	return _pCurrentTarget;
}


inline Event::PhaseType Event::eventPhase() const
{
	return _currentPhase;
}


inline bool Event::bubbles() const
{
	return _bubbles;
}


inline bool Event::cancelable() const
{
	return _cancelable;
}


inline Foundation::UInt64 Event::timeStamp() const
{
	return 0;
}


inline bool Event::isCanceled() const
{
	return _canceled;
}


inline bool Event::isStopped() const
{
	return _stopped;
}


XML_END


#endif // DOM_Event_INCLUDED