UIZE JavaScript Framework

MODULES Uize.Dom.Event

SEARCHEXAMPLESSOURCEDEPSTEST

1. Introduction

The Uize.Dom.Event package provides convenient methods for abstracting differences between the DOM node event systems of different browsers.

DEVELOPERS: Chris van Rensburg

1.1. Examples

There are no dedicated showcase example pages for the Uize.Dom.Event module.

SEARCH FOR EXAMPLES

Use the link below to search for example pages on the UIZE Web site that reference the Uize.Dom.Event module...

SEARCH

1.2. Implementation Info

The Uize.Dom.Event module defines the Uize.Dom.Event object under the Uize.Dom namespace.

1.2.1. Features Introduced in This Module

The features listed in this section have been introduced in this module.

STATIC METHODS

Uize.Dom.Event.abort | Uize.Dom.Event.charCode | Uize.Dom.Event.fix | Uize.Dom.Event.isKeyBackspace | Uize.Dom.Event.isKeyDelete | Uize.Dom.Event.isKeyDownArrow | Uize.Dom.Event.isKeyEnd | Uize.Dom.Event.isKeyEnter | Uize.Dom.Event.isKeyEscape | Uize.Dom.Event.isKeyHome | Uize.Dom.Event.isKeyInsert | Uize.Dom.Event.isKeyLeftArrow | Uize.Dom.Event.isKeyPageDown | Uize.Dom.Event.isKeyPageUp | Uize.Dom.Event.isKeyRightArrow | Uize.Dom.Event.isKeySpace | Uize.Dom.Event.isKeyTab | Uize.Dom.Event.isKeyUpArrow | Uize.Dom.Event.keyCode | Uize.Dom.Event.preventDefault | Uize.Dom.Event.relatedTarget | Uize.Dom.Event.stopPropagation | Uize.Dom.Event.target

STATIC PROPERTIES

Uize.Dom.Event.moduleName | Uize.Dom.Event.pathToResources

1.2.2. Features Overridden in This Module

No features have been overridden in this module.

1.2.3. Features Inherited From Other Modules

This module has no inherited features.

1.2.4. Modules Directly Under This Namespace

There are no modules directly under this namespace.

1.2.5. Unit Tests

There is no dedicated unit tests module for the Uize.Dom.Event module.

2. Static Methods

2.1. Uize.Dom.Event.abort

Aborts the specified DOM event, preventing the browser's default action for that event from taking place, and also preventing the event from being propagated.

SYNTAX

Uize.Dom.Event.abort (domEventOBJ);

Calling this method has the same effect as calling both the Uize.Dom.Event.preventDefault and Uize.Dom.Event.stopPropagation static methods for the specified DOM event.

NOTES

see the related Uize.Dom.Event.preventDefault and Uize.Dom.Event.stopPropagation static methods

IMPLEMENTATION INFO

this feature was introduced in this module

2.2. Uize.Dom.Event.charCode

Returns an integer, indicating the character code of the key being pressed in the keypress keyboard event.

SYNTAX

charCodeINT = Uize.Dom.Event.charCode (domEventOBJ);

In order to get the actual character for the key that is being pressed, you can use the String.fromCharCode method, as in...

keyCharSTR = String.fromCharCode (Uize.Dom.Event.charCode (domEventOBJ));

NOTES

this method is applicable only to the keypress event and is not guaranteed to work reliably with the keydown and keyup events
if the key being pressed is a special key that would not produce a character (such as one of the cursor arrow keys), then this method will return the value 0
see the related Uize.Dom.Event.keyCode static method
this method does not modify the DOM event object

IMPLEMENTATION INFO

this feature was introduced in this module

2.3. Uize.Dom.Event.fix

Performs some fixes on the specified event object by extending it with DOM standard event object methods and properties, as necessary.

SYNTAX

domEventOBJ = Uize.Dom.Event.fix (domEventOBJ);

This method abstracts the difference between Microsoft Internet Explorer, which supports proprietary properties on the event object, and other browsers that support the DOM standard methods and properties. Among other things, this method will extend the specified DOM event object with the preventDefault and stopPropagation methods, and the charCode, relatedTarget, and target properties, as necessary.

NOTES

this method may modify the DOM event object

IMPLEMENTATION INFO

this feature was introduced in this module

2.4. Uize.Dom.Event.isKeyBackspace

Returns a boolean, indicating whether or not the key being pressed in the keyboard event is the backspace key.

SYNTAX

isKeyBackspaceBOOL = Uize.Dom.Event.isKeyBackspace (domEventOBJ);

NOTES

this method is applicable to the keydown and keyup events and is not guaranteed to work reliably with the keypress event
this method does not modify the DOM event object

IMPLEMENTATION INFO

this feature was introduced in this module

2.5. Uize.Dom.Event.isKeyDelete

Returns a boolean, indicating whether or not the key being pressed in the keyboard event is the delete key.

SYNTAX

isKeyDeleteBOOL = Uize.Dom.Event.isKeyDelete (domEventOBJ);

NOTES

this method is applicable to the keydown and keyup events and is not guaranteed to work reliably with the keypress event
this method does not modify the DOM event object

IMPLEMENTATION INFO

this feature was introduced in this module

2.6. Uize.Dom.Event.isKeyDownArrow

Returns a boolean, indicating whether or not the key being pressed in the keyboard event is the down arrow key.

SYNTAX

isKeyDownArrowBOOL = Uize.Dom.Event.isKeyDownArrow (domEventOBJ);

NOTES

this method is applicable to the keydown and keyup events and is not guaranteed to work reliably with the keypress event
this method does not modify the DOM event object

IMPLEMENTATION INFO

this feature was introduced in this module

2.7. Uize.Dom.Event.isKeyEnd

Returns a boolean, indicating whether or not the key being pressed in the keyboard event is the end key.

SYNTAX

isKeyEndBOOL = Uize.Dom.Event.isKeyEnd (domEventOBJ);

NOTES

this method is applicable to the keydown and keyup events and is not guaranteed to work reliably with the keypress event
this method does not modify the DOM event object

IMPLEMENTATION INFO

this feature was introduced in this module

2.8. Uize.Dom.Event.isKeyEnter

Returns a boolean, indicating whether or not the key being pressed in the keyboard event is the home key.

SYNTAX

isKeyEnterBOOL = Uize.Dom.Event.isKeyEnter (domEventOBJ);

NOTES

this method is applicable to the keydown and keyup events and is not guaranteed to work reliably with the keypress event
this method does not modify the DOM event object

IMPLEMENTATION INFO

this feature was introduced in this module

2.9. Uize.Dom.Event.isKeyEscape

Returns a boolean, indicating whether or not the key being pressed in the keyboard event is the escape key.

SYNTAX

isKeyEscapeBOOL = Uize.Dom.Event.isKeyEscape (domEventOBJ);

NOTES

this method is applicable to the keydown and keyup events and is not guaranteed to work reliably with the keypress event
this method does not modify the DOM event object

IMPLEMENTATION INFO

this feature was introduced in this module

2.10. Uize.Dom.Event.isKeyHome

Returns a boolean, indicating whether or not the key being pressed in the keyboard event is the home key.

SYNTAX

isKeyHomeBOOL = Uize.Dom.Event.isKeyHome (domEventOBJ);

NOTES

this method is applicable to the keydown and keyup events and is not guaranteed to work reliably with the keypress event
this method does not modify the DOM event object

IMPLEMENTATION INFO

this feature was introduced in this module

2.11. Uize.Dom.Event.isKeyInsert

Returns a boolean, indicating whether or not the key being pressed in the keyboard event is the insert key.

SYNTAX

isKeyInsertBOOL = Uize.Dom.Event.isKeyInsert (domEventOBJ);

NOTES

this method is applicable to the keydown and keyup events and is not guaranteed to work reliably with the keypress event
this method does not modify the DOM event object

IMPLEMENTATION INFO

this feature was introduced in this module

2.12. Uize.Dom.Event.isKeyLeftArrow

Returns a boolean, indicating whether or not the key being pressed in the keyboard event is the left arrow key.

SYNTAX

isKeyLeftArrowBOOL = Uize.Dom.Event.isKeyLeftArrow (domEventOBJ);

NOTES

this method is applicable to the keydown and keyup events and is not guaranteed to work reliably with the keypress event
this method does not modify the DOM event object

IMPLEMENTATION INFO

this feature was introduced in this module

2.13. Uize.Dom.Event.isKeyPageDown

Returns a boolean, indicating whether or not the key being pressed in the keyboard event is the page down key.

SYNTAX

isKeyPageDownBOOL = Uize.Dom.Event.isKeyPageDown (domEventOBJ);

NOTES

this method is applicable to the keydown and keyup events and is not guaranteed to work reliably with the keypress event
this method does not modify the DOM event object

IMPLEMENTATION INFO

this feature was introduced in this module

2.14. Uize.Dom.Event.isKeyPageUp

Returns a boolean, indicating whether or not the key being pressed in the keyboard event is the page up key.

SYNTAX

isKeyPageUpBOOL = Uize.Dom.Event.isKeyPageUp (domEventOBJ);

NOTES

this method is applicable to the keydown and keyup events and is not guaranteed to work reliably with the keypress event
this method does not modify the DOM event object

IMPLEMENTATION INFO

this feature was introduced in this module

2.15. Uize.Dom.Event.isKeyRightArrow

Returns a boolean, indicating whether or not the key being pressed in the keyboard event is the right arrow key.

SYNTAX

isKeyRightArrowBOOL = Uize.Dom.Event.isKeyRightArrow (domEventOBJ);

NOTES

this method is applicable to the keydown and keyup events and is not guaranteed to work reliably with the keypress event
this method does not modify the DOM event object

IMPLEMENTATION INFO

this feature was introduced in this module

2.16. Uize.Dom.Event.isKeySpace

Returns a boolean, indicating whether or not the key being pressed in the keyboard event is the space key.

SYNTAX

isKeySpaceBOOL = Uize.Dom.Event.isKeySpace (domEventOBJ);

NOTES

this method is applicable to the keydown and keyup events and is not guaranteed to work reliably with the keypress event
this method does not modify the DOM event object

IMPLEMENTATION INFO

this feature was introduced in this module

2.17. Uize.Dom.Event.isKeyTab

Returns a boolean, indicating whether or not the key being pressed in the keyboard event is the tab key.

SYNTAX

isKeyTabBOOL = Uize.Dom.Event.isKeyTab (domEventOBJ);

NOTES

this method is applicable to the keydown and keyup events and is not guaranteed to work reliably with the keypress event
this method does not modify the DOM event object

IMPLEMENTATION INFO

this feature was introduced in this module

2.18. Uize.Dom.Event.isKeyUpArrow

Returns a boolean, indicating whether or not the key being pressed in the keyboard event is the up arrow key.

SYNTAX

isKeyUpArrowBOOL = Uize.Dom.Event.isKeyUpArrow (domEventOBJ);

NOTES

this method is applicable to the keydown and keyup events and is not guaranteed to work reliably with the keypress event
this method does not modify the DOM event object

IMPLEMENTATION INFO

this feature was introduced in this module

2.19. Uize.Dom.Event.keyCode

Returns an integer, indicating the key code of the key being pressed in the keydown or keyup keyboard event.

SYNTAX

keyCodeINT = Uize.Dom.Event.keyCode (domEventOBJ);

2.19.1. Not a Character Code

It's important to point out that the key code for a keyboard event does not correspond in a predictable or meaningful way to a character that might be produced when a key is pressed in a focused text input field.

For example, the key code when "Shift-a" is pressed is the same as when just "a" is pressed, even though the former would produce a capital "A" while the latter would produce a lowercase "a". The key code 65, in this case, merely identifies the "A" key on the keyboard. In other cases, certain keys will produce key codes that don't meaningfully map to characters in the ASCII character set. For example, the key code for the down arrow key is 40, and 40 is the ASCII character code for the "(" (open parenthesis) character - not a meaningful mapping at all.

2.19.2. Testing for Certain Keys

As a convenience, a number of static methods are provided in this module to make it easier to detect certain keys without having to remember the key codes.

An example is the Uize.Dom.Event.isKeyEnter method, which tests if the key being pressed down or released is the enter key. Other such methods include: Uize.Dom.Event.isKeyEscape, Uize.Dom.Event.isKeyDownArrow, Uize.Dom.Event.isKeyInsert, Uize.Dom.Event.isKeyTab, etc.

NOTES

this method is applicable to the keydown and keyup events and is not guaranteed to work reliably with the keypress event
see the related Uize.Dom.Event.charCode static method
this method does not modify the DOM event object

IMPLEMENTATION INFO

this feature was introduced in this module

2.20. Uize.Dom.Event.preventDefault

Prevents the browser's default action for the specified event from being performed.

SYNTAX

Uize.Dom.Event.preventDefault (domEventOBJ);

This method abstracts the difference between Microsoft Internet Explorer, which supports the proprietary returnValue property on the event object, and other browsers that support the DOM standard preventDefault method of the event object.

NOTES

see the related Uize.Dom.Event.abort and Uize.Dom.Event.stopPropagation static methods
this method may modify the DOM event object

IMPLEMENTATION INFO

this feature was introduced in this module

2.21. Uize.Dom.Event.relatedTarget

Returns a reference to a DOM node, identifying the secondary target for a mouseover or mouseout event.

SYNTAX

relatedTargetDomNodeOBJ = Uize.Dom.Event.relatedTarget (domEventOBJ);

This method is only applicable to / meaningful for the mouseover and mouseout mouse events, where the value returned for a mouseover event will be the DOM node that the mouse exited in order to enter the new node, and where the value returned for a mouseout event will be the DOM node that the mouse is entering as it exits the current node.

Target and Related Target
domEvent.name Uize.Dom.Event.target (domEvent) Uize.Dom.Event.relatedTarget (domEvent)
'mouseover' the node that mouse is entering the node that mouse is leaving
'mouseout' the node that mouse is leaving the node that mouse is entering

This method abstracts the difference between Microsoft Internet Explorer, which supports the proprietary fromElement and toElement properties on the event object, and other browsers that support the DOM standard relatedTarget property.

NOTES

this method is only applicable to the mouseover and mouseout mouse events
see the related Uize.Dom.Event.target static method
this method does not modify the DOM event object

IMPLEMENTATION INFO

this feature was introduced in this module

2.22. Uize.Dom.Event.stopPropagation

Stops the propagation of the specified DOM event to other nodes in the DOM.

SYNTAX

Uize.Dom.Event.stopPropagation (domEventOBJ);

Using this method for an event will prevent the event from being propagated / bubbled up to nodes that are up the parentNode chain for the node that is the target of the event. Consider the following example...

EXAMPLE

Uize.Dom.Basics.wire (
  myNode,
  'click',
  function (domEvent) {
    Uize.Dom.Event.stopPropagation (domEvent);
    alert ('You should see this message.');
  }
);
Uize.Dom.Basics.wire (
  myNode.parentNode,
  'click',
  function (domEvent) {
    if (Uize.Dom.Event.target (domEvent) == myNode) {
      alert ('You should NOT be seeing this message!');
    }
  }
);

In the above example, handlers are being wired for the click event of the node myNode and its parent node. Under normal circumstances, the user clicking on myNode would cause the click event to be fired first for that node and then for its parent node as the event is bubbled. In this case, however, the handler for click on myNode is using the Uize.Dom.Event.stopPropagation method to cancel the bubbling of the event up to the parent node. Therefore, clicking on the node myNode should never produce an alert with the message "You should NOT be seeing this message!".

This method abstracts the difference between Microsoft Internet Explorer, which supports the proprietary cancelBubble property on the event object, and other browsers that support the DOM standard stopPropagation method of the event object.

NOTES

this method may modify the DOM event object
see the related Uize.Dom.Event.abort and Uize.Dom.Event.preventDefault static methods

IMPLEMENTATION INFO

this feature was introduced in this module

2.23. Uize.Dom.Event.target

Returns a reference to a DOM node, being the node from which the specified DOM event was dispatched.

SYNTAX

targetDomNodeOBJ = Uize.Dom.Event.target (domEventOBJ);

This method abstracts the difference between Microsoft Internet Explorer, which supports the proprietary srcElement property on the event object, and other browsers that support the DOM standard target property.

NOTES

see the related Uize.Dom.Event.relatedTarget static method
this method does not modify the DOM event object

IMPLEMENTATION INFO

this feature was introduced in this module

3. Static Properties

3.1. Uize.Dom.Event.moduleName

IMPLEMENTATION INFO

this feature was introduced in this module

3.2. Uize.Dom.Event.pathToResources

IMPLEMENTATION INFO

this feature was introduced in this module