From: ishmal Date: Thu, 24 Apr 2008 16:23:53 +0000 (+0000) Subject: Add some Event documentation to be more respectable ^^ X-Git-Url: https://git.tokkee.org/?a=commitdiff_plain;h=21def246a6ee757c71c434e271be82cdf35b9ea9;p=inkscape.git Add some Event documentation to be more respectable ^^ --- diff --git a/src/dom/events.h b/src/dom/events.h index c19c2bdc5..1fd77890c 100644 --- a/src/dom/events.h +++ b/src/dom/events.h @@ -28,6 +28,16 @@ * You should have received a copy of the GNU Lesser General Public * License along with this library; if not, write to the Free Software * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA + * + * ======================================================================== + * NOTES + * + * This Events API follows somewhat this specification: + * http://www.w3.org/TR/2003/NOTE-DOM-Level-3-Events-20031107/events.html + * + * Some of the comments are excerpted from that document. + * + * */ @@ -73,12 +83,29 @@ class MutationNameEvent; #########################################################################*/ /** - * + * Event operations may throw an EventException as specified in their + * method descriptions. */ class EventException { public: + /** + * An integer indicating the type of error generated. + */ + typedef enum + { + UNSPECIFIED_EVENT_TYPE_ERR = 0, + DISPATCH_REQUEST_ERR = 1 + } EventExceptionCode; + + unsigned short code; + + + //################## + //# Non-API methods + //################## + EventException(short theCode) { code = theCode; @@ -87,17 +114,8 @@ public: virtual ~EventException() throw() {} - unsigned short code; }; - /** - * EventExceptionCode - */ - enum - { - UNSPECIFIED_EVENT_TYPE_ERR = 0, - DISPATCH_REQUEST_ERR = 1 - }; @@ -106,14 +124,24 @@ public: #########################################################################*/ /** - * + * The Event interface is used to provide contextual information about an event + * to the listener processing the event. An object which implements the Event + * interface is passed as the parameter to an EventListener. More specific + * context information is passed to event listeners by deriving additional + * interfaces from Event which contain information directly relating to the type + * of event they represent. These derived interfaces are also implemented by the + * object passed to the event listener. + * + * To create an instance of the Event interface, use the + * DocumentEvent.createEvent("Event") method call. */ class Event { public: /** - * PhaseType + * An integer indicating which phase of the event flow is being processed + * as defined in DOM event flow. */ typedef enum { @@ -123,63 +151,96 @@ public: } PhaseType; /** - * + * The name should be an NCName as defined in [XML Namespaces] and is + * case-sensitive. + * If the attribute Event.namespaceURI is different from null, this + * attribute represents a local name. */ virtual DOMString getType() const { return eventType; } /** - * + * Used to indicate the event target. This attribute contains the target + * node when used with the DOM event flow. */ virtual EventTarget *getTarget() { return target; } /** - * + * Used to indicate the EventTarget whose EventListeners are currently + * being processed. This is particularly useful during the capture and + * bubbling phases. This attribute could contain the target node or a + * target ancestor when used with the DOM event flow. */ virtual EventTarget *getCurrentTarget() { return currentTarget; } /** - * + * Used to indicate which phase of event flow is currently being accomplished. */ virtual unsigned short getEventPhase() { return eventPhase; } /** - * + * Used to indicate whether or not an event is a bubbling event. If the + * event can bubble the value is true, otherwise the value is false. */ virtual bool getBubbles() { return canBubble; } /** - * + * Used to indicate whether or not an event can have its default action + * prevented (see also Default actions and cancelable events). If the + * default action can be prevented the value is true, otherwise the + * value is false. */ virtual bool getCancelable() { return cancelable; } /** - * + * 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. */ virtual DOMTimeStamp getTimeStamp() { return timeStamp; } - /** - * + /** + * This method is used to prevent event listeners of the same group to be + * triggered but its effect is deferred until all event listeners attached on the + * currentTarget have been triggered (see Event propagation and event groups). + * Once it has been called, further calls to that method have no additional effect. */ virtual void stopPropagation() { } /** - * + * 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 (see also Default + * actions and cancelable events), and thus independently of event groups. + * Calling this method for a non-cancelable event has no effect. */ virtual void preventDefault() { } /** - * + * The initEvent method is used to initialize the value of an Event created + * through the DocumentEvent.createEvent method. This method may only be called + * before the Event has been dispatched via the EventTarget.dispatchEvent() + * method. If the method is called several times before invoking + * EventTarget.dispatchEvent, only the final invocation takes precedence. This + * method has no effect if called after the event has been dispatched. If called + * from a subclass of the Event interface only the values specified in this + * method are modified, all other attributes are left unchanged. + * + * This method sets the Event.type attribute to eventTypeArg, and + * Event.namespaceURI to null. To initialize an event with a namespace URI, use + * the Event.initEventNS(namespaceURIArg, eventTypeArg, ...) method. */ virtual void initEvent(const DOMString &eventTypeArg, bool canBubbleArg, @@ -193,32 +254,42 @@ public: /** - * + * The namespace URI associated with this event at creation time, or + * null if it is unspecified. */ virtual DOMString getNamespaceURI() const { return namespaceURI; } /** - * + * This method will always return false, unless the event implements + * the CustomEvent interface. */ virtual bool isCustom() { return custom; } /** - * + * This method is used to prevent event listeners of the same group to be + * triggered and, unlike stopPropagation its effect is immediate (see Event + * propagation and event groups). Once it has been called, further calls to that + * method have no additional effect. + * + * Note: This method does not prevent the default action from being invoked; use + * Event.preventDefault() for that effect. */ virtual void stopImmediatePropagation() { } /** - * + * This method will return true if the method Event.preventDefault() + * has been called for this event, false otherwise. */ virtual bool isDefaultPrevented() { return defaultPrevented; } /** - * + * The initEventNS method is used to initialize the value of an Event + * object and has the same behavior as Event.initEvent(). */ virtual void initEventNS(const DOMString &namespaceURIArg, const DOMString &eventTypeArg, @@ -315,14 +386,25 @@ protected: #########################################################################*/ /** - * + * The EventListener interface is the primary way for handling events. Users + * implement the EventListener interface and register their event listener on an + * EventTarget. The users should also remove their EventListener from its + * EventTarget after they have completed using the listener. + * + * Copying a Node, with methods such as Node.cloneNode or Range.cloneContents, + * does not copy the event listeners attached to it. Event listeners must be + * attached to the newly created Node afterwards if so desired. + * + * Moving a Node, with methods Document.adoptNode, Node.appendChild, or + * Range.extractContents, does not affect the event listeners attached to it. */ class EventListener { public: /** - * + * This method is called whenever an event occurs of the event type + * for which the EventListener interface was registered. */ virtual void handleEvent(const Event &/*evt*/) {} @@ -346,46 +428,69 @@ public: ## EventTarget #########################################################################*/ -class EventListenerEntry -{ -public: - EventListenerEntry(const DOMString &namespaceURIArg, - const DOMString &eventTypeArg, - const EventListener *listenerArg, - bool useCaptureArg) - { - namespaceURI = namespaceURIArg; - eventType = eventTypeArg; - listener = (EventListener *)listenerArg; - useCapture = useCaptureArg; - } - - EventListenerEntry(const EventListenerEntry &other) - { - namespaceURI = other.namespaceURI; - eventType = other.eventType; - listener = other.listener; - useCapture = other.useCapture; - } - - virtual ~EventListenerEntry() {} - - DOMString namespaceURI; - DOMString eventType; - EventListener *listener; - bool useCapture; -}; - /** - * + * The EventTarget interface is implemented by all the objects which could be + * event targets in an implementation which supports the Event flows. The + * interface allows registration, removal or query of event listeners, and + * dispatch of events to an event target. + * + * When used with DOM event flow, this interface is implemented by all target + * nodes and target ancestors, i.e. all DOM Nodes of the tree support this + * interface when the implementation conforms to DOM Level 3 Events and, + * therefore, this interface can be obtained by using binding-specific casting + * methods on an instance of the Node interface. + * + * Invoking addEventListener or addEventListenerNS multiple times on the same + * EventTarget with the same parameters (namespaceURI, type, listener, and + * useCapture) is considered to be a no-op and thus independently of the event + * group. They do not cause the EventListener to be called more than once and do + * not cause a change in the triggering order. In order to guarantee that an + * event listener will be added to the event target for the specified event group, + * one needs to invoke removeEventListener or removeEventListenerNS first. */ class EventTarget { +private: + + class EventListenerEntry + { + public: + EventListenerEntry(const DOMString &namespaceURIArg, + const DOMString &eventTypeArg, + const EventListener *listenerArg, + bool useCaptureArg) + { + namespaceURI = namespaceURIArg; + eventType = eventTypeArg; + listener = (EventListener *)listenerArg; + useCapture = useCaptureArg; + } + + EventListenerEntry(const EventListenerEntry &other) + { + namespaceURI = other.namespaceURI; + eventType = other.eventType; + listener = other.listener; + useCapture = other.useCapture; + } + + virtual ~EventListenerEntry() {} + + DOMString namespaceURI; + DOMString eventType; + EventListener *listener; + bool useCapture; + }; + + + public: /** - * + * This method allows the registration of an event listener in the default group + * and, depending on the useCapture parameter, on the capture phase of the DOM + * event flow or its target and bubbling phases. */ virtual void addEventListener(const DOMString &type, const EventListener *listener, @@ -396,7 +501,9 @@ public: } /** - * + * This method allows the removal of event listeners from the default group. + * Calling removeEventListener with arguments which do not identify any currently + * registered EventListener on the EventTarget has no effect. */ virtual void removeEventListener(const DOMString &type, const EventListener *listener, @@ -414,7 +521,9 @@ public: } /** - * + * This method allows the dispatch of events into the implementation's event + * model. The event target of the event is the EventTarget object on which + * dispatchEvent is called. */ virtual bool dispatchEvent(const Event &evt) throw(EventException) { @@ -434,7 +543,9 @@ public: /** - * + * This method allows the registration of an event listener in a specified group + * or the default group and, depending on the useCapture parameter, on the + * capture phase of the DOM event flow or its target and bubbling phases. */ virtual void addEventListenerNS(const DOMString &namespaceURI, const DOMString &type, @@ -446,7 +557,10 @@ public: } /** - * + * This method allows the removal of an event listener, independently of the + * associated event group. + * Calling removeEventListenerNS with arguments which do not identify any + * currently registered EventListener on the EventTarget has no effect. */ virtual void removeEventListenerNS(const DOMString &namespaceURI, const DOMString &type, @@ -466,7 +580,10 @@ public: } /** - * + * This method allows the DOM application to know if an event listener, attached + * to this EventTarget or one of its ancestors, will be triggered by the + * specified event type during the dispatch of the event to this event target or + * one of its descendants. */ virtual bool willTriggerNS(const DOMString &namespaceURI, const DOMString &type) @@ -483,7 +600,12 @@ public: } /** - * + * This method allows the DOM application to know if this EventTarget contains an + * event listener registered for the specified event type. This is useful for + * determining at which nodes within a hierarchy altered handling of specific + * event types has been introduced, but should not be used to determine whether + * the specified event type triggers an event listener (see + * EventTarget.willTriggerNS()). */ virtual bool hasEventListenerNS(const DOMString &namespaceURI, const DOMString &type) @@ -535,15 +657,21 @@ protected: ## DocumentEvent #########################################################################*/ -/* - * +/** + * The DocumentEvent interface provides a mechanism by which the user can create + * an Event object of a type supported by the implementation. If the feature + * "Events" is supported by the Document object, the DocumentEvent interface must + * be implemented on the same object. If the feature "+Events" is supported by + * the Document object, an object that supports the DocumentEvent interface must + * be returned by invoking the method Node.getFeature("+Events", "3.0") on the + * Document object. */ class DocumentEvent : virtual public Event { public: /** - * + * Create an event with the current document */ virtual Event createEvent(const DOMString &/*eventType*/) throw (dom::DOMException) @@ -553,7 +681,7 @@ public: } /** - * + * Test if the implementation can generate events of a specified type. */ virtual bool canDispatch(const DOMString &/*namespaceURI*/, const DOMString &/*type*/) @@ -595,15 +723,32 @@ protected: ## CustomEvent #########################################################################*/ -/* - * - */ +/** + * The CustomEvent interface gives access to the attributes Event.currentTarget + * and Event.eventPhase. It is intended to be used by the DOM Events + * implementation to access the underlying current target and event phase while + * dispatching a custom Event in the tree; it is also intended to be implemented, + * and not used, by DOM applications. + * + * The methods contained in this interface are not intended to be used by a DOM + * application, especially during the dispatch on the Event object. Changing the + * current target or the current phase may result in unpredictable results of the + * event flow. The DOM Events implementation should ensure that both methods + * return the appropriate current target and phase before invoking each event + * listener on the current target to protect DOM applications from malicious + * event listeners. + * + * Note: If this interface is supported by the event object, Event.isCustom() + * must return true. +*/ class CustomEvent : virtual public Event { public: /** - * + * The setDispatchState method is used by the DOM Events implementation to set + * the values of Event.currentTarget and Event.eventPhase. It also reset the + * states of isPropagationStopped and isImmediatePropagationStopped. */ virtual void setDispatchState(const EventTarget */*target*/, unsigned short /*phase*/) @@ -611,7 +756,8 @@ public: } /** - * + * This method will return true if the method stopPropagation() has been + * called for this event, false in any other cases. */ virtual bool isPropagationStopped() { @@ -619,13 +765,17 @@ public: } /** - * + * The isImmediatePropagationStopped method is used by the DOM Events + * implementation to know if the method stopImmediatePropagation() has been + * called for this event. It returns true if the method has been called, false + * otherwise. */ virtual bool isImmediatePropagationStopped() { return immediatePropagationStopped; } + //################## //# Non-API methods //################## @@ -666,26 +816,37 @@ protected: #########################################################################*/ /** - * + * The UIEvent interface provides specific contextual information associated with + * User Interface events. + * + * To create an instance of the UIEvent interface, use the + * DocumentEvent.createEvent("UIEvent") method call. + * + * NOTE: + * For dom level 2 and 3, note that views.idl and events.idl disagree on the + * name of Views. We are using level -2- Views */ class UIEvent : virtual public Event { public: /** - * Note that the return type is level -2- views + * The view attribute identifies the AbstractView from which the + * event was generated. */ virtual views::AbstractView getView() { return view; } /** - * + * Specifies some detail information about the Event, depending on + * the type of event. */ virtual long getDetail() { return detail; } /** - * Note that views.idl and events.idl disagree on the name of Views + * The initUIEvent method is used to initialize the value of a UIEvent object and + * has the same behavior as Event.initEvent(). */ virtual void initUIEvent(const DOMString &/*typeArg*/, bool /*canBubbleArg*/, @@ -696,7 +857,8 @@ public: } /** - * Note that views.idl and events.idl disagree on the name of Views + * The initUIEventNS method is used to initialize the value of a UIEvent object + * and has the same behavior as Event.initEventNS(). */ virtual void initUIEventNS(const DOMString &/*namespaceURI*/, const DOMString &/*typeArg*/, @@ -743,21 +905,31 @@ protected: ## TextEvent #########################################################################*/ -/** +/** + * The TextEvent interface provides specific contextual information associated + * with Text Events. * + * To create an instance of the TextEvent interface, use the + * DocumentEvent.createEvent("TextEvent") method call. */ class TextEvent : virtual public UIEvent { public: /** - * + * data holds the value of the characters generated by the character device. This + * may be a single Unicode character or a non-empty sequence of Unicode + * characters [Unicode]. Characters should be normalized as defined by the + * Unicode normalization form NFC, defined in [UTR #15]. This attribute cannot be + * null or contain the empty string. */ virtual DOMString getData() { return data; } /** - * Note that views.idl and events.idl disagree on the name of Views + * The initTextEvent method is used to initialize the value of a TextEvent object + * and has the same behavior as UIEvent.initUIEvent(). The value of + * UIEvent.detail remains undefined. */ virtual void initTextEvent(const DOMString &/*typeArg*/, bool /*canBubbleArg*/, @@ -768,7 +940,9 @@ public: } /** - * + * The initTextEventNS method is used to initialize the value of a TextEvent + * object and has the same behavior as UIEvent.initUIEventNS(). The value of + * UIEvent.detail remains undefined. */ virtual void initTextEventNS(const DOMString &/*namespaceURI*/, const DOMString &/*typeArg*/, @@ -819,81 +993,109 @@ protected: #########################################################################*/ /** - * + * The MouseEvent interface provides specific contextual information associated + * with Mouse events. + * + * In the case of nested elements mouse events are always targeted at the most + * deeply nested element. Ancestors of the targeted element may use bubbling to + * obtain notification of mouse events which occur within theirs descendent + * elements. + * + * To create an instance of the MouseEvent interface, use the + * DocumentEvent.createEvent("MouseEvent") method call. */ class MouseEvent : virtual public UIEvent { public: /** - * + * The horizontal coordinate at which the event occurred relative to the + * origin of the screen coordinate system. */ virtual long getScreenX() { return screenX; } /** - * + * The vertical coordinate at which the event occurred relative to the + * origin of the screen coordinate system. */ virtual long getScreenY() { return screenY; } /** - * + * The horizontal coordinate at which the event occurred relative to the + * DOM implementation's client area. */ virtual long getClientX() { return clientX; } /** - * + * The vertical coordinate at which the event occurred relative to the + * DOM implementation's client area. */ virtual long getClientY() { return clientY; } /** - * + * true if the control (Ctrl) key modifier is activated. */ virtual bool getCtrlKey() { return ctrlKey; } /** - * + * true if the shift (Shift) key modifier is activated. */ virtual bool getShiftKey() { return shiftKey; } /** - * + * true if the alt (alternative) key modifier is activated. */ virtual bool getAltKey() { return altKey; } /** - * + * true if the meta (Meta) key modifier is activated. */ virtual bool getMetaKey() { return metaKey; } /** - * + * During mouse events caused by the depression or release of a mouse button, + * button is used to indicate which mouse button changed state. 0 indicates the + * normal button of the mouse (in general on the left or the one button on + * Macintosh mice, used to activate a button or select text). 2 indicates the + * contextual property (in general on the right, used to display a context menu) + * button of the mouse if present. 1 indicates the extra (in general in the + * middle and often combined with the mouse wheel) button. Some mice may provide + * or simulate more buttons, and values higher than 2 can be used to represent + * such buttons. */ virtual unsigned short getButton() { return button; } /** - * + * Used to identify a secondary EventTarget related to a UI event. Currently this + * attribute is used with the mouseover event to indicate the EventTarget which + * the pointing device exited and with the mouseout event to indicate the + * EventTarget which the pointing device entered. */ virtual EventTarget *getRelatedTarget() { return relatedTarget; } /** - * + * This methods queries the state of a modifier using a key identifier. + * The argument is a modifier key identifier, as defined by the + * KeyboardEvent.keyIdentifier attribute. Common modifier keys are "Alt", + * "AltGraph", "CapsLock", "Control", "Meta", "NumLock", "Scroll", or "Shift". */ - virtual bool getModifierState() - { return modifierState; } + virtual bool getModifierState(const DOMString &/*id*/) + { return false; } /** - * + * The initMouseEvent method is used to initialize the value of a MouseEvent + * object and has the same behavior as UIEvent.initUIEvent(). */ virtual void initMouseEvent(const DOMString &/*typeArg*/, bool /*canBubbleArg*/, @@ -915,7 +1117,8 @@ public: /** - * + * The initMouseEventNS method is used to initialize the value of a + * MouseEvent object and has the same behavior as UIEvent.initUIEventNS(). */ virtual void initMouseEventNS(const DOMString &/*namespaceURI*/, const DOMString &/*typeArg*/, @@ -933,6 +1136,7 @@ public: { } + //################## //# Non-API methods //################## @@ -957,7 +1161,6 @@ public: metaKey = other.metaKey; button = other.button; relatedTarget = other.relatedTarget; - modifierState = other.modifierState; } /** @@ -977,9 +1180,6 @@ protected: bool metaKey; unsigned short button; EventTarget *relatedTarget; - bool modifierState; - - }; @@ -990,12 +1190,30 @@ protected: #########################################################################*/ /** - * + * The KeyboardEvent interface provides specific contextual information + * associated with keyboard devices. Each keyboard event references a key using + * an identifier. Keyboard events are commonly directed at the element that has + * the focus. + * + * The KeyboardEvent interface provides convenient attributes for some common + * modifiers keys: KeyboardEvent.ctrlKey, KeyboardEvent.shiftKey, + * KeyboardEvent.altKey, KeyboardEvent.metaKey. These attributes are equivalent + * to use the method KeyboardEvent.getModifierState(keyIdentifierArg) with + * "Control", "Shift", "Alt", or "Meta" respectively. + * + * To create an instance of the KeyboardEvent interface, use the + * DocumentEvent.createEvent("KeyboardEvent") method call. */ class KeyboardEvent : virtual public UIEvent { public: + /** + * This set of constants is used to indicate the location of a key on + * the device. In case a DOM implementation wishes to provide a new + * location information, a value different from the following constant + * values must be used. + */ typedef enum { DOM_KEY_LOCATION_STANDARD = 0x00, @@ -1005,49 +1223,59 @@ public: } KeyLocationCode; /** - * + * keyIdentifier holds the identifier of the key. + * Key identifiers can be found here: + * http://www.w3.org/TR/2003/NOTE-DOM-Level-3-Events-20031107/keyset.html#KeySet-Set + * Implementations that are unable to identify a key must use the key + * identifier "Unidentified". */ virtual DOMString getKeyIdentifier() { return keyIdentifier; } /** - * + * The keyLocation attribute contains an indication of the location of + * they key on the device, as described in: + * http://www.w3.org/TR/2003/NOTE-DOM-Level-3-Events-20031107/events.html#ID-KeyboardEvent-KeyLocationCode */ virtual unsigned long getKeyLocation() { return keyLocation; } /** - * + * true if the control (Ctrl) key modifier is activated. */ virtual bool getCtrlKey() { return ctrlKey; } /** - * + * true if the shift (Shift) key modifier is activated. */ virtual bool getShiftKey() { return shiftKey; } /** - * + * true if the alternative (Alt) key modifier is activated. */ virtual bool getAltKey() { return altKey; } /** - * + * true if the meta (Meta) key modifier is activated. */ virtual bool getMetaKey() { return metaKey; } /** - * + * This methods queries the state of a modifier using a key identifier. + * The argument is a modifier key identifier. Common modifier keys are "Alt", + * "AltGraph", "CapsLock", "Control", "Meta", "NumLock", "Scroll", or "Shift". */ - virtual bool getModifierState() - { return modifierState; } + virtual bool getModifierState(const DOMString &/*id*/) + { return false; } /** - * + * The initKeyboardEvent method is used to initialize the value of a + * KeyboardEvent object and has the same behavior as UIEvent.initUIEvent(). The + * value of UIEvent.detail remains undefined. */ virtual void initKeyboardEvent(const DOMString &/*typeArg*/, bool /*canBubbleArg*/, @@ -1062,7 +1290,9 @@ public: /** - * + * The initKeyboardEventNS method is used to initialize the value of a + * KeyboardEvent object and has the same behavior as UIEvent.initUIEventNS(). The + * value of UIEvent.detail remains undefined. */ virtual void initKeyboardEventNS(const DOMString &/*namespaceURI*/, const DOMString &/*typeArg*/, @@ -1075,6 +1305,8 @@ public: { } + + //################## //# Non-API methods //################## @@ -1095,7 +1327,6 @@ public: shiftKey = other.shiftKey; altKey = other.altKey; metaKey = other.metaKey; - modifierState = other.modifierState; } /** @@ -1111,7 +1342,6 @@ protected: bool shiftKey; bool altKey; bool metaKey; - bool modifierState; }; @@ -1127,14 +1357,18 @@ protected: #########################################################################*/ /** - * + * The MutationEvent interface provides specific contextual information + * associated with Mutation events. + * + * To create an instance of the MutationEvent interface, use the + * DocumentEvent.createEvent("MutationEvent") method call. */ class MutationEvent : virtual public Event { public: /** - * attrChangeType + * An integer indicating in which way the Attr was changed. */ typedef enum { @@ -1144,31 +1378,46 @@ public: } AttrChangeType; /** - * + * relatedNode is used to identify a secondary node related to a mutation event. + * For example, if a mutation event is dispatched to a node indicating that its + * parent has changed, the relatedNode is the changed parent. If an event is + * instead dispatched to a subtree indicating a node was changed within it, the + * relatedNode is the changed node. In the case of the + * {"http://www.w3.org/2001/xml-events", "DOMAttrModified"} event it indicates + * the Attr node which was modified, added, or removed. */ - virtual NodePtr getRelatedNodePtr () + virtual NodePtr getRelatedNode() { return relatedNodePtr ; } /** - * + * prevValue indicates the previous value of the Attr node in + * {"http://www.w3.org/2001/xml-events", "DOMAttrModified"} events, and of the + * CharacterData node in {"http://www.w3.org/2001/xml-events", + * "DOMCharacterDataModified"} events. */ virtual DOMString getPrevValue() { return prevValue; } /** - * + * newValue indicates the new value of the Attr node in + * {"http://www.w3.org/2001/xml-events", "DOMAttrModified"} events, and of the + * CharacterData node in {"http://www.w3.org/2001/xml-events", + * "DOMCharacterDataModified"} events. */ virtual DOMString getNewValue() { return newValue; } /** - * + * attrName indicates the name of the changed Attr node in a + * {"http://www.w3.org/2001/xml-events", "DOMAttrModified"} event. */ virtual DOMString getAttrName() { return attrName; } /** - * + * attrChange indicates the type of change which triggered the + * {"http://www.w3.org/2001/xml-events", "DOMAttrModified"} event. The values can + * be MODIFICATION, ADDITION, or REMOVAL. */ virtual unsigned short getAttrChange() { @@ -1176,7 +1425,8 @@ public: } /** - * + * The initMutationEvent method is used to initialize the value of a + * MutationEvent object and has the same behavior as Event.initEvent(). */ virtual void initMutationEvent(const DOMString &/*typeArg*/, bool /*canBubbleArg*/, @@ -1190,7 +1440,8 @@ public: } /** - * + * The initMutationEventNS method is used to initialize the value of a + * MutationEvent object and has the same behavior as Event.initEventNS(). */ virtual void initMutationEventNS(const DOMString &/*namespaceURI*/, const DOMString &/*typeArg*/, @@ -1252,26 +1503,32 @@ protected: #########################################################################*/ /** - * + * The MutationNameEvent interface provides specific contextual information + * associated with Mutation name event types. + * + * To create an instance of the MutationNameEvent interface, use the + * Document.createEvent("MutationNameEvent") method call. */ class MutationNameEvent : virtual public MutationEvent { public: /** - * + * The previous value of the relatedNode's namespaceURI. */ virtual DOMString getPrevNamespaceURI() { return prevNamespaceURI; } /** - * + * The previous value of the relatedNode's nodeName. */ virtual DOMString getPrevNodeName() { return prevNodeName; } /** - * + * The initMutationNameEvent method is used to initialize the value of a + * MutationNameEvent object and has the same behavior as + * MutationEvent.initMutationEvent(). */ virtual void initMutationNameEvent(const DOMString &/*typeArg*/, bool /*canBubbleArg*/, @@ -1284,7 +1541,9 @@ public: /** - * + * The initMutationNameEventNS method is used to initialize the value of a + * MutationNameEvent object and has the same behavior as + * MutationEvent.initMutationEventNS(). */ virtual void initMutationNameEventNS(const DOMString &/*namespaceURI*/, const DOMString &/*typeArg*/,