diff options
Diffstat (limited to 'tdehtml/dom/dom2_events.h')
| -rw-r--r-- | tdehtml/dom/dom2_events.h | 846 |
1 files changed, 846 insertions, 0 deletions
diff --git a/tdehtml/dom/dom2_events.h b/tdehtml/dom/dom2_events.h new file mode 100644 index 000000000..285a0c10e --- /dev/null +++ b/tdehtml/dom/dom2_events.h @@ -0,0 +1,846 @@ +/* + * This file is part of the DOM implementation for KDE. + * + * Copyright (C) 2001 Peter Kelly (pmk@post.com) + * (C) 2003 Apple Computer, Inc. + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Library General Public + * License as published by the Free Software Foundation; either + * version 2 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Library General Public License for more details. + * + * You should have received a copy of the GNU Library General Public License + * along with this library; see the file COPYING.LIB. If not, write to + * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + * Boston, MA 02110-1301, USA. + * + */ + +#ifndef _DOM_Events_h_ +#define _DOM_Events_h_ + +#include <dom/dom_node.h> +#include <dom/dom_misc.h> + +namespace DOM { + +class Event; +class EventException; +class UIEvent; +class MouseEvent; +class TextEvent; +class MutationEvent; +class AbstractView; + +class EventListenerImpl; +class EventImpl; +class UIEventImpl; +class MouseEventImpl; +class KeyEventBaseImpl; +class MutationEventImpl; + + + +/** + * Introduced in DOM Level 2 + * + * The EventListener interface is the primary method for handling events. + * Users implement the EventListener interface and register their listener on + * an EventTarget using the AddEventListener method. The users should also + * remove their EventListener from its EventTarget after they have completed + * using the listener. + * + * When a Node is copied using the cloneNode method the EventListeners attached + * to the source Node are not attached to the copied Node. If the user wishes + * the same EventListeners to be added to the newly created copy the user must + * add them manually. + * + */ +class KHTML_EXPORT EventListener : public DomShared { +public: + EventListener(); + virtual ~EventListener(); + + /** + * This method is called whenever an event occurs of the type for which the + * EventListener interface was registered. Parameters + * + * @param evt The Event contains contextual information about the event. It + * also contains the stopPropagation and preventDefault methods which are + * used in determining the event's flow and default action. + * + */ + virtual void handleEvent(Event &evt); + + /** + * @internal + * not part of the DOM + * + * Returns a name specifying the type of listener. Useful for checking + * if an event is of a particular sublass. + * + */ + virtual DOMString eventListenerType(); + +protected: + /** + * @internal + * Reserved. Do not use in your subclasses. + */ + EventListenerImpl *impl; +}; + + +/** + * Introduced in DOM Level 2 + * + * 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. + * + */ +class KHTML_EXPORT Event { + friend class Document; + friend class NodeImpl; + friend class DocumentImpl; +public: + Event(); + Event(const Event &other); + virtual ~Event(); + + Event & operator = (const Event &other); + + /** + * An integer indicating which phase of event flow is being processed. + * + * AT_TARGET: The event is currently being evaluated at the target + * EventTarget. + * + * BUBBLING_PHASE: The current event phase is the bubbling phase. + * + * CAPTURING_PHASE: The current event phase is the capturing phase. + * + */ + enum PhaseType { + CAPTURING_PHASE = 1, + AT_TARGET = 2, + BUBBLING_PHASE = 3 + }; + + /** + * The name of the event (case-insensitive). The name must be an XML name. + * + */ + DOMString type() const; + + /** + * Used to indicate the EventTarget to which the event was originally + * dispatched. + * + */ + Node target() const; + + /** + * Used to indicate the EventTarget whose EventListeners are currently + * being processed. This is particularly useful during capturing and + * bubbling. + * + */ + Node currentTarget() const; + + /** + * Used to indicate which phase of event flow is currently being evaluated. + * + */ + unsigned short eventPhase() 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 bubbles() 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. + * + */ + bool cancelable() 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. + * + */ + DOMTimeStamp timeStamp() const; + + /** + * 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 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. 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 preventDefault(); + + /** + * 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. + * + * @param eventTypeArg Specifies the event type. This type may be any event + * type currently defined in this specification or a new event type.. The + * string must be an XML name. + * + * Any new event type must not begin with any upper, lower, or mixed case + * version of the string "DOM". This prefix is reserved for future DOM + * event sets. It is also strongly recommended that third parties adding + * their own events use their own prefix to avoid confusion and lessen the + * probability of conflicts with other new events. + * + * @param canBubbleArg Specifies whether or not the event can bubble. + * + * @param cancelableArg Specifies whether or not the event's default action can be prevented. + * + */ + void initEvent(const DOMString &eventTypeArg, bool canBubbleArg, bool cancelableArg); + + /** + * @internal + * not part of the DOM + */ + EventImpl *handle() const; + bool isNull() const; + +protected: + Event(EventImpl *i); + EventImpl *impl; +}; + + +/** + * Introduced in DOM Level 2: + * + * Event operations may throw an EventException as specified in their method + * descriptions. + * + */ +class KHTML_EXPORT EventException +{ +public: + EventException(unsigned short _code); + EventException(const EventException &other); + EventException & operator = (const EventException &other); + virtual ~EventException() {} + + /** + * An integer indicating the type of error generated. + * + * UNSPECIFIED_EVENT_TYPE_ERR: If the Event's type was not specified by + * initializing the event before the method was called. Specification of + * the Event's type as null or an empty string will also trigger this + * exception. + * + */ + enum EventExceptionCode { + UNSPECIFIED_EVENT_TYPE_ERR = 0 + }; + + unsigned short code; +}; + + +/** + * Introduced in DOM Level 2 + * + * The UIEvent interface provides specific contextual information associated + * with User Interface events. + * + */ +class KHTML_EXPORT UIEvent : public Event { +public: + UIEvent(); + UIEvent(const UIEvent &other); + UIEvent(const Event &other); + UIEvent & operator = (const UIEvent &other); + UIEvent & operator = (const Event &other); + virtual ~UIEvent(); + + /** + * The view attribute identifies the AbstractView from which the event was + * generated. + * + */ + AbstractView view() const; + + /** + * Specifies some detail information about the Event, depending on the type + * of event. + * + */ + long detail() const; + + /** + * Non-standard extension to support IE-style keyCode event property. + * + */ + int keyCode() const; + + /** + * Non-standard extension to support IE-style charCode event property. + * + */ + int charCode() const; + + /** + * Non-standard extensions to support Netscape-style pageX and pageY event properties. + * + */ + int pageX() const; + int pageY() const; + + /** + * Non-standard extensions to support Netscape-style layerX and layerY event properties. + * + */ + int layerX() const; + int layerY() const; + + /** + * Non-standard extension to support Netscape-style "which" event property. + * + */ + int which() const; + + /** + * The initUIEvent method is used to initialize the value of a UIEvent + * created through the DocumentEvent interface. This method may only be + * called before the UIEvent 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. + * + * @param typeArg Specifies the event type. + * + * @param canBubbleArg Specifies whether or not the event can bubble. + * + * @param cancelableArg Specifies whether or not the event's default action + * can be prevented. + * + * @param viewArg Specifies the Event's AbstractView. + * + * @param detailArg Specifies the Event's detail. + * + */ + void initUIEvent(const DOMString &typeArg, + bool canBubbleArg, + bool cancelableArg, + const AbstractView &viewArg, + long detailArg); +protected: + UIEvent(UIEventImpl *impl); +}; + + + + +/** + * Introduced in DOM Level 2 + * + * The MouseEvent interface provides specific contextual information associated + * with Mouse events. + * + * The detail attribute inherited from UIEvent indicates the number of times a + * mouse button has been pressed and released over the same screen location + * during a user action. The attribute value is 1 when the user begins this + * action and increments by 1 for each full sequence of pressing and releasing. + * If the user moves the mouse between the mousedown and mouseup the value will + * be set to 0, indicating that no click is occurring. + * + * 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 its descendent elements. + * + */ +class KHTML_EXPORT MouseEvent : public UIEvent { +public: + MouseEvent(); + MouseEvent(const MouseEvent &other); + MouseEvent(const Event &other); + MouseEvent & operator = (const MouseEvent &other); + MouseEvent & operator = (const Event &other); + virtual ~MouseEvent(); + + /** + * The horizontal coordinate at which the event occurred relative to the + * origin of the screen coordinate system. + * + */ + long screenX() const; + + /** + * The vertical coordinate at which the event occurred relative to the + * origin of the screen coordinate system. + * + */ + long screenY() const; + + /** + * The horizontal coordinate at which the event occurred relative to the + * DOM implementation's client area. + * + */ + long clientX() const; + + /** + * The vertical coordinate at which the event occurred relative to the DOM + * implementation's client area. + * + */ + long clientY() const; + + /** + * Used to indicate whether the 'ctrl' key was depressed during the firing + * of the event. + */ + bool ctrlKey() const; + + /** + * Used to indicate whether the 'shift' key was depressed during the firing + * of the event. + * + */ + bool shiftKey() const; + + /** + * Used to indicate whether the 'alt' key was depressed during the firing + * of the event. On some platforms this key may map to an alternative key + * name. + * + */ + bool altKey() const; + + /** + * Used to indicate whether the 'meta' key was depressed during the firing + * of the event. On some platforms this key may map to an alternative key + * name. + * + */ + bool metaKey() const; + + /** + * During mouse events caused by the depression or release of a mouse + * button, button is used to indicate which mouse button changed state. The + * values for button range from zero to indicate the left button of the + * mouse, one to indicate the middle button if present, and two to indicate + * the right button. For mice configured for left handed use in which the + * button actions are reversed the values are instead read from right to + * left. + * + */ + unsigned short button() const; + + /** + * 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. + * + */ + Node relatedTarget() const; + + /** + * The initMouseEvent method is used to initialize the value of a + * MouseEvent created through the DocumentEvent interface. This method may + * only be called before the MouseEvent 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. Parameters + * + * @param typeArg Specifies the event type. + * + * @param canBubbleArg Specifies whether or not the event can bubble. + * + * @param cancelableArg Specifies whether or not the event's default action can be prevented. + * + * @param viewArg Specifies the Event's AbstractView. + * + * @param detailArg Specifies the Event's mouse click count. + * + * @param screenXArg Specifies the Event's screen x coordinate + * + * @param screenYArg Specifies the Event's screen y coordinate + * + * @param clientXArg Specifies the Event's client x coordinate + * + * @param clientYArg Specifies the Event's client y coordinate + * + * @param ctrlKeyArg Specifies whether or not control key was depressed during the Event. + * + * @param altKeyArg Specifies whether or not alt key was depressed during the Event. + * + * @param shiftKeyArg Specifies whether or not shift key was depressed during the Event. + * + * @param metaKeyArg Specifies whether or not meta key was depressed during the Event. + * + * @param buttonArg Specifies the Event's mouse button. + * + * @param relatedTargetArg Specifies the Event's related EventTarget. + * + */ + void initMouseEvent(const DOMString &typeArg, + bool canBubbleArg, + bool cancelableArg, + const AbstractView &viewArg, + long detailArg, + long screenXArg, + long screenYArg, + long clientXArg, + long clientYArg, + bool ctrlKeyArg, + bool altKeyArg, + bool shiftKeyArg, + bool metaKeyArg, + unsigned short buttonArg, + const Node &relatedTargetArg); +protected: + MouseEvent(MouseEventImpl *impl); +}; + +// Introduced in DOM Level 3: +/** + * DOM::TextEvent + * The detail attribute inherited from UIEvent is used to indicate + * the number of keypresses which have occurred during key repetition. + * If this information is not available this value should be 0. + * + * ### KDE4: split this up into proper KeyboardEvent and TextEvent classes + * as specified in current DOM3 Events revision. This is doing heavy emulation + * at the moment + */ +class KHTML_EXPORT TextEvent : public UIEvent { +public: + TextEvent(); + TextEvent(const TextEvent &other); + TextEvent(const Event &other); + TextEvent & operator = (const TextEvent &other); + TextEvent & operator = (const Event &other); + virtual ~TextEvent(); + + /** + * initTextEvent + * + * The initTextEvent method is used to initialize the value of a + * MouseEvent created through the DocumentEvent interface. This + * method may only be called before the TextEvent 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. This method has no effect + * if called after the event has been dispatched. + * + * Parameters: + * + * typeArg of type DOMString + * Specifies the event type. + * canBubbleArg of type boolean + * Specifies whether or not the event can bubble. + * cancelableArg of type boolean + * Specifies whether or not the event's default action can be prevent. + * viewArg of type views::AbstractView + * Specifies the TextEvent's AbstractView. + * detailArg of type unsigned short + * Specifies the number of repeated keypresses, if available. + * outputStringArg of type DOMString + * Specifies the TextEvent's outputString attribute + * keyValArg of type unsigned long + * Specifies the TextEvent's keyValattribute + * virtKeyValArg of type unsigned long + * Specifies the TextEvent's virtKeyValattribute + * inputGeneratedArg of type boolean + * Specifies the TextEvent's inputGeneratedattribute + * numPadArg of type boolean + * Specifies the TextEvent's numPadattribute + * + * No Return Value. + * No Exceptions. + */ + void initTextEvent(const DOMString &typeArg, + bool canBubbleArg, + bool cancelableArg, + const AbstractView &viewArg, + long detailArg, + const DOMString &outputStringArg, + unsigned long keyValArg, + unsigned long virtKeyValArg, + bool inputGeneratedArg, + bool numPadArg); + + /** + * initModifier + * + * The initModifier method is used to initialize the values of any + * modifiers associated with a TextEvent created through the + * DocumentEvent interface. This method may only be called before the + * TextEvent has been dispatched via the dispatchEvent method, though + * it may be called multiple times during that phase if necessary. If + * called multiple times with the same modifier property the final + * invocation takes precedence. Unless explicitly give a value of + * true, all modifiers have a value of false. This method has no + * effect if called after the event has been dispatched. The list of + * keys below represents the allowable modifier parameters for this + * method (note: this was not documented properly in earlier versions): + * + * Qt::ShiftButton, Qt::AltButton, Qt::ControlButton, Qt::MetaButton + * + * Parameters: + * + * modifier of type unsigned long + * The modifier which the user wishes to initialize + * value of type boolean + * The new value of the modifier. + * + * No Return Value + * No Exceptions + */ + void initModifier(unsigned long modifierArg, bool valueArg); + + /** + * inputGenerated of type boolean + * + * The inputGenerated attribute indicates whether the key event will + * normally cause visible output. If the key event does not + * generate any visible output, such as the use of a function key + * or the combination of certain modifier keys used in conjunction + * with another key, then the value will be false. If visible + * output is normally generated by the key event then the value + * will be true. The value of inputGenerated does not guarantee + * the creation of a character. If a key event causing visible + * output is cancelable it may be prevented from causing + * output. This attribute is intended primarily to differentiate + * between keys events which may or may not produce visible output + * depending on the system state. + */ + bool inputGenerated() const; + + /** keyVal of type unsigned long + * + * The value of keyVal holds the value of the Unicode character + * associated with the depressed key. If the key has no Unicode + * representation or no Unicode character is available the value is + * 0. + */ + unsigned long keyVal() const; + + /** numPad of type boolean + * + * The numPad attribute indicates whether or not the key event was + * generated on the number pad section of the keyboard. If the number + * pad was used to generate the key event the value is true, + * otherwise the value is false. + */ + bool numPad() const; + + /** + *outputString of type DOMString + * + * outputString holds the value of the output generated by the key + * event. This may be a single Unicode character or it may be a + * string. It may also be null in the case where no output was + * generated by the key event. + */ + + DOMString outputString() const; + /** virtKeyVal of type unsigned long + * + * When the key associated with a key event is not representable via + * a Unicode character virtKeyVale holds the virtual key code + * associated with the depressed key. If the key has a Unicode + * representation or no virtual code is available the value is + * DOM_VK_UNDEFINED. + */ + unsigned long virtKeyVal() const; + + /** + * checkModifier + * + * Note: the below description does not match the actual behavior. + * it's extended in a way that you can query multiple modifiers + * at once by logically OR`ing them. + * also, we use the Qt modifier enum instead of the DOM one. + * + * The CheckModifier method is used to check the status of a single + * modifier key associated with a TextEvent. The identifier of the + * modifier in question is passed into the CheckModifier function. If + * the modifier is triggered it will return true. If not, it will + * return false. The list of keys below represents the allowable + * modifier parameters for this method (warning: this was not documented + * properly in earlier versions): + * Qt::ShiftButton, Qt::AltButton, Qt::ControlButton, Qt::MetaButton + * + * Parameters: + * + * modifier of type unsigned long + * The modifier which the user wishes to query. + * + * Return Value: boolean + * The status of the modifier represented as a boolean. + * + * No Exceptions + */ + bool checkModifier(unsigned long modifierArg); // ### KDE 4: const! + +protected: + TextEvent(KeyEventBaseImpl *impl); +}; + + +/** + * Introduced in DOM Level 2 + * + * The MutationEvent interface provides specific contextual information + * associated with Mutation events. + * + */ +class KHTML_EXPORT MutationEvent : public Event { +public: + MutationEvent(); + MutationEvent(const MutationEvent &other); + MutationEvent(const Event &other); + MutationEvent & operator = (const MutationEvent &other); + MutationEvent & operator = (const Event &other); + virtual ~MutationEvent(); + + /** + * An integer indicating in which way the Attr was changed. + * + * ADDITION: The Attr was just added. + * + * MODIFICATION: The Attr was modified in place. + * + * REMOVAL: The Attr was just removed. + * + */ + enum attrChangeType { + MODIFICATION = 1, + ADDITION = 2, + REMOVAL = 3 + }; + + + /** + * 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 DOMAttrModified event it indicates the Attr node which was + * modified, added, or removed. + * + */ + Node relatedNode() const; + + /** + * prevValue indicates the previous value of the Attr node in + * DOMAttrModified events, and of the CharacterData node in + * DOMCharDataModified events. + * + */ + DOMString prevValue() const; + + /** + * newValue indicates the new value of the Attr node in DOMAttrModified + * events, and of the CharacterData node in DOMCharDataModified events. + * + */ + DOMString newValue() const; + + /** + * attrName indicates the name of the changed Attr node in a + * DOMAttrModified event. + * + */ + DOMString attrName() const; + + /** + * attrChange indicates the type of change which triggered the + * DOMAttrModified event. The values can be MODIFICATION, ADDITION, or + * REMOVAL. + * + */ + unsigned short attrChange() const; + + /** + * The initMutationEvent method is used to initialize the value of a + * MutationEvent created through the DocumentEvent interface. This method + * may only be called before the MutationEvent 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. + * + * @param typeArg Specifies the event type. + * + * @param canBubbleArg Specifies whether or not the event can bubble. + * + * @param cancelableArg Specifies whether or not the event's default action can be prevented. + * + * @param relatedNodeArg Specifies the Event's related Node. + * + * @param prevValueArg Specifies the Event's prevValue attribute. This value may be null. + * + * @param newValueArg Specifies the Event's newValue attribute. This value may be null. + * + * @param attrNameArg Specifies the Event's attrName attribute. This value may be null. + * + * @param attrChangeArg Specifies the Event's attrChange attribute + * + */ + void initMutationEvent(const DOMString &typeArg, + bool canBubbleArg, + bool cancelableArg, + const Node &relatedNodeArg, + const DOMString &prevValueArg, + const DOMString &newValueArg, + const DOMString &attrNameArg, + unsigned short attrChangeArg); +protected: + MutationEvent(MutationEventImpl *impl); +}; + + + +} //namespace +#endif |