Events API
|
Object |
Description |
Availability |
|---|---|---|
|
Represents an unknown event type, typically application-specific event types. |
4.6 or later |
|
|
Provides contextual information about an event that event handlers can use. |
4.6 or later |
|
|
Represents an event listener that listens for and handles events as they occur. |
4.6 or later |
|
|
Represents an event generated by the BlackBerry device keyboard. |
4.6 or later |
|
|
Represents an event generated when an object receives a message. |
6.0 or later |
|
|
Represents an event that is generated by the BlackBerry device trackball, trackwheel, or touch screen. |
4.6 or later |
|
|
Represents an event fired when a local or session storage area changes. |
6.0 or later |
|
|
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 |
|
|
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
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".
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 |
4.6 or later |
CustomEvent methods
Object: Event
|
Availability |
|
|
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.
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 |
Event properties
|
Property name |
Type |
Description |
Status |
Support level |
Availability |
|---|---|---|---|---|---|
|
bubbles |
boolean |
When true, the event is a bubbling event. |
read only |
4.6. or later |
|
|
cancelable |
boolean |
When true, the action of the event can be cancelled using Event.preventDefault(). |
read only |
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 |
4.6. or later |
|
|
eventPhase |
unsigned short |
The phase that the event is currently in, represented using an Event constant. |
read only |
4.6. or later |
|
|
target |
EventTarget |
The target node to which the event was dispatched. |
read only |
4.6. or later |
|
|
timeStamp |
unsigned long |
The time (in milliseconds since epoch) at which the event was created. |
read only |
4.6 or later |
|
|
type |
DOMString |
The name of the event. |
read only |
4.6 or later |
Event methods
|
Method name |
Description |
Support level |
Availability |
|---|---|---|---|
|
initEvent() |
Initializes the properties of an Event object. |
4.6 or later |
|
|
preventDefault() |
Cancels the event, preventing the default action from occurring. |
4.6 or later |
|
|
stopPropagation() |
Prevents further propagation of this event during an event flow. |
4.6 or later |
Object: EventListener
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.
EventListener methods
Object: EventException
Object: KeyboardEvent
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”.
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:
|
|
keypress |
yes |
yes |
Occurs immediately after a keydown event. This event does not repeat. This event includes the following context information:
|
|
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 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 |
4.6 or later |
|
|
ctrlKey |
boolean |
Returns false. BlackBerry devices have no CTRL key. |
read only |
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 |
4.6 or later |
|
|
keyLocation |
int |
Returns a value of DOM_KEY_LOCATION_STANDARD. |
read only |
4.6 or later |
|
|
metaKey |
boolean |
Returns false. BlackBerry devices have no Meta key. |
read only |
4.6 or later |
|
|
shiftKey |
boolean |
Returns true if the SHIFT key is pressed. |
read only |
4.6 or later |
KeyboardEvent methods
Object: MessageEvent
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".
MessageEvent properties
|
Property name |
Type |
Description |
Status |
Support level |
Availability |
|---|---|---|---|---|---|
|
data |
any |
Returns the message being sent. |
read only |
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 |
6.0 or later |
|
|
lastEventId |
DOMString |
Returns the last event ID string of the event source. |
read only |
6.0 or later |
|
|
source |
WindowProxy |
Returns the WindowProxy of the browsing context of the Window object from which the message came. |
read only |
6.0 or later |
|
|
ports |
MessagePortArray |
Returns the MessagePortArray being sent, if any. |
read only |
6.0 or later |
MessageEvent methods
Object: MouseEvent
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”.
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 |
MouseEvent properties
MouseEvent methods
Object: MutationEvent
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.
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: |
|
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: |
|
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: |
|
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: |
|
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. |
MutationEvent properties
|
Property name |
Type |
Description |
Status |
Availability |
|---|---|---|---|---|
|
unsigned short |
Returns the type of change that triggered the DOMAttrModified event. This property can return one of the following values:
|
read only |
4.6 or later |
|
|
DOMString |
Returns the name of the changed Attr node in a DOMAttrModified event. |
read only |
4.6 or later |
|
|
DOMString |
Returns the new value of:
|
read only |
4.6 or later |
|
|
DOMString |
Returns the previous value of:
|
read only |
4.6 or later |
|
|
Returns the secondary node affected by a mutation event. |
read only |
4.6 or later |
|
Property name |
Type |
Description |
Status |
Support level |
Availability |
|---|---|---|---|---|---|
|
unsigned short |
Returns the type of change that triggered the DOMAttrModified event. This property can return one of the following values: |
read only |
DOM 2 Events |
4.6 or later |
|
|
DOMString |
Returns the name of the changed Attr node in a DOMAttrModified event. |
read only |
DOM 2 Events |
4.6 or later |
|
|
DOMString |
Returns the new value of:
|
read only |
DOM 2 Events |
4.6 or later |
|
|
DOMString |
Returns the previous value of:
|
read only |
DOM 2 Events |
4.6 or later |
|
|
Returns the secondary node affected by a mutation event. |
read only |
DOM 2 Events |
4.6 or later |
MutationEvent methods
Object: TextEvent
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”.
Text event types
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 |
4.6 or later |
TextEvent methods
Object: UIEvent
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”.
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: |