Javascript Reference

BlackBerry Browser

JavaScript Reference

BlackBerry Browser JavaScript Reference

Last modified: 11 September 2008

Document number: 20248101

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

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

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

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

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

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

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

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, IN NO EVENT SHALL RIM BE LIABLE FOR ANY TYPE OF DAMAGES RELATED TO THIS DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED HEREIN INCLUDING WITHOUT LIMITATION ANY OF THE FOLLOWING DAMAGES: DIRECT, CONSEQUENTIAL, EXEMPLARY, INCIDENTAL, INDIRECT, SPECIAL, PUNITIVE, OR AGGRAVATED DAMAGES, DAMAGES FOR LOSS OF PROFITS OR REVENUES, FAILURE TO REALIZE ANY EXPECTED SAVINGS, BUSINESS INTERRUPTION,

http://www.rim.com/patents

http://www.blackberry.com/go/docs

http://www.blackberry.com/go/docs

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


Properties .................................................................................................................................................. 41CSSPrimitiveValue.......................................................................................................................................... 42


getCounterValue() ........................................................................................................................ 44getFloatValue().............................................................................................................................. 45getRectValue()...............................................................................................................................46getRGBColorValue() ..................................................................................................................... 47getStringValue()............................................................................................................................ 48setFloatValue() ..............................................................................................................................49setStringValue() ............................................................................................................................ 50

CSSRule............................................................................................................................................................. 51Properties .................................................................................................................................................. 51

CSSRuleList...................................................................................................................................................... 52Properties ................................................................................................................................................. 52Methods .................................................................................................................................................... 52

item()............................................................................................................................................... 53CSSStyleDeclaration ...................................................................................................................................... 54


getPropertyCSSValue() ................................................................................................................ 58getPropertyPriority() ....................................................................................................................59getPropertyValue() .......................................................................................................................60item()................................................................................................................................................61removeProperty() .......................................................................................................................... 62setProperty() .................................................................................................................................. 63

CSSStyleRule ...................................................................................................................................................64Properties .................................................................................................................................................64

CSSStyleSheet.................................................................................................................................................65Properties .................................................................................................................................................65Methods ....................................................................................................................................................65

deleteRule()....................................................................................................................................66insertRule() .................................................................................................................................... 67

CSSUnknownRule...........................................................................................................................................68CSSValue..........................................................................................................................................................69

Properties .................................................................................................................................................69CSSValueList ................................................................................................................................................... 70


item()................................................................................................................................................ 71

6

CustomEvent ....................................................................................................................................................72Properties ..................................................................................................................................................72Methods .....................................................................................................................................................72

initCustomEventNS().....................................................................................................................73Document......................................................................................................................................................... 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


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


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


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


getNamedItemNS() .................................................................................................................... 257item().............................................................................................................................................258removeNamedItem() ..................................................................................................................259removeNamedItemNS() .............................................................................................................260setNamedItem() ...........................................................................................................................261setNamedItemNS().....................................................................................................................262

Navigator .......................................................................................................................................................263Properties ...............................................................................................................................................263Methods ..................................................................................................................................................263

javaEnabled() ...............................................................................................................................264Node ...............................................................................................................................................................265


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


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


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


18

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.


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.


value String Specifies the value of the attribute. writable 4.6 and later


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



location BlackberryLocation Returns a pointer to the BlackberryLocation object.

This property is available for BlackBerry Device Software Version 4.1 or later.


network String Returns the wireless network on which the BlackBerry device is communicating. The value may be one of:

• 3GPP

• CDMA

• iDEN

• Wi-Fi

Multiple networks may be supported on a single BlackBerry device. If multiple networks are supported, they are returned as a comma-separated list. For example:

3GPP,Wi-Fi


20

JavaScript objects

Object: BlackberryLocation

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



GPSSupported boolean When true, this property indicates that GPS positioning is supported by the BlackBerry device.


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.


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.


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.


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


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


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()


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.


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


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.


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


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


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


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


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.


INDEX_SIZE_ERR This error is thrown if offset is negative, or is greater than the number of 16-bit units in the data.


29


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

SyntaxCharacterData.insertData( offset, arg )

Parameters

Return values

None.

Exceptions


offset int The offset position from which to start inserting.

arg String The string to insert.




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


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.




31


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


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.




32

JavaScript objects

Object: Comment

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


Extends CharacterData

33


Object: Counter

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

Properties



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


Extends CSSRule


encoding String The encoding used in the @charset rule. writable

35


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


Extends CSSRule


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


Extends CSSRule


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


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


Extends CSSRule


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


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


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


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


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


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.


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


Extends CSSRule


selectorText String The page selector for the rule. writable

style CSSStyleDeclaration The declaration block of the rule. read only

41


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


Extends CSSValue


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


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


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


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()


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.


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


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


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


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


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()


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()


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.


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


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()


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.


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


Extended by CSSCharsetRule, CSSFontFaceRule, CSSImportRule, CSSMediaRule, CSSPageRule, CSSStyleRule, CSSUnknownRule


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


Object: CSSRuleList

The CSSRuleList object represents an ordered collection of CSSRule objects.

Properties

Methods



length int The number of rules in the list. read only


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


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

53


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



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


55


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


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


getPropertyCSSValue() Returns the value of a CSS property as an object, if the property has been explicitly set.

getPropertyPriority() Returns the priority of a CSS property.

getPropertyValue() Returns the value of a CSS property as a string, if the property has been explicitly set.

item() Returns the name of the CSS property at the specified index in the collection.

removeProperty() Removes a CSS property from the style declaration block.

setProperty() Sets the value of a CSS property for the style declaration block.


57


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.


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.


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

59


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.


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.


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

61


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


propertyName String The name of the CSS property to remove.


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


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.


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


Object: CSSStyleRule

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

Properties


Extends CSSRule


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


Extends StyleSheet


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


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


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


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


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


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.


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


Object: CSSUnknownRule

The CSSUnknownRule represents an unsupported @ rule.


Extends CSSRule

68

JavaScript objects

Object: CSSValue

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

Properties


Extended by CSSPrimitiveValue, CSSValueList


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


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


Extends CSSValue


length int The number of property values in the list. read only


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.


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

71


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


Extends Event


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

read only


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.


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


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


Extends Node


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


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.


75


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()


name String The name of the attribute to create.


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()


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.


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


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


data String The contents of the CDATASection node.


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


data String The contents of the Comment node.

79


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


tagName String The type of element to create.

In an XML document, tagName is case-sensitive.


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

81


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


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.








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


name String The name of the entity to reference.


INVALID_CHARACTER_ERR This error is thrown if name contains an illegal character.


83


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


eventType String The type of event to create.


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


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.


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

85


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


target String The target of the processing instruction.

data String The data to store in the processing instruction.


INVALID_CHARACTER_ERR This error is thrown if target contains an illegal character.


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


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




87


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


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:




• 0x00000004 = SHOW_TEXT











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.


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


elementID String The ID of the element to retrieve.

89


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


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


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


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


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()


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.


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

93


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.


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


Extends Node


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


Object: DOMException

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

Constants


Error code Exception Description

1 INDEX_SIZE_ERR This error is thrown if an index or size is negative, or is greater than the permitted value.

2 DOMSTRING_SIZE_ERR This error is thrown if a range of text does not fit into a DOMString.

3 HIERARCHY_REQUEST_ERR This error is thrown if a node is inserted where it is not permitted.

4 WRONG_DOCUMENT_ERR This error is thrown if a node is used in a different document than the one that created it.

5 INVALID_CHARACTER_ERR This error is thrown if an invalid or illegal character is used.

6 NO_DATA_ALLOWED_ERR This error is thrown if data is specified for a node which does not permit data.

7 NO_MODIFICATION_ALLOWED_ERR This error is thrown if an attempt is made to modify an object which does not permit modifications.

8 NOT_FOUND_ERR This error is thrown if an attempt is made to reference a node that does not exist.

9 NOT_SUPPORTED_ERR This error is thrown if the implementation does not support the requested type of object or operation.

10 INUSE_ATTRIBUTE_ERR This error is thrown if an attribute added to an Element is already an attribute of another Element object.

11 INVALID_STATE_ERR This error is thrown if an attempt is made to use an object that is not usable.

12 SYNTAX_ERR Thie error is thrown if an invalid or illegal string is specified.

13 INVALID_MODIFICATION_ERR This error is thrown if an attempt is made to modify the type of an underlying object.

14 NAMESPACE_ERR This error is thrown if an attempt is made to create or modify an object in a way that does not comply with namespaces.

15 INVALID_ACCESS_ERR This error is thrown if a parameter or operation is not supported by the underlying object.

96

JavaScript objects

Object: DOMImplementation

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



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


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


title String The title of the CSS style sheet.

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


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


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.









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


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


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.








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()


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


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


Extends Node

Extended by HTMLElement


tagName String The name of the element. read only


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


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

103


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


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


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.



105


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


Exceptions

See also

Attr


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.



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()


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

107


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()


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.



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.


name String The name of the attribute to check.

109


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


namespaceURI String The namespace of the attribute to check.

localName String The local name of the attribute to check.



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


name String The name of the attribute node to remove.


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


Method: removeAttributeNode()The removeAttributeNode() method removes the specified Attr node from the element node.


SyntaxElement.removeAttributeNode( oldAttr )

Parameters

Return values

The removed Attr object.

Exceptions

See also

Attr


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



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 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


namespaceURI String The namespace of the attribute to retrieve.

localName String The local name of the attribute to retrieve.




113


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()


name String The nam e of the attribute to create or modify.

value String The value to set the attribute to, in string form.




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()


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


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


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()


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


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.

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


Exceptions

See also

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


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.










117


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


Extends Node


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.


Extends Node

119


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


Extended by CustomEvent, MutationEvent, UIEvent


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


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()


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


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


Object: EventException

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

Constants


Error code Exception Description

0 UNSPECIFIED_EVENT_TYPE_ERR This error is thrown if the Event object’s type was not specified by initializing the event before the method was called, or if the type was given a value of null or an empty string.

1 DISPATCH_REQUEST_ERR This error is thrown if an attempt is made to dispatch an Event object that has already been dispatched.

124

JavaScript objects

Object: EventListener

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



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

125


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.


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



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


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


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


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


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


Extends HTMLElement


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


blur() Removes keypad focus from the element.

focus() Gives keypad focus to the element.

131


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


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


Extends HTMLElement


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


Extends HTMLElement



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


target String Specifies the frame in which to render the target document. writable

135


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


Extends HTMLElement


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


Extends HTMLElement


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


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


Extends HTMLElement


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


Extends HTMLElement


clear String Specifies the control flow of text around adjacent floats. writable

139


Object: HTMLButtonElement

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

The <button> element defines a button form control.

Properties


Extends HTMLElement


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



length int Returns the number of nodes in the list. read only


item() Retrieves a specific node, by index, from the collection.

namedItem() Retrieves the node with the given name property value from the collection.

141


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.


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.


name String The name of the node to retrieve.

143


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


Extends HTMLElement


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


Extends HTMLElement


align String Specifies how text within the <div> element is horizontally aligned. writable

145


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


Extends HTMLElement



146

JavaScript objects

Object: HTMLDocument

The HTMLDocument object provides access to the HTML hierarchy.

Properties


Extends Document


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


Event handlers

Methods


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


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


Method: getElementByName()The getElementByName() method returns an array of the elements in the document with the specified name.


• 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()


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


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()


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()


text String The text to be parsed.

153


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


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


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


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


155


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


Extends HTMLElement



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


Extends HTMLElement


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


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


Extends HTMLElement


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


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


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


Extends HTMLElement


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


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


Extends HTMLElement


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


Extends HTMLElement


profile String Specifies the URLs that contain metadata about the document. writable

163


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


Extends HTMLElement


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


Extends HTMLElement


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


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


Extends HTMLElement


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


Extends HTMLElement


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


Object: HTMLImageElement

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

The <img> element defines an image to display.

Properties


Extends HTMLElement


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


Extends HTMLElement


accept String Specifies a comma-separated list of content types that this form accepts. 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



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


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


169


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



click() Simulates a mouse click.


select() Selects the contents of the element.


170

JavaScript objects


SyntaxHTMLInputElement.blur()

Parameters

None.

Return values

None.

Exceptions

None.

171


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


SyntaxHTMLInputElement.focus()

Parameters

None.

Return values

None.

Exceptions

None.

173


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


Extends HTMLElement



prompt String Specifies the prompt message. writable

175


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


Extends HTMLElement




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


Extends HTMLElement



align String Specifies the horizontal or vertical alignment of the caption relative to the parent <fieldset> element.

writable


177


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


Extends HTMLElement


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


Extends HTMLElement


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


Object: HTMLMapElement

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

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

Properties


Extends HTMLElement


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


Extends HTMLElement



181


Object: HTMLMetaElement

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

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

Properties


Extends HTMLElement


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


Extends HTMLElement


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


Object: HTMLObjectElement

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

The <object> element specifies an embedded object.

Properties


Extends HTMLElement


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


Extends HTMLElement



start int Specifies the starting value for the numbering sequence. writable

type String Specifies the numbering style to use. writable

185


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


Extends HTMLElement


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


Extends HTMLElement


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


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”)


myHTMLOptions[2]myHTMLOptions[“item”]

Properties

Methods



length int Returns the number of HTMLOptionElement objects contained in the list. read only


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.


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

189


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


• 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.


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


Extends HTMLElement


align String Specifies the horizontal alignment of the paragraph on the page. writable

191


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


Extends HTMLElement


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


Extends HTMLElement


width int Specifies the width of the content block. writable

193


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


Extends HTMLElement


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


Extends HTMLElement


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


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


Extends HTMLElement



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


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


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


add() Adds a new option to the selection list.



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()


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.


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

197



SyntaxHTMLSelectElement.blur()

Parameters

None.

Return values

None.

Exceptions

None.

198

JavaScript objects


SyntaxHTMLSelectElement.focus()

Parameters

None.

Return values

None.

Exceptions

None.

199


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

SyntaxHTMLSelectElement.remove( index )

Parameters

Return values

None.

Exceptions

None.


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


Extends HTMLElement


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


Object: HTMLTableCaptionElement

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

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

Properties


Extends HTMLElement


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


Extends HTMLElement


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


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


Extends HTMLElement




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


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


Extends HTMLElement


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


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


createTHead() Creates a new table header, if the table does not already contain one.

deleteCaption() Removes the caption from the table, if one exists.

deleteRow() Removes the row at the given index position from the table.

deleteTFoot() Removes the footer from the table, if one exists.

deleteTHead() Removes the header from the table, if one exists.

insertRow() Inserts a new empty row into the table at the given index position.


206

JavaScript objects

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

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


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


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


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.


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


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


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()


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.


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


Extends HTMLElement



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


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



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


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

SyntaxHTMLTableRowElement.deleteCell( index )

Parameters

Return values

None.

Exceptions


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.


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


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.


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


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


Extends HTMLElement




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



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


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.


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


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()


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.


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


Extends HTMLElement


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



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


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




select() Selects the entire contents of the element.

221



SyntaxHTMLTextAreaElement.blur()

Parameters

None.

Return values

None.

Exceptions

None.

222

JavaScript objects


SyntaxHTMLTextAreaElement.focus()

Parameters

None.

Return values

None.

Exceptions

None.

223


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


Extends HTMLElement


text String Specifies the title of the HTML document. writable

225


Object: HTMLUListElement

The HTMLUListElement object provides access to <ul> elements within an HTML document.

The <ul> element specifies an unordered, or bulleted, list.

Properties


Extends HTMLElement



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


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.:


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




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


Methods


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.


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

229


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()


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()


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




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


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



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


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()


URL String The URL to load.

233


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

Syntaxlocation.reload( forceGet )

Parameters

Return values

None.

Exceptions

None.

See also

Location.assign()


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()


URL String The URL to replace the current URL with.

235


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



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


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


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()


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.


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()


oldMedium String The medium to remove from MediaList.


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


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.


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



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


Object: MimeTypeArray

The MimeTypeArray object contains an ordered collection of MIME types.

Properties

Methods



length int Returns the number of MIME types in the list. read only


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.


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

243


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.


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


Extends UIEvent


click yes yes Occurs when the user clicks the trackball or trackwheel on a BlackBerry device.


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.



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


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.


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.


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


Properties

Methods

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




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


initMouseEvent() Initializes the value of a MouseEvent.


246

JavaScript objects

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

SyntaxMouseEvent.initMouseEvent( typeArg, canBubbleArg, cancelableArg, viewArg, detailArg,

screenXArg, screenYArg, clientXArg, clientYArg, ctrlKeyArg, AltKeyArg, shiftKeyArg, metaKeyArg, buttonArg, relatedTargetArg )

Parameters


typeArge String Specifies the Mouse event type. This parameter may have one of the following values:

• click

• mousedown

• mousemove

• mouseout

• mouseover

• mouseup




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


Return values

None.

Exceptions

None.

248

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


Extends Event


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.


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.


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.


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.


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


Properties

Methods


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


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.


typeArg String Specifies the mutation event type. This parameter may have one of the following values:

• DOMAttrModified

• DOMCharacterDataModified

• DOMContentLoaded

• DOMNodeInserted

• DOMNodeInsertedIntoDocument

• DOMNodeRemoved

• DOMNodeRemovedFromDocument

• DOMSubtreeModified



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


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”)


myNamedFrameMap[2]myNamedFrameMap[“item”]

Properties

Methods



length unsigned long Returns the number of nodes in the map. read only


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.


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

253


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.


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”)


myNamedNodeMap[2]myNamedNodeMap[“item”]

Properties

Methods



length unsigned long Returns the number of nodes in the map. read only


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


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()


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()


namespaceURI String The namespace of the node to retrieve.

localName String The local name of the node to retrieve.



257


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.


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


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


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


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


namespaceURI String The namespace of the node to remove.

localName String The local name of the node to remove.



NOT_FOUND_ERR This error is thrown if the specified name does not exist in the NamedNodeMap.


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


arg Node The node to add to the map.


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.


WRONG_DOCUMENT_ERR This error is thrown if arg was created from a different document than the one that created this NamedNodeMap object.

261


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


arg Node The node to add to the map.


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.



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



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


javaEnabled() Tests whether the browser supports Java or not.

263


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


Extended By Attr, CharacterData, Document, DocumentFragment, DocumentType, Element, Entity, EntityReference, Notation, ProcessingInstruction


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.


• 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


Methods

prefix String Specifies the prefix, extracted from the qualified name of the given node, or null if it is unspecified.


• 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


addEventListener() Adds an EventListener object to a set of event listeners for the given node.

appendChild() Adds a node to the end of the array of child nodes for the given node.

cloneNode() Returns a duplicate of the given node. The duplicate node has no parent.

dispatchEvent() Dispatches an Event object created by Document.createEvent().

hasAttributes() Returns whether the given node has any attributes.

hasChildNodes() Returns whether the given node has any children.

insertBefore() Inserts a new node before the given node.

isSupported() Tests whether the given node supports a specific feature.

normalize() Merges text nodes adjacent to the given element node to create a normalized DOM.

removeChild() Removes the specified child from the given element node and returns it.

removeEventListener() Removes an event listener from an EventTarget.

replaceChild() Removes the specified child from the given and replaces it with another node, then returns the removed node.


266

JavaScript objects

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

Syntax Node.addEventListener( type, listener, useCapture )

Parameters

Return values

None.

Exceptions

None.

See also

Event, EventListener


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


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()


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.


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.


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


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()


event Event The Event object to be dispatched.


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


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()


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.


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.


NOT_FOUND_ERR This error is thrown if refChild is not a child of the given node.


273


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()


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


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()


oldChild Node The child node to remove.



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()


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


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()


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.


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.


NOT_FOUND_ERR This error is thrown if oldChild is not a child of 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



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

279


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.


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



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:




• 0x00000004 = SHOW_TEXT











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


Methods


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


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


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


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


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)


myNodelist[2]

Properties

Methods



length unsigned long Returns the number of nodes in the list. read only


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.


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

287


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


Extend Node


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”)


myPlugins[2]myPlugins[“item”]

Properties

Methods



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


item() Returns the MIME type at the specified index in the collection.

namedItem() Returns the MIME type with the given name.

289


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.


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.


name String The name of the Plugin to retrieve.

291


Object: PluginArray

The PluginArray object contains an ordered collection of Plugins.

Properties

Methods



length unsigned long Returns the number of Plugins in the collection. read only


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.


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

293


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.


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


Extends Node


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


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



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



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


Object: Screen

The Screen object returns information about the dimensions and color depth of the BlackBerry device display.

Properties



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



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


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)


myStyleSheets[2]

Properties

Methods



length unsigned long Returns the number of style sheets in the list. read only


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.


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

301


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


Extends CharacterData


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


offset long The offset position at which to split the text.




303


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


Extend UIEvent


textInput yes yes Occurs when one or more characters have been entered.


TextEvent.data, UIEvent.view


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


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.


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


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.


namespaceURI String Specifies the namespace URI associated with this event, or null if no namespace exists.

typeArg String Specifies the event type.




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



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:




• 0x00000004 = SHOW_TEXT











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


Methods


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


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


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


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


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


Extends Event

Extended by KeyboardEvent, MouseEvent, TextEvent


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.


UIEvent.detail


detail long Returns detail information about the event. read only

view AbstractView Returns a reference to the AbstractView that generated the event. read only


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.


typeArg String Specifies the event type.




detailArg long Specifies the code for the event detail.

317


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



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”.


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.


frames NamedFrameMap Returns a NamedFrameMap object that contains a collection of the frames contained by the frameset.


history History Returns the History object that contains a collection of recently accessed URLs.


innerHeight int Returns the height of the content area, including the horizontal scroll bar, if rendered.


innerWidth int Returns the width of the content area, including the vertical scroll bar, if rendered.


length unsigned long Returns the number of frames in the parent window. read only 3.8 and later

location Location Specifies the URL of the document displayed in the browser window. writable 3.8 and later

navigator Navigator Returns the Navigator object, which provides information about the BlackBerry Browser.


name String Specifies the name of the window. writable 3.8 and later

opener Window Returns the Window object that created the window. read only 3.8 and later

parent Window Returns the parent Window object. read only 3.8 and later

screen Screen Returns the Screen object, which provides information about the BlackBerry device screen.


self Window Returns a reference to the current window. read only 3.8 and later

top Window Returns a reference to the top window. read only 3.8 and later

window Window Returns a reference to the current window. Using the window property lets you invoke methods or call properties on the current window without confusion when multiple browser windows are open.

Because the BlackBerry Browser is a single document interface, a new window is opened each time a new URL is opened.


318

JavaScript objects

Event handlers

Methods


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.


onclick Function Specifies the function to perform when the user clicks the trackball or trackwheel on a BlackBerry device.


onerror Function Specifies the function to perform when an error occurs. writable 4.6 and later

onkeydown Function Specifies the function to perform when a key is pressed down while the pointer is over an element.


onkeypress Function Specifies the function to perform when a key is pressed and released while the pointer is over an element.


onkeyup Function Specifies the function to perform when a key is released while the pointer is over an element.


onload Function Specifies the function to perform when the BlackBerry Browser finishes loading a new page or a complete frameset.


onmousedown Function Specifies the function to perform when the user depresses the trackwheel or trackball on a BlackBerry device.


onmousemove Function Specifies the function to perform when the user moves the pointer while it is over an element.


onmouseout Function Specifies the function to perform when the user moves the pointer off of an element.


onmouseover Function Specifies the function to perform when the user moves the pointer over an element.


onmouseup Function Specifies the function to perform when the user releases the trackwheel or trackball on a BlackBerry device.


onreset Function Specifies the function to perform when the user resets a form. writable 3.8 and later

onselect Function Specifies the function to perform when the user selects some text in a text field.


onsubmit Function Specifies the function to perform when the user submits a form. writable 3.8 and later

onunload Function Specifies the function to perform when the BlackBerry Browser removes a new page or a frameset.



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



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.


resizeBy() Resizes the viewport relative to the current viewport size.

resizeTo() Resizes the viewport to the specified width and height.

scroll() Scrolls the content to a given set of coordinates.

scrollBy() Scrolls the content by the given number of pixels.

scrollTo() Scrolls the content to a given set of coordinates.

stop() Stops the current download.


320

JavaScript objects

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

Syntax window.addEventListener( type, listener, useCapture )

Parameters

Return values

None.

Exceptions

None.

See also




listener EventListener The EventListener function to be invoked.



321


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()


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


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


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()



326

JavaScript objects


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





327


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.


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


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


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


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.


Syntaxwindow.moveBy ( deltaX, deltaY )

Parameters

Return values


Exceptions

None.


deltaX int The number of pixels to move the window horizontally.

deltaY int The number of pixels to move the window vertically.

333


Method: moveTo()The moveTo() method moves the window's left and top edge to the specified co-ordinates.


Syntaxwindow.moveTo ( x, y )

Parameters

Return values


Exceptions

None.


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()


URL int The URL to be displayed in the child window

name String Optional. The name of the window that is being opened.

335


Method: print()The print() method prints the current contents of the window.


Syntaxwindow.print()

Parameters

None.

Return values


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()



defaultValue String The default value of the input field, or null if no default is to be provided.

337


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()






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()


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


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()


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()


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


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()


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()


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


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



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


abort() Stops the current request.

addEventListener() Adds an EventListener object to a set of event listeners for the given node.


345


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.


send() Sends the request to the URL specified by open().

setRequestHeader() Specifies the value of a header to be sent with the request.


346

JavaScript objects

Method: abort()The abort() method stops the current request in progress.

When a request is aborted, the value for XMLHttpRequest.readyState is automatically set to DONE.

SyntaxXMLHttpRequest.abort()

Parameters

None.

Return values

None.

Exceptions

None.

347


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




listener EventListener The event listener function to be invoked.



348

JavaScript objects


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





349


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()


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()


header String The header to match on. This parameter is not case-sensitive.


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


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.


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()


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


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







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()


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.


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


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()


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.


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

©2008 Research In Motion Limited

Published in Canada.

Documents

Javascript Reference