BlackBerry Browser

JavaScript Reference
BlackBerry Browser JavaScript Reference

Last modified: 11 September 2008

Document number: 20248101

At the time of publication, this documentation complies with BlackBerry Device Software Version 4.6 and earlier.

©2008 Research In Motion Limited. All rights reserved. BlackBerry®, RIM®, Research In Motion®, SureType® and related trademarks, names,
and logos are the property of Research In Motion Limited and are registered and/or used as trademarks in the U.S., Canada, and countries
around the world.

JavaScript is a registered trademark of Sun Microsystems, Inc. in the United States and other countries. All other trademarks are the properties
of their respective owners.

The BlackBerry smartphone and other devices and/or associated software are protected by copyright, international treaties, and various
patents, including one or more of the following U.S. patents: 6,278,442; 6,271,605; 6,219,694; 6,075,470; 6,073,318; D445,428; D433,460;
D416,256. Other patents are registered or pending in the U.S. and in various countries around the world. Visit www.rim.com/patents for a list of
RIM (as hereinafter defined) patents.

This documentation including all documentation incorporated by reference herein such as documentation provided or made available at
www.blackberry.com/go/docs is provided or made accessible "AS IS" and "AS AVAILABLE" and without condition, endorsement, guarantee,
representation, or warranty of any kind by Research In Motion Limited and its affiliated companies ("RIM") and RIM assumes no responsibility
for any typographical, technical, or other inaccuracies, errors, or omissions in this documentation. In order to protect RIM proprietary and
confidential information and/or trade secrets, this documentation may describe some aspects of RIM technology in generalized terms. RIM
reserves the right to periodically change information that is contained in this documentation; however, RIM makes no commitment to provide
any such changes, updates, enhancements, or other additions to this documentation to you in a timely manner or at all.

This documentation might contain references to third-party sources of information, hardware or software, products or services including
components and content such as content protected by copyright and/or third-party web sites (collectively the "Third Party Products and
Services"). RIM does not control, and is not responsible for, any Third Party Products and Services including, without limitation the content,
accuracy, copyright compliance, compatibility, performance, trustworthiness, legality, decency, links, or any other aspect of Third Party Products
and Services. The inclusion of a reference to Third Party Products and Services in this documentation does not imply endorsement by RIM of
the Third Party Products and Services or the third party in any way.

EXCEPT TO THE EXTENT SPECIFICALLY PROHIBITED BY APPLICABLE LAW IN YOUR JURISDICTION, ALL CONDITIONS, ENDORSEMENTS,
GUARANTEES, REPRESENTATIONS, OR WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY
CONDITIONS, ENDORSEMENTS, GUARANTEES, REPRESENTATIONS OR WARRANTIES OF DURABILITY, FITNESS FOR A PARTICULAR
PURPOSE OR USE, MERCHANTABILITY, MERCHANTABLE QUALITY, NON-INFRINGEMENT, SATISFACTORY QUALITY, OR TITLE, OR ARISING
FROM A STATUTE OR CUSTOM OR A COURSE OF DEALING OR USAGE OF TRADE, OR RELATED TO THE DOCUMENTATION OR ITS USE,
OR PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND
SERVICES REFERENCED HEREIN, ARE HEREBY EXCLUDED. YOU MAY ALSO HAVE OTHER RIGHTS THAT VARY BY STATE OR PROVINCE.
SOME JURISDICTIONS MAY NOT ALLOW THE EXCLUSION OR LIMITATION OF IMPLIED WARRANTIES AND CONDITIONS. TO THE EXTENT
PERMITTED BY LAW, ANY IMPLIED WARRANTIES OR CONDITIONS RELATING TO THE DOCUMENTATION TO THE EXTENT THEY CANNOT
BE EXCLUDED AS SET OUT ABOVE, BUT CAN BE LIMITED, ARE HEREBY LIMITED TO NINETY (90) DAYS FROM THE DATE YOU FIRST
ACQUIRED THE DOCUMENTATION OR THE ITEM THAT IS THE SUBJECT OF THE CLAIM.

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, IN NO EVENT SHALL RIM BE LIABLE FOR ANY TYPE
OF DAMAGES RELATED TO THIS DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE,
HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED HEREIN INCLUDING WITHOUT LIMITATION ANY
OF THE FOLLOWING DAMAGES: DIRECT, CONSEQUENTIAL, EXEMPLARY, INCIDENTAL, INDIRECT, SPECIAL, PUNITIVE, OR AGGRAVATED
DAMAGES, DAMAGES FOR LOSS OF PROFITS OR REVENUES, FAILURE TO REALIZE ANY EXPECTED SAVINGS, BUSINESS INTERRUPTION,
LOSS OF BUSINESS INFORMATION, LOSS OF BUSINESS OPPORTUNITY, OR CORRUPTION OR LOSS OF DATA, FAILURES TO TRANSMIT OR
RECEIVE ANY DATA, PROBLEMS ASSOCIATED WITH ANY APPLICATIONS USED IN CONJUNCTION WITH RIM PRODUCTS OR SERVICES,
DOWNTIME COSTS, LOSS OF THE USE OF RIM PRODUCTS OR SERVICES OR ANY PORTION THEREOF OR OF ANY AIRTIME SERVICES,
COST OF SUBSTITUTE GOODS, COSTS OF COVER, FACILITIES OR SERVICES, COST OF CAPITAL, OR OTHER SIMILAR PECUNIARY LOSSES,
WHETHER OR NOT SUCH DAMAGES WERE FORESEEN OR UNFORESEEN, AND EVEN IF RIM HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, RIM SHALL HAVE NO OTHER OBLIGATION, DUTY,
OR LIABILITY WHATSOEVER IN CONTRACT, TORT, OR OTHERWISE TO YOU INCLUDING ANY LIABILITY FOR NEGLIGENCE OR STRICT
LIABILITY.

THE LIMITATIONS, EXCLUSIONS, AND DISCLAIMERS HEREIN SHALL APPLY: (A) IRRESPECTIVE OF THE NATURE OF THE CAUSE OF
ACTION, DEMAND, OR ACTION BY YOU INCLUDING BUT NOT LIMITED TO BREACH OF CONTRACT, NEGLIGENCE, TORT, STRICT LIABILITY
OR ANY OTHER LEGAL THEORY AND SHALL SURVIVE A FUNDAMENTAL BREACH OR BREACHES OR THE FAILURE OF THE ESSENTIAL
PURPOSE OF THIS AGREEMENT OR OF ANY REMEDY CONTAINED HEREIN; AND (B) TO RIM AND ITS AFFILIATED COMPANIES, THEIR
SUCCESSORS, ASSIGNS, AGENTS, SUPPLIERS (INCLUDING AIRTIME SERVICE PROVIDERS), AUTHORIZED RIM DISTRIBUTORS (ALSO
INCLUDING AIRTIME SERVICE PROVIDERS) AND THEIR RESPECTIVE DIRECTORS, EMPLOYEES, AND INDEPENDENT CONTRACTORS.

IN ADDITION TO THE LIMITATIONS AND EXCLUSIONS SET OUT ABOVE, IN NO EVENT SHALL ANY DIRECTOR, EMPLOYEE, AGENT,
DISTRIBUTOR, SUPPLIER, INDEPENDENT CONTRACTOR OF RIM OR ANY AFFILIATES OF RIM HAVE ANY LIABILITY ARISING FROM OR
RELATED TO THE DOCUMENTATION.

Prior to subscribing for, installing, or using any Third Party Products and Services, it is your responsibility to ensure that your airtime service
provider has agreed to support all of their features. Installation or use of Third Party Products and Services with RIM's products and services
may require one or more patent, trademark, copyright, or other licenses in order to avoid infringement or violation of third party rights. You are
solely responsible for determining whether to use Third Party Products and Services and if any third party licenses are required to do so. If
required you are responsible for acquiring them. You should not install or use Third Party Products and Services until all necessary licenses
have been acquired. Any Third Party Products and Services that are provided with RIM's products and services are provided as a convenience to
you and are provided "AS IS" with no express or implied conditions, endorsements, guarantees, representations, or warranties of any kind by
RIM and RIM assumes no liability whatsoever, in relation thereto. Your use of Third Party Products and Services shall be governed by and
subject to you agreeing to the terms of separate licenses and other agreements applicable thereto with third parties, except to the extent
expressly covered by a license or other agreement with RIM.

The terms of use of any RIM product or service are set out in a separate license or other agreement with RIM applicable thereto. NOTHING IN
THIS DOCUMENTATION IS INTENDED TO SUPERSEDE ANY EXPRESS WRITTEN AGREEMENTS OR WARRANTIES PROVIDED BY RIM FOR
PORTIONS OF ANY RIM PRODUCT OR SERVICE OTHER THAN THIS DOCUMENTATION.

Research In Motion Limited Research In Motion UK Limited

295 Phillip Street 200 Bath Road
Waterloo, ON N2L 3W8 Slough, Berkshire SL1 3XE
Canada United Kingdom

Published in 2008
Contents
JavaScript objects ..............................................................................................................................................19
Attr .....................................................................................................................................................................19
Properties ..................................................................................................................................................19
Blackberry ........................................................................................................................................................ 20
Properties ................................................................................................................................................. 20
BlackberryLocation.......................................................................................................................................... 21
Properties .................................................................................................................................................. 21
Methods ..................................................................................................................................................... 21
onLocationUpdate()...................................................................................................................... 22
refreshLocation()........................................................................................................................... 23
removeLocationUpdate() ............................................................................................................. 24
setAidMode() ................................................................................................................................. 25
CDATASection................................................................................................................................................. 26
CharacterData..................................................................................................................................................27
Properties ..................................................................................................................................................27
Methods .....................................................................................................................................................27
appendData()................................................................................................................................. 28
deleteData()................................................................................................................................... 29
insertData().................................................................................................................................... 30
replaceData().................................................................................................................................. 31
substringData() ............................................................................................................................. 32
Comment.......................................................................................................................................................... 33
Counter............................................................................................................................................................. 34
Properties ................................................................................................................................................. 34
CSSCharsetRule.............................................................................................................................................. 35
Properties ................................................................................................................................................. 35
CSSFontFaceRule............................................................................................................................................ 36
Properties ................................................................................................................................................. 36
CSSImportRule.................................................................................................................................................37
Properties ..................................................................................................................................................37
CSSMediaRule................................................................................................................................................. 38
Properties ................................................................................................................................................. 38
Methods .................................................................................................................................................... 38
deleteRule().................................................................................................................................... 39
insertRule() .................................................................................................................................... 40
CSSPageRule.................................................................................................................................................... 41

5
BlackBerry Browser JavaScript Reference

Properties .................................................................................................................................................. 41
CSSPrimitiveValue.......................................................................................................................................... 42
Properties ................................................................................................................................................. 42
Methods .................................................................................................................................................... 43
getCounterValue() ........................................................................................................................ 44
getFloatValue().............................................................................................................................. 45
getRectValue()...............................................................................................................................46
getRGBColorValue() ..................................................................................................................... 47
getStringValue()............................................................................................................................ 48
setFloatValue() ..............................................................................................................................49
setStringValue() ............................................................................................................................ 50
CSSRule............................................................................................................................................................. 51
Properties .................................................................................................................................................. 51
CSSRuleList...................................................................................................................................................... 52
Properties ................................................................................................................................................. 52
Methods .................................................................................................................................................... 52
item()............................................................................................................................................... 53
CSSStyleDeclaration ...................................................................................................................................... 54
Properties ................................................................................................................................................. 54
Methods .................................................................................................................................................... 57
getPropertyCSSValue() ................................................................................................................ 58
getPropertyPriority() ....................................................................................................................59
getPropertyValue() .......................................................................................................................60
item()................................................................................................................................................61
removeProperty() .......................................................................................................................... 62
setProperty() .................................................................................................................................. 63
CSSStyleRule...................................................................................................................................................64
Properties .................................................................................................................................................64
CSSStyleSheet.................................................................................................................................................65
Properties .................................................................................................................................................65
Methods ....................................................................................................................................................65
deleteRule()....................................................................................................................................66
insertRule() .................................................................................................................................... 67
CSSUnknownRule...........................................................................................................................................68
CSSValue..........................................................................................................................................................69
Properties .................................................................................................................................................69
CSSValueList ................................................................................................................................................... 70
Properties ................................................................................................................................................. 70
Methods .................................................................................................................................................... 70
item()................................................................................................................................................ 71

6
CustomEvent ....................................................................................................................................................72
Properties ..................................................................................................................................................72
Methods .....................................................................................................................................................72
initCustomEventNS().....................................................................................................................73
Document......................................................................................................................................................... 74
Properties ................................................................................................................................................. 74
Methods .................................................................................................................................................... 74
createAttribute() ........................................................................................................................... 76
createAttributeNS() .......................................................................................................................77
createCDATASection() ................................................................................................................. 78
createComment() .......................................................................................................................... 79
createDocumentFragment()........................................................................................................ 80
createElement().............................................................................................................................. 81
createElementNS() ....................................................................................................................... 82
createEntityReference()............................................................................................................... 83
createEvent() ................................................................................................................................. 84
createNodeIterator() .................................................................................................................... 85
createProcessingInstruction().....................................................................................................86
createTextNode() .......................................................................................................................... 87
createTreeWalker() ....................................................................................................................... 88
getElementById() ..........................................................................................................................89
getElementsByTagName()...........................................................................................................90
getElementsByTagNameNS() ......................................................................................................91
getOverrideStyle() ........................................................................................................................ 92
importNode() ................................................................................................................................. 93
DocumentFragment .......................................................................................................................................94
DocumentType ................................................................................................................................................95
Properties .................................................................................................................................................95
DOMException................................................................................................................................................96
Constants..................................................................................................................................................96
DOMImplementation ..................................................................................................................................... 97
Methods .................................................................................................................................................... 97
createCSSStyleSheet() .................................................................................................................98
createDocument().........................................................................................................................99
createDocumentType() .............................................................................................................. 100
hasFeature().................................................................................................................................. 101
Element ...........................................................................................................................................................102
Properties ................................................................................................................................................102
Methods ...................................................................................................................................................102
getAttribute()................................................................................................................................103

7
BlackBerry Browser JavaScript Reference

getAttributeNode() ..................................................................................................................... 104

getAttributeNodeNS().................................................................................................................105
getAttributeNS() ......................................................................................................................... 106
getElementsByTagName()..........................................................................................................107
getElementsByTagNameNS() ................................................................................................... 108
hasAttribute() .............................................................................................................................. 109
hasAttributeNS().......................................................................................................................... 110
removeAttribute().......................................................................................................................... 111
removeAttributeNode()................................................................................................................112
removeAttributeNS() ....................................................................................................................113
setAttribute() .................................................................................................................................114
setAttributeNode()........................................................................................................................115
setAttributeNodeNS() ................................................................................................................. 116
setAttributeNS()............................................................................................................................117
Entity.................................................................................................................................................................118
Properties .................................................................................................................................................118
EntityReference.............................................................................................................................................. 119
Event ................................................................................................................................................................120
Properties ................................................................................................................................................120
Methods ...................................................................................................................................................120
initEvent().......................................................................................................................................121
preventDefault()........................................................................................................................... 122
stopPropagation() ........................................................................................................................ 123
EventException...............................................................................................................................................124
Constants.................................................................................................................................................124
EventListener..................................................................................................................................................125
Methods ...................................................................................................................................................125
handleEvent() ...............................................................................................................................126
History ............................................................................................................................................................. 127
Properties ................................................................................................................................................ 127
Methods ................................................................................................................................................... 127
back() .............................................................................................................................................128
forward()........................................................................................................................................129
go() .................................................................................................................................................130
HTMLAnchorElement .....................................................................................................................................131
Properties .................................................................................................................................................131
Methods ....................................................................................................................................................131
blur()............................................................................................................................................... 132
focus() ............................................................................................................................................133
HTMLAppletElement .....................................................................................................................................134

8
 Properties ................................................................................................................................................134
HTMLAreaElement.........................................................................................................................................135
Properties ................................................................................................................................................135
HTMLBaseElement ........................................................................................................................................136
Properties ................................................................................................................................................136
HTMLBaseFontElement ................................................................................................................................ 137
Properties ................................................................................................................................................ 137
HTMLBodyElement........................................................................................................................................138
Properties ................................................................................................................................................138
HTMLBRElement............................................................................................................................................139
Properties ................................................................................................................................................139
HTMLButtonElement.................................................................................................................................... 140
Properties ............................................................................................................................................... 140
HTMLCollection ..............................................................................................................................................141
Properties .................................................................................................................................................141
Methods ....................................................................................................................................................141
item()..............................................................................................................................................142
namedItem() .................................................................................................................................143
HTMLDirectoryElement ................................................................................................................................144
Properties ................................................................................................................................................144
HTMLDivElement...........................................................................................................................................145
Properties ................................................................................................................................................145
HTMLDListElement....................................................................................................................................... 146
Properties ............................................................................................................................................... 146
HTMLDocument .............................................................................................................................................147
Properties ................................................................................................................................................147
Event handlers ........................................................................................................................................148
Methods ...................................................................................................................................................148
close() ........................................................................................................................................... 149
getElementByName() ..................................................................................................................150
open()..............................................................................................................................................151
write().............................................................................................................................................152
writeln() .........................................................................................................................................153
HTMLElement.................................................................................................................................................154
Properties ................................................................................................................................................154
Event handlers ........................................................................................................................................155
HTMLFieldsetElement.................................................................................................................................. 156
Properties ............................................................................................................................................... 156
HTMLFontElement.........................................................................................................................................157
Properties ................................................................................................................................................157

9
BlackBerry Browser JavaScript Reference

HTMLFormElement........................................................................................................................................158
Properties ................................................................................................................................................158
Methods ...................................................................................................................................................158
reset()............................................................................................................................................ 159
submit()......................................................................................................................................... 160
HTMLFrameElement...................................................................................................................................... 161
Properties ................................................................................................................................................ 161
HTMLFrameSetElement................................................................................................................................162
Properties ................................................................................................................................................162
HTMLHeadElement .......................................................................................................................................163
Properties ................................................................................................................................................163
HTMLHeadingElement................................................................................................................................. 164
Properties ............................................................................................................................................... 164
HTMLHRElement .......................................................................................................................................... 165
Properties ............................................................................................................................................... 165
HTMLHtmlElement....................................................................................................................................... 166
Properties ............................................................................................................................................... 166
HTMLIFrameElement ....................................................................................................................................167
Properties ................................................................................................................................................167
HTMLImageElement..................................................................................................................................... 168
Properties ............................................................................................................................................... 168
HTMLInputElement ...................................................................................................................................... 169
Properties ............................................................................................................................................... 169
Methods ...................................................................................................................................................170
blur()................................................................................................................................................171
click() ............................................................................................................................................. 172
focus() ............................................................................................................................................ 173
select() ...........................................................................................................................................174
HTMLIsIndexElement ....................................................................................................................................175
HTMLLabelElement .......................................................................................................................................176
Properties ................................................................................................................................................176
HTMLLegendElement.................................................................................................................................... 177
Properties ................................................................................................................................................ 177
HTMLLIElement..............................................................................................................................................178
Properties ................................................................................................................................................178
HTMLLinkElement .........................................................................................................................................179
Properties ................................................................................................................................................179
HTMLMapElement ........................................................................................................................................ 180
Properties ............................................................................................................................................... 180
HTMLMenuElement........................................................................................................................................181

10
 Properties .................................................................................................................................................181
HTMLMetaElement........................................................................................................................................182
Properties ................................................................................................................................................182
HTMLModElement .........................................................................................................................................183
Properties ................................................................................................................................................183
HTMLObjectElement.....................................................................................................................................184
Properties ................................................................................................................................................184
HTMLOListElement .......................................................................................................................................185
Properties ................................................................................................................................................185
HTMLOptGroupElement.............................................................................................................................. 186
Properties ............................................................................................................................................... 186
HTMLOptionElement ....................................................................................................................................187
Properties ................................................................................................................................................187
HTMLOptionsCollection ...............................................................................................................................188
Properties ................................................................................................................................................188
Methods ...................................................................................................................................................188
item()............................................................................................................................................. 189
namedItem() ................................................................................................................................ 190
HTMLParagraphElement .............................................................................................................................. 191
Properties ................................................................................................................................................ 191
HTMLParamElement .....................................................................................................................................192
Properties ................................................................................................................................................192
HTMLPreElement...........................................................................................................................................193
Properties ................................................................................................................................................193
HTMLQuoteElement..................................................................................................................................... 194
Properties ............................................................................................................................................... 194
HTMLScriptElement ..................................................................................................................................... 195
Properties ............................................................................................................................................... 195
HTMLSelectElement..................................................................................................................................... 196
Properties ............................................................................................................................................... 196
Methods .................................................................................................................................................. 196
add()...............................................................................................................................................197
blur().............................................................................................................................................. 198
focus() ........................................................................................................................................... 199
remove()........................................................................................................................................200
HTMLStyleElement ........................................................................................................................................201
Properties ................................................................................................................................................201
HTMLTableCaptionElement ........................................................................................................................202
Properties ...............................................................................................................................................202
HTMLTableCellElement ...............................................................................................................................203

11
BlackBerry Browser JavaScript Reference

Properties ...............................................................................................................................................203
HTMLTableColElement ................................................................................................................................204
Properties ...............................................................................................................................................204
HTMLTableElement ......................................................................................................................................205
Properties ...............................................................................................................................................205
Methods ..................................................................................................................................................205
createCaption() ........................................................................................................................... 207
createTFoot() ...............................................................................................................................208
createTHead()..............................................................................................................................209
deleteCaption() ............................................................................................................................210
deleteRow()....................................................................................................................................211
deleteTFoot()................................................................................................................................. 212
deleteTHead()............................................................................................................................... 213
insertRow()....................................................................................................................................214
HTMLTableRowElement................................................................................................................................215
Properties ................................................................................................................................................215
Methods ...................................................................................................................................................215
deleteCell()....................................................................................................................................216
insertCell() .................................................................................................................................... 217
HTMLTableSectionElement..........................................................................................................................218
Properties ................................................................................................................................................218
Methods ...................................................................................................................................................218
deleteRow()...................................................................................................................................219
insertRow()...................................................................................................................................220
HTMLTextAreaElement ................................................................................................................................. 221
Properties ................................................................................................................................................ 221
Methods ................................................................................................................................................... 221
blur().............................................................................................................................................. 222
focus() ........................................................................................................................................... 223
select() .......................................................................................................................................... 224
HTMLTitleElement ........................................................................................................................................ 225
Properties ............................................................................................................................................... 225
HTMLUListElement.......................................................................................................................................226
Properties ...............................................................................................................................................226
KeyboardEvent .............................................................................................................................................. 227
Keyboard event types ........................................................................................................................... 227
Properties ............................................................................................................................................... 227
Methods .................................................................................................................................................. 228
getModifierState() ......................................................................................................................229
initKeyboardEvent()....................................................................................................................230

12
 initKeyboardEventNS() ............................................................................................................... 231
Location.......................................................................................................................................................... 232
Properties ............................................................................................................................................... 232
Methods .................................................................................................................................................. 232
assign() ......................................................................................................................................... 233
reload() ......................................................................................................................................... 234
replace() ....................................................................................................................................... 235
toString() ......................................................................................................................................236
MediaList........................................................................................................................................................ 237
Properties ............................................................................................................................................... 237
Methods .................................................................................................................................................. 237
appendMedium()......................................................................................................................... 238
deleteMedium()...........................................................................................................................239
item().............................................................................................................................................240
MimeType........................................................................................................................................................241
Properties ................................................................................................................................................241
MimeTypeArray............................................................................................................................................. 242
Properties ............................................................................................................................................... 242
Methods .................................................................................................................................................. 242
item()............................................................................................................................................. 243
namedItem() ................................................................................................................................244
MouseEvent ...................................................................................................................................................245
Mouse event types ................................................................................................................................245
Properties ...............................................................................................................................................246
Methods ..................................................................................................................................................246
initMouseEvent()......................................................................................................................... 247
MutationEvent...............................................................................................................................................249
Mutation event types............................................................................................................................249
Properties ...............................................................................................................................................250
Methods ..................................................................................................................................................250
initMutationEvent() .....................................................................................................................251
NamedFrameMap ......................................................................................................................................... 252
Properties ............................................................................................................................................... 252
Methods .................................................................................................................................................. 252
getNamedItem().......................................................................................................................... 253
item().............................................................................................................................................254
NamedNodeMap ..........................................................................................................................................255
Properties ...............................................................................................................................................255
Methods ..................................................................................................................................................255
getNamedItem()..........................................................................................................................256

13
BlackBerry Browser JavaScript Reference

getNamedItemNS() .................................................................................................................... 257

item().............................................................................................................................................258
removeNamedItem() ..................................................................................................................259
removeNamedItemNS() .............................................................................................................260
setNamedItem() ...........................................................................................................................261
setNamedItemNS().....................................................................................................................262
Navigator .......................................................................................................................................................263
Properties ...............................................................................................................................................263
Methods ..................................................................................................................................................263
javaEnabled()...............................................................................................................................264
Node ...............................................................................................................................................................265
Properties ...............................................................................................................................................265
Methods ..................................................................................................................................................266
addEventListener()...................................................................................................................... 267
appendChild()..............................................................................................................................268
cloneNode() .................................................................................................................................269
dispatchEvent() ........................................................................................................................... 270
hasAttributes().............................................................................................................................. 271
hasChildNodes() ......................................................................................................................... 272
insertBefore()............................................................................................................................... 273
isSupported() ............................................................................................................................... 274
normalize() ................................................................................................................................... 275
removeChild() .............................................................................................................................. 276
removeEventListener() ............................................................................................................... 277
replaceChild() .............................................................................................................................. 278
NodeFilter ......................................................................................................................................................279
Methods .................................................................................................................................................. 279
acceptNode() ...............................................................................................................................280
NodeIterator...................................................................................................................................................281
detach() ........................................................................................................................................ 283
nextNode() ...................................................................................................................................284
previousNode()............................................................................................................................285
NodeList .........................................................................................................................................................286
item()............................................................................................................................................. 287
Notation .........................................................................................................................................................288
Properties ...............................................................................................................................................288
Plugin..............................................................................................................................................................289
Properties ...............................................................................................................................................289
Methods ..................................................................................................................................................289
item().............................................................................................................................................290

14
 namedItem() .................................................................................................................................291
PluginArray....................................................................................................................................................292
Properties ...............................................................................................................................................292
Methods ..................................................................................................................................................292
item().............................................................................................................................................293
namedItem() ................................................................................................................................294
ProcessingInstruction ..................................................................................................................................295
Properties ...............................................................................................................................................295
Rect .................................................................................................................................................................296
Properties ...............................................................................................................................................296
RGBColor ....................................................................................................................................................... 297
Properties ............................................................................................................................................... 297
Screen.............................................................................................................................................................298
Properties ...............................................................................................................................................298
StyleSheet..................................................................................................................................................... 299
Properties .............................................................................................................................................. 299
StyleSheetList................................................................................................................................................300
Properties ...............................................................................................................................................300
Methods ..................................................................................................................................................300
item()..............................................................................................................................................301
Text .................................................................................................................................................................302
Methods ..................................................................................................................................................302
splitText() .....................................................................................................................................303
TextEvent........................................................................................................................................................304
Text event types.....................................................................................................................................304
Properties ...............................................................................................................................................304
Methods ..................................................................................................................................................304
initTextEvent() .............................................................................................................................305
initTextEventNS()........................................................................................................................306
TreeWalker ..................................................................................................................................................... 307
Properties ............................................................................................................................................... 307
Methods ..................................................................................................................................................308
firstChild() ....................................................................................................................................309
lastChild()......................................................................................................................................310
nextNode() .....................................................................................................................................311
nextSibling() ................................................................................................................................. 312
parentNode() ................................................................................................................................313
previousNode().............................................................................................................................314
previousSibling() ..........................................................................................................................315
UIEvent............................................................................................................................................................316

15
BlackBerry Browser JavaScript Reference

User interface events.............................................................................................................................316

Properties ................................................................................................................................................316
Methods ...................................................................................................................................................316
initUIEvent() ................................................................................................................................. 317
Window............................................................................................................................................................318
Properties ................................................................................................................................................318
Event handlers ........................................................................................................................................319
Methods ...................................................................................................................................................319
addEventListener()....................................................................................................................... 321
alert() ............................................................................................................................................ 322
back() ............................................................................................................................................ 323
blur().............................................................................................................................................. 324
close() ........................................................................................................................................... 325
confirm().......................................................................................................................................326
dispatchEvent() ........................................................................................................................... 327
find().............................................................................................................................................. 328
focus() ...........................................................................................................................................329
forward().......................................................................................................................................330
getComputedStyle() ....................................................................................................................331
home()........................................................................................................................................... 332
moveBy()....................................................................................................................................... 333
moveTo()....................................................................................................................................... 334
open()............................................................................................................................................ 335
print() ............................................................................................................................................336
prompt()........................................................................................................................................ 337
removeEventListener() ............................................................................................................... 338
resizeBy()......................................................................................................................................339
resizeTo() ......................................................................................................................................340
scroll() ............................................................................................................................................341
scrollBy()....................................................................................................................................... 342
scrollTo()....................................................................................................................................... 343
stop().............................................................................................................................................344
XMLHttpRequest ..........................................................................................................................................345
Properties ...............................................................................................................................................345
Methods ..................................................................................................................................................345
abort() ........................................................................................................................................... 347
addEventListener()......................................................................................................................348
dispatchEvent() ...........................................................................................................................349
getAllResponseHeaders()..........................................................................................................350
getResponseHeader()..................................................................................................................351

16
open()............................................................................................................................................ 352
removeEventListener() ...............................................................................................................354
send() ............................................................................................................................................355
setRequestHeader()....................................................................................................................356

17
BlackBerry Browser JavaScript Reference

18
JavaScript objects
Object: Attr
Availability BlackBerry® Device Software version 4.6 and later
Extends Node

The Attr object represents an attribute in an Element object.

Although Attr objects describe Element objects, they are not actually child nodes of the element they describe.
Instead, attributes are treated as properties of elements, and reside outside of the DOM tree. As a result, the
Node.parentNode, Node.previousSibling, and Node.nextSibling properties are null for Attr objects.
If a declaration for an attribute exists that defines a default value, but that attribute does not yet exist, the
attribute is automatically created and attached to an element with the given value.

Properties
Property name Type Description Status Availability
name String Returns the name of the attribute. The value of the name property read only 4.6 and later
must be unique across all attributes attached to the same Element
node.
ownerElement Element Returns the element node that this attribute is attached to. If the read only 4.6 and later
attribute is not yet attached to an element, the value of this property
is null.
specified boolean When true, this property indicates that the value for the attribute has read only 4.6 and later
been explicitly set.
If the attribute exists with a default value, this property has a value of
false.
value String Specifies the value of the attribute. writable 4.6 and later
BlackBerry Browser JavaScript Reference

Object: Blackberry
Availability BlackBerry® Device Software version 4.0 and later

The Blackberry object is a property of the Window object. It provides information about the network on which the
BlackBerry device is running, and the global position of the BlackBerry device.

Properties
Property name Type Description Status Availability
location BlackberryLocation Returns a pointer to the BlackberryLocation object. read only 4.1 and later
This property is available for BlackBerry Device Software Version 4.1
or later.
network String Returns the wireless network on which the BlackBerry device is read only 4.0 and later
communicating. The value may be one of:
• 3GPP
• CDMA
• iDEN
• Wi-Fi
Multiple networks may be supported on a single BlackBerry device. If
multiple networks are supported, they are returned as a comma-
separated list. For example:
3GPP,Wi-Fi

20
 JavaScript objects

Object: BlackberryLocation
Availability BlackBerry® Device Software version 4.1 and later

The BlackberryLocation object is a property of the Blackberry object. It provides access to the GPS location of the
BlackBerry device. The GPS location refers to the geographical co-ordinates, latitude and longitude, of the
BlackBerry device.

Properties
Property name Type Description Status Availability
GPSSupported boolean When true, this property indicates that GPS positioning is supported by read only 4.1 and later
the BlackBerry device.
latitude double Returns the current latitude, in degrees, of the BlackBerry device. read only 4.1 and later
Positive values indicate northern latitude, negative values indicate
southern latitude.
To ensure that the most accurate co-ordinate is returned, you should
register a listener using BlackberryLocation.onLocationUpdate() and
read acquire the location information within the callback.
longitude double Returns the current longitude, in degrees, of the BlackBerry device. read only 4.1 and later
Positive values indicate eastern longitude, negative values indicate
western longitude.
To ensure that the most accurate co-ordinate is returned, you should
register a listener using BlackberryLocation.onLocationUpdate() and
read acquire the location information within the callback.
timestamp unsigned Returns time (in milliseconds since epoch) at which the read only 4.6 and later
long BlackBerryLocation object was updated.
This property is only supported on BlackBerry devices running BlackBerry
Device Software version 4.6 or later.

Methods
Method name Description Availability
onLocationUpdate() Registers a callback method that is called when the location is updated using 4.1 and later
BlackberryLocation.refreshLocation().
refreshLocation() Requests an update of the location of the BlackBerry device. 4.1 and later
removeLocationUpdate() Removes a previously registered callback method. 4.6 and later
setAidMode() Specifies which method the BlackBerry device will use to obtain the GPS location. 4.1 and later

21
BlackBerry Browser JavaScript Reference

Method: onLocationUpdate()
The onLocationUpdate() method registers a listener that evaluates a string or calls function whenever the
BlackBerry® device receives updated location information.
On BlackBerry devices running versions of BlackBerry® Device Software earlier than version 4.6, this method must
be passed as a string that is evaluated each time the location is refreshed. On BlackBerry devices running
BlackBerry Device Software version 4.6 or later, you can pass a string, or use the method to register a callback
function.
Once onlocationUpdate() has been invoked, the callback occurs whenever there is an update to the location
information. This can be as frequent as once every several seconds. If you have passed the method a function, you
can cancel the callback using BlackberryLocation.removeLocationUpdate(). If you have passed a string, the
callback cannot be removed.

Syntax
blackberry.location.onLocationUpdate( callbackFunction | callbackString )

Parameters

Parameter Type Description

callbackFunction Function A JavaScript function.
For BlackBerry devices running versions of the BlackBerry Device Software that are
earlier than version 4.6, you must specify the callback as a string.
callbackString String A string to be evaluated when the location information is updated.

Return values
None.

Exceptions
None.

See also
BlackberryLocation.refreshLocation(), BlackberryLocation.removeLocationUpdate()

22
 JavaScript objects

Method: refreshLocation()
The refreshLocation() method requests an update of the location of the BlackBerry® device.
This method is asynchronous, so the script continues regardless of whether updated location information has been
received. To ensure that location information is updated before reading it, you should first register a listener using
BlackberryLocation.onLocationUpdate() that reads BlackberryLocation.latitude and BlackberryLocation.longitude,
and call refreshLocation() afterwards.

Syntax
blackberry.location.refreshLocation()

Parameters
None.

Return values
Returns “true” if the GPS location of the BlackBerry device is successfully updated, otherwise, returns false.

Exceptions
None.

See also
BlackberryLocation.onLocationUpdate(), BlackberryLocation.removeLocationUpdate()

23
BlackBerry Browser JavaScript Reference

Method: removeLocationUpdate()
The removeLocationUpdate() method removes a previously registered callback method.
This method is only supported on BlackBerry® devices running BlackBerry® Device Software version 4.6 or later.

Syntax
blackberry.location.removeLocationUpdate( callbackFunction )

Parameters

Parameter Type Description

callbackFunction Function A JavaScript function previously registered by BlackberryLocation.onLocationUpdate().

Return values
None.

Exceptions
None.

See also
BlackberryLocation.onLocationUpdate(), BlackberryLocation.refreshLocation()

24
 JavaScript objects

Method: setAidMode()
The BlackberryLocation.setAidMode() specifies which method the BlackBerry® device will use to obtain the GPS
location.
The device can obtain location information in one of three ways.

Aid Mode Value Description

Cellsite 0 This method uses the GPS location of the active cellsite tower to provide first order GPS information. It
provides the least accurate location information; however, it is the fastest location mode.
Note: This location method requires network connectivity and carrier support.
Assisted 1 This method uses the network to provide ephemeris satellite data to the device chip. It provides the GPS
location faster than the autonomous mode and more accurately than the cellsite mode.
Note: This location method requires network connectivity and carrier support.
Autonomous 2 This method uses the GPS chip on the BlackBerry device without assistance from the network. The
autonomous mode provides the first GPS location in the slowest amount of time.

Syntax
blackberry.location.setAidMode( int aidMode )

Parameters

Parameter Type Description

aidMode int The method used to obtain the GPS location. The value for this parameter may be one of:
• 0 — Cellsite
• 1 — Assisted
• 2 —Autonomous

Return values
None.

25
BlackBerry Browser JavaScript Reference

Object: CDATASection
Availability BlackBerry® Device Software version 4.6 and later
Extends Text

The CDATASection object represents CDATA sections, which escape entire blocks of text, such as XML fragments,
source code, or other content that would otherwise be interpreted as XML markup. Only the strings <![CDATA[
(which represents the start of the CDATA section) and ]]> (which represents the end) are parsed.
Although this object inherits from the Node object, Node.normalize() does not merge adjacent CDATASection
nodes.

26
 JavaScript objects

Object: CharacterData
Availability BlackBerry® Device Software version 4.6 and later
Extends Node
Extended by Comment, Text

The CharacterData object extends the Node object and can be used to access character data in the DOM. No
DOM objects directly correspond to CharacterData; rather, the methods and properties are always inherited by
other objects that require this functionality, such as Comment, Text, and CDATASection.
The content of this node is represented as UTF-16. CharacterData methods all work with numeric character offsets
and text ranges, and manipulate ranges of text as a sequence of 16-bit units. Before invoking these methods, you
should already know the ranges that you are manipulating.

Properties
Property name Type Description Status
data String The character data of the current node. writable
length int The length of the content of the data property or the CharacterData.substringData() read only
method.

Methods
Method name Description
appendData() Appends the given string to the end of the data of the node.
deleteData() Removes the specified range of data.
insertData() Inserts a string at the specified location in the data.
replaceData() Replaces the specified range of data with the given string.
substringData() Returns the specified range of data from the node.

27
BlackBerry Browser JavaScript Reference

Method: appendData()
The appendData() method appends the given string to the end of the data of the node.

Syntax
CharacterData.appendData( arg )

Parameters

Parameter Type Description

arg String The string to append.

Return values
None.

Exceptions

Exception Description
NO_MODIFICATION_ALLOWED_ERR This error is thrown if the Node is read only.

28
 JavaScript objects

Method: deleteData()
The deleteData() method removes the specified range of data.

Syntax
CharacterData.deleteData( offset, count )

Parameters

Parameter Type Description

offset int The offset position from which to start removing.
count int The number of 16-bit units to delete. If the sum of offset and count exceeds length, then
all 16-bit units from the offset to the end of the data are deleted.

Return values
None.

Exceptions

Exception Description
INDEX_SIZE_ERR This error is thrown if offset is negative, or is greater than the number of 16-bit units in
the data.
NO_MODIFICATION_ALLOWED_ERR This error is thrown if the Node is read only.

29
BlackBerry Browser JavaScript Reference

Method: insertData()
The insertData() method inserts a string at the specified location in the data.

Syntax
CharacterData.insertData( offset, arg )

Parameters

Parameter Type Description

offset int The offset position from which to start inserting.
arg String The string to insert.

Return values
None.

Exceptions

Exception Description
INDEX_SIZE_ERR This error is thrown if offset is negative, or is greater than the number of 16-bit units in
the data.
NO_MODIFICATION_ALLOWED_ERR This error is thrown if the Node is read only.

30
 JavaScript objects

Method: replaceData()
The replaceData() method replaces the specified range of data with the given string.

Syntax
CharacterData.replaceData( offset, count, arg )

Parameters

Parameter Type Description

offset int The offset position from which to start replacing.
count int The number of 16-bit units to replace. If the sum of offset and count exceeds length, then
all 16-bit units from the offset to the end of the data are replaced.
arg String The string with which to replace to the data.

Return values
None.

Exceptions

Exception Description
INDEX_SIZE_ERR This error is thrown if offset is negative, or is greater than the number of 16-bit units in
the data.
NO_MODIFICATION_ALLOWED_ERR This error is thrown if the Node is read only.

31
BlackBerry Browser JavaScript Reference

Method: substringData()
The substringData() method returns the specified range of data from the node.

Syntax
CharacterData.substringData( offset, count )

Parameters

Parameter Type Description

offset int The offset position from which to start extracting.
count int The number of 16-bit units to extract. If the sum of offset and count exceeds length, then
all 16-bit units from the offset to the end of the data are extracted.

Return values
Returns the specified range of data.

Exceptions

Exception Description
INDEX_SIZE_ERR This error is thrown if offset is negative, or is greater than the number of 16-bit units in
the data.
NO_MODIFICATION_ALLOWED_ERR This error is thrown if the Node is read only.

32
 JavaScript objects

Object: Comment
Availability BlackBerry® Device Software version 4.6 and later
Extends CharacterData

The Comment object inherits from the CharacterData object and represents the content of a comment, which
begins with <!-- and ends with -->. The contents of this node include any characters that exist between those
two markers.

33
BlackBerry Browser JavaScript Reference

Object: Counter
Availability BlackBerry® Device Software version 4.6 and later

The Counter interface is used to represent any counter or counters function value.

Properties
Property name Type Description Status
identifier String The identifier of the counter. read only
listStyle String The style of the list. read only
separator String The string used to separate nested counters. read only

34
 JavaScript objects

Object: CSSCharsetRule
Availability BlackBerry® Device Software version 4.6 and later
Extends CSSRule

The CSSCharsetRule object represents an @charset rule in a CSS style sheet. The @charset rule holds an encoding
definition.
The value of the encoding attribute does not affect the encoding of text data in the DOM objects; this encoding is
always UTF-16. After a style sheet is loaded, the value of the encoding attribute is the value found in the @charset
rule. If there was no @charset in the original document, then no CSSCharsetRule object is created. The value of the
encoding attribute may also be used as a hint for the encoding used on serialization of the style sheet.
The value of the @charset rule (and therefore of the CSSCharsetRule) may not correspond to the encoding the
document actually came in; character encoding information e.g. in an HTTP header, has priority (see CSS
document representation) but this is not reflected in the CSSCharsetRule.

Properties
Property name Type Description Status
encoding String The encoding used in the @charset rule. writable

35
BlackBerry Browser JavaScript Reference

Object: CSSFontFaceRule
Availability BlackBerry® Device Software version 4.6 and later
Extends CSSRule

The CSSFontFaceRule interface represents an @font-face rule in a CSS style sheet. The @font-face rule is used to
hold a set of font descriptions.

Properties
Property name Type Description Status
style CSSStyleDeclaration The declaration block for this rule. read only

36
 JavaScript objects

Object: CSSImportRule
Availability BlackBerry® Device Software version 4.6 and later
Extends CSSRule

The CSSImportRule interface represents an @import rule within a CSS style sheet. The @import rule is used to
import style rules from other style sheets.

Properties
Property name Type Description Status
href String The location of the style sheet to be imported. The attribute will not read only
contain the “url(...)” specifier around the URI.
media MediaList A list of media types that this style sheet can be used with. read only
styleSheet CSSStyleSheet A pointer to the CSSStyleSheet object that represents the imported read only
style sheet.

37
BlackBerry Browser JavaScript Reference

Object: CSSMediaRule
Availability BlackBerry® Device Software version 4.6 and later
Extends CSSRule

The CSSMediaRule interface represents an @media rule in a CSS style sheet. The @media rule is used to delimit
style rules for specific media types.

Properties
Property name Type Description Status
CSSRules CSSRuleList A list of the CSS Rules contained within a media block. read only
media MediaList A list of the media types to which this rule applies. read only

Methods
Method name Description
deleteRule() Removes a rule from the media block.
insertRule() Adds a rule to the media block.

38
 JavaScript objects

Method: deleteRule()
The deleteRule() method removes a rule from the media block within a CSS style sheet.

Syntax
CSSMediaRule.deleteRule( index )

Parameters

Parameter Type Description

index int The position of the rule to remove in the media block’s collection of rules.

Return values
None.

Exceptions

Exception Description
INDEX_SIZE_ERR This error is thrown if index does not correspond to any rule in the media block’s
collection of rules.
NO_MODIFICATION_ALLOWED_ERR This error is thrown if the media rule is read only.

39
BlackBerry Browser JavaScript Reference

Method: insertRule()
The insertRule() method adds a rule to the media block.

Syntax
CSSMediaRule.insertRule( rule, index )

Parameters

Parameter Type Description

rule String The text representing the rule. For rule sets, this contains both the selector and the style
declaration. For at rules, this contains both the at-identifier and the rule content.
index int The position of the rule in the media block’s collection of rules before which to insert the
new rule.
If index is equal to the length of the index, the new rule will be added to the end of the
media block.

Return values
Returns the index position of the newly added rule.

Exceptions

Exception Description
HIERARCHY_REQUEST_ERR This error is thrown if rule is not permitted at the specified index, for example, if you tried
to insert an @import rule after a standard rule set or other at-rule.
INDEX_SIZE_ERR This error is thrown if index does not correspond to any rule in the media block’s
collection of rules.
NO_MODIFICATION_ALLOWED_ERR This error is thrown if the media rule is read only.
SYNTAX_ERR The error is thrown if the rule has a syntax error and cannot be parsed.

40
 JavaScript objects

Object: CSSPageRule
Availability BlackBerry® Device Software version 4.6 and later
Extends CSSRule

The CSSPageRule interface represents a @page rule within a CSS style sheet. The @page rule is used to specify
the dimensions, orientation, margins, for paged media.

Properties
Property name Type Description Status
selectorText String The page selector for the rule. writable
style CSSStyleDeclaration The declaration block of the rule. read only

41
BlackBerry Browser JavaScript Reference

Object: CSSPrimitiveValue
Availability BlackBerry® Device Software version 4.6 and later
Extends CSSValue

The CSSPrimitiveValue object represents a single CSS value. A CSSPrimitiveValue object only occurs in a context
of a CSS property.
This object has methods to determine the current value of a specific style property, or to explicitly set a style
property. Conversions are allowed between absolute values (from millimeters to centimeters, from degrees to
radians, and so on) but not between relative values. For example, a pixel value cannot be converted to a centimeter
value. With the exception of values representing colors, percentage values can not be converted, since they are
relative to another value.
Because a color percentage value is relative to a known range (0 to 255), however, a color percentage value can be
converted to a number.

Properties
Property name Type Description Status
primitiveType unsigned short The property value type. The following constants represent the numerical read only
values used to define which units are applied to the property value:
• 0 = CSS_UNKNOWN: The value is not recognized.
• 1 = CSS_NUMBER: A simple number value.
• 2 = CSS_PERCENTAGE: A percentage value.
• 3 = CSS_EMS: A length value, based on font size.
• 4 = CSS_EXS: A length value, based on font x-height.
• 5 = CSS_PX: A length value, in pixels.
• 6 = CSS_CM: A length value, in centimeters.
• 7 = CSS_MM: A length value, in millimeters.
• 8 = CSS_IN: A length value, in inches.
• 9 = CSS_PT: A length value, in points.
• 10 = CSS_PC: A length value, in picas.
• 11 = CSS_DEG: An angle value, in degrees.
• 12 = CSS_RAD: An angle value, in radians.
• 13 = CSS_GRAD: An angle value, in grads.
• 14 = CSS_MS: A time value, in milliseconds.
• 15 = CSS_S: A time value, in seconds.
• 16 = CSS_HZ: A frequency value, in Hertz.
• 17 = CSS_KHZ: A frequency, in kilo Hertz.
• 18 = CSS_DIMENSION: A number value of an unknown dimension.
• 19 = CSS_STRING: A simple string value.
• 20 = CSS_URI: A string value representing a URI.
• 21 = CSS_IDENT: A string value representing an identifier.
• 22 = CSS_ATTR: A string value representing an attribute function.
• 23 = CSS_COUNTER: A counter or counters function.
• 24 = CSS_RECT: A Rect function.
• 25 = CSS_RGBCOLOR: An RGB color.

42
 JavaScript objects

Methods
Method name Description
getCounterValue() Retrieves a Counter value.
getFloatValue() Retrieves a float value.
getRectValue() Retrieves a Rect value.
getRGBColorValue() Retrieves an RGB color value.
getStringValue() Retrieves a string value.
setFloatValue() Sets a float value with the specified unit.
setStringValue() Sets a string value with the specified unit.

43
BlackBerry Browser JavaScript Reference

Method: getCounterValue()
The getCounterValue() method retrieves a Counter value.

Syntax
CSSPrimitiveValue.getCounterValue()

Parameters
None.

Return values
Returns a Counter object representing the value of a CSS_COUNTER.

Exceptions

Exception Description
INVALID_ACCESS_ERR This error is thrown if the CSS value contains no Counter value (that is, if it is not of type
CSS_COUNTER).

See Also
Counter

44
 JavaScript objects

Method: getFloatValue()
The getFloatValue() method retrieves a float value in the given unit. You can modify the value using the
CSSPrimitiveValue.setFloatValue() method.

Syntax
CSSPrimitiveValue.getFloatValue( unitType )

Parameters

Parameter Type Description

unitType unsigned short The unit code of the units into which the value should be converted. The unit code must
represent one of the following float unit types:
• 0 = CSS_UNKNOWN: The value is not recognized.
• 1 = CSS_NUMBER: A simple number value.
• 2 = CSS_PERCENTAGE: A percentage value.
• 3 = CSS_EMS: A length value, based on font size.
• 4 = CSS_EXS: A length value, based on font x-height.
• 5 = CSS_PX: A length value, in pixels.
• 6 = CSS_CM: A length value, in centimeters.
• 7 = CSS_MM: A length value, in millimeters.
• 8 = CSS_IN: A length value, in inches.
• 9 = CSS_PT: A length value, in points.
• 10 = CSS_PC: A length value, in picas.
• 11 = CSS_DEG: An angle value, in degrees.
• 12 = CSS_RAD: An angle value, in radians.
• 13 = CSS_GRAD: An angle value, in grads.
• 14 = CSS_MS: A time value, in milliseconds.
• 15 = CSS_S: A time value, in seconds.
• 16 = CSS_HZ: A frequency value, in Hertz.
• 17 = CSS_KHZ: A frequency, in kilo Hertz.
• 18 = CSS_DIMENSION: A number value of an unknown dimension.

Return values
Returns the float value in the given units.

Exceptions

Exception Description
INVALID_ACCESS_ERR This error is thrown if the CSS value contains no float value (that is, if it is not of type
CSS_NUMBER, CSS_PERCENTAGE, CSS_EMS, CSS_EXS, CSS_PX, CSS_CM, CSS_MM,
CSS_IN, CSS_PT, CSS_PC, CSS_DEG, CSS_RAD, CSS_GRAD, CSS_MS, CSS_S, CSS_HZ,
CSS_KHZ, or CSS_DIMENSION), or if the float value cannot be converted into the
specified units.

See Also
CSSPrimitiveValue.setFloatValue()

45
BlackBerry Browser JavaScript Reference

Method: getRectValue()
The getRectValue() method retrieves a Rect value.

Syntax
CSSPrimitiveValue.getRectValue()

Parameters
None.

Return values
Returns a Rect object representing the value of a CSS_RECT.

Exceptions

Exception Description
INVALID_ACCESS_ERR This error is thrown if the CSS value contains no Rect value (that is, if it is not of type
CSS_RECT).

See Also
Rect

46
 JavaScript objects

Method: getRGBColorValue()
The getRGBColorValue() method retrieves an RGBColor value.

Syntax
CSSPrimitiveValue.getRGBColorValue()

Parameters
None.

Return values
Returns an RGBColor object representing the value of a CSS_RGBCOLOR.

Exceptions

Exception Description
INVALID_ACCESS_ERR This error is thrown if the CSS value contains no RGB color value (that is, if it is not of
type CSS_RGB_COLOR).

See Also
RGBColor

47
BlackBerry Browser JavaScript Reference

Method: getStringValue()
The getStringValue() method retrieves a string value. You can modify the value using the
CSSPrimitiveValue.setStringValue() method.

Syntax
CSSPrimitiveValue.getStringValue()

Parameters
None.

Return values
Returns the value of a string.

Exceptions

Exception Description
INVALID_ACCESS_ERR This error is thrown if the CSS value contains no string value (that is, if it is not of type
CSS_STRING, CSS_URI, CSS_IDENT, or CSS_ATTR).

See Also
CSSPrimitiveValue.setStringValue()

48
 JavaScript objects

Method: setFloatValue()
The setFloatValue() method sets a float value with the given unit. If the property attached to this value cannot
accept the given unit type or the float value, the value will not be changed, and an exception is thrown.

Syntax
CSSPrimitiveValue.setFloatValue( unitType, floatValue )

Parameters

Parameter Type Description

unitType unsigned short The unit code for the property value. The unit code must represent one of the following
float unit types:
• 0 = CSS_UNKNOWN: The value is not recognized.
• 1 = CSS_NUMBER: A simple number value.
• 2 = CSS_PERCENTAGE: A percentage value.
• 3 = CSS_EMS: A length value, based on font size.
• 4 = CSS_EXS: A length value, based on font x-height.
• 5 = CSS_PX: A length value, in pixels.
• 6 = CSS_CM: A length value, in centimeters.
• 7 = CSS_MM: A length value, in millimeters.
• 8 = CSS_IN: A length value, in inches.
• 9 = CSS_PT: A length value, in points.
• 10 = CSS_PC: A length value, in picas.
• 11 = CSS_DEG: An angle value, in degrees.
• 12 = CSS_RAD: An angle value, in radians.
• 13 = CSS_GRAD: An angle value, in grads.
• 14 = CSS_MS: A time value, in milliseconds.
• 15 = CSS_S: A time value, in seconds.
• 16 = CSS_HZ: A frequency value, in Hertz.
• 17 = CSS_KHZ: A frequency, in kilo Hertz.
• 18 = CSS_DIMENSION: A number value of an unknown dimension.
floatValue float The new float value for the property.

Return values
None.

Exceptions

Exception Description
INVALID_ACCESS_ERR This error is thrown if the CSS value contains no float value (that is, if it is not of type
CSS_NUMBER, CSS_PERCENTAGE, CSS_EMS, CSS_EXS, CSS_PX, CSS_CM, CSS_MM,
CSS_IN, CSS_PT, CSS_PC, CSS_DEG, CSS_RAD, CSS_GRAD, CSS_MS, CSS_S, CSS_HZ,
CSS_KHZ, or CSS_DIMENSION), or if the float value cannot be converted into the
specified units.
NO_MODIFICATION_ALLOWED_ERR This error is thrown if the property is read only.

See Also
CSSPrimitiveValue.getFloatValue()

49
BlackBerry Browser JavaScript Reference

Method: setStringValue()
The setStringValue() method sets a string value with the given unit. If the property attached to this value cannot
accept the given unit type or the string value, the value will not be changed, and an exception is thrown.

Syntax
setStringValue( unitType, stringValue )

Parameters

Parameter Type Description

unitType unsigned short The unit code for the property value. The unit code must represent one of the following
string unit types:
• 19 = CSS_STRING: A simple string value.
• 20 = CSS_URI: A string value representing a URI.
• 21 = CSS_IDENT: A string value representing an identifier.
• 22 = CSS_ATTR: A string value representing an attribute function.
stringValue String The new string value for the property.

Return values
None.

Exceptions

Exception Description
INVALID_ACCESS_ERR This error is thrown if the CSS value contains no string value (that is, if it is not of type
CSS_STRING, CSS_URI, CSS_IDENT, or CSS_ATTR).
NO_MODIFICATION_ALLOWED_ERR This error is thrown if the property is read only.

See Also
CSSPrimitiveValue.getStringValue()

50
 JavaScript objects

Object: CSSRule
Availability BlackBerry® Device Software version 4.6 and later
Extended by CSSCharsetRule, CSSFontFaceRule, CSSImportRule, CSSMediaRule, CSSPageRule, CSSStyleRule,
CSSUnknownRule

The CSSRule object is the base class used to define any rule in a CSS Style sheet, including both rule sets and
@ rules.

Properties
Property name Type Description Status
parentRule CSSRule The parent rule, if this rule is contained within another rule (for example, a read only
style rule within an @media block).
parentStyleSheet CSSStyleSheet The style sheet that contains this rule. read only
type unsigned short The type of rule. The following constants represent the numerical values used read only
to define the rule type:
• 0 = UNKNOWN_RULE: The rule is a CSSUnknownRule.
• 1 = STYLE_RULE: The rule is a CSSStyleRule.
• 2 = CHARSET_RULE: The rule is a CSSCharsetRule.
• 3 = IMPORT_RULE: The rule is a CSSImportRule.
• 4 = MEDIA_RULE: The rule is a CSSMediaRule.
• 5 = FONT_FACE_RULE: The rule is a CSSFontFaceRule.
• 6 = PAGE_RULE: The rule is a CSSPageRule.

51
BlackBerry Browser JavaScript Reference

Object: CSSRuleList
Availability BlackBerry® Device Software version 4.6 and later

The CSSRuleList object represents an ordered collection of CSSRule objects.

Properties
Property name Type Description Status
length int The number of rules in the list. read only

Methods
Method name Description
item() Returns the rule at the specified index in the collection.

52
 JavaScript objects

Method: item()
The item() method returns the CSSRule object at the specified index in the CSSRuleList.

Syntax
CSSRuleList.item( index )

Parameters

Parameter Type Description

index int An integer that represents the CSS rules’s position in rule list. Valid values are 0 to
CSSRuleList.length-1.

Return values
Returns the rule at the indexth position in CSSRuleList, or null if an invalid index position is specified.

Exceptions
None.

See also
CSSRule

53
BlackBerry Browser JavaScript Reference

Object: CSSStyleDeclaration
Availability BlackBerry® Device Software version 4.6 and later

The CSSStyleDeclaration object represents a CSS declaration block consisting of CSS properties and their values.
This object enables you to determine the style properties currently set in a block or to set style properties explicitly
within the block.
This object also provides access to the computed values of an element. It does not provide access to the specified
or actual values of the CSS cascade.

Properties
Property name Type Description Status
azimuth String Specifies the direction from which a sound originates. writable
background String Specifies any or all background properties. writable
backgroundAttachment String Specifies whether the background scrolls with the page. writable
backgroundColor String Specifies the background color for an element. writable
backgroundImage String Specifies an image resource to use as the background. writable
backgroundPosition String Specifies the starting position of a background image. writable
backgroundRepeat String Specifies how or if a background image is repeated. writable
border String Specifies any or all border properties for an element. writable
borderBottom String Specifies any or all bottom border properties for an element. writable
borderBottomColor String Specifies the bottom border color for an element writable
borderBottomStyle String Specifies the bottom border style for an element. writable
borderBottomWidth String Specifies the bottom border width of an element. writable
borderCollapse String Specifies whether the table borders are collapsed into a single border. writable
borderColor String Specifies the border color for an element writable
borderLeft String Specifies any or all left border properties for an element. writable
borderLeftColor String Specifies the left border color for an element writable
borderLeftStyle String Specifies the left border style for an element. writable
borderLeftWidth String Specifies the left border width of an element. writable
borderRight String Specifies any or all right border properties for an element. writable
borderRightColor String Specifies the right border color for an element writable
borderRightStyle String Specifies the right border style for an element. writable
borderRightWidth String Specifies the right border width of an element. writable
borderSpacing String Specifies the distance between the cell borders when not collapsed. writable
borderStyle String Specifies the border style for an element. writable
borderTop String Specifies any or all top border properties for an element. writable
borderTopColor String Specifies the top border color for an element writable
borderTopStyle String Specifies the top border style for an element. writable

54
 JavaScript objects

Property name Type Description Status

borderTopWidth String Specifies the top border width of an element. writable
borderWidth String Specifies the border width of an element. writable
bottom String Specifies the distance of the bottom edge of an element above or writable
below the parent element.
captionSide String Specifies the location of the table caption. writable
clear String Specifies the side(s) of an element that may not be adjacent to writable
floating elements.
clip String Specifies the shape of the element. writable
color String Specifies the foreground color for an element. writable
content String Used with the :before and :after pseudo-elements to generate writable
content.
counterIncrement String Specifies how much the counter is incremented for every occurrence writable
of the element.
counterReset String Resets a counter for an element. writable
cue String Specifies any or all cue properties. writable
cueAfter String Specifies a URI containing a sound that is played after an element. writable
cueBefore String Specifies a URI containing a sound that is played before an element. writable
cursor String Specifies the type of cursor. writable
direction String Specifies the base direction of the text. writable
display String Specifies how or if an element is displayed. writable
elevation String Specifies the elevation from which a sound originates. writable
emptyCells String Specifies whether empty cells are displayed when the borders are not writable
merged.
CSSFloat String Specifies where an image or text will appear in another element. writable
font String Specifies any or all of the font properties for an element. writable
fontFamily String Specifies the font family for an element. writable
fontSize String Specifies the font size for an element. writable
fontStyle String Specifies the style of the font for an element. writable
fontVariant String Specifies whether the font for an element is rendered in small caps. writable
fontWeight String Specifies the thickness of the font for an element. writable
height String Specifies the height of an element. writable
left String Specifies the distance of the left edge of an element from the right or writable
left edge of the parent element.
length int The number of properties that have been explicitly set. read only
letterSpacing String Specifies the spacing between the characters. writable
lineHeight String Specifies the height of each line in an element. writable
listStyle String Specifies any or all of the list properties. writable
listStyleImage String Specifies the image used for the list marker. writable
listStylePosition String Specifies the location of the list marker. writable
listStyleType String Specifies the type of list marker. writable
margin String Specifies the margin around all sides of an element. writable

55
BlackBerry Browser JavaScript Reference

Property name Type Description Status

marginBottom String Specifies the margin below an element. writable
marginLeft String Specifies the margin to the left of an element. writable
marginRight String Specifies the margin to the right of an element. writable
marginTop String Specifies the margin above an element. writable
maxHeight String Specifies the maximum height for an element. writable
maxWidth String Specifies the maximum width for an element. writable
minHeight String Specifies the minimum height for an element. writable
minWidth String Specifies the minimum width for an element. writable
orphans String Specifies the minimum number of lines left at the bottom of a page. writable
outline String Specifies any or all of the outline properties. writable
outlineColor String Specifies the outline color for an element writable
outlineStyle String Specifies the outline style for an element. writable
outlineWidth String Specifies the outline width for an element. writable
overflow String Specifies the behavior when the content of an element overflows the writable
available space for that element.
padding String Specifies the padding around all sides of an element writable
paddingBottom String Specifies the padding applied below an element. writable
paddingLeft String Specifies the padding applied to the left of an element. writable
paddingRight String Specifies the padding applied to the right of an element. writable
paddingTop String Specifies the padding applied above an element. writable
pageBreakAfter String Specifies how the page breaks after the element are handled. writable
pageBreakBefore String Specifies how the page breaks before the element are handled. writable
pageBreakInside String Specifies how the page breaks within the element are handled. writable
parentRule CSSRule The CSS Rule that contains this declaration block. read only
pause String Specifies any or all of the pause properties. writable
pauseAfter String Specifies a pause to be observed after an element. writable
pauseBefore String Specifies a pause to be observed before an element. writable
pitch String Specifies the average pitch of the speaking voice. writable
pitchRange String Specifies the variation in average pitch. writable
playDuring String Specifies a sound to be played in the background while an element’s writable
content is spoken.
position String Specifies the position of the element. writable
quotes String Specifies the quotation marks to use for embedded quotations. writable
richness String Specifies the brightness of the speaking voice. writable
right String Specifies the distance of the right edge of the of an element from the writable
right or left edge of the parent element.
speak String Specifies whether text will be rendered aurally. writable
speakHeader String Specifies how table headers are rendered aurally. writable
speakNumeral String Specifies how numerals are spoken. writable
speakPunctuation String Specifies how punctuation is spoken. writable
speechRate String Specifies the speaking rate. writable

56
 JavaScript objects

Property name Type Description Status

stress String Specifies the level of intonation of a voice. writable
tableLayout String Specifies whether the column width is fixed or determined by the writable
width of the content.
textAlign String Specifies the horizontal alignment of the text for an element. writable
textDecoration String Specifies the decoration applied to the text. writable
textIndent String Specifies the indentation of the first line of text in a block of text. writable
textTransform String Specifies how the text is capitalized. writable
top String Specifies the distance of the top edge of an element above or below writable
the parent element.
unicodeBidi String Specifies the Unicode bidirectional algorithm to use. writable
verticalAlign String Specifies the vertical alignment of an element. writable
visibility String Specifies whether elements are rendered or not. writable
voiceFamily String Specifies a list of voice family names. writable
volume String Specifies the median volume of the wave form. writable
whitepsace String Specifies how white space in an element is handled. writable
widows String Specifies the minimum number of lines left at the top of a page. writable
width String Specifies the width of an element. writable
wordSpacing String Specifies the spacing between words. writable
zIndex String Specifies the stack order of an element. writable

Methods
Method name Description
getPropertyCSSValue() Returns the value of a CSS property as an object, if the property has been explicitly set.
getPropertyPriority() Returns the priority of a CSS property.
getPropertyValue() Returns the value of a CSS property as a string, if the property has been explicitly set.
item() Returns the name of the CSS property at the specified index in the collection.
removeProperty() Removes a CSS property from the style declaration block.
setProperty() Sets the value of a CSS property for the style declaration block.

57
BlackBerry Browser JavaScript Reference

Method: getPropertyCSSValue()
The getPropertyCSSValue() method returns the value of a CSS property as an object, if the property has been
explicitly set.
This method cannot access the shorthand property values. The values for shorthand properties can only be
accessed and modified as strings, using CSSStyleDeclaration.getPropertyValue() and
CSSStyleDeclaration.setProperty()

Syntax
CSSStyleDeclaration.getPropertyCSSValue( propertyName )

Parameters

Parameter Type Description

propertyName String The name of the CSS property for which to retrieve the value.

Return values
Returns the CSSValue object for the given property, if that property has been explicitly set for this declaration
block; if no value has been set, or if the property is a shorthand property, returns null.

Exceptions
None.

58
 JavaScript objects

Method: getPropertyPriority()
The getPropertyPriority() method returns the priority of a CSS property. This method can be used to determine
whether the “!important” qualifier has been specified.

Syntax
CSSStyleDeclaration.getPriorityProperty( propertyName )

Parameters

Parameter Type Description

propertyName String The name of the CSS property for which to retrieve the priority.

Return values
Returns a string representing the priority of the CSS property, if that property has a priority specified; if no
priority has been specified, returns an empty string.

Exceptions
None.

59
BlackBerry Browser JavaScript Reference

Method: getPropertyValue()
The getPropertyValue() method returns the value of a CSS property as a string, if the property has been explicitly
set.

Syntax
CSSStyleDeclaration.getPropertyValue( propertyName )

Parameters

Parameter Type Description

propertyName String The name of the CSS property for which to retrieve the value.

Return values
Returns the value of the given CSS property as a string, if that property has been explicitly set for this
declaration block; if no value has been set, returns null.

Exceptions
None.

60
 JavaScript objects

Method: item()
The item() method returns the name of the CSS property at the specified index in the collection.

Syntax
CSSStyleDeclaration.item( index )

Parameters

Parameter Type Description

index int An integer that represents the CSS property’s position in style declaration block.

Return values
Returns the name of the CSS property at the indexth position in CSSStyleDeclaration, or an empty string if no
property exists at the index position specified.

Exceptions
None.

61
BlackBerry Browser JavaScript Reference

Method: removeProperty()
The removeProperty() method removes a CSS property from the style declaration block.

Syntax
CSSStyleDeclaration.removeProperty( propertyName )

Parameters

Parameter Type Description

propertyName String The name of the CSS property to remove.

Return values
Returns the value of the removed CSS property as a string, if that property has been explicitly set for this
declaration block; if no value has been set, returns null.

Exceptions

Exception Description
NO_MODIFICATION_ALLOWED_ERR This error is thrown if either the style declaration or the property is read only.

62
 JavaScript objects

Method: setProperty()
The setProperty() method sets the value of a CSS property for the style declaration block.

Syntax
CSSStyleDeclaration.setProperty( propertyName, value, priority )

Parameters

Parameter Type Description

propertyName String The name of the new CSS property.
value String The value of the new property.
priority String The priority of the new property, or an empty string, if no priority is to be set.

Return values
None.

Exceptions

Exception Description
NO_MODIFICATION_ALLOWED_ERR This error is thrown if either the style declaration or the property is read only.
SYNTAX_ERR This error is thrown if the given value has a syntax error and cannot be parsed.

63
BlackBerry Browser JavaScript Reference

Object: CSSStyleRule
Availability BlackBerry® Device Software version 4.6 and later
Extends CSSRule

The CSSStyleRule object represents a single rule set in a CSS style sheet.

Properties
Property name Type Description Status
selectorText String The name of the CSS selector for the rule set. writable
style CSSStyleDeclaration The style values for the CSS selector. read only

64
 JavaScript objects

Object: CSSStyleSheet
Availability BlackBerry® Device Software version 4.6 and later
Extends StyleSheet

The CSSStyleSheet object represents a CSS style sheet.

Properties
Property name Type Description Status
CSSRules CSSRuleList An array of the CSSRule objects in the style sheet. read only
ownerRule CSSRule The CSSImportRule object for imported style sheets. If the style sheet read only
is not imported, the value for this property is null.

Methods
Method name Description
deleteRule() Deletes a CSS Rule at the given position in the CSS style sheet.
insertRule() Adds a CSS Rule at the given position in the CSS style sheet.

65
BlackBerry Browser JavaScript Reference

Method: deleteRule()
The deleteRule() method deletes a CSS Rule at the given position in the CSS style sheet.

Syntax
CSSStyleSheet.deleteRule( index )

Parameters

Parameter Type Description

index int An integer that represents the CSS rules’s position in the style sheet’s collection of rules.

Return values
None.

Exceptions

Exception Description
NO_MODIFICATION_ALLOWED_ERR This error is thrown if the style sheet is read only.
INDEX_SIZE_ERR This error is thrown if index does not correspond to any rule in the style sheet’s collection
of rules.

66
 JavaScript objects

Method: insertRule()
The insertRule() method adds a CSS Rule at the given position in the CSS style sheet.

Syntax
CSSStyleSheet.insertRule( rule, index )

Parameters

Parameter Type Description

rule String The parsable text for the CSS Rule to add.
• For rule sets, rule includes both the selector and the style declaration.
• For at-rules, rule includes both the at-identifier and the rule content.
index int An integer that represents the position in the style sheet’s collection of rules at which
the new rule is inserted. If index is equal to StyleSheet.length, the rule is added to the
end of the list of rules.

Return values
Returns the position of the newly added style sheet in the style sheet’s collection of rules.

Exceptions

Exception Description
NO_MODIFICATION_ALLOWED_ERR This error is thrown if the style sheet is read only.
INDEX_SIZE_ERR This error is thrown if index does not correspond to any rule in the style sheet’s collection
of rules.

67
BlackBerry Browser JavaScript Reference

Object: CSSUnknownRule
Availability BlackBerry® Device Software version 4.6 and later
Extends CSSRule

The CSSUnknownRule represents an unsupported @ rule.

68
 JavaScript objects

Object: CSSValue
Availability BlackBerry® Device Software version 4.6 and later
Extended by CSSPrimitiveValue, CSSValueList

The CSSValue object represents a simple or a complex CSS property value.

Properties
Property name Type Description Status
CSSValueType unsigned short The type of value. The following constants represent the numerical read only
values used to define the value type:
• 0 = CSS_INHERIT: The value is inherited.
• 1 = CSS_PRIMITIVE: The value is a CSSPrimitiveValue.
• 2 = CSS_VALUE_LIST: The value is a CSSValueList.
• 3 = CSS_CUSTOM: The rule is a custom value.

69
BlackBerry Browser JavaScript Reference

Object: CSSValueList
Availability BlackBerry® Device Software version 4.6 and later
Extends CSSValue

The CSSValueList objects represents an ordered collection of CSSValue objects.

Some properties allow an empty list into their syntax. In that case, these properties take the none identifier. So, an
empty list means that the property has the value “none”.

Properties
Property name Type Description Status
length int The number of property values in the list. read only

Methods
Method name Description
item() Returns the CSSValue object at the specified index in the CSSValueList.

70
 JavaScript objects

Method: item()
The item() method returns the CSSValue object at the specified index in the CSSValueList.

Syntax
CSSValueList.item( index )

Parameters

Parameter Type Description

index int An integer that represents the CSS property value’s position in value list. Valid values
are 0 to CSSValueList.length-1.

Return values
Returns the property value at the indexth position in CSSValueList, or null if an invalid index position is
specified.

Exceptions
None.

71
BlackBerry Browser JavaScript Reference

Object: CustomEvent
Availability BlackBerry® Device Software version 4.6 and 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”.

Properties
Property name Type Description Status
detail Object Specifies some detail information about the Event, depending on the read only
type of event.

Methods
Method name Description
initCustomEventNS() Initializes the value of a CustomEvent created by Document.createEvent().

72
 JavaScript objects

Method: initCustomEventNS()
The initCustomEventNS() method initializes the value of a CustomEvent created by Document.createEvent().

Syntax
CustomEvent.initCustomEvent( arg, canBubbleArg, cancelableArg, detailArg )

Parameters

Parameter Type Description

arg int The event type.
canBubbleArg boolean If true, specifies that the event can bubble.
cancelableArg boolean If true, specifies that the event can be cancelled.
detailArg long The event’s detail.

Return values
None.

Exceptions
None.

73
BlackBerry Browser JavaScript Reference

Object: Document
Availability BlackBerry® Device Software version 4.6 and later
Extends Node

The Document object represents the entire HTML or XML document. It acts as the root of the tree, and provides the
primary access to the data of the document.

Properties
Property name Type Description Status
defaultView AbstractView The default view of the document. read only
doctype DocumentType The document type declaration associated with the document. read only
documentElement Element The root element in a document. read only
implementation DOMImplementation The DOMImplementation object that handles this document. read only
parentWindow Window A reference to the parent window. If no parent window exists, this property read only
points to the current active window.
styleSheets StyleSheetList An array of all the style sheets in the document. read only

Methods
Method name
createAttribute()
createAttributeNS()
createCDATASection()
createComment()
createDocumentFragment()
createElement()
createElementNS()
createEntityReference()
createEvent()
createNodeIterator()
createProcessingInstruction()
createTextNode()
createTreeWalker()
getElementById()
getElementsByTagName()
getElementsByTagNameNS()
Description
Creates a new attribute node with the given name.
Creates a new attribute object with the given qualified name and namespace URI.
Creates a new CDATASection object, which represents a block of uninterpreted content.
Creates a new Comment object with the given text as content.
Creates an empty DocumentFragment object.
Creates a new Element object of the specified type.
Creates a new Element object of the given qualified name and namespace URI.
Creates a new EntityReference object with the given name.
Creates a new Event object of the given type.
Creates a new NodeIterator object, which you can use to iterate through a set of Document nodes rooted at
the given node.
Creates a new ProcessingInstruction object with the given name and data.
Creates a new text node containing the given text.
Creates a TreeWalker object, which you can use to traverse the specified document subtree.
Returns the element node with the given ID value.
Returns a NodeList object that contains an array of a document’s descendent element nodes with the
specified tag name.
Returns a NodeList object that contains an array of a document’s descendent element nodes with the given
local name and namespace URI.

74
 JavaScript objects

Method name Description

getOverrideStyle() Retrieves the override CSSStyleDeclaration object for the given element.
importNode() Imports a node from a different document.

75
BlackBerry Browser JavaScript Reference

Method: createAttribute()
The createAttribute() method creates a new Attr node with the given name. Once created, the attribute instance
can be bound to an element using Element.setAttributeNode()
This method only populates the Node.nodeName property for the created attribute and sets the attribute’s value
to null.
To create an attribute with a qualified name and namespace URI, use Document.createAttributeNS().

Syntax
Document.createAttribute( name )

Parameters

Parameter Type Description

name String The name of the attribute to create.

Return values
Returns the new attribute node with the Node.nodeName property set to name and the Node.nodeValue
property set to an empty string.

Exceptions

Exception Description
INVALID_CHARACTER_ERR This error is thrown if newChild is one of the given node’s ancestors, or if the given node
does not allow children of the type of newChild node.

See also
Attr, Element.setAttribute(), Element.setAttributeNode()

76
 JavaScript objects

Method: createAttributeNS()
The createAttributeNS() method creates a new Attr object with the given qualified name and namespace URI.
Once created, the attribute instance can be bound to an element using Element.setAttributeNode().

Syntax
Document.createAttribute( namespaceURI, qualifiedName )

Parameters

Parameter Type Description

namespaceURI String The namespace of the new attribute.
qualifiedName String The qualified name of the attribute to create.

Return values
Returns the new attribute object with the following properties set:

Property Description
Node.nodeName The qualified name.
Node.namespaceURI The namespace URI for the attribute.
Node.prefix The prefix, extracted from the qualified name of the new attribute. If there is no prefix,
this property is set to null.
Node.localName The local name for the attribute, extracted from the qualified name.
Node.nodeValue An empty string.
Attr.name Equivalent to Node.nodeName.

Exceptions

Exception Description
INVALID_CHARACTER_ERR This error is thrown if qualifiedName contains an illegal character.
NAMESPACE_ERR This error is thrown if:
• qualifiedName is malformed,
• qualifiedName has a prefix, but namespaceURI is null
• prefix is “xml”, but namespaceURI is not
“http://www.w3.org/XML/1998/namespace”
• qualifiedName is “xmlns”, but namespaceURI is not
“http://www.w3.org/2000/xmlns/”
NOT_SUPPORTED_ERR This error is thrown if the document does not support XML namespaces.

See also
Attr, Element.setAttributeNode()

77
BlackBerry Browser JavaScript Reference

Method: createCDATASection()
The createCDATASection() method creates a new CDATASection object, which represents a block of uninterpreted
content.
HTML documents do not support CDATASection objects.

Syntax
Document.createCDATASection( data )

Parameters

Parameter Type Description

data String The contents of the CDATASection node.

Return values
Returns the new CDATASection object.

Exceptions

Exception Description
NOT_SUPPORTED_ERR This error is thrown if the document is an HTML document.

See also
CDATASection

78
 JavaScript objects

Method: createComment()
The createComment() method creates a new Comment object with the given text as content.

Syntax
Document.createComment( data )

Parameters

Parameter Type Description

data String The contents of the Comment node.

Return values
Returns the new Comment object.

Exceptions
None.

See also
Comment

79
BlackBerry Browser JavaScript Reference

Method: createDocumentFragment()
The createDocumentFragment() method creates an empty DocumentFragment object.
A DocumentFragment object can be used to hold and move a portion of a document—such as multiple parent
nodes and their children—at once.

Syntax
Document.createDocumentFragment()

Parameters
None.

Return values
Returns the new empty DocumentFragment object.

Exceptions
None.

See also
DocumentFragment

80
 JavaScript objects

Method: createElement()
The createElement() method creates a new Element object of the specified type. Attributes can be set directly on
the returned object.
If the Element type returned has any attributes with default values, those attributes will be created and attached
to the element with their default values.

Syntax
Document.createElement( tagName )

Parameters

Parameter Type Description

tagName String The type of element to create.
In an XML document, tagName is case-sensitive.

Return values
Returns the new Element object, with the Node.nodeName property set to tagName, and zero or more Attr
objects attached, representing the known attributes that have default values.

Exceptions

Exception Description
INVALID_CHARACTER_ERR This error is thrown if tagName contains an illegal character.

See also
Attr, Element

81
BlackBerry Browser JavaScript Reference

Method: createElementNS()
The createElementNS() method creates a new Element object of the given qualified name and namespace URI.
Attributes can be set directly on the returned object.

Syntax
Document.createElementNS( namespaceURI, qualifiedName )

Parameters

Parameter Type Description

namespaceURI String The namespace of the new element.
qualifiedName String The qualified name of the element to create.

Return values
Returns the new Element object, with the following properties set:

Property Description
Node.nodeName The qualified name.
Node.namespaceURI The namespace URI for the attribute.
Node.prefix The prefix, extracted from the qualified name of the new attribute. If there is no prefix,
this property is set to null.
Node.nodeValue An empty string.
Element.tagName Equivalent to Node.nodeName.

Exceptions

Exception Description
INVALID_CHARACTER_ERR This error is thrown if qualifiedName contains an illegal character.
NAMESPACE_ERR This error is thrown if:
• qualifiedName is malformed,
• qualifiedName has a prefix, but namespaceURI is null
• prefix is “xml”, but namespaceURI is not
“http://www.w3.org/XML/1998/namespace”
• qualifiedName is “xmlns”, but namespaceURI is not
“http://www.w3.org/2000/xmlns/”

See also
Attr, Element

82
 JavaScript objects

Method: createEntityReference()
The createEntityReference() method creates a new EntityReference object with the given name.
If the referenced entity is known, then that object’s list of child nodes is made the same as the corresponding
Entity node.

Syntax
Document.createEntityReference( name )

Parameters

Parameter Type Description

name String The name of the entity to reference.

Return values
Returns the new EntityReference object.

Exceptions

Exception Description
INVALID_CHARACTER_ERR This error is thrown if name contains an illegal character.
NOT_SUPPORTED_ERR This error is thrown if the document is an HTML document.

See also
Entity, EntityReference

83
BlackBerry Browser JavaScript Reference

Method: createEvent()
The createEvent() method creates a new Event object of the given type.
If the event is to be dispatched via Node.dispatchEvent(), then the appropriate initialization method must be called
after the event has been created, and before it is dispatched, in order to initialize the event’s values.
This method is used to create events when it is inconvenient or unnecessary for the user to create an event
themselves.

Syntax
Document.createEvent( eventType )

Parameters

Parameter Type Description

eventType String The type of event to create.

Return values
Returns the new Event object.

Exceptions

Exception Description
NOT_SUPPORTED_ERR This error is thrown if the implementation does not support the specified Event
interface.

See also
Event

84
 JavaScript objects

Method: createNodeIterator()
The createNodeIterator() method creates a new NodeIterator object, which you can use to iterate through a set of
Document nodes rooted at the given node.

Syntax
Document.createNodeIterator( root, whatToShow, filter, entityReferenceExpansion )

Parameters

Parameter Type Description

root Node The node to be iterated with its children. The NodeIterator object is initially positioned
just before this node. The value of root must not be null.
whatToShow unsigned long The types of nodes to show in the tree view presented by the NodeIterator. The value
may be one or more of:
• 0xFFFFFFFF = SHOW_ALL
• 0x00000001 = SHOW_ELEMENT
• 0x00000002 = SHOW_ATTRIBUTE
• 0x00000004 = SHOW_TEXT
• 0x00000008 = SHOW_CDATA_SECTION
• 0x00000010 = SHOW_ENTITY_REFERENCE
• 0x00000020 = SHOW _ENTITY
• 0x00000040 = SHOW_PROCESSING_INSTRUCTION
• 0x00000080 = SHOW_COMMENT
• 0x00000100 = SHOW_DOCUMENT
• 0x00000200 = SHOW_DOCUMENT_TYPE
• 0x00000400 = SHOW_DOCUMENT_FRAGMENT
• 0x00000800 = SHOW_NOTATION
Multiple values may be specified using a bitwise OR.
Note that because attributes, entities, and notations are not the child of any other
node, they never appear in the NodeIterator’s logical view unless root is defined as a
Node of that type. If the respective object is not defined as the root, then
SHOW_ATTRIBUTE, SHOW_ENTITY, and SHOW NOTATION have no meaning.
filter NodeFilter The filter to use with this NodeIterator object. This parameter may be null.
entityReferenceExpansion boolean When true, this method specifies that entity reference nodes should be expanded.

Return values
Returns the new NodeIterator object.

Exceptions

Exception Description
NOT_SUPPORTED_ERR This error is thrown if the specified root is null.

See also
NodeIterator

85
BlackBerry Browser JavaScript Reference

Method: createProcessingInstruction()
The createProcessingInstruction() method creates a new ProcessingInstruction object with the given name and
data.

Syntax
Document.createProcessingInstruction( target,data )

Parameters

Parameter Type Description

target String The target of the processing instruction.
data String The data to store in the processing instruction.

Return values
Returns the new ProcessingInstruction object.

Exceptions

Exception Description
INVALID_CHARACTER_ERR This error is thrown if target contains an illegal character.
NOT_SUPPORTED_ERR This error is thrown if the document is an HTML document.

See also
ProcessingInstruction

86
 JavaScript objects

Method: createTextNode()
The createTextNode() method creates a new Text node containing the given text.
You can create new text nodes to add text to an existing node, then use Node.normalize() to merge them into a
single node later on.

Syntax
Document.createTextNode( text )

Parameters

Parameter Type Description

text String The string of text that the Text node is to contain.

Return values
Returns the new Text object.

Exceptions

Exception Description
INVALID_CHARACTER_ERR This error is thrown if name contains an illegal character.
NOT_SUPPORTED_ERR This error is thrown if the document is an HTML document.

See also
Text

87
BlackBerry Browser JavaScript Reference

Method: createTreeWalker()
The createTreeWalker() method creates a TreeWalker object, which you can use to traverse the specified document
subtree.

Syntax
Document.createTreeWalker( root, whatToShow, filter, expandEntityReference )

Parameters

Parameter Type Description

root Node The node that will serve as the root for this TreeWalker object. The
TreeWalker.currentNode property to the value of root.
whatToShow unsigned long The types of nodes to show in the tree view. The value may be one or more of:
• 0xFFFFFFFF = SHOW_ALL
• 0x00000001 = SHOW_ELEMENT
• 0x00000002 = SHOW_ATTRIBUTE
• 0x00000004 = SHOW_TEXT
• 0x00000008 = SHOW_CDATA_SECTION
• 0x00000010 = SHOW_ENTITY_REFERENCE
• 0x00000020 = SHOW _ENTITY
• 0x00000040 = SHOW_PROCESSING_INSTRUCTION
• 0x00000080 = SHOW_COMMENT
• 0x00000100 = SHOW_DOCUMENT
• 0x00000200 = SHOW_DOCUMENT_TYPE
• 0x00000400 = SHOW_DOCUMENT_FRAGMENT
• 0x00000800 = SHOW_NOTATION
Multiple values may be specified using a bitwise OR.
Note that because attributes, entities, and notations are not the child of any other
node, they never appear in the TreeWalker’s logical view unless root is defined as a
Node of that type. If the respective object is not defined as the root, then
SHOW_ATTRIBUTE, SHOW_ENTITY, and SHOW NOTATION have no meaning.
filter NodeFilter The filter to use with this TreeWalker object. This parameter may be null.
entityReferenceExpansion boolean When true, this method expands entity reference nodes.

Return values
Returns the new TreeWalker object.

Exceptions

Exception Description
NOT_SUPPORTED_ERR This error is thrown if the specified root is null.

See also
TreeWalker

88
 JavaScript objects

Method: getElementById()
The getElementById() method returns the Element node with the given ID value.

Syntax
Document.getElementById( elementID )

Parameters

Parameter Type Description

elementID String The ID of the element to retrieve.

Return values
Returns the Element object with the given ID value, or null if no element with that ID value exists.

Exceptions
None.

Example
The following example appends a text node as a child of a new Paragraph element, then appends the
Paragraph node as a child of the node divb.
Function appendTextNode() {
var divb = document.getElementById(‘b’);
var str = document.getElementById(‘a’).value;
var pnode = document.createElement(‘p’);
var tnode = document.createTextNode(str);
pnode.appendChild(tnode);
divb.appendChild(pnode);
}

See also
Element

89
BlackBerry Browser JavaScript Reference

Method: getElementsByTagName()
The getElementsByTagName() method returns a NodeList object that contains an array of a document’s
descendent Element nodes with the specified tag name.

Syntax
Document.getElementsByTagName( tagName )

Parameters

Parameter Type Description

tagName String The name of the tag to match on. Specify a value of “*” to match all elements.

Return values
Returns a new NodeList object containing an array of all the elements with a given tag, in the order in which
they are encountered in a preorder traversal of the Document tree.

Exceptions
None.

See also
Document.getElementsByTagNameNS(), Element.getElementsByTagName(),
Element.getElementsByTagNameNS(), NodeList

90
 JavaScript objects

Method: getElementsByTagNameNS()
The getElementsByTagNameNS() method returns a NodeList object that contains an array of a document’s
descendent Element nodes with the given local name and namespace URI.

Syntax
Document.getElementsByTagNameNS( namespaceURI, localName )

Parameters

Parameter Type Description

namespaceURI String The namespace of the elements to match on. Specify a value of “*” to match all
elements.
localName String The local name of the elements to match on (that is, the qualified name minus the
prefix). Specify a value of “*” to match all local elements.

Return values
Returns a new NodeList object containing an array of all the elements with a given local name and namespace
URI, in the order in which they are encountered in a preorder traversal of the Document tree.

Exceptions
None.

See also
Document.getElementsByTagName(), Element.getElementsByTagName(),
Element.getElementsByTagNameNS(), NodeList

91
BlackBerry Browser JavaScript Reference

Method: getOverrideStyle()
The getOverrideStyle() method retrieves the override CSSStyleDeclaration object for the given element.
Override styles take precedence over authored styles, although authored styles which contain the “!important”
declaration maintain precedence and cannot be overridden using this method.
Using this method, you can override an explicitly linked style sheet without changing the authored style sheet
itself.

Syntax
Document.getOverrideStyle( elt, pseudoElt )

Parameters

Parameter Type Description

elt Element The element for which to modify the style.
pseudoElt String The pseudo-element for which to modify the style. This parameter may be null.

Return values
Returns the CSSStyleDeclaration object.

Exceptions
None.

See also
CSSStyleDeclaration

92
 JavaScript objects

Method: importNode()
The importNode() method imports a node from a different document.
This method is similar to Node.cloneNode(), except that it functions across documents.
The returned node has no parent, and the source node is not altered or removed from the original document; this
method creates a new copy of the source node.
Importing a node creates a new node object owned by the document the node is imported into, with values
identical to the Node.nodeName and Node.nodeType, plus the attributes related the namespaces. Additional
information is copied as appropriate to the node type.

Syntax
Document.importNode( importedNode, deep )

Parameters

Parameter Type Description

importedNode Node The node to import into the current document.
deep boolean When true, this method imports the given node and the subtree.
When false, this method only imports the given node; it does not include the subtree.
This parameter has no effect when the given node is an Attr, EntityReference, or
Notation node.

Return values
Returns the imported node.

Exceptions

Exception Description
NOT_SUPPORTED_ERR This error is thrown if the node type being imported is not supported.

See also
Node.cloneNode()

93
BlackBerry Browser JavaScript Reference

Object: DocumentFragment
Availability BlackBerry® Device Software version 4.6 and later
Extends Node

The DocumentFragment object is a lightweight Document object, used to create or extract only a portion of a
document.
A DocumentFragment behaves like a conventional Node object, except that it does not need to be fully formed.
When the children of a DocumentFragment object are inserted into a Document object, only the children of the
DocumentFragment, and not the DocumentFragment itself, are inserted into the node.

94
 JavaScript objects

Object: DocumentType
Availability BlackBerry® Device Software version 4.6 and later
Extends Node

The DocumentType object represents the doctype for a document. If a document has a doctype, it will be a
reference to this object.

Properties
Property name Type Description Status
entities NamedNodeMap A list of all the general entities defined within the DTD. read only
internalSubset String The contents of the DTD subset. Contains the string between the “[“ and “]” read only
characters.
name String The name of the DTD. read only
notations NamedNodeMap A list of all the notations defined within the DTD. read only
publicId String The public identifier of the external subset. read only
systemId String The system identifier of the external subset. read only

95
BlackBerry Browser JavaScript Reference

Object: DOMException
Availability BlackBerry® Device Software version 4.6 and later

The DOMException object represents an error which prevents an operation from completing.

Constants
Error code Exception Description
1 INDEX_SIZE_ERR This error is thrown if an index or size is negative, or is greater than the permitted
value.
2 DOMSTRING_SIZE_ERR This error is thrown if a range of text does not fit into a DOMString.
3 HIERARCHY_REQUEST_ERR This error is thrown if a node is inserted where it is not permitted.
4 WRONG_DOCUMENT_ERR This error is thrown if a node is used in a different document than the one that
created it.
5 INVALID_CHARACTER_ERR This error is thrown if an invalid or illegal character is used.
6 NO_DATA_ALLOWED_ERR This error is thrown if data is specified for a node which does not permit data.
7 NO_MODIFICATION_ALLOWED_ERR This error is thrown if an attempt is made to modify an object which does not permit
modifications.
8 NOT_FOUND_ERR This error is thrown if an attempt is made to reference a node that does not exist.
9 NOT_SUPPORTED_ERR This error is thrown if the implementation does not support the requested type of
object or operation.
10 INUSE_ATTRIBUTE_ERR This error is thrown if an attribute added to an Element is already an attribute of
another Element object.
11 INVALID_STATE_ERR This error is thrown if an attempt is made to use an object that is not usable.
12 SYNTAX_ERR Thie error is thrown if an invalid or illegal string is specified.
13 INVALID_MODIFICATION_ERR This error is thrown if an attempt is made to modify the type of an underlying object.
14 NAMESPACE_ERR This error is thrown if an attempt is made to create or modify an object in a way that
does not comply with namespaces.
15 INVALID_ACCESS_ERR This error is thrown if a parameter or operation is not supported by the underlying
object.

96
 JavaScript objects

Object: DOMImplementation
Availability BlackBerry® Device Software version 4.6 and later

The DOMImplementation object defines methods for performing operations that are independent of any
particular instance of the DOM, such as creating new documents. You can check the object to determine if the
DOMImplementation supports a given feature.

Methods
Method name Description
createCSSStyleSheet() Creates a new CSS stylesheet document object.
createDocument() Creates a new XML or HTML document object.
createDocumentType() Creates an empty document type node.
hasFeature() Determines whether the DOM implementation implements a specific feature.

97
BlackBerry Browser JavaScript Reference

Method: createCSSStyleSheet()
The createCSSStyleSheet() method creates a new CSSStyleSheet object.

Syntax
DOMImplementation.createCSSStyleSheet( title, media )

Parameters

Parameter Type Description

title String The title of the CSS style sheet.
media String A comma-separated list of media types associated with the new style sheet.

Return values
Returns the new CSSStyleSheet object.

Exceptions

Exception Description
SYNTAX_ERR This error is thrown if media has a syntax error that prevents the browser from being able
to parse it.

See also
CSSStyleSheet

98
 JavaScript objects

Method: createDocument()
The createDocument() method creates a new XML or HTML Document object.

Syntax
DOMImplementation.createDocument( namespaceURI, qualifiedName, doctype )

Parameters

Parameter Type Description

namespaceURI String The namespace of the new document.
qualifiedName String The qualified name of the document to create.
doctype DocumentType The type of document to be created, or null.

Return values
Returns the new Document object.

Exceptions

Exception Description
INVALID_CHARACTER_ERR This error is thrown if qualifiedName contains an illegal character.
NAMESPACE_ERR This error is thrown if:
• qualifiedName is malformed,
• qualifiedName has a prefix, but namespaceURI is null
• prefix is “xml”, but namespaceURI is not
“http://www.w3.org/XML/1998/namespace”
• qualifiedName is “xmlns”, but namespaceURI is not
“http://www.w3.org/2000/xmlns/”
NOT_SUPPORTED_ERR This error is thrown if the document does not support XML namespaces.
WRONG_DOCUMENT_ERR This error is thrown if doctype has already been used with a different document or was
created from a different implementation.

See also
Document

99
BlackBerry Browser JavaScript Reference

Method: createDocumentType()
The createDocumentType() method creates an empty DocumentType node.

Syntax
DOMImplementation.createDocumentType( qualifiedName, publicId, systemId )

Parameters

Parameter Type Description

qualifiedName String The qualified name of the document.
publicId String The qualified name of the document to create.
systemId String The type of document to be created, or null.

Return values
Returns the new DocumentType object.

Exceptions

Exception Description
INVALID_CHARACTER_ERR This error is thrown if qualifiedName contains an illegal character.
NAMESPACE_ERR This error is thrown if:
• qualifiedName is malformed,
• qualifiedName has a prefix, but namespaceURI is null
• prefix is “xml”, but namespaceURI is not
“http://www.w3.org/XML/1998/namespace”
• qualifiedName is “xmlns”, but namespaceURI is not
“http://www.w3.org/2000/xmlns/”

See also
DocumentType

100
 JavaScript objects

Method: hasFeature()
The hasFeature() method determines whether the DOM implementation implements a specific feature. This is
equivalent to functionality provided using Node.isSupported().

Syntax
DOMImplementation.hasFeature( feature, version )

Parameters

Parameter Type Description

feature String The name of the feature to test.
version String The version of the feature to test. This parameter may be null.
If version is not specified, this method returns true if any version of the feature is
supported.

Return values
Returns:
• True, if the specified version of the specified feature is supported.
• False, if the specified version of the specified feature is not supported.

Exceptions
None.

See also
Node.isSupported()

101
BlackBerry Browser JavaScript Reference

Object: Element
Availability BlackBerry® Device Software version 4.6 and later
Extends Node
Extended by HTMLElement

The Element object represents an element in an HTML or XML document. Elements may have attributes associated
with them. You can use the Node.attributes property to retrieve a map of all the attributes attached to the element.
This object provides several methods for handling all the available attributes, individual attribute values, or
individual Attr objects.

Properties
Property name Type Description Status
tagName String The name of the element. read only

Methods
Method name
getAttribute()
getAttributeNode()
getAttributeNodeNS()
getAttributeNS()
getElementsByTagName()
getElementsByTagNameNS()
hasAttribute()
hasAttributeNS()
removeAttribute()
removeAttributeNode()
removeAttributeNS()
setAttribute()
setAttributeNode()
setAttributeNodeNS()
setAttributeNS()
Description
Retrieves the value of the attribute of the given name.
Retrieves the attribute node of the given name.
Retrieves the attribute node with the given namespace URI and local name.
Retrieves the value of the attribute with the given namespace URI and local name.
Returns a NodeList object that contains an array of an element’s descendent element nodes with the
specified tag name.
Returns a NodeList object that contains an array of an element’s descendent element nodes with the
given local name and namespace URI.
Determines whether an attribute of the given name is specified on the element.
Determines whether an attribute of the given namespace and local name is specified on the element.
Removes the attribute of the given name from the element node.
Removes the specified attribute node from the element node.
Removes the attribute node with the given namespace URI and local name from the element node.
Adds a new attribute to an element, and sets it to the given value.
Adds a new attribute node to an element.
Adds a new attribute node to an element.
Adds a new attribute to an element, and sets it to the given value.

102
 JavaScript objects

Method: getAttribute()
The getAttribute() method retrieves the value of the attribute of the given name.
Note that this method returns a copy of the value, rather than the value itself. As a result, you cannot use this
method to actually change the value; you must use methods such as Element.getAttributeNode() or
Element.getAttributeNodeNS() to change the value of the attribute.

Syntax
Element.getAttribute( name )

Parameters

Parameter Type Description

name String The name of the attribute for which to retrieve the value.

Return values
Returns the Node.nodeValue property of the Attr object as a string, or the empty string if that attribute has no
specified or default value.

Exceptions
None.

See also
Attr, Element.getAttributeNode(), Element.getAttributeNodeNS(), Element.getAttributeNS(), Node.attributes

103
BlackBerry Browser JavaScript Reference

Method: getAttributeNode()
The getAttributeNode() method retrieves the attribute node of the given name.
Unlike Element.getAttribute(), this method allows you to access the Attr object without having to iterate over the
Node.attributes property.

Syntax
Element.getAttributeNode( name )

Parameters

Parameter Type Description

name String The name of the attribute node to retrieve.

Return values
Returns the Attr object with a Node.nodeName property of name, or a value of null the specified attribute
doesn’t exist.

Exceptions
None.

See also
Attr, Element.getAttribute(), Element.getAttributeNodeNS(), Element.getAttributeNS(), Node.attributes

104
 JavaScript objects

Method: getAttributeNodeNS()
The getAttributeNodeNS() method retrieves the Attr node with the given namespace URI and local name.

Syntax
Element.getAttributeNodeNS( namespaceURI, localName )

Parameters

Parameter Type Description

namespaceURI String The namespace of the attribute to retrieve. Specifying a value of null makes this method
functionally equivalent to Element.getAttributeNode().
localName String The local name of the attribute to retrieve.

Return values
Returns the Attr object with the given namespace URL and local name, or a value of null the specified
attribute doesn’t exist.

Exceptions

Exception Description
NOT_SUPPORTED_ERR This error is thrown if the document does not support XML namespaces.

See also
Attr

105
BlackBerry Browser JavaScript Reference

Method: getAttributeNS()
The getAttribute() method retrieves the value of the Attr with the given namespace URI and local name.

Syntax
Element.getAttribute( namespaceURI, localName )

Parameters

Parameter Type Description

namespaceURI String The namespace of the attribute for which to retrieve the value. Specifying a value of null
makes this method functionally equivalent to Element.getAttribute().
localName String The local name of the attribute for which to retrieve the value.

Return values
Returns the Node.nodeValue property of the Attr object as a string, or the empty string if that attribute has no
specified or default value.

Exceptions

Exception Description
NOT_SUPPORTED_ERR This error is thrown if the document does not support XML namespaces.

See also
Attr

106
 JavaScript objects

Method: getElementsByTagName()
The getElementsByTagName() method returns a NodeList object that contains an array of an element’s
descendent Element nodes with the specified tag name.
This method is identical to Document.getElementsByTagName(), except that it allows you to search a smaller
subset of Element nodes.

Syntax
Element.getElementsByTagName( name )

Parameters

Parameter Type Description

tagName String The name of the tag to match on. Specify a value of “*” to match all elements.

Return values
Returns a new NodeList object containing an array of all the elements that match tagName, in the order in
which they are encountered in a preorder traversal of the Document tree.

Exceptions
None.

See also
Document.getElementsByTagName(), Document.getElementsByTagNameNS(),
Element.getElementsByTagNameNS()

107
BlackBerry Browser JavaScript Reference

Method: getElementsByTagNameNS()
The getElementsByTagNameNS() method returns a NodeList object that contains an array of an element’s
descendent Element nodes with the given local name and namespace URI.
This method is identical to Document.getElementsByTagNameNS(), except that it allows you to search a smaller
subset of Element nodes.

Syntax
Element.getElementsByTagNameNS( namespaceURI, localName)

Parameters

Parameter Type Description

namespaceURI String The namespace of the elements to match on. Specify a value of “*” to match all
elements.
Specifying a value of null makes this method functionally equivalent to
Element.getElementsByTagName().
localName String The local name of the elements to match on (that is, the qualified name minus the
prefix). Specify a value of “*” to match all local elements.

Return values
Returns a new NodeList object containing an array of all the elements with a given local name and namespace
URI, in the order in which they are encountered in a preorder traversal of the Document tree.

Exceptions

Exception Description
NOT_SUPPORTED_ERR This error is thrown if the document does not support XML namespaces.

See also
Document.getElementsByTagName(), Document.getElementsByTagNameNS(),
Element.getElementsByTagName()

108
 JavaScript objects

Method: hasAttribute()
The hasAttribute() method determines whether an attribute of the given name is specified on the element. You
can use this method to verify that an attribute is attached to an element before retrieving it.

Syntax
Element.hasAttribute( name )

Parameters

Parameter Type Description

name String The name of the attribute to check.

Return values
Returns:
• True, if the specified attribute exists on the element
• False, if the attribute does not exist

Exceptions
None.

109
BlackBerry Browser JavaScript Reference

Method: hasAttributeNS()
The hasAttribute() method determines whether an attribute of the given namespace and local name is specified
on the element. You can use this method to verify that an attribute is attached to an element before retrieving it.

Syntax
Element.hasAttributeNS( namespaceURI, localName)

Parameters

Parameter Type Description

namespaceURI String The namespace of the attribute to check.
localName String The local name of the attribute to check.

Return values
Returns:
• True, if the specified attribute exists on the element
• False, if the attribute does not exist

Exceptions

Exception Description
NOT_SUPPORTED_ERR This error is thrown if the document does not support XML namespaces.

110
 JavaScript objects

Method: removeAttribute()
The removeAttribute() method removes the Attr node of the given name from the element node.
If you are removing an attribute from the Element object that is known to have a default value, the attribute will
immediately be reattached to the element with its default value, as well as its corresponding namespace URI, local
name, and prefix, if applicable.
If the attribute has no specified or default value, this method has no effect.

Syntax
Element.removeAttribute( name )

Parameters

Parameter Type Description

name String The name of the attribute node to remove.

Return values
None.

Exceptions

Exception Description
NO_MODIFICATION_ALLOWED_ERR This error is thrown if the Element node is read only.
NOT_FOUND_ERR This error is thrown if no node exists in the Element with a nodeName vlaue of name.

See also
Attr

111
BlackBerry Browser JavaScript Reference

Method: removeAttributeNode()
The removeAttributeNode() method removes the specified Attr node from the element node.
If you are removing an attribute from the Element object that is known to have a default value, the attribute will
immediately be reattached to the element with its default value, as well as its corresponding namespace URI, local
name, and prefix, if applicable.

Syntax
Element.removeAttributeNode( oldAttr )

Parameters

Parameter Type Description

oldAttr Attr The Attribute node to remove from the attribute list.

Return values
The removed Attr object.

Exceptions

Exception Description
NO_MODIFICATION_ALLOWED_ERR This error is thrown if the Element node is read only.
NOT_FOUND_ERR This error is thrown if the oldAttr node does not exist in the Element.

See also
Attr

112
 JavaScript objects

Method: removeAttributeNS()
The removeAttributeNS() method removes the Attr node with the given namespace URI and local name from the
element node.
If you are removing an attribute from the Element object that is known to have a default value, the attribute will
immediately be reattached to the element with its default value, as well as its corresponding namespace URI, local
name, and prefix, if applicable.
If the attribute has no specified or default value, this method has no effect.

Syntax
Element.removeAttributeNS( namespaceURI, localName )

Parameters

Parameter Type Description

namespaceURI String The namespace of the attribute to retrieve.
localName String The local name of the attribute to retrieve.

Return values
None.

Exceptions

Exception Description
NO_MODIFICATION_ALLOWED_ERR This error is thrown if the Element node is read only.
NOT_SUPPORTED_ERR This error is thrown if the document does not support XML namespaces.

See also
Attr

113
BlackBerry Browser JavaScript Reference

Method: setAttribute()
The setAttribute() method adds a new Attr node to an element, and sets it to the given value. If an attribute with
the given name already exists on the Element node, its value is changed to the given value.
This method only sets values as text strings, not entities. If the value contains any markup syntax (for example, if
the value is an EntityReference), it will not be parsed and it must be properly escaped. If you want to assign values
containing entities, you should use Element.setAttributeNode() or Element.setAttributeNodeNS().

Syntax
Element.getAttribute( name, value )

Parameters

Parameter Type Description

name String The nam e of the attribute to create or modify.
value String The value to set the attribute to, in string form.

Return values
None.

Exceptions

Exception Description
INVALID_CHARACTER_ERR This error is thrown if name contains an illegal character.
NO_MODIFICATION_ALLOWED_ERR This error is thrown if the Element node is read only.

See also
Attr, Element.setAttributeNode(), Element.setAttributeNodeNS(), Element.setAttributeNS()

114
 JavaScript objects

Method: setAttributeNode()
The setAttributeNode() method adds a new Attr node to an element. If an attribute node with the same name as
the new Attr node already exists on an element, that Attr node is replaced.
Unlike Element.setAttribute(), this method allows you to add DOM nodes, instead of specifying separate
arguments for the attribute name and value. Note that your attribute nodes cannot be reused in multiple elements;
you must either clone the Attr node, or remove an Attr node from another element before adding it to a new
element.

Syntax
Element.setAttributeNode( newAttr )

Parameters

Parameter Type Description

newAttr Attr The node of the Attribute to add to the attribute list.

Return values
If newAttr replaces an existing attribute, this method returns the replaced Attr object; otherwise it returns null.

Exceptions

Exception Description
INUSE_ATTRIBUTE_ERR This error is thrown if newAttr is already an attribute of of another Element object. To
add an attribute used elsewhere, you must clone it, and then add it.
NO_MODIFICATION_ALLOWED_ERR This error is thrown if the Element object is read only.
WRONG_DOCUMENT_ERR This error is thrown if newAttr was created from a different document than the one that
created this Element object.

See also
Attr, Element.setAttribute(), Element.setAttributeNodeNS(), Element.setAttributeNS()

115
BlackBerry Browser JavaScript Reference

Method: setAttributeNodeNS()
The setAttributeNodeNS() method adds a new Attr node to an element. If an Attr node with the same namespace
and local name as the new Attr node already exists on an element, that attribute node is replaced.
Unlike Element.setAttributeNS(), this method allows you to add DOM nodes, instead of specifying separate
arguments for the attribute name and value. Note that your attribute nodes cannot be reused in multiple elements;
you must either clone the Attr node, or remove an Attr node from another element before adding it to a new
element.

Syntax
Element.getAttributeNodeNS( newAttr )

Parameters

Parameter Type Description

newAttr Attr The node of the Attribute to add to the attribute list.

Return values
If newAttr replaces an existing attribute, this method returns the replaced Attr object; otherwise it returns null.

Exceptions

Exception Description
INUSE_ATTRIBUTE_ERR This error is thrown if newAttr is already an attribute of of another Element object. To
add an attribute used elsewhere, you must clone it, and then add it.
NO_MODIFICATION_ALLOWED_ERR This error is thrown if the Element object is read only.
NOT_SUPPORTED_ERR This error is thrown if the document does not support XML namespaces.
WRONG_DOCUMENT_ERR This error is thrown if newAttr was created from a different document than the one that
created this Element object.

See also
Attr, Element.setAttribute(), Element.setAttributeNode(), Element.setAttributeNS()

116
 JavaScript objects

Method: setAttributeNS()
The setAttributeNS() method adds a new Attr node to an element, and sets it to the given value. If an attribute with
the given namespace and local name already exists on the Element node, its prefix is change to the prefix portion
of the qualified name, and its value is changed to the given value.
This method only sets values as text strings, not entities. If the value contains any markup syntax (for example, if
the value is an EntityReference), it will not be parsed and it must be properly escaped. If you want to assign values
containing entities, you should use Element.setAttributeNode() or Element.setAttributeNodeNS().

Syntax
Element.setAttributeNS( namespaceURI, qualifiedName, value )

Parameters

Parameter Type Description

namespaceURI String The namespace of the attribute to create or modify.
qualifiedName String The qualified name of the attribute to create or modify.
value String The value of the attribute, in string form.

Return values
Returns the Node.nodeValue property of the Attr object as a string, or the empty string if that attribute has no
specified or default value.

Exceptions

Exception Description
INVALID_CHARACTER_ERR This error is thrown if name contains an illegal character.
NAMESPACE_ERR This error is thrown if:
• qualifiedName is malformed,
• qualifiedName has a prefix, but namespaceURI is null
• prefix is “xml”, but namespaceURI is not
“http://www.w3.org/XML/1998/namespace”
• qualifiedName is “xmlns”, but namespaceURI is not
“http://www.w3.org/2000/xmlns/”
NO_MODIFICATION_ALLOWED_ERR This error is thrown if the Element node is read only.
NOT_SUPPORTED_ERR This error is thrown if the document does not support XML namespaces.

See also
Attr, Element.setAttribute(), Element.setAttributeNode(), Element.setAttributeNodeNS()

117
BlackBerry Browser JavaScript Reference

Object: Entity
Availability BlackBerry® Device Software version 4.6 and later
Extends Node

The Entity object represents any entity in an XML document. Entities are declarations of abbreviated text or other
nodes within an XML document, which can be inserted at various places in an XML document using
EntityReference objects.
The Entity name is stored in the Node.nodeName property. However, the actual content of the entity is contained
within the Entity’s children. An Entity node has no parent; the Node.parentNode property for an entity will always
be null.
Entity nodes and their children are read only and can not be modified once they have been added to a document.
If you need to change the content of an Entity object, you must create a new one, then update all the
EntityReference objects that referred to the old Entity to refer to the new Entity instead.

Properties
Property name Type Description Status
notationName String For unparsed entities, the name of the notation for the entity. For parsed read only
entities, the value of this property is null.
publicId String The public identifier associated with the entity. read only
systemId String The system identifier associated with this entity. read only

118
 JavaScript objects

Object: EntityReference
Availability BlackBerry® Device Software version 4.6 and later
Extends Node

The EntityReference object represents references to Entity objects within the document. An EntityReference is a
node within the DOM tree that copies the children of the referenced Entity object.
The children of EntityReferences are read only and cannot be modified once they are added to a document.

119
BlackBerry Browser JavaScript Reference

Object: Event
Availability BlackBerry® Device Software version 4.6 and later
Extended by CustomEvent, MutationEvent, 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.

Properties
Property name Type Description Status
bubbles boolean When true, the event is a bubbling event. read only
cancelable boolean When true, the action of the event can be cancelled using preventDefault(). read only
cancelBubble boolean When true, bubbling of the event is disabled. writable
currentTarget EventTarget The node of the Document object that is currently handling the event. read only
eventPhase unsigned short The phase that the event is currently in. Valid values include: read only
• 1: Indicates that the event is in the capturing phase.
• 2: Indicates that the event is in being handled by the target node.
• 3: Indicates that the event is in the bubbling phase.
target EventTarget The target node to which the event was dispatched. read only
timeStamp unsigned long The time (in milliseconds since epoch) at which the event was created. read only
type String The name of the event. read only

Methods
Method name Description
initEvent() Initializes the properties of an Event object created by Document.createEvent().
preventDefault() Cancels the event, preventing the default action from occuring.
stopPropagation() Prevents further propagation of this event during an event flow.

120
 JavaScript objects

Method: initEvent()
The Event.initEvent() initializes the properties of an Event object created by Document.createEvent(). This method
must be called before the event has been dispatched using Node.dispatchEvent().

Syntax
Event.initEvent( eventTypeArg, canBubbleArg, cancelableArg )

Parameters

Parameter Type Description

eventTypeArge String Specifies the event type.
canBubbleArg boolean When true, this parameter indicates that the event will bubble.
cancelableArg boolean When true, this parameter indicates that Event.preventDefault() can cancel the event.

Return values
None.

Exceptions
None.

See also
CustomEvent.initCustomEventNS(), KeyboardEvent.initKeyboardEvent(), MouseEvent.initMouseEvent(),
MutationEvent.initMutationEvent(), TextEvent.initTextEvent(), UIEvent.initUIEvent()

121
BlackBerry Browser JavaScript Reference

Method: preventDefault()
The preventDefault() method cancels the event, preventing the default action from occuring.
Calling this method for an event whose cancelable property is set to false will have no effect.

Syntax
Event.preventDefault()

Parameters
None.

Return values
None.

Exceptions
None.

122
 JavaScript objects

Method: stopPropagation()
The stopPropagation() method prevents further propagation of this event during an event flow. If this method is
called by any EventListener, the event will no longer propagate through the tree. The event will complete the
dispatch to all listeners on the current EventTarget before the event flow stops.
This method can be used at any stage of the event flow.

Syntax
Event.stopPropagation()

Parameters
None.

Return values
None.

Exceptions
None.

123
BlackBerry Browser JavaScript Reference

Object: EventException
Availability BlackBerry® Device Software version 4.6 and later

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

Constants
Error code Exception Description
0 UNSPECIFIED_EVENT_TYPE_ERR This error is thrown if the Event object’s type was not specified by initializing the
event before the method was called, or if the type was given a value of null or an
empty string.
1 DISPATCH_REQUEST_ERR This error is thrown if an attempt is made to dispatch an Event object that has already
been dispatched.

124
 JavaScript objects

Object: EventListener
Availability BlackBerry® Device Software version 4.6 and later

The EventListener object represents an event listener, which is used to listen for and handle events as they occur.
EventListeners 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. Listeners should be removed from the target
after it has been used.

Methods
Method name Description
handleEvent() Called whenever an event occurs the EventListener object was registered to listen for.

125
BlackBerry Browser JavaScript Reference

Method: handleEvent()
The handleEvent() method is called whenever an event occurs on the object for which the EventListener was
registered.

Syntax
EventListener.handleEvent( evt )

Parameters

Parameter Type Description

evt Event The event type that the EventListener is registered to listen for.

Return values
None.

Exceptions
None.

126
 JavaScript objects

Object: History
Availability BlackBerry® Device Software version 4.2 and later

The History object belongs to the Window object. It stores an array of the URLs that the user visited during the
current browser session.

Properties
Property name Type Description Status
current String Returns the complete URL of the current history entry. read only
length int Returns the number of URLs in the history list. read only

Methods
Method name Description
back() Displays the previous URL in the BlackBerry® Browser History list.
forward() Displays the next element in the BlackBerry Browser History list.
go() Causes the BlackBerry Browser to display the URL that is the specified number of URLs before or after
the current item in the BlackBerry Browser History list.

127
BlackBerry Browser JavaScript Reference

Method: back()
The back() method displays the previous URL in the BlackBerry® Browser History list. This method is functionally
equivalent to the user clicking Back in the BlackBerry Browser menu or clicking the Escape key during a browser
session, or specifying History.go(-1).

Syntax
history.back()

Parameters
None.

Return values
None.

Exceptions
None.

Example
The following code fragment adds a custom button to an HTML page that displays the previous item in the
History list:
<INPUT TYPE="button" VALUE="Back" onClick="window.history.back()">

See also
History.forward(), History.go(), Window.history

128
 JavaScript objects

Method: forward()
The forward() method displays the next element in the BlackBerry® Browser History list. This method is
functionally equivalent to the user clicking Forward in the BlackBerry Browser menu, or specifying History.go(1).

Syntax
history.forward()

Parameters
None.

Return values
None.

Exceptions
None.

Example
The following code fragment adds a custom button to an HTML page that displays the next item in the History
list:
<INPUT TYPE="button" VALUE="Forward" onClick="window.history.forward()">

See also
History.back(), History.go(), Window.history

129
BlackBerry Browser JavaScript Reference

Method: go()
The go() method causes the BlackBerry® Browser to display the given URL, or the URL at the given index location
in the URL that is the specified number of URLs before or after the current item in the BlackBerry Browser History
list.

Syntax
history.go( targetURLposition )

Parameters

Parameter Type Description

targetURLposition int The position of the URL to display, relative to the current URL in the History list. A
positive value moves forward in the history list; a negative value moves backward.

Return values
None.

Exceptions
None.

Example
The following code fragment adds a custom button that causes the browser to display the URL three positions
earlier than the current URL in the History list:
<INPUT TYPE="button" VALUE="Leap back three pages!" onClick="window.history.go(-3)">

See also
History.back(), History.forward(), Window.history

130
 JavaScript objects

Object: HTMLAnchorElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLAnchorElement object represents an <a> element in an HTML document.

The <a> element defines an anchor, which can be used to create a link to another document, or to create a
bookmark within the current document.

Properties
Property name Type Description Status
accessKey String Specifies the keypad key that gives access to the element. writable
charset String Specifies the character encoding used in the referenced document; the value must be writable
the name of a standard character set.
coords String Specifies a comma-separated list of the coordinates of HTMLAnchorElement.shape, writable
which defines the active region in an image map.
href String Specifies the URI of the target of the link. writable
hreflang String Specifies the language code of the target resource. writable
name String Specifies a name for the anchor. writable
rel String Specifies the link type between the current document and the referenced resource. writable
rev String Specifies the link type between the referenced resource and the current document. writable
shape String Specifies the shape of an active region in an image map. The coordinates of the shape writable
are specified by HTMLAnchorElement.coords.
tabIndex int Specifies the element’s position in the tabbing order. writable
target String Specifies the frame in which to render the target document. writable
type String Specifies the MIME type of the target document. writable

Methods
Method name Description
blur() Removes keypad focus from the element.
focus() Gives keypad focus to the element.

131
BlackBerry Browser JavaScript Reference

Method: blur()
The blur() method removes keypad focus from the element.

Syntax
HTMLAnchorElement.blur()

Parameters
None.

Return values
None.

Exceptions
None.

132
 JavaScript objects

Method: focus()
The focus() method gives keypad focus to the element.

Syntax
HTMLAnchorElement.focus()

Parameters
None.

Return values
None.

Exceptions
None.

133
BlackBerry Browser JavaScript Reference

Object: HTMLAppletElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLAppletElement object represents an <applet> element in an HTML document.

The <applet> element embeds an applet into an HTML document. The <applet> element is deprecated in
HTML 4.01 and is not supported by the BlackBerry® Browser.
HTMLAppletElement is supported in the BlackBerry Browser’s JavaScript® implementation to conform with HTML
DOM Level 2 specification. However, <applet> elements will not be visually displayed in the browser and will not
have any impact on the document layout.

Properties
Property name Type Description Status
align String Specifies the horizontal or vertical alignment the object, relative to the surrounding text. writable
alt String Specifies alternate text that is rendered when the normal content of the element is not. writable
archive String Specifies a comma-separated list of URIs pointing to archives which contain resources writable
for the applet.
code String Specifies the location of the class file for the applet. writable
codeBase String Specifies the Base URI for the applet’s code and data. writable
height String Specifies the height of the applet. writable
hspace int Specifies the amount of white space, in pixels, inserted to the left and right of the applet. writable
name String Specifies the name for the applet. writable
object String Specifies a resource containing a serialized representation of an applet's state, which writable
provides the applet’s class name, but not the implementation. The class name is used to
retrieve the implementation.
vspace int Specifies the amount of white space, in pixels, inserted above and below the applet. writable
width String Specifies the width of the object. writable

134
 JavaScript objects

Object: HTMLAreaElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLAreaElement object represents an <area> element in an HTML document.

The <area> element defines an area of an image map. The <area> element is always a child of the <map> element.

Properties
Property name Type Description Status
accessKey String Specifies the keypad key that gives access to the element. writable
alt String Specifies alternate text that is rendered when the normal content of the element is not. writable
coords String Specifies a comma-separated list of the coordinates for HTMLAreaElement.shape, writable
which defines the active region in an image map.
href String Specifies the URI of the target of the link. writable
noHref boolean When true, indicates that the area is inactive and does not link to another resource. writable
shape String Specifies the shape of an active region in an image map. The coordinates of the shape writable
are specified by HTMLAreaElement.coords.
tabIndex int Specifies the element’s position in the tabbing order. writable
target String Specifies the frame in which to render the target document. writable

135
BlackBerry Browser JavaScript Reference

Object: HTMLBaseElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLBaseElement object represents a <base> element in an HTML document.

The <base> element specifies an absolute URI that acts as the base URI for resolving relative URIs.

Properties
Property name Type Description Status
href String Specifies the base URI used to resolve all relative URLs in the document. writable
target String Specifies the frame in which to render target documents by default. writable

136
 JavaScript objects

Object: HTMLBaseFontElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLBaseFontElement object represent a <basefont> element in an HTML document.

The <basefont> element specifies the base font used in the document. The <basefont> element is deprecated in
HTML 4.01.

Properties
Property name Type Description Status
color String Specifies the color of the base font. writable
face String Specifies a list of font names, listed in order of preference, in which the base font is writable
rendered.
size String Specifies the size of the base font. writable

137
BlackBerry Browser JavaScript Reference

Object: HTMLBodyElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLBodyElement object represents a <body> element in an HTML document.

The <body> element defines the page body, which contains all the renderable content.

Properties
Property name Type Description Status
aLink String Specifies the color of active links. writable
background String Specifies the URI of an image to use as the page background. writable
bgColor String Specifies the background color for the page body. writable
link String Specifies the color of unvisited links. writable
text String Specifies the color of the body text. writable
vlink String Specifies the color of visited links. writable

138
 JavaScript objects

Object: HTMLBRElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLBRElement object represents a <br> element in an HTML document.

The <br> element inserts a line break.

Properties
Property name Type Description Status
clear String Specifies the control flow of text around adjacent floats. writable

139
BlackBerry Browser JavaScript Reference

Object: HTMLButtonElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLButtonElement object represents a <button> element in an HTML document.

The <button> element defines a button form control.

Properties
Property name Type Description Status
accessKey String Specifies the keypad key that gives access to the form control. writable
disabled boolean When true, indicates that the form control is not available. writable
form HTMLFormElement Returns the parent <form> element for the form control. read only
name String Specifies the name of the form control. This is the name portion of the name-value writable
pair that is submitted with the form.
tabIndex int Specifies the tabbing order of the form control. writable
type String Returns the type of form control. The value for this property may be “button”, read only
“reset”, or “submit”.
value String Specifies the current value of the form control. This is the value portion of the name- writable
value pair that is submitted with the form.

140
 JavaScript objects

Object: HTMLCollection
Availability BlackBerry® Device Software version 4.6 and later

The HTMLCollection object is an array that contains an ordered collection of nodes. HTMLCollection objects are
automatically updated when the underlying document is changed.
You can access an individual node within a collection by its index position using HTMLCollection.item(), by its
name or id attribute using HTMLCollection.namedItem(), or you can index the object directly. For example, if you
create an instance of a HTMLCollection object called myHTMLNodes, then specifying
myHTMLNodes.item(2)
myHTMLNodes.namedItem(“item”)
is equivalent to specifying
myHTMLNodes[2]
myHTMLNodes[“item”]

Properties
Property name Type Description Status
length int Returns the number of nodes in the list. read only

Methods
Method name Description
item() Retrieves a specific node, by index, from the collection.
namedItem() Retrieves the node with the given name property value from the collection.

141
BlackBerry Browser JavaScript Reference

Method: item()
The item() method returns the node at the specified index.

Syntax
HTMLCollection.item( index )

Parameters

Parameter Type Description

index int The index position of the node to be returned. Valid values are between 0 and
HTMLCollection.length-1 inclusive.

Return values
Returns the node at the indexth position in the HTMLCollection array, or null if an invalid index position is
specified.

Exceptions
None.

142
 JavaScript objects

Method: namedItem()
The namedItem() method retrieves the node with the given name from the collection.
This method behaves differently depending on the document type:
• If the document is an HTML document, this method first searches for a node with an id attribute that matches
the given name, then searches for a node with a name attribute that matches the given name if no matching id
attribute exists.
When searching HTML documents, this method is case insensitive.
• If the document is an XHTML document, this method only searches for nodes with an id attribute that matches
the given name.
When searching XHTML documents, this method is case sensitive.

Syntax
HTMLCollection.namedItem( name )

Parameters

Parameter Type Description

name String The name of the node to retrieve.

Return values
Returns the node with an id or name attribute of name, or null if no node with the given name exists.

Exceptions
None.

143
BlackBerry Browser JavaScript Reference

Object: HTMLDirectoryElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLDirectoryElement object represents a <dir> element in an HTML document.

The <dir> element specifies that the enclosed text is a directory list.

Properties
Property name Type Description Status
compact boolean When true, indicates reduced spacing between list items. writable

144
 JavaScript objects

Object: HTMLDivElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLDivElement object represents a <div> element in an HTML document.

The <div> element is a block-level grouping element. In conjunction with the id and class attributes, the <div>
element provides a means of grouping a block of content and tailoring its appearance with styles.

Properties
Property name Type Description Status
align String Specifies how text within the <div> element is horizontally aligned. writable

145
BlackBerry Browser JavaScript Reference

Object: HTMLDListElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLDListElement object represents a <dl> element in an HTML document.

The <dl> element specifies a definition list. It can enclose one or more <dt> elements.

Properties
Property name Type Description Status
compact boolean When true, indicates reduced spacing between list items. writable

146
 JavaScript objects

Object: HTMLDocument
Availability BlackBerry® Device Software version 4.6 and later
Extends Document

The HTMLDocument object provides access to the HTML hierarchy.

Properties
Property name Type Description Status
anchors HTMLCollection Returns an index of the <a> elements contained within the document. Index positions read only
begin at 0 and continue to HTMLCollection.length-1.
applets HTMLCollection Returns an index of the <applet> elements and <object> elements containing applets read only
contained within the document. Index positions begin at 0 and continue to HTMLCol-
lection.length-1.
body HTMLElement Returns the element that contains the content of the document. In documents with writable
<body> elements, returns the <body> element. In frameset documents, returns the
outermost <frameset> element.
This property is writable. However, be aware that specifying a new value for this
property effectively removes all the renderable content of the document.
compatMode String Returns whether or not this document is rendered in strict mode. A value of read only
“CSS1Compat” indicates strict mode is enforced. A value of “BackCompat” indicates
that strict mode is not enforced.
cookie String When the BlackBerry® Browser reads this property, it returns a semicolon-separated writable
list of the name-value pairs of all visible and unexpired cookies associated with the
document or frame.
When you set a value for this property, each new value must be a single name-value
pair followed by zero or more cookie attributes. If the specified name is already
associated with a cookie, the new value and attributes replace the old value and
attributes.
If the value you specify does not adhere to correct cookie syntax, this property throws
a SYNTAX_ERR.
domain String Specifies the domain name from which the document was served. writable
forms HTMLCollection Returns an index of the <form> elements contained within the document. Index posi- read only
tions begin at 0 and continue to HTMLCollection.length-1.
images HTMLCollection Returns an index of the <img> elements contained within the document. Index posi- read only
tions begin at 0 and continue to HTMLCollection.length-1.
links HTMLCollection Returns an index of the <link> elements contained in the document. Index positions read only
begin at 0 and continue to HTMLCollection.length-1.
location Location Specifies information about the URI of the document. writable
referrer String Returns the URL of the document that linked to the active document. read only
title String Specifies the text contained within the <title> element of the active document. writable
URL String Returns the complete URL of the active document. read only

147
BlackBerry Browser JavaScript Reference

Event handlers
Property name Type Description Status
onblur EventListener Specifies the function to perform when an element loses focus by either the pointer or writable
by tabbed navigation.
onchange EventListener Specifies the function to perform when a form control loses focus after the user has writable
modified the value.
onclick EventListener Specifies the function to perform when the user clicks the trackball or trackwheel on writable
a BlackBerry device.
onfocus EventListener Specifies the function to perform when an element gains focus by either the pointer or writable
by tabbed navigation.
onkeydown EventListener Specifies the function to perform when a key is pressed down while the pointer is over writable
an element.
onkeypress EventListener Specifies the function to perform when a key is pressed and released while the pointer writable
is over an element.
onkeyup EventListener Specifies the function to perform when a key is released while the pointer is over an writable
element.
onmousedown EventListener Specifies the function to perform when the user depresses the trackwheel or trackball writable
on a BlackBerry device.
onmousemove EventListener Specifies the function to perform when the user moves the pointer while it is over an writable
element.
onmouseout EventListener Specifies the function to perform when the user moves the pointer off of an element. writable
onmouseover EventListener Specifies the function to perform when the user moves the pointer over an element. writable
onmouseup EventListener Specifies the function to perform when the user releases the trackwheel or trackball writable
on a BlackBerry device.
onreset EventListener Specifies the function to perform when the user resets a form. writable
onselect EventListener Specifies the function to perform when the user selects some text in a text field. writable
onsubmit EventListener Specifies the function to perform when the user submits a form. writable

Methods
Method name Description
close() Closes the document opened by HTMLDocument.open() and forces rendering.
getElementByName() Returns an array of all the elements in the document with the specified name.
open() Opens a document stream for writing.
write() Writes a string of text to a document stream opened by HTMLDocument.open().
writeln() Writes a string of text, followed by a new line character to a document stream opened by
HTMLDocument.open().

148
 JavaScript objects

Method: close()
The close() method closes the document opened by HTMLDocument.open() and forces rendering.

Syntax
HTMLDocument.close()

Parameters
None.

Return values
None.

Exceptions
None.

See also
HTMLDocument.open()

149
BlackBerry Browser JavaScript Reference

Method: getElementByName()
The getElementByName() method returns an array of the elements in the document with the specified name.
This method behaves differently depending on the document type:
• If the document is an HTML document, this method returns all elements with the specified name. When
searching HTML documents, this element is case-insensitive.
• If the document is an XHTML document, this method only returns form control elements with the specified
name. When searching XHTML documents, this method is case sensitive.

Syntax
HTMLDocument.getElementsByName( elementName )

Parameters

Parameter Type Description

elementName String The value of the name attribute of an element to match on.

Return values
Returns a new NodeList object containing an array of all the elements with the given name. If the document is
an XHTML document, only form control elements (<button>, <input>, <select>, <textarea>) with the given
name are returned.

Exceptions
None.

See also
Document.getElementsByTagNameNS(), Element.getElementsByTagName(),
Element.getElementsByTagNameNS()

150
 JavaScript objects

Method: open()
The open() method opens a document stream for writing.

Syntax
HTMLDocument.open()

Parameters
None.

Return values
None.

Exceptions
None.

See also
HTMLDocument.close(), HTMLDocument.write(), HTMLDocument.writeln()

151
BlackBerry Browser JavaScript Reference

Method: write()
The write() method writes a string of text to a document stream opened by HTMLDocument.open().

Syntax
HTMLDocument.write( text )

Parameters

Parameter Type Description

text String The text to be parsed.

Return values
None.

Exceptions
None.

See also
HTMLDocument.open(), HTMLDocument.writeln()

152
 JavaScript objects

Method: writeln()
The writeln() method writes a string of text, followed by a new line character to a document stream opened by
HTMLDocument.open().

Syntax
HTMLDocument.writeln( text )

Parameters

Parameter Type Description

text String The text to be parsed.

Return values
None.

Exceptions
None.

See also
HTMLDocument.open(), HTMLDocument.write()

153
BlackBerry Browser JavaScript Reference

Object: HTMLElement
Availability BlackBerry® Device Software version 4.6 and later
Extends Element
Extended by HTMLAnchorElement, HTMLAppletElement, HTMLAreaElement, HTMLBaseElement,
HTMLBaseFontElement, HTMLBodyElement, HTMLBRElement, HTMLButtonElement,
HTMLDirectoryElement, HTMLDivElement, HTMLDListElement, HTMLFieldsetElement,
HTMLFontElement, HTMLFormElement, HTMLFrameElement, HTMLFrameSetElement,
HTMLHeadElement, HTMLHeadingElement, HTMLHRElement, HTMLHtmlElement,
HTMLIFrameElement, HTMLImageElement, HTMLInputElement, HTMLIsIndexElement,
HTMLLabelElement, HTMLLegendElement, HTMLLIElement, HTMLLinkElement,
HTMLMapElement, HTMLMenuElement, HTMLMetaElement, HTMLModElement,
HTMLObjectElement, HTMLOListElement, HTMLOptGroupElement, HTMLOptionElement,
HTMLParagraphElement, HTMLParamElement, HTMLPreElement, HTMLQuoteElement,
HTMLScriptElement, HTMLSelectElement, HTMLStyleElement, HTMLTableCaptionElement,
HTMLTableCellElement, HTMLTableColElement, HTMLTableElement, HTMLTableRowElement,
HTMLTableSectionElement, HTMLTextAreaElement, HTMLTitleElement, HTMLUListElement

The HTMLElement object extends the Element class. It is the parent class of all HTML elements. This object is used
to represent those HTML elements which support only core attributes. These include the following elements:
<abbr>, <acronym>, <address>, <b>, <bdo>, <big>, <center>, <cite>, <code>, <dd>, <dfn>, <dt>, <em>, <i>, <kbd>,
<noscript>, <s>, <samp>, <small>, <span>, <strike>, <strong>, <sub>, <sup>, <th>, <tt>, <u>, <var>

Properties
Property name Type Description Status
className String Specifies the class attribute of an element. writable
dir String Specifies the dir attribute of an element. writable
id String Specifies the id attribute of an element. writable
innerHTML String Specifies the string enclosed by the text of the element. Any contained HTML tags writable
will be interpreted as part of the text string, not as HTML.
lang String Specifies the lang attribute of an element. writable
offsetHeight int Returns the height of the element, in pixels. read only
offsetLeft int Returns the number of pixels the left edge of the element is offset from the left edge read only
of the containing element.
offsetParent Node Returns the a reference to the nearest containing element that is positioned, from read only
which all offsets are determined. If the element has a style.display set to none, this
property returns null.
offsetTop int Returns the number of pixels the top edge of the element is offset from the top edge read only
of the containing element.
offsetWidth int Returns the width of the element, in pixels. read only

154
 JavaScript objects

Property name Type Description Status

style CSSStyleDeclaration Returns the contents of the style attribute that defines an inline style for an read only
element.
title String Returns the title attribute of an element. writable

Event handlers
Property name Type Description Status
onblur EventListener Specifies the function to perform when an element loses focus by either the pointer writable
or by tabbed navigation.
onchange EventListener Specifies the function to perform when a form control loses focus after the user has writable
modified the value.
onclick EventListener Specifies the function to perform when the user clicks the trackball or trackwheel writable
on a BlackBerry® device.
onfocus EventListener Specifies the function to perform when an element gains focus by either the pointer writable
or by tabbed navigation.
onkeydown EventListener Specifies the function to perform when a key is pressed down while the pointer is writable
over an element.
onkeypress EventListener Specifies the function to perform when a key is pressed and released while the writable
pointer is over an element.
onkeyup EventListener Specifies the function to perform when a key is released while the pointer is over an writable
element.
onload EventListener Specifies the function to perform when the BlackBerry® Browser finishes loading a writable
new page or a complete frameset.
onmousedown EventListener Specifies the function to perform when the user depresses the trackwheel or writable
trackball on a BlackBerry device.
onmousemove EventListener Specifies the function to perform when the user moves the pointer while it is over writable
an element.
onmouseout EventListener Specifies the function to perform when the user moves the pointer off of an element. writable
onmouseover EventListener Specifies the function to perform when the user moves the pointer over an element. writable
onmouseup EventListener Specifies the function to perform when the user releases the trackwheel or trackball writable
on a BlackBerry device.
onreset EventListener Specifies the function to perform when the user resets a form. writable
onselect EventListener Specifies the function to perform when the user selects some text in a text field. writable
onsubmit EventListener Specifies the function to perform when the user submits a form. writable
onunload EventListener Specifies the function to perform when the BlackBerry Browser removes a new page writable
or a frameset.

155
BlackBerry Browser JavaScript Reference

Object: HTMLFieldsetElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLFieldsetElement object represents a <fieldset> element in an HTML document.

The <fieldset> element allows you to group a related set of form controls and labels.

Properties
Property name Type Description Status
form HTMLFormElement Returns the parent <form> element for the form control. read only

156
 JavaScript objects

Object: HTMLFontElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLFontElement object represents a <font> element in an HTML document.

The <font> element specifies an inline font change.

Properties
Property name Type Description Status
color String Specifies the color of the font. writable
face String Specifies a list of font names, listed in order of preference, in which the font is rendered. writable
size String Specifies the size of the font. writable

157
BlackBerry Browser JavaScript Reference

Object: HTMLFormElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLFormElement object represents a <form> element in an HTML document.

The <form> element specifies a form that gathers information from the user. Users can submit a form by using the
<submit> input element. After a submission, the form collects the names and values of enclosed <select>, <input>,
and <textarea> elements and submits the query as part of the request (GET) or as post data (POST).

Properties
Property name Type Description Status
acceptCharset String Specifies a list of valid character sets for form data. writable
action String Specifies a a URI to which the form is submitted. writable
elements HTMLCollection Returns an index of the form control elements contained within the form. Index posi- read only
tions begin at 0 and continue to HTMLCollection.length-1.
enctype String Specifies the content type the form data is encoded with. writable
length int The number of form controls contained within the form. read only
method String Specifies the HTTP method used to send the data to the server. writable
name String Specifies a unique name for the form writable
target String Specifies where the target document is opened. writable

Methods
Method name Description
reset() Restores the default values to the form element.
submit() Submits the current values of the form element.

158
 JavaScript objects

Method: reset()
The reset() method restores the default values to the form element. This method is functionally equivalent to the
user clicking a Reset button.

Syntax
HTMLFormElement.reset()

Parameters
None.

Return values
None.

Exceptions
None.

159
BlackBerry Browser JavaScript Reference

Method: submit()
The submit() method submits the current values of the form element. This method is functionally equivalent to the
user clicking a Submit button.

Syntax
HTMLFormElement.submit()

Parameters
None.

Return values
None.

Exceptions
None.

160
 JavaScript objects

Object: HTMLFrameElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLFrameElement object represents a <frame> element in an HTML frameset.

The <frame> element identifies the content to be displayed in a single pane of a frameset.

Properties
Property name Type Description Status
contentDocument Document Returns a reference to the Document object that the frame contains. read only
contentWindow Window Returns a reference to the Window object that contains the frame. read only
frameBorder String Specifies whether or not a separator is displayed around the frame. writable
longDesc String Specifies a URL where the content of the frame is described. writable
marginHeight String Specifies the top and bottom margins for the frame. The value must be greater than 0. writable
marginWidth String Specifies the left and right margins of the frames. The value must be greater than 0. writable
name String Specifies a unique name for the frame. writable
noResize boolean When true, indicates that the user cannot resize the frame. writable
scrolling String Specifies the scrolling behavior. writable
src String Specifies the URL of the source content for the frame. writable

161
BlackBerry Browser JavaScript Reference

Object: HTMLFrameSetElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLFrameSetElement object represents a <frame> element in an HTML document.

The <frameset> element presents multiple documents within a single browser window, and defines the layout of
the contained frames.

Properties
Property name Type Description Status
cols String Specifies the layout of columns in the frameset. writable
rows String Specifies the layout of rows in the frameset. writable

162
 JavaScript objects

Object: HTMLHeadElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLHeadElement object represents the <head> element in an HTML document.

The <head> element contains information about the current document, such as title, keywords that might be useful
to search engines, and other data that is not considered document content.

Properties
Property name Type Description Status
profile String Specifies the URLs that contain metadata about the document. writable

163
BlackBerry Browser JavaScript Reference

Object: HTMLHeadingElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLHeadingElement object represents a heading element in an HTML document.

The <h1> to <h6> heading elements are used to provide organizational headings for the document.

Properties
Property name Type Description Status
align String Specifies the horizontal alignment of the heading text. writable

164
 JavaScript objects

Object: HTMLHRElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLHRElement object represents an <hr> element in an HTML document.

The <hr> element renders a horizontal line.

Properties
Property name Type Description Status
align String Specifies the horizontal alignment of the horizontal line on the page. writable
noShade boolean When true, indicates that no shading is applied to the horizontal line. writable
size String Specifies the height of the horizontal line. writable
width String Specifies the width of the horizontal line. writable

165
BlackBerry Browser JavaScript Reference

Object: HTMLHtmlElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLHtmlElement object represents an <html> element in an HTML document.

The <html> element is the root element of an HTML document.

Properties
Property name Type Description Status
version String Specifies version information about the document DTD. writable

166
 JavaScript objects

Object: HTMLIFrameElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLIFrameElement object represents an <iframe> element in an HTML document.

The <iframe> element defines an inline frame.

Properties
Property name Type Description Status
align String Specifies the horizontal alignment of the frame on the page. writable
contentDocument Document Returns a reference to the Document object that the frame contains. read only
content Window Window Returns a reference to the Window object that contains the frame.
frameBorder String Specifies whether or not a separator is displayed around the frame. writable
height String Specifies the height of the frame. writable
longDesc String Specifies a URL where the content of the frame is described. writable
marginHeight String Specifies the top and bottom margins for the frame. The value must be greater than 0. writable
marginWidth String Specifies the left and right margins of the frames. The value must be greater than 0. writable
name String Specifies a unique name for the frame. writable
scrolling String Specifies the scrolling behavior. writable
src String Specifies the URL of the source content for the frame. writable
width String Specifies the width of the frame. writable

167
BlackBerry Browser JavaScript Reference

Object: HTMLImageElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLImageElement object represents an <img> element in an HTML document.

The <img> element defines an image to display.

Properties
Property name Type Description Status
align String Specifies the vertical or horizontal alignment of the image on the page. writable
alt String Specifies the text that appears when an image is unavailable or cannot be displayed. writable
border String Specifies the width of a border around an image. writable
height int Specifies the width of a border around an image. writable
hspace int Specifies the amount of whitespace padding added to the left and right of the image. writable
isMap boolean When true, indicates that the image uses a server-side image map. writable
longDesc String Specifies the URI of a document that provides a long description of the image. writable
name String Specifies a unique name for the image. writable
src String Specifies the URI of the source image. writable
usemap String Specifies the client-side map to use with this image. writable
vspace int Specifies the amount of whitespace padding added to the top and bottom of the image. writable
width int Specifies the width of the image, with the unit of measurement. writable

168
 JavaScript objects

Object: HTMLInputElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLInputElement object represents an <input> element in an HTML document.

The <input> element defines a user input object.

Properties
Property name Type Description Status
accept String Specifies a comma-separated list of content types that this form accepts. writable
accessKey String Specifies the keypad key that gives access to the element. writable
align String Specifies the vertical or horizontal alignment of the image on the page. writable
alt String When HTMLInputElement.type has a value of “image”, specifies the text that writable
appears when an image is unavailable or cannot be displayed.
checked boolean When HTMLInputElement.type has a value of ”checkbox” or ”radio” and this writable
property is true, indicates that the check box or radio button appears selected, and
its value is included when the form is submitted.
defaultChecked boolean When HTMLInputElement.type has a value of ”checkbox” or ”radio” and this writable
property is true, indicates that the input control is initially selected.
The value of this property does not change if the state of the input control within the
form changes.
defaultValue String When HTMLInputElement.type has a value of ”text”, “file”, or ”password”, specifies writable
the initial value of the form control.
The value of this property does not change if the contents of the form control within
the form changes.
disabled boolean When true, indicates that the form control is not available. writable
form HTMLFormElement Returns the parent <form> element for the form control. read only
maxLength int When HTMLInputElement.type has a value of ”text” or ”password”, specifies the writable
maximum number of characters permitted as input into the text field.
name String Specifies the name of the form control. This is the name portion of the name-value writable
pair that is submitted with the form.
readonly boolean When HTMLInputElement.type has a value of ”text” or ”password” and this property writable
is true, indicates that the form control cannot be modified by a user.
size int Specifies the size of the form control. writable
src String When HTMLInputElement.type has a value of “image”, specifies the URI of the writable
source image.
tabIndex int Specifies the element’s position in the tabbing order. writable

169
BlackBerry Browser JavaScript Reference

Property name Type Description Status

type String Specifies the type of form control this input element is. This property may have the writable
following values:
• type=”button”: The element appears as a button. Use the value attribute to
specify the text of the button.
• type=“checkbox”: The element is rendered using a check box control. Check
boxes can occur anywhere in a form element.
• type=“file”: The associated file that appears is selectable and can be submitted
with a form.
• type=“hidden”: Hidden elements are not displayed, but they are included when
the form is submitted.
• type=“image”: The associated image that appears is selectable.
• type=“password”: The browser displays an asterisk (*) for each character that
the user types. The actual value is included in encoded form data when the form
is submitted.
• type=“radio”: The element is rendered using a radio control (a single selection
option list). Radio input elements can appear anywhere in a form element.
• type=“reset”: The element appears as a button. Users click the button to reset
the form values to its original values. This does not affect other forms on the
screen.
• type=“submit”: The element appears as a submit button.
• type=“text”: The element appears as a text input field.
useMap String When HTMLInputElement.type has a value of “image”, specifies the client-side map writable
to use with this image.
value String Specifies the current value of the form control. This is the value portion of the name- writable
value pair that is submitted with the form.

Methods
Method name Description
blur() Removes keypad focus from the element.
click() Simulates a mouse click.
focus() Gives keypad focus to the element.
select() Selects the contents of the element.

170
 JavaScript objects

Method: blur()
The blur() method removes keypad focus from the element.

Syntax
HTMLInputElement.blur()

Parameters
None.

Return values
None.

Exceptions
None.

171
BlackBerry Browser JavaScript Reference

Method: click()
The click() method simulates a mouse click. This method can be used when HTMLInputElement.type has a value of
“button”, “checkbox”, “radio”, “reset”, or “submit”.

Syntax
HTMLInputElement.click()

Parameters
None.

Return values
None.

Exceptions
None.

172
 JavaScript objects

Method: focus()
The focus() method gives keypad focus to the element.

Syntax
HTMLInputElement.focus()

Parameters
None.

Return values
None.

Exceptions
None.

173
BlackBerry Browser JavaScript Reference

Method: select()
The select() method selects the entire contents of the element. This method can be used when
HTMLInputElement.type has a value of “file”, “password”, or “text”.

Syntax
HTMLInputElement.select()

Parameters
None.

Return values
None.

Exceptions
None.

174
 JavaScript objects

Object: HTMLIsIndexElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLIsIndexElement object represents an <isindex> element in an HTML document.

The <isindex> element specifies that the enclosed text is single-line text input. This element is deprecated in
HTML 4.01, and is not supported by the BlackBerry® Browser.
HTMLIsIndexElement is supported in the BlackBerry Browser’s JavaScript® implementation to conform with HTML
DOM Level 2 specification. However, <isindex> elements will not be visually displayed in the browser and will not
have any impact on the document layout.

Properties
Property name Type Description Status
form HTMLFormElement Returns the parent <form> element for the form control. read only
prompt String Specifies the prompt message. writable

175
BlackBerry Browser JavaScript Reference

Object: HTMLLabelElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLLabelElement object represents a <label> element in an HTML document.

The <label> element provides a descriptive label for an <input>, <select>, and <textarea> elements in a form.

Properties
Property name Type Description Status
accessKey String Specifies the keypad key that gives access to the element. writable
form HTMLFormElement Returns the parent <form> element for the form control. read only
htmlFor String Specifies the form control with which the label is associated. The value must be the writable
value of the id attribute of the related element.

176
 JavaScript objects

Object: HTMLLegendElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLLegendElement object represents a <legend> element in an HTML document.

The <legend> element specifies a caption for a <fieldset> element.

Properties
Property name Type Description Status
accessKey String Specifies the keypad key that gives access to the element. writable
align String Specifies the horizontal or vertical alignment of the caption relative to the parent writable
<fieldset> element.
form HTMLFormElement Returns the parent <form> element for the form control. read only

177
BlackBerry Browser JavaScript Reference

Object: HTMLLIElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLLIElement object represents an <li> element in an HTML document.

The <li> element specifies a list item. These elements appear with a bullet or number, depending on the enclosing
element.

Properties
Property name Type Description Status
type String Specifies the bullet or number style for the list. writable
value int Specifies the list item number if the list item is part of an ordered list. Subsequent items writable
in that list are numbered sequentially from this value.

178
 JavaScript objects

Object: HTMLLinkElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLLinkElement object represents a <link> element in an HTML document.

The <link> element specifies an external reference to another document.

Properties
Property name Type Description Status
charset String Specifies the character encoding used in the referenced document; the value must be writable
the name of a standard character set.
disabled boolean When true, indicates that this link is disabled. writable
href String Specifies the target of the link. writable
hreflang String Specifies the base language of the target document. writable
media String Specifies the destination medium for the link. writable
rel String Specifies the relationship between the current page and the referenced document. For writable
example, “stylesheet”.
rev String Describes a link relationship from the referenced target document to the source writable
document.
sheet StyleSheet The StyleSheet object associated with the element. read only
target String Specifies where the target document will be opened. The value can be the id attribute writable
of the target frame, or can have one of the following special values:
• _blank: Default. The document in a new window.
• _self: The document opens in the same frame as the image map that was clicked.
• _parent: The document opens in the parent frameset.
• _top: The document opens in the full window.
type String Specifies the MIME type of the target document. writable

179
BlackBerry Browser JavaScript Reference

Object: HTMLMapElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLMapElement object represents a <map> element in an HTML document.

The <map> element creates a client-side image map.

Properties
Property name Type Description Status
areas HTMLCollection Returns an index of the active regions contained within the map. Index positions begin read only
at 0 and continue to HTMLCollection.length-1.
name String Specifies a unique name for the image map. The value must match the corresponding writable
value for the usemap attribute in the <img> element in which it is referenced.

180
 JavaScript objects

Object: HTMLMenuElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLMenuElement object represents a <menu> element in an HTML document.

The <menu> element denotes that the enclosed text is a menu list.

Properties
Property name Type Description Status
compact boolean When true, indicates reduced spacing between list items. writable

181
BlackBerry Browser JavaScript Reference

Object: HTMLMetaElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLMetaElement object represents a <meta> element in an HTML document.

The <meta> element provides additional information about the document.

Properties
Property name Type Description Status
content String Specifies the value of a property. writable
httpEquiv String Specifies the HTTP response header name. writable
name String Specifies the name used to identify the meta information. writable
scheme String Specifies the name of the scheme used to interpret the value of the content property. writable

182
 JavaScript objects

Object: HTMLModElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLModElement object represents a <del> or <ins> element in an HTML document.

The <del> element specifies that the enclosed text was deleted. The <ins> element specifies that the enclosed text
was inserted.

Properties
Property name Type Description Status
cite String Specifies the URI of a document that explains why the text was modified. writable
dateTime String Specifies the date and time that the enclosed text was modified. writable

183
BlackBerry Browser JavaScript Reference

Object: HTMLObjectElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLObjectElement object represents an <object> element in an HTML document.

The <object> element specifies an embedded object.

Properties
Property name Type Description Status
align String Specifies the horizontal or vertical alignment of the object. writable
archive String Specifies a whitespace-separated list of URLs for archives which contain resources writable
for the object.
border String Specifies the width of the border around the object. writable
code String Specifies the location of the class ID for the object. writable
codeBase String Specifies the root location for the object’s code and data. writable
codeType String Specifies the MIME type for the data downloaded for use by the object. writable
contentDocument Document Returns the document this object contains, if there is one. If the object contains no read only
document, this property returns null.
data String Specifies the URI that defines the location of the object’s data. writable
declare boolean When true, indicates that this object should be declared, but not instantiated. writable
form HTMLFormElement Returns the form that contains this object. If the object is not contained by a form, read only
this property returns null.
height String Specifies the height of the object. writable
hspace int Specifies the amount of white space, in pixels, inserted to the left and right of the writable
object.
name String Specifies the name for the object. writable
standby String Specifies text to display while the object is loading. writable
tabIndex int Specifies the objects position in the tabbing order. writable
type String Specifies the MIME type for the data specified by the data property. writable
useMap String Specifies the location of a client side map used with the object, if the object is an writable
image.
vspace int Specifies the amount of white space, in pixels, inserted above and below the object. writable
width String Specifies the width of the object. writable

184
 JavaScript objects

Object: HTMLOListElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLOListElement object represents an <ol> element in an HTML document.

The <ol> element specifies an ordered, or numbered, list.

Properties
Property name Type Description Status
compact boolean When true, indicates reduced spacing between list items. writable
start int Specifies the starting value for the numbering sequence. writable
type String Specifies the numbering style to use. writable

185
BlackBerry Browser JavaScript Reference

Object: HTMLOptGroupElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLOptGroupElement object represents an <optgroup> element in an HTML document.

The <optgroup> element defines a logical group in a drop-down list of elements.

Properties
Property name Type Description Status
disabled boolean When true, indicates that the option group is disabled. writable
label String Specifies a label for the option group. writable

186
 JavaScript objects

Object: HTMLOptionElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLOptionElement object represents an <option> element in an HTML document.

The <option> element encloses the text of an option in a selection list.

Properties
Property name Type Description Status
defaultSelected boolean When true, indicates that the option is selected by default. writable
disabled boolean When true, indicates that the option is not available. writable
form HTMLFormElement Returns the form that contains the option. If this element is not contained by a read only
form, this property returns null.
index int Returns the position of this option within the parent <select> element. read only
label String Specifies a label for the option. writable
selected boolean When true, indicates that the option is currently selected. writable
text String Specifies the text contained within the <option> element. writable
value String Specifies the value of the option that is sent to the server when the form is writable
submitted.

187
BlackBerry Browser JavaScript Reference

Object: HTMLOptionsCollection
Availability BlackBerry® Device Software version 4.6 and later

The HTMLOptionsCollection object contains an array of HTMLOptionElement objects.

You can access an individual option element within a collection by its index position using
HTMLOptionsCollection.item(), by its name or id attribute using HTMLOptionsCollection.namedItem(), or you can
index the object directly. For example, if you create an instance of a HTMLOptionsCollection object called
myHTMLOptions, then specifying
myHTMLOptions.item(2)
myHTMLOptions.namedItem(“item”)
is equivalent to specifying
myHTMLOptions[2]
myHTMLOptions[“item”]

Properties
Property name Type Description Status
length int Returns the number of HTMLOptionElement objects contained in the list. read only

Methods
Method name Description
item() Retrieves a specific option node, by index, from the collection.
namedItem() Retrieves the option node with the given name or id property value from the collection.

188
 JavaScript objects

Method: item()
The item() method returns the node at the specified index.

Syntax
HTMLOptionsCollection.item( index )

Parameters

Parameter Type Description

index int The index position of the node to be returned. Valid values are between 0 and
HTMLCollection.length-1 inclusive.

Return values
Returns the node at the indexth position in the HTMLCollection array, or null if an invalid index position is
specified.

Exceptions
None.

189
BlackBerry Browser JavaScript Reference

Method: namedItem()
The namedItem() method retrieves the node with the given name from the collection.
This method behaves differently depending on the document type:
• If the document is an HTML document, this method first searches for a node with an id attribute that matches
the given name, then searches for a node with a name attribute that matches the given name if no matching id
attribute exists.
When searching HTML documents, this method is case insensitive.
• If the document is an XHTML document, this method only searches for nodes with an id attribute that matches
the given name.
When searching XHTML documents, this method is case sensitive.

Syntax
HTMLOptionsCollection.namedItem( name )

Parameters

Parameter Type Description

name String The name of the node to retrieve.

Return values
Returns the node with an id or name attribute of name, or null if no node with the given name exists.

Exceptions
None.

190
 JavaScript objects

Object: HTMLParagraphElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLParagraphElement object represents a <p> element in an HTML document.

The <p> element delimits a paragraph of text. Each <p> element starts on a new line.

Properties
Property name Type Description Status
align String Specifies the horizontal alignment of the paragraph on the page. writable

191
BlackBerry Browser JavaScript Reference

Object: HTMLParamElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLParamElement object represents a <param> element in an HTML document.

The <param> element defines the run-time parameters for an object. The parameter is a name-value pair,
specified by the name and value attributes.

Properties
Property name Type Description Status
name String Specifies a unique name for the parameter. writable
type String Specifies the content type. writable
value String Specifies the value of the parameter. writable
valueType String Specifies the type of the value attribute. The value attribute can be one of the following writable
types:
• data: The specified value is passed to the object as a string.
• object: The specified value is an object declaration in the same document.
• ref: The value is a URI that specifies where the run-time values are located.

192
 JavaScript objects

Object: HTMLPreElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLPreElement object represents a <pre> element in an HTML document.

The <pre> element denotes that the all spacing and new lines in the enclosed text is preserved.

Properties
Property name Type Description Status
width int Specifies the width of the content block. writable

193
BlackBerry Browser JavaScript Reference

Object: HTMLQuoteElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLQuoteElement object represents a <blockquote> or <q> element in an HTML document.

The <blockquote> and <q> elements specify that the enclosed text is part of a quotation.

Properties
Property name Type Description Status
cite String Specifies a URL citation to indicate the source of the quotation writable

194
 JavaScript objects

Object: HTMLScriptElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLScriptElement object represents a <script> element in an HTML document.

The <script> element defines a script.

Properties
Property name Type Description Status
charset String Specifies the character encoding used in the script. writable
defer boolean When true, indicates that the script does not generate any document content and that writable
the BlackBerry® Browser can therefore defer processing the script.
event String This property is not currently defined in the DOM HTML specification. undefined
htmlFor String This property is not currently defined in the DOM HTML specification. undefined
src String Specifies the URI where an external script document is located. writable
text String Specifies the script content. writable
type String Specifies the content type of the script. writable

195
BlackBerry Browser JavaScript Reference

Object: HTMLSelectElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLSelectElement object represents a <select> element in an HTML document.

The <select> element specifies a selection list. A selection list can be a single-selection or a multiple-selection list.

Properties
Property name Type Description Status
disabled boolean When true, indicates that the form control is not available. writable
form HTMLFormElement Returns the form that contains the form control. If this element is not read only
contained by a form, this property returns null.
length int Specifies the number of <option> elements the selection list contains. writable
multiple boolean When true, indicates that more than one option may be selected from the list. writable
name String Specifies the name of the form control. This is the name portion of the name- writable
value pair that is submitted with the form.
options HTMLOptionsCollection Returns an index of the <option> elements contained within the selection list. read only
Index positions begin at 0 and continue to HTMLOptionsCollection.length-1.
selectIndex int Specifies the index position of the selected option. writable
size int Specifies the number of visible rows. writable
tabIndex int Specifies the tabbing order of the form control. writable
type String Returns the type of form control. The value returned depends on the value of read only
HTMLSelectElement.multiple:
• When HTMLSelectElement.multiple has a value of “true”, the value for this
property is “select-multiple”.
• When HTMLSelectElement.multiple has a value of “false”, the value for
this property is “select-one”.
value String Specifies the value of the currently selected option(s). This is the value portion writable
of the name-value pair that is submitted with the form.

Methods
Method name Description
add() Adds a new option to the selection list.
blur() Removes keypad focus from the element.
focus() Gives keypad focus to the element.
remove() Removes an option from the selection list.

196
 JavaScript objects

Method: add()
The add() method adds a new option to the selection list.
If the before parameter is null, this method provides the same functionality as Node.appendChild(). Otherwise,
this method functions the same as Node.insertBefore().

Syntax
HTMLSelectElement.add( element, before )

Parameters

Parameter Type Description

element HTMLElement The element to insert.
before HTMLElement The existing child element before which element is inserted.
If before is not specified or is null, element is inserted at the end of the list of children.

Return values
None.

Exceptions

Exception Description
NOT_FOUND_ERR This error is thrown if before is not a child of the <select> element.

See also
Node.appendChild(), Node.insertBefore()

197
BlackBerry Browser JavaScript Reference

Method: blur()
The blur() method removes keypad focus from the element.

Syntax
HTMLSelectElement.blur()

Parameters
None.

Return values
None.

Exceptions
None.

198
 JavaScript objects

Method: focus()
The focus() method gives keypad focus to the element.

Syntax
HTMLSelectElement.focus()

Parameters
None.

Return values
None.

Exceptions
None.

199
BlackBerry Browser JavaScript Reference

Method: remove()
The remove() method removes an option from the selection list.

Syntax
HTMLSelectElement.remove( index )

Parameters

Parameter Type Description

index int The position in the HTMLSelectElement.options index of the element to remove from the
selection list.

Return values
None.

Exceptions
None.

200
 JavaScript objects

Object: HTMLStyleElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLStyleElement object represents a <style> element in an HTML document.

The <style> element defines an internal style sheet.

Properties
Property name Type Description Status
disabled boolean When true, indicates that the style sheet is not applied to the document. writable
media String Specifies the destination medium for the style information. writable
sheet StyleSheet Returns the StyleSheet object associated with the element. read only
type String Specifies the content type of the style sheet language. writable

201
BlackBerry Browser JavaScript Reference

Object: HTMLTableCaptionElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLTableCaptionElement object represents a <caption> element in an HTML document.

The <caption> element provides a description for a table.

Properties
Property name Type Description Status
align String Specifies the horizontal alignment of the table caption. writable

202
 JavaScript objects

Object: HTMLTableCellElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLTableCellElement object represents <td> and <th> elements in an HTML document.
The <td> element specifies a cell in a table. The <th> element specifies a table heading cell.

Properties
Property name Type Description Status
abbr String Specifies an abbreviated version of the cell text. writable
align String Specifies the horizontal alignment of the cell data. writable
axis String Specifies a list of category names used to organize cell content. writable
bgColor String Specifies the background color for the table cell. writable
cellIndex int Returns the index position of the cell in the parent row’s HTMLTableRowElement.cells read only
array.
ch String Specifies the alignment character for cells in a column. writable
chOff String Specifies the distance between the alignment character and the first adjacent charac- writable
ter.
colSpan int Specifies the number of columns the table cell spans. writable
headers String Specifies for which sides of the table the border will be visible. writable
height String Specifies the height of the table cell. writable
noWrap boolean When true, indicates that text is not wrapped in the cell. writable
rowSpan int Specifies the number of rows the table cell spans. writable
scope String Specifies whether the cell provides header information for the column, column group, writable
row, or row group.
vAlign String Specifies the vertical alignment of the content within the table cell. writable
width String Specifies the width of the table cell. writable

203
BlackBerry Browser JavaScript Reference

Object: HTMLTableColElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLTableColElement object represents a <col> and <colgroup> elements in an HTML document.
The <col> element defines the attributes for one or more columns in a table. The <colgroup> element defines
groups of table columns.These elements are not supported by the BlackBerry® Browser.
HTMLColElement is supported in the BlackBerry Browser’s JavaScript® implementation to conform with HTML
DOM Level 2 specification. However, <col> and <colgroup> elements will not be visually displayed in the browser
and will not have any impact on the document layout.

Properties
Property name Type Description Status
align String Specifies the horizontal alignment of the cell data. writable
ch String Specifies the alignment character for cells in a column. writable
chOff String Specifies the distance between the alignment character and the first adja- writable
cent character.
span int Specifies the number of columns included in a column group. writable
vAlign String Specifies the vertical alignment of the content within the table cell. writable
width String Specifies the width of the table cell. writable

204
 JavaScript objects

Object: HTMLTableElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLTableElement object represents a <table> element. You can use the methods to add or remove rows from
a table.
The <table> element specifies the start of a table.

Properties
Property name Type Description Status
align String Specifies the horizontal alignment of the table. writable
bgColor String Specifies the background color for the table. writable
border String Specifies the thickness of the border around the table cells. writable
caption HTMLTableCaptionElement Specifies a pointer to the <caption> element for the table. writable
When setting a value for this property, if you specify an element that is not
a <caption> element, this property throws a HIERARCHY_REQUEST_ERR.
cellPadding String Specifies the amount of white space, in pixels, to add between cell content writable
and its borders.
cellSpacing String Specifies the amount of white space, in pixels, to add between cells. writable
frame String Specifies for which sides of the table the border will be visible. writable
rows HTMLCollection Returns an index of the rows contained within the table, starting at 0. read only
rules String Specifies the location of rules in the table. writable
summary String Specifies summary text that describes the contents of the table. writable
tBodies HTMLCollection Returns an index of all the <tbody> element in the table. read only
tFoot HTMLTableSectionElement Specifies a pointer to the <tfoot> element for the table. writable
When setting a value for this property, if you specify an element that is not
a <tfoot> element, this property throws a HIERARCHY_REQUEST_ERR.
tHead HTMLTableSectionElement Specifies a pointer to the <thead> element for the table. writable
When setting a value for this property, if you specify an element that is not
a <thead> element, this property throws a HIERARCHY_REQUEST_ERR.
width String Specifies the width of the table, in pixels, or as a percentage of the Black- writable
Berry® Browser window.

Methods
Method name Description
createCaption() Creates a new table caption, if the table does not already contain one.
createTFoot() Creates a new table footer, it the table does not already contain one.

205
BlackBerry Browser JavaScript Reference

Method name Description

createTHead() Creates a new table header, if the table does not already contain one.
deleteCaption() Removes the caption from the table, if one exists.
deleteRow() Removes the row at the given index position from the table.
deleteTFoot() Removes the footer from the table, if one exists.
deleteTHead() Removes the header from the table, if one exists.
insertRow() Inserts a new empty row into the table at the given index position.

206
 JavaScript objects

Method: createCaption()
The createCaption() method creates a new table caption, if the table does not already contain one. If a table
caption already exists, this method returns it.

Syntax
HTMLTableElement.createCaption()

Parameters
None.

Return values
Returns the new table caption, or the existing table caption, if the table already contains one.

Exceptions
None.

207
BlackBerry Browser JavaScript Reference

Method: createTFoot()
The createTFoot() method creates a new table footer, it the table does not already contain one. If a table footer
already exists, this method returns it.

Syntax
HTMLTableElement.createTFoot()

Parameters
None.

Return values
Returns the new table footer, or the existing table footer, if the table already contains one.

Exceptions
None.

208
 JavaScript objects

Method: createTHead()
The createTHead() method creates a new table header, if the table does not already contain one. If a table header
already exists, this method returns it.

Syntax
HTMLTableElement.createTHead()

Parameters
None.

Return values
Returns the new table header, or the existing table header, if the table already contains one.

Exceptions
None.

209
BlackBerry Browser JavaScript Reference

Method: deleteCaption()
The deleteCaption() method removes the caption from the table, if one exists.

Syntax
HTMLTableElement.deleteCaption()

Parameters
None.

Return values
None.

Exceptions
None.

210
 JavaScript objects

Method: deleteRow()
The deleteRow() method removes the row at the given index position from the table.

Syntax
HTMLTableElement.deleteRow( index )

Parameters

Parameter Type Description

index int The index position of the row to remove from the table.
If index has a value of -1, or is equal to the number of rows in the table, the last row in
the table is removed.

Return values
None.

Exceptions

Exception Description
INDEX_SIZE_ERR This error is thrown if index exceeds the number of rows in the table, or has a negative
value other than -1.

211
BlackBerry Browser JavaScript Reference

Method: deleteTFoot()
The deleteTFoot() method removes the footer from the table, if one exists.

Syntax
HTMLTableElement.deleteTFoot()

Parameters
None.

Return values
None.

Exceptions
None.

212
 JavaScript objects

Method: deleteTHead()
The deleteTHead() method removes the header from the table, if one exists.

Syntax
HTMLTableELement.deleteTHead()

Parameters
None.

Return values
None.

Exceptions
None.

213
BlackBerry Browser JavaScript Reference

Method: insertRow()
The insertRow() method inserts a new empty row into the table at the given index position.
Once the new row is added, you can populate it with table cells using HTMLTableRowElement.insertCell().

Syntax
HTMLTableElement.insertRow( index )

Parameters

Parameter Type Description

index int The index position at which to insert the new row in the table.
If index has a value of -1, or is equal to the number of rows in the table, the new row is
added to the end of the table.

Return values
Returns the newly added row.

Exceptions

Exception Description
INDEX_SIZE_ERR This error is thrown if index exceeds the number of rows in the table, or has a negative
value other than -1.

See Also
HTMLTableRowElement.insertCell()

214
 JavaScript objects

Object: HTMLTableRowElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLTableRowElement object represents a <tr> element in an HTML document.

The <tr> element specifies a table row.

Properties
Property name Type Description Status
align String Specifies the horizontal alignment of the cell data. writable
bgColor String Specifies the background color for the table cell. writable
cells HTMLCollection Returns an index of the table cells contained within the table row, starting at 0. read only
ch String Specifies the alignment character for cells in a column. writable
chOff String Specifies the distance the distance between the alignment character and the first ad- writable
jacent character.
rowIndex int Returns the index position of the row in the parent table’s HTMLTableElement.rows ar- read only
ray.
sectionRowIndex int Returns the index position of the row in the parent table section’s HTMLTableSection- read only
Element.rows array.
vAlign String Specifies the vertical alignment of the content within the table cell. writable

Methods
Method name Description
deleteCell() Removes the table cell at the given index position.
insertCell() Inserts a new empty table cell into the row at the given index position.

215
BlackBerry Browser JavaScript Reference

Method: deleteCell()
The deleteCell() method removes the cell at the given index position in the row.

Syntax
HTMLTableRowElement.deleteCell( index )

Parameters

Parameter Type Description

index int The index position of the row to remove from the table.
If index has a value of -1, or is equal to the number of table cells in the row, the last table
cell in the row is removed.

Return values
None.

Exceptions

Exception Description
INDEX_SIZE_ERR This error is thrown if index exceeds the number of table cells in the row, or has a
negative value other than -1.

216
 JavaScript objects

Method: insertCell()
The insertCell() method inserts a new empty table cell into the row at the given index position.

Syntax
HTMLTableRowElement.insertCell( index )

Parameters

Parameter Type Description

index int The index position at which to insert the new cell in the row.
If index has a value of -1, or is equal to the number of table cells in the row, the new row
is added to the end of the table.

Return values
Returns the newly added table cell.

Exceptions

Exception Description
INDEX_SIZE_ERR This error is thrown if index exceeds the number of table cells in the row, or has a
negative value other than -1.

217
BlackBerry Browser JavaScript Reference

Object: HTMLTableSectionElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLTableSectionElement object represents a <tbody>, <tfoot>, or <thead> element in an HTML document.
The <tbody> element specifies a table body section. The <tfoot> and <thead> elements specify the table footer and
table header, respectively.

Properties
Property name Type Description Status
align String Specifies the horizontal alignment of the cell data. writable
ch String Specifies the alignment character for cells in a column. writable
chOff String Specifies the distance the distance between the alignment character and the first ad- writable
jacent character.
rows HTMLCollection Returns an index of the rows contained within the table section, starting at 0. read only
vAlign String Specifies the vertical alignment of the content within the table cell. writable

Methods
Method name Description
deleteRow() Removes the row at the given index position from the table section.
insertRow() Inserts a new empty row into the table section at the given index position.

218
 JavaScript objects

Method: deleteRow()
The deleteRow() method removes the row at the given index position from the table section.

Syntax
HTMLTableSectionElement.deleteRow( index )

Parameters

Parameter Type Description

index int The index position of the row to remove from the table section.
If index has a value of -1, or is equal to the number of rows in the table section, the last
row in the section is removed.

Return values
None.

Exceptions

Exception Description
INDEX_SIZE_ERR This error is thrown if index exceeds the number of rows in the table section, or has a
negative value other than -1.

219
BlackBerry Browser JavaScript Reference

Method: insertRow()
The insertRow() method inserts a new empty row into the table section at the given index position.
Once the new row is added, you can populate it with table cells using HTMLTableRowElement.insertCell().

Syntax
HTMLTableSectionElement.insertRow( index )

Parameters

Parameter Type Description

index int The index position at which to insert the new row in the table section.
If index has a value of -1, or is equal to the number of rows in the table section, the new
row is added to the end of the section.

Return values
Returns the newly added row.

Exceptions

Exception Description
INDEX_SIZE_ERR This error is thrown if index exceeds the number of rows in the table section, or has a
negative value other than -1.

See Also
HTMLTableRowElement.insertCell()

220
 JavaScript objects

Object: HTMLTextAreaElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLTextAreaElement object provides access to <textarea> elements within an HTML document.
The <textarea> element specifies a multiline text entry field in a form. It can optionally contain plain text, which is
displayed to the user in the text area.

Properties
Property name Type Description Status
accessKey String Specifies the keypad key that gives access to the form control. writable
cols int Specifies the width of the text area control, in characters. writable
defaultValue String Specifies the initial contents of the text area. The value of this property does not writable
change if the contents of the text area control within the form changes.
disabled boolean When true, indicates that the text area control is not available. writable
form HTMLFormElement Returns the parent <form> element for the form control. read only
name String Specifies the name of the form control. This is the name portion of the name-value writable
pair that is submitted with the form.
readonly boolean When true, indicates that the form control cannot be modified by a user. writable
rows int Specifies the height of the form control, in text rows. writable
tabIndex int Specifies the tabbing order of the form control. writable
type String Returns the type of form control. The value for this property is “textarea”. read only
value String Specifies the current contents of the form control. This is the value portion of the writable
name-value pair that is submitted with the form.

Methods
Method name Description
blur() Removes keypad focus from the element.
focus() Gives keypad focus to the element.
select() Selects the entire contents of the element.

221
BlackBerry Browser JavaScript Reference

Method: blur()
The blur() method removes keypad focus from the element.

Syntax
HTMLTextAreaElement.blur()

Parameters
None.

Return values
None.

Exceptions
None.

222
 JavaScript objects

Method: focus()
The focus() method gives keypad focus to the element.

Syntax
HTMLTextAreaElement.focus()

Parameters
None.

Return values
None.

Exceptions
None.

223
BlackBerry Browser JavaScript Reference

Method: select()
The select() method selects the entire contents of the element.

Syntax
HTMLTextAreaElement.select()

Parameters
None.

Return values
None.

Exceptions
None.

224
 JavaScript objects

Object: HTMLTitleElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLTitleElement object provides access to <title> elements within an HTML document.
The <title> element provides a descriptive title for the document.

Properties
Property name Type Description Status
text String Specifies the title of the HTML document. writable

225
BlackBerry Browser JavaScript Reference

Object: HTMLUListElement
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement

The HTMLUListElement object provides access to <ul> elements within an HTML document.
The <ul> element specifies an unordered, or bulleted, list.

Properties
Property name Type Description Status
compact boolean When true, indicates reduced spacing between list items. writable
type String Specifies the bullet style used in the list. writable

226
 JavaScript objects

Object: KeyboardEvent
Availability BlackBerry® Device Software version 4.6 and later
Extends UIEvent

The KeyboardEvent object extends the UIEvent object and represents an event generated by the BlackBerry®
device keypad. 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:
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

Properties
Property name Type Description Status
altKey boolean Returns “true” if the ALT key is pressed or if the ALT key is locked. read only
ctrlKey boolean Returns “false”. BlackBerry devices have no CTRL key. read only
keyCode int Returns the key code associated with the key in this event. read only
keyIdentifier String Returns the identifier of the key. read only
keyLocation int Returns a value of DOM_KEY_LOCATION_STANDARD. read only
metaKey boolean Returns “false”. BlackBerry devices have no Meta key. read only
shiftKey boolean Returns “true” if the SHIFT key is pressed. read only

227
BlackBerry Browser JavaScript Reference

Methods
Method name
getModifierState()
initKeyboardEvent()
initKeyboardEventNS()
Description
Checks the state of a modifier key.
Initializes the value of a KeyboardEvent.
Initializes the value of a KeyboardEvent with the given namespace URI.

228
 JavaScript objects

Method: getModifierState()
The getModifierState() method checks the state of a modifier key.

Syntax
KeyboardEvent.getModifierState( keyIdentifierArg )

Parameters

Parameter Type Description

keyIdentifierArg String Specifies a modifier key identifier, such as ALT.

Return values
Returns “true” if the modifier key specified by keyIdentifierArg is activated; otherwise, returns false.

Exceptions
None.

229
BlackBerry Browser JavaScript Reference

Method: initKeyboardEvent()
The initKeyboardEvent() method initializes the value of a KeyboardEvent created by Document.createEvent(). This
method can only be called before the KeyboardEvent has been dispatched.

Syntax
KeyboardEvent.initKeyboardEvent( typeArg, canBubbleArg, cancelableArg, viewArg,
keyIdentifierArg, keyLocationArg, modifiersList )

Parameters

Parameter Type Description

typeArg String Specifies the keyboard event type. This parameter may have one of the following values:
• keydown
• keypress
• keyup
canBubbleArg boolean When true, this parameter indicates that the event can bubble upwards through the
DOM tree. This parameter sets the value of Event.bubbles.
cancelableArg boolean When true, this parameter indicates that the event’s default action can be cancelled.
This parameter sets the value of Event.cancelable.
viewArg AbstractView Specifies the window or frame that is generating the event. This parameter sets the
value of UIEvent.view.
keyIdentiferArg String Specifies the identifier of the key. This parameter sets the value of
KeyboardEvent.keyIdentifier.
keyLocationArg String Specifies the location of the key on the device that started the key event. This parameter
must have a value of DOM_KEY_LOCATION_STANDARD.
This parameter sets the value of KeyboardEvent.keyLocation.
modifiersList String Specifies a whitespace-separated list of modifier key identifiers to be activated on the
object.

Return values
None.

Exceptions
None.

See also
KeyboardEvent.initKeyboardEventNS()

230
 JavaScript objects

Method: initKeyboardEventNS()
The initKeyboardEventNS() method initializes the value of a KeyboardEvent created by Document.createEvent()
with the given namespace URI. This method can only be called before the KeyboardEvent has been dispatched.

Syntax
KeyboardEvent.initKeyboardEventNS( namespaceURI, typeArg, canBubbleArg, cancelableArg,
viewArg, keyIdentifierArg, keyLocationArg,
modifiersList )

Parameters

Parameter Type Description

namespaceURI String Specifies the namespace URI associated with this event, or null if no namespace exists.
typeArg String Specifies the keyboard event type. This parameter may have one of the following values:
• keydown
• keypress
• keyup
canBubbleArg boolean When true, this parameter indicates that the event can bubble upwards through the
DOM tree. This parameter sets the value of Event.bubbles.
cancelableArg boolean When true, this parameter indicates that the event’s default action can be cancelled.
This parameter sets the value of Event.cancelable.
viewArg AbstractView Specifies the window or frame that is generating the event. This parameter sets the
value of UIEvent.view.
keyIdentiferArg String Specifies the identifier of the key. This parameter sets the value of
KeyboardEvent.keyIdentifier.
keyLocationArg String Specifies the location of the key on the device that started the key event. This parameter
sets the value of KeyboardEvent.keyLocation.
modifiersList String Specifies a whitespace-separated list of modifier key identifiers to be activated on the
object.

Return values
None.

Exceptions
None.

See also
KeyboardEvent.initKeyboardEvent()

231
BlackBerry Browser JavaScript Reference

Object: Location
Availability BlackBerry® Device Software version 4.6 and later

The Location object is a property of the Window object. This object accesses the URL of the web page being
displayed in the BlackBerry® Browser.
A URL is composed of some or all of the following components:
protocol://hostname:port/path?query#fragment.

Properties
Property name Type Description Status
hash String Specifies the anchor portion of the URL, including the leading hash mark, if one exists. writable
host String Specifies the URL hostname and port. writable
hostname String Specifies the hostname portion of the URL. writable
href String Specifies the entire URL. writable
pathname String Specifies the pathname portion of the URL. writable
port String Specifies the port portion of the URL. writable
protocol String Specifies the protocol portion of the URL. writable
search String Specifies the URL query string portion of the URL, including the question mark. writable

Methods
Method name Description
assign() Loads a new document.
replace() Replaces the current web page with the web page at the given URL.
reload() Reloads the current web page.
toString() Returns the URL of the Location object’s URL.

232
 JavaScript objects

Method: assign()
The assign() method loads a new document. Unlike Location.replace(), when the given URL is loaded, the old URL
is still available in the BlackBerry® Browser History list.

Syntax
location.assign( URL )

Parameters

Parameter Type Description

URL String The URL to load.

Return values
None.

Exceptions
None.

See also
Location.replace()

233
BlackBerry Browser JavaScript Reference

Method: reload()
The reload() method reloads the current web page.

Syntax
location.reload( forceGet )

Parameters

Parameter Type Description

forceGet boolean When true, indicates that the page will always be reloaded from the server. When false,
or unspecified, the page can be reloaded from the BlackBerry® Browser cache, if it is
available and still valid.

Return values
None.

Exceptions
None.

See also
Location.assign()

234
 JavaScript objects

Method: replace()
The replace() method replaces the current web page with the web page at the given URL. This method differs from
Location.assign() in that when the old URL is replaced, it is not saved in the History list. As a result, the user will
have no way to navigate back to it.

Syntax
location.replace( URL )

Parameters

Parameter Type Description

URL String The URL to replace the current URL with.

Return values
None.

Exceptions
None.

See also
Location.assign()

235
BlackBerry Browser JavaScript Reference

Method: toString()
The toString() method returns the URL of the web page as a string.

Syntax
location.toString()

Parameters
None.

Return values
Returns the current URL (the value of Location.href) as a string value.

Exceptions
None.

236
 JavaScript objects

Object: MediaList
Availability BlackBerry® Device Software version 4.6 and later

The MediaList object represents an ordered collection of media. An empty list is equivalent to a list that contains a
value of “all”.

Properties
Property name Type Description Status
length int Returns the number of media in the list. read only
mediaText String Specifies a comma-separated list of media. writable
When setting a value for this property, the following errors may be thrown:
• SYNTAX_ERR: Thrown if the string value is unparsable.
• NO_MODIFICATION_ERR: Thrown if the MediaList object is read only.

Methods
Method name Description
appendMedium() Adds the given medium to the end of the MediaList object.
deleteMedium() Removes the given medium from the MediaList object.
item() Returns the medium at the given index in the collection.

237
BlackBerry Browser JavaScript Reference

Method: appendMedium()
The appendMedium() method adds the given medium to the end of the MediaList object.

Syntax
MediaList.appendMedium( newMedium )

Parameters

Parameter Type Description

newMedium String The medium to append to the end of MediaList. If newMedium already exists in the list,
it is first removed and then replaced.

Return values
None.

Exceptions

Exception Description
NO_MODIFICATION_ALLOWED_ERR This error is thrown if the MediaList object is read only.
INVALID_CHARACTER_ERR This error is thrown if newMedium contains characters that are invalid in the style
language.

See also
MediaList.deleteMedium()

238
 JavaScript objects

Method: deleteMedium()
The deleteMedium() method removes the given medium from the MediaList object.

Syntax
MediaList.deleteMedium( oldMedium )

Parameters

Parameter Type Description

oldMedium String The medium to remove from MediaList.

Return values
None.

Exceptions

Exception Description
NO_MODIFICATION_ALLOWED_ERR This error is thrown if the MediaList object is read only.
NOT_FOUND_ERR This error is thrown if no medium matching oldMedium exists in the collection.

See also
MediaList.appendMedium()

239
BlackBerry Browser JavaScript Reference

Method: item()
The item() method returns the medium at the given index in the collection.

Syntax
MediaList.item( index )

Parameters

Parameter Type Description

index int An integer that represents the item’s position in MediaList object. Valid values are
between 0 and MediaList.length-1 inclusive.

Return values
Returns the medium at the indexth position in MediaList, or null if an invalid index position is specified.

Exceptions
None.

240
 JavaScript objects

Object: MimeType
Availability BlackBerry® Device Software version 4.6 and later

The MimeType object belongs to the Navigator object. It allows you to determine whether the browser can handle
specific MIME types before loading the content from the server. This object represents a MIME type specification.

Properties
Property name Type Description Status
description String Returns a description of the MIME type. read only
enabledPlugin Plugin Returns a reference to the Plugin object currently set to display any incoming data read only
formatted according to the MIME type.
suffixes String Returns a list of possible file extensions associated with the MIME type. read only
type String Returns the name of the MIME type. read only

241
BlackBerry Browser JavaScript Reference

Object: MimeTypeArray
Availability BlackBerry® Device Software version 4.6 and later

The MimeTypeArray object contains an ordered collection of MIME types.

Properties
Property name Type Description Status
length int Returns the number of MIME types in the list. read only

Methods
Method name Description
item() Retrieves a specific node, by index, from the collection.
namedItem() Retrieves the node with the given name property value from the collection.

242
 JavaScript objects

Method: item()
The item() method returns the MIME type at the specified index in the collection.

Syntax
MimeTypeArray.item( index )

Parameters

Parameter Type Description

index int The index position of the MIME type to be returned. Valid values are between 0 and
MimeTypeArray.length-1 inclusive.

Return values
Returns the node at the indexth position in MimeTypeArray, or null if an invalid index position is specified.

Exceptions
None.

243
BlackBerry Browser JavaScript Reference

Method: namedItem()
The namedItem() method retrieves the MIME type with the given name from the collection.

Syntax
MimeTypeArray.namedItem( name )

Parameters

Parameter Type Description

name String The name of the MIME type to retrieve.

Return values
Returns the MIME type with the given name, or null if no MIME type with the given name exists in the array.

Exceptions
None.

244
 JavaScript objects

Object: MouseEvent
Availability BlackBerry® Device Software version 4.6 and 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”.

Mouse event types

Event type Bubbles Cancelable Description
click yes yes Occurs when the user clicks the trackball or trackwheel 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
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

245
BlackBerry Browser JavaScript Reference

Event type Bubbles Cancelable Description

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

Properties
Property name Type Description Status
altKey boolean Returns “true” if the ALT key is pressed or ALT lock is on. read only
button short Returns a value indicating which mouse button changed state. Because BlackBerry read only
devices have a single button (the trackball or trackwheel), this parameter will always
return a value of “0”.
clientX int Returns the horizontal coordinate within the BlackBerry Browser window where the read only
event occurred.
clientY int Returns the vertical coordinate within the BlackBerry Browser window where the event read only
occurred.
ctrlKey boolean Returns “false”. The BlackBerry device does not have a CTRL key. read only
metaKey boolean Returns “false”. The BlackBerry device does not have a Meta key. read only
relatedTarget EventTarget Returns the EventTarget that the pointer is moving over or moving off of. read only
screenX int Returns the horizontal coordinate on the BlackBerry device screen where the event read only
occurred.
screenY int Returns the vertical coordinate on the BlackBerry device screen where the event read only
occurred.
shiftKey boolean Returns “true” if the SHIFT key is pressed. read only

Methods
Method name Description
initMouseEvent() Initializes the value of a MouseEvent.

246
 JavaScript objects

Method: initMouseEvent()
The initMouseEvent() method initializes the value of a MouseEvent created by Document.createEvent(). This
method can only be called before the MouseEvent has been dispatched.

Syntax
MouseEvent.initMouseEvent( typeArg, canBubbleArg, cancelableArg, viewArg, detailArg,
screenXArg, screenYArg, clientXArg, clientYArg, ctrlKeyArg,
AltKeyArg, shiftKeyArg, metaKeyArg, buttonArg,
relatedTargetArg )

Parameters

Parameter Type Description

typeArge String Specifies the Mouse event type. This parameter may have one of the following values:
• click
• mousedown
• mousemove
• mouseout
• mouseover
• mouseup
canBubbleArg boolean When true, this parameter indicates that the event can bubble upwards through the
DOM tree. This parameter sets the value of Event.bubbles.
cancelableArg boolean When true, this parameter indicates that the event’s default action can be cancelled.
This parameter sets the value of Event.cancelable.
viewArg AbstractView Specifies the window or frame that is generating the event. This parameter sets the
value of UIEvent.view.
detailArg long Specifies the number of clicks associated with the event. This parameter sets the value
of UIEvent.detail.
screenXArg long Specifies the horizontal coordinate on the BlackBerry® device screen where the event
occurred.
screenYArg long Specifies the vertical coordinate on the BlackBerry device screen where the event
occurred.
clientXArg long Specifies the horizontal coordinate within the BlackBerry® Browser window where the
event occurred.
clientYArg long Specifies the vertical coordinate within the BlackBerry Browser window where the event
occurred.
ctrlKeyArg boolean Specifies whether the CTRL key was pressed during the event.
altKeyArg boolean Specifies whether the ALT key was pressed during the event.
shiftKeyArg boolean Specifies whether the SHIFT key was pressed during the event.
metaKeyArg boolean Specifies whether the meta key was pressed during the event.
buttonArg unsigned short Specifies which button was clicked.
relatedTargetArg EventTarget Specifies the event’s related EventTarget. A value for this parameter is only necessary if
typeArg has a value of “mouseover” or “mouseout”. Otherwise, this parameter should
have a value of null.

247
BlackBerry Browser JavaScript Reference

Return values
None.

Exceptions
None.

248
 JavaScript objects

Object: MutationEvent
Availability BlackBerry® Device Software version 4.6 and later
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”.

Mutation event types

Event type
DOMAttrModified
DOMCharacterDataModified
DOMContentLoaded
DOMNodeInserted
DOMNodeInsertedIntoDocument
DOMNodeRemoved
DOMNodeRemovedFromDocument yes
DOMSubtreeModified
Bubbles Cancelable Description
yes no 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
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
no no Occurs when the BlackBerry® Browser has completely parsed the
document, before any onload events are triggered.
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 holds the parent node of the parent node of
the node being added.
yes no Occurs when a node has been inserted into the document, either directly
or as part of a subtree.
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 holds the parent node of the parent node of
the node being removed.
no Occurs when a node has been removed from the document, either directly
or as part of a subtree.
yes no Occurs when any modification has been made to the document,
encompassing all other Mutation event types.

249
BlackBerry Browser JavaScript Reference

Properties
Property name Type Description Status
attrChange unsigned short Returns the type of change that triggered the DOMAttrModified event. This property read only
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.
attrName String Returns the name of the changed Attr node in a DOMAttrModified event. read only
newValue String Returns the new value of: read only
• the Attr node in a DOMAttrModified event
• the CharacterData node in a DOMCharacterDataModified event
prevValue String Returns the previous value of: read only
• the Attr node in a DOMAttrModified event
• the CharacterData node in a DOMCharacterDataModified event
relatedNode Node Returns the secondary node affected by a mutation event. read only

Methods
Method name Description
initMutationEvent() Initializes the value of a MutationEvent.

250
 JavaScript objects

Method: initMutationEvent()
The initMutationEvent() method initializes the value of a MutationEvent created by Document.createEvent(). This
method can only be called before the MutationEvent has been dispatched.

Syntax
MutationEvent.initMutationEvent( typeArg, canBubbleArg, cancelableArg, relatedNodeArg,
prevValueArg, newValueArg, attrNameArg, attrChangeArg )

Parameters

Parameter Type Description

typeArg String Specifies the mutation event type. This parameter may have one of the following values:
• DOMAttrModified
• DOMCharacterDataModified
• DOMContentLoaded
• DOMNodeInserted
• DOMNodeInsertedIntoDocument
• DOMNodeRemoved
• DOMNodeRemovedFromDocument
• DOMSubtreeModified
canBubbleArg boolean When true, this parameter indicates that the event can bubble upwards through the
DOM tree. This parameter sets the value of Event.bubbles.
cancelableArg boolean When true, this parameter indicates that the event’s default action can be cancelled.
This parameter sets the value of Event.cancelable.
relatedNodeArg Node Specifies the secondary node impacted by the mutation event. This parameter sets the
value of MutationEvent.relatedNode.
prevValueArg String Specifies the previous value of a changed Attr or CharacterData node. This parameter
sets the value of MutationEvent.prevValue.
If typeArg is not “DOMAttrModified” or “DOMCharacterDataModified”, this parameter
may be null.
newValueArg String Specifies the previous value of a changed Attr or CharacterData node. This parameter
sets the value of MutationEvent.newValue.
attrNameArg String Specifies the name of a changed Attr node. This parameter sets the value of
MutationEvent.attrName.
attrChangeArg short Specifies the type of change. This parameter can have 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.
This parameter sets the value of MutationEvent.attrChange.

Return values
None.

Exceptions
None.

251
BlackBerry Browser JavaScript Reference

Object: NamedFrameMap
Availability BlackBerry® Device Software version 4.6 and later

The NamedFrameMap object represents collections of frames that can be accessed by name.
You can access an individual frame within a collection by its index position using NamedFrameMap.item(), by its
name or id attribute using NamedFrameMap.getNamedItem(), or you can index the object directly. For example, if
you create an instance of a NamedFrameMap object called myNamedFrameMap, then specifying
myNamedFrameMap.item(2)
myNamedFrameMap.namedItem(“item”)
is equivalent to specifying
myNamedFrameMap[2]
myNamedFrameMap[“item”]

Properties
Property name Type Description Status
length unsigned long Returns the number of nodes in the map. read only

Methods
Method name Description
getNamedItem() Retrieves the frame with the given name.
item() Returns the frame at the given index in the map.

252
 JavaScript objects

Method: getNamedItem()
The getNamedItem() method retrieves the frame with the given name.

Syntax
NamedFrameMap.getNamedItem( name )

Parameters

Parameter Type Description

name String The value of the Node.nodeName property of the frame to retrieve.

Return values
Returns the frame with a Node.nodeName value of name, or null if the given parameter does not identify any
existing frame in the map.

Exceptions
None.

253
BlackBerry Browser JavaScript Reference

Method: item()
The item() method returns the frame at the specified index in the map.

Syntax
NamedFrameMap.item( index )

Parameters

Parameter Type Description

index int An integer that represents the frame’s position in the frame map. Valid values are
between 0 and NamedFrameMap.length-1 inclusive.

Return values
Returns the frame at the indexth position in NamedFrameMap, or null if an invalid index position is specified.

Exceptions
None.

254
 JavaScript objects

Object: NamedNodeMap
Availability BlackBerry® Device Software version 4.6 and later

The NamedNodeMap object represents collections of nodes that can be accessed by name.
You can access an individual node within a collection by its index position using NamedNodeMap.item(), by its
name or id attribute using NamedNodeMap.getNamedItem(), or you can index the object directly. For example, if
you create an instance of a NamedNodeMap object called myNamedNodeMap, then specifying
myNamedNodeMap.item(2)
myNamedNodeMap.namedItem(“item”)
is equivalent to specifying
myNamedNodeMap[2]
myNamedNodeMap[“item”]

Properties
Property name Type Description Status
length unsigned long Returns the number of nodes in the map. read only

Methods
Method name Description
getNamedItem() Retrieves the node with the given name.
getNamedItemNS() Retrieves the node with the given name and namespace URI.
item() Returns the node at the given index in the map.
removeNamedItem() Removes the node with the given name from the map.
removeNamedItemNS() Removes the node with the given name and namespace URI from the map.
setNamedItem() Adds a node using the Node.nodeName attribute.
setNamedItemNS() Adds a node using the Node.nodeName attribute and the namespace URI.

255
BlackBerry Browser JavaScript Reference

Method: getNamedItem()
The getNamedItem() method retrieves the node with the given name.

Syntax
NamedNodeMap.getNamedItem( name )

Parameters

Parameter Type Description

name String The value of the Node.nodeName property of the node to retrieve.

Return values
Returns the node with a Node.nodeName value of name, or null if the given parameter does not identify any
existing node in the map.

Exceptions
None.

See also
NamedNodeMap.getNamedItemNS()

256
 JavaScript objects

Method: getNamedItemNS()
The getNamedItemNS() method retrieves the node with the specified name and namespace URI.

Syntax
NamedNodeMap.getNamedItemNS( namespaceURI, localName )

Parameters

Parameter Type Description

namespaceURI String The namespace of the node to retrieve.
localName String The local name of the node to retrieve.

Return values
Returns the node with the given local name and namespace URI, or null if the given parameters do not
identify any existing node in the map.

Exceptions

Exception Description
NOT_SUPPORTED_ERR This error is thrown if the document does not support XML namespaces.

See also
NamedNodeMap.getNamedItem()

257
BlackBerry Browser JavaScript Reference

Method: item()
The item() method returns the node at the specified index in the map.

Syntax
nodeMap.item( index )

Parameters

Parameter Type Description

index int An integer that represents the node’s position in the node map. Valid values are
between 0 and NamedNodeMap.length-1 inclusive.

Return values
Returns the node at the indexth position in NamedNodeMap, or null if an invalid index position is specified.

Exceptions
None.

258
 JavaScript objects

Method: removeNamedItem()
The removeNamedItem() method removes the node with the specified name from the map.
If you are removing an attribute node from the NamedNodeMap object that is known to have a default value, the
attribute will immediately be reattached to the element with its default value, as well as its corresponding
namespace URI, local name, and prefix, if applicable.

Syntax
NamedNodeMap.removeNamedItem( name )

Parameters

Parameter Type Description

name String The value of Node.nodeName property of the node to remove.

Return values
Returns the removed Node object, if it exists.

Exceptions

Exception Description
NO_MODIFICATION_ALLOWED_ERR This error is thrown if the NamedNodeMap object is read only.
NOT_FOUND_ERR This error is thrown if no node with a Node.nodeName value of name exists in the
NamedNodeMap.

259
BlackBerry Browser JavaScript Reference

Method: removeNamedItemNS()
The removeNamedItemNS() method removes the node with the specified name and namespace URI from the map.
If you are removing an attribute node from the NamedNodeMap object that is known to have a default value, the
attribute will immediately be reattached to the element with its default value, as well as its corresponding
namespace URI, local name, and prefix, if applicable.

Syntax
NamedNodeMap.removeNamedItemNS( namespaceURI, localName )

Parameters

Parameter Type Description

namespaceURI String The namespace of the node to remove.
localName String The local name of the node to remove.

Return values
Returns the removed node object, if it exists.

Exceptions

Exception Description
NO_MODIFICATION_ALLOWED_ERR This error is thrown if the NamedNodeMap object is read only.
NOT_FOUND_ERR This error is thrown if the specified name does not exist in the NamedNodeMap.
NOT_SUPPORTED_ERR This error is thrown if the document does not support XML namespaces.

260
 JavaScript objects

Method: setNamedItem()
The setNamedItem() method adds a node to the node map using the Node.nodeName property. If a node with the
same Node.nodeName value already exists in the map, the existing node is removed and is replaced by the new
node and the removed node is returned.
As the Node.nodeName property is used to store the new node in the map, in order to prevent name clashes, you
may not add multiple nodes of those node types that always have the same Node.nodeName value. For example, a
text node will always have a Node.nodeName value of “#text”. Therefore, only a single text node may be included
in any NamedNodeMap object.

Syntax
NamedNodeMap.setNamedItem( arg )

Parameters

Parameter Type Description

arg Node The node to add to the map.

Return values
If the new node has replaced an existing node, returns the removed node; otherwise returns null.

Exceptions

Exception
HIERARCHY_REQUEST_ERR
INUSE_ATTRIBUTE_ERR
NO_MODIFICATION_ALLOWED_ERR
WRONG_DOCUMENT_ERR
Description
This error is thrown if the arg node is not permitted in this NamedNodeMap, for
example, if you tried to insert a node other than an Attr into an Element’s map of
attributes.
This error is thrown if arg is an Attr object that is already an attribute of another Element
object. To add an attribute used elsewhere, you must clone it, and then add it.
This error is thrown if the NamedNodeMap object is read only.
This error is thrown if arg was created from a different document than the one that
created this NamedNodeMap object.

261
BlackBerry Browser JavaScript Reference

Method: setNamedItemNS()
The setNamedItemNS() method adds a node using the Node.nodeName property and the namespace URI.

Syntax
NamedNodeMap.setNamedItemNS( arg )

Parameters

Parameter Type Description

arg Node The node to add to the map.

Return values
If the new node has replaced an existing node, returns the removed node; otherwise returns null.

Exceptions

Exception
HIERARCHY_REQUEST_ERR
INUSE_ATTRIBUTE_ERR
NO_MODIFICATION_ALLOWED_ERR
NOT_SUPPORTED_ERR
WRONG_DOCUMENT_ERR
Description
This error is thrown if the arg node is not permitted in this NamedNodeMap, for
example, if you tried to insert a node other than an Attr into an Element’s map of
attributes.
This error is thrown if arg in an Attr object that is already an attribute of another Element
object. To add an attribute used elsewhere, you must clone it, and then add it.
This error is thrown if the NamedNodeMap object is read only.
This error is thrown if the document does not support XML namespaces.
This error is thrown if arg was created from a different document than the one the
created this NamedNodeMap object.

262
 JavaScript objects

Object: Navigator
Availability BlackBerry® Device Software version 4.0 and later

The Navigator object provides information about the version of the BlackBerry® Browser that is being used. All its
properties, which are read-only, contain information about different aspects of the browser.

Properties
Property name Type Description Status
appCodeName String Returns the code name of the browser. The value is typically “BlackBerry”, but may be read only
different if the user has selected an emulation mode other than BlackBerry.
appName String Returns the name of the browser. In the case of the BlackBerry Browser, the value is read only
always “BlackBerry”.
appVersion String Returns the version of the BlackBerry Device Software that is running on the BlackBerry read only
device (for example, “4.6.0”).
buildID String Returns the build identifier of the version of the BlackBerry Device Software running on read only
the device.
cookieEnabled boolean Returns “true” if cookies are enabled in the BlackBerry Browser. read only
language String Returns the two-letter language code (for example, de, en, or ja) that represents the read only
default language translation of the BlackBerry Browser.
mimeTypes MimeTypeArray Returns a list of the MIME types that the target BlackBerry Browser supports. read only
platform String Returns “BlackBerry”. This property is treated as a constant. read only
plugins PluginArray Returns a list of the embedded plugins in the document. read only
userAgent String Returns the user agent from the user-agent header of the HTTP header. The user agent read only
is used by servers to identify the client browser.

Methods
Method name Description
javaEnabled() Tests whether the browser supports Java or not.

263
BlackBerry Browser JavaScript Reference

Method: javaEnabled()
The javaEnabled() method tests whether the browser supports Java or not.

Syntax
navigator.javaEnabled()

Parameters
None.

Return values
In the case of the BlackBerry® Browser, always returns a value of false.

Exceptions
None.

Example
The following code fragment runs the function doThis if Java is supported otherwise, it runs the function
doThat:
if (navigator.javaEnabled()) {
doThis();
}
else doThat();

264
 JavaScript objects

Object: Node
Availability BlackBerry® Device Software version 4.6 and later
Extended By Attr, CharacterData, Document, DocumentFragment, DocumentType, Element, Entity,
EntityReference, Notation, ProcessingInstruction

The Node object represents a unique node within the DOM tree. It is the primary data type for the DOM.
While Node exposes methods for dealing with children, not all objects inheriting from Node may have children. For
example, Text nodes do not permit children; trying to add children to such nodes results in a DOMException being
raised.
The Node.nodeName, Node.nodeValue, and Node.nodeType properties enable you to acquire node information
without casting down to the specific child object. In cases where there is no obvious mapping of these properties
for a specific nodeType (for example, the Node.nodeValue for an Element or attributes for a Comment), they return
null.
The specialized objects may contain additional and more convenient mechanisms to get and set the relevant
information.

Properties
Property name Type Description Status
attributes NamedNodeMap Returns a NamedNodeMap object that contains the attributes of the given read only
element node, or null, if the node is not an element.
childNodes NodeList Returns a NodeList object that contains all the child elements of the given read only
node.
firstChild Node Returns the first child of the given node. read only
lastChild Node Returns the last child of the given node. read only
localName String Returns the local part of the qualified name for the given node. read only
namespaceURI String Returns the namespace URI for the given node, or null if it is not specified. read only
nextSibling Node Returns the node immediately following the given node. read only
nodeName String Returns the name of the given node. read only
nodeType unsigned short Returns a code representing the type of the given node. read only
nodeValue String Specifies the value of the given node. writable
When setting a value for this property, the following errors may be thrown:
• NO_MODIFICATION_ERR: Thrown if the Node object is read only.
When retrieving the value of this property, the following errors may be
thrown:
• DOMSTRING_SIZE_ERR: Thrown if the string contains more characters
than fit in a DOMString variable.
ownerDocument Document Returns the Document object associated with the given node. read only
parentNode Node Returns the parent of the given node. read only

265
BlackBerry Browser JavaScript Reference

Property name Type Description Status

prefix String Specifies the prefix, extracted from the qualified name of the given node, or writable
null if it is unspecified.
When setting a value for this property, the following errors may be thrown:
• INVALID_CHARACTER_ERR: Thrown if the specified value contains an
illegal character.
• NO_MODIFICATION_ERR: Thrown if the Node object is read only.
• NAMESPACE_ERRL Thrown if the specified value is malformed.
previousSibling Node Returns the node immediately preceding the current node. read only

Methods
Method name Description
addEventListener() Adds an EventListener object to a set of event listeners for the given node.
appendChild() Adds a node to the end of the array of child nodes for the given node.
cloneNode() Returns a duplicate of the given node. The duplicate node has no parent.
dispatchEvent() Dispatches an Event object created by Document.createEvent().
hasAttributes() Returns whether the given node has any attributes.
hasChildNodes() Returns whether the given node has any children.
insertBefore() Inserts a new node before the given node.
isSupported() Tests whether the given node supports a specific feature.
normalize() Merges text nodes adjacent to the given element node to create a normalized DOM.
removeChild() Removes the specified child from the given element node and returns it.
removeEventListener() Removes an event listener from an EventTarget.
replaceChild() Removes the specified child from the given and replaces it with another node, then returns the removed node.

266
 JavaScript objects

Method: addEventListener()
The addEventListener() method adds an EventListener object to a set of event listeners for the given node.

Syntax
Node.addEventListener( type, listener, useCapture )

Parameters

Parameter Type Description

type String The type of event to add.
listener EventListener The event listener function to be invoked.
useCapture boolean When true, indicates all events of the specified type to the registered EventListener
before being dispatched to any EventTargets beneath the given node in the tree.
Bubbling events will not trigger the EventListener.
When false, this method dispatches events of the specified type to the registered
EventListener before being dispatched to any EventTargets above the given node in the
tree.

Return values
None.

Exceptions
None.

See also
Event, EventListener

267
BlackBerry Browser JavaScript Reference

Method: appendChild()
The appendChild() method adds a node to the end of an array of children of the given node.

Syntax
Node.appendChild( newChild )

Parameters

Parameter Type Description

newChild Node The node to add.
If newChild is a DocumentFragment object, then the entire contents of the document
fragment are appended to the given node.
If newChild already exists in the tree, it is removed, and then replaced.

Return values
Returns the added node.

Exceptions

Exception
HIERARCHY_REQUEST_ERR
NO_MODIFICATION_ALLOWED_ERR
WRONG_DOCUMENT_ERR
Description
This error is thrown if newChild is one of the given node’s ancestors, or if the given node
does not allow children of the type of newChild node.
This error is thrown if the given node is read only.
This error is thrown if newChild was created from a different document than the given
node.

See also
Node.insertBefore(), Node.removeChild(), Node.replaceChild()

268
 JavaScript objects

Method: cloneNode()
The cloneNode() method returns a duplicate of the given node. The duplicate node has no parent.
If you clone an element or an attribute, you should be aware of the following:
• When you clone an Element, you also duplicate its attributes and their values. However, you do not clone any
text the element contains (since the text is contained in a child text node) unless you specify the deep
parameter.
• When you clone an Attr, this method returns a specified attribute (that is, the specified property for that
attribute is set to true).
Cloning any other type of node simply returns a copy of the node.

Syntax
Node.cloneNode( deep )

Parameters

Parameter Type Description

deep boolean When true, this method clones the subtree under the given node.
When false, this method only clones the given node; it does not clone the subtree.

Return values
Returns the duplicate node.

Exceptions
None.

269
BlackBerry Browser JavaScript Reference

Method: dispatchEvent()
The dispatchEvent() method dispatches an Event object created by Document.createEvent().

Syntax
Node.dispatchEvent( event )

Parameters

Parameter Type Description

event Event The Event object to be dispatched.

Return values
Returns “true” if the Event.preventDefault() was not called by any of the event listeners that handled the
event. The Event.preventDefault() method prevents the default action for the event from occurring; otherwise,
returns “false”.

Exceptions

Exception Description
UNSPECIFIED_EVENT_TYPE_ERR This error is thrown if the event type was not specified by initializing the event before
calling dispatchEvent(), or if the event type was null.

See also
Document.createEvent(), CustomEvent.initCustomEventNS(), Event.initEvent(),
KeyboardEvent.initKeyboardEvent(), MouseEvent.initMouseEvent(), MutationEvent.initMutationEvent(),
TextEvent.initTextEvent(), UIEvent.initUIEvent()

270
 JavaScript objects

Method: hasAttributes()
The hasAttributes() method returns whether the specified node has any attributes. If the node is not an element,
this method returns false.

Syntax
Node.hasAttributes()

Parameters
None.

Return values
Returns “true” if the given node is an element with attributes; otherwise, returns “false”.

Exceptions
None.

See also
Element.getAttribute(), Element.hasAttribute(), Node.attributes

271
BlackBerry Browser JavaScript Reference

Method: hasChildNodes()
The hasChildNodes() method returns whether the given node has any children.

Syntax
Node.hasChildNodes()

Parameters
None.

Return values
Returns “true” if the given node has any child nodes; otherwise, returns “false”.

Exceptions
None.

See also
Node.childNodes

272
 JavaScript objects

Method: insertBefore()
The insertBefore() method inserts a new node before the given child node of the current node. This methods allows
you to insert a node at a specific location among a number of child nodes.

Syntax
Node.insertBefore( newChild, refChild )

Parameters

Parameter Type Description

newChild Node The node to insert.
If newChild is a DocumentFragment object, then the entire contents of the document
fragment are inserted, in order, before refChild.
If newChild already exists as a child of the current node in the tree, it is removed, and
the new node inserted.
refChild Node The existing child node before which newChild is inserted.
If refChild is not specified or is null, newChild is inserted at the end of the list of children.

Return values
Returns the inserted node.

Exceptions

Exception Description
HIERARCHY_REQUEST_ERR This error is thrown if newChild is one of the given node’s ancestors, or if the given node
does not allow children of the type of newChild node.
NO_MODIFICATION_ALLOWED_ERR This error is thrown if the given node is read only.
NOT_FOUND_ERR This error is thrown if refChild is not a child of the given node.
WRONG_DOCUMENT_ERR This error is thrown if newChild was created from a different document than the given
node.

See also
Node.appendChild(), Node.removeChild(), Node.replaceChild()

273
BlackBerry Browser JavaScript Reference

Method: isSupported()
The isSupported() method tests whether the given node supports a specific feature. This method provides similar
functionality as the DOMImplementation.hasFeature() method.

Syntax
Node.isSupported( feature, version )

Parameters

Parameter Type Description

feature String The name of the feature to test.
version String The version of the feature to test.
If version is null, this method returns true if any version of the feature is supported.

Return values
Returns “true” if the specified version of the specified feature is supported; otherwise, returns “false”.

Exceptions
None.

See also
DOMImplementation.hasFeature()

274
 JavaScript objects

Method: normalize()
The normalize() method merges any adjacent text nodes contained by the given node and all of its children to
create a normalized DOM.

Syntax
Node.normalize()

Parameters
None.

Return values
None.

Exceptions
None.

275
BlackBerry Browser JavaScript Reference

Method: removeChild()
The removeChild() method removes the specified child from the given node and returns it.

Syntax
Node.removeChild( oldChild )

Parameters

Parameter Type Description

oldChild Node The child node to remove.

Return values
Returns the removed node.

Exceptions

Exception Description
NO_MODIFICATION_ALLOWED_ERR This error is thrown if the given node is read only.
NOT_FOUND_ERR This error is thrown if oldChild is not a child of the given node.

See also
Node.appendChild(), Node.insertBefore(), Node.replaceChild()

276
 JavaScript objects

Method: removeEventListener()
The removeEventListener() method removes an EventListener from an EventTarget.

Syntax
Node.removeEventListener( type, listener, useCapture )

Parameters

Parameter Type Description

type String The type of event.
listener EventListener The event listener function to be removed.
useCapture boolean When true, indicates that the EventListener being removed was registered as a
capturing listener.
A listener may be registered twice, once as a capturing listener, and once as a non-
capturing listener. Each must be removed separately.

Return values
None.

Exceptions
None.

See also
Event, EventListener, Node.addEventListener()

277
BlackBerry Browser JavaScript Reference

Method: replaceChild()
The replaceChild() method removes the specified child from the current node and replaces it with another node,
then returns the replaced node.

Syntax
Node.replaceChild( newChild, oldChild )

Parameters

Parameter Type Description

newChild Node The node with which to replace the old node with.
If newChild is a DocumentFragment object, then the entire contents of the document
fragment are appended to the given node.
If newChild already exists as a child of the current node in the tree, it is removed, and
then replaced.
oldChild Node The child node to replace.

Return values
Returns the replaced node.

Exceptions

Exception Description
HIERARCHY_REQUEST_ERR This error is thrown if either newChild or oldChild is one of the given node’s ancestors,
or if the given node does not allow children of the type of newChild node.
NO_MODIFICATION_ALLOWED_ERR This error is thrown if the given node is read only.
NOT_FOUND_ERR This error is thrown if oldChild is not a child of the given node.
WRONG_DOCUMENT_ERR This error is thrown if newChild was created from a different document than the given
node.

See also
Node.appendChild(), Node.insertBefore(), Node.removeChild()

278
 JavaScript objects

Object: NodeFilter
Availability BlackBerry® Device Software version 4.6 and later

The NodeFilter object is an object used to filter out nodes. If a NodeIterator or TreeWalker is given a NodeFilter, it
applies the filter before it returns the next node. If the filter says to accept the node, the traversal object, either a
NodeIterator or TreeWalker, returns it; otherwise, the traversal object looks for the next node and pretends that the
node that was rejected was not there.

Methods
Method name Description
acceptNode() Tests whether a specified node is visible in the logical view of a TreeWalker or NodeIterator.

279
BlackBerry Browser JavaScript Reference

Method: acceptNode()
The acceptNode() method tests whether a specified node is visible in the logical view of a TreeWalker or
NodeIterator. This method is normally called by the TreeWalker or NodeIterator object, rather than as part of the
JavaScript code.

Syntax
NodeFilter.acceptNode( n )

Parameters

Parameter Type Description

n Node The node to check.

Return values
Returns a constant that determines whether the node is accepted, rejected, or skipped.

Constant Definition Description

1 FILTER_ACCEPT
2 FILTER_REJECT
3 FILTER_SKIP
Navigation methods defined for TreeWalker or NodeIterator will return the node.
Navigation methods defined for TreeWalker or NodeIterator will not return the node. In
the case of TreeWalker, the children of the node are also rejected. In the case of
NodeIterator, this is equivalent to FILTER_SKIP.
Navigation methods defined for TreeWalker or NodeIterator will not return the node,
however, children of this node are still considered.

Exceptions
None.

280
 JavaScript objects

Object: NodeIterator
Availability BlackBerry® Device Software version 4.6 and later

The NodeIterator object enables you to navigate up and down through a flat representation of the document tree.
This object is similar to the TreeWalker objects, except that TreeWalker presents nodes in a tree-oriented view,
rather than the list view presented by NodeIterator.
Create a NodeIterator using Document.createNodeIterator().

Related topics
NodeFilter, TreeWalker

Properties
Property name Type Description Status
expandEntityReferences boolean Returns whether or not the NodeIterator expands the entity references it read only
encounters as it traverses the document.
filter NodeFilter Returns the NodeFilter used to filter nodes for traversal. read only
root Node Returns the Node at which the NodeIterator begins traversing the document. read only
whatToShow unsigned long Returns which node types are presented by the NodeIterator. The value may be read only
one or more of:
• 0xFFFFFFFF = SHOW_ALL
• 0x00000001 = SHOW_ELEMENT
• 0x00000002 = SHOW_ATTRIBUTE
• 0x00000004 = SHOW_TEXT
• 0x00000008 = SHOW_CDATA_SECTION
• 0x00000010 = SHOW_ENTITY_REFERENCE
• 0x00000020 = SHOW _ENTITY
• 0x00000040 = SHOW_PROCESSING_INSTRUCTION
• 0x00000080 = SHOW_COMMENT
• 0x00000100 = SHOW_DOCUMENT
• 0x00000200 = SHOW_DOCUMENT_TYPE
• 0x00000400 = SHOW_DOCUMENT_FRAGMENT
• 0x00000800 = SHOW_NOTATION
Multiple values may be specified using a bitwise OR.
Note that because attributes, entities, and notations are not the child of any other
node, they never appear when traversing the document tree unless they are
defined as the root of the NodeIterator object. If the respective object is not
defined as the root, then SHOW_ATTRIBUTE, SHOW_ENTITY, and SHOW
NOTATION have no meaning.

281
BlackBerry Browser JavaScript Reference

Methods
Method name Description
detach() Detaches the NodeIterator from the set which it iterated over.
nextNode() Moves the NodeIterator to the next visible Node in the document order, relative to the current node.
previousNode() Moves the NodeIterator to the previous visible Node in the document order, relative to the current
node.

282
 JavaScript objects

Method: detach()
The detach() method detaches the NodeIterator from the set which it iterated over. After a NodeIterator has been
detached, attempting to use NodeIterator.nextNode() or NodeIterator.previousNode() results in an error.

Syntax
NodeIterator.detach()

Parameters
None.

Return values
None.

Exceptions
Node.

283
BlackBerry Browser JavaScript Reference

Method: nextNode()
The nextNode() method moves the NodeIterator to the next visible Node in the document order, relative to the
current node. The first call to this method after a NodeIterator is created returns the first Node in the set.

Syntax
NodeIterator.nextNode()

Parameters
None.

Return values
Returns the node, or null, if there is no node after the current node in the NodeIterator’s logical view.

Exceptions

Exception Description
INVALID_STATE_ERR This error is thrown if this method is called after the NodeIterator has been detached
from the set that it iterated over.

284
 JavaScript objects

Method: previousNode()
The previousNode() method moves the NodeIterator to the previous visible Node in the document order, relative to
the current node.

Syntax
NodeIterator.previousNode()

Parameters
None.

Return values
Returns the node, or null, if there is no node before the current node in the NodeIterator’s logical view.

Exceptions

Exception Description
INVALID_STATE_ERR This error is thrown if this method is called after the NodeIterator has been detached
from the set that it iterated over.

285
BlackBerry Browser JavaScript Reference

Object: NodeList
Availability BlackBerry® Device Software version 4.6 and later

The NodeList object is an array that contains an ordered collection of nodes.

You can access an individual Node within a collection by its index position using NodeList.item() or you can index
the object directly. For example, if you create an instance of a NodeList object called myNodeList, then specifying
myNodelist.item(2)
is equivalent to specifying
myNodelist[2]

Properties
Property name Type Description Status
length unsigned long Returns the number of nodes in the list. read only

Methods
Method name Description
item() Returns the node at the specified index in the collection.

286
 JavaScript objects

Method: item()
The item() method returns the node at the specified index in the collection.

Syntax
ModeList.item( index )

Parameters

Parameter Type Description

index int An integer that represents the node’s position in NodeList. Valid values are between 0
and NodeList.length-1 inclusive.

Return values
Returns the node at the indexth position in NodeList, or null if an invalid index position is specified.

Exceptions
None.

287
BlackBerry Browser JavaScript Reference

Object: Notation
Availability BlackBerry® Device Software version 4.6 and later
Extend Node

The Notation object represents a notation declared in a DTD. A Notation declares the format of an unparsed entity,
or is used to formally declare ProcessingInstruction targets.
The Node.nodeName property is set to the declared name of the Notation.

Properties
Property name Type Description Status
publicId String Returns the public identifier of the Notation, or null if no identifier has been specified. read only
systemId String Returns the system identifier of the Notation, or null if no identifier has been specified. read only

288
 JavaScript objects

Object: Plugin
Availability BlackBerry® Device Software version 4.0 and later

The Plugin object belongs to the Navigator object. It provides access to all the plugins that the BlackBerry®
Browser supports.
You can access an individual Plugin within a collection by its index position using Plugin.item(), by its name or id
attribute using Plugin.namedItem(), or you can index the object directly. For example, if you create an instance of
a Plugin object called myPlugins, then specifying
myPlugins.item(2)
myPlugins.namedItem(“item”)
is equivalent to specifying
myPlugins[2]
myPlugins[“item”]

Properties
Property name Type Description Status
description String Returns the description of the Plugin. read only
filename String Returns the Plugin filename. read only
length unsigned long Returns the number of MIME types associated with the Plugin. read only
name String Returns the name of the Plugin. read only

Methods
Method name Description
item() Returns the MIME type at the specified index in the collection.
namedItem() Returns the MIME type with the given name.

289
BlackBerry Browser JavaScript Reference

Method: item()
The item() method returns the Plugin at the specified index in the collection.

Syntax
Plugin.item( index )

Parameters

Parameter Type Description

index int The index position of the Plugin to be returned. Valid values are between 0 and
Plugin.length-1 inclusive.

Return values
Returns the plugin at the indexth position in Plugin, or null if an invalid index position is specified.

Exceptions
None.

290
 JavaScript objects

Method: namedItem()
The namedItem() method retrieves the Plugin with the given name from the collection.

Syntax
Plugin.namedItem( name )

Parameters

Parameter Type Description

name String The name of the Plugin to retrieve.

Return values
Returns the Plugin with the given name, or null if no Plugin with the given name exists in the array.

Exceptions
None.

291
BlackBerry Browser JavaScript Reference

Object: PluginArray
Availability BlackBerry® Device Software version 4.6 and later

The PluginArray object contains an ordered collection of Plugins.

Properties
Property name Type Description Status
length unsigned long Returns the number of Plugins in the collection. read only

Methods
Method name Description
item() Returns the Plugin at the specified index in the collection.
namedItem() Retrieves the Plugin with the given name from the collection.

292
 JavaScript objects

Method: item()
The item() method returns the Plugin at the specified index in the collection.

Syntax
PluginArray.item( index )

Parameters

Parameter Type Description

index int The index position of the MIME type to be returned. Valid values are between 0 and
PluginArray.length-1 inclusive.

Return values
Returns the Plugin at the indexth position in PluginArray, or null if an invalid index position is specified.

Exceptions
None.

293
BlackBerry Browser JavaScript Reference

Method: namedItem()
The namedItem() method retrieves the Plugin with the given name from the collection.

Syntax
PluginArray.namedItem( name )

Parameters

Parameter Type Description

name String The name of the Plugin object to retrieve.

Return values
Returns the Plugin with the given name, or null if no plugin with the given name exists in the array.

Exceptions
None.

294
 JavaScript objects

Object: ProcessingInstruction
Availability BlackBerry® Device Software version 4.6 and later
Extends Node

The ProcessingInstruction object represents a Processing Instruction for an XML document, which enables you to
keep processor-specific information within the context of the document. Processing instructions are specified
within the <? and ?> markers.
For instance, instructions on which style sheets to apply can be defined in a processing instruction, even though
that is not directly related to the content of the document.

Properties
Property name Type Description Status
data String Specifies the content of the processing instruction. This content includes everything writable
contained between the processing instruction markers.
sheet String Returns the style sheet associated with the processing instruction. read only
target String Returns the target of the processing instruction. read only

295
BlackBerry Browser JavaScript Reference

Object: Rect
Availability BlackBerry® Device Software version 4.6 and later

The Rect object represents a Rect value.

The Rect object contains four properties, each of which defines a style for the side of a rectangle.

Properties
Property name Type Description Status
bottom String Returns the style for the bottom of the Rect. read only
left String Returns the style for the left side of the Rect. read only
right String Returns the style for the right side of the Rect. read only
top String Returns the style for the top of the Rect. read only

296
 JavaScript objects

Object: RGBColor
Availability BlackBerry® Device Software version 4.6 and later

The RGBColor object represents an RGB color value.

The RGBColor object contains three properties, each of which specifies the value for a different color channel for
the overall color. Valid color channel values can be either a numerical value between 0 and 255, or a percentage
between 0% and 100%, although values outside of those ranges are not clipped.

Properties
Property name Type Description Status
blue CSSPrimitiveValue Returns the blue value of the RGB value. read only
green CSSPrimitiveValue Returns the green value of the RGB value. read only
red CSSPrimitiveValue Returns the red value of the RGB value. read only

297
BlackBerry Browser JavaScript Reference

Object: Screen
Availability BlackBerry® Device Software version 4.6 and later

The Screen object returns information about the dimensions and color depth of the BlackBerry device display.

Properties
Property name Type Description Status
availHeight int Returns the height of the BlackBerry device screen that is available to the BlackBerry® read only
Browser, in pixels. This may be equal to or less than the value of Screen.height.
availLeft int Returns the screen space available to the left of the browser window. In the case of the read only
BlackBerry Browser, this property always returns a value of “0”.
availTop int Returns the screen space available above the browser window. In the case of the read only
BlackBerry Browser, this property always returns a value of “0”.
availWidth int Returns the width of the BlackBerry device screen that is available to the BlackBerry read only
Browser, in pixels. This may be equal to or less than the value of Screen.width.
colorDepth int Returns the bit depth of the color palette. This property behaves identically to the read only
pixelDepth property.
height int Returns the height of the BlackBerry device screen, in pixels. read only
pixelDepth int Returns the color resolution, in bits per pixel, of the display. read only
width int Returns the width of the BlackBerry device screen, in pixels. read only

298
 JavaScript objects

Object: StyleSheet
Availability BlackBerry® Device Software version 4.6 and later

The StyleSheet object represents a single style sheet associated with a document. A StyleSheet object can
represent either an external style sheet, or an inline style element.

Properties
Property name Type Description Status
disabled boolean When true, indicates that the style sheet is not applied. writable
Note that if the media specified in the MediaList object returned by StyleSheet.media is
not supported by the BlackBerry® Browser, then this property is ignored.
href String Returns the URI of an external style sheet. read only
media MediaList Returns the destination media for the style information. If no media has been specified, read only
this property returns the empty MediaList object.
The media is often specified in StyleSheet.ownerNode.
ownerNode Node Returns the Node that associates this style sheet with the document. For HTML read only
documents, this is typically the corresponding <link> or <style> element.
If the style sheet is the child of another style sheet, this property returns null.
parentStyleSheet StyleSheet Returns the StyleSheet object that contains the style sheet, if one exists. read only
If the style sheet is not the child of another style sheet, this property returns null.
title String Returns the title of the style sheet. read only
The title is often specified in StyleSheet.ownerNode.
type String Returns the style sheet language used by the style sheet, specified as a content type, read only
such as “text/css”.
The content type is often specified in StyleSheet.ownerNode.

299
BlackBerry Browser JavaScript Reference

Object: StyleSheetList
Availability BlackBerry® Device Software version 4.6 and later

The StyleSheetList object represents an ordered collection of StyleSheet objects.

You can access an individual StyleSheet within a collection by its index position using StyleSheetList.item() or you
can index the object directly. For example, if you create an instance of a StyleSheetList object called
myStyleSheets, then specifying
myStyleSheets.item(2)
is equivalent to specifying
myStyleSheets[2]

Properties
Property name Type Description Status
length unsigned long Returns the number of style sheets in the list. read only

Methods
Method name Description
item() Returns the StyleSheet object at the specified index in the StyleSheetList.

300
 JavaScript objects

Method: item()
The item() method returns the StyleSheet object at the specified index in the StyleSheetList.

Syntax
StyleSheetList.item( index )

Parameters

Parameter Type Description

index int An integer that represents the CSS rule’s position in rule list. Valid values are 0 to
StyleSheetList.length-1.

Return values
Returns the rule at the indexth position in StyleSheetList, or null if an invalid index position is specified.

Exceptions
None.

301
BlackBerry Browser JavaScript Reference

Object: Text
Availability BlackBerry® Device Software version 4.6 and later
Extends CharacterData

The Text object represents the textual content of an element or attribute. If an element contains no child elements,
any text is contained in a single text node in the DOM.
Although it is possible to place multiple text objects are adjacent to one another in a document, adjacent text
nodes have no meaning in a document. Hence, using Text.splitText() has no visual effect on the document unless
one of the nodes is wrapped by an element.

Methods
Method name Description
splitText() Breaks the node into two nodes at the specified offset location.

302
 JavaScript objects

Method: splitText()
The splitText() method breaks the node into two nodes at the specified offset location.

Syntax
TextNode.splitText( offset )

Parameters

Parameter Type Description

offset long The offset position at which to split the text.

Return values
Returns the second half of the text as a new Text node, which is automatically added to the DOM tree
adjacent to the original Text node.

Exceptions

Exception Description
INDEX_SIZE_ERR This error is thrown if offset is negative, or is greater than the number of 16-bit units in
the data.
NO_MODIFICATION_ALLOWED_ERR This error is thrown if the Node is read only.

303
BlackBerry Browser JavaScript Reference

Object: TextEvent
Availability BlackBerry® Device Software version 4.6 and later
Extend UIEvent

The Text 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

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

Properties
Property name Type Description Status
data String Returns the value of the characters generated by the character device. The value of this read only
property may be a single Unicode character or a sequence of Unicode characters. This
property cannot be null or contain an empty string.

Methods
Method name Description
initTextEvent() Initializes the value of a TextEvent.
initTextEventNS() Initializes the value of a TextEvent with the given namespace URI.

304
 JavaScript objects

Method: initTextEvent()
The initTextEvent() method initializes the value of a TextEvent created by Document.createEvent().

Syntax
TextEvent.initUIEvent( typeArg, canBubbleArg, cancelableArg, viewArg, dataArg )

Parameters

Parameter Type Description

typeArge String Specifies the event type.
canBubbleArg boolean When true, this parameter indicates that the event can bubble.
cancelableArg boolean When true, this parameter indicates that the event can be cancelled.
viewArg AbstractView Specifies the window or frame that is generating the event.
dataArg String Specifies the characters generated by the input device. This parameter sets the value of
TextEvent.data.

Return values
None.

Exceptions
None.

305
BlackBerry Browser JavaScript Reference

Method: initTextEventNS()
The initTextEventNS() method initializes the value of a TextEvent created by Document.createEvent() with the
given namespace URI.

Syntax
TextEvent.initTextEvent( namespaceURI, typeArg, canBubbleArg, cancelableArg, viewArg,
dataArg )

Parameters

Parameter Type Description

namespaceURI String Specifies the namespace URI associated with this event, or null if no namespace exists.
typeArg String Specifies the event type.
canBubbleArg boolean When true, this parameter indicates that the event can bubble.
cancelableArg boolean When true, this parameter indicates that the event can be cancelled.
viewArg AbstractView Specifies the window or frame that is generating the event.
dataArg String Specifies the characters generated by the input device. This parameter sets the value of
TextEvent.data.

Return values
None.

Exceptions
None.

306
 JavaScript objects

Object: TreeWalker
Availability BlackBerry® Device Software version 4.6 and later

The TreeWalker object enables you to navigate the document tree or subtree. This object is similar to the
NodeIterator objects, except that TreeWalker presents nodes in a tree-oriented view, rather than the list view
presented by NodeIterator. This allows you to use TreeWalker to navigate directly to a parent or child, rather than
simply up and down in the list using NodeIterator.
Create a TreeWalker using Document.createTreeWalker().

Related topics
NodeFilter, NodeIterator

Properties
Property name Type Description Status
currentNode Node Specifies the current position of the TreeWalker. writable
expandEntityReferences boolean Returns whether or not the TreeWalker expands the entity references it read only
encounters as it traverses the document.
filter NodeFilter Returns the NodeFilter used to filter nodes for traversal. read only
root Node Returns the Node at which the TreeWalker begins traversing the document. read only
whatToShow unsigned long Returns which node types are presented by the TreeWalker. The value may be one read only
or more of:
• 0xFFFFFFFF = SHOW_ALL
• 0x00000001 = SHOW_ELEMENT
• 0x00000002 = SHOW_ATTRIBUTE
• 0x00000004 = SHOW_TEXT
• 0x00000008 = SHOW_CDATA_SECTION
• 0x00000010 = SHOW_ENTITY_REFERENCE
• 0x00000020 = SHOW _ENTITY
• 0x00000040 = SHOW_PROCESSING_INSTRUCTION
• 0x00000080 = SHOW_COMMENT
• 0x00000100 = SHOW_DOCUMENT
• 0x00000200 = SHOW_DOCUMENT_TYPE
• 0x00000400 = SHOW_DOCUMENT_FRAGMENT
• 0x00000800 = SHOW_NOTATION
Multiple values may be specified using a bitwise OR.
Note that because attributes, entities, and notations are not the child of any other
node, they never appear in the TreeWalker’s logical view unless they are defined
as the root of the TreeWalker object. If the respective object is not defined as the
root, then SHOW_ATTRIBUTE, SHOW_ENTITY, and SHOW NOTATION have no
meaning.

307
BlackBerry Browser JavaScript Reference

Methods
Method name Description
firstChild() Moves the TreeWalker to the first visible child of the current node.
lastChild() Moves the TreeWalker to the last visible child of the current node.
nextNode() Moves the TreeWalker to the next visible Node in the document order, relative to the current node.
nextSibling() Moves the TreeWalker to the next sibling of the current node.
parentNode() Moves the TreeWalker to the closest visible ancestor node of the current node.
previousNode() Moves the TreeWalker to the previous visible Node in the document order, relative to the current node.
previousSibling() Moves the TreeWalker to the previous sibling of the current node.

308
 JavaScript objects

Method: firstChild()
The firstChild() method moves the TreeWalker to the first visible child of the current node. The value of
TreeWalker.currentNode is updated to reflect the TreeWalker’s new location in the tree.
If no visible children exist in the TreeWalker’s view, the value of TreeWalker.currentNode remains unchanged.

Syntax
TreeWalker.firstChild()

Parameters
None.

Return values
Returns the node, or null, if the current node has no visible children in the TreeWalker’s logical view.

Exceptions
None.

309
BlackBerry Browser JavaScript Reference

Method: lastChild()
The lastChild() method moves the TreeWalker to the last visible child of the current node. The value of
TreeWalker.currentNode is updated to reflect the TreeWalker’s new location in the tree.
If no visible children exist in the TreeWalker’s view, the value of TreeWalker.currentNode remains unchanged.

Syntax
TreeWalker.lastChild()

Parameters
None.

Return values
Returns the node, or null, if the current node has no visible children in the TreeWalker’s logical view.

Exceptions
None.

310
 JavaScript objects

Method: nextNode()
The nextNode() method moves the TreeWalker to the next visible Node in the document order, relative to the
current node. The value of TreeWalker.currentNode is updated to reflect the TreeWalker’s new location in the tree.
If no node exists after the current node in the TreeWalker’s view, the value of TreeWalker.currentNode remains
unchanged.

Syntax
TreeWalker.nextNode()

Parameters
None.

Return values
Returns the node, or null, if there is no node after the current node in the TreeWalker’s logical view.

Exceptions
None.

311
BlackBerry Browser JavaScript Reference

Method: nextSibling()
The nextSibling() method moves the TreeWalker to the next sibling of the current node. The value of
TreeWalker.currentNode is updated to reflect the TreeWalker’s new location in the tree.
If no visible sibling node exists after the current node in the TreeWalker’s view, the value of
TreeWalker.currentNode remains unchanged.

Syntax
TreeWalker.nextSibling()

Parameters
None.

Return values
Returns the node, or null, if the current node has no visible siblings after it in the TreeWalker’s logical view.

Exceptions
None.

312
 JavaScript objects

Method: parentNode()
The parentNode() method moves the TreeWalker to the closest visible ancestor node of the current node. The value
of TreeWalker.currentNode is updated to reflect the TreeWalker’s new location in the tree.
If no visible ancestor node exists in the TreeWalker’s view, the value of TreeWalker.currentNode remains
unchanged.

Syntax
TreeWalker.parentNode()

Parameters
None.

Return values
Returns the node, or null, if the current node has no visible ancestor in the TreeWalker’s logical view.

Exceptions
None.

313
BlackBerry Browser JavaScript Reference

Method: previousNode()
The previousNode() method moves the TreeWalker to the previous visible Node in the document order, relative to
the current node. The value of TreeWalker.currentNode is updated to reflect the TreeWalker’s new location in the
tree.
If no node exists before the current node in the TreeWalker’s view, the value of TreeWalker.currentNode remains
unchanged.

Syntax
TreeWalker.previousNode()

Parameters
None.

Return values
Returns the node, or null, if there is no node before the current node in the TreeWalker’s logical view.

Exceptions
None.

314
 JavaScript objects

Method: previousSibling()
The previousSibling() method moves the TreeWalker to the previous sibling of the current node. The value of
TreeWalker.currentNode is updated to reflect the TreeWalker’s new location in the tree.
If no visible sibling node exists before the current node in the TreeWalker’s view, the value of
TreeWalker.currentNode remains unchanged.

Syntax
TreeWalker.previousSibling()

Parameters
None.

Return values
Returns the node, or null, if the current node has no visible sibling before it in the TreeWalker’s logical view.

Exceptions
None.

315
BlackBerry Browser JavaScript Reference

Object: UIEvent
Availability BlackBerry® Device Software version 4.6 and 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”.

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

Properties
Property name Type Description Status
detail long Returns detail information about the event. read only
view AbstractView Returns a reference to the AbstractView that generated the event. read only

Methods
Method name Description
initUIEvent() Initializes the value of a UIEvent.

316
 JavaScript objects

Method: initUIEvent()
The initUIEvent() method initializes the value of a UIEvent created by Document.createEvent().

Syntax
UIEvent.initUIEvent( typeArg, canBubbleArg, cancelableArg, viewArg, detailArg )

Parameters

Parameter Type Description

typeArg String Specifies the event type.
canBubbleArg boolean When true, this parameter indicates that the event can bubble.
cancelableArg boolean When true, this parameter indicates that the event can be cancelled.
viewArg AbstractView Specifies the window or frame that is generating the event.
detailArg long Specifies the code for the event detail.

Return values
None.

Exceptions
None.

317
BlackBerry Browser JavaScript Reference

Object: Window
Availability BlackBerry® Device Software version 3.8 and later

The Window object is created automatically when the BlackBerry® Browser encounters a <body> or <frameset>
tag. It returns information about the window.

Properties
Property name Type Description Status Availability
blackberry Blackberry Returns a reference to the Blackberry object. read only 3.8 and later
closed boolean Returns whether the window is open or closed. This property always read only 3.8 and later
has a value of “false”.
document Document Returns the Document object that is contained within the window. read only 3.8 and later
frameElement HTMLElement Returns the element in which the window is embedded, or null if the read only 3.8 and later
window is not embedded in any frame.
frames NamedFrameMap Returns a NamedFrameMap object that contains a collection of the read only 3.8 and later
frames contained by the frameset.
history History Returns the History object that contains a collection of recently read only 3.8 and later
accessed URLs.
innerHeight int Returns the height of the content area, including the horizontal scroll read only 3.8 and later
bar, if rendered.
innerWidth int Returns the width of the content area, including the vertical scroll bar, read only 3.8 and later
if rendered.
length unsigned long Returns the number of frames in the parent window. read only 3.8 and later
location Location Specifies the URL of the document displayed in the browser window. writable 3.8 and later
navigator Navigator Returns the Navigator object, which provides information about the read only 3.8 and later
BlackBerry Browser.
name String Specifies the name of the window. writable 3.8 and later
opener Window Returns the Window object that created the window. read only 3.8 and later
parent Window Returns the parent Window object. read only 3.8 and later
screen Screen Returns the Screen object, which provides information about the read only 3.8 and later
BlackBerry device screen.
self Window Returns a reference to the current window. read only 3.8 and later
top Window Returns a reference to the top window. read only 3.8 and later
window Window Returns a reference to the current window. Using the window read only 3.8 and later
property lets you invoke methods or call properties on the current
window without confusion when multiple browser windows are open.
Because the BlackBerry Browser is a single document interface, a new
window is opened each time a new URL is opened.

318
 JavaScript objects

Event handlers
Property name Type Description Status Availability
onabort Function Specifies the function to perform when the loading of a page or image writable 4.6 and later
is aborted.
onchange Function Specifies the function to perform when a form control loses focus after writable 4.6 and later
the user has modified the value.
onclick Function Specifies the function to perform when the user clicks the trackball or writable 3.8 and later
trackwheel on a BlackBerry device.
onerror Function Specifies the function to perform when an error occurs. writable 4.6 and later
onkeydown Function Specifies the function to perform when a key is pressed down while writable 4.6 and later
the pointer is over an element.
onkeypress Function Specifies the function to perform when a key is pressed and released writable 4.6 and later
while the pointer is over an element.
onkeyup Function Specifies the function to perform when a key is released while the writable 4.6 and later
pointer is over an element.
onload Function Specifies the function to perform when the BlackBerry Browser writable 4.6 and later
finishes loading a new page or a complete frameset.
onmousedown Function Specifies the function to perform when the user depresses the writable 4.6 and later
trackwheel or trackball on a BlackBerry device.
onmousemove Function Specifies the function to perform when the user moves the pointer writable 4.6 and later
while it is over an element.
onmouseout Function Specifies the function to perform when the user moves the pointer off writable 4.6 and later
of an element.
onmouseover Function Specifies the function to perform when the user moves the pointer writable 4.6 and later
over an element.
onmouseup Function Specifies the function to perform when the user releases the writable 4.6 and later
trackwheel or trackball on a BlackBerry device.
onreset Function Specifies the function to perform when the user resets a form. writable 3.8 and later
onselect Function Specifies the function to perform when the user selects some text in a writable 4.6 and later
text field.
onsubmit Function Specifies the function to perform when the user submits a form. writable 3.8 and later
onunload Function Specifies the function to perform when the BlackBerry Browser writable 4.6 and later
removes a new page or a frameset.

Methods
Method name Description
addEventListener() Adds an EventListener object to a set of event listeners for the window.
alert() Displays a standard alert dialog box with an OK button.
back() Displays the previous URL in the history list.
blur() Removes focus from the window.
close() Closes the active window.
confirm() Displays a standard confirmation dialog box with an OK button and a Cancel button.

319
BlackBerry Browser JavaScript Reference

Method name Description

dispatchEvent() Dispatches an Event object created by Document.createEvent().
find() Displays a dialog box that allows a user to enter a string of text and search for it in the current
document.
focus() Gives focus to the current window.
forward() Displays the next element in the history list of the browser.
getComputedStyle() Retrieves the computed style values for an element.
home() Returns to the page that the user set as the browser home page.
moveBy() Moves the window a specified number of pixels in relation to its current co-ordinates.
moveTo() Moves the window's left and top edge to the specified co-ordinates .
open() Opens a new browser window.
print() Prints the current contents of the window.
prompt() Displays a prompt dialog box that prompts users for input.
removeEventListener() Removes an event listener from an EventTarget.
resizeBy() Resizes the viewport relative to the current viewport size.
resizeTo() Resizes the viewport to the specified width and height.
scroll() Scrolls the content to a given set of coordinates.
scrollBy() Scrolls the content by the given number of pixels.
scrollTo() Scrolls the content to a given set of coordinates.
stop() Stops the current download.

320
 JavaScript objects

Method: addEventListener()
The addEventListener() method adds an EventListener object to a set of event listeners for the window.

Syntax
window.addEventListener( type, listener, useCapture )

Parameters

Parameter Type Description

type String The type of event to add.
listener EventListener The EventListener function to be invoked.
useCapture boolean When true, indicates all events of the specified type to the registered EventListener
before being dispatched to any EventTargets beneath the given node in the tree.
Bubbling events will not trigger the EventListener.
When false, this method dispatches events of the specified type to the registered
EventListener before being dispatched to any EventTargets above the given node in the
tree.

Return values
None.

Exceptions
None.

See also
Event, EventListener

321
BlackBerry Browser JavaScript Reference

Method: alert()
The alert() method displays a standard alert dialog box with an OK button.
You should use an alert dialog box for those cases in which no input is required by the user.

Syntax
window.alert( message )

Parameters

Parameter Type Description

message String The text that is displayed as the dialog box message.

Return values
None.

Exceptions
None.

See also
Window.confirm(), Window.prompt()

322
 JavaScript objects

Method: back()
The back() method displays the previous URL in the history list. This method is functionally equivalent to
History.back().

Syntax
window.back()

Parameters
None.

Return values
None.

Exceptions
None.

See also
History.back(), Window.close(), Window.forward(), Window.history

323
BlackBerry Browser JavaScript Reference

Method: blur()
The blur() method removes focus from the window.
This method is a stub implementation. It has no effect on the BlackBerry® Browser.

Syntax
window.blur()

Parameters
None.

Return values
This method is ignored. No values are returned.

Exceptions
None.

324
 JavaScript objects

Method: close()
The close() method closes the active window. In the BlackBerry® Browser, this is functionally equivalent to
Window.back() and History.back().
If no earlier item exists in the Window.history array, the BlackBerry Browser is closed and the browser session
ends.

Syntax
window.close()

Parameters
None.

Return values
None.

Exceptions
None.

See also
History.back(), Window.back(), Window.history, Window.open()

325
BlackBerry Browser JavaScript Reference

Method: confirm()
The confirm() method displays a standard confirmation dialog box with an OK button and a Cancel button.
Use a confirm dialog box when you want to give the user the option to proceed with or cancel some action. The
user may not continue to browse or use the current page until they have closed the dialog box.

Syntax
window.confirm( message )

Parameters

Parameter Type Description

message String The text that is displayed as the dialog box message.

Return values
Returns a value of “true” if the OK button was clicked; returns “false” if Cancel was clicked.

Exceptions
None.

See also
Window.alert(), Window.prompt()

326
 JavaScript objects

Method: dispatchEvent()
The dispatchEvent() method dispatches an Event object created by Document.createEvent().

Syntax
window.dispatchEvent( event )

Parameters

Parameter Type Description

event Event The Event object to be dispatched.

Return values
Returns “true” if the Event.preventDefault() was not called by any of the event listeners that handled the
event. The Event.preventDefault() method prevents the default action for the event from occurring; otherwise,
returns “false”.

Exceptions

Exception Description
UNSPECIFIED_EVENT_TYPE_ERR This error is thrown if the event type was not specified by initializing the event before
calling dispatchEvent(), or if the event type was null.

327
BlackBerry Browser JavaScript Reference

Method: find()
The find() method searches for a given string in the current window. If the search term was located within the
window, the search stops and returns a value of “true”.
If the search is restarted with the same term, the browser continues searching from the location of the last search
result. If you provide a new search term, the browser begins searching at the start of the document and stops and
returns a value of “true” when the given term is found.
Note that the caseSensitive and searchInFrames parameters are optional, but mutually inclusive. That is, you must
either specify both of the parameters or neither of them.

Syntax
window.find( str [, caseSensitive, searchInFrames ] )

Parameters

Parameter Type Description

str String The string of text to search for in the current document.
caseSensitive boolean Optional. If true, indicates that the case of the search term should be considered when
searching.
searchInFrames boolean Optional. If true, indicates that the browser should search for the given term in all
currently displayed frames.

Return values
Return a value of “true” if the string is found; otherwise, returns “false”.

Exceptions
None.

328
 JavaScript objects

Method: focus()
The focus() method gives focus to the window.

Syntax
window.focus()

Parameters
None.

Return values
None.

Exceptions
None.

329
BlackBerry Browser JavaScript Reference

Method: forward()
The forward() method displays the next URL in the history list of the browser. This method is functionally
equivalent to History.forward().

Syntax
window.forward()

Parameters
None.

Return values
None.

Exceptions
None.

See also
History.forward(), Window.back(), Window.history

330
 JavaScript objects

Method: getComputedStyle()
The getComputedStyle() method retrieves the computed style values for an element. This method returns the style
declaration as a read only value.

Syntax
window.getComputedStyle( elt, pseudoElt )

Parameters

Parameter Type Description

elt Element The element for which to view the style.
pseudoElt String The pseudo-element for which to modify the style, or null if none.

Return values
Returns the computed style value for the specified element.

Exceptions
None.

See also
HTMLElement.style

331
BlackBerry Browser JavaScript Reference

Method: home()
The home() method displays the page that the user set as the BlackBerry® Browser home page.

Syntax
window.home()

Parameters
None.

Return values
None.

Exceptions
None.

332
 JavaScript objects

Method: moveBy()
The moveBy() method moves the window a specified number of pixels in relation to its current co-ordinates.
This method is a stub implementation. It has no effect on the BlackBerry® Browser.

Syntax
window.moveBy ( deltaX, deltaY )

Parameters

Parameter Type Description

deltaX int The number of pixels to move the window horizontally.
deltaY int The number of pixels to move the window vertically.

Return values
This method is ignored. No values are returned.

Exceptions
None.

333
BlackBerry Browser JavaScript Reference

Method: moveTo()
The moveTo() method moves the window's left and top edge to the specified co-ordinates.
This method is a stub implementation. It has no effect on the BlackBerry® Browser.

Syntax
window.moveTo ( x, y )

Parameters

Parameter Type Description

x int The number of pixels from the left edge of the screen to move the window.
y int The number of pixels from the top edge of the screen to move the window.

Return values
This method is ignored. No values are returned.

Exceptions
None.

334
 JavaScript objects

Method: open()
The open() method opens a new browser window.
The BlackBerry® Browser is a single document interface, it opens a new window and places it at the top of the
stack whenever the user opens a link on a page or enters a new URL via the Go to menu item. Consequently, this
method essentially has the same net effect in the BlackBerry Browser as specifying a new value for
Window.location.

Syntax
window.open( URL [, name ] )

Parameters

Parameter Type Description

URL int The URL to be displayed in the child window
name String Optional. The name of the window that is being opened.

Return values
Returns a reference to the new Window object.

Exceptions
None.

See also
Window.close()

335
BlackBerry Browser JavaScript Reference

Method: print()
The print() method prints the current contents of the window.
This method is a stub implementation. It has no effect on the BlackBerry® Browser.

Syntax
window.print()

Parameters
None.

Return values
This method is ignored. No values are returned.

Exceptions
None.

336
 JavaScript objects

Method: prompt()
The prompt() method displays a prompt dialog box that prompts users for input. A prompt dialog box includes a
single line input field.
Use a prompt dialog when you need immediate feedback from the user. The user may not continue to browse or
use the current page until they have closed the dialog box.

Syntax
window.prompt( message, defaultValue )

Parameters

Parameter Type Description

message String The text that is displayed as the dialog box message.
defaultValue String The default value of the input field, or null if no default is to be provided.

Return values
Returns the user input as a string. If the user enters no input, this method returns an empty string.

Exceptions
None.

See also
Window.alert(), Window.confirm()

337
BlackBerry Browser JavaScript Reference

Method: removeEventListener()
The removeEventListener() method removes an event listener from the Window object.

Syntax
window.removeEventListener( type, listener, useCapture )

Parameters

Parameter Type Description

type String The type of event.
listener EventListener The event listener function to be removed.
useCapture boolean When true, indicates that the EventListener being removed was registered as a
capturing listener.
A listener may be registered twice, once as a capturing listener, and once as a non-
capturing listener. Each must be removed separately.

Return values
None.

Exceptions
None.

See also
Event, EventListener, Node.removeEventListener()

338
 JavaScript objects

Method: resizeBy()
The resizeBy() method resizes the viewport relative to the current window size.
To resize the viewport to an absolute size, use Window.resizeTo().

Syntax
window.resizeBy( deltaX, deltaY )

Parameter

Parameter Type Description

deltaX int The number of pixels to resize the window by horizontally.
deltaY int The number of pixels to resize the window by vertically.

Return values
None.

Exceptions
None.

See also
Window.resizeTo()

339
BlackBerry Browser JavaScript Reference

Method: resizeTo()
The resizeTo() method resizes the window to the specified width and height.

Syntax
window.resizeTo( width, height )

Parameter

Parameter Type Description

width int The new width of the viewport, in pixels.
height int The new height of the viewport, in pixels.

Return values
None.

Exceptions
None.

See also
Window.resizeBy()

340
 JavaScript objects

Method: scroll()
The scroll() method scrolls the content to a given set of coordinates. This method is functionally equivalent to
Window.scrollTo().

Syntax
window.scroll( x, y )

Parameter

Parameter Type Description

x int The position along the horizontal access, in pixels, to which to scroll the document.
y int The position along the vertical access, in pixels, to which to scroll the document.

Return values
None.

Exceptions
None.

See also
Window.scrollBy(), Window.scrollTo()

341
BlackBerry Browser JavaScript Reference

Method: scrollBy()
The scrollBy() method scrolls the content by the given number of pixels.

Syntax
window.scrollBy( deltaX, deltaY )

Parameter

Parameter Type Description

deltaX int The distance, in pixels, to scroll the document horizontally.
deltaY int The distance, in pixels, to scroll the document vertically.

Return values
None.

Exceptions
None.

See also
Window.scroll(), Window.scrollTo()

342
 JavaScript objects

Method: scrollTo()
The scrollTo() method scrolls the content to a given set of coordinates. This method is functionally equivalent to
Window.scroll().

Syntax
window.scrollTo( x, y )

Parameter

Parameter Type Description

x int The position along the horizontal access, in pixels, to which to scroll the document.
y int The position along the vertical access, in pixels, to which to scroll the document.

Return values
None.

Exceptions
None.

See also
Window.scroll(), Window.scrollBy()

343
BlackBerry Browser JavaScript Reference

Method: stop()
The stop() method stops the current download.
This method is equivalent to the user clicking the Stop item in the BlackBerry® Browser menu.

Syntax
window.stop()

Parameters
None.

Return values
None.

Exceptions
None.

344
 JavaScript objects

Object: XMLHttpRequest
Availability BlackBerry® Device Software version 4.6 and later

The XMLHttpRequest object enables you to transfer data to and from the server without reloading or replacing the
current document.
To make an HTTP request, you create the instance of the object, open a URL, and send the request. The HTTP
status code of the result, as well as the result document are available in the request object afterwards.
Because it allows you to communicate with a server in the background, the XMLHttpRequest object enables you to
create extremely dynamic documents.

Properties
Property name Type Description Status
onreadystatechange EventListener Specifies the event handler for asynchronous events. writable
readyState unsigned short Returns the status of the server's response. Each time the readyState changes, the read only
onreadystatechange function will be executed. This property may return the
following values:
• 0 = UNSENT: Represents the initial state of the object.
• 1 = OPENED: Indicates that XMLHttpRequest.open() has been successfully
invoked.
• 2 = HEADERS_RECEIVED: Indicates that all the response headers have been
received.
• 3 = LOADING: Indicates that the response entity body is being received.
• 4 = DONE: Indicates that the data transfer is complete, or that the transfer was
aborted due to an error. This state has an associated error flag which indicates
whether the response was successfully received.
responseText String Returns the response text entity body. This may return only a fragment of the entity read only
body, if the request response is still in the loading state.
responseXML String Returns the XML response entity body. This may return only a fragment of the entity read only
body, if the request response is still in the loading state.
status unsigned short Returns the HTTP status code sent by the server, or, if no status code is available, read only
throws an INVALID_STATE_ERR exception.
statusText String Returns the HTTP status text sent by the server, or, if no status text is available, read only
throws an INVALID_STATE_ERR exception.

Methods
Method name Description
abort() Stops the current request.
addEventListener() Adds an EventListener object to a set of event listeners for the given node.
dispatchEvent() Dispatches an Event object created by Document.createEvent().

345
BlackBerry Browser JavaScript Reference

Method name Description

getAllResponseHeaders()
getResponseHeader()
open()
removeEventListener()
send()
setRequestHeader()
Returns a complete set of headers and their values.
Returns the value of the given header.
Assigns the HTTP method and destination URL, as well as some additional optional parameters, for a
pending request.
Removes an event listener from an EventTarget.
Sends the request to the URL specified by open().
Specifies the value of a header to be sent with the request.

346
 JavaScript objects

Method: abort()
The abort() method stops the current request in progress.
When a request is aborted, the value for XMLHttpRequest.readyState is automatically set to DONE.

Syntax
XMLHttpRequest.abort()

Parameters
None.

Return values
None.

Exceptions
None.

347
BlackBerry Browser JavaScript Reference

Method: addEventListener()
The addEventListener() method adds an EventListener object to the XMLHttpRequest object.

Syntax
XMLHttpRequest.addEventListener( type, listener, useCapture )

Parameters

Parameter Type Description

type String The type of event to add.
listener EventListener The event listener function to be invoked.
useCapture boolean When true, indicates all events of the specified type to the registered EventListener
before being dispatched to any EventTargets beneath the given node in the tree.
Bubbling events will not trigger the EventListener.
When false, this method dispatches events of the specified type to the registered
EventListener before being dispatched to any EventTargets above the given node in the
tree.

Return values
None.

Exceptions
None.

See also
Event, EventListener

348
 JavaScript objects

Method: dispatchEvent()
The dispatchEvent() method dispatches an Event object created by Document.createEvent().

Syntax
XMLHttpRequest.dispatchEvent( event )

Parameters

Parameter Type Description

event Event The Event object to be dispatched.

Return values
Returns “true” if the Event object was successfully dispatched to the event handlers. If Event.preventDefault()
was called by any of the event listeners that handled the event, this method return “false”.

Exceptions

Exception Description
UNSPECIFIED_EVENT_TYPE_ERR This error is thrown if the event type was not specified by initializing the event before
calling dispatchEvent(), or if the event type was null.

349
BlackBerry Browser JavaScript Reference

Method: getAllResponseHeaders()
The getAllResponseHeaders() method returns a complete set of headers and their values.

Syntax
XMLHttpRequest.getAllResponseHeaders()

Parameters
None.

Return values
Returns all the response headers as a single string, with each header separated by a carriage return and line a
feed character.

Exceptions

Exception Description
INVALID_STATE_ERR This error is thrown if this method is called before any response headers have been
received (that is, before the XMLHttpRequest.readyState property has a value of 2,
indicating HEADERS_RECEIVED).

See also
XMLHttpRequest.getResponseHeader()

350
 JavaScript objects

Method: getResponseHeader()
The getResponseHeader() method returns the value of the given header.

Syntax
XMLHttpRequest.getResponseHeader( header )

Parameters

Parameter Type Description

header String The header to match on. This parameter is not case-sensitive.

Return values
Returns the value of the given header, or null if the header is not present in the header list. If header matches
more than one header in the list of response headers, the values are concatenated into a single comma-
separated list.

Exceptions

Exception Description
INVALID_STATE_ERR This error is thrown if this method is called before any response headers have been
received (that is, before the XMLHttpRequest.readyState property has a value of 2,
indicating HEADERS_RECEIVED).

See also
XMLHttpRequest.getAllResponseHeaders()

351
BlackBerry Browser JavaScript Reference

Method: open()
The open() method assigns the HTTP method and destination URL, as well as some additional optional
parameters, for a pending request.
When this method is successfully invoked, the value for XMLHttpRequest.readyState is set to OPENED.

Syntax
XMLHttpRequest.open( method, url [, async ] [, user ] [, password ] )

Parameters

Parameter Type Description

method String The HTTP method used to open the connection. This parameters may have one of the
following values:
• DELETE
• GET
• HEAD
• OPTIONS
• POST
• PUT
url String The destination URL of the request. The URL may be an absolute or a relative URL.
If you specify a relative URL, this method resolves the address by accessing the baseURI
attribute of the Document object reference that is created when the XMLHttpRequest
object is constructed.
async boolean Optional. When set to a value of “true”, this parameter indicates that the request is
asynchronous. If no value is specified, a value of “true” is set by default.
When set to a value of false, the request is synchronous. If a request is synchronous, no
other operations can be performed by the browser until the data has been received, or
the request aborted.
Because of the variability of network speed and connection availability in a wireless
environment, when the XMLHttpRequest object is used in conjunction with the
BlackBerry® Browser, requests should in almost all cases be made asynchronous.
user String Optional. Specifies a username if the server requires authentication. If this value is not
specified and the site requires authentication, the user will be prompted for their user
credentials.
password String Optional. Specifies a password if the server requires authentication.

Return values
None.

352
 JavaScript objects

Exceptions

Exception Description
NOT_SUPPORTED_ERR This error is thrown if url specifies an unsupported scheme.
SECURITY_ERR This error is thrown if:
• method is one of CONNECT, TRACE, TRACK
• url does not have the same origin as Window.document.
SYNTAX_ERR This error is thrown if:
• method does not match any known HTTP methods
• url cannot successfully be resolved
• user or password were specified but do not match the format expected by the
authentication method

See also
XMLHttpRequest.send()

353
BlackBerry Browser JavaScript Reference

Method: removeEventListener()
The removeEventListener() method removes an event listener from an EventTarget.

Syntax
XMLHttpRequest.removeEventListener( type, listener, useCapture )

Parameters

Parameter Type Description

type String The type of event.
listener EventListener The event listener function to be removed.
useCapture boolean When true, indicates that the EventListener being removed was registered as a
capturing listener.
A listener may be registered twice, once as a capturing listener, and once as a non-
capturing listener. Each must be removed separately.

Return values
None.

Exceptions
None.

See also
Event, EventListener

354
 JavaScript objects

Method: send()
The send() method sends the request to the URL specified by open(). If the request is asynchronous, this method is
returned as a callback when the response has been successfully received. The send() method must be called only
after the request has been opened using XMLHttpRequest.open().
This method can pass data to the server as either a string of text or as a Document object to the server.
If a value for the data argument is specified, it becomes the entity body for the request. In order for the server to
properly handle the data, you should specify the content type using XMLHttpRequest.setRequestHeader() before
invoking this method.
If data is not specified, no entity body is sent with the request.

Syntax
XMLHttpRequest.send( [data ] )

Parameters

Parameter Type Description

data String | Document Optional. The data to send to the server.
If data is not a string or a Document object, the BlackBerry® Browser attempts to
convert it into a string before passing it on to the server. If it is unable to do so, the
request is sent as if it had a null value.

Return values
If the request was asynchronous, this method returns the callback when the response has been successfully
received.

Exceptions

Exception Description
ABORT_ERR This error is thrown if the request cancelled by the user.
INVALID_STATE_ERR This error is thrown if this method is called before the request has been opened using
XMLHttpRequest.open().
NETWORK_ERR The error is thrown if there was a network error preventing the request from being
delivered to the destination URL, or if the destination URL is a redirection that violates
security, or would result in an infinite loop.

See also
XMLHttpRequest.open(), XMLHttpRequest.setRequestHeader()

355
BlackBerry Browser JavaScript Reference

Method: setRequestHeader()
The setRequestHeader() method specifies the value of a header to be sent with the request.
This method must be called only after the request has been opened using XMLHttpRequest.open().

Syntax
XMLHttpRequest.setRequestHeader( header, value )

Parameters

Parameter Type Description

header String The header to set.
This parameter may not have as its value any of the following: Accept-Charset, Accept-
Encoding, Connection, Content-Length, Content-Transfer-Encoding, Date, Expect, Host,
Keep-Alive, Proxy-{anyvalue}, Referer, Sec-{anyvalue}, TE, Trailer, Transfer-Encoding,
Upgrade, Via
value String The value of the header.

Return values
None.

Exceptions

Exception Description
ABORT_ERR This error is thrown if the request cancelled by the user.
INVALID_STATE_ERR This error is thrown if this method is called before the request has been opened using
XMLHttpRequest.open().
SYNTAX_ERR This error is thrown if
• header is not recognized as a valid header name.
• value is not recognized as a valid header value.

See also
XMLHttpRequest.send()

356
©2008 Research In Motion Limited
Published in Canada.