Post on 15-Nov-2014
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.
Published in 2008
Research In Motion Limited 295 Phillip Street Waterloo, ON N2L 3W8 Canada
Research In Motion UK Limited 200 Bath Road Slough, Berkshire SL1 3XE United Kingdom
ContentsJavaScript objects .............................................................................................................................................. 19
Attr .....................................................................................................................................................................19Properties ..................................................................................................................................................19
Blackberry ........................................................................................................................................................ 20Properties ................................................................................................................................................. 20
BlackberryLocation.......................................................................................................................................... 21Properties .................................................................................................................................................. 21Methods ..................................................................................................................................................... 21
onLocationUpdate()...................................................................................................................... 22refreshLocation()........................................................................................................................... 23removeLocationUpdate() ............................................................................................................. 24setAidMode() ................................................................................................................................. 25
CDATASection................................................................................................................................................. 26CharacterData..................................................................................................................................................27
Properties ..................................................................................................................................................27Methods .....................................................................................................................................................27
appendData()................................................................................................................................. 28deleteData()................................................................................................................................... 29insertData().................................................................................................................................... 30replaceData().................................................................................................................................. 31substringData() ............................................................................................................................. 32
Comment.......................................................................................................................................................... 33Counter............................................................................................................................................................. 34
Properties ................................................................................................................................................. 34CSSCharsetRule .............................................................................................................................................. 35
Properties ................................................................................................................................................. 35CSSFontFaceRule............................................................................................................................................ 36
Properties ................................................................................................................................................. 36CSSImportRule .................................................................................................................................................37
Properties ..................................................................................................................................................37CSSMediaRule................................................................................................................................................. 38
Properties ................................................................................................................................................. 38Methods .................................................................................................................................................... 38
deleteRule().................................................................................................................................... 39insertRule() ....................................................................................................................................40
CSSPageRule.................................................................................................................................................... 41
5
BlackBerry Browser JavaScript Reference
Properties .................................................................................................................................................. 41CSSPrimitiveValue.......................................................................................................................................... 42
Properties ................................................................................................................................................. 42Methods .................................................................................................................................................... 43
getCounterValue() ........................................................................................................................ 44getFloatValue().............................................................................................................................. 45getRectValue()...............................................................................................................................46getRGBColorValue() ..................................................................................................................... 47getStringValue()............................................................................................................................ 48setFloatValue() ..............................................................................................................................49setStringValue() ............................................................................................................................ 50
CSSRule............................................................................................................................................................. 51Properties .................................................................................................................................................. 51
CSSRuleList...................................................................................................................................................... 52Properties ................................................................................................................................................. 52Methods .................................................................................................................................................... 52
item()............................................................................................................................................... 53CSSStyleDeclaration ...................................................................................................................................... 54
Properties ................................................................................................................................................. 54Methods .................................................................................................................................................... 57
getPropertyCSSValue() ................................................................................................................ 58getPropertyPriority() ....................................................................................................................59getPropertyValue() .......................................................................................................................60item()................................................................................................................................................61removeProperty() .......................................................................................................................... 62setProperty() .................................................................................................................................. 63
CSSStyleRule ...................................................................................................................................................64Properties .................................................................................................................................................64
CSSStyleSheet.................................................................................................................................................65Properties .................................................................................................................................................65Methods ....................................................................................................................................................65
deleteRule()....................................................................................................................................66insertRule() .................................................................................................................................... 67
CSSUnknownRule...........................................................................................................................................68CSSValue..........................................................................................................................................................69
Properties .................................................................................................................................................69CSSValueList ................................................................................................................................................... 70
Properties ................................................................................................................................................. 70Methods .................................................................................................................................................... 70
item()................................................................................................................................................ 71
6
CustomEvent ....................................................................................................................................................72Properties ..................................................................................................................................................72Methods .....................................................................................................................................................72
initCustomEventNS().....................................................................................................................73Document......................................................................................................................................................... 74
Properties ................................................................................................................................................. 74Methods .................................................................................................................................................... 74
createAttribute() ........................................................................................................................... 76createAttributeNS() .......................................................................................................................77createCDATASection() ................................................................................................................. 78createComment() .......................................................................................................................... 79createDocumentFragment()........................................................................................................80createElement().............................................................................................................................. 81createElementNS() ....................................................................................................................... 82createEntityReference() ............................................................................................................... 83createEvent() ................................................................................................................................. 84createNodeIterator() .................................................................................................................... 85createProcessingInstruction().....................................................................................................86createTextNode() .......................................................................................................................... 87createTreeWalker() ....................................................................................................................... 88getElementById() ..........................................................................................................................89getElementsByTagName()...........................................................................................................90getElementsByTagNameNS() ......................................................................................................91getOverrideStyle() ........................................................................................................................ 92importNode() ................................................................................................................................. 93
DocumentFragment .......................................................................................................................................94DocumentType ................................................................................................................................................95
Properties .................................................................................................................................................95DOMException................................................................................................................................................96
Constants..................................................................................................................................................96DOMImplementation ..................................................................................................................................... 97
Methods .................................................................................................................................................... 97createCSSStyleSheet() .................................................................................................................98createDocument() .........................................................................................................................99createDocumentType() .............................................................................................................. 100hasFeature().................................................................................................................................. 101
Element ...........................................................................................................................................................102Properties ................................................................................................................................................102Methods ...................................................................................................................................................102
getAttribute()................................................................................................................................103
7
BlackBerry Browser JavaScript Reference
getAttributeNode() ..................................................................................................................... 104getAttributeNodeNS().................................................................................................................105getAttributeNS() ......................................................................................................................... 106getElementsByTagName()..........................................................................................................107getElementsByTagNameNS() ................................................................................................... 108hasAttribute() .............................................................................................................................. 109hasAttributeNS() .......................................................................................................................... 110removeAttribute().......................................................................................................................... 111removeAttributeNode()................................................................................................................112removeAttributeNS() ....................................................................................................................113setAttribute() .................................................................................................................................114setAttributeNode()........................................................................................................................115setAttributeNodeNS() ................................................................................................................. 116setAttributeNS()............................................................................................................................117
Entity.................................................................................................................................................................118Properties .................................................................................................................................................118
EntityReference.............................................................................................................................................. 119Event ................................................................................................................................................................120
Properties ................................................................................................................................................120Methods ...................................................................................................................................................120
initEvent().......................................................................................................................................121preventDefault()........................................................................................................................... 122stopPropagation() ........................................................................................................................ 123
EventException...............................................................................................................................................124Constants.................................................................................................................................................124
EventListener..................................................................................................................................................125Methods ...................................................................................................................................................125
handleEvent() ...............................................................................................................................126History ............................................................................................................................................................. 127
Properties ................................................................................................................................................ 127Methods ................................................................................................................................................... 127
back() .............................................................................................................................................128forward()........................................................................................................................................129go() .................................................................................................................................................130
HTMLAnchorElement .....................................................................................................................................131Properties .................................................................................................................................................131Methods ....................................................................................................................................................131
blur()............................................................................................................................................... 132focus() ............................................................................................................................................ 133
HTMLAppletElement .....................................................................................................................................134
8
Properties ................................................................................................................................................134HTMLAreaElement.........................................................................................................................................135
Properties ................................................................................................................................................135HTMLBaseElement ........................................................................................................................................136
Properties ................................................................................................................................................136HTMLBaseFontElement ................................................................................................................................ 137
Properties ................................................................................................................................................ 137HTMLBodyElement ........................................................................................................................................138
Properties ................................................................................................................................................138HTMLBRElement............................................................................................................................................139
Properties ................................................................................................................................................139HTMLButtonElement.................................................................................................................................... 140
Properties ............................................................................................................................................... 140HTMLCollection ..............................................................................................................................................141
Properties .................................................................................................................................................141Methods ....................................................................................................................................................141
item()..............................................................................................................................................142namedItem() .................................................................................................................................143
HTMLDirectoryElement ................................................................................................................................144Properties ................................................................................................................................................144
HTMLDivElement ...........................................................................................................................................145Properties ................................................................................................................................................145
HTMLDListElement....................................................................................................................................... 146Properties ............................................................................................................................................... 146
HTMLDocument ............................................................................................................................................. 147Properties ................................................................................................................................................ 147Event handlers ........................................................................................................................................148Methods ...................................................................................................................................................148
close() ........................................................................................................................................... 149getElementByName() ..................................................................................................................150open()..............................................................................................................................................151write().............................................................................................................................................152writeln() .........................................................................................................................................153
HTMLElement.................................................................................................................................................154Properties ................................................................................................................................................154Event handlers ........................................................................................................................................155
HTMLFieldsetElement.................................................................................................................................. 156Properties ............................................................................................................................................... 156
HTMLFontElement......................................................................................................................................... 157Properties ................................................................................................................................................ 157
9
BlackBerry Browser JavaScript Reference
HTMLFormElement........................................................................................................................................158Properties ................................................................................................................................................158Methods ...................................................................................................................................................158
reset()............................................................................................................................................ 159submit()......................................................................................................................................... 160
HTMLFrameElement...................................................................................................................................... 161Properties ................................................................................................................................................ 161
HTMLFrameSetElement................................................................................................................................162Properties ................................................................................................................................................162
HTMLHeadElement .......................................................................................................................................163Properties ................................................................................................................................................163
HTMLHeadingElement................................................................................................................................. 164Properties ............................................................................................................................................... 164
HTMLHRElement .......................................................................................................................................... 165Properties ............................................................................................................................................... 165
HTMLHtmlElement ....................................................................................................................................... 166Properties ............................................................................................................................................... 166
HTMLIFrameElement ....................................................................................................................................167Properties ................................................................................................................................................167
HTMLImageElement..................................................................................................................................... 168Properties ............................................................................................................................................... 168
HTMLInputElement ...................................................................................................................................... 169Properties ............................................................................................................................................... 169Methods ...................................................................................................................................................170
blur()................................................................................................................................................171click() ............................................................................................................................................. 172focus() ............................................................................................................................................ 173select() ........................................................................................................................................... 174
HTMLIsIndexElement .................................................................................................................................... 175HTMLLabelElement .......................................................................................................................................176
Properties ................................................................................................................................................176HTMLLegendElement.................................................................................................................................... 177
Properties ................................................................................................................................................ 177HTMLLIElement.............................................................................................................................................. 178
Properties ................................................................................................................................................ 178HTMLLinkElement .........................................................................................................................................179
Properties ................................................................................................................................................179HTMLMapElement ........................................................................................................................................ 180
Properties ............................................................................................................................................... 180HTMLMenuElement........................................................................................................................................181
10
Properties .................................................................................................................................................181HTMLMetaElement........................................................................................................................................182
Properties ................................................................................................................................................182HTMLModElement .........................................................................................................................................183
Properties ................................................................................................................................................183HTMLObjectElement.....................................................................................................................................184
Properties ................................................................................................................................................184HTMLOListElement .......................................................................................................................................185
Properties ................................................................................................................................................185HTMLOptGroupElement.............................................................................................................................. 186
Properties ............................................................................................................................................... 186HTMLOptionElement .................................................................................................................................... 187
Properties ................................................................................................................................................ 187HTMLOptionsCollection ...............................................................................................................................188
Properties ................................................................................................................................................188Methods ...................................................................................................................................................188
item()............................................................................................................................................. 189namedItem() ................................................................................................................................ 190
HTMLParagraphElement .............................................................................................................................. 191Properties ................................................................................................................................................ 191
HTMLParamElement .....................................................................................................................................192Properties ................................................................................................................................................192
HTMLPreElement...........................................................................................................................................193Properties ................................................................................................................................................193
HTMLQuoteElement..................................................................................................................................... 194Properties ............................................................................................................................................... 194
HTMLScriptElement ..................................................................................................................................... 195Properties ............................................................................................................................................... 195
HTMLSelectElement..................................................................................................................................... 196Properties ............................................................................................................................................... 196Methods .................................................................................................................................................. 196
add() ...............................................................................................................................................197blur().............................................................................................................................................. 198focus() ........................................................................................................................................... 199remove()........................................................................................................................................200
HTMLStyleElement ........................................................................................................................................201Properties ................................................................................................................................................201
HTMLTableCaptionElement ........................................................................................................................202Properties ...............................................................................................................................................202
HTMLTableCellElement ...............................................................................................................................203
11
BlackBerry Browser JavaScript Reference
Properties ...............................................................................................................................................203HTMLTableColElement ................................................................................................................................204
Properties ...............................................................................................................................................204HTMLTableElement ......................................................................................................................................205
Properties ...............................................................................................................................................205Methods ..................................................................................................................................................205
createCaption() ........................................................................................................................... 207createTFoot() ...............................................................................................................................208createTHead()..............................................................................................................................209deleteCaption() ............................................................................................................................210deleteRow()....................................................................................................................................211deleteTFoot()................................................................................................................................. 212deleteTHead()............................................................................................................................... 213insertRow()....................................................................................................................................214
HTMLTableRowElement................................................................................................................................215Properties ................................................................................................................................................215Methods ...................................................................................................................................................215
deleteCell()....................................................................................................................................216insertCell() .................................................................................................................................... 217
HTMLTableSectionElement..........................................................................................................................218Properties ................................................................................................................................................218Methods ...................................................................................................................................................218
deleteRow()...................................................................................................................................219insertRow()...................................................................................................................................220
HTMLTextAreaElement ................................................................................................................................. 221Properties ................................................................................................................................................ 221Methods ................................................................................................................................................... 221
blur().............................................................................................................................................. 222focus() ........................................................................................................................................... 223select() .......................................................................................................................................... 224
HTMLTitleElement ........................................................................................................................................ 225Properties ............................................................................................................................................... 225
HTMLUListElement.......................................................................................................................................226Properties ...............................................................................................................................................226
KeyboardEvent .............................................................................................................................................. 227Keyboard event types ........................................................................................................................... 227Properties ............................................................................................................................................... 227Methods .................................................................................................................................................. 228
getModifierState() ......................................................................................................................229initKeyboardEvent()....................................................................................................................230
12
initKeyboardEventNS() ............................................................................................................... 231Location.......................................................................................................................................................... 232
Properties ............................................................................................................................................... 232Methods .................................................................................................................................................. 232
assign() ......................................................................................................................................... 233reload() ......................................................................................................................................... 234replace() ....................................................................................................................................... 235toString() ......................................................................................................................................236
MediaList........................................................................................................................................................ 237Properties ............................................................................................................................................... 237Methods .................................................................................................................................................. 237
appendMedium()......................................................................................................................... 238deleteMedium() ...........................................................................................................................239item().............................................................................................................................................240
MimeType........................................................................................................................................................241Properties ................................................................................................................................................241
MimeTypeArray............................................................................................................................................. 242Properties ............................................................................................................................................... 242Methods .................................................................................................................................................. 242
item()............................................................................................................................................. 243namedItem() ................................................................................................................................244
MouseEvent ...................................................................................................................................................245Mouse event types ................................................................................................................................245Properties ...............................................................................................................................................246Methods ..................................................................................................................................................246
initMouseEvent() ......................................................................................................................... 247MutationEvent...............................................................................................................................................249
Mutation event types............................................................................................................................249Properties ...............................................................................................................................................250Methods ..................................................................................................................................................250
initMutationEvent() .....................................................................................................................251NamedFrameMap......................................................................................................................................... 252
Properties ............................................................................................................................................... 252Methods .................................................................................................................................................. 252
getNamedItem().......................................................................................................................... 253item().............................................................................................................................................254
NamedNodeMap ..........................................................................................................................................255Properties ...............................................................................................................................................255Methods ..................................................................................................................................................255
getNamedItem()..........................................................................................................................256
13
BlackBerry Browser JavaScript Reference
getNamedItemNS() .................................................................................................................... 257item().............................................................................................................................................258removeNamedItem() ..................................................................................................................259removeNamedItemNS() .............................................................................................................260setNamedItem() ...........................................................................................................................261setNamedItemNS().....................................................................................................................262
Navigator .......................................................................................................................................................263Properties ...............................................................................................................................................263Methods ..................................................................................................................................................263
javaEnabled() ...............................................................................................................................264Node ...............................................................................................................................................................265
Properties ...............................................................................................................................................265Methods ..................................................................................................................................................266
addEventListener()...................................................................................................................... 267appendChild()..............................................................................................................................268cloneNode() .................................................................................................................................269dispatchEvent() ........................................................................................................................... 270hasAttributes().............................................................................................................................. 271hasChildNodes() ......................................................................................................................... 272insertBefore()............................................................................................................................... 273isSupported() ............................................................................................................................... 274normalize() ................................................................................................................................... 275removeChild() .............................................................................................................................. 276removeEventListener() ............................................................................................................... 277replaceChild() .............................................................................................................................. 278
NodeFilter ......................................................................................................................................................279Methods .................................................................................................................................................. 279
acceptNode() ...............................................................................................................................280NodeIterator...................................................................................................................................................281
detach() ........................................................................................................................................ 283nextNode() ...................................................................................................................................284previousNode()............................................................................................................................285
NodeList .........................................................................................................................................................286item()............................................................................................................................................. 287
Notation .........................................................................................................................................................288Properties ...............................................................................................................................................288
Plugin..............................................................................................................................................................289Properties ...............................................................................................................................................289Methods ..................................................................................................................................................289
item().............................................................................................................................................290
14
namedItem() .................................................................................................................................291PluginArray....................................................................................................................................................292
Properties ...............................................................................................................................................292Methods ..................................................................................................................................................292
item().............................................................................................................................................293namedItem() ................................................................................................................................294
ProcessingInstruction ..................................................................................................................................295Properties ...............................................................................................................................................295
Rect .................................................................................................................................................................296Properties ...............................................................................................................................................296
RGBColor ....................................................................................................................................................... 297Properties ............................................................................................................................................... 297
Screen.............................................................................................................................................................298Properties ...............................................................................................................................................298
StyleSheet..................................................................................................................................................... 299Properties .............................................................................................................................................. 299
StyleSheetList................................................................................................................................................300Properties ...............................................................................................................................................300Methods ..................................................................................................................................................300
item()..............................................................................................................................................301Text .................................................................................................................................................................302
Methods ..................................................................................................................................................302splitText() .....................................................................................................................................303
TextEvent........................................................................................................................................................304Text event types.....................................................................................................................................304Properties ...............................................................................................................................................304Methods ..................................................................................................................................................304
initTextEvent() .............................................................................................................................305initTextEventNS()........................................................................................................................306
TreeWalker ..................................................................................................................................................... 307Properties ............................................................................................................................................... 307Methods ..................................................................................................................................................308
firstChild() ....................................................................................................................................309lastChild()......................................................................................................................................310nextNode() .....................................................................................................................................311nextSibling() .................................................................................................................................312parentNode() ................................................................................................................................313previousNode().............................................................................................................................314previousSibling() ..........................................................................................................................315
UIEvent............................................................................................................................................................316
15
BlackBerry Browser JavaScript Reference
User interface events.............................................................................................................................316Properties ................................................................................................................................................316Methods ...................................................................................................................................................316
initUIEvent() ................................................................................................................................. 317Window............................................................................................................................................................318
Properties ................................................................................................................................................318Event handlers ........................................................................................................................................319Methods ...................................................................................................................................................319
addEventListener().......................................................................................................................321alert() ............................................................................................................................................ 322back() ............................................................................................................................................ 323blur().............................................................................................................................................. 324close() ........................................................................................................................................... 325confirm() .......................................................................................................................................326dispatchEvent() ........................................................................................................................... 327find().............................................................................................................................................. 328focus() ...........................................................................................................................................329forward().......................................................................................................................................330getComputedStyle() ....................................................................................................................331home()........................................................................................................................................... 332moveBy()....................................................................................................................................... 333moveTo().......................................................................................................................................334open()............................................................................................................................................ 335print() ............................................................................................................................................336prompt()........................................................................................................................................ 337removeEventListener() ...............................................................................................................338resizeBy()......................................................................................................................................339resizeTo() ......................................................................................................................................340scroll() ............................................................................................................................................341scrollBy()....................................................................................................................................... 342scrollTo().......................................................................................................................................343stop() .............................................................................................................................................344
XMLHttpRequest ..........................................................................................................................................345Properties ...............................................................................................................................................345Methods ..................................................................................................................................................345
abort() ........................................................................................................................................... 347addEventListener()......................................................................................................................348dispatchEvent() ...........................................................................................................................349getAllResponseHeaders() ..........................................................................................................350getResponseHeader()..................................................................................................................351
16
open()............................................................................................................................................ 352removeEventListener() ...............................................................................................................354send() ............................................................................................................................................355setRequestHeader()....................................................................................................................356
17
JavaScript objects
Object: Attr
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
Availability BlackBerry® Device Software version 4.6 and later
Extends Node
Property name Type Description Status Availability
name String Returns the name of the attribute. The value of the name property must be unique across all attributes attached to the same Element node.
read only 4.6 and later
ownerElement Element Returns the element node that this attribute is attached to. If the attribute is not yet attached to an element, the value of this property is null.
read only 4.6 and later
specified boolean When true, this property indicates that the value for the attribute has been explicitly set.
If the attribute exists with a default value, this property has a value of false.
read only 4.6 and later
value String Specifies the value of the attribute. writable 4.6 and later
BlackBerry Browser JavaScript Reference
Object: Blackberry
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
Availability BlackBerry® Device Software version 4.0 and later
Property name Type Description Status Availability
location BlackberryLocation Returns a pointer to the BlackberryLocation object.
This property is available for BlackBerry Device Software Version 4.1 or later.
read only 4.1 and later
network String Returns the wireless network on which the BlackBerry device is 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
read only 4.0 and later
20
JavaScript objects
Object: BlackberryLocation
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
Methods
Availability BlackBerry® Device Software version 4.1 and later
Property name Type Description Status Availability
GPSSupported boolean When true, this property indicates that GPS positioning is supported by the BlackBerry device.
read only 4.1 and later
latitude double Returns the current latitude, in degrees, of the BlackBerry device. 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.
read only 4.1 and later
longitude double Returns the current longitude, in degrees, of the BlackBerry device. 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.
read only 4.1 and later
timestamp unsigned long
Returns time (in milliseconds since epoch) at which the BlackBerryLocation object was updated.
This property is only supported on BlackBerry devices running BlackBerry Device Software version 4.6 or later.
read only 4.6 and later
Method name Description Availability
onLocationUpdate() Registers a callback method that is called when the location is updated using BlackberryLocation.refreshLocation().
4.1 and later
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.
Syntaxblackberry.location.onLocationUpdate( callbackFunction | callbackString )
Parameters
Return values
None.
Exceptions
None.
See also
BlackberryLocation.refreshLocation(), BlackberryLocation.removeLocationUpdate()
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.
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.
Syntaxblackberry.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.
Syntaxblackberry.location.removeLocationUpdate( callbackFunction )
Parameters
Return values
None.
Exceptions
None.
See also
BlackberryLocation.onLocationUpdate(), BlackberryLocation.refreshLocation()
Parameter Type Description
callbackFunction Function A JavaScript function previously registered by BlackberryLocation.onLocationUpdate().
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.
Syntaxblackberry.location.setAidMode( int aidMode )
Parameters
Return values
None.
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.
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
25
BlackBerry Browser JavaScript Reference
Object: CDATASection
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.
Availability BlackBerry® Device Software version 4.6 and later
Extends Text
26
JavaScript objects
Object: CharacterData
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
Methods
Availability BlackBerry® Device Software version 4.6 and later
Extends Node
Extended by Comment, Text
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() method.
read only
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.
SyntaxCharacterData.appendData( arg )
Parameters
Return values
None.
Exceptions
Parameter Type Description
arg String The string to append.
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.
SyntaxCharacterData.deleteData( offset, count )
Parameters
Return values
None.
Exceptions
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.
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.
SyntaxCharacterData.insertData( offset, arg )
Parameters
Return values
None.
Exceptions
Parameter Type Description
offset int The offset position from which to start inserting.
arg String The string to insert.
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.
SyntaxCharacterData.replaceData( offset, count, arg )
Parameters
Return values
None.
Exceptions
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.
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.
SyntaxCharacterData.substringData( offset, count )
Parameters
Return values
Returns the specified range of data.
Exceptions
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.
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
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.
Availability BlackBerry® Device Software version 4.6 and later
Extends CharacterData
33
BlackBerry Browser JavaScript Reference
Object: Counter
The Counter interface is used to represent any counter or counters function value.
Properties
Availability BlackBerry® Device Software version 4.6 and later
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
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
Availability BlackBerry® Device Software version 4.6 and later
Extends CSSRule
Property name Type Description Status
encoding String The encoding used in the @charset rule. writable
35
BlackBerry Browser JavaScript Reference
Object: CSSFontFaceRule
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
Availability BlackBerry® Device Software version 4.6 and later
Extends CSSRule
Property name Type Description Status
style CSSStyleDeclaration The declaration block for this rule. read only
36
JavaScript objects
Object: CSSImportRule
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
Availability BlackBerry® Device Software version 4.6 and later
Extends CSSRule
Property name Type Description Status
href String The location of the style sheet to be imported. The attribute will not contain the “url(...)” specifier around the URI.
read only
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 style sheet.
read only
37
BlackBerry Browser JavaScript Reference
Object: CSSMediaRule
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
Methods
Availability BlackBerry® Device Software version 4.6 and later
Extends CSSRule
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
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.
SyntaxCSSMediaRule.deleteRule( index )
Parameters
Return values
None.
Exceptions
Parameter Type Description
index int The position of the rule to remove in the media block’s collection of rules.
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.
SyntaxCSSMediaRule.insertRule( rule, index )
Parameters
Return values
Returns the index position of the newly added rule.
Exceptions
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.
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
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
Availability BlackBerry® Device Software version 4.6 and later
Extends CSSRule
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
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
Availability BlackBerry® Device Software version 4.6 and later
Extends CSSValue
Property name Type Description Status
primitiveType unsigned short The property value type. The following constants represent the numerical 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.
read only
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.
SyntaxCSSPrimitiveValue.getCounterValue()
Parameters
None.
Return values
Returns a Counter object representing the value of a CSS_COUNTER.
Exceptions
See Also
Counter
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).
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.
SyntaxCSSPrimitiveValue.getFloatValue( unitType )
Parameters
Return values
Returns the float value in the given units.
Exceptions
See Also
CSSPrimitiveValue.setFloatValue()
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.
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.
45
BlackBerry Browser JavaScript Reference
Method: getRectValue()The getRectValue() method retrieves a Rect value.
SyntaxCSSPrimitiveValue.getRectValue()
Parameters
None.
Return values
Returns a Rect object representing the value of a CSS_RECT.
Exceptions
See Also
Rect
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).
46
JavaScript objects
Method: getRGBColorValue()The getRGBColorValue() method retrieves an RGBColor value.
SyntaxCSSPrimitiveValue.getRGBColorValue()
Parameters
None.
Return values
Returns an RGBColor object representing the value of a CSS_RGBCOLOR.
Exceptions
See Also
RGBColor
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).
47
BlackBerry Browser JavaScript Reference
Method: getStringValue()The getStringValue() method retrieves a string value. You can modify the value using the CSSPrimitiveValue.setStringValue() method.
SyntaxCSSPrimitiveValue.getStringValue()
Parameters
None.
Return values
Returns the value of a string.
Exceptions
See Also
CSSPrimitiveValue.setStringValue()
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).
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.
SyntaxCSSPrimitiveValue.setFloatValue( unitType, floatValue )
Parameters
Return values
None.
Exceptions
See Also
CSSPrimitiveValue.getFloatValue()
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.
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.
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.
SyntaxsetStringValue( unitType, stringValue )
Parameters
Return values
None.
Exceptions
See Also
CSSPrimitiveValue.getStringValue()
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.
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.
50
JavaScript objects
Object: CSSRule
The CSSRule object is the base class used to define any rule in a CSS Style sheet, including both rule sets and @ rules.
Properties
Availability BlackBerry® Device Software version 4.6 and later
Extended by CSSCharsetRule, CSSFontFaceRule, CSSImportRule, CSSMediaRule, CSSPageRule, CSSStyleRule, CSSUnknownRule
Property name Type Description Status
parentRule CSSRule The parent rule, if this rule is contained within another rule (for example, a style rule within an @media block).
read only
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 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.
read only
51
BlackBerry Browser JavaScript Reference
Object: CSSRuleList
The CSSRuleList object represents an ordered collection of CSSRule objects.
Properties
Methods
Availability BlackBerry® Device Software version 4.6 and later
Property name Type Description Status
length int The number of rules in the list. read only
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.
SyntaxCSSRuleList.item( index )
Parameters
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
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.
53
BlackBerry Browser JavaScript Reference
Object: CSSStyleDeclaration
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
Availability BlackBerry® Device Software version 4.6 and later
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
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 below the parent element.
writable
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 floating elements.
writable
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 content.
writable
counterIncrement String Specifies how much the counter is incremented for every occurrence of the element.
writable
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 merged.
writable
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 left edge of the parent element.
writable
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
Property name Type Description Status
55
BlackBerry Browser JavaScript Reference
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 available space for that element.
writable
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 content is spoken.
writable
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 right or left edge of the parent element.
writable
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
Property name Type Description Status
56
JavaScript objects
Methods
stress String Specifies the level of intonation of a voice. writable
tableLayout String Specifies whether the column width is fixed or determined by the width of the content.
writable
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 the parent element.
writable
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
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.
Property name Type Description Status
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()
SyntaxCSSStyleDeclaration.getPropertyCSSValue( propertyName )
Parameters
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.
Parameter Type Description
propertyName String The name of the CSS property for which to retrieve the value.
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.
SyntaxCSSStyleDeclaration.getPriorityProperty( propertyName )
Parameters
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.
Parameter Type Description
propertyName String The name of the CSS property for which to retrieve the priority.
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.
SyntaxCSSStyleDeclaration.getPropertyValue( propertyName )
Parameters
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.
Parameter Type Description
propertyName String The name of the CSS property for which to retrieve the value.
60
JavaScript objects
Method: item()The item() method returns the name of the CSS property at the specified index in the collection.
SyntaxCSSStyleDeclaration.item( index )
Parameters
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.
Parameter Type Description
index int An integer that represents the CSS property’s position in style declaration block.
61
BlackBerry Browser JavaScript Reference
Method: removeProperty()The removeProperty() method removes a CSS property from the style declaration block.
SyntaxCSSStyleDeclaration.removeProperty( propertyName )
Parameters
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
Parameter Type Description
propertyName String The name of the CSS property to remove.
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.
SyntaxCSSStyleDeclaration.setProperty( propertyName, value, priority )
Parameters
Return values
None.
Exceptions
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.
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
The CSSStyleRule object represents a single rule set in a CSS style sheet.
Properties
Availability BlackBerry® Device Software version 4.6 and later
Extends CSSRule
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
The CSSStyleSheet object represents a CSS style sheet.
Properties
Methods
Availability BlackBerry® Device Software version 4.6 and later
Extends StyleSheet
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 is not imported, the value for this property is null.
read only
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.
SyntaxCSSStyleSheet.deleteRule( index )
Parameters
Return values
None.
Exceptions
Parameter Type Description
index int An integer that represents the CSS rules’s position in the style sheet’s collection of rules.
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.
SyntaxCSSStyleSheet.insertRule( rule, index )
Parameters
Return values
Returns the position of the newly added style sheet in the style sheet’s collection of rules.
Exceptions
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.
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
The CSSUnknownRule represents an unsupported @ rule.
Availability BlackBerry® Device Software version 4.6 and later
Extends CSSRule
68
JavaScript objects
Object: CSSValue
The CSSValue object represents a simple or a complex CSS property value.
Properties
Availability BlackBerry® Device Software version 4.6 and later
Extended by CSSPrimitiveValue, CSSValueList
Property name Type Description Status
CSSValueType unsigned short The type of value. The following constants represent the numerical 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.
read only
69
BlackBerry Browser JavaScript Reference
Object: CSSValueList
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
Methods
Availability BlackBerry® Device Software version 4.6 and later
Extends CSSValue
Property name Type Description Status
length int The number of property values in the list. read only
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.
SyntaxCSSValueList.item( index )
Parameters
Return values
Returns the property value at the indexth position in CSSValueList, or null if an invalid index position is specified.
Exceptions
None.
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.
71
BlackBerry Browser JavaScript Reference
Object: CustomEvent
The CustomEvent object represents an unknown event type. This object is typically used for application-specific event types.
To create an instance of a CustomEvent, you must invoke Document.createEvent() with an input parameter of ”CustomEvent”.
Properties
Methods
Availability BlackBerry® Device Software version 4.6 and later
Extends Event
Property name Type Description Status
detail Object Specifies some detail information about the Event, depending on the type of event.
read only
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().
SyntaxCustomEvent.initCustomEvent( arg, canBubbleArg, cancelableArg, detailArg )
Parameters
Return values
None.
Exceptions
None.
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.
73
BlackBerry Browser JavaScript Reference
Object: Document
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
Methods
Availability BlackBerry® Device Software version 4.6 and later
Extends Node
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 points to the current active window.
read only
styleSheets StyleSheetList An array of all the style sheets in the document. read only
Method name Description
createAttribute() Creates a new attribute node with the given name.
createAttributeNS() Creates a new attribute object with the given qualified name and namespace URI.
createCDATASection() Creates a new CDATASection object, which represents a block of uninterpreted content.
createComment() Creates a new Comment object with the given text as content.
createDocumentFragment() Creates an empty DocumentFragment object.
createElement() Creates a new Element object of the specified type.
createElementNS() Creates a new Element object of the given qualified name and namespace URI.
createEntityReference() Creates a new EntityReference object with the given name.
createEvent() Creates a new Event object of the given type.
createNodeIterator() Creates a new NodeIterator object, which you can use to iterate through a set of Document nodes rooted at the given node.
createProcessingInstruction() Creates a new ProcessingInstruction object with the given name and data.
createTextNode() Creates a new text node containing the given text.
createTreeWalker() Creates a TreeWalker object, which you can use to traverse the specified document subtree.
getElementById() Returns the element node with the given ID value.
getElementsByTagName() Returns a NodeList object that contains an array of a document’s descendent element nodes with the specified tag name.
getElementsByTagNameNS() 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
getOverrideStyle() Retrieves the override CSSStyleDeclaration object for the given element.
importNode() Imports a node from a different document.
Method name Description
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().
SyntaxDocument.createAttribute( name )
Parameters
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
See also
Attr, Element.setAttribute(), Element.setAttributeNode()
Parameter Type Description
name String The name of the attribute to create.
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.
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().
SyntaxDocument.createAttribute( namespaceURI, qualifiedName )
Parameters
Return values
Returns the new attribute object with the following properties set:
Exceptions
See also
Attr, Element.setAttributeNode()
Parameter Type Description
namespaceURI String The namespace of the new attribute.
qualifiedName String The qualified name of the attribute to create.
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.
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.
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.
SyntaxDocument.createCDATASection( data )
Parameters
Return values
Returns the new CDATASection object.
Exceptions
See also
CDATASection
Parameter Type Description
data String The contents of the CDATASection node.
Exception Description
NOT_SUPPORTED_ERR This error is thrown if the document is an HTML document.
78
JavaScript objects
Method: createComment()The createComment() method creates a new Comment object with the given text as content.
SyntaxDocument.createComment( data )
Parameters
Return values
Returns the new Comment object.
Exceptions
None.
See also
Comment
Parameter Type Description
data String The contents of the Comment node.
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.
SyntaxDocument.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.
SyntaxDocument.createElement( tagName )
Parameters
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
See also
Attr, Element
Parameter Type Description
tagName String The type of element to create.
In an XML document, tagName is case-sensitive.
Exception Description
INVALID_CHARACTER_ERR This error is thrown if tagName contains an illegal character.
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.
SyntaxDocument.createElementNS( namespaceURI, qualifiedName )
Parameters
Return values
Returns the new Element object, with the following properties set:
Exceptions
See also
Attr, Element
Parameter Type Description
namespaceURI String The namespace of the new element.
qualifiedName String The qualified name of the element to create.
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.
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/”
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.
SyntaxDocument.createEntityReference( name )
Parameters
Return values
Returns the new EntityReference object.
Exceptions
See also
Entity, EntityReference
Parameter Type Description
name String The name of the entity to reference.
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.
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.
SyntaxDocument.createEvent( eventType )
Parameters
Return values
Returns the new Event object.
Exceptions
See also
Event
Parameter Type Description
eventType String The type of event to create.
Exception Description
NOT_SUPPORTED_ERR This error is thrown if the implementation does not support the specified Event interface.
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.
SyntaxDocument.createNodeIterator( root, whatToShow, filter, entityReferenceExpansion )
Parameters
Return values
Returns the new NodeIterator object.
Exceptions
See also
NodeIterator
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.
Exception Description
NOT_SUPPORTED_ERR This error is thrown if the specified root is null.
85
BlackBerry Browser JavaScript Reference
Method: createProcessingInstruction()The createProcessingInstruction() method creates a new ProcessingInstruction object with the given name and data.
SyntaxDocument.createProcessingInstruction( target,data )
Parameters
Return values
Returns the new ProcessingInstruction object.
Exceptions
See also
ProcessingInstruction
Parameter Type Description
target String The target of the processing instruction.
data String The data to store in the processing instruction.
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.
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.
SyntaxDocument.createTextNode( text )
Parameters
Return values
Returns the new Text object.
Exceptions
See also
Text
Parameter Type Description
text String The string of text that the Text node is to contain.
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.
87
BlackBerry Browser JavaScript Reference
Method: createTreeWalker()The createTreeWalker() method creates a TreeWalker object, which you can use to traverse the specified document subtree.
SyntaxDocument.createTreeWalker( root, whatToShow, filter, expandEntityReference )
Parameters
Return values
Returns the new TreeWalker object.
Exceptions
See also
TreeWalker
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.
Exception Description
NOT_SUPPORTED_ERR This error is thrown if the specified root is null.
88
JavaScript objects
Method: getElementById()The getElementById() method returns the Element node with the given ID value.
SyntaxDocument.getElementById( elementID )
Parameters
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
Parameter Type Description
elementID String The ID of the element to retrieve.
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.
SyntaxDocument.getElementsByTagName( tagName )
Parameters
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
Parameter Type Description
tagName String The name of the tag to match on. Specify a value of “*” to match all elements.
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.
SyntaxDocument.getElementsByTagNameNS( namespaceURI, localName )
Parameters
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
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.
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.
SyntaxDocument.getOverrideStyle( elt, pseudoElt )
Parameters
Return values
Returns the CSSStyleDeclaration object.
Exceptions
None.
See also
CSSStyleDeclaration
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.
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.
SyntaxDocument.importNode( importedNode, deep )
Parameters
Return values
Returns the imported node.
Exceptions
See also
Node.cloneNode()
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.
Exception Description
NOT_SUPPORTED_ERR This error is thrown if the node type being imported is not supported.
93
BlackBerry Browser JavaScript Reference
Object: DocumentFragment
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.
Availability BlackBerry® Device Software version 4.6 and later
Extends Node
94
JavaScript objects
Object: DocumentType
The DocumentType object represents the doctype for a document. If a document has a doctype, it will be a reference to this object.
Properties
Availability BlackBerry® Device Software version 4.6 and later
Extends Node
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 “]” characters.
read only
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
The DOMException object represents an error which prevents an operation from completing.
Constants
Availability BlackBerry® Device Software version 4.6 and later
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
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
Availability BlackBerry® Device Software version 4.6 and later
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.
SyntaxDOMImplementation.createCSSStyleSheet( title, media )
Parameters
Return values
Returns the new CSSStyleSheet object.
Exceptions
See also
CSSStyleSheet
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.
Exception Description
SYNTAX_ERR This error is thrown if media has a syntax error that prevents the browser from being able to parse it.
98
JavaScript objects
Method: createDocument()The createDocument() method creates a new XML or HTML Document object.
SyntaxDOMImplementation.createDocument( namespaceURI, qualifiedName, doctype )
Parameters
Return values
Returns the new Document object.
Exceptions
See also
Document
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.
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.
99
BlackBerry Browser JavaScript Reference
Method: createDocumentType()The createDocumentType() method creates an empty DocumentType node.
SyntaxDOMImplementation.createDocumentType( qualifiedName, publicId, systemId )
Parameters
Return values
Returns the new DocumentType object.
Exceptions
See also
DocumentType
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.
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/”
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().
SyntaxDOMImplementation.hasFeature( feature, version )
Parameters
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()
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.
101
BlackBerry Browser JavaScript Reference
Object: Element
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
Methods
Availability BlackBerry® Device Software version 4.6 and later
Extends Node
Extended by HTMLElement
Property name Type Description Status
tagName String The name of the element. read only
Method name Description
getAttribute() Retrieves the value of the attribute of the given name.
getAttributeNode() Retrieves the attribute node of the given name.
getAttributeNodeNS() Retrieves the attribute node with the given namespace URI and local name.
getAttributeNS() Retrieves the value of the attribute with the given namespace URI and local name.
getElementsByTagName() Returns a NodeList object that contains an array of an element’s descendent element nodes with the specified tag name.
getElementsByTagNameNS() Returns a NodeList object that contains an array of an element’s descendent element nodes with the given local name and namespace URI.
hasAttribute() Determines whether an attribute of the given name is specified on the element.
hasAttributeNS() Determines whether an attribute of the given namespace and local name is specified on the element.
removeAttribute() Removes the attribute of the given name from the element node.
removeAttributeNode() Removes the specified attribute node from the element node.
removeAttributeNS() Removes the attribute node with the given namespace URI and local name from the element node.
setAttribute() Adds a new attribute to an element, and sets it to the given value.
setAttributeNode() Adds a new attribute node to an element.
setAttributeNodeNS() Adds a new attribute node to an element.
setAttributeNS() 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.
SyntaxElement.getAttribute( name )
Parameters
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
Parameter Type Description
name String The name of the attribute for which to retrieve the value.
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.
SyntaxElement.getAttributeNode( name )
Parameters
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
Parameter Type Description
name String The name of the attribute node to retrieve.
104
JavaScript objects
Method: getAttributeNodeNS()The getAttributeNodeNS() method retrieves the Attr node with the given namespace URI and local name.
SyntaxElement.getAttributeNodeNS( namespaceURI, localName )
Parameters
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
See also
Attr
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.
Exception Description
NOT_SUPPORTED_ERR This error is thrown if the document does not support XML namespaces.
105
BlackBerry Browser JavaScript Reference
Method: getAttributeNS()The getAttribute() method retrieves the value of the Attr with the given namespace URI and local name.
SyntaxElement.getAttribute( namespaceURI, localName )
Parameters
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
See also
Attr
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.
Exception Description
NOT_SUPPORTED_ERR This error is thrown if the document does not support XML namespaces.
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.
SyntaxElement.getElementsByTagName( name )
Parameters
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()
Parameter Type Description
tagName String The name of the tag to match on. Specify a value of “*” to match all elements.
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.
SyntaxElement.getElementsByTagNameNS( namespaceURI, localName)
Parameters
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
See also
Document.getElementsByTagName(), Document.getElementsByTagNameNS(), Element.getElementsByTagName()
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.
Exception Description
NOT_SUPPORTED_ERR This error is thrown if the document does not support XML namespaces.
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.
SyntaxElement.hasAttribute( name )
Parameters
Return values
Returns:
• True, if the specified attribute exists on the element
• False, if the attribute does not exist
Exceptions
None.
Parameter Type Description
name String The name of the attribute to check.
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.
SyntaxElement.hasAttributeNS( namespaceURI, localName)
Parameters
Return values
Returns:
• True, if the specified attribute exists on the element
• False, if the attribute does not exist
Exceptions
Parameter Type Description
namespaceURI String The namespace of the attribute to check.
localName String The local name of the attribute to check.
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.
SyntaxElement.removeAttribute( name )
Parameters
Return values
None.
Exceptions
See also
Attr
Parameter Type Description
name String The name of the attribute node to remove.
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.
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.
SyntaxElement.removeAttributeNode( oldAttr )
Parameters
Return values
The removed Attr object.
Exceptions
See also
Attr
Parameter Type Description
oldAttr Attr The Attribute node to remove from the attribute list.
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.
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.
SyntaxElement.removeAttributeNS( namespaceURI, localName )
Parameters
Return values
None.
Exceptions
See also
Attr
Parameter Type Description
namespaceURI String The namespace of the attribute to retrieve.
localName String The local name of the attribute to retrieve.
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.
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().
SyntaxElement.getAttribute( name, value )
Parameters
Return values
None.
Exceptions
See also
Attr, Element.setAttributeNode(), Element.setAttributeNodeNS(), Element.setAttributeNS()
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.
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.
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.
SyntaxElement.setAttributeNode( newAttr )
Parameters
Return values
If newAttr replaces an existing attribute, this method returns the replaced Attr object; otherwise it returns null.
Exceptions
See also
Attr, Element.setAttribute(), Element.setAttributeNodeNS(), Element.setAttributeNS()
Parameter Type Description
newAttr Attr The node of the Attribute to add to the attribute list.
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.
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.
SyntaxElement.getAttributeNodeNS( newAttr )
Parameters
Return values
If newAttr replaces an existing attribute, this method returns the replaced Attr object; otherwise it returns null.
Exceptions
See also
Attr, Element.setAttribute(), Element.setAttributeNode(), Element.setAttributeNS()
Parameter Type Description
newAttr Attr The node of the Attribute to add to the attribute list.
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.
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().
SyntaxElement.setAttributeNS( namespaceURI, qualifiedName, value )
Parameters
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
See also
Attr, Element.setAttribute(), Element.setAttributeNode(), Element.setAttributeNodeNS()
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.
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.
117
BlackBerry Browser JavaScript Reference
Object: Entity
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
Availability BlackBerry® Device Software version 4.6 and later
Extends Node
Property name Type Description Status
notationName String For unparsed entities, the name of the notation for the entity. For parsed entities, the value of this property is null.
read only
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
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.
Availability BlackBerry® Device Software version 4.6 and later
Extends Node
119
BlackBerry Browser JavaScript Reference
Object: Event
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
Methods
Availability BlackBerry® Device Software version 4.6 and later
Extended by CustomEvent, MutationEvent, UIEvent
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:
• 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.
read only
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
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().
SyntaxEvent.initEvent( eventTypeArg, canBubbleArg, cancelableArg )
Parameters
Return values
None.
Exceptions
None.
See also
CustomEvent.initCustomEventNS(), KeyboardEvent.initKeyboardEvent(), MouseEvent.initMouseEvent(), MutationEvent.initMutationEvent(), TextEvent.initTextEvent(), UIEvent.initUIEvent()
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.
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.
SyntaxEvent.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.
SyntaxEvent.stopPropagation()
Parameters
None.
Return values
None.
Exceptions
None.
123
BlackBerry Browser JavaScript Reference
Object: EventException
The EventException object represents an error that occurs when initializing or dispatching an event.
Constants
Availability BlackBerry® Device Software version 4.6 and later
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
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
Availability BlackBerry® Device Software version 4.6 and later
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.
SyntaxEventListener.handleEvent( evt )
Parameters
Return values
None.
Exceptions
None.
Parameter Type Description
evt Event The event type that the EventListener is registered to listen for.
126
JavaScript objects
Object: History
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
Methods
Availability BlackBerry® Device Software version 4.2 and later
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
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).
Syntaxhistory.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).
Syntaxhistory.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.
Syntaxhistory.go( targetURLposition )
Parameters
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
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.
130
JavaScript objects
Object: HTMLAnchorElement
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
Methods
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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 the name of a standard character set.
writable
coords String Specifies a comma-separated list of the coordinates of HTMLAnchorElement.shape, which defines the active region in an image map.
writable
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 are specified by HTMLAnchorElement.coords.
writable
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
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.
SyntaxHTMLAnchorElement.blur()
Parameters
None.
Return values
None.
Exceptions
None.
132
JavaScript objects
Method: focus()The focus() method gives keypad focus to the element.
SyntaxHTMLAnchorElement.focus()
Parameters
None.
Return values
None.
Exceptions
None.
133
BlackBerry Browser JavaScript Reference
Object: HTMLAppletElement
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
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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 for the applet.
writable
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 provides the applet’s class name, but not the implementation. The class name is used to retrieve the implementation.
writable
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
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
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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, which defines the active region in an image map.
writable
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 are specified by HTMLAreaElement.coords.
writable
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
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
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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
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
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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 rendered.
writable
size String Specifies the size of the base font. writable
137
BlackBerry Browser JavaScript Reference
Object: HTMLBodyElement
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
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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
The HTMLBRElement object represents a <br> element in an HTML document.
The <br> element inserts a line break.
Properties
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
Property name Type Description Status
clear String Specifies the control flow of text around adjacent floats. writable
139
BlackBerry Browser JavaScript Reference
Object: HTMLButtonElement
The HTMLButtonElement object represents a <button> element in an HTML document.
The <button> element defines a button form control.
Properties
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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 pair that is submitted with the form.
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 may be “button”, “reset”, or “submit”.
read only
value String Specifies the current value of the form control. This is the value portion of the name-value pair that is submitted with the form.
writable
140
JavaScript objects
Object: HTMLCollection
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
Methods
Availability BlackBerry® Device Software version 4.6 and later
Property name Type Description Status
length int Returns the number of nodes in the list. read only
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.
SyntaxHTMLCollection.item( index )
Parameters
Return values
Returns the node at the indexth position in the HTMLCollection array, or null if an invalid index position is specified.
Exceptions
None.
Parameter Type Description
index int The index position of the node to be returned. Valid values are between 0 and HTMLCollection.length-1 inclusive.
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.
SyntaxHTMLCollection.namedItem( name )
Parameters
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.
Parameter Type Description
name String The name of the node to retrieve.
143
BlackBerry Browser JavaScript Reference
Object: HTMLDirectoryElement
The HTMLDirectoryElement object represents a <dir> element in an HTML document.
The <dir> element specifies that the enclosed text is a directory list.
Properties
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
Property name Type Description Status
compact boolean When true, indicates reduced spacing between list items. writable
144
JavaScript objects
Object: HTMLDivElement
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
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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
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
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
Property name Type Description Status
compact boolean When true, indicates reduced spacing between list items. writable
146
JavaScript objects
Object: HTMLDocument
The HTMLDocument object provides access to the HTML hierarchy.
Properties
Availability BlackBerry® Device Software version 4.6 and later
Extends Document
Property name Type Description Status
anchors HTMLCollection Returns an index of the <a> elements contained within the document. Index positions begin at 0 and continue to HTMLCollection.length-1.
read only
applets HTMLCollection Returns an index of the <applet> elements and <object> elements containing applets contained within the document. Index positions begin at 0 and continue to HTMLCol-lection.length-1.
read only
body HTMLElement Returns the element that contains the content of the document. In documents with <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.
writable
compatMode String Returns whether or not this document is rendered in strict mode. A value of “CSS1Compat” indicates strict mode is enforced. A value of “BackCompat” indicates that strict mode is not enforced.
read only
cookie String When the BlackBerry® Browser reads this property, it returns a semicolon-separated 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.
writable
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-tions begin at 0 and continue to HTMLCollection.length-1.
read only
images HTMLCollection Returns an index of the <img> elements contained within the document. Index posi-tions begin at 0 and continue to HTMLCollection.length-1.
read only
links HTMLCollection Returns an index of the <link> elements contained in the document. Index positions begin at 0 and continue to HTMLCollection.length-1.
read only
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
Methods
Property name Type Description Status
onblur EventListener Specifies the function to perform when an element loses focus by either the pointer or by tabbed navigation.
writable
onchange EventListener Specifies the function to perform when a form control loses focus after the user has modified the value.
writable
onclick EventListener Specifies the function to perform when the user clicks the trackball or trackwheel on a BlackBerry device.
writable
onfocus EventListener Specifies the function to perform when an element gains focus by either the pointer or by tabbed navigation.
writable
onkeydown EventListener Specifies the function to perform when a key is pressed down while the pointer is over an element.
writable
onkeypress EventListener Specifies the function to perform when a key is pressed and released while the pointer is over an element.
writable
onkeyup EventListener Specifies the function to perform when a key is released while the pointer is over an element.
writable
onmousedown EventListener Specifies the function to perform when the user depresses the trackwheel or trackball on a BlackBerry device.
writable
onmousemove EventListener Specifies the function to perform when the user moves the pointer while it is over an element.
writable
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 on a BlackBerry device.
writable
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
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.
SyntaxHTMLDocument.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.
SyntaxHTMLDocument.getElementsByName( elementName )
Parameters
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()
Parameter Type Description
elementName String The value of the name attribute of an element to match on.
150
JavaScript objects
Method: open()The open() method opens a document stream for writing.
SyntaxHTMLDocument.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().
SyntaxHTMLDocument.write( text )
Parameters
Return values
None.
Exceptions
None.
See also
HTMLDocument.open(), HTMLDocument.writeln()
Parameter Type Description
text String The text to be parsed.
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().
SyntaxHTMLDocument.writeln( text )
Parameters
Return values
None.
Exceptions
None.
See also
HTMLDocument.open(), HTMLDocument.write()
Parameter Type Description
text String The text to be parsed.
153
BlackBerry Browser JavaScript Reference
Object: HTMLElement
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
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
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 will be interpreted as part of the text string, not as HTML.
writable
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 of the containing element.
read only
offsetParent Node Returns the a reference to the nearest containing element that is positioned, from which all offsets are determined. If the element has a style.display set to none, this property returns null.
read only
offsetTop int Returns the number of pixels the top edge of the element is offset from the top edge of the containing element.
read only
offsetWidth int Returns the width of the element, in pixels. read only
154
JavaScript objects
Event handlers
style CSSStyleDeclaration Returns the contents of the style attribute that defines an inline style for an element.
read only
title String Returns the title attribute of an element. writable
Property name Type Description Status
onblur EventListener Specifies the function to perform when an element loses focus by either the pointer or by tabbed navigation.
writable
onchange EventListener Specifies the function to perform when a form control loses focus after the user has modified the value.
writable
onclick EventListener Specifies the function to perform when the user clicks the trackball or trackwheel on a BlackBerry® device.
writable
onfocus EventListener Specifies the function to perform when an element gains focus by either the pointer or by tabbed navigation.
writable
onkeydown EventListener Specifies the function to perform when a key is pressed down while the pointer is over an element.
writable
onkeypress EventListener Specifies the function to perform when a key is pressed and released while the pointer is over an element.
writable
onkeyup EventListener Specifies the function to perform when a key is released while the pointer is over an element.
writable
onload EventListener Specifies the function to perform when the BlackBerry® Browser finishes loading a new page or a complete frameset.
writable
onmousedown EventListener Specifies the function to perform when the user depresses the trackwheel or trackball on a BlackBerry device.
writable
onmousemove EventListener Specifies the function to perform when the user moves the pointer while it is over an element.
writable
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 on a BlackBerry device.
writable
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 or a frameset.
writable
Property name Type Description Status
155
BlackBerry Browser JavaScript Reference
Object: HTMLFieldsetElement
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
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
Property name Type Description Status
form HTMLFormElement Returns the parent <form> element for the form control. read only
156
JavaScript objects
Object: HTMLFontElement
The HTMLFontElement object represents a <font> element in an HTML document.
The <font> element specifies an inline font change.
Properties
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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
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
Methods
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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-tions begin at 0 and continue to HTMLCollection.length-1.
read only
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
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.
SyntaxHTMLFormElement.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.
SyntaxHTMLFormElement.submit()
Parameters
None.
Return values
None.
Exceptions
None.
160
JavaScript objects
Object: HTMLFrameElement
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
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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
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
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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
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
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
Property name Type Description Status
profile String Specifies the URLs that contain metadata about the document. writable
163
BlackBerry Browser JavaScript Reference
Object: HTMLHeadingElement
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
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
Property name Type Description Status
align String Specifies the horizontal alignment of the heading text. writable
164
JavaScript objects
Object: HTMLHRElement
The HTMLHRElement object represents an <hr> element in an HTML document.
The <hr> element renders a horizontal line.
Properties
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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
The HTMLHtmlElement object represents an <html> element in an HTML document.
The <html> element is the root element of an HTML document.
Properties
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
Property name Type Description Status
version String Specifies version information about the document DTD. writable
166
JavaScript objects
Object: HTMLIFrameElement
The HTMLIFrameElement object represents an <iframe> element in an HTML document.
The <iframe> element defines an inline frame.
Properties
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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
The HTMLImageElement object represents an <img> element in an HTML document.
The <img> element defines an image to display.
Properties
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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
The HTMLInputElement object represents an <input> element in an HTML document.
The <input> element defines a user input object.
Properties
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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 appears when an image is unavailable or cannot be displayed.
writable
checked boolean When HTMLInputElement.type has a value of ”checkbox” or ”radio” and this property is true, indicates that the check box or radio button appears selected, and its value is included when the form is submitted.
writable
defaultChecked boolean When HTMLInputElement.type has a value of ”checkbox” or ”radio” and this 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.
writable
defaultValue String When HTMLInputElement.type has a value of ”text”, “file”, or ”password”, specifies 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.
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
maxLength int When HTMLInputElement.type has a value of ”text” or ”password”, specifies the maximum number of characters permitted as input into the text field.
writable
name String Specifies the name of the form control. This is the name portion of the name-value pair that is submitted with the form.
writable
readonly boolean When HTMLInputElement.type has a value of ”text” or ”password” and this property is true, indicates that the form control cannot be modified by a user.
writable
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 source image.
writable
tabIndex int Specifies the element’s position in the tabbing order. writable
169
BlackBerry Browser JavaScript Reference
Methods
type String Specifies the type of form control this input element is. This property may have the 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.
writable
useMap String When HTMLInputElement.type has a value of “image”, specifies the client-side map to use with this image.
writable
value String Specifies the current value of the form control. This is the value portion of the name-value pair that is submitted with the form.
writable
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.
Property name Type Description Status
170
JavaScript objects
Method: blur()The blur() method removes keypad focus from the element.
SyntaxHTMLInputElement.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”.
SyntaxHTMLInputElement.click()
Parameters
None.
Return values
None.
Exceptions
None.
172
JavaScript objects
Method: focus()The focus() method gives keypad focus to the element.
SyntaxHTMLInputElement.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”.
SyntaxHTMLInputElement.select()
Parameters
None.
Return values
None.
Exceptions
None.
174
JavaScript objects
Object: HTMLIsIndexElement
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
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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
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
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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 value of the id attribute of the related element.
writable
176
JavaScript objects
Object: HTMLLegendElement
The HTMLLegendElement object represents a <legend> element in an HTML document.
The <legend> element specifies a caption for a <fieldset> element.
Properties
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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 <fieldset> element.
writable
form HTMLFormElement Returns the parent <form> element for the form control. read only
177
BlackBerry Browser JavaScript Reference
Object: HTMLLIElement
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
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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 in that list are numbered sequentially from this value.
writable
178
JavaScript objects
Object: HTMLLinkElement
The HTMLLinkElement object represents a <link> element in an HTML document.
The <link> element specifies an external reference to another document.
Properties
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
Property name Type Description Status
charset String Specifies the character encoding used in the referenced document; the value must be the name of a standard character set.
writable
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 example, “stylesheet”.
writable
rev String Describes a link relationship from the referenced target document to the source document.
writable
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 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.
writable
type String Specifies the MIME type of the target document. writable
179
BlackBerry Browser JavaScript Reference
Object: HTMLMapElement
The HTMLMapElement object represents a <map> element in an HTML document.
The <map> element creates a client-side image map.
Properties
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
Property name Type Description Status
areas HTMLCollection Returns an index of the active regions contained within the map. Index positions begin at 0 and continue to HTMLCollection.length-1.
read only
name String Specifies a unique name for the image map. The value must match the corresponding value for the usemap attribute in the <img> element in which it is referenced.
writable
180
JavaScript objects
Object: HTMLMenuElement
The HTMLMenuElement object represents a <menu> element in an HTML document.
The <menu> element denotes that the enclosed text is a menu list.
Properties
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
Property name Type Description Status
compact boolean When true, indicates reduced spacing between list items. writable
181
BlackBerry Browser JavaScript Reference
Object: HTMLMetaElement
The HTMLMetaElement object represents a <meta> element in an HTML document.
The <meta> element provides additional information about the document.
Properties
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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
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
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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
The HTMLObjectElement object represents an <object> element in an HTML document.
The <object> element specifies an embedded object.
Properties
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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 for the object.
writable
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 document, this property returns null.
read only
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, this property returns null.
read only
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 object.
writable
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 image.
writable
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
The HTMLOListElement object represents an <ol> element in an HTML document.
The <ol> element specifies an ordered, or numbered, list.
Properties
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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
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
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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
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
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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 form, this property returns null.
read only
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 submitted.
writable
187
BlackBerry Browser JavaScript Reference
Object: HTMLOptionsCollection
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
Methods
Availability BlackBerry® Device Software version 4.6 and later
Property name Type Description Status
length int Returns the number of HTMLOptionElement objects contained in the list. read only
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.
SyntaxHTMLOptionsCollection.item( index )
Parameters
Return values
Returns the node at the indexth position in the HTMLCollection array, or null if an invalid index position is specified.
Exceptions
None.
Parameter Type Description
index int The index position of the node to be returned. Valid values are between 0 and HTMLCollection.length-1 inclusive.
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.
SyntaxHTMLOptionsCollection.namedItem( name )
Parameters
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.
Parameter Type Description
name String The name of the node to retrieve.
190
JavaScript objects
Object: HTMLParagraphElement
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
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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
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
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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 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.
writable
192
JavaScript objects
Object: HTMLPreElement
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
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
Property name Type Description Status
width int Specifies the width of the content block. writable
193
BlackBerry Browser JavaScript Reference
Object: HTMLQuoteElement
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
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
Property name Type Description Status
cite String Specifies a URL citation to indicate the source of the quotation writable
194
JavaScript objects
Object: HTMLScriptElement
The HTMLScriptElement object represents a <script> element in an HTML document.
The <script> element defines a script.
Properties
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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 the BlackBerry® Browser can therefore defer processing the script.
writable
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
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
Methods
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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 contained by a form, this property returns null.
read only
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-value pair that is submitted with the form.
writable
options HTMLOptionsCollection Returns an index of the <option> elements contained within the selection list. Index positions begin at 0 and continue to HTMLOptionsCollection.length-1.
read only
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 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”.
read only
value String Specifies the value of the currently selected option(s). This is the value portion of the name-value pair that is submitted with the form.
writable
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().
SyntaxHTMLSelectElement.add( element, before )
Parameters
Return values
None.
Exceptions
See also
Node.appendChild(), Node.insertBefore()
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.
Exception Description
NOT_FOUND_ERR This error is thrown if before is not a child of the <select> element.
197
BlackBerry Browser JavaScript Reference
Method: blur()The blur() method removes keypad focus from the element.
SyntaxHTMLSelectElement.blur()
Parameters
None.
Return values
None.
Exceptions
None.
198
JavaScript objects
Method: focus()The focus() method gives keypad focus to the element.
SyntaxHTMLSelectElement.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.
SyntaxHTMLSelectElement.remove( index )
Parameters
Return values
None.
Exceptions
None.
Parameter Type Description
index int The position in the HTMLSelectElement.options index of the element to remove from the selection list.
200
JavaScript objects
Object: HTMLStyleElement
The HTMLStyleElement object represents a <style> element in an HTML document.
The <style> element defines an internal style sheet.
Properties
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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
The HTMLTableCaptionElement object represents a <caption> element in an HTML document.
The <caption> element provides a description for a table.
Properties
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
Property name Type Description Status
align String Specifies the horizontal alignment of the table caption. writable
202
JavaScript objects
Object: HTMLTableCellElement
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
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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 array.
read only
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-ter.
writable
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, row, or row 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
203
BlackBerry Browser JavaScript Reference
Object: HTMLTableColElement
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
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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-cent character.
writable
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
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
Methods
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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.
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.
writable
cellPadding String Specifies the amount of white space, in pixels, to add between cell content and its borders.
writable
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.
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.
writable
tHead HTMLTableSectionElement Specifies a pointer to the <thead> element for the table.
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.
writable
width String Specifies the width of the table, in pixels, or as a percentage of the Black-Berry® Browser window.
writable
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
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.
Method name Description
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.
SyntaxHTMLTableElement.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.
SyntaxHTMLTableElement.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.
SyntaxHTMLTableElement.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.
SyntaxHTMLTableElement.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.
SyntaxHTMLTableElement.deleteRow( index )
Parameters
Return values
None.
Exceptions
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.
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.
SyntaxHTMLTableElement.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.
SyntaxHTMLTableELement.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().
SyntaxHTMLTableElement.insertRow( index )
Parameters
Return values
Returns the newly added row.
Exceptions
See Also
HTMLTableRowElement.insertCell()
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.
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.
214
JavaScript objects
Object: HTMLTableRowElement
The HTMLTableRowElement object represents a <tr> element in an HTML document.
The <tr> element specifies a table row.
Properties
Methods
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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-jacent character.
writable
rowIndex int Returns the index position of the row in the parent table’s HTMLTableElement.rows ar-ray.
read only
sectionRowIndex int Returns the index position of the row in the parent table section’s HTMLTableSection-Element.rows array.
read only
vAlign String Specifies the vertical alignment of the content within the table cell. writable
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.
SyntaxHTMLTableRowElement.deleteCell( index )
Parameters
Return values
None.
Exceptions
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.
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.
SyntaxHTMLTableRowElement.insertCell( index )
Parameters
Return values
Returns the newly added table cell.
Exceptions
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.
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
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
Methods
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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-jacent character.
writable
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
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.
SyntaxHTMLTableSectionElement.deleteRow( index )
Parameters
Return values
None.
Exceptions
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.
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().
SyntaxHTMLTableSectionElement.insertRow( index )
Parameters
Return values
Returns the newly added row.
Exceptions
See Also
HTMLTableRowElement.insertCell()
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.
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.
220
JavaScript objects
Object: HTMLTextAreaElement
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
Methods
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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 change if the contents of the text area control within the form changes.
writable
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 pair that is submitted with the form.
writable
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 name-value pair that is submitted with the form.
writable
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.
SyntaxHTMLTextAreaElement.blur()
Parameters
None.
Return values
None.
Exceptions
None.
222
JavaScript objects
Method: focus()The focus() method gives keypad focus to the element.
SyntaxHTMLTextAreaElement.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.
SyntaxHTMLTextAreaElement.select()
Parameters
None.
Return values
None.
Exceptions
None.
224
JavaScript objects
Object: HTMLTitleElement
The HTMLTitleElement object provides access to <title> elements within an HTML document.
The <title> element provides a descriptive title for the document.
Properties
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
Property name Type Description Status
text String Specifies the title of the HTML document. writable
225
BlackBerry Browser JavaScript Reference
Object: HTMLUListElement
The HTMLUListElement object provides access to <ul> elements within an HTML document.
The <ul> element specifies an unordered, or bulleted, list.
Properties
Availability BlackBerry® Device Software version 4.6 and later
Extends HTMLElement
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
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
Properties
Availability BlackBerry® Device Software version 4.6 and later
Extends UIEvent
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
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 Description
getModifierState() Checks the state of a modifier key.
initKeyboardEvent() Initializes the value of a KeyboardEvent.
initKeyboardEventNS() 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.
SyntaxKeyboardEvent.getModifierState( keyIdentifierArg )
Parameters
Return values
Returns “true” if the modifier key specified by keyIdentifierArg is activated; otherwise, returns false.
Exceptions
None.
Parameter Type Description
keyIdentifierArg String Specifies a modifier key identifier, such as ALT.
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.
SyntaxKeyboardEvent.initKeyboardEvent( typeArg, canBubbleArg, cancelableArg, viewArg,
keyIdentifierArg, keyLocationArg, modifiersList )
Parameters
Return values
None.
Exceptions
None.
See also
KeyboardEvent.initKeyboardEventNS()
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.
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.
SyntaxKeyboardEvent.initKeyboardEventNS( namespaceURI, typeArg, canBubbleArg, cancelableArg,
viewArg, keyIdentifierArg, keyLocationArg, modifiersList )
Parameters
Return values
None.
Exceptions
None.
See also
KeyboardEvent.initKeyboardEvent()
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.
231
BlackBerry Browser JavaScript Reference
Object: Location
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
Methods
Availability BlackBerry® Device Software version 4.6 and later
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
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.
Syntaxlocation.assign( URL )
Parameters
Return values
None.
Exceptions
None.
See also
Location.replace()
Parameter Type Description
URL String The URL to load.
233
BlackBerry Browser JavaScript Reference
Method: reload()The reload() method reloads the current web page.
Syntaxlocation.reload( forceGet )
Parameters
Return values
None.
Exceptions
None.
See also
Location.assign()
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.
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.
Syntaxlocation.replace( URL )
Parameters
Return values
None.
Exceptions
None.
See also
Location.assign()
Parameter Type Description
URL String The URL to replace the current URL with.
235
BlackBerry Browser JavaScript Reference
Method: toString()The toString() method returns the URL of the web page as a string.
Syntaxlocation.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
The MediaList object represents an ordered collection of media. An empty list is equivalent to a list that contains a value of “all”.
Properties
Methods
Availability BlackBerry® Device Software version 4.6 and later
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.
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.
writable
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.
SyntaxMediaList.appendMedium( newMedium )
Parameters
Return values
None.
Exceptions
See also
MediaList.deleteMedium()
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.
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.
238
JavaScript objects
Method: deleteMedium()The deleteMedium() method removes the given medium from the MediaList object.
SyntaxMediaList.deleteMedium( oldMedium )
Parameters
Return values
None.
Exceptions
See also
MediaList.appendMedium()
Parameter Type Description
oldMedium String The medium to remove from MediaList.
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.
239
BlackBerry Browser JavaScript Reference
Method: item()The item() method returns the medium at the given index in the collection.
SyntaxMediaList.item( index )
Parameters
Return values
Returns the medium at the indexth position in MediaList, or null if an invalid index position is specified.
Exceptions
None.
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.
240
JavaScript objects
Object: MimeType
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
Availability BlackBerry® Device Software version 4.6 and later
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 formatted according to the MIME type.
read only
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
The MimeTypeArray object contains an ordered collection of MIME types.
Properties
Methods
Availability BlackBerry® Device Software version 4.6 and later
Property name Type Description Status
length int Returns the number of MIME types in the list. read only
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.
SyntaxMimeTypeArray.item( index )
Parameters
Return values
Returns the node at the indexth position in MimeTypeArray, or null if an invalid index position is specified.
Exceptions
None.
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.
243
BlackBerry Browser JavaScript Reference
Method: namedItem()The namedItem() method retrieves the MIME type with the given name from the collection.
SyntaxMimeTypeArray.namedItem( name )
Parameters
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.
Parameter Type Description
name String The name of the MIME type to retrieve.
244
JavaScript objects
Object: MouseEvent
The MouseEvent object extends the UIEvent object and represents an event generated by the BlackBerry® device trackball or trackwheel. It provides contextual information associated with clicking the trackball or trackwheel and moving the pointer in the BlackBerry® Browser window.
To create an instance of a MouseEvent, you must invoke Document.createEvent() with an input parameter of ”MouseEvent”.
Mouse event types
Availability BlackBerry® Device Software version 4.6 and later
Extends UIEvent
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
Properties
Methods
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
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 devices have a single button (the trackball or trackwheel), this parameter will always return a value of “0”.
read only
clientX int Returns the horizontal coordinate within the BlackBerry Browser window where the event occurred.
read only
clientY int Returns the vertical coordinate within the BlackBerry Browser window where the event occurred.
read only
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 occurred.
read only
screenY int Returns the vertical coordinate on the BlackBerry device screen where the event occurred.
read only
shiftKey boolean Returns “true” if the SHIFT key is pressed. read only
Method name Description
initMouseEvent() Initializes the value of a MouseEvent.
Event type Bubbles Cancelable Description
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.
SyntaxMouseEvent.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
JavaScript objects
Object: MutationEvent
The MutationEvent object extends the Event object and represents an event generated when the structure of document is modified. To create an instance of a MutationEvent, you must invoke Document.createEvent() with an input parameter of ”MutationEvent”.
Mutation event types
Availability BlackBerry® Device Software version 4.6 and later
Extends Event
Event type Bubbles Cancelable Description
DOMAttrModified 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
DOMCharacterDataModified yes no Occurs when CharacterData.data or ProcessingInstruction.data have been modified on a node. The EventTarget is the CharacterData node or ProcessingInstruction node.
This event type includes the following context information:
MutationEvent.newValue, MutationEvent.prevValue
DOMContentLoaded no no Occurs when the BlackBerry® Browser has completely parsed the document, before any onload events are triggered.
DOMNodeInserted yes no Occurs when a node has been added as a child of another node, or if an Attr node has been added to an Element node.
This event type includes the following context information:
MutationEvent.relatedNode holds the parent node of the parent node of the node being added.
DOMNodeInsertedIntoDocument yes no Occurs when a node has been inserted into the document, either directly or as part of a subtree.
DOMNodeRemoved yes no Occurs when a node has been removed from another node, or if an Attr node has been removed from its Element node.
This event type includes the following context information:
MutationEvent.relatedNode holds the parent node of the parent node of the node being removed.
DOMNodeRemovedFromDocument yes no Occurs when a node has been removed from the document, either directly or as part of a subtree.
DOMSubtreeModified yes no Occurs when any modification has been made to the document, encompassing all other Mutation event types.
249
BlackBerry Browser JavaScript Reference
Properties
Methods
Property name Type Description Status
attrChange unsigned short Returns the type of change that triggered the DOMAttrModified event. This property can return one of the following values:
• 1 = MODIFICATION: An existing Attr object was modified in place.
• 2 = ADDITION: A new Attr object was added to the DOM.
• 3 = REMOVAL: An Attr object was removed from the DOM.
read only
attrName String Returns the name of the changed Attr node in a DOMAttrModified event. read only
newValue String Returns the new value of:
• the Attr node in a DOMAttrModified event
• the CharacterData node in a DOMCharacterDataModified event
read only
prevValue String Returns the previous value of:
• the Attr node in a DOMAttrModified event
• the CharacterData node in a DOMCharacterDataModified event
read only
relatedNode Node Returns the secondary node affected by a mutation event. read only
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.
SyntaxMutationEvent.initMutationEvent( typeArg, canBubbleArg, cancelableArg, relatedNodeArg,
prevValueArg, newValueArg, attrNameArg, attrChangeArg )
Parameters
Return values
None.
Exceptions
None.
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.
251
BlackBerry Browser JavaScript Reference
Object: NamedFrameMap
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
Methods
Availability BlackBerry® Device Software version 4.6 and later
Property name Type Description Status
length unsigned long Returns the number of nodes in the map. read only
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.
SyntaxNamedFrameMap.getNamedItem( name )
Parameters
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.
Parameter Type Description
name String The value of the Node.nodeName property of the frame to retrieve.
253
BlackBerry Browser JavaScript Reference
Method: item()The item() method returns the frame at the specified index in the map.
SyntaxNamedFrameMap.item( index )
Parameters
Return values
Returns the frame at the indexth position in NamedFrameMap, or null if an invalid index position is specified.
Exceptions
None.
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.
254
JavaScript objects
Object: NamedNodeMap
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
Methods
Availability BlackBerry® Device Software version 4.6 and later
Property name Type Description Status
length unsigned long Returns the number of nodes in the map. read only
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.
SyntaxNamedNodeMap.getNamedItem( name )
Parameters
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()
Parameter Type Description
name String The value of the Node.nodeName property of the node to retrieve.
256
JavaScript objects
Method: getNamedItemNS()The getNamedItemNS() method retrieves the node with the specified name and namespace URI.
SyntaxNamedNodeMap.getNamedItemNS( namespaceURI, localName )
Parameters
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
See also
NamedNodeMap.getNamedItem()
Parameter Type Description
namespaceURI String The namespace of the node to retrieve.
localName String The local name of the node to retrieve.
Exception Description
NOT_SUPPORTED_ERR This error is thrown if the document does not support XML namespaces.
257
BlackBerry Browser JavaScript Reference
Method: item()The item() method returns the node at the specified index in the map.
SyntaxnodeMap.item( index )
Parameters
Return values
Returns the node at the indexth position in NamedNodeMap, or null if an invalid index position is specified.
Exceptions
None.
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.
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.
SyntaxNamedNodeMap.removeNamedItem( name )
Parameters
Return values
Returns the removed Node object, if it exists.
Exceptions
Parameter Type Description
name String The value of Node.nodeName property of the node to remove.
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.
SyntaxNamedNodeMap.removeNamedItemNS( namespaceURI, localName )
Parameters
Return values
Returns the removed node object, if it exists.
Exceptions
Parameter Type Description
namespaceURI String The namespace of the node to remove.
localName String The local name of the node to remove.
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.
SyntaxNamedNodeMap.setNamedItem( arg )
Parameters
Return values
If the new node has replaced an existing node, returns the removed node; otherwise returns null.
Exceptions
Parameter Type Description
arg Node The node to add to the map.
Exception Description
HIERARCHY_REQUEST_ERR 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.
INUSE_ATTRIBUTE_ERR 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.
NO_MODIFICATION_ALLOWED_ERR This error is thrown if the NamedNodeMap object is read only.
WRONG_DOCUMENT_ERR 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.
SyntaxNamedNodeMap.setNamedItemNS( arg )
Parameters
Return values
If the new node has replaced an existing node, returns the removed node; otherwise returns null.
Exceptions
Parameter Type Description
arg Node The node to add to the map.
Exception Description
HIERARCHY_REQUEST_ERR 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.
INUSE_ATTRIBUTE_ERR 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.
NO_MODIFICATION_ALLOWED_ERR This error is thrown if the NamedNodeMap 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 arg was created from a different document than the one the created this NamedNodeMap object.
262
JavaScript objects
Object: Navigator
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
Methods
Availability BlackBerry® Device Software version 4.0 and later
Property name Type Description Status
appCodeName String Returns the code name of the browser. The value is typically “BlackBerry”, but may be different if the user has selected an emulation mode other than BlackBerry.
read only
appName String Returns the name of the browser. In the case of the BlackBerry Browser, the value is always “BlackBerry”.
read only
appVersion String Returns the version of the BlackBerry Device Software that is running on the BlackBerry device (for example, “4.6.0”).
read only
buildID String Returns the build identifier of the version of the BlackBerry Device Software running on the device.
read only
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 default language translation of the BlackBerry Browser.
read only
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 is used by servers to identify the client browser.
read only
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.
Syntaxnavigator.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
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
Availability BlackBerry® Device Software version 4.6 and later
Extended By Attr, CharacterData, Document, DocumentFragment, DocumentType, Element, Entity, EntityReference, Notation, ProcessingInstruction
Property name Type Description Status
attributes NamedNodeMap Returns a NamedNodeMap object that contains the attributes of the given element node, or null, if the node is not an element.
read only
childNodes NodeList Returns a NodeList object that contains all the child elements of the given node.
read only
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.
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.
writable
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
Methods
prefix String Specifies the prefix, extracted from the qualified name of the given node, or 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.
writable
previousSibling Node Returns the node immediately preceding the current node. read only
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.
Property name Type Description Status
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
Return values
None.
Exceptions
None.
See also
Event, EventListener
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.
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.
SyntaxNode.appendChild( newChild )
Parameters
Return values
Returns the added node.
Exceptions
See also
Node.insertBefore(), Node.removeChild(), Node.replaceChild()
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.
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.
WRONG_DOCUMENT_ERR This error is thrown if newChild was created from a different document than the given node.
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.
SyntaxNode.cloneNode( deep )
Parameters
Return values
Returns the duplicate node.
Exceptions
None.
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.
269
BlackBerry Browser JavaScript Reference
Method: dispatchEvent()The dispatchEvent() method dispatches an Event object created by Document.createEvent().
SyntaxNode.dispatchEvent( event )
Parameters
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
See also
Document.createEvent(), CustomEvent.initCustomEventNS(), Event.initEvent(), KeyboardEvent.initKeyboardEvent(), MouseEvent.initMouseEvent(), MutationEvent.initMutationEvent(), TextEvent.initTextEvent(), UIEvent.initUIEvent()
Parameter Type Description
event Event The Event object to be dispatched.
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.
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.
SyntaxNode.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.
SyntaxNode.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.
SyntaxNode.insertBefore( newChild, refChild )
Parameters
Return values
Returns the inserted node.
Exceptions
See also
Node.appendChild(), Node.removeChild(), Node.replaceChild()
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.
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.
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.
SyntaxNode.isSupported( feature, version )
Parameters
Return values
Returns “true” if the specified version of the specified feature is supported; otherwise, returns “false”.
Exceptions
None.
See also
DOMImplementation.hasFeature()
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.
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.
SyntaxNode.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.
SyntaxNode.removeChild( oldChild )
Parameters
Return values
Returns the removed node.
Exceptions
See also
Node.appendChild(), Node.insertBefore(), Node.replaceChild()
Parameter Type Description
oldChild Node The child node to remove.
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.
276
JavaScript objects
Method: removeEventListener()The removeEventListener() method removes an EventListener from an EventTarget.
Syntax Node.removeEventListener( type, listener, useCapture )
Parameters
Return values
None.
Exceptions
None.
See also
Event, EventListener, Node.addEventListener()
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.
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.
SyntaxNode.replaceChild( newChild, oldChild )
Parameters
Return values
Returns the replaced node.
Exceptions
See also
Node.appendChild(), Node.insertBefore(), Node.removeChild()
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.
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.
278
JavaScript objects
Object: NodeFilter
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
Availability BlackBerry® Device Software version 4.6 and later
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.
SyntaxNodeFilter.acceptNode( n )
Parameters
Return values
Returns a constant that determines whether the node is accepted, rejected, or skipped.
Exceptions
None.
Parameter Type Description
n Node The node to check.
Constant Definition Description
1 FILTER_ACCEPT Navigation methods defined for TreeWalker or NodeIterator will return the node.
2 FILTER_REJECT 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.
3 FILTER_SKIP Navigation methods defined for TreeWalker or NodeIterator will not return the node, however, children of this node are still considered.
280
JavaScript objects
Object: NodeIterator
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 topicsNodeFilter, TreeWalker
Properties
Availability BlackBerry® Device Software version 4.6 and later
Property name Type Description Status
expandEntityReferences boolean Returns whether or not the NodeIterator expands the entity references it encounters as it traverses the document.
read only
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 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.
read only
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.
SyntaxNodeIterator.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.
SyntaxNodeIterator.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.
SyntaxNodeIterator.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
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
Methods
Availability BlackBerry® Device Software version 4.6 and later
Property name Type Description Status
length unsigned long Returns the number of nodes in the list. read only
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.
SyntaxModeList.item( index )
Parameters
Return values
Returns the node at the indexth position in NodeList, or null if an invalid index position is specified.
Exceptions
None.
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.
287
BlackBerry Browser JavaScript Reference
Object: Notation
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
Availability BlackBerry® Device Software version 4.6 and later
Extend Node
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
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
Methods
Availability BlackBerry® Device Software version 4.0 and later
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
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.
SyntaxPlugin.item( index )
Parameters
Return values
Returns the plugin at the indexth position in Plugin, or null if an invalid index position is specified.
Exceptions
None.
Parameter Type Description
index int The index position of the Plugin to be returned. Valid values are between 0 and Plugin.length-1 inclusive.
290
JavaScript objects
Method: namedItem()The namedItem() method retrieves the Plugin with the given name from the collection.
SyntaxPlugin.namedItem( name )
Parameters
Return values
Returns the Plugin with the given name, or null if no Plugin with the given name exists in the array.
Exceptions
None.
Parameter Type Description
name String The name of the Plugin to retrieve.
291
BlackBerry Browser JavaScript Reference
Object: PluginArray
The PluginArray object contains an ordered collection of Plugins.
Properties
Methods
Availability BlackBerry® Device Software version 4.6 and later
Property name Type Description Status
length unsigned long Returns the number of Plugins in the collection. read only
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.
SyntaxPluginArray.item( index )
Parameters
Return values
Returns the Plugin at the indexth position in PluginArray, or null if an invalid index position is specified.
Exceptions
None.
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.
293
BlackBerry Browser JavaScript Reference
Method: namedItem()The namedItem() method retrieves the Plugin with the given name from the collection.
SyntaxPluginArray.namedItem( name )
Parameters
Return values
Returns the Plugin with the given name, or null if no plugin with the given name exists in the array.
Exceptions
None.
Parameter Type Description
name String The name of the Plugin object to retrieve.
294
JavaScript objects
Object: ProcessingInstruction
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
Availability BlackBerry® Device Software version 4.6 and later
Extends Node
Property name Type Description Status
data String Specifies the content of the processing instruction. This content includes everything contained between the processing instruction markers.
writable
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
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
Availability BlackBerry® Device Software version 4.6 and later
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
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
Availability BlackBerry® Device Software version 4.6 and later
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
The Screen object returns information about the dimensions and color depth of the BlackBerry device display.
Properties
Availability BlackBerry® Device Software version 4.6 and later
Property name Type Description Status
availHeight int Returns the height of the BlackBerry device screen that is available to the BlackBerry® Browser, in pixels. This may be equal to or less than the value of Screen.height.
read only
availLeft int Returns the screen space available to the left of the browser window. In the case of the BlackBerry Browser, this property always returns a value of “0”.
read only
availTop int Returns the screen space available above the browser window. In the case of the BlackBerry Browser, this property always returns a value of “0”.
read only
availWidth int Returns the width of the BlackBerry device screen that is available to the BlackBerry Browser, in pixels. This may be equal to or less than the value of Screen.width.
read only
colorDepth int Returns the bit depth of the color palette. This property behaves identically to the pixelDepth property.
read only
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
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
Availability BlackBerry® Device Software version 4.6 and later
Property name Type Description Status
disabled boolean When true, indicates that the style sheet is not applied.
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.
writable
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, this property returns the empty MediaList object.
The media is often specified in StyleSheet.ownerNode.
read only
ownerNode Node Returns the Node that associates this style sheet with the document. For HTML 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.
read only
parentStyleSheet StyleSheet Returns the StyleSheet object that contains the style sheet, if one exists.
If the style sheet is not the child of another style sheet, this property returns null.
read only
title String Returns the title of the style sheet.
The title is often specified in StyleSheet.ownerNode.
read only
type String Returns the style sheet language used by the style sheet, specified as a content type, such as “text/css”.
The content type is often specified in StyleSheet.ownerNode.
read only
299
BlackBerry Browser JavaScript Reference
Object: StyleSheetList
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
Methods
Availability BlackBerry® Device Software version 4.6 and later
Property name Type Description Status
length unsigned long Returns the number of style sheets in the list. read only
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.
SyntaxStyleSheetList.item( index )
Parameters
Return values
Returns the rule at the indexth position in StyleSheetList, or null if an invalid index position is specified.
Exceptions
None.
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.
301
BlackBerry Browser JavaScript Reference
Object: Text
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
Availability BlackBerry® Device Software version 4.6 and later
Extends CharacterData
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.
SyntaxTextNode.splitText( offset )
Parameters
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
Parameter Type Description
offset long The offset position at which to split the text.
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
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
Properties
Methods
Availability BlackBerry® Device Software version 4.6 and later
Extend UIEvent
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
Property name Type Description Status
data String Returns the value of the characters generated by the character device. The value of this property may be a single Unicode character or a sequence of Unicode characters. This property cannot be null or contain an empty string.
read only
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().
SyntaxTextEvent.initUIEvent( typeArg, canBubbleArg, cancelableArg, viewArg, dataArg )
Parameters
Return values
None.
Exceptions
None.
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.
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.
SyntaxTextEvent.initTextEvent( namespaceURI, typeArg, canBubbleArg, cancelableArg, viewArg,
dataArg )
Parameters
Return values
None.
Exceptions
None.
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.
306
JavaScript objects
Object: TreeWalker
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 topicsNodeFilter, NodeIterator
Properties
Availability BlackBerry® Device Software version 4.6 and later
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 encounters as it traverses the document.
read only
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 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.
read only
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.
SyntaxTreeWalker.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.
SyntaxTreeWalker.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.
SyntaxTreeWalker.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.
SyntaxTreeWalker.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.
SyntaxTreeWalker.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.
SyntaxTreeWalker.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.
SyntaxTreeWalker.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
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
Properties
Methods
Availability BlackBerry® Device Software version 4.6 and later
Extends Event
Extended by KeyboardEvent, MouseEvent, TextEvent
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
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
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().
SyntaxUIEvent.initUIEvent( typeArg, canBubbleArg, cancelableArg, viewArg, detailArg )
Parameters
Return values
None.
Exceptions
None.
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.
317
BlackBerry Browser JavaScript Reference
Object: Window
The Window object is created automatically when the BlackBerry® Browser encounters a <body> or <frameset> tag. It returns information about the window.
Properties
Availability BlackBerry® Device Software version 3.8 and later
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 has a value of “false”.
read only 3.8 and later
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 window is not embedded in any frame.
read only 3.8 and later
frames NamedFrameMap Returns a NamedFrameMap object that contains a collection of the frames contained by the frameset.
read only 3.8 and later
history History Returns the History object that contains a collection of recently accessed URLs.
read only 3.8 and later
innerHeight int Returns the height of the content area, including the horizontal scroll bar, if rendered.
read only 3.8 and later
innerWidth int Returns the width of the content area, including the vertical scroll bar, if rendered.
read only 3.8 and later
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 BlackBerry Browser.
read only 3.8 and later
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 BlackBerry device screen.
read only 3.8 and later
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 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.
read only 3.8 and later
318
JavaScript objects
Event handlers
Methods
Property name Type Description Status Availability
onabort Function Specifies the function to perform when the loading of a page or image is aborted.
writable 4.6 and later
onchange Function Specifies the function to perform when a form control loses focus after the user has modified the value.
writable 4.6 and later
onclick Function Specifies the function to perform when the user clicks the trackball or trackwheel on a BlackBerry device.
writable 3.8 and later
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 the pointer is over an element.
writable 4.6 and later
onkeypress Function Specifies the function to perform when a key is pressed and released while the pointer is over an element.
writable 4.6 and later
onkeyup Function Specifies the function to perform when a key is released while the pointer is over an element.
writable 4.6 and later
onload Function Specifies the function to perform when the BlackBerry Browser finishes loading a new page or a complete frameset.
writable 4.6 and later
onmousedown Function Specifies the function to perform when the user depresses the trackwheel or trackball on a BlackBerry device.
writable 4.6 and later
onmousemove Function Specifies the function to perform when the user moves the pointer while it is over an element.
writable 4.6 and later
onmouseout Function Specifies the function to perform when the user moves the pointer off of an element.
writable 4.6 and later
onmouseover Function Specifies the function to perform when the user moves the pointer over an element.
writable 4.6 and later
onmouseup Function Specifies the function to perform when the user releases the trackwheel or trackball on a BlackBerry device.
writable 4.6 and later
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 text field.
writable 4.6 and later
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 removes a new page or a frameset.
writable 4.6 and later
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
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.
Method name Description
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
Return values
None.
Exceptions
None.
See also
Event, EventListener
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.
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.
Syntaxwindow.alert( message )
Parameters
Return values
None.
Exceptions
None.
See alsoWindow.confirm(), Window.prompt()
Parameter Type Description
message String The text that is displayed as the dialog box message.
322
JavaScript objects
Method: back()The back() method displays the previous URL in the history list. This method is functionally equivalent to History.back().
Syntaxwindow.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.
Syntaxwindow.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.
Syntaxwindow.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.
Syntaxwindow.confirm( message )
Parameters
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()
Parameter Type Description
message String The text that is displayed as the dialog box message.
326
JavaScript objects
Method: dispatchEvent()The dispatchEvent() method dispatches an Event object created by Document.createEvent().
Syntaxwindow.dispatchEvent( event )
Parameters
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
Parameter Type Description
event Event The Event object to be dispatched.
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.
Syntaxwindow.find( str [, caseSensitive, searchInFrames ] )
Parameters
Return values
Return a value of “true” if the string is found; otherwise, returns “false”.
Exceptions
None.
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.
328
JavaScript objects
Method: focus()The focus() method gives focus to the window.
Syntaxwindow.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().
Syntaxwindow.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.
Syntaxwindow.getComputedStyle( elt, pseudoElt )
Parameters
Return values
Returns the computed style value for the specified element.
Exceptions
None.
See also
HTMLElement.style
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.
331
BlackBerry Browser JavaScript Reference
Method: home()The home() method displays the page that the user set as the BlackBerry® Browser home page.
Syntaxwindow.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.
Syntaxwindow.moveBy ( deltaX, deltaY )
Parameters
Return values
This method is ignored. No values are returned.
Exceptions
None.
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.
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.
Syntaxwindow.moveTo ( x, y )
Parameters
Return values
This method is ignored. No values are returned.
Exceptions
None.
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.
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.
Syntaxwindow.open( URL [, name ] )
Parameters
Return values
Returns a reference to the new Window object.
Exceptions
None.
See also
Window.close()
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.
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.
Syntaxwindow.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.
Syntaxwindow.prompt( message, defaultValue )
Parameters
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()
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.
337
BlackBerry Browser JavaScript Reference
Method: removeEventListener()The removeEventListener() method removes an event listener from the Window object.
Syntaxwindow.removeEventListener( type, listener, useCapture )
Parameters
Return values
None.
Exceptions
None.
See also
Event, EventListener, Node.removeEventListener()
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.
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().
Syntaxwindow.resizeBy( deltaX, deltaY )
Parameter
Return values
None.
Exceptions
None.
See also
Window.resizeTo()
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.
339
BlackBerry Browser JavaScript Reference
Method: resizeTo()The resizeTo() method resizes the window to the specified width and height.
Syntaxwindow.resizeTo( width, height )
Parameter
Return values
None.
Exceptions
None.
See also
Window.resizeBy()
Parameter Type Description
width int The new width of the viewport, in pixels.
height int The new height of the viewport, in pixels.
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().
Syntaxwindow.scroll( x, y )
Parameter
Return values
None.
Exceptions
None.
See also
Window.scrollBy(), Window.scrollTo()
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.
341
BlackBerry Browser JavaScript Reference
Method: scrollBy()The scrollBy() method scrolls the content by the given number of pixels.
Syntaxwindow.scrollBy( deltaX, deltaY )
Parameter
Return values
None.
Exceptions
None.
See also
Window.scroll(), Window.scrollTo()
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.
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().
Syntaxwindow.scrollTo( x, y )
Parameter
Return values
None.
Exceptions
None.
See also
Window.scroll(), Window.scrollBy()
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.
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.
Syntaxwindow.stop()
Parameters
None.
Return values
None.
Exceptions
None.
344
JavaScript objects
Object: XMLHttpRequest
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
Methods
Availability BlackBerry® Device Software version 4.6 and later
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 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.
read only
responseText String Returns the response text entity body. This may return only a fragment of the entity body, if the request response is still in the loading state.
read only
responseXML String Returns the XML response entity body. This may return only a fragment of the entity body, if the request response is still in the loading state.
read only
status unsigned short Returns the HTTP status code sent by the server, or, if no status code is available, throws an INVALID_STATE_ERR exception.
read only
statusText String Returns the HTTP status text sent by the server, or, if no status text is available, throws an INVALID_STATE_ERR exception.
read only
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
getAllResponseHeaders() Returns a complete set of headers and their values.
getResponseHeader() Returns the value of the given header.
open() Assigns the HTTP method and destination URL, as well as some additional optional parameters, for a pending request.
removeEventListener() Removes an event listener from an EventTarget.
send() Sends the request to the URL specified by open().
setRequestHeader() Specifies the value of a header to be sent with the request.
Method name Description
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.
SyntaxXMLHttpRequest.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
Return values
None.
Exceptions
None.
See also
Event, EventListener
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.
348
JavaScript objects
Method: dispatchEvent()The dispatchEvent() method dispatches an Event object created by Document.createEvent().
SyntaxXMLHttpRequest.dispatchEvent( event )
Parameters
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
Parameter Type Description
event Event The Event object to be dispatched.
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.
SyntaxXMLHttpRequest.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
See also
XMLHttpRequest.getResponseHeader()
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).
350
JavaScript objects
Method: getResponseHeader()The getResponseHeader() method returns the value of the given header.
SyntaxXMLHttpRequest.getResponseHeader( header )
Parameters
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
See also
XMLHttpRequest.getAllResponseHeaders()
Parameter Type Description
header String The header to match on. This parameter is not case-sensitive.
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).
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.
SyntaxXMLHttpRequest.open( method, url [, async ] [, user ] [, password ] )
Parameters
Return values
None.
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.
352
JavaScript objects
Exceptions
See also
XMLHttpRequest.send()
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
353
BlackBerry Browser JavaScript Reference
Method: removeEventListener()The removeEventListener() method removes an event listener from an EventTarget.
SyntaxXMLHttpRequest.removeEventListener( type, listener, useCapture )
Parameters
Return values
None.
Exceptions
None.
See also
Event, EventListener
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.
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.
SyntaxXMLHttpRequest.send( [data ] )
Parameters
Return values
If the request was asynchronous, this method returns the callback when the response has been successfully received.
Exceptions
See also
XMLHttpRequest.open(), XMLHttpRequest.setRequestHeader()
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.
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.
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().
SyntaxXMLHttpRequest.setRequestHeader( header, value )
Parameters
Return values
None.
Exceptions
See also
XMLHttpRequest.send()
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.
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.
356