Source: dom/dom2_events.h
|
|
|
|
/*
* This file is part of the DOM implementation for KDE.
*
* (C) 2001 Peter Kelly (pmk@post.com)
*
* 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., 59 Temple Place - Suite 330,
* Boston, MA 02111-1307, USA.
*
* $Id: dom2__events_h.html 203394 2003-01-28 18:16:22Z ctennis $
*/
#ifndef _DOM_Events_h_
#define _DOM_Events_h_
#include
#include
namespace KJS {
class Image;
}
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 TextEventImpl;
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 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 Event {
friend class Document;
friend class NodeImpl;
friend class DocumentImpl;
friend class KJS::Image;
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;
/**
* @internal
* not part of the DOM
*
* Returns the module name of the event - this is the same as passed to
* Document::createEvent() (e.g. UIEvents)
*/
DOMString eventModuleName();
protected:
Event(EventImpl *i);
EventImpl *impl;
};
/**
* Introduced in DOM Level 2:
*
* Event operations may throw an EventException as specified in their method
* descriptions.
*
*/
class 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 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;
/**
* 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 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.
*/
class 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 paramaters for this
* method:
* DOM_VK_LEFT_ALT
* DOM_VK_RIGHT_ALT
* DOM_VK_LEFT_CONTROL
* DOM_VK_RIGHT_CONTROL
* DOM_VK_LEFT_SHIFT
* DOM_VK_RIGHT_SHIFT
* DOM_VK_META
*
* 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 behaviour.
* 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 paramaters for this method:
* DOM_VK_LEFT_ALT
* DOM_VK_RIGHT_ALT
* DOM_VK_LEFT_CONTROL
* DOM_VK_RIGHT_CONTROL
* DOM_VK_LEFT_SHIFT
* DOM_VK_RIGHT_SHIFT
* DOM_VK_META
*
* Parameters:
*
* modifer 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 modiferArg);
protected:
TextEvent(TextEventImpl *impl);
};
/**
* Introduced in DOM Level 2
*
* The MutationEvent interface provides specific contextual information
* associated with Mutation events.
*
*/
class 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
| Generated by: caleb on tcdevel on Tue Jan 28 12:54:28 2003, using kdoc $. |