Home | Class Index

SDK Version: 3.11.4-302512

Documentation generated on 24 July 2015

Class
caplin.dom.event

Event

The Event class provides a uniform interface over the W3C event object, which is implemented differently in IE than it is in standards compliant browsers. Using this class for performing event access eliminates the need for much of the boiler plate code that would otherwise be required. Except where this was not possible, this interface has been modeled on the W3C event object specification.

The #getNormalizedEvent method is used to get a reference to a normalized event object. This requires the event object to be passed as a parameter since the global window.event object is not available in all browsers. If it is not possible to obtain the information that is necessary using the normalized event, the underlying event can be obtained via the #getRawEvent method.

Example usage:

window.onload = function() {
  document.body.onmousedown = function(oRawEvent) {
    // oRawEvent required in Firefox, in IE this will be undefined, and the 
    // getNormalizedEvent() method will use the window.event global instead
    var oNormalisedEvent = caplin.dom.event.Event.getNormalizedEvent(oRawEvent);

    // check if the middle mouse button was pressed
    if (oNormalisedEvent.button == caplin.dom.event.Event.MouseButtons.MIDDLE) {
      // inform the user what type of element they clicked on
      alert("Middle mouse button pressed on " + oNormalisedEvent.target.tagName);
    }
 };
};

Further reading:

Constructor Summary

Attributes Name and Description
caplin.dom.event.Event()

This constructor is private and should not be used.

Field Summary

Attributes Name and Description
altKey

Returns true if the "ALT" key was pressed when the event was triggered, otherwise false.
button

Returns which mouse button was clicked when the event was triggered.
charCode

Returns the ascii code of the character that will be inserted due to a keypress event.
clientX

Returns the horizontal coordinate of the mouse pointer when the event was triggered.
clientY

Returns the vertical coordinate of the mouse pointer when the event was triggered.
ctrlKey

Returns true if the "CTRL" key was pressed when the event was triggered, otherwise false.
keyCode

Returns the code of the key during a keyUp or keyDown event.
relatedTarget

Returns the element related to the actual target that triggered the event.
screenX

Returns the horizontal coordinate of the mouse pointer when the event was triggered.
screenY

Returns the vertical coordinate of the mouse pointer when the event was triggered.
shiftKey

Returns true if the "SHIFT" key was pressed when the event was triggered, otherwise false.
target

Returns the element that triggered the event.
type

Returns the name of the event.

Method Summary

Attributes Name and Description
<static> void cancelEventBubbling(Object eventObj)

Crossbrowser method for canceling event bubbling.
void finalize()

Clean up any DOM references in the event.
<static> Object getEventSrc(Object eventObj:)

Crossbrowser method for returning the DOM element that fired the event.
<static> caplin.dom.event.Event getNormalizedEvent(HtmlEvent rawEvent)

Gets the normalised event that applies across all browsers representing the specified event.
HtmlEvent getRawEvent()

Gets the underlying event that this normalised event was constructed from.
void preventDefault()

Cancels the event if it is cancelable, without stopping further propagation of the event.
void stopPropagation()

Prevents further propagation of the current event.

Constructor Detail

► caplin.dom.event.Event()

This constructor is private and should not be used. To create a normalised event please use the #getNormalizedEvent method.

Field Detail

► boolean altKey

Returns true if the "ALT" key was pressed when the event was triggered, otherwise false.

► int button

Returns which mouse button was clicked when the event was triggered. Please see caplin.dom.event.Event.MouseButtons for the possible values.

WARNING - The normalisation of the button in Internet Explorer is not suitable if the user is expected to press more than one mouse button at any one time. If they do so, then the normalised value will only indicate that one of the buttons has been pressed. For example if the user presses the LEFT and RIGHT mouse buttons, this value will be Event.MouseButtons.LEFT.

► int charCode

Returns the ascii code of the character that will be inserted due to a keypress event.

► int clientX

Returns the horizontal coordinate of the mouse pointer when the event was triggered.

► int clientY

Returns the vertical coordinate of the mouse pointer when the event was triggered.

► boolean ctrlKey

Returns true if the "CTRL" key was pressed when the event was triggered, otherwise false.

► int keyCode

Returns the code of the key during a keyUp or keyDown event. You should use this on keyUp or keyDown events. It contains a code indicating the hardware key that was pressed. This is not necessarily the same as the ascii character that will be inserted.

► HtmlElement relatedTarget

Returns the element related to the actual target that triggered the event. For example when a mouseout event is fired, the caplin.dom.event.Event#target will refer to element that the mouse pointer is moving out of, whilst the relatedTarget will refer to the element that is being moved into.

► int screenX

Returns the horizontal coordinate of the mouse pointer when the event was triggered.

► int screenY

Returns the vertical coordinate of the mouse pointer when the event was triggered.

► boolean shiftKey

Returns true if the "SHIFT" key was pressed when the event was triggered, otherwise false.

► HtmlElement target

Returns the element that triggered the event. For example when a click event is fired, this is the element that was clicked.

► String type

Returns the name of the event.

Method Detail

► <static> void cancelEventBubbling(Object eventObj)

Crossbrowser method for canceling event bubbling.

Parameters
Object eventObj The event object.

► void finalize()

Clean up any DOM references in the event.

► <static> Object getEventSrc(Object eventObj:)

Crossbrowser method for returning the DOM element that fired the event.

Parameters
Object eventObj: The event object
Returns
{Object} The DOM element where that fired the event

► <static> caplin.dom.event.Event getNormalizedEvent(HtmlEvent rawEvent)

Gets the normalised event that applies across all browsers representing the specified event.

Parameters
HtmlEvent rawEvent The event to be normalised. If this value is undefined this method will use the window.event.
Throws
caplin.core.Error
if the rawEvent is undefined and the window.event global does not exist.
Returns
{caplin.dom.event.Event} A normalised event.
See
caplin.dom.event.Event

► HtmlEvent getRawEvent()

Gets the underlying event that this normalised event was constructed from.

Returns
{HtmlEvent} The underlying event.

► void preventDefault()

Cancels the event if it is cancelable, without stopping further propagation of the event. This means that any default action normally taken as a result of the event will not occur (e.g. the key that was pressed will be ignored). This method does not stop further propagation of the event through the DOM (please see #stopPropagation).

Invoking this method for a non-cancelable event has no effect.

► void stopPropagation()

Prevents further propagation of the current event.