Scott Lanning > Mozilla-DOM > Mozilla::DOM::Event

Download:
Mozilla-DOM-0.23.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  2
Open  5
View/Report Bugs
Source  

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)

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

syntax highlighting: