JavaScript Reference

Local Navigation

Events API

Object

Description

Availability

CustomEvent

Represents an unknown event type, typically application-specific event types.

4.6 or later

Event

Provides contextual information about an event that event handlers can use.

4.6 or later

EventListener

Represents an event listener that listens for and handles events as they occur.

4.6 or later

KeyboardEvent

Represents an event generated by the BlackBerry device keyboard.

4.6 or later

MessageEvent

Represents an event generated when an object receives a message.

6.0 or later

MouseEvent

Represents an event that is generated by the BlackBerry device trackball, trackwheel, or touch screen.

4.6 or later

StorageEvent

Represents an event fired when a local or session storage area changes.

6.0 or later

TextEvent

Represents an event that is generated by entering characters using the BlackBerry keyboard or an input source such as a voice command.

4.6 or later

UIEvent

Represents a UI event that is generated by user interaction with the trackwheel, trackball, touch screen, or keyboard on a BlackBerry device keyboard.

4.6 or later

Object: CustomEvent

Availability

BlackBerry Device Software version 4.6 or later

Extends

Event

The CustomEvent object represents an unknown event type. This object is typically used for application-specific event types.

To create an instance of a CustomEvent, you must invoke Document.createEvent() with an input parameter of "CustomEvent".

Back To Top

Properties

Property name

Type

Description

Status

Support level

Availability

detail

DOMObject

Specifies some detail information about the Event, depending on the type of event.

read only

DOM 3 Event

4.6 or later

Back To Top

CustomEvent methods

Method name

Description

Support level

Availability

initCustomEventNS()

Initializes the value of a CustomEvent.

DOM 3 Events

4.6 or later

Back To Top

Object: Event

Availability

BlackBerry Device Software version 4.6 or later

Extended by

CustomEvent, MessageEvent, MutationEvent, StorageEvent, UIEvent

The Event object represents provides contextual information about an event that Event handlers can use, such as the originating element, what stage the event is currently in within the event system, and so forth.

The properties and methods exposed by Event are minimal, and provide the basic functionality required by events of all types. More specific event objects should be used to acquire context information specific to a certain event type.

For example, the MouseEvent object, which inherits from Event through the UIEvent object, supplies additional properties supplying information such as the MouseEvent.button, MouseEvent.screenX and MouseEvent.screenY for where the current mouse event took place.

Back To Top

Event constants

Constant

Phase type

Description

Support level

Availability

1

CAPTURING_PHASE

Indicates that the event is in the capturing phase.

DOM 2 Events

4.6 or later

2

AT_TARGET

Indicates that the event is in being handled by the target node.

DOM 2 Events

4.6 or later

3

BUBBLING_PHASE

Indicates that the event is in the bubbling phase.

DOM 2 Style

4.6 or later

Back To Top

Event properties

Property name

Type

Description

Status

Support level

Availability

bubbles

boolean

When true, the event is a bubbling event.

read only

DOM 2 Events

4.6. or later

cancelable

boolean

When true, the action of the event can be cancelled using Event.preventDefault().

read only

DOM 2 Events

4.6. or later

cancelBubble

boolean

When true, bubbling of the event is cancelled.

writable

Not part of any standard.

4.6. or later

currentTarget

EventTarget

The node of the Document object that is currently handling the event.

read only

DOM 2 Events

4.6. or later

eventPhase

unsigned short

The phase that the event is currently in, represented using an Event constant.

read only

DOM 2 Events

4.6. or later

target

EventTarget

The target node to which the event was dispatched.

read only

DOM 2 Events

4.6. or later

timeStamp

unsigned long

The time (in milliseconds since epoch) at which the event was created.

read only

DOM 2 Events

4.6 or later

type

DOMString

The name of the event.

read only

DOM 2 Events

4.6 or later

Back To Top

Event methods

Method name

Description

Support level

Availability

initEvent()

Initializes the properties of an Event object.

DOM 2 Events

4.6 or later

preventDefault()

Cancels the event, preventing the default action from occurring.

DOM 2 Events

4.6 or later

stopPropagation()

Prevents further propagation of this event during an event flow.

DOM 2 Events

4.6 or later

Back To Top

Object: EventListener

Availability

BlackBerry Device Software version 4.6 or later

The EventListener object represents an event listener, which is used to listen for and handle events as they occur. EventListener objects are registered on an EventTarget, the node(s) within the DOM that may be impacted by an event. Events may be registered against Node, Window, or XMLHttpRequest. A listener should be removed from the target after it has been used.

Back To Top

EventListener methods

Method name

Description

Support level

Availability

handleEvent()

Called whenever an event occurs the EventListener object was registered to listen for.

DOM Level 2 Events

4.6 or later

Back To Top

Object: EventException

Availability

BlackBerry Device Software version 4.6 or later

The EventException object represents an error that occurs when initializing or dispatching an event.

Back To Top

Object: KeyboardEvent

Availability

BlackBerry Device Software version 4.6 or later

Extends

UIEvent

The KeyboardEvent object extends the UIEvent object and represents an event generated by the BlackBerry device keyboard. It provides specific contextual information associated with keyboard devices. Each keyboard event references a key using an identifier. Keyboard events are commonly directed at the element that has the focus.

To create an instance of a KeyboardEvent, you must invoke Document.createEvent() with an input parameter of ”KeyboardEvent”.

Back To Top

Keyboard event types

Event type

Bubbles

Cancelable

Description

keydown

yes

yes

Occurs when a key is pressed while the pointer is over an element.

This event type includes the following context information:

  • KeyboardEvent.altKey
  • KeyboardEvent.ctrlKey
  • KeyboardEvent.keyIdentifier
  • KeyboardEvent.keyLocation
  • KeyboardEvent.metaKey
  • KeyboardEvent.shiftKey
  • UIEvent.view

keypress

yes

yes

Occurs immediately after a keydown event. This event does not repeat.

This event includes the following context information:

  • KeyboardEvent.altKey
  • KeyboardEvent.ctrlKey
  • KeyboardEvent.keyIdentifier
  • KeyboardEvent.keyLocation
  • KeyboardEvent.metaKey
  • KeyboardEvent.shiftKey
  • UIEvent.view

keyup

yes

yes

Occurs when a key is released while the pointer is over an element.

This event type includes the following context information:

  • KeyboardEvent.altKey
  • KeyboardEvent.ctrlKey
  • KeyboardEvent.keyIdentifier
  • KeyboardEvent.keyLocation
  • KeyboardEvent.metaKey
  • KeyboardEvent.shiftKey
  • UIEvent.view
Back To Top

KeyboardEvent properties

Property name

Type

Description

Status

Support level

Availability

altKey

boolean

Returns true if the ALT key is pressed or if the ALT key is locked.

read only

DOM 3 Events

4.6 or later

ctrlKey

boolean

Returns false. BlackBerry devices have no CTRL key.

read only

DOM 3 Events

4.6 or later

keyCode

int

Returns the key code associated with the key in this event.

read only

Not part of any standard.

4.6 or later

keyIdentifier

String

Returns the identifier of the key.

read only

DOM 3 Events

4.6 or later

keyLocation

int

Returns a value of DOM_KEY_LOCATION_STANDARD.

read only

DOM 3 Events

4.6 or later

metaKey

boolean

Returns false. BlackBerry devices have no Meta key.

read only

DOM 3 Events

4.6 or later

shiftKey

boolean

Returns true if the SHIFT key is pressed.

read only

DOM 3 Events

4.6 or later

Back To Top

KeyboardEvent methods

Method name

Description

Support level

Availability

getModifierState()

Checks the state of a modifier key.

DOM 3 Events

4.6 or later

initKeyboardEvent()

Initializes the value of a KeyboardEvent.

DOM 3 Events

4.6 or later

initKeyboardEventNS()

Initializes the value of a KeyboardEvent with the given namespace URI.

DOM 3 Events

4.6 or later

Back To Top

Object: MessageEvent

Availability

BlackBerry Device Software 6.0 or later

Extends

Event

The MessageEvent object extends the Event object and represents an event generated when an object receives a message. To create an instance of a MessageEvent, you must invoke Document.createEvent() with an input parameter of "MessageEvent".

Back To Top

MessageEvent properties

Property name

Type

Description

Status

Support level

Availability

data

any

Returns the message being sent.

read only

HTML 5

6.0 or later

origin

DOMString

Returns the origin of the document that sent the message (typically the scheme, hostname, and port of the document).

read only

HTML 5

6.0 or later

lastEventId

DOMString

Returns the last event ID string of the event source.

read only

HTML 5

6.0 or later

source

WindowProxy

Returns the WindowProxy of the browsing context of the Window object from which the message came.

read only

HTML 5

6.0 or later

ports

MessagePortArray

Returns the MessagePortArray being sent, if any.

read only

HTML 5

6.0 or later

Back To Top

MessageEvent methods

Method name

Description

Support level

Availability

initMessageEvent()

Initializes a MessageEvent.

HTML 5

6.0 or later

Back To Top

Object: MouseEvent

Availability

BlackBerry Device Software version 4.6 or later

Extends

UIEvent

The MouseEvent object extends the UIEvent object and represents an event generated by the BlackBerry device trackball or trackwheel. It provides contextual information associated with clicking the trackball or trackwheel and moving the pointer in the BlackBerry Browser window.

To create an instance of a MouseEvent, you must invoke Document.createEvent() with an input parameter of ”MouseEvent”.

Back To Top

Mouse event types

Event type

Bubbles

Cancelable

Description

click

yes

yes

Occurs when the user clicks the trackball or trackwheel on a BlackBerry device, or, on touchscreen devices, when the user performs a tap.

This event type includes the following context information:

UIEvent.detail, MouseEvent.altKey, MouseEvent.button, MouseEvent.clientX, MouseEvent.clientY, MouseEvent.ctrlKey, MouseEvent.metaKey, MouseEvent.screenX, MouseEvent.screenY, MouseEvent.shiftKey

mousedown

yes

yes

Occurs when the user depresses the trackwheel or trackball on a BlackBerry device.

This event type includes the following context information:

UIEvent.detail, MouseEvent.altKey, MouseEvent.button, MouseEvent.clientX, MouseEvent.clientY, MouseEvent.ctrlKey, MouseEvent.metaKey, MouseEvent.screenX, MouseEvent.screenY, MouseEvent.shiftKey

mousemove

yes

no

Occurs when the user moves the pointer while it is over an element.

This event type includes the following context information:

MouseEvent.altKey, MouseEvent.clientX, MouseEvent.clientY, MouseEvent.ctrlKey, MouseEvent.metaKey, MouseEvent.screenX, MouseEvent.screenY, MouseEvent.shiftKey

mouseout

yes

yes

Occurs when the user moves the pointer off of an element.

This event type includes the following context information:

MouseEvent.altKey, MouseEvent.clientX, MouseEvent.clientY, MouseEvent.ctrlKey, MouseEvent.metaKey, MouseEvent.relatedTarget (indicating which EventTarget the pointer is leaving), MouseEvent.screenX, MouseEvent.screenY, MouseEvent.shiftKey

mouseover

yes

yes

Occurs when the user moves the pointer over an element.

This event type includes the following context information:

MouseEvent.altKey, MouseEvent.clientX, MouseEvent.clientY, MouseEvent.ctrlKey, MouseEvent.metaKey, MouseEvent.relatedTarget (indicating which EventTarget the pointer is entering), MouseEvent.screenX, MouseEvent.screenY, MouseEvent.shiftKey

mouseup

yes

yes

Occurs when the user releases the trackwheel or trackball on a BlackBerry device.

This event type includes the following context information:

UIEvent.detail, MouseEvent.altKey, MouseEvent.button, MouseEvent.clientX, MouseEvent.clientY, MouseEvent.ctrlKey, MouseEvent.metaKey, MouseEvent.screenX, MouseEvent.screenY, MouseEvent.shiftKey

Back To Top

MouseEvent properties

Property name

Type

Description

Status

Support level

Availability

altKey

boolean

Returns true if the ALT key is pressed or ALT lock is on.

read only

DOM 2 Events

4.6 or later

button

short

Returns a value indicating which mouse button changed state. Because BlackBerry devices have a single button (the trackball,trackpad, or touchscreen), this parameter will always return a value of “0”.

read only

DOM 2 Events

4.6 or later

clientX

int

Returns the horizontal coordinate within the BlackBerry Browser window where the event occurred.

read only

DOM 2 Events

4.6 or later

clientY

int

Returns the vertical coordinate within the BlackBerry Browser window where the event occurred.

read only

DOM 2 Events

4.6 or later

ctrlKey

boolean

Returns false. The BlackBerry device does not have a CTRL key.

read only

DOM 2 Events

4.6 or later

metaKey

boolean

Returns false. The BlackBerry device does not have a Meta key.

read only

DOM 2 Events

4.6 or later

relatedTarget

EventTarget

Returns the EventTarget that the pointer is moving over or moving off of.

read only

DOM 2 Events

4.6 or later

screenX

int

Returns the horizontal coordinate on the BlackBerry device screen where the event occurred.

read only

DOM 2 Events

4.6 or later

screenY

int

Returns the vertical coordinate on the BlackBerry device screen where the event occurred.

read only

DOM 2 Events

4.6 or later

shiftKey

boolean

Returns true if the SHIFT key is pressed.

read only

DOM 2 Events

4.6 or later

Back To Top

MouseEvent methods

Method name

Description

Support level

Availability

initMouseEvent()

Initializes the value of a MouseEvent.

DOM 2 Events

4.6 or later

Back To Top

Object: MutationEvent

Availability

BlackBerry Device Software 4.6 to 5.0

Extends

Event

The MutationEvent object extends the Event object and represents an event generated when the structure of document is modified. To create an instance of a MutationEvent, you must invoke Document.createEvent() with an input parameter of "MutationEvent".

To improve the performance of the browser, support for mutation events has been removed in in BlackBerry 6.

Back To Top

Mutation event types

Event type

Bubbles

Cancelable

Description

DOMAttrModified

yes

yes

Occurs when Attr.value has been modified on a node, or when an Attr node has been added or removed. The EventTarget is the Element node to which the Attr is attached.

This event type includes the following context information:

  • MutationEvent.attrName
  • MutationEvent.attrChange
  • MutationEvent.newValue
  • MutationEvent.prevValue
  • MutationEvent.relatedNode

DOMCharacterDataModified

yes

no

Occurs when CharacterData.data or ProcessingInstruction.data have been modified on a node. The EventTarget is the CharacterData node or ProcessingInstruction node.

This event type includes the following context information:

  • MutationEvent.newValue
  • MutationEvent.prevValue

DOMContentLoaded

no

no

Occurs when the BlackBerry Browser has completely parsed the document, before any onload events are triggered.

DOMNodeInserted

yes

no

Occurs when a node has been added as a child of another node, or if an Attr node has been added to an Element node.

This event type includes the following context information:

  • MutationEvent.relatedNode

DOMNodeInsertedIntoDocument

yes

no

Occurs when a node has been inserted into the document, either directly or as part of a subtree.

DOMNodeRemoved

yes

no

Occurs when a node has been removed from another node, or if an Attr node has been removed from its Element node.

This event type includes the following context information:

  • MutationEvent.relatedNode

DOMNodeRemovedFromDocument

yes

no

Occurs when a node has been removed from the document, either directly or as part of a subtree.

DOMSubtreeModified

yes

no

Occurs when any modification has been made to the document, encompassing all other MutationEvent types.

Back To Top

MutationEvent properties

Property name

Type

Description

Status

Availability

attrChange

unsigned short

Returns the type of change that triggered the DOMAttrModified event. This property can return one of the following values:

  • 1 = MODIFICATION: An existing Attr object was modified in place.
  • 2 = ADDITION: A new Attr object was added to the DOM.
  • 3 = REMOVAL: An Attr object was removed from the DOM.

read only

4.6 or later

attrName

DOMString

Returns the name of the changed Attr node in a DOMAttrModified event.

read only

4.6 or later

newValue

DOMString

Returns the new value of:

read only

4.6 or later

prevValue

DOMString

Returns the previous value of:

read only

4.6 or later

relatedNode

Node

Returns the secondary node affected by a mutation event.

read only

4.6 or later

Property name

Type

Description

Status

Support level

Availability

attrChange

unsigned short

Returns the type of change that triggered the DOMAttrModified event. This property can return one of the following values:

  • MODIFICATION
  • ADDITION
  • REMOVAL

read only

DOM 2 Events

4.6 or later

attrName

DOMString

Returns the name of the changed Attr node in a DOMAttrModified event.

read only

DOM 2 Events

4.6 or later

newValue

DOMString

Returns the new value of:

  • the Attr node in a DOMAttrModified event

  • the CharacterData node in a DOMCharacterDataModified event

read only

DOM 2 Events

4.6 or later

prevValue

DOMString

Returns the previous value of:

  • the Attr node in a DOMAttrModified event

  • the CharacterData node in a DOMCharacterDataModified event

read only

DOM 2 Events

4.6 or later

relatedNode

Node

Returns the secondary node affected by a mutation event.

read only

DOM 2 Events

4.6 or later

Back To Top

MutationEvent methods

Method name

Description

Support level

Availability

initMutationEvent()

Initializes the value of a MutationEvent.

DOM 2 Events

4.6 or later

Back To Top

Object: TextEvent

Availability

BlackBerry Device Software version 4.6 or later

Extends

UIEvent

The TextEvent object extends the UIEvent object and represents an event generated by entering characters using either the BlackBerry device or some other input source, such as a voice command. Unlike with KeyboardEvent objects, TextEvent objects can comprise multiple key presses, essentially creating an event after one or more characters have been entered.

To create an instance of a TextEvent, you must invoke Document.createEvent() with an input parameter of ”TextEvent”.

Back To Top

Text event types

Event type

Bubbles

Cancelable

Description

textInput

yes

yes

Occurs when one or more characters have been entered.

This event type includes the following context information:

TextEvent.data, UIEvent.view

Back To Top

TextEvent properties

Property name

Type

Description

Status

Support level

Availability

data

DOMString

Returns the value of the characters generated by the character device. The value of this property may be a single Unicode character or a sequence of Unicode characters. This property cannot be null or contain an empty string.

read only

DOM 3 Events

4.6 or later

Back To Top

TextEvent methods

Method name

Description

Support level

Availability

initTextEvent()

Initializes the value of a TextEvent.

DOM 3 Events

4.6 or later

initTextEventNS()

Initializes the value of a TextEvent with the given namespace URI.

DOM 3 Events

4.6 or later

Back To Top

Object: UIEvent

Availability

BlackBerry Device Software version 4.6 or later

Extends

Event

Extended by

KeyboardEvent, MouseEvent, TextEvent

The UIEvent object represents a user interface event, generated by user interaction with a BlackBerry device input method, such as the trackball or trackwheel, or the BlackBerry device keypad.

To create an instance of a UIEvent, you must invoke Document.createEvent() with an input parameter of ”UIEvent”.

Back To Top

User interface events

Event type

Bubbles

Cancelable

Description

DOMFocusIn

yes

no

Occurs when an EventTarget receives focus.

DOMFocusOut

yes

no

Occurs when an EventTarget loses focus.

DOMActivate

yes

yes

Occurs when an EventTarget is activated though a keyboard press or trackball or trackwheel click.

This event type includes the following context information:

UIEvent.detail

Back To Top

UIEvent properties

Property name

Type

Description

Status

Support level

Availability

detail

long

Returns detail information about the event.

read only

DOM 2 Events

4.6 or later

view

AbstractView

Returns a reference to the AbstractView that generated the event.

read only

DOM 2 Events

4.6 or later

Back To Top

UIEvent methods

Method name

Description

Support level

Availability

initUIEvent()

Initializes the value of a UIEvent.

DOM 2 events

4.6 or later

Back To Top
Next topic: Geolocation API
Previous topic: StyleSheetList methods

Was this information helpful? Send us your comments.