← Back to branch summary

~ubuntu-branches/ubuntu/gutsy/poco/gutsy

« back to all changes in this revision

Viewing changes to XML/include/Poco/DOM/Event.h

  • Committer: Bazaar Package Importer
  • Author(s): Krzysztof Burghardt
  • Date: 2007-04-27 18:33:48 UTC
  • Revision ID: james.westby@ubuntu.com-20070427183348-xgnpct0qd6a2ip34
Tags: upstream-1.2.9
Import upstream version 1.2.9

Show diffs side-by-side

added added

removed removed

Lines of Context:
XML/include/Poco/DOM/Event.h
 
1
//
 
2
// Event.h
 
3
//
 
4
// $Id: //poco/1.2/XML/include/Poco/DOM/Event.h#1 $
 
5
//
 
6
// Library: XML
 
7
// Package: DOM
 
8
// Module:  DOMEvents
 
9
//
 
10
// Definition of the DOM Event class.
 
11
//
 
12
// Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH.
 
13
// and Contributors.
 
14
//
 
15
// Permission is hereby granted, free of charge, to any person or organization
 
16
// obtaining a copy of the software and accompanying documentation covered by
 
17
// this license (the "Software") to use, reproduce, display, distribute,
 
18
// execute, and transmit the Software, and to prepare derivative works of the
 
19
// Software, and to permit third-parties to whom the Software is furnished to
 
20
// do so, all subject to the following:
 
21
// 
 
22
// The copyright notices in the Software and this entire statement, including
 
23
// the above license grant, this restriction and the following disclaimer,
 
24
// must be included in all copies of the Software, in whole or in part, and
 
25
// all derivative works of the Software, unless such copies or derivative
 
26
// works are solely in the form of machine-executable object code generated by
 
27
// a source language processor.
 
28
// 
 
29
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 
30
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 
31
// FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
 
32
// SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
 
33
// FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
 
34
// ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 
35
// DEALINGS IN THE SOFTWARE.
 
36
//
 
37
 
 
38
 
 
39
#ifndef DOM_Event_INCLUDED
 
40
#define DOM_Event_INCLUDED
 
41
 
 
42
 
 
43
#include "Poco/XML/XML.h"
 
44
#include "Poco/XML/XMLString.h"
 
45
#include "Poco/DOM/DOMObject.h"
 
46
 
 
47
 
 
48
namespace Poco {
 
49
namespace XML {
 
50
 
 
51
 
 
52
class EventTarget;
 
53
class Document;
 
54
 
 
55
 
 
56
class XML_API Event: public DOMObject
 
57
        /// The Event interface is used to provide contextual information about an event
 
58
        /// to the handler processing the event. An object which implements the Event
 
59
        /// interface is generally passed as the first parameter to an event handler.
 
60
        /// More specific context information is passed to event handlers by deriving
 
61
        /// additional interfaces from Event which contain information directly relating
 
62
        /// to the type of event they accompany. These derived interfaces are also implemented
 
63
        /// by the object passed to the event listener.
 
64
{
 
65
public:
 
66
        enum PhaseType
 
67
        {
 
68
                CAPTURING_PHASE = 1, /// The event is currently being evaluated at the target EventTarget. 
 
69
                AT_TARGET       = 2, /// The current event phase is the bubbling phase. 
 
70
                BUBBLING_PHASE  = 3  /// The current event phase is the capturing phase. 
 
71
        };
 
72
 
 
73
        const XMLString& type() const;
 
74
                /// The name of the event (case-insensitive). The name must be an XML name.
 
75
 
 
76
        EventTarget* target() const;
 
77
                /// Used to indicate the EventTarget to which the event was originally dispatched.
 
78
 
 
79
        EventTarget* currentTarget() const;
 
80
                /// Used to indicate the EventTarget whose EventListeners are currently being 
 
81
                /// processed. This is particularly useful during capturing and bubbling.
 
82
 
 
83
        PhaseType eventPhase() const;
 
84
                /// Used to indicate which phase of event flow is currently being evaluated.
 
85
 
 
86
        bool bubbles() const;
 
87
                /// Used to indicate whether or not an event is a bubbling event. 
 
88
                /// If the event can bubble the value is true, else the value is false.
 
89
 
 
90
        bool cancelable() const;
 
91
                /// Used to indicate whether or not an event can have its default action 
 
92
                /// prevented. If the default action can be prevented the value is
 
93
                /// true, else the value is false.
 
94
 
 
95
        Poco::UInt64 timeStamp() const;
 
96
                /// Used to specify the time (in milliseconds relative to the epoch) at 
 
97
                /// which the event was created. Due to the fact that some
 
98
                /// systems may not provide this information the value of timeStamp may 
 
99
                /// be not available for all events. When not available, a
 
100
                /// value of 0 will be returned. Examples of epoch time are the time of the 
 
101
                /// system start or 0:0:0 UTC 1st January 1970.
 
102
                /// This implementation always returns 0.
 
103
 
 
104
        void stopPropagation();
 
105
                /// The stopPropagation method is used prevent further propagation of an 
 
106
                /// event during event flow. If this method is called by
 
107
                /// any EventListener the event will cease propagating through the tree. 
 
108
                /// The event will complete dispatch to all listeners on the
 
109
                /// current EventTarget before event flow stops. This method may be used 
 
110
                /// during any stage of event flow. 
 
111
 
 
112
        void preventDefault();
 
113
                /// If an event is cancelable, the preventDefault method is used to signify 
 
114
                /// that the event is to be canceled, meaning any default
 
115
                /// action normally taken by the implementation as a result of 
 
116
                /// the event will not occur. If, during any stage of event flow, the
 
117
                /// preventDefault method is called the event is canceled. Any default 
 
118
                /// action associated with the event will not occur. Calling
 
119
                /// this method for a non-cancelable event has no effect. Once 
 
120
                /// preventDefault has been called it will remain in effect throughout
 
121
                /// the remainder of the event's propagation. This method may be 
 
122
                /// used during any stage of event flow. 
 
123
 
 
124
        void initEvent(const XMLString& eventType, bool canBubble, bool isCancelable);
 
125
                /// The initEvent method is used to initialize the value of an 
 
126
                /// Event created through the DocumentEvent interface. This method
 
127
                /// may only be called before the Event has been dispatched via the 
 
128
                /// dispatchEvent method, though it may be called multiple
 
129
                /// times during that phase if necessary. If called multiple 
 
130
                /// times the final invocation takes precedence. If called from 
 
131
                /// a subclass of Event interface only the values specified in the 
 
132
                /// initEvent method are modified, all other attributes are left unchanged. 
 
133
 
 
134
        void autoRelease();
 
135
 
 
136
protected:
 
137
        Event(Document* pOwnerDocument, const XMLString& type);
 
138
        Event(Document* pOwnerDocument, const XMLString& type, EventTarget* pTarget, bool canBubble, bool isCancelable);
 
139
        ~Event();
 
140
 
 
141
        bool isCanceled() const;
 
142
                /// returns true if and only if the event has been cancelled.
 
143
 
 
144
        bool isStopped() const;
 
145
                /// returns true if and only if propagation of the event has been stopped.
 
146
 
 
147
        void setTarget(EventTarget* pTarget);
 
148
                /// sets the target
 
149
 
 
150
        void setCurrentPhase(PhaseType phase);
 
151
                /// sets the current phase
 
152
 
 
153
        void setCurrentTarget(EventTarget* pTarget);
 
154
                /// sets the current target
 
155
 
 
156
private:
 
157
        Document*    _pOwner;
 
158
        XMLString    _type;
 
159
        EventTarget* _pTarget;
 
160
        EventTarget* _pCurrentTarget;
 
161
        PhaseType    _currentPhase;
 
162
        bool         _bubbles;
 
163
        bool         _cancelable;
 
164
        bool         _canceled;
 
165
        bool         _stopped;
 
166
        
 
167
        friend class AbstractNode;
 
168
};
 
169
 
 
170
 
 
171
//
 
172
// inlines
 
173
//
 
174
inline const XMLString& Event::type() const
 
175
{
 
176
        return _type;
 
177
}
 
178
 
 
179
 
 
180
inline EventTarget* Event::target() const
 
181
{
 
182
        return _pTarget;
 
183
}
 
184
 
 
185
 
 
186
inline EventTarget* Event::currentTarget() const
 
187
{
 
188
        return _pCurrentTarget;
 
189
}
 
190
 
 
191
 
 
192
inline Event::PhaseType Event::eventPhase() const
 
193
{
 
194
        return _currentPhase;
 
195
}
 
196
 
 
197
 
 
198
inline bool Event::bubbles() const
 
199
{
 
200
        return _bubbles;
 
201
}
 
202
 
 
203
 
 
204
inline bool Event::cancelable() const
 
205
{
 
206
        return _cancelable;
 
207
}
 
208
 
 
209
 
 
210
inline Poco::UInt64 Event::timeStamp() const
 
211
{
 
212
        return 0;
 
213
}
 
214
 
 
215
 
 
216
inline bool Event::isCanceled() const
 
217
{
 
218
        return _canceled;
 
219
}
 
220
 
 
221
 
 
222
inline bool Event::isStopped() const
 
223
{
 
224
        return _stopped;
 
225
}
 
226
 
 
227
 
 
228
} } // namespace Poco::XML
 
229
 
 
230
 
 
231
#endif // DOM_Event_INCLUDED