Scott Lanning

NAME

Mozilla::DOM::Event

DESCRIPTION

Mozilla::DOM::Event is a wrapper around an instance of Mozilla's nsIDOMEvent interface, from which Mozilla::DOM::UIEvent inherits. This class inherits from Supports.

 * The nsIDOMEvent interface is the primary datatype for all events in
 * the Document Object Model.
 *
 * For more information on this interface please see
 * L<http:E<sol>E<sol>www.w3.orgE<sol>TRE<sol>DOM-Level-2-EventsE<sol>>

The constants CAPTURING_PHASE, AT_TARGET, and BUBBLING_PHASE are available for comparing with GetEventPhase. You can access these either through the (mouse or key) event object, like $event->AT_TARGET, export them all with use Mozilla::DOM::Event qw(:phases), or export them individually.

CLASS METHODS

$iid = Mozilla::DOM::Event->GetIID()

Pass this to QueryInterface.

METHODS

$bool = $event->GetBubbles

    Indicates whether or not an event is a bubbling event. If the event can bubble the value is true, else the value is false.

$bool = $event->GetCancelable

    Indicates 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.

$target = $event->GetCurrentTarget

    Get the EventTarget whose EventListeners are currently being processed. This is particularly useful during capturing and bubbling.

$phase = $event->GetEventPhase

    Get which phase of event flow is currently being evaluated.

$target = $event->GetTarget

    Get the EventTarget to which the Event was originally dispatched.

$event->GetTimeStamp

    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 00:00:00 UTC 1st January 1970.

    XXX: I'm doing something wrong, because it seems to only keep the bottom half of the (64-bit) number. As long as the time between events your comparing isn't too long, it shouldn't matter (as long as the number doesn't wrap around...). Let me know if you see what I'm doing wrong. I was thinking also of splitting the number in half and returning a list of two integers.

$type = $event->GetType

    The name of the event (case-insensitive). The name must be an XML name.

$event->InitEvent($eventType, $canbubble, $cancelable)

    • $eventtype (string)

    • $canbubble (boolean)

    • $cancelable (boolean)

       * 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.

    The $event object is an event created by DocumentEvent's CreateEvent method. You can morph that into a KeyEvent, etc., by calling <QueryInterface|Mozilla::DOM::Supports/QueryInterface>.

    The $event_type argument here depends on the argument you passed to CreateEvent. Here is information obtained from section 1.6 of the DOM Level 2 specification (qv. for more details):

    UIEvents
    DOMFocusIn

    The DOMFocusIn event occurs when an EventTarget receives focus, for instance via a pointing device being moved onto an element or by tabbing navigation to the element. Unlike the HTML event focus, DOMFocusIn can be applied to any focusable EventTarget, not just FORM controls.

        * Bubbles: Yes
        * Cancelable: No
        * Context Info: None
    DOMFocusOut

    The DOMFocusOut event occurs when a EventTarget loses focus, for instance via a pointing device being moved out of an element or by tabbing navigation out of the element. Unlike the HTML event blur, DOMFocusOut can be applied to any focusable EventTarget, not just FORM controls.

        * Bubbles: Yes
        * Cancelable: No
        * Context Info: None
    DOMActivate

    The activate event occurs when an element is activated, for instance, thru a mouse click or a keypress. A numerical argument is provided to give an indication of the type of activation that occurs: 1 for a simple activation (e.g. a simple click or Enter), 2 for hyperactivation (for instance a double click or Shift Enter).

            * Bubbles: Yes
            * Cancelable: Yes
            * Context Info: detail (the numerical value)
    MouseEvents
    click

    The click event occurs when the pointing device button is clicked over an element. A click is defined as a mousedown and mouseup over the same screen location. The sequence of these events is:

        mousedown
        mouseup
        click

    If multiple clicks occur at the same screen location, the sequence repeats with the detail attribute incrementing with each repetition. This event is valid for most elements.

        * Bubbles: Yes
        * Cancelable: Yes
        * Context Info: screenX, screenY, clientX, clientY, altKey,
          ctrlKey, shiftKey, metaKey, button, detail
    mousedown

    The mousedown event occurs when the pointing device button is pressed over an element. This event is valid for most elements.

        * Bubbles: Yes
        * Cancelable: Yes
        * Context Info: screenX, screenY, clientX, clientY, altKey,
          ctrlKey, shiftKey, metaKey, button, detail
    mouseup

    The mouseup event occurs when the pointing device button is released over an element. This event is valid for most elements.

        * Bubbles: Yes
        * Cancelable: Yes
        * Context Info: screenX, screenY, clientX, clientY, altKey,
          ctrlKey, shiftKey, metaKey, button, detail
    mouseover

    The mouseover event occurs when the pointing device is moved onto an element. This event is valid for most elements.

        * Bubbles: Yes
        * Cancelable: Yes
        * Context Info: screenX, screenY, clientX, clientY, altKey,
          ctrlKey, shiftKey, metaKey,
          relatedTarget indicates the EventTarget the pointing device is exiting.
    mousemove

    The mousemove event occurs when the pointing device is moved while it is over an element. This event is valid for most elements.

        * Bubbles: Yes
        * Cancelable: No
        * Context Info: screenX, screenY, clientX, clientY, altKey, ctrlKey,
          shiftKey, metaKey
    mouseout

    The mouseout event occurs when the pointing device is moved away from an element. This event is valid for most elements..

        * Bubbles: Yes
        * Cancelable: Yes
        * Context Info: screenX, screenY, clientX, clientY, altKey,
          ctrlKey, shiftKey, metaKey,
          relatedTarget indicates the EventTarget the pointing device is entering.
    KeyEvents

    Not provided with DOM Level 2, it says. However, see the Events example.

    MutationEvents

    The mutation event module is designed to allow notification of any changes to the structure of a document, including attr and text modifications. [...]

    (I'm not sure why you'd create one of these. EventListeners? Seems they'd be automatically generated, though, when you modified the DOM somehow.)

    DOMSubtreeModified

    This is a general event for notification of all changes to the document. It can be used instead of the more specific events listed below. It may be fired after a single modification to the document or, at the implementation's discretion, after multiple changes have occurred. The latter use should generally be used to accomodate multiple changes which occur either simultaneously or in rapid succession. The target of this event is the lowest common parent of the changes which have taken place. This event is dispatched after any other events caused by the mutation have fired.

            * Bubbles: Yes
            * Cancelable: No
            * Context Info: None
    DOMNodeInserted

    Fired when a node has been added as a child of another node. This event is dispatched after the insertion has taken place. The target of this event is the node being inserted.

            * Bubbles: Yes
            * Cancelable: No
            * Context Info: relatedNode holds the parent node
    DOMNodeRemoved

    Fired when a node is being removed from its parent node. This event is dispatched before the node is removed from the tree. The target of this event is the node being removed.

            * Bubbles: Yes
            * Cancelable: No
            * Context Info: relatedNode holds the parent node
    DOMNodeRemovedFromDocument

    Fired when a node is being removed from a document, either through direct removal of the Node or removal of a subtree in which it is contained. This event is dispatched before the removal takes place. The target of this event is the Node being removed. If the Node is being directly removed the DOMNodeRemoved event will fire before the DOMNodeRemovedFromDocument event.

            * Bubbles: No
            * Cancelable: No
            * Context Info: None
    DOMNodeInsertedIntoDocument

    Fired when a node is being inserted into a document, either through direct insertion of the Node or insertion of a subtree in which it is contained. This event is dispatched after the insertion has taken place. The target of this event is the node being inserted. If the Node is being directly inserted the DOMNodeInserted event will fire before the DOMNodeInsertedIntoDocument event.

            * Bubbles: No
            * Cancelable: No
            * Context Info: None
    DOMAttrModified

    Fired after an Attr has been modified on a node. The target of this event is the Node whose Attr changed. The value of attrChange indicates whether the Attr was modified, added, or removed. The value of relatedNode indicates the Attr node whose value has been affected. It is expected that string based replacement of an Attr value will be viewed as a modification of the Attr since its identity does not change. Subsequently replacement of the Attr node with a different Attr node is viewed as the removal of the first Attr node and the addition of the second.

            * Bubbles: Yes
            * Cancelable: No
            * Context Info: attrName, attrChange, prevValue, newValue, relatedNode
    DOMCharacterDataModified

    Fired after CharacterData within a node has been modified but the node itself has not been inserted or deleted. This event is also triggered by modifications to PI elements. The target of this event is the CharacterData node.

            * Bubbles: Yes
            * Cancelable: No
            * Context Info: prevValue, newValue
    HTMLEvents

    I don't see anything in the Mozilla headers, and I haven't wrapped a Mozilla::DOM::HTMLEvent class, but here you go anyway.

    load

    The load event occurs when the DOM implementation finishes loading all content within a document, all frames within a FRAMESET, or an OBJECT element.

            * Bubbles: No
            * Cancelable: No
            * Context Info: None
    unload

    The unload event occurs when the DOM implementation removes a document from a window or frame. This event is valid for BODY and FRAMESET elements.

            * Bubbles: No
            * Cancelable: No
            * Context Info: None
    abort

    The abort event occurs when page loading is stopped before an image has been allowed to completely load. This event applies to OBJECT elements.

            * Bubbles: Yes
            * Cancelable: No
            * Context Info: None
    error

    The error event occurs when an image does not load properly or when an error occurs during script execution. This event is valid for OBJECT elements, BODY elements, and FRAMESET element.

            * Bubbles: Yes
            * Cancelable: No
            * Context Info: None
    select

    The select event occurs when a user selects some text in a text field. This event is valid for INPUT and TEXTAREA elements.

            * Bubbles: Yes
            * Cancelable: No
            * Context Info: None
    change

    The change event occurs when a control loses the input focus and its value has been modified since gaining focus. This event is valid for INPUT, SELECT, and TEXTAREA. element.

            * Bubbles: Yes
            * Cancelable: No
            * Context Info: None
    submit

    The submit event occurs when a form is submitted. This event only applies to the FORM element.

            * Bubbles: Yes
            * Cancelable: Yes
            * Context Info: None
    reset

    The reset event occurs when a form is reset. This event only applies to the FORM element.

            * Bubbles: Yes
            * Cancelable: No
            * Context Info: None
    focus

    The focus event occurs when an element receives focus either via a pointing device or by tabbing navigation. This event is valid for the following elements: LABEL, INPUT, SELECT, TEXTAREA, and BUTTON.

            * Bubbles: No
            * Cancelable: No
            * Context Info: None
    blur

    The blur event occurs when an element loses focus either via the pointing device or by tabbing navigation. This event is valid for the following elements: LABEL, INPUT, SELECT, TEXTAREA, and BUTTON.

            * Bubbles: No
            * Cancelable: No
            * Context Info: None
    resize

    The resize event occurs when a document view is resized.

            * Bubbles: Yes
            * Cancelable: No
            * Context Info: None
    scroll

    The scroll event occurs when a document view is scrolled.

            * Bubbles: Yes
            * Cancelable: No
            * Context Info: None

$event->PreventDefault

    If an event is cancelable, the prevent_default 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 prevent_default 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 prevent_default 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.

$event->StopPropagation

    This 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.

SEE ALSO

Mozilla::DOM

COPYRIGHT

Copyright (C) 2005-2007, Scott Lanning

This software is licensed under the LGPL. See Mozilla::DOM for a full notice.