Logo Search packages:      
Sourcecode: poco version File versions  Download package

Event.h

//
// Event.h
//
// $Id: //poco/1.2/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;


00056 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:
00066       enum PhaseType
      {
            CAPTURING_PHASE = 1, /// The event is currently being evaluated at the target EventTarget. 
00069             AT_TARGET       = 2, /// The current event phase is the bubbling phase. 
00070             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:
00157       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;
}


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


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


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


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


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


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


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


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


} } // namespace Poco::XML


#endif // DOM_Event_INCLUDED

Generated by  Doxygen 1.6.0   Back to index