1//
2// Event.h
3//
4// Library: XML
5// Package: DOM
6// Module: DOMEvents
7//
8// Definition of the DOM Event class.
9//
10// Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH.
11// and Contributors.
12//
13// SPDX-License-Identifier: BSL-1.0
14//
15
16
17#ifndef DOM_Event_INCLUDED
18#define DOM_Event_INCLUDED
19
20
21#include "Poco/XML/XML.h"
22#include "Poco/XML/XMLString.h"
23#include "Poco/DOM/DOMObject.h"
24
25
26namespace Poco {
27namespace XML {
28
29
30class EventTarget;
31class Document;
32
33
34class XML_API Event: public DOMObject
35 /// The Event interface is used to provide contextual information about an event
36 /// to the handler processing the event. An object which implements the Event
37 /// interface is generally passed as the first parameter to an event handler.
38 /// More specific context information is passed to event handlers by deriving
39 /// additional interfaces from Event which contain information directly relating
40 /// to the type of event they accompany. These derived interfaces are also implemented
41 /// by the object passed to the event listener.
42{
43public:
44 enum PhaseType
45 {
46 CAPTURING_PHASE = 1, /// The event is currently being evaluated at the target EventTarget.
47 AT_TARGET = 2, /// The current event phase is the bubbling phase.
48 BUBBLING_PHASE = 3 /// The current event phase is the capturing phase.
49 };
50
51 const XMLString& type() const;
52 /// The name of the event (case-insensitive). The name must be an XML name.
53
54 EventTarget* target() const;
55 /// Used to indicate the EventTarget to which the event was originally dispatched.
56
57 EventTarget* currentTarget() const;
58 /// Used to indicate the EventTarget whose EventListeners are currently being
59 /// processed. This is particularly useful during capturing and bubbling.
60
61 PhaseType eventPhase() const;
62 /// Used to indicate which phase of event flow is currently being evaluated.
63
64 bool bubbles() const;
65 /// Used to indicate whether or not an event is a bubbling event.
66 /// If the event can bubble the value is true, else the value is false.
67
68 bool cancelable() const;
69 /// Used to indicate whether or not an event can have its default action
70 /// prevented. If the default action can be prevented the value is
71 /// true, else the value is false.
72
73 Poco::UInt64 timeStamp() const;
74 /// Used to specify the time (in milliseconds relative to the epoch) at
75 /// which the event was created. Due to the fact that some
76 /// systems may not provide this information the value of timeStamp may
77 /// be not available for all events. When not available, a
78 /// value of 0 will be returned. Examples of epoch time are the time of the
79 /// system start or 0:0:0 UTC 1st January 1970.
80 /// This implementation always returns 0.
81
82 void stopPropagation();
83 /// The stopPropagation method is used prevent further propagation of an
84 /// event during event flow. If this method is called by
85 /// any EventListener the event will cease propagating through the tree.
86 /// The event will complete dispatch to all listeners on the
87 /// current EventTarget before event flow stops. This method may be used
88 /// during any stage of event flow.
89
90 void preventDefault();
91 /// If an event is cancelable, the preventDefault method is used to signify
92 /// that the event is to be canceled, meaning any default
93 /// action normally taken by the implementation as a result of
94 /// the event will not occur. If, during any stage of event flow, the
95 /// preventDefault method is called the event is canceled. Any default
96 /// action associated with the event will not occur. Calling
97 /// this method for a non-cancelable event has no effect. Once
98 /// preventDefault has been called it will remain in effect throughout
99 /// the remainder of the event's propagation. This method may be
100 /// used during any stage of event flow.
101
102 void initEvent(const XMLString& eventType, bool canBubble, bool isCancelable);
103 /// The initEvent method is used to initialize the value of an
104 /// Event created through the DocumentEvent interface. This method
105 /// may only be called before the Event has been dispatched via the
106 /// dispatchEvent method, though it may be called multiple
107 /// times during that phase if necessary. If called multiple
108 /// times the final invocation takes precedence. If called from
109 /// a subclass of Event interface only the values specified in the
110 /// initEvent method are modified, all other attributes are left unchanged.
111
112 void autoRelease();
113
114protected:
115 Event(Document* pOwnerDocument, const XMLString& type);
116 Event(Document* pOwnerDocument, const XMLString& type, EventTarget* pTarget, bool canBubble, bool isCancelable);
117 ~Event();
118
119 bool isCanceled() const;
120 /// returns true if and only if the event has been cancelled.
121
122 bool isStopped() const;
123 /// returns true if and only if propagation of the event has been stopped.
124
125 void setTarget(EventTarget* pTarget);
126 /// sets the target
127
128 void setCurrentPhase(PhaseType phase);
129 /// sets the current phase
130
131 void setCurrentTarget(EventTarget* pTarget);
132 /// sets the current target
133
134private:
135 Document* _pOwner;
136 XMLString _type;
137 EventTarget* _pTarget;
138 EventTarget* _pCurrentTarget;
139 PhaseType _currentPhase;
140 bool _bubbles;
141 bool _cancelable;
142 bool _canceled;
143 bool _stopped;
144
145 friend class AbstractNode;
146};
147
148
149//
150// inlines
151//
152inline const XMLString& Event::type() const
153{
154 return _type;
155}
156
157
158inline EventTarget* Event::target() const
159{
160 return _pTarget;
161}
162
163
164inline EventTarget* Event::currentTarget() const
165{
166 return _pCurrentTarget;
167}
168
169
170inline Event::PhaseType Event::eventPhase() const
171{
172 return _currentPhase;
173}
174
175
176inline bool Event::bubbles() const
177{
178 return _bubbles;
179}
180
181
182inline bool Event::cancelable() const
183{
184 return _cancelable;
185}
186
187
188inline Poco::UInt64 Event::timeStamp() const
189{
190 return 0;
191}
192
193
194inline bool Event::isCanceled() const
195{
196 return _canceled;
197}
198
199
200inline bool Event::isStopped() const
201{
202 return _stopped;
203}
204
205
206} } // namespace Poco::XML
207
208
209#endif // DOM_Event_INCLUDED
210