source: XMLIO_V2/external/include/Poco/DOM/Event.h @ 80

//
// Event.h
//
// $Id: //poco/1.3/XML/include/Poco/DOM/Event.h#1 $
//
// Library: XML
// Package: DOM
// Module:  DOMEvents
//
// Definition of the DOM Event class.
//
// Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH.
// and Contributors.
//
// Permission is hereby granted, free of charge, to any person or organization
// obtaining a copy of the software and accompanying documentation covered by
// this license (the "Software") to use, reproduce, display, distribute,
// execute, and transmit the Software, and to prepare derivative works of the
// Software, and to permit third-parties to whom the Software is furnished to
// do so, all subject to the following:
// 
// The copyright notices in the Software and this entire statement, including
// the above license grant, this restriction and the following disclaimer,
// must be included in all copies of the Software, in whole or in part, and
// all derivative works of the Software, unless such copies or derivative
// works are solely in the form of machine-executable object code generated by
// a source language processor.
// 
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
// SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
// FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
// ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
// DEALINGS IN THE SOFTWARE.
//


#ifndef DOM_Event_INCLUDED
#define DOM_Event_INCLUDED


#include "Poco/XML/XML.h"
#include "Poco/XML/XMLString.h"
#include "Poco/DOM/DOMObject.h"


namespace Poco {
namespace XML {


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.

        Poco::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 Poco::UInt64 Event::timeStamp() const
{
        return 0;
}


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


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


} } // namespace Poco::XML


#endif // DOM_Event_INCLUDED