BlackBerry BrowserVersion: 5.0

JavaScript Reference

Published: 2010-07-19SWD-626606-0719035233-001

Contents1 JavaScript reference overview................................................................................................................................................... 18

Supported JavaScript objects: Alphabetical................................................................................................................................ 18

A................................................................................................................................................................................................ 18

B................................................................................................................................................................................................ 18

C................................................................................................................................................................................................ 18

D............................................................................................................................................................................................... 19

E................................................................................................................................................................................................ 20

H............................................................................................................................................................................................... 20

K................................................................................................................................................................................................ 23

L................................................................................................................................................................................................ 23

M............................................................................................................................................................................................... 23

N............................................................................................................................................................................................... 24

P................................................................................................................................................................................................ 24

R................................................................................................................................................................................................ 25

S................................................................................................................................................................................................ 25

T................................................................................................................................................................................................ 25

U............................................................................................................................................................................................... 26

W............................................................................................................................................................................................... 26

X................................................................................................................................................................................................ 26

2 JavaScript objects........................................................................................................................................................................ 27

Object: Attr...................................................................................................................................................................................... 27

Attr properties......................................................................................................................................................................... 27

Object: blackberry........................................................................................................................................................................... 28

blackberry properties............................................................................................................................................................. 28

Object: blackberry.launch.............................................................................................................................................................. 29

blackberry.launch methods................................................................................................................................................... 29

Method: blackberry.launch.launchCamera()....................................................................................................................... 30

Method: blackberry.launch.launchVideoRecorder().......................................................................................................... 30

Method: blackberry.launch.launchVoicemail()................................................................................................................... 31

Method: blackberry.launch.newAppointment().................................................................................................................. 31

Method: blackberry.launch.newContact()........................................................................................................................... 33

Method: blackberry.launch.newMap()................................................................................................................................. 35

Method: blackberry.launch.newMemo().............................................................................................................................. 36

Method: blackberry.launch.newPhoneCall()....................................................................................................................... 37

Method: blackberry.launch.newSMS()................................................................................................................................. 38

Method: blackberry.launch.newTask()................................................................................................................................. 38

JSON Object: Address........................................................................................................................................................... 40

Object: blackberry.location............................................................................................................................................................ 40

blackberry.location properties.............................................................................................................................................. 41

blackberry.location methods................................................................................................................................................. 42

Method: blackberry.location.onLocationUpdate()............................................................................................................. 42

Method: blackberry.location.refreshLocation()................................................................................................................... 43

Method: blackberry.location.removeLocationUpdate()..................................................................................................... 44

Method: blackberry.location.setAidMode()......................................................................................................................... 44

Object: CDATASection................................................................................................................................................................... 45

Object: CharacterData................................................................................................................................................................... 46

CharacterData properties...................................................................................................................................................... 46

CharacterData methods........................................................................................................................................................ 46

Method: CharacterData.appendData()............................................................................................................................... 47

Method: CharacterData.deleteData().................................................................................................................................. 47

Method: CharacterData.insertData()................................................................................................................................... 48

Method: CharacterData.replaceData()................................................................................................................................ 49

Method: CharacterData.substringData()............................................................................................................................ 50

Object: Comment............................................................................................................................................................................ 50

Object: Counter............................................................................................................................................................................... 51

Counter properties................................................................................................................................................................. 51

Object: CSSCharsetRule................................................................................................................................................................ 51

CSSCharsetRule properties................................................................................................................................................... 51

Object: CSSFontFaceRule.............................................................................................................................................................. 52

CSSFontFaceRule properties................................................................................................................................................. 52

Object: CSSImportRule.................................................................................................................................................................. 52

CSSImportRule properties..................................................................................................................................................... 52

Object: CSSMediaRule................................................................................................................................................................... 53

CSSMediaRule properties...................................................................................................................................................... 53

CSSMediaRule methods........................................................................................................................................................ 53

Method: CSSMediaRule.deleteRule().................................................................................................................................. 53

Method: CSSMediaRule.insertRule()................................................................................................................................... 54

Object: CSSPageRule..................................................................................................................................................................... 55

CSSPageRule properties........................................................................................................................................................ 55

Object: CSSPrimitiveValue............................................................................................................................................................ 55

CSSPrimitiveValue properties............................................................................................................................................... 56

CSSPrimitiveValue methods.................................................................................................................................................. 57

Method: CSSPrimitiveValue.getCounterValue()................................................................................................................. 58

Method: CSSPrimitiveValue.getFloatValue()...................................................................................................................... 58

Method: CSSPrimitiveValue.getRectValue()....................................................................................................................... 60

Method: CSSPrimitiveValue.getRGBColorValue().............................................................................................................. 61

Method: getStringValue()...................................................................................................................................................... 62

Method: CSSPrimitiveValue.setFloatValue()....................................................................................................................... 62

Method: CSSPrimitiveValue.setStringValue()..................................................................................................................... 64

Object: CSSRule.............................................................................................................................................................................. 65

CSSRule properties................................................................................................................................................................. 66

Object: CSSRuleList........................................................................................................................................................................ 66

CSSRuleList properties........................................................................................................................................................... 67

CSSRuleList methods............................................................................................................................................................. 67

Method: CSSRuleList.item().................................................................................................................................................. 67

Object: CSSStyleDeclaration......................................................................................................................................................... 68

CSSStyleDeclaration properties........................................................................................................................................... 68

CSSStyleDeclaration methods.............................................................................................................................................. 73

Method: CSSStyleDeclaration.getPropertyPriority().......................................................................................................... 73

Method: CSSStyleDeclaration.getPropertyCSSValue()..................................................................................................... 74

Method: CSSStyleDeclaration.getPropertyValue()............................................................................................................ 75

Method: CSSStyleDeclaration.item()................................................................................................................................... 75

Method: CSSStyleDeclaration.removeProperty()............................................................................................................... 76

Method: CSSStyleDeclaration.setProperty()....................................................................................................................... 76

Object: CSSStyleRule..................................................................................................................................................................... 77

CSSStyleRule properties........................................................................................................................................................ 77

Object: CSSStyleSheet................................................................................................................................................................... 78

CSSStyleSheet properties...................................................................................................................................................... 78

CSSStyleSheet methods........................................................................................................................................................ 78

Method: CSSStyleSheet.deleteRule()................................................................................................................................... 78

Method: CSSStyleSheet.insertRule().................................................................................................................................... 79

Object: CSSUnknownRule............................................................................................................................................................. 80

Object: CSSValue............................................................................................................................................................................ 80

CSSValue properties.............................................................................................................................................................. 81

Object: CSSValueList...................................................................................................................................................................... 81

CSSValueList properties........................................................................................................................................................ 81

CSSValueList methods........................................................................................................................................................... 82

Method: CSSValueList.item()................................................................................................................................................ 82

Object: CustomEvent...................................................................................................................................................................... 82

Properties................................................................................................................................................................................ 83

CustomEvent methods........................................................................................................................................................... 83

Method: CustomEvent.initCustomEventNS()...................................................................................................................... 83

Object: Document........................................................................................................................................................................... 84

Document properties............................................................................................................................................................. 84

Document methods................................................................................................................................................................ 84

Method: Document.adoptNode()......................................................................................................................................... 86

Method: Document.createAttribute().................................................................................................................................. 86

Method: Document.createAttributeNS()............................................................................................................................. 87

Method: Document.createCDATASection()........................................................................................................................ 88

Method: Document.createComment()................................................................................................................................. 89

Method: Document.createDocumentFragment()............................................................................................................... 90

Method: Document.createElement()................................................................................................................................... 90

Method: Document.createElementNS().............................................................................................................................. 91

Method: Document.createEntityReference()...................................................................................................................... 92

Method: Document.createEvent()........................................................................................................................................ 93

Method: Document.createNodeIterator()........................................................................................................................... 94

Method: Document.createProcessingInstruction()............................................................................................................ 95

Method: Document.createRange()....................................................................................................................................... 96

Method: Document.createTextNode()................................................................................................................................. 97

Method: Document.createTreeWalker().............................................................................................................................. 97

Method: Document.getElementById()................................................................................................................................. 99

Method: Document.getElementsByTagName().................................................................................................................. 100

Method: Document.getElementsByTagNameNS()............................................................................................................ 100

Method: Document.getOverrideStyle()............................................................................................................................... 101

Method: Document.importNode()........................................................................................................................................ 102

Object: DocumentFragment.......................................................................................................................................................... 103

Object: DocumentType.................................................................................................................................................................. 103

DocumentType properties..................................................................................................................................................... 103

Object: DOMImplementation....................................................................................................................................................... 104

DOMImplementation methods............................................................................................................................................. 104

Method: DOMImplementation.createCSSStyleSheet()..................................................................................................... 105

Method: DOMImplementation.createDocument()............................................................................................................ 105

Method: DOMImplementation.createDocumentType().................................................................................................... 106

Method: DOMImplementation.hasFeature()...................................................................................................................... 107

Object: DOMParser........................................................................................................................................................................ 108

DOMParser methods............................................................................................................................................................. 108

Method: DOMParser.parseFromString()............................................................................................................................. 109

Object: Element.............................................................................................................................................................................. 110

Element properties................................................................................................................................................................. 110

Element methods.................................................................................................................................................................... 110

Method: Element.getAttribute()........................................................................................................................................... 111

Method: Element.getAttributeNode().................................................................................................................................. 112

Method: Element.getAttributeNodeNS()............................................................................................................................ 112

Method: Element.getAttributeNS()...................................................................................................................................... 113

Method: Element.getElementsByTagName()...................................................................................................................... 114

Method: Element.getElementsByTagNameNS()................................................................................................................ 115

Method: Element.hasAttribute()........................................................................................................................................... 116

Method: Element.hasAttributeNS()..................................................................................................................................... 116

Method: Element.removeAttribute().................................................................................................................................... 117

Method: Element.removeAttributeNode()........................................................................................................................... 118

Method: Element.removeAttributeNS()............................................................................................................................... 119

Method: Element.setAttribute()............................................................................................................................................ 120

Method: Element.setAttributeNode().................................................................................................................................. 120

Method: Element.setAttributeNodeNS()............................................................................................................................. 121

Method: setAttributeNS()...................................................................................................................................................... 122

Object: Entity................................................................................................................................................................................... 123

Entity properties..................................................................................................................................................................... 124

Object: EntityReference................................................................................................................................................................. 124

Object: Event................................................................................................................................................................................... 124

Event properties...................................................................................................................................................................... 125

Event methods........................................................................................................................................................................ 125

Method: Event.initEvent()...................................................................................................................................................... 126

Method: Event.preventDefault()........................................................................................................................................... 126

Method: Event.stopPropagation()........................................................................................................................................ 127

Object: EventListener..................................................................................................................................................................... 128

EventListener methods.......................................................................................................................................................... 128

Method: EventListener.handleEvent().................................................................................................................................. 128

Object: History................................................................................................................................................................................ 129

History properties................................................................................................................................................................... 129

History methods..................................................................................................................................................................... 129

Method: history.back()........................................................................................................................................................... 129

Method: history.forward()...................................................................................................................................................... 130

Method: history.go()............................................................................................................................................................... 131

Object: HTMLAnchorElement....................................................................................................................................................... 131

HTMLAnchorElement properties.......................................................................................................................................... 132

HTMLAnchorElement methods............................................................................................................................................. 133

Method: HTMLAnchorElement.blur()................................................................................................................................... 133

Method: HTMLAnchorElement.focus()................................................................................................................................ 133

Object: HTMLAreaElement............................................................................................................................................................ 134

HTMLAreaElement properties............................................................................................................................................... 134

Object: HTMLAppletElement......................................................................................................................................................... 135

HTMLAppletElement properties........................................................................................................................................... 135

Object: HTMLBaseElement............................................................................................................................................................ 136

HTMLBaseElement properties.............................................................................................................................................. 136

Object: HTMLBaseFontElement.................................................................................................................................................... 136

HTMLBaseFontElement properties....................................................................................................................................... 136

Object: HTMLBodyElement........................................................................................................................................................... 137

HTMLBodyElement properties.............................................................................................................................................. 137

Object: HTMLBRElement............................................................................................................................................................... 137

HTMLBRElement properties.................................................................................................................................................. 138

Object: HTMLButtonElement........................................................................................................................................................ 138

HTMLButtonElement properties........................................................................................................................................... 138

Object: HTMLCollection................................................................................................................................................................. 139

HTMLCollection properties................................................................................................................................................... 139

HTMLCollection methods...................................................................................................................................................... 139

Method: HTMLCollection.item()........................................................................................................................................... 140

Method: HTMLCollection.namedItem()............................................................................................................................... 140

Object: HTMLDataListElement...................................................................................................................................................... 141

HTMLDataListElement properties........................................................................................................................................ 141

Object: HTMLDirectoryElement.................................................................................................................................................... 141

HTMLDirectoryElement properties....................................................................................................................................... 142

Object: HTMLDivElement.............................................................................................................................................................. 142

HTMLDivElement properties................................................................................................................................................. 142

Object: HTMLDListElement........................................................................................................................................................... 142

HTMLDListElement properties.............................................................................................................................................. 143

Object: HTMLDocument................................................................................................................................................................ 143

HTMLDocument properties................................................................................................................................................... 143

HTMLDocument event handlers........................................................................................................................................... 145

HTMLDocument methods..................................................................................................................................................... 146

Method: HTMLDocument.close()......................................................................................................................................... 147

Method: HTMLDocument.getElementByName()............................................................................................................... 147

Method: HTMLDocument.open().......................................................................................................................................... 148

Method: HTMLDocument.write()......................................................................................................................................... 149

Method: HTMLDocument.writeln()...................................................................................................................................... 149

Object: HTMLElement.................................................................................................................................................................... 150

HTMLElement properties....................................................................................................................................................... 151

HTMLElement event handlers............................................................................................................................................... 152

Object: HTMLFieldsetElement...................................................................................................................................................... 154

HTMLFieldsetElement properties......................................................................................................................................... 154

Object: HTMLFontElement............................................................................................................................................................ 154

HTMLFontElement properties............................................................................................................................................... 155

Object: HTMLFormElement........................................................................................................................................................... 155

HTMLFormElement properties.............................................................................................................................................. 155

HTMLFormElement methods................................................................................................................................................ 156

Method: HTMLFormElement.item()..................................................................................................................................... 156

Method: HTMLFormElement.namedItem()......................................................................................................................... 157

Method: HTMLFormElement.reset()..................................................................................................................................... 158

Method: HTMLFormElement.submit()................................................................................................................................. 158

Object: HTMLFrameElement......................................................................................................................................................... 159

HTMLFrameElement properties............................................................................................................................................ 159

Object: HTMLFrameSetElement................................................................................................................................................... 159

HTMLFrameSetElement properties...................................................................................................................................... 160

Object: HTMLHeadElement........................................................................................................................................................... 160

HTMLHeadElement properties............................................................................................................................................. 160

Object: HTMLHeadingElement..................................................................................................................................................... 160

HTMLHeadingElement properties........................................................................................................................................ 161

Object: HTMLHRElement............................................................................................................................................................... 161

HTMLHRElement properties................................................................................................................................................. 161

Object: HTMLHtmlElement........................................................................................................................................................... 161

HTMLHtmlElement properties.............................................................................................................................................. 162

Object: HTMLIFrameElement........................................................................................................................................................ 162

HTMLIFrameElement properties........................................................................................................................................... 162

Object: HTMLImageElement......................................................................................................................................................... 163

HTMLImageElement properties............................................................................................................................................ 163

Object: HTMLInputElement........................................................................................................................................................... 164

HTMLInputElement properties............................................................................................................................................. 164

HTMLInputElement methods................................................................................................................................................ 167

Method: HTMLInputElement.blur()...................................................................................................................................... 167

Method: HTMLInputElement.click()..................................................................................................................................... 168

Method: HTMLInputElement.focus().................................................................................................................................... 168

Method: HTMLInputElement.select()................................................................................................................................... 169

Method: HTMLInputElement.stepDown()........................................................................................................................... 169

Method: HTMLInputElement.stepUp()................................................................................................................................ 170

Object: HTMLIsIndexElement....................................................................................................................................................... 170

HTMLIsIndexElement properties.......................................................................................................................................... 171

Object: HTMLLabelElement........................................................................................................................................................... 171

HTMLLabelElement properties............................................................................................................................................. 171

Object: HTMLLegendElement....................................................................................................................................................... 172

HTMLLegendElement properties.......................................................................................................................................... 172

Object: HTMLLIElement................................................................................................................................................................. 172

HTMLIElement properties...................................................................................................................................................... 173

Object: HTMLLinkElement............................................................................................................................................................. 173

HTMLLinkElement properties................................................................................................................................................ 173

Object: HTMLMapElement............................................................................................................................................................ 174

HTMLMapElement properties............................................................................................................................................... 174

Object: HTMLMenuElement.......................................................................................................................................................... 175

HTMLMenuElement properties............................................................................................................................................. 175

Object: HTMLMetaElement........................................................................................................................................................... 175

HMTLMetaElement properties.............................................................................................................................................. 175

Object: HTMLModElement............................................................................................................................................................ 176

HTMLModElement properties............................................................................................................................................... 176

Object: HTMLObjectElement........................................................................................................................................................ 176

HTMLObjectElement properties........................................................................................................................................... 176

Object: HTMLOListElement........................................................................................................................................................... 178

HTMLOListElement properties............................................................................................................................................. 178

Object: HTMLOptGroupElement.................................................................................................................................................. 178

HTMLOptGroupElement properties..................................................................................................................................... 178

Object: HTMLOptionElement........................................................................................................................................................ 179

HTMLOptionElement properties.......................................................................................................................................... 179

Object: HTMLOptionsCollection................................................................................................................................................... 179

HTMLOptionsCollection properties..................................................................................................................................... 180

HTMLOptionsCollection methods........................................................................................................................................ 180

Method: HTMLOptionsCollection.item()............................................................................................................................. 180

Method: HTMLOptionsCollection.namedItem()................................................................................................................. 181

Method: HTMLOptionsCollection.item()............................................................................................................................. 182

Method: HTMLOptionsCollection.namedItem()................................................................................................................. 182

Object: HTMLParagraphElement.................................................................................................................................................. 183

HTMLParagraphElement properties.................................................................................................................................... 183

Object: HTMLParamElement......................................................................................................................................................... 184

HTMLParamElement properties........................................................................................................................................... 184

Object: HTMLPreElement.............................................................................................................................................................. 184

HTMLPreElement properties................................................................................................................................................. 185

Object: HTMLQuoteElement......................................................................................................................................................... 185

HTMLQuoteElement properties............................................................................................................................................ 185

Object: HTMLScriptElement.......................................................................................................................................................... 185

HTMLScriptElement properties............................................................................................................................................. 186

Object: HTMLSelectElement......................................................................................................................................................... 186

HTMLSelectElement properties............................................................................................................................................ 187

Methods................................................................................................................................................................................... 188

Method: HTMLSelectElement.add()..................................................................................................................................... 188

Method: HTMLSelectElement.blur()..................................................................................................................................... 189

Method: HTMLSelectElement.focus().................................................................................................................................. 190

Method: HTMLSelectElement.remove()............................................................................................................................... 190

Object: HTMLStyleElement........................................................................................................................................................... 191

HTMLStyleElement properties.............................................................................................................................................. 191

Object: HTMLTableCaptionElement............................................................................................................................................. 191

HTMLTableCaptionElement properties................................................................................................................................ 191

Object: HTMLTableCellElement.................................................................................................................................................... 192

HTMLTableCellElement properties....................................................................................................................................... 192

Object: HTMLTableColElement..................................................................................................................................................... 193

HTMLTableColElement properties........................................................................................................................................ 193

Object: HTMLTableElement........................................................................................................................................................... 194

HTMLTableElement properties............................................................................................................................................. 194

HTMLTableElement methods................................................................................................................................................ 195

Method: HTMLTableElement.createCaption().................................................................................................................... 196

Method: HTMLTableElement.createTFoot()........................................................................................................................ 196

Method: HTMLTableElement.createTHead()...................................................................................................................... 197

Method: HTMLTableElement.deleteCaption().................................................................................................................... 197

Method: HTMLTableElement.deleteRow().......................................................................................................................... 198

Method: HTMLTableElement.deleteTFoot()........................................................................................................................ 198

Method: HTMLTableElement.deleteTHead()...................................................................................................................... 199

Method: HTMLTableElement.insertRow()........................................................................................................................... 199

Object: HTMLTableRowElement................................................................................................................................................... 200

HTMLTableRowElement properties...................................................................................................................................... 200

HTMLTableRowElement methods........................................................................................................................................ 201

Method: HTMLTableRowElement.deleteCell().................................................................................................................... 201

Method: HTMLTableRowElement.insertCell()..................................................................................................................... 202

Object: HTMLTableSectionElement.............................................................................................................................................. 203

HTMLTableSectionElement properties................................................................................................................................ 203

HTMLTableSectionElement methods................................................................................................................................... 203

Method: HTMLTableSectionElement.deleteRow()............................................................................................................. 204

Method: HTMLTableSectionElement.insertRow().............................................................................................................. 204

Object: HTMLTextAreaElement..................................................................................................................................................... 205

HTMLTextAreaElement properties....................................................................................................................................... 205

HTMLTextAreaElement methods.......................................................................................................................................... 206

Method: HTMLTextAreaElement.blur()................................................................................................................................ 207

Method: HTMLTextAreaElement.focus()............................................................................................................................. 207

Method: HTMLTextAreaElement.select()............................................................................................................................ 208

Object: HTMLTitleElement............................................................................................................................................................. 208

HTMLTitleElement properties............................................................................................................................................... 208

Object: HTMLUListElement........................................................................................................................................................... 208

HTMLUListElement properties.............................................................................................................................................. 209

Object: KeyboardEvent.................................................................................................................................................................. 209

KeyboardEvent properties..................................................................................................................................................... 209

Keyboard event types............................................................................................................................................................. 210

KeyboardEvent methods........................................................................................................................................................ 211

Method: KeyboardEvent.getModifierState()....................................................................................................................... 211

Method: KeyboardEvent.initKeyboardEvent()..................................................................................................................... 211

Method: KeyboardEvent.initKeyboardEventNS()............................................................................................................... 213

Object: Location.............................................................................................................................................................................. 214

Location properties................................................................................................................................................................. 214

Location methods................................................................................................................................................................... 215

Method: location.assign()...................................................................................................................................................... 215

Method: location.reload()...................................................................................................................................................... 216

Method: location.replace().................................................................................................................................................... 217

Method: location.toString()................................................................................................................................................... 217

Object: MediaList............................................................................................................................................................................ 218

MediaList properties.............................................................................................................................................................. 218

MediaList methods................................................................................................................................................................. 218

Method: MediaList.appendMedium().................................................................................................................................. 219

Method: MediaList.deleteMedium()..................................................................................................................................... 219

Method: MediaList.item()...................................................................................................................................................... 220

Object: MimeType........................................................................................................................................................................... 221

MimeType properties............................................................................................................................................................. 221

Object: MimeTypeArray................................................................................................................................................................. 221

MimeTypeArray properties.................................................................................................................................................... 221

MimeTypeArray methods....................................................................................................................................................... 222

Method: MimeTypeArray.item()............................................................................................................................................ 222

Method: MimeTypeArray.namedItem()............................................................................................................................... 222

Object: MouseEvent....................................................................................................................................................................... 223

MouseEvent properties.......................................................................................................................................................... 223

Mouse event types.................................................................................................................................................................. 224

MouseEvent methods............................................................................................................................................................. 226

Method: MouseEvent.initMouseEvent().............................................................................................................................. 226

Object: MutationEvent................................................................................................................................................................... 228

MutationEvent properties...................................................................................................................................................... 228

Mutation event types............................................................................................................................................................. 229

MutationEvent methods........................................................................................................................................................ 230

Method: MutationEvent.initMutationEvent()...................................................................................................................... 230

Object: NamedFrameMap............................................................................................................................................................. 232

NamedFrameMap properties................................................................................................................................................ 232

NamedFrameMap methods.................................................................................................................................................. 232

Method: NamedFrameMap.item()....................................................................................................................................... 233

Method: NamedFrameMap.getNamedItem()..................................................................................................................... 233

Object: NamedNodeMap............................................................................................................................................................... 234

NamedNodeMap properties................................................................................................................................................. 234

NamedNodeMap methods.................................................................................................................................................... 235

Method: NamedNodeMap.getNamedItem()...................................................................................................................... 235

Method: NamedNodeMap.getNamedItemNS()................................................................................................................. 236

Method: NamedNodeMap.item()......................................................................................................................................... 236

Method: NamedNodeMap.removeNamedItem()............................................................................................................... 237

Method: NamedNodeMap.removeNamedItemNS().......................................................................................................... 238

Method: NamedNodeMap.setNamedItem()....................................................................................................................... 238

Method: NamedNodeMap.setNamedItemNS()................................................................................................................. 239

Object: Navigator........................................................................................................................................................................... 240

Navigator properties.............................................................................................................................................................. 241

Navigator methods................................................................................................................................................................. 242

Method: navigator.javaEnabled()......................................................................................................................................... 242

Object: Node................................................................................................................................................................................... 242

Node properties...................................................................................................................................................................... 243

Node methods........................................................................................................................................................................ 244

Method: Node.removeEventListener()................................................................................................................................. 245

Method: Node.removeChild()............................................................................................................................................... 246

Method: Node.replaceChild()............................................................................................................................................... 247

Method: Node.normalize().................................................................................................................................................... 248

Method: Node.addEventListener()....................................................................................................................................... 248

Method: Node.appendChild()............................................................................................................................................... 249

Method: Node.cloneNode().................................................................................................................................................. 250

Method: Node.dispatchEvent()............................................................................................................................................. 251

Method: Node.hasAttributes().............................................................................................................................................. 252

Method: Node.hasChildNodes()........................................................................................................................................... 252

Method: Node.insertBefore()................................................................................................................................................ 253

Method: Node.isSupported()................................................................................................................................................ 254

Object: NodeFilter.......................................................................................................................................................................... 255

NodeFilter methods............................................................................................................................................................... 255

Method: NodeFilter.acceptNode()....................................................................................................................................... 255

Object: NodeList............................................................................................................................................................................. 256

NodeList properties................................................................................................................................................................ 256

NodeList methods.................................................................................................................................................................. 257

Method: NodeList.item()....................................................................................................................................................... 257

Object: Notation............................................................................................................................................................................. 257

Notation properties................................................................................................................................................................ 258

Object: NodeIterator...................................................................................................................................................................... 258

NodeIterator properties......................................................................................................................................................... 258

NodeIterator methods........................................................................................................................................................... 260

Method: NodeIterator.detach()............................................................................................................................................ 260

Method: NodeIterator.nextNode()....................................................................................................................................... 260

Method: NodeIterator.previousNode()................................................................................................................................ 261

Object: Plugin.................................................................................................................................................................................. 262

Plugin properties.................................................................................................................................................................... 262

Plugin methods....................................................................................................................................................................... 262

Method: Plugin.item()............................................................................................................................................................ 263

Method: Plugin.namedItem()................................................................................................................................................ 263

Object: PluginArray........................................................................................................................................................................ 264

PluginArray properties........................................................................................................................................................... 264

PluginArray methods............................................................................................................................................................. 264

Method: PluginArray.item()................................................................................................................................................... 264

Method: PluginArray.namedItem()...................................................................................................................................... 265

Object: ProcessingInstruction....................................................................................................................................................... 265

ProcessingInstruction properties.......................................................................................................................................... 266

Object: Range.................................................................................................................................................................................. 266

Range properties.................................................................................................................................................................... 267

Range methods....................................................................................................................................................................... 267

Method: Range.cloneContents().......................................................................................................................................... 268

Method: Range.cloneRange()............................................................................................................................................... 269

Method: Range.collapse()..................................................................................................................................................... 269

Method: Range.compareBoundaryPoints()......................................................................................................................... 270

Method: Range.deleteContents()......................................................................................................................................... 271

Method: Range.detach()........................................................................................................................................................ 272

Method: Range.extractContents()........................................................................................................................................ 272

Method: Range.insertNode()................................................................................................................................................ 273

Method: Range.selectNodeContents()................................................................................................................................ 274

Method: Range.selectNode()................................................................................................................................................ 275

Method: Range.setEndAfter()............................................................................................................................................... 275

Method: Range.setEndBefore()............................................................................................................................................ 276

Method: Range.setEnd()........................................................................................................................................................ 277

Method: Range.setStartAfter()............................................................................................................................................. 278

Method: Range.setStartBefore()........................................................................................................................................... 278

Method: Range.setStart()...................................................................................................................................................... 279

Method: Range.surroundContents().................................................................................................................................... 280

Method: Range.toString()...................................................................................................................................................... 281

Object: Rect..................................................................................................................................................................................... 281

Rect properties........................................................................................................................................................................ 282

Object: RGBColor............................................................................................................................................................................ 282

RGBColor properties.............................................................................................................................................................. 282

Object: Screen................................................................................................................................................................................. 283

Screen properties................................................................................................................................................................... 283

Object: Selection............................................................................................................................................................................. 283

Selection properties............................................................................................................................................................... 284

Selection methods.................................................................................................................................................................. 284

Method: Selection.addRange()............................................................................................................................................. 285

Method: Selection.collapseToEnd()...................................................................................................................................... 285

Method: Selection.collapseToStart().................................................................................................................................... 286

Method: Selection.collapse()................................................................................................................................................. 286

Method: Selection.deleteFromDocument()......................................................................................................................... 287

Method: Selection.getRangeAt().......................................................................................................................................... 287

Method: Selection.removeAllRanges()................................................................................................................................ 288

Method: Selection.removeRange()....................................................................................................................................... 288

Method: Selection.selectAllChildren()................................................................................................................................. 289

Object: StyleSheet.......................................................................................................................................................................... 289

StyleSheet properties............................................................................................................................................................. 289

Object: StyleSheetList.................................................................................................................................................................... 291

StyleSheetList properties....................................................................................................................................................... 292

StyleSheetList methods......................................................................................................................................................... 292

Method: StyleSheetList.item().............................................................................................................................................. 292

Object: Text..................................................................................................................................................................................... 293

Text methods........................................................................................................................................................................... 293

Method: Text.splitText()......................................................................................................................................................... 293

Object: TextEvent............................................................................................................................................................................ 294

TextEvent properties.............................................................................................................................................................. 294

Text event types...................................................................................................................................................................... 294

TextEvent methods................................................................................................................................................................. 295

Method: TextEvent.initTextEvent()....................................................................................................................................... 295

Method: TextEvent.initTextEventNS().................................................................................................................................. 295

Object: TreeWalker......................................................................................................................................................................... 296

TreeWalker properties............................................................................................................................................................ 297

TreeWalker methods............................................................................................................................................................... 298

Method: TreeWalker.firstChild()........................................................................................................................................... 299

Method: TreeWalker.lastChild()............................................................................................................................................ 299

Method: TreeWalker.nextNode().......................................................................................................................................... 300

Method: TreeWalker.nextSibling()........................................................................................................................................ 300

Method: TreeWalker.parentNode()...................................................................................................................................... 301

Method: TreeWalker.previousNode()................................................................................................................................... 301

Method: TreeWalker.previousSibling()................................................................................................................................. 302

Object: UIEvent............................................................................................................................................................................... 302

UIEvent properties................................................................................................................................................................. 302

User interface events............................................................................................................................................................. 303

UIEvent methods.................................................................................................................................................................... 303

Method: UIEvent.initUIEvent()............................................................................................................................................. 303

Object: Window............................................................................................................................................................................... 304

Window properties.................................................................................................................................................................. 304

Window event handlers.......................................................................................................................................................... 306

Window methods.................................................................................................................................................................... 310

Method: window.addEventListener()................................................................................................................................... 311

Method: window.alert()......................................................................................................................................................... 312

Method: window.back()......................................................................................................................................................... 312

Method: window.blur()........................................................................................................................................................... 313

Method: window.close()......................................................................................................................................................... 313

Method: window.confirm().................................................................................................................................................... 314

Method: window.dispatchEvent()......................................................................................................................................... 315

Method: window.find()........................................................................................................................................................... 315

Method: window.focus()........................................................................................................................................................ 316

Method: window.forward().................................................................................................................................................... 317

Method: window.getComputedStyle()................................................................................................................................. 317

Method: window.home()........................................................................................................................................................ 318

Method: window.moveBy().................................................................................................................................................... 318

Method: window.moveTo().................................................................................................................................................... 319

Method: window.open()......................................................................................................................................................... 320

Method: window.print()......................................................................................................................................................... 320

Method: window.prompt()..................................................................................................................................................... 321

Method: window.removeEventListener()............................................................................................................................. 321

Method: window.resizeBy()................................................................................................................................................... 322

Method: window.resizeTo()................................................................................................................................................... 323

Method: window.scroll()........................................................................................................................................................ 324

Method: window.scrollBy().................................................................................................................................................... 324

Method: window.scrollTo().................................................................................................................................................... 325

Method: window.stop().......................................................................................................................................................... 326

Object: XMLHttpRequest............................................................................................................................................................... 326

XMLHttpRequest properties................................................................................................................................................. 327

XMLHttpRequest event handlers......................................................................................................................................... 328

XMLHttpRequest methods.................................................................................................................................................... 328

Method: XMLHttpRequest.abort()........................................................................................................................................ 329

Method: XMLHttpRequest.addEventListener()................................................................................................................... 329

Method: XMLHttpRequest.dispatchEvent()........................................................................................................................ 330

Method: XMLHttpRequest.getAllResponseHeaders()....................................................................................................... 331

Method: XMLHttpRequest.getResponseHeader()............................................................................................................. 331

Method: XMLHttpResponse.open()..................................................................................................................................... 332

Method: XMLHttpRequest.removeEventListener()............................................................................................................ 333

Method: XMLHttpRequest.send()........................................................................................................................................ 334

Method: XMLHttpRequest.setRequestHeader()................................................................................................................. 335

Object: XMLSerializer..................................................................................................................................................................... 336

XMLSerializer methods.......................................................................................................................................................... 337

Method: XMLSerializer.serializeToString().......................................................................................................................... 337

3 Glossary......................................................................................................................................................................................... 339

4 Provide feedback......................................................................................................................................................................... 341

5 Legal notice.................................................................................................................................................................................. 342

JavaScript reference overview 1

Supported JavaScript objects: Alphabetical

A

Object Description Availability

Attr Represents an attribute of an Element object. 4.6 or later

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

B

Object Description Availability

blackberry Provides network and global positioning information for a

BlackBerry® device.

3.8 or later

blackberry. launch Provides access to other BlackBerry applications on the

device.

5.0 or later

blackberry. location Provides access to the GPS location information for the

BlackBerry device.

4.1 or later

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

C

Object Description Availability

CDATASection Represents a block of escaped text, such as XML fragments, source code,

or other content that is otherwise interpreted as XML markup.

4.6 or later

CharacterData Accesses character data in the DOM. 4.6 or later

JavaScript Reference JavaScript reference overview

18

Object Description Availability

Comment Represents the contents of a comment within a document. 4.6 or later

Counter Represents any counter or counters function value. 4.6 or later

CSSCharsetRule Represents an @charset rule, which holds an encoding definition. 4.6 or later

CSSFontFaceRule Represents an @font-face rule, which holds a set of font descriptions. 4.6 or later

CSSImportRule Represents an @import rule, which imports style rules from other style

sheets.

4.6 or later

CSSMediaRule Represents an @media rule, which defines style rules for a specific media

type.

4.6 or later

CSSPageRule Represents a @page rule, which specifies the dimensions, orientation,

and margins for paged media.

4.6 or later

CSSPrimitiveValue Represents a single CSS value. 4.6 or later

CSSRule The base class that defines any rule in a CSS style sheet, including rule

sets and @ rules.

4.6 or later

CSSRuleList Represents an ordered collection of CSSRule objects. 4.6 or later

CSSStyleDeclaration Represents a CSS declaration block that consists of CSS properties and

their values.

4.6 or later

CSSStyleRule Represents a single rule set in a CSS style sheet. 4.6 or later

CSSStyleSheet Represents a CSS style sheet. 4.6 or later

CSSUnknownValue Represents an unsupported @ rule. 4.6 or later

CSSValue Represents a simple or complex CSS property value. 4.6 or later

CSSValueList Represents an ordered collection of CSSValue objects. 4.6 or later

CustomEvent Represents an unknown event type, typically application-specific event

types.

4.6 or later

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

D

Object Description Availability

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

4.6 or later

JavaScript Reference Supported JavaScript objects: Alphabetical

19

Object Description Availability

DocumentFragment A lightweight Document object, that creates or extracts only part of a

document.

4.6 or later

DocumentType Represents the doctype for a document. If a document has a doctype, it

will be a reference to this object.

4.6 or later

DOMImplementation Defines the methods for performing the operations that are independent

of any particular instance of the DOM, such as creating new documents.

4.6 or later

DOMParser Enables you to parse strings into a DOM. 4.7.1 or later

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

E

Object Description Availability

Element Represents an element in an HTML or XML document. 4.6 or later

Entity Represents any entity in an XML document. 4.6 or later

EntityReference Represents a reference to an Entity object within the document. 4.6 or later

Event Provides contextual information about an event that event handlers can

use.

4.6 or later

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

occur.

4.6 or later

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

H

Object Description Availability

History Stores an array of the URLs that the user visited during the current

browser session.

4.6 or later

HTMLAnchorElement Represents an <a> element in an HTML document. 4.6 or later

HTMLAppletElement Represents an <applet> element in an HTML document. 4.6 or later

JavaScript Reference Supported JavaScript objects: Alphabetical

20

Object Description Availability

HTMLAreaElement Represents an <area> element in an HTML document. 4.6 or later

HTMLBaseElement Represents a <base> element in an HTML document. 4.6 or later

HTMLBaseFontElement Represent a <basefont> element in an HTML document. 4.6 or later

HTMLBodyElement Represents a <body> element in an HTML document. 4.6 or later

HTMLBRElement Represents a <br> element in an HTML document. 4.6 or later

HTMLButtonElement Represents a <button> element in an HTML document. 4.6 or later

HTMLCollection Contains an ordered collection of nodes, which are updated

automatically when the underlying document is changed.

4.6 or later

HTMLDataListElement Represents a <datalist> element in an HTML document. 4.7.1 or later

HTMLDirectoryElement Represents a <dir> element in an HTML document. 4.6 or later

HTMLDivElement Represents a <div> element in an HTML document. 4.6 or later

HTMLDListElement Represents a <dl> element in an HTML document. 4.6 or later

HTMLDocument Provides access to the HTML hierarchy. 4.6 or later

HTMLElement The parent class of all HTML elements, which represents those HTML

elements which support only core attributes.

4.6 or later

HTMLFieldsetElement Represents a <fieldset> element in an HTML document. 4.6 or later

HTMLFontElement Represents a <font> element in an HTML document. 4.6 or later

HTMLFormElement Represents a <form> element in an HTML document. 4.6 or later

HTMLFrameElement Represents a <frame> element in an HTML frameset. 4.6 or later

HTMLFrameSetElement Represents a <frameset> element in an HTML document. 4.6 or later

HTMLHeadElement Represents a <head> element in an HTML document. 4.6 or later

HTMLHeadingElement Represents a heading element (<h1> to <h6>) in an HTML document. 4.6 or later

HTMLHRElement Represents an <hr> element in an HTML document. 4.6 or later

HTMLHtmlElement Represents an <html> element in an HTML document. 4.6 or later

HTMLIFrameElement Represents an <iframe> element in an HTML document. 4.6 or later

HTMLImageElement Represents an <img> element in an HTML document. 4.6 or later

HTMLInputElement Represents an <input> element in an HTML document. 4.6 or later

HTMLIsIndexElement Represents an <isindex> element in an HTML document. 4.6 or later

HTMLLabelElement Represents a <label> element in an HTML document. 4.6 or later

HTMLLegendElement Represents a <legend> element in an HTML document. 4.6 or later

HTMLLIElement Represents an <li> element in an HTML document. 4.6 or later

HTMLLinkElement Represents a <link> element in an HTML document. 4.6 or later

HTMLMapElement Represents a <map> element in an HTML document. 4.6 or later

JavaScript Reference Supported JavaScript objects: Alphabetical

21

Object Description Availability

HTMLMenuElement Represents a <menu> element in an HTML document. 4.6 or later

HTMLMetaElement Represents a <meta> element in an HTML document. 4.6 or later

HTMLModElement Represents a <del> or <ins> element in an HTML document. 4.6 or later

HTMLObjectElement Represents an <object> element in an HTML document. 4.6 or later

HTMLOListElement Represents an <ol> element in an HTML document. 4.6 or later

HTMLOptGroupElement Represents an <optgroup> element in an HTML document. 4.6 or later

HTMLOptionElement Represents an <option> element in an HTML document. 4.6 or later

HTMLOptionsCollecti

on

Contains an array of HTMLOptionElement objects. 4.6 or later

HTMLParagraphElement Represents a <p> element in an HTML document. 4.6 or later

HTMLParamElement Represents a <param> element in an HTML document. 4.6 or later

HTMLPreElement Represents a <pre> element in an HTML document. 4.6 or later

HTMLQuoteElement Represents a <blockquote> or <q> element in an HTML document. 4.6 or later

HTMLScriptElement Represents a <script> element in an HTML document. 4.6 or later

HTMLSelectElement Represents a <select> element in an HTML document. 4.6 or later

HTMLStyleElement Represents a <style> element in an HTML document. 4.6 or later

HTMLTableCaptionEle

ment

Represents a <caption> element in an HTML document. 4.6 or later

HTMLTableCellElement Represents a <td> or <th> element in an HTML document. 4.6 or later

HTMLTableColElement Represents a <col> or <colgroup> element in an HTML document. 4.6 or later

HTMLTableElement Represents a <table> element in an HTML document. 4.6 or later

HTMLTableRowElement Represents a <tr> element in an HTML document. 4.6 or later

HTMLTableSectionEle

ment

Represents a <tbody>, <tfoot>, or <thead> element in an HTML

document.

4.6 or later

HTMLTextAreaElement Represents a <textarea> element in an HTML document. 4.6 or later

HTMLTitleElement Represents a <title> element in an HTML document. 4.6 or later

HTMLUListElement Represents a <ul> element in an HTML document. 4.6 or later

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

JavaScript Reference Supported JavaScript objects: Alphabetical

22

K

Object Description Availability

KeyboardEvent Represents an event generated by the BlackBerry® device keyboard. 4.6 or later

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

L

Object Description Availability

Location Accesses the URL of the web page that is currently displayed in the

BlackBerry® Browser.

4.6 or later

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

M

Object Description Availability

MediaList Represents an ordered collection of media. An empty list is equivalent

to a list that contains a value of all.

4.6 or later

MimeType Represents a MIME type specification. 4.6 or later

MimeTypeArray Contains an ordered collection of MIME types. 4.6 or later

MouseEvent Represents an event that is generated by the BlackBerry® device

trackball, trackwheel, or touch screen.

4.6 or later

MutationEvent Represents an event that is generated when the structure of the

document is modified.

4.6 or later

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

JavaScript Reference Supported JavaScript objects: Alphabetical

23

N

Object Description Availability

NamedFrameMap Represents a collection of frames that can be accessed by name. 4.6 or later

NamedNodeMap Represents a collection of nodes that can be accessed by name. 4.6 or later

Navigator Provides information about the version of the BlackBerry® Browser. 4.6 or later

Node Represents a unique node within the DOM tree, and is the primary data

type for the DOM.

4.6 or later

NodeFilter Specifies which nodes should be filtered when a document is traversed. 4.6 or later

NodeIterator Enables navigation up and down through a flat representation of the

document tree.

4.6 or later

NodeList Contains an ordered collection of nodes. 4.6 or later

Notation Represents a notation that is declared in a DTD. 4.6 or later

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

P

Object Description Availability

Plugin Represents an installed plug-in. 4.6 or later

PluginArray Contains an ordered collection of Plugin objects. 4.6 or later

ProcessingInstructi

on

Represents a processing instruction for an XML document. 4.6 or later

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

JavaScript Reference Supported JavaScript objects: Alphabetical

24

R

Object Description Availability

Range Represents a range of content between two boundary points, a start point

and an end point, in a Document, DocumentFragment, or Attr

node.

4.7.1 or later

Rect Represents a Rect value. 4.6 or later

RGBColor Represents an RGB color value. 4.6 or later

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

S

Object Description Availability

Screen Returns information about the dimensions and the color depth of the

BlackBerry® device display.

4.6 or later

Selection Contains a Range object. 4.7.1 or later

Stylesheet Represents a single external or inline style sheet that is associated with

a document.

4.6 or later

StylesheetList Represents an ordered collection of StyleSheet objects. 4.6 or later

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

T

Object Description Availability

Text Represents the text contents of an element or attribute. 4.6 or later

TextEvent Represents an event that is generated by entering characters using the

BlackBerry® keyboard or an input source such as a voice command.

4.6 or later

JavaScript Reference Supported JavaScript objects: Alphabetical

25

Object Description Availability

TreeWalker Enables you to navigate the document tree or subtree. 4.6 or later

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

U

Object Description Availability

UIEvent Represents a UI event that is generated by user interaction with the

trackwheel, trackball, touch screen, or keyboard on a BlackBerry device

keyboard.

4.6 or later

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

W

Object Description Availability

Window Returns information about the browser window. 3.8 or later

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

X

Object Description Availability

XMLHttpRequest Enables you to transfer data to and from a server without reloading or

replacing the current document.

4.6 or later

XMLSerializer Enables you to convert a DOM document or a DOM subtree into a string. 4.7.1 or later

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

JavaScript Reference Supported JavaScript objects: Alphabetical

26

JavaScript objects 2

Object: Attr

Availability BlackBerry® Device Software version 4.6 or later

Extends Node

The Attr object represents an attribute in an Element object.

Although Attr objects describe Element objects, they are not actually child nodes of the element they describe. Instead,attributes are treated as properties of elements, and reside outside of the DOM tree. As a result, the Node.parentNode ,Node.previousSibling , and Node.nextSibling properties are null for Attr objects.

If a declaration for an attribute exists that defines a default value, but that attribute does not yet exist, the attribute is automaticallycreated and attached to an element with the given value.

Attr properties

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

ownerElement Element Returns the element node that this attribute is attached

to. If the attribute is not yet attached to an element, the

value of this property is null.

read only 4.6 or later

specified boolean When true, this property indicates that the value for the

attribute has been explicitly set.

If the attribute exists with a default value, this property

has a value of false.

read only 4.6 or later

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

JavaScript Reference JavaScript objects

27

Object: blackberry

Availability BlackBerry® Device Software version 4.0 or later

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

blackberry properties

Property name Type Description Status Availability

location blackberry.loc

ation

Returns a pointer to the

blackberry.location object.

This property is available for BlackBerry® Device

Software Version 4.1 or later.

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

read only 4.0 or later

JavaScript Reference Object: blackberry

28

Object: blackberry.launch

Availability BlackBerry® Device Software 5.0 or later

The blackberry.launch object provides methods that lets you access core and add-on BlackBerry® applications throughJavaScript®. Depending on the application, you can either launch the application or open the application and create a new item,such as a calendar entry or a task, and prepopulate any of the entry fields. Although the methods of theblackberry.launch object can open and create new items for an application, changes are not made to the applicationwithout confirmation from the user. For example, if you use the blackberry.launch object to make a phone call to a specificphone number, the user is prompted to confirm whether the user wants to proceed with the call before the number is dialed.Similarly, if you create a new item for any application, the user must save the item before it is added to that application.

Parameters for the blackberry.launch methods are provided in the form of a single JSON object. For example, to openBlackBerry® Maps and display a set of coordinates, you could use the blackberry.launch.newMap() method as follows:

blackberry.launch.newMap({"latitude":4328915, "longitude":-8032480});

When a JSON object is identified as the parameter of a method, it is required. However, the members contained within the JSONobject are all optional. For example, you can specify an empty JSON object as the parameter to a method, as long as the JSONobject (identified by the braces) is present. For example:

blackberry.launch.newMap({});

blackberry.launch methods

Method name Description Availability

launchCamera() Opens the Camera application. 5.0 or later

launchVideoRedorder() Opens the Video Camera application. 5.0 or later

launchVoicemail() Opens the Phone application to call the voice mail account that is

associated with the BlackBerry® device.

5.0 or later

newAppointment() Creates a new appointment in the Calendar application. 5.0 or later

newContact() Adds a new contact to the Contacts list. 5.0 or later

newMap() Opens the BlackBerry® Maps application and displays the specified

location.

5.0 or later

newMemo() Creates a new memo in the Memo application. 5.0 or later

newPhoneCall() Opens the phone application to call a specific phone number. 5.0 or later

newSMS() Creates a new SMS text message. 5.0 or later

JavaScript Reference Object: blackberry.launch

29

Method name Description Availability

newTask() Creates a new task in the Tasks application. 5.0 or later

Method: blackberry.launch.launchCamera()

Availability BlackBerry® Device Software 5.0 or later

The launchCamera() method permits you to open the camera application on the BlackBerry® device.

Syntaxblackberry.launch.launchCamera()

ParametersNone.

Return valuesNone.

Code sample: Opening the camera application on the BlackBerry device<html> <body> <div id="camera" onClick="blackberry.launch.launchCamera()">Click here to start the camera application on your BlackBerry device!</div> </body></html>

Method: blackberry.launch.launchVideoRecorder()

Availability BlackBerry® Device Software 5.0 or later

The launchVideoRecorder() method opens the video recorder on the BlackBerry device.

Syntaxblackberry.launch.launchVideoRecorder()

ParametersNone.

Return values

JavaScript Reference Object: blackberry.launch

30

None.

Code sample: Opening the video recorder application<html> <body> <div id="video" onClick="blackberry.launch.launchVideoRecorder()">Click here to launch the video recorder on your BlackBerry device!</div> </body></html>

Method: blackberry.launch.launchVoicemail()

Availability BlackBerry® Device Software 5.0 or later

The launchVoicemail() method permits you to call the voice mail account that is associated with a BlackBerry® device.Before the call is placed, the phone application prompts the user to confirm whether they want to proceed with the call.

Syntaxblackberry.launch.launchVoicemail()

ParametersNone.

Return valuesNone.

Code sample: Calling the BlackBerry device user's voice mail using JavaScript<html> <body> <div id="voicemail" onClick="blackberry.launch.launchVoicemail()">Click here to check your messages.</div> </body></html>

Method: blackberry.launch.newAppointment()

Availability BlackBerry® Device Software 5.0 or later

The newAppointment() method creates a new appointment in the calendar application. The user must save the appointmentbefore it is saved to the calendar.

Syntax

JavaScript Reference Object: blackberry.launch

31

blackberry.launch.newAppointment({ summary, location, allDay, start, end, freeBusy, note })

JSON object members

Member Type Description

summary String Briefly summarizes the reason for the appointment. This value is used to identify

this appointment in the calendar.

location String Specifies the location of the appointment.

allDay Boolean When true, indicates whether the appointment should be scheduled for the whole

day. An all-day event is considered an entire work day, from 9:00 AM to 5:00 PM.

start Date Specifies the start time of the appointment.

end Date Specifies the end time of the appointment.

freeBusy integer Specifies how the time is marked in the user's calendar. You can specify one of the

following values:

• 0: free

• 1: busy

• 2: tentative

• 3: out of office

note String Specifies text that is included as a part of the appointment.

Return valuesNone.

ExceptionsNone.

Code sample: Creating a new appointment for the calendar application// Define the start and end times as JavaScript Date objectsvar startTime = new Date(2010,10,10,2);var endTime = new Date(2010,0,1,3,29);

// Create the JSON object that defines all the appointment // information as name-value pairs var appointmentInfo = { "summary":"Meet new VP" "location":"Conference room 2" "allDay":false "start":startTime "end":endTime "freeBusy":1

JavaScript Reference Object: blackberry.launch

32

"note":"Refreshments will be served."};

// Create a new appointment with the new JSON object as a parameterblackberry.launch.newAppointment(appointmentInfo);

Method: blackberry.launch.newContact()

Availability BlackBerry® Device Software 5.0 or later

The newContact() method creates a contact in the BlackBerry device user's contact list. The user must save the new contactbefore it is added to the contact list.

Syntaxblackberry.launch.newContact({ title, firstName, lastName, company, jobTitle, email, workPhone, workPhone2, homePhone, homePhone2, mobilePhone, pagerPhone, faxPhone, otherPhone, pin, workAddress, homeAddress, birthday, anniversary, webpage, user1, user2, user3, user4, note })

JSON object members

Member Type Description

title String Specifies the contact's title, such as Mr, Mrs, or Dr.

firstName, lastName String Specify the contact's first name and last name.

company integer Specifies the organization that the contact belongs to.

jobTitle String Specifies a job title for the contact.

email array Specifies an array of email addresses for the contact. The array contains a

comma-separated list of strings, each representing an email address. The

contents of the array are enclosed in brackets. For example:

["email1@company1.com", "email2@company2.com"]

workPhone,

workPhone2,

homePhone,

homePhone2,

mobilePhone,

String Specify assorted phone numbers for the contact.

JavaScript Reference Object: blackberry.launch

33

Member Type Description

pagerPhone,

faxPhone,

otherPhone

pin String Specifies a BlackBerry device PIN for the contact.

workAddress,

homeAddress

Address Specify various addresses for the contact, represented by an Address JSON

object.

birthday,

anniversary

Date Specify important dates for the contact, represented by a JavaScript® Date

object.

webpage String Specifies a web page for the contact.

user1, user2, user3,

user4, note

String Specify additional information for the contact.

Return valuesNone.

ExceptionsNone.

Code sample: Creating a new contactvar workAddress = { "address1":"295 Phillip Street", "city":"Waterloo", "country":"Canada", "stateProvince":"ON", "zipPostal":"N2L3WE"};var bday = new Date(1978,3,22);

var contactInfo={ "title":"Ms" "firstName":"Karen" "lastName":"Moser" "email":[ "too_cool@internet.com", "KM_2@work.com" ] "pin":"2100000A" "workAddress":workAddress "birthDay":bday};blackberry.launch.newContact(contactInfo);

JavaScript Reference Object: blackberry.launch

34

Method: blackberry.launch.newMap()

Availability BlackBerry® Device Software5.0 or later

The newMap() method opens BlackBerry® Maps and displays a specified location on the map. You can specify a location usingone of three following ways:

• specify the latitude and longitude• specify an address• specify a location document

Syntaxblackberry.launch.newMap({ latitude, longitude })

OR

blackberry.launch.newMap({ address })

OR

blackberry.launch.newMap({ locationDocument })

JSON object members

Member Type Description

latitude double Specifies the latitude in decimal degrees to five decimal places, multiplied by

100,000. A negative value indicates a southern latitude.

For example, to indicate a latitude of 43°N, specify a value of 4,300,000.

longitude double Specifies the longitude in decimal degrees to five decimal places, multiplied by

100,000. A negative value indicates a western longitude.

For example, to indicate a longitude of 80°W, specify a value of -8,000,000.

address Address Specifies address information, represented by an Address JSON object.

locationDocument String Specifies an XML location document. This XML structure is specific to BlackBerry

Maps.

Return valuesNone.

Exceptions

JavaScript Reference Object: blackberry.launch

35

None.

Code sample: Displaying a set of geographic coordinates in BlackBerry Mapsblackberry.launch.newMap({ "latitude":4346518, "longitude":-8052237});

Code sample: Displaying an address in BlackBerry Mapsvar workAddress = { "address1":"295 Phillip Street", "city":"Waterloo", "country":"Canada", "stateProvince":"ON", "zipPostal":"N2L3WE"};

blackberry.launch.newMap({"address":workAddress});

Code sample: Displaying a location document in BlackBerry Mapsblackberry.launch.newMap({ "locationDocument":"<lbs id=\"Waterloo\"> <location x=\"-8052237\" y=\"4346518\" label=\"Waterloo, ON\" description=\"Waterloo\" zoom=\"10\" \/> <\/lbs>" });

Method: blackberry.launch.newMemo()

Availability BlackBerry® Device Software 5.0 or later

The newMemo() opens the memo application and creates a new memo item.

Syntaxblackberry.launch.newMemo({ title, note })

JSON object members

Member Type Description

title String Specifies the title for the memo. This value is used to identify this memo in the list

of memo items in the memo application.

note String Specifies the memo text.

Return values

JavaScript Reference Object: blackberry.launch

36

None.

Code sample: Creating a new memoblackberry.launch.newMemo({ "title":"Note to self", "note":"The rain in spain falls mainly on the plain" });

Method: blackberry.launch.newPhoneCall()

Availability BlackBerry® Device Software 5.0 or later

The newPhoneCall() method opens the phone application to call a specified phone number.

Syntaxblackberry.launch.newPhoneCall({ dialString, smartDialing })

JSON object members

Member Type Description

dialString String Specifies the phone number to call. The phone number is specified as a string and

must be enclosed by quotation marks.

smartDialing Boolean When true, indicates that the phone application should apply the Smart Dialing

options that the BlackBerry device user specified in the Phone options. Smart dialing

permits the user to configure a default country code and area code for phone numbers.

The phone application prepends these values automatically when it dials a phone

number.

Return valuesNone.

ExceptionsNone.

Code sample: Making a phone call<html> <body> <div id="phone" onClick="blackberry.launch.newPhoneCall({ "dialString":"15198887465", "smartDialing":false })"> <p>Click here to call now!</p>

JavaScript Reference Object: blackberry.launch

37

</div> </body></html>

Method: blackberry.launch.newSMS()

Availability BlackBerry® Device Software 5.0 or later

The newSMS() method creates a new SMS text message that a user can send to a specified phone number.

This method does not send the SMS text message. The user must send the SMS text message manually.

Syntaxblackberry.launch.newSMS({ number, text })

JSON object members

Member Type Description

number String The number to send the SMS text message to. The number is specified as a string

and must be enclosed by quotation marks.

text String The text in the SMS text message to send to the specified number.

Return valuesNone.

ExceptionsNone.

Code sample: Sending an SMS messageblackberry.launch.newSMS({ "number":"5198887465", "text":"This is a very important message!" });

Method: blackberry.launch.newTask()

Availability BlackBerry® Device Software 5.0 or later

The newTask() method creates a new task in the tasks application.

Syntax

JavaScript Reference Object: blackberry.launch

38

blackberry.launch.newTask({ summary, status, priority, due, note })

JSON object members

Member Type Description

summary String Briefly summarizes the purpose of the task. This value is used to identify this task

in the tasks application.

status integer Specifies the current status of the task. This parameter can have one of the

following values:

• 0: Not started

• 1: In progress

• 2: Completed

• 3: Waiting

• 4: Deferred

priority integer Specifies the priority of the task. This parameter can have one of the following

values:

• 0: High

• 1: Normal

• 2: Low

due Date Specifies a JavaScript® Date object that represents the due date of the task.

note String Specifies a detailed description of the task.

Return valuesNone.

ExceptionsNone.

Code sample: Creating a new task// set the task completion date for one week from today var currentDate = new Date();var DateInMilliseconds = currentDate.getTime();var completeDate = DateInMilliseconds + 604 800 000;

// Create a JSON object that specifies the task propertiesvar taskProperties = { "summary":"Create new business proposal", "status":0, "priority":0,

JavaScript Reference Object: blackberry.launch

39

"due":completeDate, "note":"Complete this proposal on time!!"};

// create a new task with the new JSON object as a parameterblackberry.launch.newTask(taskProperties);

JSON Object: Address

Availability BlackBerry® Device Software 5.0 or later

The Address object is a JSON object that contains address information used by the methods of the blackberry.launchobject.

Syntax{ address1, address2, city, stateProvince, country, zipPostal }

JSON object members

Member Type Description

address1 String Specifies the street address.

address2 String Specifies additional address information.

city String Specifies the city that the address is located in.

stateProvince String Specifies the state or province that the address is located in.

country String Specifies the country that the address is located in.

zipPostal String Specifies the zip code or postal code of the address.

Object: blackberry.location

Availability BlackBerry® Device Software version 4.1 or later

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

JavaScript Reference Object: blackberry.location

40

blackberry.location properties

Property name Type Description Status Availability

GPSSupported boolean When true, this property indicates that GPS positioning

is supported by the BlackBerry® device.

read only 4.1 or later

latitude double Returns the current latitude, in degrees, of the

BlackBerry device. Positive values indicate northern

latitude, negative values indicate southern latitude.

To ensure that the most accurate co-ordinate is

returned, you should register a listener using

blackberry.location.onLocationUpdate

() and acquire the location information within the

callback.

read only 4.1 or later

longitude double Returns the current longitude, in degrees, of the

BlackBerry device. Positive values indicate eastern

longitude, negative values indicate western longitude.

To ensure that the most accurate co-ordinate is

returned, you should register a listener using

blackberry.location.onLocationUpdate

() and read acquire the location information within

the callback.

read only 4.1 or later

timestamp unsigned

long

Returns time (in milliseconds since epoch) at which the

blackberry.location object was updated.

This property is only supported on BlackBerry devices

running BlackBerry® Device Software version 4.6 or

later.

read only 4.6 or later

JavaScript Reference Object: blackberry.location

41

blackberry.location methods

Method name Description Availability

onLocationUpdate() Registers a callback method that is called when the location is updated

using blackberry.location.refreshLocation().

4.1 or later

refreshLocation() Requests an update of the location of the BlackBerry® device. 4.1 or later

removeLocationUpdate

()

Removes a previously registered callback method. 4.6 or later

setAidMode() Specifies which method the BlackBerry device will use to obtain the GPS

location.

4.1 or later

Method: blackberry.location.onLocationUpdate()

Availability BlackBerry® Device Software version 4.1 or later

The onLocationUpdate() method registers a listener that evaluates a string or calls a 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 asa string that is evaluated each time the location is refreshed. On BlackBerry devices running BlackBerry Device Software version4.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 callbackusing blackberry.location.removeLocationUpdate() . If you have passed a string, the callback cannot be removed.

Syntaxblackberry.location.onLocationUpdate( callbackFunction | callbackString )

Parameters

Parameter Type Description

callbackFunction Function A JavaScript® function.

For BlackBerry devices running versions of the BlackBerry Device

Software that are earlier than version 4.6, you must specify the

callback as a string.

JavaScript Reference Object: blackberry.location

42

Parameter Type Description

callbackString String A string to be evaluated when the location information is

updated.

Return valuesNone.

ExceptionsNone.

See alsoblackberry.location.refreshLocation() , blackberry.location.removeLocationUpdate()

Method: blackberry.location.refreshLocation()

Availability BlackBerry® Device Software version 4.1 or later

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. Toensure that location information is updated before reading it, you should first register a listener usingblackberry.location.onLocationUpdate() that reads blackberry.location.latitude andblackberry.location.longitude , and then call refreshLocation() afterwards.

Syntaxblackberry.location.refreshLocation()

ParametersNone.

Return valuesReturns true if the GPS location of the BlackBerry device is successfully updated; otherwise, returns false.

ExceptionsNone.

See alsoblackberry.location.onLocationUpdate() , blackberry.location.removeLocationUpdate()

JavaScript Reference Object: blackberry.location

43

Method: blackberry.location.removeLocationUpdate()

Availability BlackBerry® Device Software version 4.6 or later

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

Parameter Type Description

callbackFunction Function A JavaScript® function previously registered by

blackberry.location.onLocationUpdate() .

Return valuesNone.

ExceptionsNone.

See alsoblackberry.location.onLocationUpdate() , blackberry.location.refreshLocation()

Method: blackberry.location.setAidMode()

Availability BlackBerry® Device Software version 4.1 or later

The setAidMode() method specifies which method the BlackBerry® device will use to obtain the GPS location.

The device can obtain location information in one of three ways.

Aid Mode Value Description

Cellsite 0 This method uses the GPS location of the active cellsite tower to provide first order GPS

information. It provides the least accurate location information; however, it is the fastest

location mode.

JavaScript Reference Object: blackberry.location

44

Aid Mode Value Description

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.

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.

Syntaxblackberry.location.setAidMode( aidMode )

Parameters

Parameter Type Description

aidMode int The method used to obtain the GPS location. The value for this

parameter may be one of:

• 0 — Cellsite

• 1 — Assisted

• 2 — Autonomous

Return valuesNone.

Object: CDATASection

Availability BlackBerry® Device Software version 4.6 or later

Extends Text

The CDATASection object represents CDATA sections, which escape entire blocks of text, such as XML fragments, source code,or other content that would otherwise be interpreted as XML markup. Only the strings <![CDATA[ (which represents the startof 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.

JavaScript Reference Object: CDATASection

45

Object: CharacterData

Availability BlackBerry® Device Software version 4.6 or later

Extends Node

Extended by Comment , Text

The CharacterData object extends the Node object and can be used to access character data in the DOM. No DOM objectsdirectly correspond to CharacterData; rather, the methods and properties are always inherited by other objects that requirethis 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 textranges, and manipulate ranges of text as a sequence of 16-bit units. Before invoking these methods, you should already knowthe ranges that you are manipulating.

CharacterData properties

Property name Type Description Status Availability

data String Specifies the character data of the current node. writable 4.6 or later

length int Returns the length of the content of the data property or

the CharacterData.substringData() method.

read only 4.6 or later

CharacterData methods

Method name Description Availability

appendData() Appends the given string to the end of the data of the node. 4.6 or later

deleteData() Removes the specified range of data. 4.6 or later

insertData() Inserts a string at the specified location in the data. 4.6 or later

replaceData() Replaces the specified range of data with the given string. 4.6 or later

substringData() Returns the specified range of data from the node. 4.6 or later

JavaScript Reference Object: CharacterData

46

Method: CharacterData.appendData()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxCharacterData.appendData( arg )

Parameters

Parameter Type Description

arg String The string to append.

Return valuesNone.

Exceptions

Exception Description

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

Method: CharacterData.deleteData()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxCharacterData.deleteData( offset, count )

Parameters

Parameter Type Description

offset int The offset position from which to start removing.

JavaScript Reference Object: CharacterData

47

Parameter Type Description

count int The number of 16-bit units to delete. If the sum of offset and count exceeds

the length of the data, then all 16-bit units from the offset to the end of the data

are deleted.

Return valuesNone.

Exceptions

Exception Description

INDEX_SIZE_ERR This error is thrown if offset is negative, or is greater than the number of 16-

bit units in the data.

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

Method: CharacterData.insertData()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxCharacterData.insertData( offset, arg )

Parameters

Parameter Type Description

offset int The offset position from which to start inserting.

arg String The string to insert.

Return valuesNone.

Exceptions

Exception Description

INDEX_SIZE_ERR This error is thrown if offset is negative, or is greater than the number of

16-bit units in the data.

JavaScript Reference Object: CharacterData

48

Exception Description

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

Method: CharacterData.replaceData()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxCharacterData.replaceData( offset, count, arg )

Parameters

Parameter Type Description

offset int The offset position from which to start replacing.

count int The number of 16-bit units to replace. If the sum of offset and countexceeds the length of the data, then all 16-bit units from the offset to the

end of the data are replaced.

arg String The string with which to replace to the data.

Return valuesNone.

Exceptions

Exception Description

INDEX_SIZE_ERR This error is thrown if offset is negative, or is greater than the number

of 16-bit units in the data.

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

JavaScript Reference Object: CharacterData

49

Method: CharacterData.substringData()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxCharacterData.substringData( offset, count )

Parameters

Parameter Type Description

offset int The offset position from which to start extracting.

count int The number of 16-bit units to extract. If the sum of offset and countexceeds the length of the data, then all 16-bit units from the offset to the end

of the data are extracted.

Return valuesReturns the specified range of data.

Exceptions

Exception Description

INDEX_SIZE_ERR This error is thrown if offset is negative, or is greater than the number of

16-bit units in the data.

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

Object: Comment

Availability BlackBerry® Device Software version 4.6 or later

Extends CharacterData

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

JavaScript Reference Object: Comment

50

Object: Counter

Availability BlackBerry® Device Software version 4.6 or later

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

Counter properties

Property name Type Description Status Availability

identifier String Returns the identifier of the counter. read only 4.6 or later

listStyle String Returns the style of the list. read only 4.6 or later

separator String Returns the string used to separate nested counters. read only 4.6 or later

Object: CSSCharsetRule

Availability BlackBerry® Device Software version 4.6 or later

Extends CSSRule

The CSSCharsetRule object represents an @charset rule in a CSS style sheet. The @charset rule holds an encoding definition.

The value of the encoding property does not affect the encoding of text data in the DOM objects; this encoding is alwaysUTF-16. After a style sheet is loaded, the value of the encoding property is the value found in the @charset rule. If there wasno @charset in the original document, then no CSSCharsetRule object is created. The value of the encoding property mayalso 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 object) may not correspond to the encoding thedocument actually came in; character encoding information, for example, in an HTTP header, has priority but this is not reflectedin the CSSCharsetRule.

CSSCharsetRule properties

Property name Type Description Status Availability

encoding String Specifies the encoding used in the @charset rule. writable 4.6 or later

JavaScript Reference Object: Counter

51

Object: CSSFontFaceRule

Availability BlackBerry® Device Software version 4.6 or later

Extends CSSRule

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

CSSFontFaceRule properties

Property name Type Description Status Availability

style CSSStyleDeclar

ation

Returns the declaration block for this rule. read only 4.6 or later

Object: CSSImportRule

Availability BlackBerry® Device Software version 4.6 or later

Extends CSSRule

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

CSSImportRule properties

Property name Type Description Status Availability

href String Returns the location of the style sheet to be imported.

The attribute does not contain the “url(...)” specifier

around the URI.

read only 4.6 or later

media MediaList Returns a list of media types that this style sheet can

be used with.

read only 4.6 or later

styleSheet CSSStyleShe

et

Returns a pointer to the CSSStyleSheet object

that represents the imported style sheet.

read only 4.6 or later

JavaScript Reference Object: CSSFontFaceRule

52

Object: CSSMediaRule

Availability BlackBerry® Device Software version 4.6 or later

Extends CSSRule

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

CSSMediaRule properties

Property name Type Description StatusAvailabilit

y

CSSRules CSSRuleList Returns a list of the CSS rules contained within a

media block.

read only 4.6 or later

media MediaList Returns a list of media types that this style sheet

can be used with.

read only 4.6 or later

CSSMediaRule methods

Method name Description Availability

deleteRule() Removes a rule from the media block. 4.6 or later

insertRule() Adds a rule to the media block. 4.6 or later

Method: CSSMediaRule.deleteRule()

Availability BlackBerry® Device Software version 4.6 or later

The deleteRule() method removes the media block within a CSS style sheet.

SyntaxCSSMediaRule.deleteRule( index )

Parameters

JavaScript Reference Object: CSSMediaRule

53

Parameter Type Description

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

Return valuesNone.

Exceptions

Exception Description

INDEX_SIZE_ERR This error is thrown if index does not correspond to any rule in the media

block’s collection of rules.

NO_MODIFICATION_ALLOWED_ERR This error is thrown if the media rule is read only.

Method: CSSMediaRule.insertRule()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxCSSMediaRule.insertRule( rule, index )

Parameters

Parameter Type Description

rule String The text representing the rule. For rule sets, this contains both the selector and

the style declaration. For at rules, this contains both the at-identifier and the rule

content.

index int The position of the rule in the media block’s collection of rules before which to

insert the new rule.

If index is equal to the length of the index, the new rule will be added to the

end of the media block.

Return valuesReturns the index position of the newly added rule.

Exceptions

JavaScript Reference Object: CSSMediaRule

54

Exception Description

HIERARCHY_REQUEST_ERR This error is thrown if rule is not permitted at the specified index , for example,

if you tried to insert an @import rule after a standard rule set or other at-rule.

INDEX_SIZE_ERR This error is thrown if index does not correspond to any rule in the media block’s

collection of rules.

NO_MODIFICATION_ALLOWED_ERR This error is thrown if the media rule is read only.

SYNTAX_ERR The error is thrown if the rule has a syntax error and cannot be parsed.

Object: CSSPageRule

Availability BlackBerry® Device Software version 4.6 or later

Extends CSSRule

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

CSSPageRule properties

Property name Type Description Status Availability

selectorText String Specifies the page selector for the rule. writable 4.6 or later

style CSSStyleDecla

ration

Returns the declaration block of the rule. read only 4.6 or later

Object: CSSPrimitiveValue

Availability BlackBerry® Device Software version 4.6 or later

Extends CSSValue

The CSSPrimitiveValue object represents a single CSS value. A CSSPrimitiveValue object only occurs in the contextof a CSS property.

JavaScript Reference Object: CSSPageRule

55

This object has methods to determine the current value of a specific style property, or to explicitly set a style property. Conversionsare allowed between absolute values (from millimeters to centimeters, from degrees to radians, and so on) but not betweenrelative values. For example, a pixel value cannot be converted to a centimeter value. With the exception of values representingcolors, 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 convertedto a number.

CSSPrimitiveValue properties

Property name Type Description Status Availability

primitiveTy

pe

unsigned short Returns 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.

read only 4.6 or later

JavaScript Reference Object: CSSPrimitiveValue

56

Property name Type Description Status Availability

• 17 = CSS_KHZ: A frequency, in kiloHertz.

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

function.

CSSPrimitiveValue methods

Method name Description Availability

getCounterValue() Retrieves a Counter value. 4.6 or later

getFloatValue() Retrieves a float value. 4.6 or later

getRectValue() Retrieves a Rect value. 4.6 or later

getRGBColorValue() Retrieves an RGBColor value. 4.6 or later

getStringValue() Retrieves a string value. 4.6 or later

setFloatValue() Sets a float value with the specified unit. 4.6 or later

setStringValue() Sets a string value with the specified unit. 4.6 or later

JavaScript Reference Object: CSSPrimitiveValue

57

Method: CSSPrimitiveValue.getCounterValue()

Availability BlackBerry® Device Software version 4.6 or later

The getCounterValue() method retrieves a Counter value.

SyntaxCSSPrimitiveValue.getCounterValue()

ParametersNone.

Return valuesReturns a Counter object representing the value of a CSS_COUNTER.

Exceptions

Exception Description

INVALID_ACCESS_ERR This error is thrown if the CSS value contains no Counter value (that is, if it is

not of type CSS_COUNTER ).

See AlsoCounter

Method: CSSPrimitiveValue.getFloatValue()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxCSSPrimitiveValue.getFloatValue( unitType )

Parameters

JavaScript Reference Object: CSSPrimitiveValue

58

Parameter Type Description

unitType unsigned short The unit code of the units into which the value

should be converted. The unit code must

represent one of the following float unit types:

• 0 = CSS_UNKNOWN: The value is not

recognized.

• 1 = CSS_NUMBER: A simple number

value.

• 2 = CSS_PERCENTAGE: A percentage

value.

• 3 = CSS_EMS: A length value, based on

font size.

• 4 = CSS_EXS: A length value, based on

font x-height.

• 5 = CSS_PX: A length value, in pixels.

• 6 = CSS_CM: A length value, in

centimeters.

• 7 = CSS_MM: A length value, in

millimeters.

• 8 = CSS_IN: A length value, in inches.

• 9 = CSS_PT: A length value, in points.

• 10 = CSS_PC: A length value, in picas.

• 11 = CSS_DEG: An angle value, in

degrees.

• 12 = CSS_RAD: An angle value, in

radians.

• 13 = CSS_GRAD: An angle value, in

grads.

• 14 = CSS_MS: A time value, in

milliseconds.

• 15 = CSS_S: A time value, in seconds.

JavaScript Reference Object: CSSPrimitiveValue

59

Parameter Type Description

• 16 = CSS_HZ: A frequency value, in

Hertz.

• 17 = CSS_KHZ: A frequency, in

kiloHertz.

• 18 = CSS_DIMENSION: A number value

of an unknown dimension.

Return valuesReturns the float value in the given units.

Exceptions

Exception Description

INVALID_ACCESS_ERR This error is thrown if the CSS value contains no float value (that is, if it is not of

type CSS_NUMBER, CSS_PERCENTAGE, CSS_EMS, CSS_EXS, CSS_PX,

CSS_CM, CSS_MM, CSS_IN, CSS_PT, CSS_PC, CSS_DEG, CSS_RAD,

CSS_GRAD, CSS_MS, CSS_S, CSS_HZ, CSS_KHZ, or CSS_DIMENSION), or if

the float value cannot be converted into the specified units.

See AlsoCSSPrimitiveValue.setFloatValue()

Method: CSSPrimitiveValue.getRectValue()

Availability BlackBerry® Device Software version 4.6 or later

The getRectValue() method retrieves a Rect value.

SyntaxCSSPrimitiveValue.getRectValue()

ParametersNone.

Return values

JavaScript Reference Object: CSSPrimitiveValue

60

Returns a Rect object representing the value of a CSS_RECT.

Exceptions

Exception Description

INVALID_ACCESS_ERR This error is thrown if the CSS value contains no Rect value (that is, if it is not

of type CSS_RECT).

See AlsoRect

Method: CSSPrimitiveValue.getRGBColorValue()

Availability BlackBerry® Device Software version 4.6 or later

The getRGBColorValue() method retrieves an RGBColor value.

SyntaxCSSPrimitiveValue.getRGBColorValue()

ParametersNone.

Return valuesReturns an RGBColor object representing the value of a CSS_RGBCOLOR.

Exceptions

Exception Description

INVALID_ACCESS_ERR This error is thrown if the CSS value contains no RGB color value (that is, if it

is not of type

CSS_RGB_COLOR).

See AlsoRGBColor

JavaScript Reference Object: CSSPrimitiveValue

61

Method: getStringValue()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxCSSPrimitiveValue.getStringValue()

ParametersNone.

Return valuesReturns the value of a string.

Exceptions

Exception Description

INVALID_ACCESS_ERR This error is thrown if the CSS value contains no string value (that is, if it is not

of type CSS_STRING, CSS_URI, CSS_IDENT, or CSS_ATTR).

See AlsoCSSPrimitiveValue.setStringValue()

Method: CSSPrimitiveValue.setFloatValue()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxCSSPrimitiveValue.setFloatValue( unitType, floatValue )

Parameters

JavaScript Reference Object: CSSPrimitiveValue

62

Parameter Type Description

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

JavaScript Reference Object: CSSPrimitiveValue

63

Parameter Type Description

• 16 = CSS_HZ: A frequency value, in

Hertz.

• 17 = CSS_KHZ: A frequency, in

kiloHertz.

• 18 = CSS_DIMENSION: A number

value of an unknown dimension.

floatValue float The new float value for the property.

Return valuesNone.

Exceptions

Exception Description

INVALID_ACCESS_ERR This error is thrown if the CSS value contains no float value (that is, if it is not of

type CSS_NUMBER, CSS_PERCENTAGE, CSS_EMS, CSS_EXS, CSS_PX,

CSS_CM, CSS_MM, CSS_IN, CSS_PT, CSS_PC, CSS_DEG, CSS_RAD,

CSS_GRAD, CSS_MS, CSS_S, CSS_HZ, CSS_KHZ, or CSS_DIMENSION), or if

the float value cannot be converted into the specified units.

NO_MODIFICATION_ALLOWED_ERR This error is thrown if the property is read only.

See AlsoCSSPrimitiveValue.getFloatValue()

Method: CSSPrimitiveValue.setStringValue()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxsetStringValue( unitType, stringValue )

Parameters

JavaScript Reference Object: CSSPrimitiveValue

64

Parameter Type Description

unitType unsigned short The unit code for the prdoperty value. The

unit code must represent one of the following

string unit types:

• 19 = CSS_STRING: A simple string

value.

• 20 = CSS_URI: A string value

representing a URI.

• 21 = CSS_IDENT: A string value

representing an identifier.

• 22 = CSS_ATTR: A string value

representing an attribute function.

stringValue String The new string value for the property.

Return valuesNone.

Exceptions

Exception Description

INVALID_ACCESS_ERR This error is thrown if the CSS value contains no string value (that is, if it is not of

type CSS_STRING, CSS_URI, CSS_IDENT, or CSS_ATTR).

NO_MODIFICATION_ALLOWED_ERR This error is thrown if the property is read only.

See AlsoCSSPrimitiveValue.getStringValue()

Object: CSSRule

Availability BlackBerry® Device Software version 4.6 or later

Extended by CSSCharsetRule , CSSFontFaceRule , CSSImportRule , CSSMediaRule ,

CSSPageRule , CSSStyleRule , CSSUnknownRule

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

JavaScript Reference Object: CSSRule

65

CSSRule properties

Property name Type Description Status Availability

parentRule CSSRule Returns the parent rule, if this rule is contained

within another rule (for example, a style rule within

an @media block).

read only 4.6 or later

parentStyleShee

t

CSSStyleSh

eet

Returns the style sheet that contains this rule. read only 4.6 or later

type unsigned short Returns 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 4.6 or later

Object: CSSRuleList

Availability BlackBerry® Device Software version 4.6 or later

The CSSRuleList object represents an ordered collection of CSSRule objects.

JavaScript Reference Object: CSSRuleList

66

CSSRuleList properties

Property name Type Description Status Availability

length int Returns the number of rules in the list. read only 4.6 or later

CSSRuleList methods

Method name Description Availability

item() Returns the rule at the specified index in the collection. 4.6 or later

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

SyntaxCSSRuleList.item( index )

Parameters

Parameter Type Description

index int An integer that represents the CSS rules’s

position in rule list. Valid values are 0 to

CSSRuleList.length -1.

Return valuesReturns the rule at the index th position in CSSRuleList, or null if an invalid index position is specified.

ExceptionsNone.

See AlsoCSSRule

JavaScript Reference Object: CSSRuleList

67

Object: CSSStyleDeclaration

Availability BlackBerry® Device Software version 4.6 or later

The CSSStyleDeclaration object represents a CSS declaration block consisting of CSS properties and their values. Thisobject 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 valuesof the CSS cascade.

CSSStyleDeclaration properties

Property name Type Description Status Availability

azimuth String Specifies the direction from which a sound

originates.

writable 4.6 or later

background String Specifies any or all background properties. writable 4.6 or later

backgroundAttachmen

t

String Specifies whether the background scrolls with the

page.

writable 4.6 or later

backgroundColor String Specifies the background color for an element. writable 4.6 or later

backgroundImage String Specifies an image resource to use as the

background.

writable 4.6 or later

backgroundPosition String Specifies the starting position of a background

image.

writable 4.6 or later

backgroundRepeat String Specifies how or if a background image is repeated. writable 4.6 or later

border String Specifies any or all border properties for an element. writable 4.6 or later

borderBottom String Specifies any or all bottom border properties for an

element.

writable 4.6 or later

borderBottomColor String Specifies the bottom border color for an element writable 4.6 or later

borderBottomStyle String Specifies the bottom border style for an element. writable 4.6 or later

borderBottomWidth String Specifies the bottom border width of an element. writable 4.6 or later

borderCollapse String Specifies whether the table borders are collapsed

into a single border.

writable 4.6 or later

borderColor String Specifies the border color for an element. writable 4.6 or later

JavaScript Reference Object: CSSStyleDeclaration

68

Property name Type Description Status Availability

borderLeft String Specifies any or all left border properties for an

element.

writable 4.6 or later

borderLeftColor String Specifies the left border color for an element. writable 4.6 or later

borderLeftStyle String Specifies the left border style for an element. writable 4.6 or later

borderLeftWidth String Specifies the left border width of an element. writable 4.6 or later

borderRight String Specifies any or all right border properties for an

element.

writable 4.6 or later

borderRightColor String Specifies the right border color for an element. writable 4.6 or later

borderRightStyle String Specifies the right border style for an element. writable 4.6 or later

borderRightWidth String Specifies the right border width of an element. writable 4.6 or later

borderSpacing String Specifies the distance between the cell borders

when not collapsed.

writable 4.6 or later

borderStyle String Specifies the border style for an element. writable 4.6 or later

borderTop String Specifies any or all top border properties for an

element.

writable 4.6 or later

borderTopColor String Specifies the top border color for an element. writable 4.6 or later

borderTopStyle String Specifies the top border style for an element. writable 4.6 or later

borderTopWidth String Specifies the top border width of an element. writable 4.6 or later

borderWidth String Specifies the border width of an element. writable 4.6 or later

bottom String Specifies the distance of the bottom edge of an

element above or below the parent element.

writable 4.6 or later

captionSide String Specifies the location of the table caption. writable 4.6 or later

clear String Specifies the side(s) of an element that may not be

adjacent to floating elements.

writable 4.6 or later

clip String Specifies the shape of the element. writable 4.6 or later

color String Specifies the foreground color for an element. writable 4.6 or later

content String Used with the :before and :after pseudo-elements

to generate content.

writable 4.6 or later

counterIncrement String Specifies how much the counter is incremented for

every occurrence of the element.

writable 4.6 or later

counterReset String Resets a counter for an element. writable 4.6 or later

cue String Specifies any or all cue properties. writable 4.6 or later

JavaScript Reference Object: CSSStyleDeclaration

69

Property name Type Description Status Availability

cueAfter String Specifies a URI containing a sound that is played

after an element.

writable 4.6 or later

cueBefore String Specifies a URI containing a sound that is played

before an element.

writable 4.6 or later

cursor String Specifies the type of cursor. writable 4.6 or later

direction String Specifies the base direction of the text. writable 4.6 or later

display String Specifies how or if an element is displayed. writable 4.6 or later

elevation String Specifies the elevation from which a sound

originates.

writable 4.6 or later

emptyCells String Specifies whether empty cells are displayed when

the borders are not merged.

writable 4.6 or later

CSSFloat String Specifies where an image or text will appear in

another element.

writable 4.6 or later

font String Specifies any or all of the font properties for an

element.

writable 4.6 or later

fontFamily String Specifies the font family for an element. writable 4.6 or later

fontSize String Specifies the font size for an element. writable 4.6 or later

fontStyle String Specifies the style of the font for an element. writable 4.6 or later

fontVariant String Specifies whether the font for an element is

rendered in small caps.

writable 4.6 or later

fontWeight String Specifies the thickness of the font for an element. writable 4.6 or later

height String Specifies the height of an element. writable 4.6 or later

left String Specifies the distance of the left edge of an element

from the right or left edge of the parent element.

writable 4.6 or later

length int Returns the number of properties that have been

explicitly set.

read only 4.6 or later

letterSpacing String Specifies the spacing between the characters. writable 4.6 or later

lineHeight String Specifies the height of each line in an element. writable 4.6 or later

listStyle String Specifies any or all of the list properties. writable 4.6 or later

listStyleImage String Specifies the image used for the list marker. writable 4.6 or later

listStylePosition String Specifies the location of the list marker. writable 4.6 or later

listStyleType String Specifies the type of list marker. writable 4.6 or later

margin String Specifies the margin around all sides of an element. writable 4.6 or later

JavaScript Reference Object: CSSStyleDeclaration

70

Property name Type Description Status Availability

marginBottom String Specifies the margin below an element. writable 4.6 or later

marginLeft String Specifies the margin to the left of an element. writable 4.6 or later

marginRight String Specifies the margin to the right of an element. writable 4.6 or later

marginTop String Specifies the margin above an element. writable 4.6 or later

maxHeight String Specifies the maximum height for an element. writable 4.6 or later

maxWidth String Specifies the maximum width for an element. writable 4.6 or later

minHeight String Specifies the minimum height for an element. writable 4.6 or later

minWidth String Specifies the minimum width for an element. writable 4.6 or later

orphans String Specifies the minimum number of lines left at the

bottom of a page.

writable 4.6 or later

outline String Specifies any or all of the outline properties. writable 4.6 or later

outlineColor String Specifies the outline color for an element. writable 4.6 or later

outlineStyle String Specifies the outline style for an element. writable 4.6 or later

outlineWidth String Specifies the outline width for an element. writable 4.6 or later

overflow String Specifies the behavior when the content of an

element overflows the available space for that

element.

writable 4.6 or later

padding String Specifies the padding around all sides of an

element.

writable 4.6 or later

paddingBottom String Specifies the padding applied below an element. writable 4.6 or later

paddingLeft String Specifies the padding applied to the left of an

element.

writable 4.6 or later

paddingRight String Specifies the padding applied to the right of an

element.

writable 4.6 or later

paddingTop String Specifies the padding applied above an element. writable 4.6 or later

pageBreakAfter String Specifies how the page breaks after the element are

handled.

writable 4.6 or later

pageBreakBefore String Specifies how the page breaks before the element

are handled.

writable 4.6 or later

pageBreakInside String Specifies how the page breaks within the element

are handled.

writable 4.6 or later

parentRule CSSRule Returns the CSSRule that contains this

declaration block.

read only 4.6 or later

JavaScript Reference Object: CSSStyleDeclaration

71

Property name Type Description Status Availability

pause String Specifies any or all of the pause properties. writable 4.6 or later

pauseAfter String Specifies a pause to be observed after an element. writable 4.6 or later

pauseBefore String Specifies a pause to be observed before an element. writable 4.6 or later

pitch String Specifies the average pitch of the speaking voice. writable 4.6 or later

pitchRange String Specifies the variation in average pitch. writable 4.6 or later

playDuring String Specifies a sound to be played in the background

while an element’s content is spoken.

writable 4.6 or later

position String Specifies the position of the element. writable 4.6 or later

quotes String Specifies the quotation marks to use for embedded

quotations.

writable 4.6 or later

richness String Specifies the brightness of the speaking voice. writable 4.6 or later

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 4.6 or later

speak String Specifies whether text will be rendered aurally. writable 4.6 or later

speakHeader String Specifies how table headers are rendered aurally. writable 4.6 or later

speakNumeral String Specifies how numerals are spoken. writable 4.6 or later

speakPunctuation String Specifies how punctuation is spoken. writable 4.6 or later

speechRate String Specifies the speaking rate. writable 4.6 or later

stress String Specifies the level of intonation of a voice. writable 4.6 or later

tableLayout String Specifies whether the column width is fixed or

determined by the width of the content.

writable 4.6 or later

textAlign String Specifies the horizontal alignment of the text for an

element.

writable

writable

4.6 or later

textDecoration String Specifies the decoration applied to the text. writable 4.6 or later

textIndent String Specifies the indentation of the first line of text in

a block of text.

writable 4.6 or later

textTransform String Specifies how the text is capitalized. writable 4.6 or later

top String Specifies the distance of the top edge of an element

above or below the parent element.

writable 4.6 or later

unicodeBidi String Specifies the Unicode bidirectional algorithm to

use.

writable 4.6 or later

verticalAlign String Specifies the vertical alignment of an element. writable 4.6 or later

JavaScript Reference Object: CSSStyleDeclaration

72

Property name Type Description Status Availability

visibility String Specifies whether elements are rendered or not. writable 4.6 or later

voiceFamily String Specifies a list of voice family names. writable 4.6 or later

volume String Specifies the median volume of the wave form. writable 4.6 or later

whitespace String Specifies how white space in an element is handled. writable 4.6 or later

widows String Specifies the minimum number of lines left at the

top of a page.

writable 4.6 or later

width String Specifies the width of an element. writable 4.6 or later

wordSpacing String Specifies the spacing between words. writable 4.6 or later

zIndex String Specifies the stack order of an element. writable 4.6 or later

CSSStyleDeclaration methods

Method name Description Availability

getPropertyCSSValue

()

Returns the value of a CSS property as an object, if the property has been

explicitly set.

4.6 or later

getPropertyPriority

()

Returns the priority of a CSS property. 4.6 or later

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

explicitly set.

4.6 or later

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

collection.

4.6 or later

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

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

Method: CSSStyleDeclaration.getPropertyPriority()

Availability BlackBerry® Device Software version 4.6 or later

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

Syntax

JavaScript Reference Object: CSSStyleDeclaration

73

CSSStyleDeclaration.getPriorityProperty( propertyName )

Parameters

Parameter Type Description

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

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

ExceptionsNone.

Method: CSSStyleDeclaration.getPropertyCSSValue()

Availability BlackBerry® Device Software version 4.6 or later

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 modifiedas strings, using CSSStyleDeclaration.getPropertyValue() and CSSStyleDeclaration.setProperty() .

SyntaxCSSStyleDeclaration.getPropertyCSSValue( propertyName )

Parameters

Parameter Type Description

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

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

ExceptionsNone.

JavaScript Reference Object: CSSStyleDeclaration

74

Method: CSSStyleDeclaration.getPropertyValue()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxCSSStyleDeclaration.getPropertyValue( propertyName )

Parameters

Parameter Type Description

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

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

ExceptionsNone.

Method: CSSStyleDeclaration.item()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxCSSStyleDeclaration.item( index )

Parameters

Parameter Type Description

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

Return values

JavaScript Reference Object: CSSStyleDeclaration

75

Returns the name of the CSS property at the index th position in CSSStyleDeclaration , or an empty string if no propertyexists at the index position specified.

ExceptionsNone.

Method: CSSStyleDeclaration.removeProperty()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxCSSStyleDeclaration.removeProperty( propertyName )

Parameters

Parameter Type Description

propertyName String The name of the CSS property to remove.

Return valuesReturns the value of the removed CSS property as a string, if that property has been explicitly set for this declaration block; if novalue has been set, returns

null.

Exceptions

Exception Description

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

Method: CSSStyleDeclaration.setProperty()

Availability BlackBerry® Device Software version 4.6 or later

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

Syntax

JavaScript Reference Object: CSSStyleDeclaration

76

CSSStyleDeclaration.setProperty( propertyName, value, priority )

Parameters

Parameter Type Description

propertyName String The name of the CSS property to remove.

value String The value of the new property.

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

Return valuesNone.

Exceptions

Exception Description

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

SYNTAX_ERR This error is thrown if the given value has a syntax error and cannot be parsed.

Object: CSSStyleRule

Availability BlackBerry® Device Software version 4.6 or later

Extends CSSRule

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

CSSStyleRule properties

Property name Type Description Status Availability

selectorText String Specifies the name of the CSS selector for the

rule set.

writable 4.6 or later

style CSSStyleDeclar

ation

Returns the style values for the CSS selector. read only 4.6 or later

JavaScript Reference Object: CSSStyleRule

77

Object: CSSStyleSheet

Availability BlackBerry® Device Software version 4.6 or later

Extends StyleSheet

The CSSStyleSheet object represents a CSS style sheet.

CSSStyleSheet properties

Property name Type Description Status Availability

CSSRules CSSRuleLis

t

Returns an array of the CSSRule objects in the style

sheet.

read only 4.6 or later

ownerRule CSSRule Returns the CSSImportRule object for imported

style sheets. If the style sheet is not imported, the value

for this property is null.

read only 4.6 or later

CSSStyleSheet methods

Method name Description Availability

deleteRule() Deletes a CSS Rule at the given position in the CSS style sheet. 4.6 or later

insertRule() Adds a CSS Rule at the given position in the CSS style sheet. 4.6 or later

Method: CSSStyleSheet.deleteRule()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxCSSStyleSheet.deleteRule( index )

Parameters

JavaScript Reference Object: CSSStyleSheet

78

Parameter Type Description

index int An integer that represents the CSS rules’s

position in the style sheet’s collection of rules.

Return valuesNone.

Exceptions

Exception Description

NO_MODIFICATION_ALLOWED_ERR This error is thrown if the style sheet is read only.

INDEX_SIZE_ERR This error is thrown if index does not correspond to any rule in the style sheet’s

collection of rules.

Method: CSSStyleSheet.insertRule()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxCSSStyleSheet.insertRule( rule, index )

Parameters

Parameter Type Description

rule String The parsable text for the CSS Rule to add.

• For rule sets, rule includes both the

selector and the style declaration.

• For @-rules, rule includes both the @-

identifier and the rule content.

JavaScript Reference Object: CSSStyleSheet

79

Parameter Type Description

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

CSSRuleList.length , the rule is added

to the end of the list of rules.

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

Exceptions

Exception Description

NO_MODIFICATION_ALLOWED_ERR This error is thrown if the style sheet is read only.

INDEX_SIZE_ERR This error is thrown if index does not correspond to any rule in the style sheet’s

collection of rules.

Object: CSSUnknownRule

Availability BlackBerry® Device Software version 4.6 or later

Extends CSSRule

The CSSUnknownRule represents an unsupported @ rule.

Object: CSSValue

Availability BlackBerry® Device Software version 4.6 or later

Extended by CSSPrimitiveValue , CSSValueList

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

JavaScript Reference Object: CSSUnknownRule

80

CSSValue properties

Property name Type Description Status Availability

CSSValueType unsigned short Returns 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 value is a custom value.

read only 4.6 or later

Object: CSSValueList

Availability BlackBerry® Device Software version 4.6 or later

Extends CSSValue

The CSSValueList objects represents an ordered collection of CSSValue objects.

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

CSSValueList properties

Property name Type Description Status Availability

length int Returns the number of property values in the list. read only 4.6 or later

JavaScript Reference Object: CSSValueList

81

CSSValueList methods

Method name Description Availability

item() Returns the CSSValue object at the specified index in the

CSSValueList.

4.6 or later

Method: CSSValueList.item()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxCSSValueList.item( index )

Parameters

Parameter Type Description

index int An integer that represents the CSS property value’s position in rule list.

Valid values are 0 to CSSValueList.length -1.

Return valuesReturns the property value at the index th position in CSSValueList, or null if an invalid index position is specified.

ExceptionsNone.

Object: CustomEvent

Availability BlackBerry® Device Software version 4.6 or later

Extends Event

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

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

JavaScript Reference Object: CustomEvent

82

Properties

Property name Type Description Status Availability

detail Object Specifies some detail information about the

Event , depending on the type of event.

read only 4.6 or later

CustomEvent methods

Method name Description Availability

initCustomEventNS() Initializes the value of a CustomEvent created by

Document.createEvent() .

4.6 or later

Method: CustomEvent.initCustomEventNS()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxCustomEvent.initCustomEventNS( arg, canBubbleArg, cancelableArg, detailArg )

Parameters

Parameter Type Description

arg int The event type.

canBubbleArg boolean If true, specifies that the event can bubble.

cancelableArg boolean If true, specifies that the event can be cancelled.

detailArg long The event’s detail.

Return valuesNone.

ExceptionsNone.

JavaScript Reference Object: CustomEvent

83

Object: Document

Availability BlackBerry® Device Software version 4.6 or later

Extends Node

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

Document properties

Property name Type Description Status Availability

defaultView AbstractView Returns the default view of the document. read only 4.6 or later

doctype DocumentType Returns the document type declaration

associated with the document.

read only 4.6 or later

documentElement Element Returns the root element in a document. read only 4.6 or later

implementation DOMImplementa

tion

Returns the DOMImplementation object

that handles this document.

read only 4.6 or later

parentWindow Window Returns a reference to the parent window. If

no parent window exists, this property points

to the current active window.

read only 4.6 or later

styleSheets StyleSheetLis

t

Returns an array of all the style sheets in the

document.

read only 4.6 or later

Document methods

Method name Description Availability

adoptNode() Adopts a node and its children from an external document to the

current document.

4.7.1 or later

createAttribute() Creates a new Attr object with the given name. 4.6 or later

createAttributeNS() Creates a new Attr object with the given qualified name and

namespace URI.

4.6 or later

JavaScript Reference Object: Document

84

Method name Description Availability

createCDATASection() Creates a new CDATASection object, which represents a block of

uninterpreted content.

4.6 or later

createComment() Creates a new Comment object with the given text as content. 4.6 or later

createDocumentFragment() Creates an empty DocumentFragment object. 4.6 or later

createElement() Creates a new Element object of the specified type. 4.6 or later

createElementNS() Creates a new Element object of the given qualified name and

namespace URI.

4.6 or later

createEntityReference() Creates a new EntityReference object with the given name. 4.6 or later

createEvent() Creates a new Event object of the given type. 4.6 or later

createNodeIterator() Creates a new NodeIterator object, which you can use to iterate

through a set of Document nodes rooted at the given node.

4.6 or later

createProcessingInstruct

ion()

Creates a new ProcessingInstruction object with the given

name and data.

4.6 or later

createRange() Creates a new Range object. 4.7.1 or later

createTextNode() Creates a new Text node containing the given text. 4.6 or later

createTreeWalker() Creates a TreeWalker object, which you can use to traverse the

specified document subtree.

4.6 or later

getElementById() Returns the element node with the given ID value. 4.6 or later

getElementsByTagName() Returns a NodeList object that contains an array of a document’s

descendent element nodes with the specified tag name.

4.6 or later

getElementsByTagNameNS() Returns a NodeList object that contains an array of a document’s

descendent element nodes with the given local name and namespace

URI.

4.6 or later

getOverrideStyle() Retrieves the override CSSStyleDeclaration object for the given

element.

4.6 or later

importNode() Imports a node from a different document. 4.6 or later

JavaScript Reference Object: Document

85

Method: Document.adoptNode()

Availability BlackBerry® Device Software version 4.7.1 or later

The adoptNode() method moves a node and its child nodes from another document to the current document. Unlike theDocument.importNode() method, which imports a copy of the source node, the adoptNode() method removes a nodefrom the one document and adds it to another.

If the adopted node has a parent node, this method first deletes the adopted node from the child list of the parent node, thenchanges the ownerDocument property of the adopted node to reflect the current document.

The adopted node must be inserted into the desired location within the current document tree by using the Node.appendChild() method or a similar method.

SyntaxDocument.adoptNode( sourceNode )

Parameters

Parameter Type Description

sourceNode Node Specifies the node to move to the current document.

Return valuesThis method returns the new node, or null if the operation is unsuccessful.

Exceptions

Exception Description

NO_MODIFICATION_ALLOWED_ERR Thrown if sourceNode is read-only.

NOT_SUPPORTED_ERR Thrown if sourceNode is of a type that cannot be adopted, such as a Document

or DocumentType node.

Method: Document.createAttribute()

Availability BlackBerry® Device Software version 4.6 or later

The createAttribute() method creates a new Attr node with the given name. Once created, the attribute instance canbe 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.

JavaScript Reference Object: Document

86

To create an attribute with a qualified name and namespace URI, use Document.createAttributeNS() .

SyntaxDocument.createAttribute( name )

Parameters

Parameter Type Description

name String The name of the attribute to create.

Return valuesReturns the new attribute node with the Node.nodeName property set to name and the Node.nodeValue property set toan empty string.

Exceptions

Exception Description

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

See alsoAttr , Document.createAttributeNS() , Element.setAttribute() , Element.setAttributeNode()

Method: Document.createAttributeNS()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxDocument.createAttributeNS( namespaceURI, qualifiedName )

Parameters

Parameter Type Description

namespaceURI String The namespace of the new attribute.

qualifiedName String The qualified name of the attribute to create.

Return valuesReturns the new Attr object with the following properties set:

JavaScript Reference Object: Document

87

Property Description

Node.nodeName The qualified name.

Node.namespaceURI The namespace URI for the attribute.

Node.prefix The prefix, extracted from the qualified name of the new attribute. If there is no

prefix, this property is set to null.

Node.localName The local name for the attribute, extracted from the qualified name.

Node.nodeValue An empty string.

Attr.name Equivalent to Node.nodeName.

Exceptions

Exception Description

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

NAMESPACE_ERR This error is thrown if:

• qualifiedName is malformed

• qualifiedName has a prefix, but namespaceURI is null

• prefix is “xml”, but namespaceURI is not “http://www.w3.org/

XML/1998/namespace”

• qualifiedName is “xmlns”, but namespaceURI is not “http://

www.w3.org/2000/xmlns/”

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

See alsoAttr , Element.setAttributeNode()

Method: Document.createCDATASection()

Availability BlackBerry® Device Software version 4.6 or later

The createCDATASection() method creates a new CDATASection object, which represents a block of uninterpretedcontent.

HTML documents do not support CDATASection objects.

Syntax

JavaScript Reference Object: Document

88

Document.createCDATASection( data )

Parameters

Parameter Type Description

data String The contents of the CDATASection node.

Return valuesReturns the new CDATASection object.

ExceptionsNone.

See alsoCDATASection

Method: Document.createComment()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxDocument.createComment( data )

Parameters

Parameter Type Description

data String The contents of the Comment node.

Return valuesReturns the new Comment object.

ExceptionsNone.

See alsoComment

JavaScript Reference Object: Document

89

Method: Document.createDocumentFragment()

Availability BlackBerry® Device Software version 4.6 or later

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 theirchildren—at once.

SyntaxDocument.createDocumentFragment()

ParametersNone.

Return valuesReturns the new DocumentFragment object.

ExceptionsNone.

See alsoDocumentFragment

Method: Document.createElement()

Availability BlackBerry® Device Software version 4.6 or later

The createElement() method creates a new Element object of the specified type. Attributes can be set directly on thereturned object.

If the Element type returned has any attributes with default values, those attributes will be created and attached to the elementwith their default values.

SyntaxDocument.createElement( tagName )

Parameters

JavaScript Reference Object: Document

90

Parameter Type Description

tagName String The type of element to create.

In an XML document, tagName is case-sensitive.

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

Exceptions

Exception Description

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

See alsoAttr , Element

Method: Document.createElementNS()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxDocument.createElementNS( namespaceURI, qualifiedName )

Parameters

Parameter Type Description

namespaceURI String The namespace of the new attribute.

qualifiedName String The qualified name of the attribute to create.

Return valuesReturns the new Element object with the following properties set:

JavaScript Reference Object: Document

91

Property Description

Node.nodeName The qualified name.

Node.namespaceURI The namespace URI for the attribute.

Node.prefix The prefix, extracted from the qualified name of the new attribute. If there is no

prefix, this property is set to null.

Node.nodeValue An empty string.

Element.tagName Equivalent to Node.nodeName.

Exceptions

Exception Description

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

NAMESPACE_ERR This error is thrown if:

• qualifiedName is malformed

• qualifiedName has a prefix, but namespaceURI is null

• prefix is “xml”, but namespaceURI is not “http://www.w3.org/

XML/1998/namespace”

• qualifiedName is “xmlns”, but namespaceURI is not “http://

www.w3.org/2000/xmlns/”

See alsoElement

Method: Document.createEntityReference()

Availability BlackBerry® Device Software version 4.6 or later

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

JavaScript Reference Object: Document

92

Parameter Type Description

name String The name of the entity to reference.

Return valuesReturns the new EntityReference object.

Exceptions

Exception Description

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

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

See alsoEntity , EntityReference

Method: Document.createEvent()

Availability BlackBerry® Device Software version 4.6 or later

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

Parameter Type Description

eventType String The type of event to create.

Return valuesReturns the new Event object.

Exceptions

JavaScript Reference Object: Document

93

Exception Description

NOT_SUPPORTED_ERR This error is thrown if the implementation does not support the specified Event

interface.

See alsoEvent

Method: Document.createNodeIterator()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxDocument.createNodeIterator( root, whatToShow, filter, entityReferenceExpansion )

Parameters

Parameter Type Description

root Node The node to be iterated with its children. The NodeIterator object is initially

positioned just before this node. The value of root must not be null.

whatToShow unsigned long The types of nodes to show in the tree view presented by the NodeIterator.

The value may be one or more of:

• 0xFFFFFFFF = SHOW_ALL

• 0x00000001 = SHOW_ELEMENT

• 0x00000002 = SHOW_ATTRIBUTE

• 0x00000004 = SHOW_TEXT

• 0x00000008 = SHOW_CDATA_SECTION

• 0x00000010 = SHOW_ENTITY_REFERENCE

• 0x00000020 = SHOW_ENTITY

• 0x00000040 = SHOW_PROCESSING_INSTRUCTION

• 0x00000080 = SHOW_COMMENT

• 0x00000100 = SHOW_DOCUMENT

JavaScript Reference Object: Document

94

Parameter Type Description

• 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 object’s logical view unless root

is defined as a Node of that type. If the respective object is not defined as the

root, then SHOW_ATTRIBUTE, SHOW_ENTITY, and SHOW_NOTATION have

no meaning.

filter NodeFilter The filter to use with this NodeIterator object. This parameter may be null.

entityReferenceExpansion

boolean When true, this method specifies that entity reference nodes should be

expanded.

Return valuesReturns the new NodeIterator object.

Exceptions

Exception Description

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

See alsoNodeIterator

Method: Document.createProcessingInstruction()

Availability BlackBerry® Device Software version 4.6 or later

The createProcessingInstruction() method creates a new ProcessingInstruction object with the given nameand data.

SyntaxDocument.createProcessingInstruction( target, data )

Parameters

JavaScript Reference Object: Document

95

Parameter Type Description

target String The target of the processing instruction.

data String The data to store in the processing instruction.

Return valuesReturns the new ProcessingInstruction object.

Exceptions

Exception Description

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

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

See alsoProcessingInstruction

Method: Document.createRange()

Availability BlackBerry® Device Software version 4.7.1 or later

The createRange() method creates a new empty Range object.

The Range object can be used only to select content that is associated with the current document, or with DocumentFragmentor Attr objects for which this document is the owner.

SyntaxDocument.createRange()

ParametersNone.

Return valuesThis method returns the new empty Range object. The boundary points of the Range object that is returned from this methodare positioned at the beginning of the corresponding document, before any content.

ExceptionsNone.

See also

JavaScript Reference Object: Document

96

Range

Method: Document.createTextNode()

Availability BlackBerry® Device Software version 4.6 or later

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 singlenode later on.

SyntaxDocument.createTextNode( text )

Parameters

Parameter Type Description

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

Return valuesReturns the new Text object.

ExceptionsNone.

See alsoText

Method: Document.createTreeWalker()

Availability BlackBerry® Device Software version 4.6 or later

The createTreeWalker() method creates a TreeWalker object, which you can use to traverse the specified documentsubtree.

SyntaxDocument.createTreeWalker( root, whatToShow, filter, expandEntityReference )

Parameters

JavaScript Reference Object: Document

97

Parameter Type Description

root Node The node that will serve as the root for this TreeWalker object. The

TreeWalker.currentNode property is set to the value of root .

whatToShow unsigned

long

The types of nodes to show in the tree view. The value may be one or more of:

• 0xFFFFFFFF = SHOW_ALL

• 0x00000001 = SHOW_ELEMENT

• 0x00000002 = SHOW_ATTRIBUTE

• 0x00000004 = SHOW_TEXT

• 0x00000008 = SHOW_CDATA_SECTION

• 0x00000010 = SHOW_ENTITY_REFERENCE

• 0x00000020 = SHOW_ENTITY

• 0x00000040 = SHOW_PROCESSING_INSTRUCTION

• 0x00000080 = SHOW_COMMENT

• 0x00000100 = SHOW_DOCUMENT

• 0x00000200 = SHOW_DOCUMENT_TYPE

• 0x00000400 = SHOW_DOCUMENT_FRAGMENT

• 0x00000800 = SHOW_NOTATION

Multiple values may be specified using a bitwise OR.

Note that because attributes, entities, and notations are not the child of any

other node, they never appear in the TreeWalker object’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 NodeFilt

er

The filter to use with this TreeWalker object. This parameter may be null.

entityReferenceExpansion

boolean When true, this method specifies that entity reference nodes should be

expanded.

Return valuesReturns the new TreeWalker object.

Exceptions

JavaScript Reference Object: Document

98

Exception Description

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

See alsoTreeWalker

Method: Document.getElementById()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxDocument.getElementById( elementID )

Parameters

Parameter Type Description

elementID String The ID of the element to retrieve.

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

ExceptionsNone.

Code sampleThe following example appends a text node as a child of a new Paragraph element, then appends the Paragraph node asa 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 alsoElement

JavaScript Reference Object: Document

99

Method: Document.getElementsByTagName()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxDocument.getElementsByTagName( tagName )

Parameters

Parameter Type Description

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

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

ExceptionsNone.

See alsoDocument.getElementsByTagNameNS() , Element.getElementsByTagName() ,Element.getElementsByTagNameNS() , NodeList

Method: Document.getElementsByTagNameNS()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxDocument.getElementsByTagNameNS( namespaceURI, localName )

Parameters

JavaScript Reference Object: Document

100

Parameter Type Description

namespaceURI String The namespace of the elements to match on. Specify a value of “*” to match all

elements.

localName String The local name of the elements to match on (that is, the qualified name minus the

prefix). Specify a value of “*” to match all local elements.

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

ExceptionsNone.

See alsoDocument.getElementsByTagName() , Element.getElementsByTagName() ,Element.getElementsByTagNameNS() , NodeList

Method: Document.getOverrideStyle()

Availability BlackBerry® Device Software version 4.6 or later

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

Parameter Type Description

elt Element The element for which to modify the style.

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

Return values

JavaScript Reference Object: Document

101

Returns the CSSStyleDeclaration object.

ExceptionsNone.

See alsoCSSStyleDeclaration

Method: Document.importNode()

Availability BlackBerry® Device Software version 4.6 or later

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 createsa 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 theNode.nodeName and Node.nodeType , plus the attributes related to namespaces. Additional information is copied asappropriate to the node type.

SyntaxDocument.importNode( importedNode, deep )

Parameters

Parameter Type Description

importedNode Node The node to import into the current document.

deep boolean When true, this method imports the given node and the subtree.

When false, this method only imports the given node; it does not include the

subtree.

This parameter has no effect when the given node is an Attr ,

EntityReference , or Notation node.

Return valuesReturns the imported Node.

Exceptions

JavaScript Reference Object: Document

102

Exception Description

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

See alsoNode.cloneNode()

Object: DocumentFragment

Availability BlackBerry® Device Software version 4.6 or later

Extends Node

The DocumentFragment object is a lightweight Document object, used to create or extract only a portion of a document.

A DocumentFragment behaves like a conventional Node object, except that it does not need to be fully formed.

The Range object uses DocumentFragment objects extensively, so that it can extract and store ranges of DOM nodes withoutcreating an entirely new document.

When the children of a DocumentFragment object are inserted into a Document object, only the children of theDocumentFragment, and not the DocumentFragment itself, are inserted into the node.

Object: DocumentType

Availability BlackBerry® Device Software version 4.6 or later

Extends Node

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

DocumentType properties

Property name Type Description Status Availability

entities NamedNode

Map

Returns a list of all the general

entities defined within the DTD.

read only 4.6 or later

JavaScript Reference Object: DocumentFragment

103

Property name Type Description Status Availability

internalSubset String Returns the contents of the

DTD subset. Contains the string

between the “[“ and “]”

characters.

read only 4.6 or later

name String Returns the name of the DTD. read only 4.6 or later

notations NamedNode

Map

Returns a list of all the notations

defined within the DTD.

read only 4.6 or later

publicId String Returns the public identifier of

the external subset.

read only 4.6 or later

systemId String Returns the system identifier of

the external subset.

read only 4.6 or later

Object: DOMImplementation

Availability BlackBerry® Device Software version 4.6 or later

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

DOMImplementation methods

Method name Description Availability

createCSSStyleSheet

()

Creates a new CSS stylesheet document object. 4.6 or later

createDocument() Creates a new XML or HTML document object. 4.6 or later

createDocumentType() Creates an empty document type node. 4.6 or later

hasFeature() Determines whether the DOM implementation implements a specific

feature.

4.6 or later

JavaScript Reference Object: DOMImplementation

104

Method: DOMImplementation.createCSSStyleSheet()

Availability BlackBerry® Device Software version 4.6 or later

The createCSSStyleSheet() method creates a new CSSStyleSheet object.

SyntaxDOMImplementation.createCSSStyleSheet( title, media )

Parameters

Parameter Type Description

title String The title of the CSS style sheet.

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

Return valuesReturns the new CSSStyleSheet object.

Exceptions

Exception Description

SYNTAX_ERR This error is thrown if media has a syntax error that prevents the browser from

being able to parse it.

See alsoCSSStyleSheet

Method: DOMImplementation.createDocument()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxDOMImplementation.createDocument( namespaceURI, qualifiedName, doctype )

Parameters

JavaScript Reference Object: DOMImplementation

105

Parameter Type Description

namespaceURI String The namespace of the new document.

qualifiedName String The qualified name of the document to create.

doctype DocumentTy

pe

The type of document to be created, or null.

Return valuesReturns the new Document object.

Exceptions

Exception Description

SYNTAX_ERR This error is thrown if qualifiedName contains an illegal character.

NAMESPACE_ERR This error is thrown if:

• qualifiedName is malformed

• qualifiedName has a prefix, but namespaceURI is null

• prefix is xml, but namespaceURI is not http://www.w3.org/

XML/1998/namespace

• qualifiedName is xmlns, but namespaceURI is not http://

www.w3.org/2000/xmlns/

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

WRONG_DOCUMENT_ERR This error is thrown if doctype has already been used with a different document

or was created from a different implementation.

See alsoDocument

Method: DOMImplementation.createDocumentType()

Availability BlackBerry® Device Software version 4.6 or later

The createDocumentType() method creates an empty DocumentType node.

Syntax

JavaScript Reference Object: DOMImplementation

106

DOMImplementation.createDocumentType( qualifiedName, publicId, systemId )

Parameters

Parameter Type Description

qualifiedName String The qualified name of the document.

publicId String The qualified name of the document to create.

systemId String The type of document to be created, or null.

Return valuesReturns the new DocumentType object.

Exceptions

Exception Description

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

NAMESPACE_ERR This error is thrown if:

• qualifiedName is malformed

• qualifiedName has a prefix, but namespaceURI is null

• prefix is xml, but namespaceURI is not http://www.w3.org/

XML/1998/namespace

• qualifiedName is xmlns, but namespaceURI is not http://

www.w3.org/2000/xmlns/

See alsoDocumentType

Method: DOMImplementation.hasFeature()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxDOMImplementation.hasFeature( feature, version )

JavaScript Reference Object: DOMImplementation

107

Parameters

Parameter Type Description

feature String The name of the feature to test.

version String The version of the feature to test. This parameter may be null.

If version is not specified, this method returns true if any version of the

feature is supported.

Return valuesReturns:

• true, if the specified version of the specified feature is supported.• false, if the specified version of the specified feature is not supported.

ExceptionsNone.

See alsoNode.isSupported()

Object: DOMParser

Availability BlackBerry® Device Software version 4.7.1 or later

The DOMParser object provides the parseFromString() method, which creates an XML document from a XML string.

The BlackBerry® Browser always parses the current page into a DOM document, but you can also create a DOM from an XMLstring that you construct, or an XML string that you retrieve from a remote location.

DOMParser methods

Method name Description Availability

parseFromString() Converts a string into an XML document. 4.7.1 or later

JavaScript Reference Object: DOMParser

108

Method: DOMParser.parseFromString()

Availability BlackBerry® Device Software version 4.7.1 or later

The parseFromString() method converts a string into an XML document.

SyntaxDOMParser.parseFromString( string, mimeType )

Parameters

Parameter Type Description

string String Specifies the string of text.

mimeType String Specifies the content type of the resulting XML document. This parameter can have

one of the following values:

• application/xml

• application/xhtml+xml

• text/xml

Return valuesThis method returns an XML document. If the parsing process fails, an error document is returned.

ExceptionsNo exceptions are thrown. If the parsing process cannot be succesfully completed, an error document is returned.

Code sample: Converting a string into XML and back to a string againvar xmlString = "<?xml version='1.0' ?>\<root>\ <level1>\ <option>Option1</option>\ <option>Option2</option>\ <option>Option3</option>\ </level1>\</root>";

var parser = new DOMParser();var xmlDocument = parser.parseFromString( xmlString, "text/xml" );

var serializer = new XMLSerializer();var string = serializer.serializeToString( xmlDocument ); alert( string )

JavaScript Reference Object: DOMParser

109

Object: Element

Availability BlackBerry® Device Software version 4.6 or later

Extends Node

Extended by HTMLElement

The Element object represents an element in an HTML or XML document. Elements may have attributes associated with them.You can use the Node.attributes property to retrieve a map of all the attributes attached to the element.

This object provides several methods for handling all the available attributes, individual attribute values, or individual Attrobjects.

Element properties

Property name Type Description Status Availability

tagName String The name of the element. read only 4.6 or later

Element methods

Method name Description Availability

getAttribute() Retrieves the value of the attribute of the given name. 4.6 or later

getAttributeNode() Retrieves the attribute node of the given name. 4.6 or later

getAttributeNodeNS() Retrieves the attribute node with the given namespace URI and local name. 4.6 or later

getAttributeNS() Retrieves the value of the attribute with the given namespace URI and

local name.

4.6 or later

getElementsByTagName

()

Returns a NodeList object that contains an array of an element’s

descendent element nodes with the specified tag name.

4.6 or later

getElementsByTagName

NS()

Returns a NodeList object that contains an array of an element’s

descendent element nodes with the given local name and namespace URI.

4.6 or later

hasAttribute() Determines whether an attribute of the given name is specified on the

element.

4.6 or later

hasAttributeNS() Determines whether an attribute of the given namespace and local name

is specified on the element.

4.6 or later

JavaScript Reference Object: Element

110

Method name Description Availability

removeAttribute() Removes the attribute of the given name from the element node. 4.6 or later

removeAttributeNode

()

Removes the specified attribute node from the element node. 4.6 or later

removeAttributeNS() Removes the attribute node with the given namespace URI and local name

from the element node.

4.6 or later

setAttribute() Adds a new attribute to an element, and sets it to the given value. 4.6 or later

setAttributeNode() Adds a new attribute node to an element. 4.6 or later

setAttributeNodeNS() Adds a new attribute node to an element. 4.6 or later

setAttributeNS() Adds a new attribute to an element, and sets it to the given value. 4.6 or later

Method: Element.getAttribute()

Availability BlackBerry® Device Software version 4.6 or later

The getAttribute() method retrieves the value of the Attr with the given name.

SyntaxElement.getAttribute( name )

Parameters

Parameter Type Description

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

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

ExceptionsNone.

See alsoAttr , Element.getAttributeNode() , Element.getAttributeNodeNS() , Element.getAttributeNS() ,Node.attributes

JavaScript Reference Object: Element

111

Method: Element.getAttributeNode()

Availability BlackBerry® Device Software version 4.6 or later

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 theNode.attributes property.

SyntaxElement.getAttributeNode( name )

Parameters

Parameter Type Description

name String The name of the Attr node to retrieve.

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

ExceptionsNone.

See alsoAttr , Element.getAttribute() , Element.getAttributeNodeNS() , Element.getAttributeNS() ,Node.attributes

Method: Element.getAttributeNodeNS()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxElement.getAttributeNodeNS( namespaceURI, localName )

Parameters

JavaScript Reference Object: Element

112

Parameter Type Description

namespaceURI String The namespace of the attribute to retrieve. Specifying a value of null makes this

method functionally equivalent to Element.getAttributeNode() .

localName String The local name of the attribute to retrieve.

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

Exceptions

Exception Description

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

See alsoAttr

Method: Element.getAttributeNS()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxElement.getAttributeNS( namespaceURI, localName )

Parameters

Parameter Type Description

namespaceURI String The namespace of the attribute for which to retrieve the value. Specifying a value

of null makes this method functionally equivalent to Element.getAttribute

() .

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

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

Exceptions

JavaScript Reference Object: Element

113

Exception Description

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

See alsoAttr

Method: Element.getElementsByTagName()

Availability BlackBerry® Device Software version 4.6 or later

The getElementsByTagName() method returns a NodeList object that contains an array of an element’s descendentElement nodes with the specified tag name.

This method is identical to Document.getElementsByTagName() , except that it allows you to search a smaller subset ofElement nodes.

SyntaxElement.getElementsByTagName( tagName )

Parameters

Parameter Type Description

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

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

ExceptionsNone.

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

JavaScript Reference Object: Element

114

Method: Element.getElementsByTagNameNS()

Availability BlackBerry® Device Software version 4.6 or later

The getElementsByTagNameNS() method returns a NodeList object that contains an array of an element’s descendentElement 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 subsetof Element nodes.

SyntaxElement.getElementsByTagNameNS( namespaceURI, localName )

Parameters

Parameter Type Description

namespaceURI String The namespace of the elements to match on. Specify a value of “*” to match all

elements.

Specifying a value of null makes this method functionally equivalent to

Element.getElementsByTagName() .

localName String The local name of the elements to match on (that is, the qualified name minus

the prefix). Specify a value of “*” to match all local elements.

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

Exceptions

Exception Description

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

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

JavaScript Reference Object: Element

115

Method: Element.hasAttribute()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxElement.hasAttribute( name )

Parameters

Parameter Type Description

name String The name of the attribute to check.

Return valuesReturns:

• true, if the specified attribute exists on the element• false, if the attribute does not exist

ExceptionsNone.

Method: Element.hasAttributeNS()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxElement.hasAttributeNS( namespaceURI, localName )

Parameters

Parameter Type Description

namespaceURI String The namespace of the attribute to check.

JavaScript Reference Object: Element

116

Parameter Type Description

localName String The local name of the attribute to check.

Return valuesReturns:

• true, if the specified attribute exists on the element• false, if the attribute does not exist

Exceptions

Exception Description

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

Method: Element.removeAttribute()

Availability BlackBerry® Device Software version 4.6 or later

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 immediatelybe reattached to the element with its default value, as well as its corresponding namespace URI, local name, and prefix, ifapplicable.

If the attribute has no specified or default value, this method has no effect.

SyntaxElement.removeAttribute( name )

Parameters

Parameter Type Description

name String The name of the Attr node to remove.

Return valuesNone.

Exceptions

JavaScript Reference Object: Element

117

Exception Description

NO_MODIFICATION_ALLOWED_ERR This error is thrown if the Element node is read only.

NOT_FOUND_ERR This error is thrown if no node exists in the Element with a Node.nodeName

value of name .

See alsoAttr

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

If you are removing an attribute from the Element object that is known to have a default value, the attribute will immediatelybe reattached to the element with its default value, as well as its corresponding namespace URI, local name, and prefix, ifapplicable.

SyntaxElement.removeAttributeNode( oldAttr )

Parameters

Parameter Type Description

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

Return valuesNone.

Exceptions

Exception Description

NO_MODIFICATION_ALLOWED_ERR This error is thrown if the Element node is read only.

NOT_FOUND_ERR This error is thrown if the oldAttr node does not exist in the Element.

See alsoAttr

JavaScript Reference Object: Element

118

Method: Element.removeAttributeNS()

Availability BlackBerry® Device Software version 4.6 or later

The removeAttributeNS() method removes the Attr node with the given namespace URI and local name from theelement node.

If you are removing an attribute from the Element object that is known to have a default value, the attribute will immediatelybe reattached to the element with its default value, as well as its corresponding namespace URI, local name, and prefix, ifapplicable.

If the attribute has no specified or default value, this method has no effect.

SyntaxElement.removeAttributeNS( namespaceURI, localName )

Parameters

Parameter Type Description

namespaceURI String The namespace of the attribute to remove.

localName String The local name of the attribute to remove.

Return valuesNone.

Exceptions

Exception Description

NO_MODIFICATION_ALLOWED_ERR This error is thrown if the Element node is read only.

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

See alsoAttr

JavaScript Reference Object: Element

119

Method: Element.setAttribute()

Availability BlackBerry® Device Software version 4.6 or later

The setAttribute() method adds a new Attr node to an element, and sets it to the given value. If an attribute with thegiven 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 anEntityReference), 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.setAttribute( name, value )

Parameters

Parameter Type Description

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

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

Return valuesNone.

Exceptions

Exception Description

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

NO_MODIFICATION_ALLOWED_ERR This error is thrown if the Element node is read only.

See alsoAttr , Element.setAttributeNode() , Element.setAttributeNodeNS() , Element.setAttributeNS()

Method: Element.setAttributeNode()

Availability BlackBerry® Device Software version 4.6 or later

The setAttributeNode() method adds a new Attr node to an element. If an attribute node with the same name as thenew Attr node already exists on an element, that Attr node is replaced.

JavaScript Reference Object: Element

120

Unlike Element.setAttribute() , this method allows you to add DOM nodes, instead of specifying separate argumentsfor the attribute name and value. Note that your attribute nodes cannot be reused in multiple elements; you must either clonethe Attr node, or remove an Attr node from another element before adding it to a new element.

SyntaxElement.setAttributeNode( newAttr )

Parameters

Parameter Type Description

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

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

Exceptions

Exception Description

INUSE_ATTRIBUTE_ERR This error is thrown if newAttr is already an attribute of another Element

object. To add an attribute used elsewhere, you must clone it, and then add it.

NO_MODIFICATION_ALLOWED_ERR This error is thrown if the Element object is read only.

WRONG_DOCUMENT_ERR This error is thrown if newAttr was created from a different document than

the one that created this Element object.

See alsoAttr , Element.setAttribute() , Element.setAttributeNodeNS() , Element.setAttributeNS()

Method: Element.setAttributeNodeNS()

Availability BlackBerry® Device Software version 4.6 or later

The setAttributeNodeNS() method adds a new Attr node to an element. If an Attr node with the same namespaceand 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 argumentsfor the attribute name and value. Note that your attribute nodes cannot be reused in multiple elements; you must either clonethe Attr node, or remove an Attr node from another element before adding it to a new element.

Syntax

JavaScript Reference Object: Element

121

Element.setAttributeNodeNS( newAttr )

Parameters

Parameter Type Description

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

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

Exceptions

Exception Description

INUSE_ATTRIBUTE_ERR This error is thrown if newAttr is already an attribute of another

Element object. To add an attribute used elsewhere, you must clone it, and

then add it.

NO_MODIFICATION_ALLOWED_ERR This error is thrown if the Element object is read only.

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

WRONG_DOCUMENT_ERR This error is thrown if newAttr was created from a different document than

the one that created this Element object.

See alsoAttr , Element.setAttribute() , Element.setAttributeNode() , Element.setAttributeNS()

Method: setAttributeNS()

Availability BlackBerry® Device Software version 4.6 or later

The setAttributeNS() method adds a new Attr node to an element, and sets it to the given value. If an attribute withthe given namespace and local name already exists on the Element node, its prefix is change to the prefix portion of thequalified 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 anEntityReference ), 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

JavaScript Reference Object: Element

122

Parameter Type Description

newAttr String The namespace of the attribute to create or modify.

qualifiedName String The qualified name of the attribute to create or modify.

value String The value of the attribute, in string form.

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

Exceptions

Exception Description

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

NAMESPACE_ERR This error is thrown if:

• qualifiedName is malformed

• qualifiedName has a prefix, but namespaceURI is null

• prefix is xml, but namespaceURI is not http://www.w3.org/

XML/1998/namespace

• qualifiedName is xmlns, but namespaceURI is not http://

www.w3.org/2000/xmlns/

NO_MODIFICATION_ALLOWED_ERR This error is thrown if the Element node is read only.

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

See alsoAttr , Element.setAttribute() , Element.setAttributeNode() , Element.setAttributeNodeNS()

Object: Entity

Availability BlackBerry® Device Software version 4.6 or later

Extends Node

The Entity object represents any entity in an XML document. Entities are declarations of abbreviated text or other nodes withinan XML document, which can be inserted at various places in an XML document using EntityReference objects.

JavaScript Reference Object: Entity

123

The Entity name is stored in the Node.nodeName property. However, the actual content of the entity is contained withinthe Entity node’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 needto change the content of an Entity object, you must create a new one, then update all the EntityReference objects thatreferred to the old Entity so that they refer to the new Entity instead.

Entity properties

Property name Type Description Status Availability

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 4.6 or later

publicId String The public identifier associated with the entity. read only 4.6 or later

systemId String The system identifier associated with this entity. read only 4.6 or later

Object: EntityReference

Availability BlackBerry® Device Software version 4.6 or later

Extends Node

The EntityReference object represents references to Entity objects within the document. An EntityReference isa 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.

Object: Event

Availability BlackBerry® Device Software version 4.6 or later

Extended by CustomEvent , MutationEvent , UIEvent

The Event object represents provides contextual information about an event that Event handlers can use, such as theoriginating 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.

JavaScript Reference Object: EntityReference

124

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

Event properties

Property name Type Description Status Availability

bubbles boolean When true, the event is a bubbling event. read only 4.6. or later

cancelable boolean When true, the action of the event can be cancelled

using Event.preventDefault() .

read only 4.6. or later

cancelBubble boolean When true, bubbling of the event is cancelled. writable 4.6. or later

currentTarget EventTarget The node of the Document object that is currently

handling the event.

read only 4.6. or later

eventPhase unsigned short The phase that the event is currently in. 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 4.6. or later

target EventTarget The target node to which the event was dispatched. read only 4.6. or later

timeStamp unsigned long The time (in milliseconds since epoch) at which the

event was created.

read only 4.6 or later

type String The name of the event. read only 4.6 or later

Event methods

Method name Description Availability

initEvent() Initializes the properties of an Event object created by

Document.createEvent() .

4.6 or later

preventDefault() Cancels the event, preventing the default action from occurring. 4.6 or later

JavaScript Reference Object: Event

125

Method name Description Availability

stopPropagation() Prevents further propagation of this event during an event flow. 4.6 or later

Method: Event.initEvent()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxEvent.initEvent( eventTypeArg, canBubbleArg, cancelableArg )

Parameters

Parameter Type Description

eventTypeArge String Specifies the event type.

canBubbleArg boolean When true, this parameter indicates that the event will bubble.

cancelableArg boolean When true, this parameter indicates that Event.preventDefault() can

cancel the event.

Return valuesNone.

ExceptionsNone.

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

Method: Event.preventDefault()

Availability BlackBerry® Device Software version 4.6 or later

The preventDefault() method cancels the event, preventing the default action from occurring.

JavaScript Reference Object: Event

126

Calling this method for an event whose cancelable property is set to false will have no effect.

SyntaxEvent.preventDefault()

ParametersNone.

Return valuesNone.

ExceptionsNone.

Method: Event.stopPropagation()

Availability BlackBerry® Device Software version 4.6 or later

The stopPropagation() method prevents further propagation of this event during an event flow. If this method is called byany EventListener , the event will no longer propagate through the tree. The event will complete the dispatch to all listenerson the current EventTarget before the event flow stops.

This method can be used at any stage of the event flow.

SyntaxEvent.stopPropagation()

ParametersNone.

Return valuesNone.

ExceptionsNone.

JavaScript Reference

127

Object: EventListener

Availability BlackBerry® Device Software version 4.6 or later

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

EventListener methods

Method name Description Availability

handleEvent() Called whenever an event occurs the EventListener object was

registered to listen for.

4.6 or later

Method: EventListener.handleEvent()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxEventListener.handleEvent( evt )

Parameters

Parameter Type Description

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

Return valuesNone.

ExceptionsNone.

JavaScript Reference Object: EventListener

128

Object: History

Availability BlackBerry® Device Software version 4.2 or later

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

History properties

Property name Type Description Status Availability

current String Returns the complete URL of the current history

entry.

read only 4.6 or later

length int Returns the number of URLs in the history list. read only 4.6 or later

History methods

Method name Description Availability

back() Displays the previous URL in the BlackBerry® Browser History list. 4.6 or later

forward() Displays the next element in the BlackBerry Browser History list. 4.6 or later

go() Causes the to display the URL that is the specified number of URLs before or after

the current item in the BlackBerry Browser History list.

4.6 or later

Method: history.back()

Availability BlackBerry® Device Software version 3.8 or later

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

Syntaxhistory.back()

JavaScript Reference Object: History

129

ParametersNone.

Return valuesNone.

ExceptionsNone.

ExamplesThe 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 alsohistory.forward() , history.go() , window.history

Method: history.forward()

Availability BlackBerry® Device Software version 3.8 or later

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

Syntaxhistory.forward()

ParametersNone.

Return valuesNone.

ExceptionsNone.

ExamplesThe 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

JavaScript Reference Object: History

130

history.back() , history.go() , window.history

Method: history.go()

Availability BlackBerry® Device Software version 3.8 or later

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

Syntaxhistory.go( targetURLposition )

Parameters

Parameter Type Description

targetURLposition int The position of the URL to display, relative to the current URL in

the History list. A positive value moves forward in the history list;

a negative value moves backward.

Return valuesNone.

ExceptionsNone.

ExamplesThe following code fragment adds a custom button that causes the browser to display the URL three positions earlier than thecurrent URL in the History list:

<INPUT TYPE="button" VALUE="Leap back three pages!" onClick="window.history.go(-3)">

See alsohistory.back() , history.forward() , window.history

Object: HTMLAnchorElement

Availability BlackBerry® Device Software version 4.6 or later

JavaScript Reference Object: HTMLAnchorElement

131

Extends HTMLElement

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

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

HTMLAnchorElement properties

Property name Type Description Status Availability

accessKey String Specifies the keypad key that gives access to the

element.

writable 4.6 or later

charset String Specifies the character encoding used in the

referenced document; the value must be the name of

a standard character set.

writable 4.6 or later

coords String Specifies a comma-separated list of the coordinates of

HTMLAnchorElement.shape, which defines the

active region in an image map.

writable 4.6 or later

href String Specifies the URI of the target of the link. writable 4.6 or later

hreflang String Specifies the language code of the target resource. writable 4.6 or later

name String Specifies a name for the anchor. writable 4.6 or later

rel String Specifies the link type between the current document

and the referenced resource.

writable 4.6 or later

rev String Specifies the link type between the referenced resource

and the current document.

writable 4.6 or later

shape String Specifies the shape of an active region in an image

map. The coordinates of the shape are specified by

HTMLAnchorElement.coords.

writable 4.6 or later

tabIndex int Specifies the element’s position in the tabbing order. writable 4.6 or later

target String Specifies the frame in which to render the target

document.

writable 4.6 or later

type String Specifies the MIME type of the target document. writable 4.6 or later

JavaScript Reference Object: HTMLAnchorElement

132

HTMLAnchorElement methods

Method name Description Availability

blur() Removes keypad focus from the element. 4.6 or later

focus() Gives keypad focus to the element. 4.6 or later

Method: HTMLAnchorElement.blur()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxHTMLAnchorElement.blur()

ParametersNone.

Return valuesNone.

ExceptionsNone.

Method: HTMLAnchorElement.focus()

Availability BlackBerry® Device Software version 4.6 or later

The focus() method removes keypad focus from the element.

SyntaxHTMLAnchorElement.focus()

ParametersNone.

Return values

JavaScript Reference Object: HTMLAnchorElement

133

None.

ExceptionsNone.

Object: HTMLAreaElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

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

HTMLAreaElement properties

Property name Type Description Status Availability

accessKey String Specifies the keypad key that gives access to the element. writable 4.6 or later

alt String Specifies alternate text that is rendered when the normal

content of the element is not.

writable 4.6 or later

coords String Specifies a comma-separated list of the coordinates for

HTMLAreaElement.shape, which defines the active

region in an image map.

writable 4.6 or later

href String Specifies the URI of the target of the link. writable 4.6 or later

noHref boolean When true, indicates that the area is inactive and does

not link to another resource.

writable 4.6 or later

shape String Specifies the shape of an active region in an image map.

The coordinates of the shape are specified by

HTMLAreaElement.coords.

writable 4.6 or later

tabIndex int Specifies the element’s position in the tabbing order. writable 4.6 or later

target String Specifies the frame in which to render the target

document.

writable 4.6 or later

JavaScript Reference Object: HTMLAreaElement

134

Object: HTMLAppletElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

The <applet> element embeds an applet into an HTML document. The <applet> element is deprecated in HTML 4.01 andis not supported by the BlackBerry® Browser.

HTMLAppletElement is supported in the BlackBerry Browser’s JavaScript® implementation to conform with the HTML DOMLevel 2 specification. However, <applet> elements will not be visually displayed in the browser and will not have any impacton the document layout.

HTMLAppletElement properties

Property name Type Description Status Availability

align String Specifies the horizontal or vertical alignment the object,

relative to the surrounding text.

writable 4.6 or later

alt String Specifies alternate text that is rendered when the

normal content of the element is not.

writable 4.6 or later

archive String Specifies a comma-separated list of URIs pointing to

archives which contain resources for the applet.

writable 4.6 or later

code String Specifies the location of the class file for the applet. writable 4.6 or later

codeBase String Specifies the Base URI for the applet’s code and data. writable 4.6 or later

height String Specifies the height of the applet. writable 4.6 or later

hspace int Specifies the amount of white space, in pixels, inserted

to the left and right of the applet.

writable 4.6 or later

name String Specifies the name for the applet. writable 4.6 or later

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 4.6 or later

vspace int Specifies the amount of white space, in pixels, inserted

above and below the applet.

writable 4.6 or later

JavaScript Reference Object: HTMLAppletElement

135

Property name Type Description Status Availability

width String Specifies the width of the object. writable 4.6 or later

Object: HTMLBaseElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

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

HTMLBaseElement properties

Property name Type Description Status Availability

href String Specifies the base URI used to resolve all relative URLs

in the document.

writable 4.6 or later

target String Specifies the frame in which to render target documents

by default.

writable 4.6 or later

Object: HTMLBaseFontElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

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

HTMLBaseFontElement properties

Property name Type Description Status Availability

color String Specifies the color of the base font. writable 4.6 or later

JavaScript Reference Object: HTMLBaseElement

136

Property name Type Description Status Availability

face String Specifies a list of font names, listed in order of

preference, in which the base font is rendered.

writable 4.6 or later

size String Specifies the size of the base font. writable 4.6 or later

Object: HTMLBodyElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

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

HTMLBodyElement properties

Property name Type Description Status Availability

aLink String Specifies the color of active links. writable 4.6 or later

background String Specifies the URI of an image to use as the page

background.

writable 4.6 or later

bgColor String Specifies the background color for the page body. writable 4.6 or later

link String Specifies the color of unvisited links. writable 4.6 or later

text String Specifies the color of the body text. writable 4.6 or later

vlink String Specifies the color of visited links. writable 4.6 or later

Object: HTMLBRElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

The <br> element inserts a line break.

JavaScript Reference Object: HTMLBodyElement

137

HTMLBRElement properties

Property name Type Description Status Availability

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

Object: HTMLButtonElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

The <button> element defines a button form control.

HTMLButtonElement properties

Property name Type Description Status Availability

accessKey String Specifies the key that gives access to the form

control.

writable 4.6 or later

disabled boolean When true, indicates that the form control is not

available.

writable 4.6 or later

form HTMLFormEleme

nt

Returns the parent <form> element for the form

control.

read only 4.6 or later

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 4.6 or later

tabIndex int Specifies the tabbing order of the form control. writable 4.6 or later

type String Returns the type of form control. The value for this

property may be button, reset, or submit.

read only 4.6 or later

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 4.6 or later

JavaScript Reference Object: HTMLButtonElement

138

Object: HTMLCollection

Availability BlackBerry® Device Software version 4.6 or later

The HTMLCollection object is an array that contains an ordered collection of nodes. HTMLCollection objects areautomatically 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 orid attribute using HTMLCollection.namedItem() , or you can index the object directly. For example, if you create aninstance of a HTMLCollection object called myHTMLNodes, then specifying

myHTMLNodes.item(2)

myHTMLNodes.namedItem(“item”)

is equivalent to specifying

myHTMLNodes[2]

myHTMLNodes[“item”]

HTMLCollection properties

Property name Type Description Status Availability

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

HTMLCollection methods

Method name Description Availability

item() Returns the node at the specified index. 4.6 or later

namedItem() Retrieves the node with the given name

from the collection.

4.6 or later

JavaScript Reference Object: HTMLCollection

139

Method: HTMLCollection.item()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxHTMLCollection.item( index )

Parameters

Parameter Type Description

index int The index position of the node to be returned. Valid values are between 0 and

HTMLCollection.length -1 inclusive.

Return valuesReturns the node at the index th position in the HTMLCollection array, or null if an invalid index position is specified.

ExceptionsNone.

Method: HTMLCollection.namedItem()

Availability BlackBerry® Device Software version 4.6 or later

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 givenname, then searches for a node with a name attribute that matches the given name if no matching id attribute exists.

When searching HTML documents, this method is case insensitive.• If the document is an XHTML document, this method only searches for nodes with an id attribute that matches the given

name.

When searching XHTML documents, this method is case sensitive.

Syntax

JavaScript Reference Object: HTMLCollection

140

HTMLCollection.namedItem( name )

Parameters

Parameter Type Description

name String The name of the node to retrieve.

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

ExceptionsNone.

Object: HTMLDataListElement

Availability BlackBerry® Device Software version 4.7.1 or later

Extends HTMLElement

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

The <datalist> element contains a list of data values, contained in a one or more child <option> elements.

HTMLDataListElement properties

Property name Type Description Status Availability

options HTMLCollectio

n

Returns a list of the options contained by the

HTMLDataList object.

read-only 4.7.1 or later

Object: HTMLDirectoryElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

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

JavaScript Reference Object: HTMLDataListElement

141

HTMLDirectoryElement properties

Property

nameType Description Status Availability

compact boolean When true, indicates reduced spacing between list items. writable 4.6 or later

Object: HTMLDivElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

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

HTMLDivElement properties

Property name Type Description Status Availability

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

aligned.

writable 4.6 or later

Object: HTMLDListElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

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

JavaScript Reference Object: HTMLDivElement

142

HTMLDListElement properties

Property name Type Description Status Availability

compact boolean When true, indicates reduced spacing between list items. writable 4.6 or later

Object: HTMLDocument

Availability BlackBerry® Device Software version 3.8 or later

Extends Document

The HTMLDocument object provides access to the HTML hierarchy.

HTMLDocument properties

Property name Type Description Status Availability

anchors HTMLCollecti

on

Returns an index of the <a> elements contained within

the document. Index positions begin at 0 and continue

to HTMLCollection.length -1.

read only 3.8 or later

applets HTMLCollecti

on

Returns an index of the <applet> elements and

<object> elements containing applets contained

within the document. Index positions begin at 0 and

continue to HTMLCollection.length -1.

read only 3.8 or later

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 3.8 or later

JavaScript Reference Object: HTMLDocument

143

Property name Type Description Status Availability

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 3.8 or later

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 3.8 or later

domain String Specifies the domain name from which the document was

served.

writable 3.8 or later

forms HTMLCollecti

on

Returns an index of the <form> elements contained

within the document. Index positions begin at 0 and

continue to HTMLCollection.length -1.

read only 3.8 or later

images HTMLCollecti

on

Returns an index of the <img> elements contained

within the document. Index positions begin at 0 and

continue to HTMLCollection.length -1.

read only 3.8 or later

links HTMLCollecti

on

Returns an index of the <link> elements contained in

the document. Index positions begin at 0 and continue

to HTMLCollection.length -1.

read only 3.8 or later

location Location Specifies information about the URI of the document. writable 3.8 or later

referrer String Returns the URL of the document that linked to the active

document.

read only 3.8 or later

title String Specifies the text contained within the <title>

element of the active document.

writable 3.8 or later

URL String Returns the complete URL of the active document. read only 3.8 or later

JavaScript Reference Object: HTMLDocument

144

HTMLDocument event handlers

Property name Type Description Status Availability

onblur EventListene

r

Specifies the function to

perform when an element loses

focus by either the pointer or by

tabbed navigation.

writable 4.6 or later

onchange EventListene

r

Specifies the function to

perform when a form control

loses focus after the user has

modified the value.

writable 4.6 or later

onclick EventListene

r

Specifies the function to

perform when the user clicks the

trackball or trackwheel on a

BlackBerry® device.

writable 3.8 or later

onfocus EventListene

r

Specifies the function to

perform when an element gains

focus by either the pointer or by

tabbed navigation.

writable 4.6 or later

onkeydown EventListene

r

Specifies the function to

perform when a key is pressed

down while the pointer is over

an element.

writable 4.6 or later

onkeypress EventListene

r

Specifies the function to

perform when a key is pressed

and released while the pointer is

over an element.

writable 4.6 or later

onkeyup EventListene

r

Specifies the function to

perform when a key is released

while the pointer is over an

element.

writable 4.6 or later

JavaScript Reference Object: HTMLDocument

145

Property name Type Description Status Availability

onmousedown EventListene

r

Specifies the function to

perform when the user

depresses the trackwheel or

trackball on a BlackBerry device.

writable 3.8 or later

onmousemove EventListene

r

Specifies the function to

perform when the user moves

the pointer over an element.

writable 4.6 or later

onmouseout EventListene

r

Specifies the function to

perform when the user moves

the pointer off of an element.

writable 4.6 or later

onmouseover EventListene

r

Specifies the function to

perform when the user moves

the pointer over an element.

writable 4.6 or later

onmouseup EventListene

r

Specifies the function to

perform when the user releases

the trackwheel or trackball on a

BlackBerry device.

writable 4.6 or later

onreset EventListene

r

Specifies the function to

perform when the user resets a

form.

writable 3.8 or later

onselect EventListene

r

Specifies the function to

perform when the user selects

some text in a text field.

writable 4.6 or later

onsubmit EventListene

r

Specifies the function to

perform when the user submits

a form.

writable 3.8 or later

HTMLDocument methods

Method name Description Availability

close() Closes the document opened by HTMLDocument.open() and forces rendering. 3.8 or later

JavaScript Reference Object: HTMLDocument

146

Method name Description Availability

getElementByName

()

Returns an array of all the elements in the document with the specified name. 4.6 or later

open() Opens a document stream for writing. 3.8 or later

write() Writes a string of text to a document stream opened by HTMLDocument.open

() .

3.8 or later

writeln() Writes a string of text, followed by a new line character to a document stream

opened by HTMLDocument.open() .

3.8 or later

Method: HTMLDocument.close()

Availability BlackBerry® Device Software version 3.8 or later

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

SyntaxHTMLDocument.close()

ParametersNone.

Return valuesNone.

ExceptionsNone.

See alsoHTMLDocument.open()

Method: HTMLDocument.getElementByName()

Availability BlackBerry® Device Software version 4.6 or later

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

This method behaves differently depending on the document type:

JavaScript Reference Object: HTMLDocument

147

• If the document is an HTML document, this method returns all elements with the specified name. When searching HTMLdocuments, this element is case-insensitive.

• If the document is an XHTML document, this method only returns form control elements with the specified name. Whensearching XHTML documents, this method is case sensitive.

SyntaxHTMLDocument.getElementsByName( elementName )

Parameters

Parameter Type Description

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

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

ExceptionsNone.

See alsoDocument.getElementsByTagNameNS() , Element.getElementsByTagName() ,Element.getElementsByTagNameNS()

Method: HTMLDocument.open()

Availability BlackBerry® Device Software version 3.8 or later

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

SyntaxHTMLDocument.open()

ParametersNone.

Return valuesNone.

Exceptions

JavaScript Reference Object: HTMLDocument

148

None.

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

Method: HTMLDocument.write()

Availability BlackBerry® Device Software version 3.8 or later

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

SyntaxHTMLDocument.write( text )

Parameters

Parameter Type Description

text String The text to be parsed.

Return valuesNone.

ExceptionsNone.

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

Method: HTMLDocument.writeln()

Availability BlackBerry® Device Software version 3.8 or later

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

SyntaxHTMLDocument.writeln( text )

Parameters

JavaScript Reference Object: HTMLDocument

149

Parameter Type Description

text String The text to be parsed.

Return valuesNone.

ExceptionsNone.

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

Object: HTMLElement

Availability BlackBerry® Device Software version 4.6 or later

Extends Element

Extended by HTMLAnchorElement , HTMLAppletElement , HTMLAreaElement ,

HTMLBaseElement , HTMLBaseFontElement , HTMLBodyElement ,

HTMLBRElement , HTMLButtonElement , HTMLDirectoryElement ,

HTMLDivElement , HTMLDListElement , HTMLFieldsetElement ,

HTMLFontElement , HTMLFormElement, HTMLFrameElement ,

HTMLFrameSetElement , HTMLHeadElement , HTMLHeadingElement ,

HTMLHRElement , HTMLHtmlElement , HTMLIFrameElement ,

HTMLImageElement , HTMLInputElement , HTMLIsIndexElement ,

HTMLLabelElement , HTMLLegendElement , HTMLLIElement ,

HTMLLinkElement , HTMLMapElement , HTMLMenuElement ,

HTMLMetaElement , HTMLModElement , HTMLObjectElement ,

HTMLOListElement , HTMLOptGroupElement , HTMLOptionElement ,

HTMLParagraphElement , HTMLParamElement , HTMLPreElement ,

HTMLQuoteElement , HTMLScriptElement , HTMLSelectElement ,

HTMLStyleElement , HTMLTableCaptionElement ,

JavaScript Reference Object: HTMLElement

150

HTMLTableCellElement , HTMLTableColElement , HTMLTableElement ,

HTMLTableRowElement , HTMLTableSectionElement ,

HTMLTextAreaElement , HTMLTitleElement , HTMLUListElement

The HTMLElement object extends the Element class. It is the parent class of all HTML elements. This object is used to representthose 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>

HTMLElement properties

Property name Type Description Status Availability

className String Specifies the class attribute of an element. writable 4.6 or later

dir String Specifies the dir attribute of an element. writable 4.6 or later

id String Specifies the id attribute of an element. writable 4.6 or later

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 4.6 or later

lang String Specifies the lang attribute of an element. writable 4.6 or later

offsetHeig

ht

int Returns the height of the element, in pixels. read only 4.6 or later

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 4.6 or later

offsetPare

nt

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 value set to none, this

property returns null.

read only 4.6 or later

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 4.6 or later

offsetWidt

h

int Returns the width of the element, in pixels. read only 4.6 or later

JavaScript Reference Object: HTMLElement

151

Property name Type Description Status Availability

style CSSStyleDecla

ration

Returns the contents of the style attribute that

defines an inline style for an element.

read only 4.6 or later

title String Returns the title attribute of an element. writable 4.6 or later

HTMLElement event handlers

Property name Type Description Status Availability

onblur EventListen

er

Specifies the function to

perform when an element loses

focus by either the pointer or by

tabbed navigation.

writable 4.6 or later

onchange EventListen

er

Specifies the function to

perform when a form control

loses focus after the user has

modified the value.

writable 4.6 or later

onclick EventListen

er

Specifies the function to

perform when the user clicks

the trackball or trackwheel on a

BlackBerry® device.

writable 4.6 or later

onfocus EventListen

er

Specifies the function to

perform when an element gains

focus by either the pointer or by

tabbed navigation.

writable 4.6 or later

onkeydown EventListen

er

Specifies the function to

perform when a key is pressed

down while the pointer is over

an element.

writable 4.6 or later

onkeypress EventListen

er

Specifies the function to

perform when a key is pressed

and released while the pointer

is over an element.

writable 4.6 or later

JavaScript Reference Object: HTMLElement

152

Property name Type Description Status Availability

onkeyup EventListen

er

Specifies the function to

perform when a key is released

while the pointer is over an

element.

writable 4.6 or later

onload EventListen

er

Specifies the function to

perform when the BlackBerry®

Browser finishes loading a new

page or a complete frameset.

writable 4.6 or later

onmousedown EventListen

er

Specifies the function to

perform when the user

depresses the trackwheel or

trackball on a BlackBerry

device.

writable 4.6 or later

onmousemove EventListen

er

Specifies the function to

perform when the user moves

the pointer over an element.

writable 4.6 or later

onmouseout EventListen

er

Specifies the function to

perform when the user moves

the pointer off of an element.

writable 4.6 or later

onmouseover EventListen

er

Specifies the function to

perform when the user moves

the pointer over an element.

writable 4.6 or later

onmouseup EventListen

er

Specifies the function to

perform when the user releases

the trackwheel or trackball on a

BlackBerry device.

writable 4.6 or later

onreset EventListen

er

Specifies the function to

perform when the user resets a

form.

writable 4.6 or later

onselect EventListen

er

Specifies the function to

perform when the user selects

some text in a text field.

writable 4.6 or later

JavaScript Reference Object: HTMLElement

153

Property name Type Description Status Availability

onsubmit EventListen

er

Specifies the function to

perform when the user submits

a form.

writable 4.6 or later

onunload EventListen

er

Specifies the function to

perform when the BlackBerry

Browser removes a new page or

a frameset.

writable 4.6 or later

Object: HTMLFieldsetElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

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

HTMLFieldsetElement properties

Property name Type Description Status Availability

form HTMLFormEleme

nt

Returns the parent <form> element for the form

control.

read only 4.6 or later

Object: HTMLFontElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

The <font> element specifies an inline font change.

JavaScript Reference Object: HTMLFieldsetElement

154

HTMLFontElement properties

Property name Type Description Status Availability

color String Specifies the color of the font. writable 4.6 or later

face String Specifies a list of font names, listed in order of preference,

in which the font is rendered.

writable 4.6 or later

size String Specifies the size of the font. writable 4.6 or later

Object: HTMLFormElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

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

HTMLFormElement properties

Property name Type Description Status Availability

acceptCharset String Specifies a list of valid character sets for form data. writable 4.6.0

action String Specifies a URI to which the form is submitted. writable 4.6.0

elements HTMLCollecti

on

Returns an index of the form control elements

contained within the form. Index positions begin at

0 and continue to HTMLCollection.length

-1.

Image buttons (<input> elements for which

type="image") are excluded from the

collection.

read only 4.6.0

JavaScript Reference Object: HTMLFormElement

155

Property name Type Description Status Availability

enctype String Specifies the content type the form data is encoded

with.

writable 4.6.0

length int Returns the number of form control elements

contained within the form.

read only 4.6.0

method String Specifies the HTTP method used to send the data

to the server.

writable 4.6.0

name String Specifies a unique name for the form. read only 4.6.0

target String Specifies where the target document is opened. writable 4.6.0

HTMLFormElement methods

Method name Description Availability

item() Returns the form control element at he specified index of the collection. 4.7.1 or later

namedItem() Retrieves the form control element or elements whose id or name attributes

that match the given name from the collection.

4.7.1 or later

reset() Restores the default values to the form element. 4.6 or later

submit() Submits the current values of the form element. 4.6 or later

Method: HTMLFormElement.item()

Availability BlackBerry® Device Software version 4.7.1 or later

The item() method returns the element that is located at the specified index of the HTMLFormElement.elementscollection. Image buttons (<input> elements for which type="image") are not included in the collection, and are thereforenot returned with this method.

This method is equivalent to invoking HTMLFormElement.elements[ index ].

SyntaxHTMLFormElement.item( index )

Parameters

JavaScript Reference Object: HTMLFormElement

156

Parameter Type Description

index int Specifies the index position of the element to be returned. Valid values are from 0

and HTMLFormElement.elements -1.

Return valuesThis method returns the element at the index th position in the HTMLFormElement.elements collection, or null if aninvalid index position is specified.

ExceptionsNone.

Method: HTMLFormElement.namedItem()

Availability BlackBerry® Device Software version 4.7.1 or later

The namedItem() method retrieves the element or elements that contain id or name attributes that match the specifiedname from the HTMLFormElement.elements collection. Image buttons (<input> elements for whichtype="image") are not included in the collection, and are therefore not returned with this method.

This method is equivalent to invoking HTMLFormElement.elements["name"].

SyntaxHTMLFormElement.namedItem( name )

Parameters

Parameter Type Description

name String Specifies the name of the element to retrieve.

Return valuesThis method returns the element that has an id or name attribute of name , or null if no element with the specified name existswithin the HTMLFormElement.elements collection. If multiple elements match, this method returns a NodeList objectthat contains all the matching elements.

ExceptionsNone.

JavaScript Reference Object: HTMLFormElement

157

Method: HTMLFormElement.reset()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxHTMLFormElement.reset()

ParametersNone.

Return valuesNone.

ExceptionsNone.

Method: HTMLFormElement.submit()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxHTMLFormElement.submit()

ParametersNone.

Return valuesNone.

ExceptionsNone.

JavaScript Reference

158

Object: HTMLFrameElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

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

HTMLFrameElement properties

Property name Type Description Status Availability

contentDocumen

t

Document Returns a reference to the Document object that the frame

contains.

read only 4.6 or later

contentWindow Window Returns a reference to the Window object that contains the

frame.

read only 4.6 or later

frameBorder String Specifies whether or not a separator is displayed around the

frame.

writable 4.6 or later

longDesc String Specifies a URL where the content of the frame is described. writable 4.6 or later

marginHeight String Specifies the top and bottom margins for the frame. The

value must be greater than 0.

writable 4.6 or later

marginWidth String Specifies the left and right margins of the frames. The value

must be greater than 0.

writable 4.6 or later

name String Specifies a unique name for the frame. writable 4.6 or later

noResize boolean When true, indicates that the user cannot resize the frame. writable 4.6 or later

scrolling String Specifies the scrolling behavior. writable 4.6 or later

src String Specifies the URL of the source content for the frame. writable 4.6 or later

Object: HTMLFrameSetElement

Availability BlackBerry® Device Software version 4.6 or later

JavaScript Reference Object: HTMLFrameElement

159

Extends HTMLElement

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

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

HTMLFrameSetElement properties

Property name Type Description Status Availability

cols String Specifies the layout of columns in the frameset. writable 4.6 or later

rows String Specifies the layout of rows in the frameset. writable 4.6 or later

Object: HTMLHeadElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

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

HTMLHeadElement properties

Property name Type Description Status Availability

profile String Specifies the URLs that contain metadata about the

document.

writable 4.6 or later

Object: HTMLHeadingElement

Availability BlackBerry® Device Software version 4.6 or later

JavaScript Reference Object: HTMLHeadElement

160

Extends HTMLElement

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

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

HTMLHeadingElement properties

Property name Type Description Status Availability

align String Specifies the horizontal alignment of the heading text. writable 4.6 or later

Object: HTMLHRElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

The <hr> element renders a horizontal line.

HTMLHRElement properties

Property name Type Description Status Availability

align String Specifies the horizontal alignment of the horizontal line

on the page.

writable 4.6 or later

noShade boolean When true, indicates that no shading is applied to the

horizontal line.

writable 4.6 or later

size String Specifies the height of the horizontal line. writable 4.6 or later

width String Specifies the width of the horizontal line. writable 4.6 or later

Object: HTMLHtmlElement

Availability BlackBerry® Device Software version 4.6 or later

JavaScript Reference Object: HTMLHRElement

161

Extends HTMLElement

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

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

HTMLHtmlElement properties

Property name Type Description Status Availability

version String Specifies version information about the document DTD. writable 4.6 or later

Object: HTMLIFrameElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

The <iframe> element defines an inline frame.

HTMLIFrameElement properties

Property name Type Description Status Availability

align String Specifies the horizontal alignment of the horizontal

line on the page.

writable 4.6 or later

contentDocumen

t

Document Returns a reference to the Document object that

the frame contains.

read only 4.6 or later

contentWindow Window Returns a reference to the Window object that

contains the frame.

writable 4.6 or later

frameBorder String Specifies whether or not a separator is displayed

around the frame.

writable 4.6 or later

height String Specifies the height of the frame. writable 4.6 or later

longDesc String Specifies a URL where the content of the frame is

described.

writable 4.6 or later

JavaScript Reference Object: HTMLIFrameElement

162

Property name Type Description Status Availability

marginHeight String Specifies the top and bottom margins for the frame.

The value must be greater than 0.

writable 4.6 or later

marginWidth String Specifies the left and right margins of the frames.

The value must be greater than 0.

writable 4.6 or later

name String Specifies a unique name for the frame. writable 4.6 or later

scrolling String Specifies the scrolling behavior. writable 4.6 or later

src String Specifies the URL of the source content for the frame. writable 4.6 or later

width String Specifies the width of the frame. writable 4.6 or later

Object: HTMLImageElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

The <img> element defines an image to display.

HTMLImageElement properties

Property name Type Description Status Availability

align String Specifies the vertical or horizontal alignment of the

image on the page.

writable 4.6 or later

alt String Specifies the text that appears when an image is

unavailable or cannot be displayed.

writable 4.6 or later

border String Specifies the width of a border around an image. writable 4.6 or later

height int Specifies the width of a border around an image. writable 4.6 or later

hspace int Specifies the amount of whitespace padding added to

the left and right of the image.

writable 4.6 or later

isMap boolean When true, indicates that the image uses a server-

side image map.

writable 4.6 or later

JavaScript Reference Object: HTMLImageElement

163

Property name Type Description Status Availability

longDesc String Specifies the URI of a document that provides a long

description of the image.

writable 4.6 or later

name String Specifies a unique name for the image. writable 4.6 or later

src String Specifies the URI of the source image. writable 4.6 or later

usemap String Specifies the client-side map to use with this image. writable 4.6 or later

vspace int Specifies the amount of whitespace padding added to

the top and bottom of the image.

writable 4.6 or later

width int Specifies the width of the image, with the unit of

measurement.

writable 4.6 or later

Object: HTMLInputElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

The <input> element defines a user input object.

HTMLInputElement properties

Property name Type Description Status Availability

accept String Specifies a comma-separated list of content types

that this form accepts.

writable 4.6 or later

accessKey String Specifies the keypad key that gives access to the

element.

writable 4.6 or later

align String Specifies the vertical or horizontal alignment of the

image on the page.

writable 4.6 or later

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 4.6 or later

JavaScript Reference Object: HTMLInputElement

164

Property name Type Description Status Availability

checked boolean When true and HTMLInputElement.type has

a value of checkbox or radio, indicates that the

check box or radio button appears selected, and its

value is included when the form is submitted.

writable 4.6 or later

defaultChecked boolean When true and HTMLInputElement.type has

a value of checkbox or radio, 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 4.6 or later

defaultValue String When HTMLInputElement.type has a value

other than button, checkbox, hidden, image,

reset, or submit, 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 4.6 or later

disabled boolean When true, indicates that the form control is not

available.

writable 4.6 or later

form HTMLFormEle

ment

Returns the parent <form> element for the form

control.

read only 4.6 or later

list HTMLElement Returns the associated <datalist> element

containing the list of value suggestions, if one exists.

If no associated <datalist> element exists, this

property returns null.

read only 4.7.1 or later

maxLength int When HTMLInputElement.type has a value of

email, password, search, text, or url,

specifies the maximum number of characters

permitted as input into the text field.

writable 4.6 or later

name String Specifies the amount of whitespace padding added

to the top and bottom of the image.

writable 4.6 or later

readonly boolean When HTMLInputElement.type has a value of

of email, password, search, text, or url and

this property is true, indicates that the form control

cannot be modified by a user.

writable 4.6 or later

JavaScript Reference Object: HTMLInputElement

165

Property name Type Description Status Availability

size int Specifies the size of the form control. writable 4.6 or later

src String When HTMLInputElement.type has a value of

image, specifies the URI of the source image.

writable 4.6 or later

tabIndex int Specifies the element’s position in the tabbing order. writable 4.6 or later

type String Specifies the type of form control this input element

is. This property may have the following values:

• button

• checkbox

• date (4.7.1 or later)

• datetime (4.7.1 or later)

• datetime-local (4.7.1 or later)

• email (4.7.1 or later)

• file

• hidden

• image

• month (4.7.1 or later)

• number (4.7.1 or later)

• password

• radio

• range (4.7.1 or later)

• reset

• search (4.7.1 or later)

• submit

• text

• time (4.7.1 or later)

• url (4.7.1 or later)

• week (4.7.1 or later)

writable type-

dependent

useMap String When HTMLInputElement.type has a value of

image, specifies the client-side map to use with this

image.

writable 4.6 or later

JavaScript Reference Object: HTMLInputElement

166

Property name Type Description Status Availability

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 4.6 or later

valueAsDate long Specifies the value of the element interpreted as a

date. The browser represents this number as the

number of milliseconds elapsed from origin

(Midnight UTC, the morning of January 1, 1970).

This property can be used with all date- and time-

based input types, excluding the datetime-

local input type.

writable 4.7.1 or later

valueAsNumber float Specifies the value of the element interpreted as a

number.

This property can be used with the number and

range input types.

writable 4.7.1 or later

HTMLInputElement methods

Method name Description Availability

blur() Removes keypad focus from the element. 4.6 or later

click() Simulates a mouse click. 4.6 or later

focus() Gives keypad focus to the element. 4.6 or later

select() Selects the contents of the element. 4.6 or later

stepDown() Reduces the value of the form control element by the given value. 4.7.1 or later

stepUp() Increases the value of the form control element by the given value. 4.7.1 or later

Method: HTMLInputElement.blur()

Availability BlackBerry® Device Software version 4.6 or later

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

Syntax

JavaScript Reference Object: HTMLInputElement

167

HTMLInputElement.blur()

ParametersNone.

Return valuesNone.

ExceptionsNone.

Method: HTMLInputElement.click()

Availability BlackBerry® Device Software version 4.6 or later

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

ParametersNone.

Return valuesNone.

ExceptionsNone.

Method: HTMLInputElement.focus()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxHTMLInputElement.focus()

Parameters

JavaScript Reference Object: HTMLInputElement

168

None.

Return valuesNone.

ExceptionsNone.

Method: HTMLInputElement.select()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxHTMLInputElement.select()

ParametersNone.

Return valuesNone.

ExceptionsNone.

Method: HTMLInputElement.stepDown()

Availability BlackBerry® Device Software version 4.7.1 or later

The stepDown() method decreases the value of the form control by the specified value.

SyntaxHTMLInputElement.stepDown( increment )

Parameters

Parameter Type Description

increment long Specifies the amount by which the value is decreased.

JavaScript Reference Object: HTMLInputElement

169

Parameter Type Description

If the resulting value is less than the value of the element's min attribute, then

HTMLInputElement.value is not changed.

Return valuesNone.

ExceptionsNone.

Method: HTMLInputElement.stepUp()

Availability BlackBerry® Device Software version 4.7.1 or later

The stepUp() method increases the value of the form control by the specified value.

SyntaxHTMLInputElement.stepUp( increment )

Parameters

Parameter Type Description

increment long Specifies the amount by which the value is increased.

If the resulting value is greater than the value of the element's max attribute, then

HTMLInputElement.value is not changed.

Return valuesNone.

ExceptionsNone.

Object: HTMLIsIndexElement

Availability BlackBerry® Device Software version 4.6 or later

JavaScript Reference Object: HTMLIsIndexElement

170

Extends HTMLElement

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

The <isindex> element specifies that the enclosed text is single-line text input. This element is deprecated in HTML 4.01, andis not supported by the BlackBerry® Browser.

HTMLIsIndexElement is supported in the BlackBerry Browser’s JavaScript® implementation to conform with HTML DOMLevel 2 specification. However, <isindex> elements will not be visually displayed in the browser and will not have any impacton the document layout.

HTMLIsIndexElement properties

Property name Type Description Status Availability

form HTMLFormElem

ent

Returns the parent <form> element for the form

control.

read only 4.6 or later

prompt String Specifies the prompt message. writable 4.6 or later

Object: HTMLLabelElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

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

HTMLLabelElement properties

Property

nameType Description Status Availability

accessKey String Specifies the keypad key that gives access to the element. writable 4.6 or later

form HTMLFormEle

ment

Returns the parent <form> element for the form control. read only 4.6 or later

JavaScript Reference Object: HTMLLabelElement

171

Property

nameType Description Status Availability

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 4.6 or later

Object: HTMLLegendElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

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

HTMLLegendElement properties

Property name Type Description Status Availability

accessKey String Specifies the keypad key that gives access to the element. writable 4.6 or later

align String Specifies the horizontal or vertical alignment of the

caption relative to the parent <fieldset> element.

writable 4.6 or later

form HTMLFormElem

ent

Returns the parent <form> element for the form control. read only 4.6 or later

Object: HTMLLIElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

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

JavaScript Reference Object: HTMLLegendElement

172

HTMLIElement properties

Property name Type Description Status Availability

type String Specifies the bullet or number style for the list. writable 4.6 or later

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 4.6 or later

Object: HTMLLinkElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

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

HTMLLinkElement properties

Property name Type Description Status Availability

charset String Specifies the character encoding used in the referenced

document; the value must be the name of a standard

character set.

writable 4.6 or later

disabled boolean When true, indicates that this link is disabled. writable 4.6 or later

href String Specifies the target of the link. writable 4.6 or later

hreflang String Specifies the base language of the target document. writable 4.6 or later

media String Specifies the destination medium for the link. writable 4.6 or later

rel String Specifies the relationship between the current page and

the referenced document. For example,

“stylesheet”.

writable 4.6 or later

rev String Describes a link relationship from the referenced target

document to the source document.

writable 4.6 or later

JavaScript Reference Object: HTMLLinkElement

173

Property name Type Description Status Availability

sheet StyleShe

et

The StyleSheet object associated with the element. read only 4.6 or later

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 4.6 or later

type String Specifies the MIME type of the target document. writable 4.6 or later

Object: HTMLMapElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

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

HTMLMapElement properties

Property name Type Description Status Availability

areas HTMLCollecti

on

Returns an index of the active regions contained within

the map. Index positions begin at 0 and continue to

HTMLCollection.length -1.

read only 4.6 or later

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 4.6 or later

JavaScript Reference Object: HTMLMapElement

174

Object: HTMLMenuElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

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

HTMLMenuElement properties

Property name Type Description Status Availability

compact boolean When true, indicates reduced spacing between list items. writable 4.6 or later

Object: HTMLMetaElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

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

HMTLMetaElement properties

Property name Type Description Status Availability

content String Specifies the value of a property. writable 4.6 or later

httpEquiv String Specifies the HTTP response header name. writable 4.6 or later

name String Specifies the name used to identify the meta information. writable 4.6 or later

scheme String Specifies the name of the scheme used to interpret the

value of the content property.

writable 4.6 or later

JavaScript Reference Object: HTMLMenuElement

175

Object: HTMLModElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

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

HTMLModElement properties

Property name Type Description Status Availability

cite String Specifies the URI of a document that explains why the text

was modified.

writable 4.6 or later

dateTime String Specifies the date and time that the enclosed text was

modified.

writable 4.6 or later

Object: HTMLObjectElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

The <object> element specifies an embedded object.

HTMLObjectElement properties

Property name Type Description Status Availability

align String Specifies the horizontal or vertical alignment of

the object.

writable 4.6 or later

archive String Specifies a whitespace-separated list of URLs for

archives which contain resources for the object.

writable 4.6 or later

JavaScript Reference Object: HTMLModElement

176

Property name Type Description Status Availability

border String Specifies the width of the border around the

object.

writable 4.6 or later

code String Specifies the location of the class ID for the object. writable 4.6 or later

codeBase String Specifies the root location for the object’s code

and data.

writable 4.6 or later

codeType String Specifies the MIME type for the data downloaded

for use by the object.

writable 4.6 or later

contentDocumen

t

Document Returns the document this object contains, if

there is one. If the object contains no document,

this property returns null.

read only 4.6 or later

data String Specifies the URI that defines the location of the

object’s data.

writable 4.6 or later

declare boolean When true, indicates that this object should be

declared, but not instantiated.

writable 4.6 or later

form HTMLFormEleme

nt

Returns the form that contains this object. If the

object is not contained by a form, this property

returns null.

writable 4.6 or later

height String Specifies the height of the object. writable 4.6 or later

hspace int Specifies the amount of whitespace, in pixels,

inserted to the left and right of the object.

writable 4.6 or later

name String Specifies the name for the object. writable 4.6 or later

standby String Specifies text to display while the object is

loading.

writable 4.6 or later

tabIndex int Specifies the object's position in the tabbing

order.

writable 4.6 or later

type String Specifies the MIME type for the data specified by

the data property.

writable 4.6 or later

useMap String Specifies the location of a client side map used

with the object, if the object is an image.

writable 4.6 or later

vspace int Specifies the amount of white space, in pixels,

inserted above and below the object.

writable 4.6 or later

width String Specifies the width of the object. writable 4.6 or later

JavaScript Reference Object: HTMLObjectElement

177

Object: HTMLOListElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

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

HTMLOListElement properties

Property name Type Description Status Availability

compact boolean When true, indicates reduced spacing between list

items.

writable 4.6 or later

start int Specifies the starting value for the numbering sequence. writable 4.6 or later

type String Specifies the numbering style to use. writable 4.6 or later

Object: HTMLOptGroupElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

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

HTMLOptGroupElement properties

Property name Type Description Status Availability

disabled boolean When true, indicates that the option group is disabled. writable 4.6 or later

label String Specifies a label for the option group. writable 4.6 or later

JavaScript Reference Object: HTMLOListElement

178

Object: HTMLOptionElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

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

HTMLOptionElement properties

Property name Type Description Status Availability

defaultSelect

ed

boolean When true, indicates that the option is selected by

default.

writable 4.6 or later

disabled boolean When true, indicates that the option is not

available.

writable 4.6 or later

form HTMLFormElem

ent

Returns the form that contains the option. If this

element is not contained by a form, this property

returns null.

read only 4.6 or later

index int Returns the position of this option within the parent

<select> element.

read only 4.6 or later

label String Specifies a label for the option. writable 4.6 or later

selected boolean When true, indicates that the option is currently

selected.

writable 4.6 or later

text String Specifies the text contained within the <option>

element.

writable 4.6 or later

value String Specifies the value of the option that is sent to the

server when the form is submitted.

writable 4.6 or later

Object: HTMLOptionsCollection

Availability BlackBerry® Device Software version 4.6 or later

JavaScript Reference Object: HTMLOptionElement

179

Extends HTMLElement

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. Forexample, if you create an instance of a HTMLOptionsCollection object called myHTMLOptions, then specifying

myHTMLOptions.item(2)

myHTMLOptions.namedItem(“item”)

is equivalent to specifying

myHTMLOptions[2]

myHTMLOptions[“item”]

HTMLOptionsCollection properties

Property name Type Description Status Availability

length int Returns the number of HTMLOptionElement objects

contained in the list.

read only 4.6 or later

HTMLOptionsCollection methods

Method name Description Availability

item() Retrieves a specific option node, by index, from the collection. 4.6 or later

namedItem() Retrieves the option node with the given name or id property value from the

collection.

4.6 or later

Method: HTMLOptionsCollection.item()

Availability BlackBerry® Device Software version 4.6 or later

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

Syntax

JavaScript Reference Object: HTMLOptionsCollection

180

HTMLOptionsCollection.item( index )

Parameters

Parameter Type Description

index int The index position of the node to be returned. Valid values are

between 0 and HTMLOptionsCollection.length -1

inclusive.

Return valuesReturns the node at the index th position in the HTMLOptionsCollection array, or null if an invalid index position isspecified.

ExceptionsNone.

Method: HTMLOptionsCollection.namedItem()

Availability BlackBerry® Device Software version 4.6 or later

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

Parameter Type Description

name String The name of the node to retrieve.

Return values

JavaScript Reference Object: HTMLOptionsCollection

181

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

ExceptionsNone.

Method: HTMLOptionsCollection.item()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxHTMLOptionsCollection.item( index )

Parameters

Parameter Type Description

index int The index position of the node to be returned. Valid values are

between 0 and HTMLOptionsCollection.length -1

inclusive.

Return valuesReturns the node at the index th position in the HTMLOptionsCollection array, or null if an invalid index position isspecified.

ExceptionsNone.

Method: HTMLOptionsCollection.namedItem()

Availability BlackBerry® Device Software version 4.6 or later

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 givenname, 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.

JavaScript Reference Object: HTMLOptionsCollection

182

• If the document is an XHTML document, this method only searches for nodes with an id attribute that matches the givenname.

When searching XHTML documents, this method is case sensitive.

SyntaxHTMLOptionsCollection.namedItem( name )

Parameters

Parameter Type Description

name String The name of the node to retrieve.

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

ExceptionsNone.

Object: HTMLParagraphElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

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

HTMLParagraphElement properties

Property name Type Description Status Availability

align String Specifies the horizontal alignment of the paragraph on

the page.

writable 4.6 or later

JavaScript Reference Object: HTMLParagraphElement

183

Object: HTMLParamElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

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

HTMLParamElement properties

Property name Type Description Status Availability

name String Specifies a unique name for the parameter. writable 4.6 or later

type String Specifies the content type. writable 4.6 or later

value String Specifies the value of the parameter. writable 4.6 or later

valueType String Specifies the type of the value property. The value

property 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 4.6 or later

Object: HTMLPreElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

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

JavaScript Reference Object: HTMLParamElement

184

HTMLPreElement properties

Property name Type Description Status Availability

width int Specifies the width of the content block. writable 4.6 or later

Object: HTMLQuoteElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

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

HTMLQuoteElement properties

Property name Type Description Status Availability

cite String Specifies a URL citation to indicate the source of the

quotation.

writable 4.6 or later

Object: HTMLScriptElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

The <script> element defines a script.

JavaScript Reference Object: HTMLQuoteElement

185

HTMLScriptElement properties

Property name Type Description Status Availability

charset String Specifies the character encoding used in the script. writable 4.6 or later

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 4.6 or later

event String This property is not currently defined in the DOM HTML

specification.

undefined 4.6 or later

htmlFor String This property is not currently defined in the DOM HTML

specification.

undefined 4.6 or later

src String Specifies the URI where an external script document is

located.

writable 4.6 or later

text String Specifies the script content. writable 4.6 or later

type String Specifies the content type of the script.

The BlackBerry Browser engine ignores this variable

when determining whether or not to execute the

content as JavaScript®. Instead, the browser checks the

language attribute.

writable 4.6 or later

Object: HTMLSelectElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

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

JavaScript Reference Object: HTMLSelectElement

186

HTMLSelectElement properties

Property name Type Description Status Availability

disabled boolean When true, indicates that the form control is not

available.

writable 4.6 or later

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 4.6 or later

length int Specifies the number of <option> elements the

selection list contains.

writable 4.6 or later

multiple boolean When true, indicates that more than one option

may be selected from the list.

writable 4.6 or later

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 4.6 or later

options HTMLOptionsCollec

tion

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 4.6 or later

selectIndex int Specifies the index position of the selected

option.

writable 4.6 or later

size int Specifies the number of visible rows. writable 4.6 or later

tabIndex int Specifies the tabbing order of the form control. writable 4.6 or later

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

read only 4.6 or later

JavaScript Reference Object: HTMLSelectElement

187

Property name Type Description Status Availability

• When

HTMLSelectElement.multiple has

a value of “false”, the value for this

property is “select-one”.

value String Specifies the value of the currently selected

option(s). This is the value portion of the name-

value pair that is submitted with the form.

writable 4.6 or later

Methods

Method name Description

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

blur() Removes keypad focus from the element.

focus() Gives keypad focus to the element.

remove() Removes an option from the selection list.

Method: HTMLSelectElement.add()

Availability BlackBerry® Device Software version 4.6 or later

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, thismethod functions the same as Node.insertBefore() .

SyntaxHTMLSelectElement.add( element, before )

Parameters

Parameter Type Description

element HTMLElement The element to insert.

before HTMLElement The existing child element before which element is inserted.

JavaScript Reference Object: HTMLSelectElement

188

Parameter Type Description

If before is not specified or is null, element is inserted at the end of the

list of children.

Return valuesNone.

Exceptions

Exception Description

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

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

Method: HTMLSelectElement.blur()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxHTMLSelectElement.blur()

ParametersNone.

Return valuesNone.

ExceptionsNone.

JavaScript Reference Object: HTMLSelectElement

189

Method: HTMLSelectElement.focus()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxHTMLSelectElement.focus()

ParametersNone.

Return valuesNone.

ExceptionsNone.

Method: HTMLSelectElement.remove()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxHTMLSelectElement.remove( index )

Parameters

Parameter Type Description

index int The position in the HTMLSelectElement.options index of the element to

remove from the selection list.

Return valuesNone.

ExceptionsNone.

JavaScript Reference

190

Object: HTMLStyleElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

The <style> element defines an internal style sheet.

HTMLStyleElement properties

Property name Type Description Status Availability

disabled boolean When true, indicates that the style sheet is not applied

to the document.

writable 4.6 or later

media String Specifies the destination medium for the style

information.

writable 4.6 or later

sheet StyleShe

et

Returns the StyleSheet object associated with the

element.

read only 4.6 or later

type String Specifies the content type of the style sheet language. writable 4.6 or later

Object: HTMLTableCaptionElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

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

HTMLTableCaptionElement properties

Property name Type Description Status Availability

align String Specifies the horizontal alignment of the table caption. writable 4.6 or later

JavaScript Reference Object: HTMLStyleElement

191

Object: HTMLTableCellElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

The HTMLTableCellElement object represents <td> and <th> elements in an HTML document.

The <td> element specifies a cell in a table. The <th> element specifies a table heading cell.

HTMLTableCellElement properties

Property name Type Description Status Availability

abbr String Specifies an abbreviated version of the cell text. writable 4.6 or later

align String Specifies the horizontal alignment of the cell data. writable 4.6 or later

axis String Specifies a list of category names used to organize cell

content.

undefined 4.6 or later

bgColor String This property is not currently defined in the DOM HTML

specification.

writable 4.6 or later

cellIndex int Returns the index position of the cell in the parent row’s

HTMLTableRowElement.cells array.

read only 4.6 or later

ch String Specifies the alignment character for cells in a column. writable 4.6 or later

chOff String Specifies the distance between the alignment

character and the first adjacent character.

writable 4.6 or later

colSpan int Specifies the number of columns the table cell spans. writable 4.6 or later

headers String Specifies for which sides of the table the border will be

visible.

writable 4.6 or later

height String Specifies the height of the table cell. writable 4.6 or later

noWrap boolean When true, indicates that text is not wrapped in the

cell.

writable 4.6 or later

rowSpan int Specifies the number of rows the table cell spans. writable 4.6 or later

scope String Specifies whether the cell provides header information

for the column, column group, row, or row group.

writable 4.6 or later

JavaScript Reference Object: HTMLTableCellElement

192

Property name Type Description Status Availability

vAlign String Specifies the vertical alignment of the content within

the table cell.

writable 4.6 or later

width String Specifies the width of the table cell. writable 4.6 or later

Object: HTMLTableColElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

The HTMLTableColElement object represents the <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 oftable columns. These elements are not supported by the BlackBerry® Browser.

HTMLTableColElement is supported in the BlackBerry Browser’s JavaScript® implementation to conform with HTML DOMLevel 2 specification. However, <col> and <colgroup> elements will not be visually displayed in the browser and will nothave any impact on the document layout.

HTMLTableColElement properties

Property name Type Description Status Availability

align String Specifies the horizontal alignment of the cell data. writable 4.6 or later

ch String Specifies the alignment character for cells in a column. writable 4.6 or later

chOff String Specifies the distance between the alignment character

and the first adjacent character.

writable 4.6 or later

span int Specifies the number of columns included in a column

group.

writable 4.6 or later

vAlign String Specifies the vertical alignment of the content within the

table cell.

writable 4.6 or later

width String Specifies the width of the table cell. writable 4.6 or later

JavaScript Reference Object: HTMLTableColElement

193

Object: HTMLTableElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

The <table> element specifies the start of a table.

HTMLTableElement properties

Property name Type Description Status Availability

align String Specifies the horizontal alignment of the table. writable 4.6 or later

bgColor String Specifies the background color for the table. writable 4.6 or later

border String Specifies the thickness of the border around the

table cells.

writable 4.6 or later

caption HTMLTableCaptionEl

ement

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 4.6 or later

cellPadding String Specifies the amount of white space, in pixels,

to add between cell content and its borders.

writable 4.6 or later

cellSpacing String Specifies the amount of white space, in pixels,

to add between cells.

writable 4.6 or later

frame String Specifies for which sides of the table the border

will be visible.

writable 4.6 or later

rows HTMLCollection Returns an index of the rows contained within

the table, starting at 0.

read only 4.6 or later

rules String Specifies the location of rules in the table. writable 4.6 or later

summary String Specifies summary text that describes the

contents of the table.

writable 4.6 or later

JavaScript Reference Object: HTMLTableElement

194

Property name Type Description Status Availability

tBodies HTMLCollection Returns an index of all the <tbody> element

in the table.

read only 4.6 or later

tFoot HTMLTableCaptionEl

ement

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 4.6 or later

tHead HTMLTableCaptionEl

ement

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 4.6 or later

width String Specifies the width of the table, in pixels, or as

a percentage of the BlackBerry® Browser

window.

writable 4.6 or later

HTMLTableElement methods

Method name Description Availability

createCaption() Creates a new table caption, if the table does not already contain one. 4.6 or later

createTFoot() Creates a new table footer, it the table does not already contain one. 4.6 or later

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

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

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

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

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

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

JavaScript Reference Object: HTMLTableElement

195

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

SyntaxHTMLTableElement.createCaption()

ParametersNone.

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

ExceptionsNone.

Method: HTMLTableElement.createTFoot()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxHTMLTableElement.createTFoot()

ParametersNone.

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

ExceptionsNone.

JavaScript Reference Object: HTMLTableElement

196

Method: HTMLTableElement.createTHead()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxHTMLTableElement.createTHead()

ParametersNone.

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

ExceptionsNone.

Method: HTMLTableElement.deleteCaption()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxHTMLTableElement.deleteCaption()

ParametersNone.

Return valuesNone.

ExceptionsNone.

JavaScript Reference Object: HTMLTableElement

197

Method: HTMLTableElement.deleteRow()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxHTMLTableElement.deleteRow( index )

Parameters

Parameter Type Description

index int The index position of the row to remove from the table.

If index has a value of -1, or is equal to the number of rows in

the table, the last row in the table is removed.

Return valuesNone.

Exceptions

Exception Description

INDEX_SIZE_ERR This error is thrown if index exceeds the number of rows in the

table, or has a negative value other than -1.

Method: HTMLTableElement.deleteTFoot()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxHTMLTableElement.deleteTFoot()

ParametersNone.

Return values

JavaScript Reference Object: HTMLTableElement

198

None.

ExceptionsNone.

Method: HTMLTableElement.deleteTHead()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxHTMLTableELement.deleteTHead()

ParametersNone.

Return valuesNone.

ExceptionsNone.

Method: HTMLTableElement.insertRow()

Availability BlackBerry® Device Software version 4.6 or later

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

Parameter Type Description

index int The index position at which to insert the new row in the table.

JavaScript Reference Object: HTMLTableElement

199

Parameter Type Description

If index has a value of -1, or is equal to the number of rows in

the table, the new row is added to the end of the table.

Return valuesReturns the newly added row.

Exceptions

Exception Description

INDEX_SIZE_ERR This error is thrown if index exceeds the number of rows in the

table, or has a negative value other than -1.

See AlsoHTMLTableRowElement.insertCell()

Object: HTMLTableRowElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

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

The <tr> element specifies a table row.

HTMLTableRowElement properties

Property name Type Description Status Availability

align String Specifies the horizontal alignment of the cell data. writable 4.6 or later

bgColor String Specifies the background color for the table cell. writable 4.6 or later

cells HTMLCollectio

n

Returns an index of the table cells contained within

the table row, starting at 0.

read only 4.6 or later

ch String Specifies the alignment character for cells in a

column.

writable 4.6 or later

JavaScript Reference Object: HTMLTableRowElement

200

Property name Type Description Status Availability

chOff String Specifies the distance the distance between the

alignment character and the first adjacent

character.

writable 4.6 or later

rowIndex int Returns the index position of the row in the parent

table’s HTMLTableElement.rows array.

read only 4.6 or later

sectionRowInde

x

int Returns the index position of the row in the parent

table section’s

HTMLTableSectionElement.rows array.

read only 4.6 or later

vAlign String Specifies the vertical alignment of the content

within the table cell.

writable 4.6 or later

HTMLTableRowElement methods

Method name Description Availability

deleteCell() Removes the table cell at the given index position. 4.6 or later

insertCell() Inserts a new empty table cell into the row at the given index position. 4.6 or later

Method: HTMLTableRowElement.deleteCell()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxHTMLTableRowElement.deleteCell( index )

Parameters

Parameter Type Description

index int The index position of the row to remove from the table.

JavaScript Reference Object: HTMLTableRowElement

201

Parameter Type Description

If index has a value of -1, or is equal to the number of table cells in the row, the

last table cell in the row is removed.

Return valuesNone.

Exceptions

Exception Description

INDEX_SIZE_ERR This error is thrown if index exceeds the number of table cells in the row, or has

a negative value other than -1.

Method: HTMLTableRowElement.insertCell()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxHTMLTableRowElement.insertCell( index )

Parameters

Parameter Type Description

index int The index position at which to insert the new cell in the row.

If index has a value of -1, or is equal to the number of table cells in the row,

the new row is added to the end of the table.

Return valuesReturns the newly added table cell.

Exceptions

Exception Description

INDEX_SIZE_ERR This error is thrown if index exceeds the number of table cells in the row, or

has a negative value other than -1.

JavaScript Reference

202

Object: HTMLTableSectionElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

The HTMLTableSectionElement object represents a <tbody>, <tfoot>, or <thead> element in an HTML document.

The <tbody> element specifies a table body section. The <tfoot> and <thead> elements specify the table footer and tableheader, respectively.

HTMLTableSectionElement properties

Property name Type Description Status Availability

align String Specifies the horizontal alignment of the cell data. writable 4.6 or later

ch String Specifies the alignment character for cells in a

column.

writable 4.6 or later

chOff String Specifies the distance the distance between the

alignment character and the first adjacent character.

writable 4.6 or later

rows HTMLCollect

ion

Returns an index of the rows contained within the

table section, starting at 0.

read only 4.6 or later

vAlign String Specifies the vertical alignment of the content within

the table cell.

writable 4.6 or later

HTMLTableSectionElement methods

Method name Description Availability

deleteRow() Removes the row at the given index position from the table section. 4.6 or later

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

JavaScript Reference Object: HTMLTableSectionElement

203

Method: HTMLTableSectionElement.deleteRow()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxHTMLTableSectionElement.deleteRow( index )

Parameters

Parameter Type Description

index int The index position of the row to remove from the table section.

If index has a value of -1, or is equal to the number of rows in the table section,

the last row in the section is removed.

Return valuesNone.

Exceptions

Exception Description

INDEX_SIZE_ERR This error is thrown if index exceeds the number of rows in the table section,

or has a negative value other than -1.

Method: HTMLTableSectionElement.insertRow()

Availability BlackBerry® Device Software version 4.6 or later

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

JavaScript Reference Object: HTMLTableSectionElement

204

Parameter Type Description

index int The index position at which to insert the new row in the table section.

If index has a value of -1, or is equal to the number of rows in the table section,

the new row is added to the end of the section.

Return valuesReturns the newly added row.

Exceptions

Exception Description

INDEX_SIZE_ERR This error is thrown if index exceeds the number of rows in the table section,

or has a negative value other than -1.

See AlsoHTMLTableRowElement.insertCell()

Object: HTMLTextAreaElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

The HTMLTextAreaElement object provides access to <textarea> elements within an HTML document.

The <textarea> element specifies a multiline text entry field in a form. It can optionally contain plain text, which is displayedto the user in the text area.

HTMLTextAreaElement properties

Property name Type Description Status Availability

accessKey String Specifies the keypad key that gives access to the form

control.

writable 4.6 or later

cols int Specifies the width of the text area control, in

characters.

writable 4.6 or later

JavaScript Reference Object: HTMLTextAreaElement

205

Property name Type Description Status Availability

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 4.6 or later

disabled boolean When true, indicates that the text area control is not

available.

writable 4.6 or later

form HTMLFormEleme

nt

Returns the parent <form> element for the form

control.

Specifies the amount of white space, in pixels, to add

between cell content and its borders.

read only 4.6 or later

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 4.6 or later

readonly boolean When true, indicates that the form control cannot

be modified by a user.

writable 4.6 or later

rows int Specifies the height of the form control, in text rows. writable 4.6 or later

tabIndex int Specifies the tabbing order of the form control. writable 4.6 or later

type String Returns the type of form control. The value for this

property is “textarea”.

read only 4.6 or later

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 4.6 or later

HTMLTextAreaElement methods

Method name Description Availability

blur() Removes keypad focus from the element. 4.6 or later

focus() Gives keypad focus to the element. 4.6 or later

select() Selects the entire contents of the element. 4.6 or later

JavaScript Reference Object: HTMLTextAreaElement

206

Method: HTMLTextAreaElement.blur()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxHTMLTextAreaElement.blur()

ParametersNone.

Return valuesNone.

ExceptionsNone.

Method: HTMLTextAreaElement.focus()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxHTMLTextAreaElement.focus()

ParametersNone.

Return valuesNone.

ExceptionsNone.

JavaScript Reference Object: HTMLTextAreaElement

207

Method: HTMLTextAreaElement.select()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxHTMLTextAreaElement.select()

ParametersNone.

Return valuesNone.

ExceptionsNone.

Object: HTMLTitleElement

Availability BlackBerry® Device Software version 4.6 or later

Extends HTMLElement

The HTMLTitleElement object provides access to <title> elements within an HTML document.

The <title> element provides a descriptive title for the document.

HTMLTitleElement properties

Property name Type Description Status Availability

text String Specifies the title of the HTML document. writable 4.6 or later

Object: HTMLUListElement

Availability BlackBerry® Device Software version 4.6 or later

JavaScript Reference Object: HTMLTitleElement

208

Extends HTMLElement

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

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

HTMLUListElement properties

Property name Type Description Status Availability

compact boolean When true, indicates reduced spacing between list

items.

writable 4.6 or later

type String Specifies the bullet style used in the list. writable 4.6 or later

Object: KeyboardEvent

Availability BlackBerry® Device Software version 4.6 or later

Extends UIEvent

The KeyboardEvent object extends the UIEvent object and represents an event generated by the BlackBerry® devicekeyboard. It provides specific contextual information associated with keyboard devices. Each keyboard event references a keyusing 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”.

KeyboardEvent properties

Property name Type Description Status Availability

altKey boolean Returns true if the ALT key is pressed or if the ALT

key is locked.

read only 4.6 or later

ctrlKey boolean Returns false. BlackBerry® devices have no CTRL

key.

read only 4.6 or later

keyCode int Returns the key code associated with the key in this

event.

read only 4.6 or later

keyIdentifier String Returns the identifier of the key. read only 4.6 or later

JavaScript Reference Object: KeyboardEvent

209

Property name Type Description Status Availability

keyLocation int Returns a value of

DOM_KEY_LOCATION_STANDARD.

read only 4.6 or later

metaKey boolean Returns false. BlackBerry devices have no Meta

key.

read only 4.6 or later

shiftKey boolean Returns true if the SHIFT key is pressed. read only 4.6 or later

Keyboard event types

Event type Bubbles Cancelable Description

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

This event type includes the following context information:

KeyboardEvent.altKey , KeyboardEvent.ctrlKey ,

KeyboardEvent.keyIdentifier ,

KeyboardEvent.keyLocation , KeyboardEvent.metaKey ,

KeyboardEvent.shiftKey , UIEvent.view

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

This event includes the following context information:

KeyboardEvent.altKey , KeyboardEvent.ctrlKey ,

KeyboardEvent.keyIdentifier ,

KeyboardEvent.keyLocation , KeyboardEvent.metaKey ,

KeyboardEvent.shiftKey , UIEvent.view

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

This event type includes the following context information:

KeyboardEvent.altKey , KeyboardEvent.ctrlKey ,

KeyboardEvent.keyIdentifier ,

KeyboardEvent.keyLocation , KeyboardEvent.metaKey ,

KeyboardEvent.shiftKey , UIEvent.view

JavaScript Reference Object: KeyboardEvent

210

KeyboardEvent methods

Method name Description Availability

getModifierState() Checks the state of a modifier key. 4.6 or later

initKeyboardEvent() Initializes the value of a KeyboardEvent. 4.6 or later

initKeyboardEventNS() Initializes the value of a KeyboardEvent with the given namespace

URI.

4.6 or later

Method: KeyboardEvent.getModifierState()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxKeyboardEvent.getModifierState( keyIdentifierArg )

Parameters

Parameter Type Description

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

Return valuesReturns true if the modifier key specified by keyIdentifierArg is activated; otherwise, returns false.

ExceptionsNone.

Method: KeyboardEvent.initKeyboardEvent()

Availability BlackBerry® Device Software version 4.6 or later

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

Syntax

JavaScript Reference Object: KeyboardEvent

211

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

Parameters

Parameter Type Description

typeArg String Specifies the Keyboard event type. This parameter may have

one of the following values:

• keydown

• keypress

• keyup

canBubbleArg boolean When true, this parameter indicates that the event can bubble

upwards through the DOM tree. This parameter sets the value

of Event.bubbles .

cancelableArg boolean When true, this parameter indicates that the event’s default

action can be cancelled. This parameter sets the value of

Event.cancelable .

viewArg AbstractView Specifies the window or frame that is generating the event. This

parameter sets the value of UIEvent.view .

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

keyLocationArg String Specifies a whitespace-separated list of modifier key identifiers

to be activated on the object.

Return valuesNone.

ExceptionsNone.

See also

JavaScript Reference Object: KeyboardEvent

212

KeyboardEvent.initKeyboardEventNS()

Method: KeyboardEvent.initKeyboardEventNS()

Availability BlackBerry® Device Software version 4.6 or later

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 )

String

Parameters

Parameter Type Description

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

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 .

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

JavaScript Reference Object: KeyboardEvent

213

Parameter Type Description

modifiersList String Specifies a whitespace-separated list of modifier key identifiers

to be activated on the object.

Return valuesNone.

ExceptionsNone.

See alsoKeyboardEvent.initKeyboardEvent()

Object: Location

Availability BlackBerry® Device Software version 4.6 or later

Extends Window

The Location object is a property of the Window object. This object accesses the URL of the web page being displayed inthe BlackBerry® Browser.

A URL is composed of some or all of the following components:

protocol://hostname:port/path?query#fragment.

Location properties

Property name Type Description Status Availability

hash String Specifies the anchor portion of the

URL, including the leading hash mark,

if one exists.

writable 4.6 or later

host String Specifies the URL hostname and port. writable 4.6 or later

hostname String Specifies the hostname portion of the

URL.

writable 4.6 or later

href String Specifies the entire URL. writable 4.6 or later

JavaScript Reference Object: Location

214

Property name Type Description Status Availability

pathname String Specifies the pathname portion of the

URL.

writable 4.6 or later

port String Specifies the port portion of the URL. read only 4.6 or later

protocol String Specifies the protocol portion of the

URL.

writable 4.6 or later

search String Specifies the URL query string portion

of the URL, including the question

mark.

writable 4.6 or later

Location methods

Method name Description Availability

assign() Loads a new document. 4.6 or later

replace() Replaces the current web page with the web page at the given URL. 4.6 or later

reload() Reloads the current web page. 4.6 or later

toString() Returns the URL of the Location object’s URL. 4.6 or later

Method: location.assign()

Availability BlackBerry® Device Software version 4.6 or later

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

Syntaxlocation.assign( URL )

Parameters

Parameter Type Description

URL String The URL to load.

Return values

JavaScript Reference Object: Location

215

None.

ExceptionsNone.

See alsolocation.replace()

Method: location.reload()

Availability BlackBerry® Device Software version 4.6 or later

The reload() method reloads the current web page.

Syntaxlocation.reload( forceGet )

Parameters

Parameter Type Description

forceGet boolean When true, indicates that the page will always be reloaded from

the server. When false, or unspecified, the page can be

reloaded from the BlackBerry® Browser cache, if it is available

and still valid.

Return valuesNone.

ExceptionsNone.

See alsolocation.assign()

JavaScript Reference Object: Location

216

Method: location.replace()

Availability BlackBerry® Device Software version 4.6 or later

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

Syntaxlocation.replace( URL )

Parameters

Parameter Type Description

URL String The URL to replace the current URL with.

Return valuesNone.

ExceptionsNone.

See alsoLocation.assign()

Method: location.toString()

Availability BlackBerry® Device Software version 4.6 or later

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

Syntaxlocation.toString()

ParametersNone.

Return values

JavaScript Reference Object: Location

217

Returns the current URL (the value of location.href) as a string value.

ExceptionsNone.

Object: MediaList

Availability BlackBerry® Device Software version 4.6 or later

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

MediaList properties

Property name Type Description Status Availability

length int Returns the number of media in the list. read only 4.6 or later

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 4.6 or later

MediaList methods

Method name Description Availability

appendMedium() Adds the given medium to the end of the MediaList object. 4.6 or later

deleteMedium() Removes the given medium from the MediaList object. 4.6 or later

item() Returns the medium at the given index in the collection. 4.6 or later

JavaScript Reference Object: MediaList

218

Method: MediaList.appendMedium()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxMediaList.appendMedium( newMedium )

Parameters

Parameter Type Description

newMedium String The medium to append to the end of MediaList. If newMedium already

exists in the list, it is first removed and then replaced.

Return valuesNone.

Exceptions

Exception Description

NO_MODIFICATION_ALLOWED_ERR This error is thrown if the MediaList object is read only.

INVALID_CHARACTER_ERR This error is thrown if newMedium contains characters that are invalid in

the style language.

See alsoMediaList.deleteMedium()

Method: MediaList.deleteMedium()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxMediaList.deleteMedium( oldMedium )

Parameters

JavaScript Reference Object: MediaList

219

Parameter Type Description

oldMedium String The medium to remove from MediaList.

Return valuesNone.

Exceptions

Exception Description

NO_MODIFICATION_ALLOWED_ERR This error is thrown if the MediaList object is read only.

NOT_FOUND_ERR This error is thrown if no medium matching oldMedium exists in the

collection.

See alsoMediaList.appendMedium()

Method: MediaList.item()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxMediaList.item( index )

Parameters

Parameter Type Description

index int An integer that represents the item’s position in MediaList

object. Valid values are between 0 and MediaList.length-1

inclusive.

Return valuesReturns the medium at the index th position in MediaList, or null if an invalid index position is specified.

ExceptionsNone.

JavaScript Reference

220

Object: MimeType

Availability BlackBerry® Device Software version 4.6 or later

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

MimeType properties

Property name Type Description Status Availability

description String Returns a description of the MIME type. read only 4.6 or later

enabledPlugi

n

Plugin Returns a reference to the Plugin object currently set

to display any incoming data formatted according to the

MIME type.

read only 4.6 or later

suffixes String Returns a list of possible file extensions associated with

the MIME type.

read only 4.6 or later

type String Returns the name of the MIME type. read only 4.6 or later

Object: MimeTypeArray

Availability BlackBerry® Device Software version 4.6 or later

The MimeTypeArray object contains an ordered collection of MIME types.

MimeTypeArray properties

Property name Type Description Status Availability

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

JavaScript Reference Object: MimeType

221

MimeTypeArray methods

Method name Description Availability

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

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

Method: MimeTypeArray.item()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxMimeTypeArray.item( index )

Parameters

Parameter Type Description

index int The index position of the MIME type to be returned. Valid values are between

0 and MimeTypeArray.length -1 inclusive.

Return valuesReturns the node at the index th position in MimeTypeArray, or null if an invalid index position is specified.

ExceptionsNone.

Method: MimeTypeArray.namedItem()

Availability BlackBerry® Device Software version 4.6 or later

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

Syntax

JavaScript Reference Object: MimeTypeArray

222

MimeTypeArray.namedItem( name )

Parameters

Parameter Type Description

name String The name of the MIME type to retrieve.

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

ExceptionsNone.

Object: MouseEvent

Availability BlackBerry® Device Software version 4.6 or later

Extends UIEvent

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

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

MouseEvent properties

Property name Type Description Status Availability

altKey boolean Returns true if the ALT key is pressed or ALT lock is

on.

read only 4.6 or later

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 4.6 or later

clientX int Returns the horizontal coordinate within the

BlackBerry Browser window where the event occurred.

read only 4.6 or later

JavaScript Reference Object: MouseEvent

223

Property name Type Description Status Availability

clientY int Returns the vertical coordinate within the BlackBerry

Browser window where the event occurred.

read only 4.6 or later

ctrlKey boolean Returns false. The BlackBerry device does not have

a CTRL key.

read only 4.6 or later

metaKey boolean Returns false. The BlackBerry device does not have

a Meta key.

read only 4.6 or later

relatedTarg

et

EventTarget Returns the EventTarget that the pointer is

moving over or moving off of.

read only 4.6 or later

screenX int Returns the horizontal coordinate on the BlackBerry

device screen where the event occurred.

read only 4.6 or later

screenY int Returns the vertical coordinate on the BlackBerry

device screen where the event occurred.

read only 4.6 or later

shiftKey boolean Returns true if the SHIFT key is pressed. read only 4.6 or later

Mouse event types

Event type Bubbles Cancelable Description

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

device, or, on touchscreen devices, when the user performs a tap.

This event type includes the following context information:

UIEvent.detail , MouseEvent.altKey ,

MouseEvent.button , MouseEvent.clientX ,

MouseEvent.clientY , MouseEvent.ctrlKey ,

MouseEvent.metaKey , MouseEvent.screenX ,

MouseEvent.screenY , MouseEvent.shiftKey

mousedown yes yes Occurs when the user depresses the trackwheel or trackball on a

BlackBerry device.

This event type includes the following context information:

JavaScript Reference Object: MouseEvent

224

Event type Bubbles Cancelable Description

UIEvent.detail , MouseEvent.altKey ,

MouseEvent.button , MouseEvent.clientX ,

MouseEvent.clientY , MouseEvent.ctrlKey ,

MouseEvent.metaKey , MouseEvent.screenX ,

MouseEvent.screenY , MouseEvent.shiftKey

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

This event type includes the following context information:

MouseEvent.altKey , MouseEvent.clientX ,

MouseEvent.clientY , MouseEvent.ctrlKey ,

MouseEvent.metaKey , MouseEvent.screenX ,

MouseEvent.screenY , MouseEvent.shiftKey

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

This event type includes the following context information:

MouseEvent.altKey , MouseEvent.clientX ,

MouseEvent.clientY , MouseEvent.ctrlKey ,

MouseEvent.metaKey , MouseEvent.relatedTarget

(indicating which EventTarget the pointer is leaving),

MouseEvent.screenX , MouseEvent.screenY ,

MouseEvent.shiftKey

mouseover yes yes Occurs when the user moves the pointer over an element.

This event type includes the following context information:

MouseEvent.altKey , MouseEvent.clientX ,

MouseEvent.clientY , MouseEvent.ctrlKey ,

MouseEvent.metaKey , MouseEvent.relatedTarget

(indicating which EventTarget the pointer is entering),

MouseEvent.screenX , MouseEvent.screenY ,

MouseEvent.shiftKey

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

BlackBerry device.

This event type includes the following context information:

JavaScript Reference Object: MouseEvent

225

Event type Bubbles Cancelable Description

UIEvent.detail , MouseEvent.altKey ,

MouseEvent.button , MouseEvent.clientX ,

MouseEvent.clientY , MouseEvent.ctrlKey ,

MouseEvent.metaKey , MouseEvent.screenX ,

MouseEvent.screenY , MouseEvent.shiftKey

MouseEvent methods

Method name Description Availability

initMouseEvent() Initializes the value of a MouseEvent. 4.6 or later

Method: MouseEvent.initMouseEvent()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxMouseEvent.initMouseEvent( typeArg, canBubbleArg, cancelableArg, viewArg, detailArg,screenXArg, screenYArg, clientXArg, clientYArg, ctrlKeyArg, altKeyArg, shiftKeyArg,metaKeyArg, buttonArg, relatedTargetArg )

Parameters

Parameter Type Description

typeArg String Specifies the MouseEvent type. This parameter may have one of the

following values:

• click

• mousedown

• mousemove

• mouseout

• mouseover

JavaScript Reference Object: MouseEvent

226

Parameter Type Description

• mouseup

canBubbleArg boolean When true, this parameter indicates that the event can bubble upwards

through the DOM tree. This parameter sets the value of Event.bubbles .

cancelableArg boolean When true, this parameter indicates that the event’s default action can be

cancelled. This parameter sets the value of Event.cancelable .

viewArg AbstractView Specifies the window or frame that is generating the event. This parameter

sets the value of UIEvent.view .

detailArg long Specifies the number of clicks associated with the event. This parameter sets

the value of UIEvent.detail .

screenXArg long Specifies the horizontal coordinate on the BlackBerry® device screen where

the event occurred.

screenYArg long Specifies the vertical coordinate on the BlackBerry device screen where the

event occurred.

clientXArg long Specifies the horizontal coordinate within the BlackBerry® Browser window

where the event occurred.

clientYArg long Specifies the vertical coordinate within the BlackBerry Browser window where

the event occurred.

ctrlKeyArg boolean Specifies whether the CTRL key was pressed during the event.

altKeyArg boolean Specifies whether the ALT key was pressed during the event.

shiftKeyArg boolean Specifies whether the SHIFT key was pressed during the event.

metaKeyArg boolean Specifies whether the meta key was pressed during the event.

buttonArg unsigned short Specifies which button was clicked.

relatedTargetArg

EventTarget Specifies the event’s related EventTarget. A value for this parameter is

only necessary if typeArg has a value of “mouseover” or

“mouseout”. Otherwise, this parameter should have a value of null.

Return valuesNone.

ExceptionsNone.

JavaScript Reference

227

Object: MutationEvent

Availability BlackBerry® Device Software version 4.6 or later

Extends Event

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

MutationEvent properties

Property name Type Description Status Availability

attrChange unsigned

short

Returns the type of change that triggered the

DOMAttrModified event. This property can return one

of the following values:

• 1 = MODIFICATION: An existing Attr object was

modified in place.

• 2 = ADDITION: A new Attr object was added to

the DOM.

• 3 = REMOVAL: An Attr object was removed from

the DOM.

read only 4.6 or later

attrName String Returns the name of the changed Attr node in a

DOMAttrModified event.

read only 4.6 or later

newValue String Returns the new value of:

• the Attr node in a DOMAttrModified event

• the CharacterData node in a

DOMCharacterDataModified event

read only 4.6 or later

prevValue String Returns the previous value of:

• the Attr node in a DOMAttrModified event

• the CharacterData node in a

DOMCharacterDataModified event

read only 4.6 or later

JavaScript Reference Object: MutationEvent

228

Property name Type Description Status Availability

relatedNode Node Returns the secondary node affected by a mutation event. read only 4.6 or later

Mutation event types

Event type Bubbles Cancelable Description

DOMAttrModified yes yes Occurs when Attr.value has been modified on a node, or

when an Attr node has been added or removed. The

EventTarget is the Element node to which the Attr is

attached.

This event type includes the following context information:

MutationEvent.attrName ,

MutationEvent.attrChange ,

MutationEvent.newValue ,

MutationEvent.prevValue ,

MutationEvent.relatedNode

DOMCharacterDataModif

ied

yes no Occurs when CharacterData.data or

ProcessingInstruction.data have been modified on

a node. The EventTarget is the CharacterData node or

ProcessingInstruction node.

This event type includes the following context information:

MutationEvent.newValue ,

MutationEvent.prevValue

DOMContentLoaded no no Occurs when the BlackBerry® Browser has completely parsed

the document, before any onload events are triggered.

DOMNodeInserted yes no Occurs when a node has been added as a child of another node,

or if an Attr node has been added to an Element node.

This event type includes the following context information:

MutationEvent.relatedNode holds the parent node of

the parent node of the node being added.

JavaScript Reference Object: MutationEvent

229

Event type Bubbles Cancelable Description

DOMNodeInsertedIntoDo

cument

yes no Occurs when a node has been inserted into the document,

either directly or as part of a subtree.

DOMNodeRemoved yes no Occurs when a node has been removed from another node, or

if an Attr node has been removed from its Element node.

This event type includes the following context information:

MutationEvent.relatedNode holds the parent node of

the parent node of the node being removed.

DOMNodeRemovedFromDoc

ument

yes no Occurs when a node has been removed from the document,

either directly or as part of a subtree.

DOMSubtreeModified yes no Occurs when any modification has been made to the document,

encompassing all other MutationEvent types.

MutationEvent methods

Method name Description Availability

initMutationEven

t()

Initializes the value of a MutationEvent. 4.6 or later

Method: MutationEvent.initMutationEvent()

Availability BlackBerry® Device Software version 4.6 or later

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

JavaScript Reference Object: MutationEvent

230

Parameter Type Description

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

following values:

• DOMAttrModified

• DOMCharacterDataModified

• DOMContentLoaded

• DOMNodeInserted

• DOMNodeInsertedIntoDocument

• DOMNodeRemoved

• DOMNodeRemovedFromDocument

• DOMSubtreeModified

canBubbleArg boolean When true, this parameter indicates that the event can bubble upwards

through the DOM tree. This parameter sets the value of Event.bubbles .

cancelableArg boolean When true, this parameter indicates that the event’s default action can be

cancelled. This parameter sets the value of Event.cancelable .

relatedNodeArg Node Specifies the secondary node impacted by the mutation event. This

parameter sets the value of MutationEvent.relatedNode .

prevValueArg String Specifies the previous value of a changed Attr or CharacterData node.

This parameter sets the value of MutationEvent.prevValue .

If typeArg is not “DOMAttrModified” or

“DOMCharacterDataModified”, this parameter may be null.

newValueArg String Specifies the previous value of a changed Attr or CharacterData node.

This parameter sets the value of MutationEvent.newValue .

attrNameArg String Specifies the name of a changed Attr node. This parameter sets the value

of MutationEvent.attrName .

attrChangeArg short Specifies the type of change. This parameter can have one of the following

values:

• 1 = MODIFICATION: An existing Attr object was modified in place.

• 2 = ADDITION: A new Attr object was added to the DOM.

• 3 = REMOVAL: An Attr object was removed from the DOM.

JavaScript Reference Object: MutationEvent

231

Parameter Type Description

This parameter sets the value of MutationEvent.attrChange .

Return valuesNone.

ExceptionsNone.

Object: NamedFrameMap

Availability BlackBerry® Device Software version 4.6 or later

The NamedFrameMap object represents collections of frames that can be accessed by name.

You can access an individual frame within a collection by its index position using NamedFrameMap.item() , by its name orid attribute using NamedFrameMap.getNamedItem() , or you can index the object directly. For example, if you create aninstance of a NamedFrameMap object called myNamedFrameMap, then specifying

myNamedFrameMap.item(2)

myNamedFrameMap.getNamedItem(“item”)

is equivalent to specifying

myNamedFrameMap[2]

myNamedFrameMap[“item”]

NamedFrameMap properties

Property name Type Description Status Availability

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

NamedFrameMap methods

Method name Description Availability

getNamedItem() Retrieves the frame with the given name. 4.6 or later

JavaScript Reference Object: NamedFrameMap

232

Method name Description Availability

item() Returns the frame at the given index in the map. 4.6 or later

Method: NamedFrameMap.item()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxNamedFrameMap.item( index )

Parameters

Parameter Type Description

index int An integer that represents the frame’s position in the frame map.

Valid values are between 0 and NamedFrameMap.length -1

inclusive.

Return valuesReturns the frame at the index th position in NamedFrameMap , or null if an invalid index position is specified.

ExceptionsNone.

Method: NamedFrameMap.getNamedItem()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxNamedFrameMap.getNamedItem( name )

Parameters

JavaScript Reference Object: NamedFrameMap

233

Parameter Type Description

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

retrieve.

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

ExceptionsNone.

Object: NamedNodeMap

Availability BlackBerry® Device Software version 4.6 or later

The NamedNodeMap object represents collections of nodes that can be accessed by name.

You can access an individual node within a collection by its index position using NamedNodeMap.item() , by its name orid attribute using NamedNodeMap.getNamedItem() , or you can index the object directly. For example, if you create aninstance of a NamedNodeMap object called myNamedNodeMap, then specifying

myNamedNodeMap.item(2)

myNamedNodeMap.getNamedItem(“item”)

is equivalent to specifying

myNamedNodeMap[2]

myNamedNodeMap[“item”]

NamedNodeMap properties

Property name Type Description Status Availability

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

JavaScript Reference Object: NamedNodeMap

234

NamedNodeMap methods

Method name Description Availability

getNamedItem() Retrieves the node with the given name. 4.6 or later

getNamedItemNS() Retrieves the node with the given name and namespace URI. 4.6 or later

item() Returns the node at the given index in the map. 4.6 or later

removeNamedItem() Removes the node with the given name from the map. 4.6 or later

removeNamedItemNS() Removes the node with the given name and namespace URI from the map. 4.6 or later

setNamedItem() Adds a node using the Node.nodeName attribute. 4.6 or later

setNamedItemNS() Adds a node using the Node.nodeName attribute and the namespace

URI.

4.6 or later

Method: NamedNodeMap.getNamedItem()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxNamedNodeMap.getNamedItem( name )

Parameters

Parameter Type Description

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

retrieve.

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

ExceptionsNone.

See alsoNamedNodeMap.getNamedItemNS()

JavaScript Reference Object: NamedNodeMap

235

Method: NamedNodeMap.getNamedItemNS()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxNamedNodeMap.getNamedItemNS( namespaceURI, localName )

Parameters

Parameter Type Description

namespaceURI String The namespace of the node to retrieve.

localName String The local name of the node to retrieve.

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

Exceptions

Exception Description

NOT_SUPPORTED_ERR This error is thrown if the document does not support XML

namespaces.

See alsoNamedNodeMap.getNamedItem()

Method: NamedNodeMap.item()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxNamedNodeMap.item( index )

Parameters

JavaScript Reference Object: NamedNodeMap

236

Parameter Type Description

index int An integer that represents the node’s position in the node map.

Valid values are between 0 and NamedNodeMap.length -1

inclusive.

Return valuesReturns the node at the index th position in NamedNodeMap, or null if an invalid index position is specified.

ExceptionsNone.

Method: NamedNodeMap.removeNamedItem()The removeNamedItem() method removes the node with the specified name from the map.

If you are removing an Attr node from the NamedNodeMap.length object that is known to have a default value, theremoved Attr 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

Parameter Type Description

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

Return valuesReturns the removed Node object, if it exists.

Exceptions

Exception Description

NO_MODIFICATION_ALLOWED_ERR This error is thrown if the NamedNodeMap object is read only.

NOT_FOUND_ERR This error is thrown if no node with a Node.nodeName value

of name exists in the NamedNodeMap.

JavaScript Reference Object: NamedNodeMap

237

Method: NamedNodeMap.removeNamedItemNS()

Availability BlackBerry® Device Software version 4.6 or later

The removeNamedItemNS() method removes the node with the specified name and namespace URI from the map.

If you are removing an Attr node from the NamedNodeMap object that is known to have a default value, the Attr willimmediately be reattached to the element with its default value, as well as its corresponding namespace URI, local name, andprefix, if applicable.

SyntaxNamedNodeMap.removeNamedItemNS( namespaceURI, localName )

Parameters

Parameter Type Description

namespaceURI String The namespace of the node to remove.

localName String The local name of the node to remove.

Return valuesReturns the removed Node object, if it exists.

Exceptions

Exception Description

NO_MODIFICATION_ALLOWED_ERR This error is thrown if the NamedNodeMap object is read only.

NOT_FOUND_ERR This error is thrown if no node with a Node.nodeName value

of name exists in the NamedNodeMap.

NOT_SUPPORTED_ERR This error is thrown if the document does not support XML

namespaces.

Method: NamedNodeMap.setNamedItem()The setNamedItem() method adds a node to the node map using the Node.nodeName property. If a node with the sameNode.nodeName value already exists in the map, the existing node is removed and is replaced by the new node and the removednode is returned.

JavaScript Reference Object: NamedNodeMap

238

As the Node.nodeName property is used to store the new node in the map, in order to prevent name clashes, you may not addmultiple nodes of those node types that always have the same Node.nodeName value. For example, a text node will alwayshave a Node.nodeName value of #text. Therefore, only a single text node may be included in any NamedNodeMap object.

SyntaxNamedNodeMap.setNamedItem( arg )

Parameters

Parameter Type Description

arg Node The node to add to the map.

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

Exceptions

Exception Description

HIERARCHY_REQUEST_ERR This error is thrown if the arg node is not permitted in this

NamedNodeMap, for example, if you tried to insert a node other

than an Attr into an Element ’s map of attributes.

INUSE_ATTRIBUTE_ERR This error is thrown if arg is an Attr object that is already an

attribute of another Element object. To add an attribute used

elsewhere, you must clone it, and then add it.

NO_MODIFICATION_ALLOWED_ERR This error is thrown if the NamedNodeMap object is read only.

WRONG_DOCUMENT_ERR This error is thrown if arg was created from a different document

than the one that created this NamedNodeMap object.

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

SyntaxNamedNodeMap.setNamedItemNS( arg )

Parameters

JavaScript Reference Object: NamedNodeMap

239

Parameter Type Description

arg Node The node to add to the map.

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

Exceptions

Exception Description

HIERARCHY_REQUEST_ERR This error is thrown if the arg node is not permitted in this

NamedNodeMap , for example, if you tried to insert a node other

than an Attr into an Element ’s map of attributes.

INUSE_ATTRIBUTE_ERR This error is thrown if arg is an Attr object that is already an

attribute of another Element object. To add an attribute used

elsewhere, you must clone it, and then add it.

NO_MODIFICATION_ALLOWED_ERR This error is thrown if the NamedNodeMap object is read only.

NOT_SUPPORTED_ERR This error is thrown if the document does not support XML

namespaces.

WRONG_DOCUMENT_ERR This error is thrown if arg was created from a different document

than the one that created this NamedNodeMap object.

Object: Navigator

Availability BlackBerry® Device Software version 3.8 or later

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

JavaScript Reference Object: Navigator

240

Navigator properties

Property name Type Description Status Availability

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 3.8 or later

appName String Returns the name of the browser. In the case of the

BlackBerry® Browser, the value is always

BlackBerry.

read only 3.8 or later

appVersion String Returns the version of the BlackBerry® Device

Software that is running on the BlackBerry device (for

example, 4.6.0).

read only 3.8 or later

buildID String Returns the build identifier of the version of the

BlackBerry Device Software running on the device.

read only 4.6 or later

cookieEnabled boolean Returns true if cookies are enabled in the BlackBerry

Browser.

read only 4.6 or later

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 3.8 or later

mimeTypes MimeTypeArr

ay

Returns a list of the MIME types that the target

BlackBerry Browser supports.

read only 3.8 or later

platform String Returns BlackBerry. This property is treated as a

constant.

read only 3.8 or later

plugins PluginArray Returns a list of the embedded plugins in the

document.

read only 4.6 or later

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 3.8 or later

JavaScript Reference Object: Navigator

241

Navigator methods

Method name Description Availability

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

Method: navigator.javaEnabled()

Availability BlackBerry® Device Software version 3.8 or later

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

Syntaxnavigator.javaEnabled()

ParametersNone.

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

ExceptionsNone.

ExamplesThe following code fragment runs the function doThis if Java is supported otherwise, it runs the function doThat:

if (navigator.javaEnabled()) { doThis();}else doThat();

Object: Node

Availability BlackBerry® Device Software version 4.6 or later

JavaScript Reference Object: Node

242

Extended by Attr , CharacterData , Document , DocumentFragment , DocumentType ,

Element , Entity , EntityReference , Notation , ProcessingInstruction

The Node object represents a unique node within the DOM tree. It is the primary data type for the DOM.

While Node exposes methods for dealing with children, not all objects inheriting from Node may have children. For example,Text nodes do not permit children; trying to add children to such nodes results in a DOMException being raised.

The Node.nodeName , Node.nodeValue , and Node.nodeType properties enable you to acquire node information withoutcasting down to the specific child object. In cases where there is no obvious mapping of these properties for a specificnodeType (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.

Node properties

Property name Type Description Status Availability

attributes NamedNodeM

ap

Returns a NamedNodeMap object that contains the

attributes of the given element node, or null, if the

node is not an element.

read only 4.6 or later

childNodes NodeList Returns a NodeList object that contains all the

child elements of the given node.

read only 4.6 or later

firstChild Node Returns the first child of the given node. read only 4.6 or later

lastChild Node Returns the last child of the given node. read only 4.6 or later

localName String Returns the local part of the qualified name for the

given node.

read only 4.6 or later

namespaceURI String Returns the namespace URI for the given node, or

null if it is not specified.

read only 4.6 or later

nextSibling Node Returns the node immediately following the given

node.

read only 4.6 or later

nodeName String Returns the name of the given node. read only 4.6 or later

nodeType unsigned short Returns a code representing the type of the given

node.

read only 4.6 or later

nodeValue String Specifies the value of the given node.

When setting a value for this property, the following

error may be thrown:

writable 4.6 or later

JavaScript Reference Object: Node

243

Property name Type Description Status Availability

• NO_MODIFICATION_ERR: Thrown if the

Node object is read only.

When retrieving the value of this property, the

following error may be thrown:

• DOMSTRING_SIZE_ERR: Thrown if the string

contains more characters than fit in a

DOMString variable.

ownerDocument Document Returns the Document object associated with the

given node.

read only 4.6 or later

parentNode Node Returns the parent of the given node. read only 4.6 or later

prefix String Specifies the prefix, extracted from the qualified

name of the given node, or null if it is unspecified.

When setting a value for this property, the following

errors may be thrown:

• INVALID_CHARACTER_ERR: Thrown if the

specified value contains an illegal character.

• NO_MODIFICATION_ERR: Thrown if the

Node object is read only.

• NAMESPACE_ERR: Thrown if the specified

value is malformed.

writable 4.6 or later

previousSiblin

g

Node Returns the node immediately preceding the current

node.

read only 4.6 or later

Node methods

Method name Description Availability

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

node.

4.6 or later

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

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

JavaScript Reference Object: Node

244

Method name Description Availability

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

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

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

insertBefore() Inserts a new node before the given node. 4.6 or later

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

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

DOM.

4.6 or later

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

removeEventListener

()

Removes an event listener from an EventTarget. 4.6 or later

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

then returns the removed node.

4.6 or later

Method: Node.removeEventListener()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxNode.removeEventListener( type, listener, useCapture )

Parameters

Parameter Type Description

type String The type of event.

listener EventListener The EventListener function to be removed.

useCapture boolean When true, indicates that the EventListener being

removed was registered as a capturing listener.

A listener may be registered twice, once as a capturing listener,

and once as a non-capturing listener. Each must be removed

separately.

Return values

JavaScript Reference Object: Node

245

None.

ExceptionsNone.

See alsoEvent , EventListener , Node.addEventListener()

Method: Node.removeChild()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxNode.removeChild( oldChild )

Parameters

Parameter Type Description

oldChild Node The child node to remove.

Return valuesReturns the removed node.

Exceptions

Exception Description

NO_MODIFICATION_ALLOWED_ERR This error is thrown if the given node is read only.

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

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

JavaScript Reference Object: Node

246

Method: Node.replaceChild()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxNode.replaceChild( newChild, oldChild )

Parameters

Parameter Type Description

newChild Node The node with which to replace the old node with.

If newChild is a DocumentFragment object, then the entire

contents of the document fragment are appended to the given

node.

If newChild already exists as a child of the current node in the

tree, it is removed, and then replaced.

oldChild Node The child node to replace.

Return valuesReturns the replaced node.

Exceptions

Exception Description

HIERARCHY_REQUEST_ERR This error is thrown if either newChild or oldChild is one

of the current node’s ancestors, or if the current node does not

allow children of the type of newChild node.

NO_MODIFICATION_ALLOWED_ERR This error is thrown if the current node is read only.

NOT_FOUND_ERR This error is thrown if oldChild is not a child of the current

node.

JavaScript Reference Object: Node

247

Exception Description

WRONG_DOCUMENT_ERR This error is thrown if newChild was created from a different

document than the current node.

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

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

SyntaxNode.normalize()

ParametersNone.

Return valuesNone.

ExceptionsNone.

Method: Node.addEventListener()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxNode.addEventListener( type, listener, useCapture )

Parameters

Parameter Type Description

type String The type of event to add.

listener EventListener The event listener function to be invoked.

JavaScript Reference Object: Node

248

Parameter Type Description

useCapture boolean When true, indicates all events of the specified type to the

registered EventListener before being dispatched to any

EventTargets beneath the given node in the tree. Bubbling

events will not trigger the EventListener.

When false, this method dispatches events of the specified

type to the registered EventListener before being

dispatched to any EventTargets above the given node in the

tree.

Return valuesNone.

ExceptionsNone.

See alsoEvent , EventListener

Method: Node.appendChild()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxNode.appendChild( newChild )

Parameters

Parameter Type Description

newChild Node The node to add.

If newChild is a DocumentFragment object, then the entire

contents of the document fragment are appended to the given

node.

JavaScript Reference Object: Node

249

Parameter Type Description

If newChild already exists in the tree, it is removed, and then

replaced.

Return valuesReturns the added node.

Exceptions

Exception Description

HIERARCHY_REQUEST_ERR This error is thrown if newChild is one of the given node’s

ancestors, or if the given node does not allow children of the type

of newChild node.

NO_MODIFICATION_ALLOWED_ERR This error is thrown if the given node is read only.

WRONG_DOCUMENT_ERR This error is thrown if newChild was created from a different

document than the given node.

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

Method: Node.cloneNode()

Availability BlackBerry® Device Software version 4.6 or later

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

If you clone an Element or an Attr node, you should be aware of the following:

When you clone an Element node, you also duplicate its attributes and their values. However, you do not clone any text theElement node contains (since the text is contained in a child text node) unless you specify the deep parameter.

When you clone an Attr node, this method returns a "specified" attribute (that is, the specified property for that attributeis set to true).

Cloning any other type of node simply returns a copy of the node.

SyntaxNode.cloneNode( deep )

Parameters

JavaScript Reference Object: Node

250

Parameter Type Description

deep boolean When true, this method clones the subtree under the given

node.

When false, this method only clones the given node; it does

not clone the subtree.

Return valuesReturns the duplicate node.

ExceptionsNone.

Method: Node.dispatchEvent()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxNode.dispatchEvent( event )

Parameters

Parameter Type Description

event Event The Event object to be dispatched.

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

Exceptions

JavaScript Reference Object: Node

251

Exception Description

UNSPECIFIED_EVENT_TYPE_ERR This error is thrown if the event type was not specified by

initializing the event before calling dispatchEvent(), or if

the event type was null.

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

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

SyntaxNode.hasAttributes()

ParametersNone.

Return valuesReturns true if the given node is an element with attributes; otherwise, returns false.

ExceptionsNone.

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

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

SyntaxNode.hasChildNodes()

Parameters

JavaScript Reference Object: Node

252

None.

Return valuesReturns true if the given node has any child nodes; otherwise, returns false.

ExceptionsNone.

See alsoNode.childNodes

Method: Node.insertBefore()The insertBefore() method inserts a new child node into the current node before the specified child node. This methodsallows you to insert a node at a specific location among a number of child nodes.

SyntaxNode.insertBefore( newChild, refChild )

Parameters

Parameter Type Description

newChild Node The node to insert.

If newChild is a DocumentFragment object, then the entire

contents of the document fragment are inserted, in order, before

refChild .

If newChild already exists as a child of the current node in the

tree, then 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, then newChild isinserted at the end of the list of children.

Return valuesReturns the inserted node.

Exceptions

JavaScript Reference Object: Node

253

Exception Description

HIERARCHY_REQUEST_ERR This error is thrown if newChild is an ancestor of

refChild , or if refChild does not allow children of the type

of newChild node.

NO_MODIFICATION_ALLOWED_ERR This error is thrown if the given node is read only.

NOT_FOUND_ERR This error is thrown if refChild is not a child of the current

node.

WRONG_DOCUMENT_ERR This error is thrown if newChild was created from a different

document than the current node.

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

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

SyntaxNode.isSupported( feature, version )

Parameters

Parameter Type Description

feature String The name of the feature to test.

version String The version of the feature to test.

If version is null, this method returns true if any version of

the feature is supported.

Return valuesReturns true if the specified version of the specified feature is supported; otherwise, returns false.

ExceptionsNone.

See also

JavaScript Reference Object: Node

254

DOMImplementation.hasFeature()

Object: NodeFilter

Availability BlackBerry® Device Software version 4.6 or later

The NodeFilter object is used to filter out nodes. If a NodeIterator or TreeWalker is given a NodeFilter, it appliesthe filter before it returns the next node. If the filter says to accept the node, the traversal object, either a NodeIterator orTreeWalker, returns it; otherwise, the traversal object looks for the next node and acts as if that the node that was rejectedwas not there.

NodeFilter methods

Method name Description Availability

acceptNode() Tests whether a specified node is visible in the logical view of a

NodeIterator or TreeWalker.

4.6 or later

Method: NodeFilter.acceptNode()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxNodeFilter.acceptNode( n )

Parameters

Parameter Type Description

n Node The node to check.

Return valuesReturns a constant that that determines whether the node is accepted, rejected, or skipped.

JavaScript Reference Object: NodeFilter

255

Constant Definition Description

1 FILTER_ACCEPT Navigation methods defined for NodeIterator or

TreeWalker will return the node.

2 FILTER_REJECT Navigation methods defined for NodeIterator or

TreeWalker will not return the node. In the case of

NodeIterator, this is equivalent to FILTER_SKIP. In the

case of TreeWalker, the children of the node are also rejected.

3 FILTER_SKIP Navigation methods defined for NodeIterator or

TreeWalker will not return the node; however, children of this

node are still considered.

ExceptionsNone.

Object: NodeList

Availability BlackBerry® Device Software version 4.6 or later

The NodeList object is an array that contains an ordered collection of nodes.

You can access an individual Node within a collection by its index position using NodeList.item() or you can index theobject directly. For example, if you create an instance of a NodeList object called myNodeList, then specifying

myNodelist.item(2)

is equivalent to specifying

myNodelist[2]

NodeList properties

Property name Type Description Status Availability

length unsigned long Returns the number of Node s in the list. read only 4.6 or later

JavaScript Reference Object: NodeList

256

NodeList methods

Method name Description Availability

item() Returns the Node at the specified index in the collection. 4.6 or later

Method: NodeList.item()

Availability BlackBerry® Device Software version 4.6 or later

The item() method returns the Node at the specified index in the collection.

SyntaxNodeList.item( index )

Parameters

Parameter Type Description

index int An integer that represents the node’s position in NodeList .

Valid values are between 0 and NodeList.length -1

inclusive.

Return valuesReturns the node at the index th position in NodeList, or null if an invalid index position is specified.

ExceptionsNone.

Object: Notation

Availability BlackBerry® Device Software version 4.6 or later

Extends Node

The Notation object represents a notation declared in a DTD. A Notation declares the format of an unparsed entity, or isused to formally declare ProcessingInstruction targets.

The Node.nodeName property is set to the declared name of the Notation.

JavaScript Reference Object: Notation

257

Notation properties

Property name Type Description Status Availability

publicId String Returns the public identifier of the Notation, or null if

no identifier has been specified.

read only 4.6 or later

systemId String Returns the system identifier of the Notation, or null if

no identifier has been specified.

read only 4.6 or later

Object: NodeIterator

Availability BlackBerry® Device Software version 4.6 or later

The NodeIterator object enables you to navigate up and down through a flat representation of the document tree. This objectis similar to the TreeWalker objects, except that TreeWalker presents nodes in a tree-oriented view, rather than the listview presented by NodeIterator.

Create a NodeIterator using Document.createNodeIterator() .

NodeIterator properties

Property name Type Description Status Availability

expandEntityReferen

ces

boolean Returns whether or not the NodeIterator

expands the entity references it encounters as

it traverses the document.

read only 4.6 or later

filter NodeFilte

r

Returns the NodeFilter used to filter nodes

for traversal.

read only 4.6 or later

root Node Returns the Node at which the

NodeIterator begins traversing the

document.

read only 4.6 or later

whatToShow unsigned

long

Returns which node types are presented by the

NodeIterator. The value may be one or

more of:

read only 4.6 or later

JavaScript Reference Object: NodeIterator

258

Property name Type Description Status Availability

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

JavaScript Reference Object: NodeIterator

259

NodeIterator methods

Method name Description Availability

detach() Detaches the NodeIterator from the set which it iterated over. 4.6 or later

nextNode() Moves the NodeIterator to the next visible Node in the document order,

relative to the current node.

4.6 or later

previousNode() Moves the NodeIterator to the previous visible Node in the document order,

relative to the current node.

4.6 or later

Method: NodeIterator.detach()

Availability BlackBerry® Device Software version 4.6 or later

The detach() method detaches the NodeIterator from the set which it iterated over. After a NodeIterator has beendetached, attempting to use NodeIterator.nextNode() or NodeIterator.previousNode() results in an error.

SyntaxNodeIterator.detach()

ParametersNone.

Return valuesNone.

ExceptionsNone.

Method: NodeIterator.nextNode()

Availability BlackBerry® Device Software version 4.6 or later

The nextNode() method moves the NodeIterator to the next visible Node in the document order, relative to the currentnode. The first call to this method after a NodeIterator is created returns the first Node in the set.

Syntax

JavaScript Reference Object: NodeIterator

260

NodeIterator.nextNode()

ParametersNone.

Return valuesReturns the node, or null, if there is no node after the current node in the NodeIterator’s logical view.

Exceptions

Exception Description

INVALID_STATE_ERR This error is thrown if this method is called after the NodeIterator has been

detached from the set that it iterated over.

Method: NodeIterator.previousNode()

Availability BlackBerry® Device Software version 4.6 or later

The previousNode() method moves the NodeIterator to the previous visible Node in the document order, relative tothe current node.

SyntaxNodeIterator.previousNode()

ParametersNone.

Return valuesReturns the node, or null, if there is no node before the current node in the NodeIterator’s logical view.

Exceptions

Exception Description

INVALID_STATE_ERR This error is thrown if this method is called after the

NodeIterator has been detached from the set that it iterated

over.

JavaScript Reference

261

Object: Plugin

Availability BlackBerry® Device Software version 4.6 or later

The Plugin object represents an installed plugin.

You can access an individual Plugin within a collection by its index position using Plugin.item() , by its name or idattribute using Plugin.namedItem() , or you can index the object directly. For example, if you create an instance of aPlugin object called myPlugins, then specifying

myPlugins.item(2)

myPlugins.namedItem(“item”)

is equivalent to specifying

myPlugins[2]

myPlugins[“item”]

Plugin properties

Property name Type Description Status Availability

description String Returns the description of the Plugin. read only 4.6 or later

filename String Returns the Plugin filename. read only 4.6 or later

length unsigned long Returns the number of MIME types associated with

the Plugin.

read only 4.6 or later

name String Returns the name of the Plugin. read only 4.6 or later

Plugin methods

Method name Description Availability

item() Returns the Plugin at the specified index in the collection. 4.6 or later

namedItem() Returns the Plugin with the given name. 4.6 or later

JavaScript Reference Object: Plugin

262

Method: Plugin.item()

Availability BlackBerry® Device Software version 4.6 or later

The item() method returns the Plugin at the specified index in the collection.

SyntaxPlugin.item( index )

Parameters

Parameter Type Description

index int The index position of the Plugin to be returned. Valid values

are between 0 and Plugin.length -1 inclusive.

Return valuesReturns the plugin at the index th position in Plugin, or null if an invalid index position is specified.

ExceptionsNone.

Method: Plugin.namedItem()

Availability BlackBerry® Device Software version 4.6 or later

The namedItem() method retrieves the Plugin with the given name from the collection.

SyntaxPlugin.namedItem( name )

Parameters

Parameter Type Description

name String The name of the Plugin to retrieve.

Return values

JavaScript Reference Object: Plugin

263

Returns the Plugin with the given name, or null if no Plugin with the given name exists in the array.

ExceptionsNone.

Object: PluginArray

Availability BlackBerry® Device Software version 4.6 or later

The PluginArray object contains an ordered collection of Plugin objects.

PluginArray properties

Property name Type Description Status Availability

length unsigned long Returns the number of Plugin objects in the

collection.

read only 4.6 or later

PluginArray methods

Method name Description Availability

item() Returns the Plugin at the specified index in the collection. 4.6 or later

namedItem() Retrieves the Plugin with the given name from the collection. 4.6 or later

Method: PluginArray.item()

Availability BlackBerry® Device Software version 4.6 or later

The item() method returns the Plugin at the specified index in the collection.

SyntaxPluginArray.item( index )

Parameters

JavaScript Reference Object: PluginArray

264

Parameter Type Description

index int The index position of the Plugin to be returned. Valid values

are between 0 and PluginArray.length -1 inclusive.

Return valuesReturns the Plugin at the index th position in PluginArray, or null if an invalid index position is specified.

ExceptionsNone.

Method: PluginArray.namedItem()

Availability BlackBerry® Device Software version 4.6 or later

The namedItem() method retrieves the Plugin with the given name from the collection.

SyntaxPluginArray.namedItem( name )

Parameters

Parameter Type Description

name String The name of the Plugin object to retrieve.

Return valuesReturns the Plugin with the given name, or null if no plugin with the given name exists in the array.

ExceptionsNone.

Object: ProcessingInstruction

Availability BlackBerry® Device Software version 4.6 or later

JavaScript Reference Object: ProcessingInstruction

265

Extends Node

The ProcessingInstruction object represents a Processing Instruction for an XML document, which enables you to keepprocessor-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 directlyrelated to the content of the document.

ProcessingInstruction properties

Property name Type Description Status Availability

data String Specifies the content of the

processing instruction. This content

includes everything contained

between the processing instruction

markers.

writable 4.6 or later

sheet String Returns the style sheet associated

with the processing instruction.

read only 4.6 or later

target String Returns the target of the processing

instruction.

read only 4.6 or later

Object: Range

Availability BlackBerry® Device Software version 4.7.1 or later

The Range object represents a range of content between two boundary points, a start point and an end point, in a Document ,DocumentFragment , or Attr node.

You can create a Range object by using Document.createRange . You can retrieve a Range object by usingSelection.getRangeAt .

JavaScript Reference Object: Range

266

Range properties

Property name Type Description Status Availability

collapsed boolean Returns true if the start point and end

point of the range are the same.

read-only 4.7.1 or later

commonAncestorContainer Node Returns the deepest node that contains the

startContainer and endContainer

nodes.

read-only 4.7.1 or later

endContainer Node Returns the node that contains the end

point of the range.

read-only 4.7.1 or later

endOffset int Returns a number that represents the end

point of the range within the

endContainer node.

read-only 4.7.1 or later

startContainer Node Returns the node that contains the start

point of the range.

read-only 4.7.1 or later

startOffset int Returns a number that represents the start

point of the range within the

startContainer node.

read-only 4.7.1 or later

Range methods

Method name Description Availability

cloneContents() Duplicates the contents of a specified range. 4.7.1 or later

cloneRange() Creates a new Range object with the same start point and end point

as the specified range.

4.7.1 or later

collapse() Collapses a range onto its start point or end point. 4.7.1 or later

compareBoundaryPoints() Compares the start points and end points of two ranges. 4.7.1 or later

deleteContents() Deletes the contents of the range from the Document or

DocumentFragment node.

4.7.1 or later

detach() Immediately releases the Range object from the object model. 4.7.1 or later

JavaScript Reference Object: Range

267

Method name Description Availability

extractContents() Extracts the entire contents of the range from a Document or

DocumentFragment node and moves it to a new

DocumentFragment object.

4.7.1 or later

insertNode() Inserts a new node at the start of the range. 4.7.1 or later

selectNode() Populates the range with a specified node and its contents. 4.7.1 or later

selectNodeContents() Populates the range with the contents of a specified node. 4.7.1 or later

setEnd() Sets the end point of the range. 4.7.1 or later

setEndAfter() Sets the end point of a range at a position that is after the specified node. 4.7.1 or later

setEndBefore() Sets the end point of a range at a position that is before the specified

node.

4.7.1 or later

setStart() Sets the start point of the range. 4.7.1 or later

setStartAfter() Sets the start point of a range at a position that is after the specified

node.

4.7.1 or later

setStartBefore() Sets the start point of a range at a position that is before the specified

node.

4.7.1 or later

surroundContents() Moves the contents of the range to a new node object, and inserts the

new node at the start point of the range.

4.7.1 or later

toString() Returns the contents of the range as a string. 4.7.1 or later

Method: Range.cloneContents()

Availability BlackBerry® Device Software version 4.7.1 or later

The cloneContents() method duplicates the contents of a specified range.

SyntaxRange.cloneContents()

ParametersNone.

Return valuesThis method returns a DocumentFragment object that contains the same contents as the range.

Exceptions

JavaScript Reference Object: Range

268

Exception Description

HIERARCHY_REQUEST_ERR Thrown if the result of this action is that a DocumentType node is inserted into the

DocumentFragment object.

INVALID_STATE_ERR Thrown if the Range.detach() method is already invoked on the Range object.

Method: Range.cloneRange()

Availability BlackBerry® Device Software version 4.7.1 or later

The cloneRange() method creates a new Range object with the same start point and end point as the specified range.

SyntaxRange.cloneRange()

ParametersNone.

Return valuesThis method returns the new Range object.

Exceptions

Exception Description

INVALID_STATE_ERR Thrown if the Range.detach() method is already invoked on the Range object.

Method: Range.collapse()

Availability BlackBerry® Device Software version 4.7.1 or later

The collapse() method collapses a range onto its start point or end point.

SyntaxRange.collapse( toStart )

Parameters

JavaScript Reference Object: Range

269

Parameter Type Description

toStart boolean When true, indicates that the range is collapsed onto its start point. When false,

indicates that the range is collapsed onto its end point.

Return valuesNone.

Exceptions

Exception Description

INVALID_STATE_ERR Thrown if the Range.detach() method is already invoked on the Range object.

Method: Range.compareBoundaryPoints()

Availability BlackBerry® Device Software version 4.7.1 or later

The compareBoundaryPoints() method compares the start points and end points of two ranges.

SyntaxRange.compareBoundaryPoints( how, sourceRange )

Parameters

Parameter Type Description

how short Describes the type of comparison using one of the following constants:

• END_TO_END: Compares the end point of sourceRange to the end point

of the current range.

• END_TO_START: Compares the end point of sourceRange to the start

point of the current range.

• START_TO_END: Compares the start point of sourceRange to the end

point of the current range.

• START_TO_START: Compares the start point of sourceRange to the start

point of the current range.

sourceRange Range Specifies the Range object to which the current range is compared.

Return values

JavaScript Reference Object: Range

270

This method returns one of the following values:

• -1: Indicates that the specified start point or end point of the current range is before the corresponding start point or endpoint of sourceRange .

• 0: Indicates that the specified start point or end point of the given range is identical to the corresponding start point or endpoint of sourceRange .

• 1: Indicates that the specified start point or end point of the given range is after the corresponding start point or end pointof sourceRange .

Exceptions

Exception Description

INVALID_STATE_ERR Thrown if the Range.detach() method is already invoked on the Range object.

WRONG_DOCUMENT_ERR Thrown if the current range and sourceRange are not in the same Document or

DocumentFragment node.

Method: Range.deleteContents()

Availability BlackBerry® Device Software version 4.7.1 or later

The deleteContents() method deletes the contents of the range from the Document or DocumentFragment node.

SyntaxRange.deleteContents()

ParametersNone.

Return valuesNone.

Exceptions

Exception Description

INVALID_STATE_ERR Thrown if the Range.detach() method is already invoked on the Range

object.

NO_MODIFICATION_ALLOWED_ERR Thrown if any portion of the contents of the range is read-only, or if any of the

nodes that contain any of the contents of the range is read-only.

JavaScript Reference Object: Range

271

Method: Range.detach()

Availability BlackBerry® Device Software version 4.7.1 or later

The detach() method immediately releases the Range object from the object model. Although it is permissible to just stopusing a Range object when you are finished with it, the browser will continue to expend some resources maintaining it. Detachinga Range object informs the browser that it can release those resources, making them available to other objects. As a result, itis a good practice to invoke the Range.detach() method whenever a range is no longer needed.

Once a Range object is detached, any attempts to access it will result in an exception.

SyntaxRange.detach()

ParametersNone.

Return valuesNone.

Exceptions

Exception Description

INVALID_STATE_ERR Thrown if the Range.detach() method is already invoked on the Range object.

Method: Range.extractContents()

Availability BlackBerry® Device Software version 4.7.1 or later

The extractContents() method extracts the entire contents of the range from a Document or DocumentFragmentnode and moves it to a new DocumentFragment object.

SyntaxRange.extractContents()

ParametersNone

Return values

JavaScript Reference Object: Range

272

This method returns a new DocumentFragment object that contains the extracted range contents.

Exceptions

Exception Description

HIERARCHY_REQUEST_ERR Thrown if this action would result in a DocumentType node being inserted into

the DocumentFragment object.

INVALID_STATE_ERR Thrown if the Range.detach() method is already invoked on the Range object.

NO_MODIFICATION_ALLOWED_ERR Thrown if any portion of the contents of the range is read-only, or if any of the Node

objects that contain any of the contents of the range is read-only.

Method: Range.insertNode()

Availability BlackBerry® Device Software version 4.7.1 or later

The insertNode() method inserts a new node at the start of the range.

If the container is a Text node, the node is split (as if the Text.splitText method had been invoked), and the new nodeis inserted between the resulting pair of Text nodes.

SyntaxRange.insertNode( newNode )

Parameters

Parameter Type Description

newNode Node Specifies the new node to insert.

If newNode is a DocumentFragment node, only the child nodes will be inserted,

not the DocumentFragment node itself.

Return valuesNone.

Exceptions

Exception Description

HIERARCHY_REQUEST_ERR Thrown if this action would result in a DocumentType node being inserted

into the DocumentFragment object.

INVALID_NODE_TYPE_ERR Thrown if newNode is an Attr , Entity , Notation , or Document node.

JavaScript Reference Object: Range

273

Exception Description

INVALID_STATE_ERR Thrown if the Range.detach() method is already invoked on the Range

object.

NO_MODIFICATION_ALLOWED_ERR Thrown if any portion of the contents of the range is read-only, or if any of the

Node objects that contain any of the contents of the range is read-only.

WRONG_DOCUMENT_ERR Thrown if newNode and the container of the start of the range were not created

from the same document.

Method: Range.selectNodeContents()

Availability BlackBerry® Device Software version 4.7.1 or later

The selectNodeContents() method populates the range with the contents of a specified node.

SyntaxRange.selectNodeContents( refNode )

Parameters

Parameter Type Description

refNode Node Specifies the node from which to select the contents. This node will become the

parent node for the start and end of the range.

Return valuesNone.

Exceptions

Exception Description

INVALID_NODE_TYPE_ERR Thrown if refNode or an ancestor of refNode is an Attr , Entity , Notation , or

Document node.

INVALID_STATE_ERR Thrown if the Range.detach() method is already invoked on the Range object.

JavaScript Reference Object: Range

274

Method: Range.selectNode()

Availability BlackBerry® Device Software version 4.7.1 or later

The selectNode() method populates the range with a node and its contents.

SyntaxRange.selectNode( refNode )

Parameters

Parameter Type Description

refNode Node Specifies the node from which to select the contents. This node will become the

parent node for the start and end of the range.

Return valuesNone.

Exceptions

Exception Description

INVALID_NODE_TYPE_ERR Thrown if an ancestor of refNode is an Entity , Notation or DocumentType

node, or if refNode is an Attr , Document , DocumentFragment , Entity , or

Notation node.

INVALID_STATE_ERR Thrown if the Range.detach() method is already invoked on the Range object.

Method: Range.setEndAfter()

Availability BlackBerry® Device Software version 4.7.1 or later

The setEndAfter() method sets the end point of a range at a position that is after the specified node.

SyntaxRange.setEndAfter( refNode )

Parameters

JavaScript Reference Object: Range

275

Parameter Type Description

refNode Node Specifies the node after which the range ends. The parent node for the end of the range

will be the same as the parent node of refNode .

Return valuesNone.

Exceptions

Exception Description

INVALID_NODE_TYPE_ERR Thrown if the root container of refNode is not an Attr , Document , or

DocumentFragment node, or if refNode is an Attr, Document,

DocumentFragment, Entity , or Notation node.

INVALID_STATE_ERR Thrown if the Range.detach() method is already invoked on the Range object.

Method: Range.setEndBefore()

Availability BlackBerry® Device Software version 4.7.1 or later

The setEndBefore() method sets the end point of a range at a position that is before the specified node.

SyntaxRange.setEndBefore( refNode )

Parameters

Parameter Type Description

refNode Node Specifies the node before which the range ends. The parent node for the end of the

range will be the same as the parent node of refNode .

Return valuesNone.

Exceptions

JavaScript Reference Object: Range

276

Exception Description

INVALID_NODE_TYPE_ERR Thrown if the root container of refNode is not an Attr , Document , or

DocumentFragment node, or if refNode is an Attr, Document,

DocumentFragment, Entity , or Notation node.

INVALID_STATE_ERR Thrown if the Range.detach() method is already invoked on the Range object.

Method: Range.setEnd()

Availability BlackBerry® Device Software version 4.7.1 or later

The setEnd() method sets the end point of the range.

SyntaxRange.setEnd( endNode, endOffset )

Parameters

Parameter Type Description

endNode Node Specifies the node at which the range ends. This parameter must not be null.

endOffset int Specifies the offset for the end of the range from the start of endNode .

Return valuesNone.

Exceptions

Exception Description

INDEX_SIZE_ERR Thrown if endOffset is greater than the number of child units in endNode .

For CharacterData nodes (such as Text or Comment nodes) or

ProcessingInstruction nodes, child units are 16-bit units. For all other nodes,

child units are child nodes.

INVALID_NODE_TYPE_ERR Thrown if endNode or an ancestor of endNode is an Entity , Notation , or

DocumentType node.

INVALID_STATE_ERR Thrown if the Range.detach() method is already invoked on the Range object.

JavaScript Reference Object: Range

277

Method: Range.setStartAfter()

Availability BlackBerry® Device Software version 4.7.1 or later

The setStartAfter() method sets the start point of a range at a position that is after the specified node.

SyntaxRange.setStartAfter( refNode )

Parameters

Parameter Type Description

refNode Node Specifies the node after which the range begins. The parent node for the start of the

range will be the same as the parent node of refNode .

Return valuesNone.

Exceptions

Exception Description

INVALID_NODE_TYPE_ERR Thrown if the root container of refNode is not an Attr , Document , or

DocumentFragment node, or if refNode is an Attr, Document,

DocumentFragment, Entity , or Notation node.

INVALID_STATE_ERR Thrown if the Range.detach() method is already invoked on the Range object.

Method: Range.setStartBefore()

Availability BlackBerry® Device Software version 4.7.1 or later

The setStartBefore() method sets the start point of a range at a position that is before the specified node.

SyntaxRange.setStartBefore( refNode )

Parameters

JavaScript Reference Object: Range

278

Parameter Type Description

refNode Node Specifies the node before which the range begins. The parent node for the start of the

range will be the same as the parent node of refNode .

Return valuesNone.

Exceptions

Exception Description

INVALID_NODE_TYPE_ERR Thrown if the root container of refNode is not an Attr , Document , or

DocumentFragment node, or if refNode is an Attr, Document,

DocumentFragment, Entity , or Notation node.

INVALID_STATE_ERR Thrown if the Range.detach() method is already invoked on the Range object.

Method: Range.setStart()

Availability BlackBerry® Device Software version 4.7.1 or later

The setStart() method sets the start point of the range.

SyntaxRange.setStart( startNode, startOffset )

Parameters

Parameter Type Description

startNode Node Specifies the node at which the range begins. This parameter must not be null.

startOffset int Specifies the offset for the start of the range from the start of startNode .

Return valuesNone.

Exceptions

Exception Description

INDEX_SIZE_ERR Thrown if startOffset is greater than the number of child units in startNode .

JavaScript Reference Object: Range

279

Exception Description

For CharacterData nodes (such as Text or Comment nodes) or

ProcessingInstruction nodes, child units are 16-bit units. For all other nodes,

child units are child nodes.

INVALID_NODE_TYPE_ERR Thrown if startNode or an ancestor of startNode is an Entity , Notation ,

or DocumentType node.

INVALID_STATE_ERR Thrown if the Range.detach() method is already invoked on the Range object.

Method: Range.surroundContents()

Availability BlackBerry® Device Software version 4.7.1 or later

The surroundContents() method moves the contents of the range to a new node object, and inserts the new node at thestart point of the range.

SyntaxRange.surroundContents( newNode )

Parameters

Parameter Type Description

newNode Node Specifies the node with which to surround the contents.

Return valuesNone.

Exceptions

Exception Description

BAD_BOUNDARYPOINTS_ERR Thrown if the range partially selects a non-text node.

HIERARCHY_REQUEST_ERR Thrown if:

• the container of the start of the range is of a type that does not allow child

nodes of the type of newNode

• newNode is an ancestor of the container

• inserting newNode results in newNode having a child node of a type that

it does not allow

JavaScript Reference Object: Range

280

Exception Description

INVALID_NODE_TYPE_ERR Thrown if newNode is an Attr , Document , DocumentFragment ,

DocumentType , Entity , or Notation node.

INVALID_STATE_ERR Thrown if the Range.detach() method is already invoked on the Range

object.

NO_MODIFICATION_ALLOWED_ERR Thrown if an ancestor container of either start point or the end point of the range

is read-only.

WRONG_DOCUMENT_ERR Thrown if newNode and the container of the start point of the range are not

created from the same document.

Method: Range.toString()

Availability BlackBerry® Device Software version 4.7.1 or later

The toString() method returns the contents of the range as a string.

SyntaxRange.toString()

ParametersNone.

Return valuesThis method returns the contents of the range as a string.

Exceptions

Exception Description

INVALID_STATE_ERR Thrown if the Range.detach() method is already invoked on the Range object.

Object: Rect

Availability BlackBerry® Device Software version 4.6 or later

The Rect object represents a Rect value.

The Rect object contains four properties, each of which defines a style for the side of a rectangle.

JavaScript Reference Object: Rect

281

Rect properties

Property name Type Description Status Availability

bottom String Returns the style for the bottom of the Rect. read only 4.6 or later

left String Returns the style for the left side of the Rect. read only 4.6 or later

right String Returns the style for the right side of the Rect. read only 4.6 or later

top String Returns the style for the top of the Rect. read only 4.6 or later

Object: RGBColor

Availability BlackBerry® Device Software version 4.6 or later

Extends Node

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

RGBColor properties

Property name Type Description Status Availability

blue CSSPrimitiveValu

e

Returns the blue value of the RGB value. read only 4.6 or later

green CSSPrimitiveValu

e

Returns the green value of the RGB value. read only 4.6 or later

red CSSPrimitiveValu

e

Returns the red value of the RGB value. read only 4.6 or later

JavaScript Reference Object: RGBColor

282

Object: Screen

Availability BlackBerry® Device Software version 3.8 or later

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

Screen properties

Property name Type Description Status Availability

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 3.8 or later

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 3.8 or later

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 3.8 or later

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 3.8 or later

colorDepth int Returns the bit depth of the color palette. This property

behaves identically to the pixelDepth property.

read only 3.8 or later

height int Returns the height of the BlackBerry device screen, in

pixels.

read only 3.8 or later

pixelDepth int Returns the color resolution, in bits per pixel, of the display. read only 3.8 or later

width int Returns the width of the BlackBerry device screen, in pixels. read only 3.8 or later

Object: Selection

Availability BlackBerry® Device Software version 4.7.1 or later

JavaScript Reference Object: Screen

283

The Selection object contains one or more Range objects.

Selection properties

Property name Type Description Status Availability

anchorNode Node Returns the node in which the selection begins. read-only 4.7.1 or later

anchorOffset int Returns the number of characters within the

anchorNode that the selection begins.

read-only 4.7.1 or later

focusNode Node Returns the node in which the selection ends. read-only 4.7.1 or later

focusOffset int Returns the number of characters within the

focusNode that the selection ends.

read-only 4.7.1 or later

isCollapsed boolean Returns true if the start point and end point of the

selection are at the same position; returns false if

they are not.

read-only 4.7.1 or later

rangeCount int Returns the number of Range objects contained by

the Selection object.

read-only 4.7.1 or later

Selection methods

Method name Description Availability

addRange() Adds a Range object to the selection. 4.7.1 or later

collapse() Collapses a selection onto a single boundary point. 4.7.1 or later

collapseToEnd() Moves the anchor of the selection to the same point as the focus. 4.7.1 or later

collapseToStart() Moves the focus of the selection to the same point as the anchor. 4.7.1 or later

deleteFromDocument() Deletes the text contained within the selection from the Document

object.

4.7.1 or later

getRangeAt() Returns a Range object that is present in the selection. 4.7.1 or later

removeRange() Removes the specified Range object from the selection. 4.7.1 or later

removeAllRanges() Removes all Range objects from the selection. 4.7.1 or later

selectAllChildren() Adds all the child nodes of a specified node to the selection. 4.7.1 or later

JavaScript Reference Object: Selection

284

Method: Selection.addRange()

Availability BlackBerry® Device Software version 4.7.1 or later

The addRange() method adds a Range object to the selection.

SyntaxSelection.addRange( range )

Parameters

Parameter Type Description

range Range Specifies the Range to add to the selection.

Return valuesNone.

ExceptionsNone.

Method: Selection.collapseToEnd()

Availability BlackBerry® Device Software version 4.7.1 or later

The collapseToEnd() method moves the anchor of the selection to the same point as the focus.

SyntaxSelection.collapseToEnd()

ParametersNone.

Return valuesNone.

ExceptionsNone.

JavaScript Reference Object: Selection

285

Method: Selection.collapseToStart()

Availability BlackBerry® Device Software version 4.7.1 or later

The collapseToStart() method moves the focus of the selection to the same point as the anchor.

SyntaxSelection.collapseToStart()

ParametersNone.

Return valuesNone.

ExceptionsNone.

Method: Selection.collapse()

Availability BlackBerry® Device Software version 4.7.1 or later

The collapse() method collapses a selection onto a single point.

SyntaxSelection.collapse( parentNode, offset )

Parameters

Parameter Type Description

parentNode Node Specifies the node into which the selection is collapsed.

offset int Specifies the offset to which the selection is collapsed. Valid values may be one of

the following:

0: Collapses the selection from the anchor onto the start point of parentNode .

1: Collapses the selection from the anchor onto the end point of parentNode .

Return values

JavaScript Reference Object: Selection

286

None.

ExceptionsNone.

Method: Selection.deleteFromDocument()

Availability BlackBerry® Device Software version 4.7.1 or later

The deleteFromDocument() method deletes the text contained within the selection from the Document object.

SyntaxSelection.deleteFromDocument()

ParametersNone.

Return valuesNone.

ExceptionsNone.

Method: Selection.getRangeAt()

Availability BlackBerry® Device Software version 4.7.1 or later

The getRangeAt() method returns a Range object that is present in the selection.

SyntaxSelection.getRangeAt( index )

Parameters

Parameter Type Description

index int Specifies an integer that represents the Range object’s position in the frame map.

Valid values are from 0 to Selection.rangeCount -1.

Return values

JavaScript Reference Object: Selection

287

This method returns the Range object at the specified index.

ExceptionsNone.

Method: Selection.removeAllRanges()

Availability BlackBerry® Device Software version 4.7.1 or later

The removeAllRanges() method removes all Range objects from the selection.

SyntaxSelection.removeAllRanges()

ParametersNone.

Return valuesNone.

ExceptionsNone.

Method: Selection.removeRange()

Availability BlackBerry® Device Software version 4.7.1 or later

The removeRange() method removes the specified Range object from the selection.

SyntaxSelection.removeRange( range )

Parameters

Parameter Type Description

range Range Specifies the Range object to remove from the selection.

Return valuesNone.

Exceptions

JavaScript Reference Object: Selection

288

None.

Method: Selection.selectAllChildren()

Availability BlackBerry® Device Software version 4.7.1 or later

The selectAllChildren() method adds all the child nodes from a specified node to the selection. If the selection is alreadypopulated, the contents are replaced.

SyntaxSelection.selectAllChildren( parentNode )

Parameters

Parameter Type Description

parentNode Node Specifies the node that is the parent of the nodes to add to the selection. The

parentNode is not added.

Return valuesNone.

ExceptionsNone.

Object: StyleSheet

Availability BlackBerry® Device Software version 4.6 or later

The StyleSheet object represents a single style sheet associated with a document. A StyleSheet object can representeither an external style sheet, or an inline style element.

StyleSheet properties

Property name Type Description Status Availability

disabled boolean When true, indicates that

the style sheet is not applied.

writable 4.6 or later

JavaScript Reference Object: StyleSheet

289

Property name Type Description Status Availability

Note that if the media

specified in the

MediaList object returned

by StyleSheet.media is

not supported by the

BlackBerry® Browser, then

this property is ignored.

href String Returns the URI of an

external style sheet.

read only 4.6 or later

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

e.

read only 4.6 or later

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 4.6 or later

parentStyleShee

t

StyleShee

t

Returns the StyleSheet

object that contains the style

sheet, if one exists.

read only 4.6 or later

JavaScript Reference Object: StyleSheet

290

Property name Type Description Status Availability

If the style sheet is not the

child of another style sheet,

this property returns null.

title String Returns the title of the style

sheet.

The title is often specified in

StyleSheet.ownerNod

e.

read only 4.6 or later

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

e.

read only 4.6 or later

Object: StyleSheetList

Availability BlackBerry® Device Software version 4.6 or later

The StyleSheetList object represents an ordered collection of StyleSheet objects.

You can access an individual StyleSheet within a collection by its index position using StyleSheetList.item() or youcan index the object directly. For example, if you create an instance of a StyleSheetList object called myStyleSheets,then specifying

myStyleSheets.item(2)

is equivalent to specifying

myStyleSheets[2]

JavaScript Reference Object: StyleSheetList

291

StyleSheetList properties

Property name Type Description Status Availability

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

StyleSheetList methods

Method name Description Availability

item() Returns the StyleSheet object at the specified index in the

StyleSheetList.

4.6 or later

Method: StyleSheetList.item()

Availability BlackBerry® Device Software version 4.6 or later

The item() method returns the StyleSheet object at the specified index in the StyleSheetList.

SyntaxStyleSheetList.item( index )

Parameters

Parameter Type Description

index int An integer that represents the stylesheet’s position in stylesheet

list. Valid values are 0 to StyleSheetList.length -1.

Return valuesReturns the rule at the index th position in StyleSheetList, or null if an invalid index position is specified.

ExceptionsNone.

JavaScript Reference Object: StyleSheetList

292

Object: Text

Availability BlackBerry® Device Software version 4.6 or later

Extends CharacterData

The Text object represents the textual content of an element or attribute. If an element contains no child elements, any text iscontained 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 nomeaning in a document. Hence, using Text.splitText() has no visual effect on the document unless one of the nodes iswrapped by an element.

Text methods

Method name Description Availability

splitText() Breaks the node into two nodes at the specified offset location. 4.6 or later

Method: Text.splitText()

Availability BlackBerry® Device Software version 4.6 or later

The splitText() method breaks the node into two nodes at the specified offset location.

SyntaxText.splitText( offset )

Parameters

Parameter Type Description

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

Return valuesReturns the second half of the text as a new Text node, which is automatically added to the DOM tree adjacent to the originalText node.

Exceptions

JavaScript Reference Object: Text

293

Exception Description

INDEX_SIZE_ERR This error is thrown if offset is negative, or is greater than

the number of 16-bit units in the data.

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

Object: TextEvent

Availability BlackBerry® Device Software version 4.6 or later

Extends UIEvent

The TextEvent object extends the UIEvent object and represents an event generated by entering characters using eitherthe 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 beenentered.

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

TextEvent properties

Property name Type Description Status Availability

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 4.6 or later

Text event types

Event type Bubbles Cancelable Description

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

This event type includes the following context information:

TextEvent.data , UIEvent.view

JavaScript Reference Object: TextEvent

294

TextEvent methods

Method name Description Availability

initTextEvent() Initializes the value of a TextEvent. 4.6 or later

initTextEventNS() Initializes the value of a TextEvent with the given namespace URI. 4.6 or later

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

SyntaxTextEvent.initTextEvent( typeArg, canBubbleArg, cancelableArg, viewArg, dataArg )

Parameters

Parameter Type Description

typeArg String Specifies the event type.

canBubbleArg boolean When true, this parameter indicates that the event can bubble.

cancelableArg boolean When true, this parameter indicates that the event can be

cancelled.

viewArg AbstractView Specifies the window or frame that is generating the event.

dataArg String Specifies the characters generated by the input device. This

parameter sets the value of TextEvent.data .

Return valuesNone.

ExceptionsNone.

Method: TextEvent.initTextEventNS()The initTextEventNS() method initializes the value of a TextEvent created by Document.createEvent() withthe given namespace URI.

Syntax

JavaScript Reference Object: TextEvent

295

TextEvent.initTextEventNS( namespaceURI, typeArg, canBubbleArg, cancelableArg, viewArg,dataArg )

Parameters

Parameter Type Description

namespaceURI String Specifies the namespace URI associated with this event, or null

if no namespace exists.

typeArg String Specifies the event type.

canBubbleArg boolean When true, this parameter indicates that the event can bubble.

cancelableArg boolean When true, this parameter indicates that the event can be

cancelled.

viewArg AbstractView Specifies the window or frame that is generating the event.

dataArg String Specifies the characters generated by the input device. This

parameter sets the value of TextEvent.data .

Return valuesNone.

ExceptionsNone.

Object: TreeWalker

Availability BlackBerry® Device Software version 4.6 or later

The TreeWalker object enables you to navigate the document tree or subtree. This object is similar to the NodeIteratorobjects, except that TreeWalker presents nodes in a tree-oriented view, rather than the list view presented byNodeIterator. This allows you to use TreeWalker to navigate directly to a parent or child, rather than simply up and downin the list using NodeIterator.

Create a TreeWalker using Document.createTreeWalker() .

JavaScript Reference Object: TreeWalker

296

TreeWalker properties

Property name Type Description Status Availability

currentNode Node Specifies the current position of the

TreeWalker.

writable 4.6 or later

expandEntityReferenc

es

boolean Returns whether or not the TreeWalker

expands the entity references it encounters as

it traverses the document.

read only 4.6 or later

filter NodeFilt

er

Returns the NodeFilter used to filter nodes

for traversal.

read only 4.6 or later

root Node Returns the Node at which the TreeWalker

begins traversing the document.

read only 4.6 or later

whatToShow unsigned

long

Returns which node types are presented by the

TreeWalker. The value may be one or more

of:

• 0xFFFFFFFF = SHOW_ALL

• 0x00000001 = SHOW_ELEMENT

• 0x00000002 = SHOW_ATTRIBUTE

• 0x00000004 = SHOW_TEXT

• 0x00000008 =

SHOW_CDATA_SECTION

• 0x00000010 =

SHOW_ENTITY_REFERENCE

• 0x00000020 = SHOW _ENTITY

• 0x00000040 =

SHOW_PROCESSING_INSTRUCTION

• 0x00000080 = SHOW_COMMENT

• 0x00000100 = SHOW_DOCUMENT

• 0x00000200 =

SHOW_DOCUMENT_TYPE

• 0x00000400 =

SHOW_DOCUMENT_FRAGMENT

read only 4.6 or later

JavaScript Reference Object: TreeWalker

297

Property name Type Description Status Availability

• 0x00000800 = SHOW_NOTATION

Multiple values may be specified using a bitwise

OR.

Note that because attributes, entities, and

notations are not the child of any other node,

they never appear in the TreeWalker’s

logical view unless they are defined as the root

of the TreeWalker object. If the respective

object is not defined as the root, then

SHOW_ATTRIBUTE, SHOW_ENTITY, and

SHOW NOTATION have no meaning.

TreeWalker methods

Method name Description Availability

firstChild() Moves the TreeWalker to the first visible child of the current node. 4.6 or later

lastChild() Moves the TreeWalker to the last visible child of the current node. 4.6 or later

nextNode() Moves the TreeWalker to the next visible node in the document order,

relative to the current node.

4.6 or later

nextSibling() Moves the TreeWalker to the next sibling of the current node. 4.6 or later

parentNode() Moves the TreeWalker to the closest visible ancestor node of the current

node.

4.6 or later

previousNode() Moves the TreeWalker to the previous visible node in the document order,

relative to the current node.

4.6 or later

previousSibling() Moves the TreeWalker to the previous sibling of the current node. 4.6 or later

JavaScript Reference Object: TreeWalker

298

Method: TreeWalker.firstChild()

Availability BlackBerry® Device Software version 4.6 or later

The firstChild() method moves the TreeWalker to the first visible child of the current node. The value ofTreeWalker.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()

ParametersNone.

Return valuesReturns the node, or null, if the current node has no visible children in the TreeWalker’s logical view.

ExceptionsNone.

Method: TreeWalker.lastChild()

Availability BlackBerry® Device Software version 4.6 or later

The lastChild() method moves the TreeWalker to the last visible child of the current node. The value ofTreeWalker.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()

ParametersNone.

Return valuesReturns the node, or null, if the current node has no visible children in the TreeWalker’s logical view.

ExceptionsNone.

JavaScript Reference Object: TreeWalker

299

Method: TreeWalker.nextNode()

Availability BlackBerry® Device Software version 4.6 or later

The nextNode() method moves the TreeWalker to the next visible Node in the document order, relative to the currentnode. 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 remainsunchanged.

SyntaxTreeWalker.nextNode()

ParametersNone.

Return valuesReturns the node, or null, if there is no node after the current node in the TreeWalker’s logical view.

ExceptionsNone.

Method: TreeWalker.nextSibling()The nextSibling() method moves the TreeWalker to the next sibling of the current node. The value ofTreeWalker.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.currentNoderemains unchanged.

SyntaxTreeWalker.nextSibling()

ParametersNone.

Return valuesReturns the node, or null, if the current node has no visible siblings after it in the TreeWalker’s logical view.

ExceptionsNone.

JavaScript Reference Object: TreeWalker

300

Method: TreeWalker.parentNode()

Availability BlackBerry® Device Software version 4.6 or later

The parentNode() method moves the TreeWalker to the closest visible ancestor node of the current node. The value ofTreeWalker.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()

ParametersNone.

Return valuesReturns the node, or null, if the current node has no visible ancestor in the TreeWalker’s logical view.

ExceptionsNone.

Method: TreeWalker.previousNode()The previousNode() method moves the TreeWalker to the previous visible Node in the document order, relative to thecurrent 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 remainsunchanged.

SyntaxTreeWalker.previousNode()

ParametersNone.

Return valuesReturns the node, or null, if there is no node before the current node in the TreeWalker’s logical view.

ExceptionsNone.

JavaScript Reference Object: TreeWalker

301

Method: TreeWalker.previousSibling()

Availability BlackBerry® Device Software version 4.6 or later

The previousSibling() method moves the TreeWalker to the previous sibling of the current node. The value ofTreeWalker.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.currentNoderemains unchanged.

SyntaxTreeWalker.previousSibling()

ParametersNone.

Return valuesReturns the node, or null, if the current node has no visible sibling before it in the TreeWalker’s logical view.

ExceptionsNone.

Object: UIEvent

Availability BlackBerry® Device Software version 4.6 or later

Extends Event

Extended by KeyboardEvent , MouseEvent , TextEvent

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

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

UIEvent properties

Property name Type Description Status Availability

detail long Returns detail information about the event. read only 4.6 or later

JavaScript Reference Object: UIEvent

302

Property name Type Description Status Availability

view AbstractVie

w

Returns a reference to the AbstractView that

generated the event.

read only 4.6 or later

User interface events

Event type Bubbles Cancelable Description

DOMFocusIn yes no Occurs when an EventTarget receives focus.

DOMFocusOut yes no Occurs when an EventTarget loses focus.

DOMActivate yes yes Occurs when an EventTarget is activated though a keyboard press or

trackball or trackwheel click.

This event type includes the following context information:

UIEvent.detail

UIEvent methods

Method name Description Availability

initUIEvent() Initializes the value of a UIEvent. 4.6 or later

Method: UIEvent.initUIEvent()

Availability BlackBerry® Device Software version 4.6 or later

The initUIEvent() method initializes the value of a UIEvent created by Document.createEvent() .

SyntaxUIEvent.initUIEvent( typeArg, canBubbleArg, cancelableArg, viewArg, detailArg )

Parameters

Parameter Type Description

typeArg String Specifies the event type.

JavaScript Reference Object: UIEvent

303

Parameter Type Description

canBubbleArg boolean When true, this parameter indicates that the event can bubble.

cancelableArg boolean When true, this parameter indicates that the event can be

cancelled.

viewArg AbstractView Specifies the window or frame that is generating the event.

detailArg long Specifies the code for the event detail.

Return valuesNone.

ExceptionsNone.

Object: Window

Availability BlackBerry® Device Software version 3.8 or later

The Window object is created automatically when the BlackBerry® Browser encounters a <body> or <frameset> tag. Itreturns information about the window.

Window properties

Property name Type Description Status Availability

blackberry blackberry Returns a reference to the blackberry object. read only 3.8 or later

closed boolean Returns whether the window is open or closed.

This property always has a value of false.

read only 3.8 or later

document Document Returns the Document object that is contained

within the window.

read only 3.8 or later

frameElement HTMLElement Returns the element in which the window is

embedded, or null if the window is not embedded

in any frame.

read only 3.8 or later

frames NamedFrameMa

p

Returns a NamedFrameMap object that contains

a collection of the frames contained by the

frameset.

read only 3.8 or later

JavaScript Reference Object: Window

304

Property name Type Description Status Availability

history History Returns the History object that contains a

collection of recently accessed URLs.

read only 3.8 or later

innerHeight int Returns the height of the content area, including

the horizontal scroll bar, if rendered.

read only 3.8 or later

innerWidth int Returns the width of the content area, including

the vertical scroll bar, if rendered.

read only 3.8 or later

length unsigned long Returns the number of frames in the parent

window.

read only 3.8 or later

location Location Specifies the URL of the document displayed in

the browser window.

writable 3.8 or later

navigator Navigator Returns the Navigator object, which provides

information about the BlackBerry® Browser.

read only 3.8 or later

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

opener Window Returns the Window object that created the

window.

read only 3.8 or later

orientation int Returns an integer that represents the current

orientation of a BlackBerry device that has an

accelerometer, such as a BlackBerry® Storm™

Series device.

This property can have one of the following values:

• 0: The BlackBerrydevice is in portrait mode.

• -90: The BlackBerry device is in landscape

mode and is turned to the right

• 90: the BlackBerry device is in landscape

mode and turned to the left.

read only 4.7 or later

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

screen Screen Returns the Screen object, which provides

information about the BlackBerry device screen.

read only 3.8 or later

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

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

JavaScript Reference Object: Window

305

Property name Type Description Status Availability

window Window Returns a reference to the current window. Using

the window property lets you invoke methods or

call properties on the current window without

confusion when multiple browser windows are

open.

Because the BlackBerry Browser is a single

document interface, a new window is opened each

time a new URL is opened.

read only 3.8 or later

Window event handlers

Property name Type Description Status Availability

onabort EventListene

r

Specifies the

function to

perform when

the loading of a

page or image is

aborted.

writable 4.6 or later

onchange EventListene

r

Specifies the

function to

perform when a

form control

loses focus after

the user has

modified the

value.

writable 4.6 or later

onclick EventListene

r

Specifies the

function to

perform when

the user clicks

the trackball or

writable 3.8 or later

JavaScript Reference Object: Window

306

Property name Type Description Status Availability

trackwheel on a

BlackBerry®

device.

onkeydown EventListene

r

Specifies the

function to

perform when a

key is pressed

down while the

pointer is over

an element.

writable 4.6 or later

onkeypress EventListene

r

Specifies the

function to

perform when a

key is pressed

and released

while the

pointer is over

an element.

writable 4.6 or later

onkeyup EventListene

r

Specifies the

function to

perform when a

key is released

while the

pointer is over

an element.

writable 4.6 or later

onload EventListene

r

Specifies the

function to

perform when

the BlackBerry®

Browser finishes

loading a new

page or a

complete

frameset.

writable 4.6 or later

JavaScript Reference Object: Window

307

Property name Type Description Status Availability

onmousedown EventListene

r

Specifies the

function to

perform when

the user

depresses the

trackwheel or

trackball on a

BlackBerry

device.

writable 4.6 or later

onmousemove EventListene

r

Specifies the

function to

perform when

the user moves

the pointer

while it is over an

element.

writable 4.6 or later

onmouseout EventListene

r

Specifies the

function to

perform when

the user moves

the pointer off of

an element.

writable 4.6 or later

onmouseover EventListene

r

Specifies the

function to

perform when

the user moves

the pointer over

an element.

writable 4.6 or later

onmouseup EventListene

r

Specifies the

function to

perform when

the user releases

the trackwheel

writable 4.6 or later

JavaScript Reference Object: Window

308

Property name Type Description Status Availability

or trackball on a

BlackBerry

device.

onorientationchan

ge

EventListene

r

Specifies the

function to

perform when

the user

changes the

orientation of a

BlackBerry

device that has

an

accelerometer,

such as a

BlackBerry®

Storm™ Series

device.

writable 4.7 or later

onreset EventListene

r

Specifies the

function to

perform when

the user resets a

form.

writable 3.8 or later

onselect EventListene

r

Specifies the

function to

perform when

the user selects

some text in a

text field.

writable 4.6 or later

onsubmit EventListene

r

Specifies the

function to

perform when

the user submits

a form.

writable 3.8 or later

JavaScript Reference Object: Window

309

Property name Type Description Status Availability

onunload EventListene

r

Specifies the

function to

perform when

the BlackBerry

Browser

removes a new

page or a

frameset.

writable 4.6 or later

Window methods

Method name Description Availability

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

window.

4.6 or later

alert() Displays a standard alert dialog box with an OK button. 3.8 or later

back() Displays the previous URL in the history list. 3.8 or later

blur() Removes focus from the window. 3.8 or later

close() Closes the active window. 3.8 or later

confirm() Displays a standard confirmation dialog box with an OK button and

a Cancel button.

3.8 or later

dispatchEvent() Dispatches an Event object created by

Document.createEvent().

4.6 or later

find() Displays a dialog box that allows a user to enter a string of text and

search for it in the current document.

4.6 or later

focus() Gives focus to the current window. 3.8 or later

forward() Displays the next element in the history list of the browser. 3.8 or later

getComputedStyle() Retrieves the computed style values for an element. 4.6 or later

home() Returns to the page that the user set as the browser home page. 3.8 or later

moveBy() Moves the window a specified number of pixels in relation to its

current co-ordinates.

3.8 or later

moveTo() Moves the window's left and top edge to the specified co-ordinates. 3.8 or later

open() Opens a new browser window. 3.8 or later

JavaScript Reference Object: Window

310

Method name Description Availability

print() Prints the current contents of the window. 3.8 or later

prompt() Displays a prompt dialog box that prompts users for input. 3.8 or later

removeEventListener() Removes an event listener from an EventTarget. 4.6 or later

resizeBy() Resizes the viewport relative to the current viewport size. 3.8 or later

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

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

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

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

stop() Stops the current download. 3.8 or later

Method: window.addEventListener()

Availability BlackBerry® Device Software version 4.6 or later

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

Syntaxwindow.addEventListener( type, listener, useCapture )

Parameters

Parameter Type Description

type String The type of event to add.

listener EventListener The EventListener function to be invoked.

useCapture boolean When true, indicates all events of the specified type to the

registered EventListener before being dispatched to any

EventTarget objects 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 EventTarget objects above the given node

in the tree.

Return values

JavaScript Reference Object: Window

311

None.

ExceptionsNone.

See alsoEvent , EventListener

Method: window.alert()

Availability BlackBerry® Device Software version 3.8 or later

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

Parameter Type Description

message String The text that is displayed as the dialog box message.

Return valuesNone.

ExceptionsNone.

See alsowindow.confirm() , window.prompt()

Method: window.back()

Availability BlackBerry® Device Software version 3.8 or later

The back() method displays the previous URL in the history list. This method is functionally equivalent to history.back() .

Syntax

JavaScript Reference Object: Window

312

window.back()

ParametersNone.

Return valuesNone.

ExceptionsNone.

See alsohistory.back() , window.close() , window.forward() , window.history

Method: window.blur()

Availability BlackBerry® Device Software version 3.8 or later

The blur() method removes focus from the window.

This method is a stub implementation. It has no effect on the BlackBerry® Browser.

Syntaxwindow.blur()

ParametersNone.

Return valuesThis method is ignored. No values are returned.

ExceptionsNone.

Method: window.close()

Availability BlackBerry® Device Software version 3.8 or later

The close() method closes the active window. In the BlackBerry® Browser, this is functionally equivalent to window.back() and history.back() .

JavaScript Reference Object: Window

313

If no earlier item exists in the window.history array, the BlackBerry Browser is closed and the browser session ends.

Syntaxwindow.close()

ParametersNone.

Return valuesThis method is ignored. No values are returned.

ExceptionsNone.

See alsohistory.back() , window.back() , window.history , window.open()

Method: window.confirm()

Availability BlackBerry® Device Software version 3.8 or later

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 notcontinue to browse or use the current page until they have closed the dialog box.

Syntaxwindow.confirm( message )

Parameters

Parameter Type Description

message String The text that is displayed as the dialog box message.

Return valuesReturns a value of true if the OK button was clicked; returns false if Cancel was clicked.

ExceptionsNone.

See alsowindow.alert() , window.prompt()

JavaScript Reference Object: Window

314

Method: window.dispatchEvent()

Availability BlackBerry® Device Software version 4.6 or later

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

Syntaxwindow.dispatchEvent( event )

Parameters

Parameter Type Description

event Event The Event object to be dispatched.

Return valuesReturns true if the Event.preventDefault() was not called by any of the event listeners that handled the event. TheEvent.preventDefault() method prevents the default action for the event from occurring. Otherwise, returns false.

Exceptions

Exception Description

UNSPECIFIED_EVENT_TYPE_ERR This error is thrown if the event type was not specified by

initializing the event before calling dispatchEvent(), or if

the event type was null.

Method: window.find()

Availability BlackBerry® Device Software version 4.6 or later

The find() method searches for a given string in the current window. If the search term was located within the window, thesearch 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 youprovide a new search term, the browser begins searching at the start of the document and stops and returns a value of truewhen the given term is found.

Note that the caseSensitive and searchInFrames parameters are optional, but mutually inclusive. That is, you musteither specify both of the parameters or neither of them.

Syntax

JavaScript Reference Object: Window

315

window.find( str [, caseSensitive, searchInFrames ] )

Parameters

Parameter Type Description

str String The string of text to search for in the current document.

caseSensitive boolean Optional. If true, indicates that the case of the search term

should be considered when searching.

searchInFrames boolean Optional. If true, indicates that the browser should search for

the given term in all currently displayed frames.

Return valuesReturn a value of true if the string is found; otherwise, returns false.

ExceptionsNone.

Method: window.focus()

Availability BlackBerry® Device Software version 3.8 or later

The focus() method gives focus to the window.

Syntaxwindow.focus()

ParametersNone.

Return valuesNone.

ExceptionsNone.

JavaScript Reference Object: Window

316

Method: window.forward()

Availability BlackBerry® Device Software version 3.8 or later

The forward() method displays the next URL in the history list of the browser. This method is functionally equivalent tohistory.forward() .

Syntaxwindow.forward()

ParametersNone.

Return valuesNone.

ExceptionsNone.

See alsohistory.forward() , window.back() , window.history

Method: window.getComputedStyle()

Availability BlackBerry® Device Software version 4.6 or later

The getComputedStyle() method retrieves the computed style values for an element. This method returns the styledeclaration as a read only value.

Syntaxwindow.getComputedStyle( elt, pseudoElt )

Parameters

Parameter Type Description

elt Element The element for which to view the style.

pseudoElt String The pseudo-element for which to modify the style, or null if none.

Return values

JavaScript Reference Object: Window

317

Returns the computed style value for the specified element.

ExceptionsNone.

See alsoHTMLElement.style

Method: window.home()

Availability BlackBerry® Device Software version 3.8 or later

The home() method displays the page that the user set as the BlackBerry® Browser home page.

Syntaxwindow.home()

ParametersNone.

Return valuesNone.

ExceptionsNone.

Method: window.moveBy()

Availability BlackBerry® Device Software version 3.8 or later

The moveBy() method moves the window a specified number of pixels in relation to its current co-ordinates.

This method is a stub implementation. It has no effect on the BlackBerry® Browser.

Syntaxwindow.moveBy ( deltaX, deltaY )

Parameters

JavaScript Reference Object: Window

318

Parameter Type Description

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

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

Return valuesThis method is ignored. No values are returned.

ExceptionsNone.

Method: window.moveTo()

Availability BlackBerry® Device Software version 3.8 or later

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

This method is a stub implementation. It has no effect on the BlackBerry® Browser .

Syntaxwindow.moveTo ( deltaX, deltaY )

Parameters

Parameter Type Description

deltaX int The number of pixels from the left edge of the screen to move

the window.

deltaY int The number of pixels from the top edge of the screen to move

the window.

Return valuesThis method is ignored. No values are returned.

ExceptionsNone.

JavaScript Reference Object: Window

319

Method: window.open()

Availability BlackBerry® Device Software version 3.8 or later

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 wheneverthe user opens a link on a page or enters a new URL via the Go to menu item. Consequently, this method essentially has thesame net effect in the BlackBerry Browser as specifying a new value for Window.location .

Syntaxwindow.open( URL [, name ] )

Parameters

Parameter Type Description

URL int The URL to be displayed in the child window.

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

Return valuesReturns a reference to the new Window object.

ExceptionsNone.

See alsowindow.close()

Method: window.print()

Availability BlackBerry® Device Software version 3.8 or later

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

This method is a stub implementation. It has no effect on the BlackBerry® Browser.

Syntaxwindow.print()

Parameters

JavaScript Reference Object: Window

320

None.

Return valuesThis method is ignored. No values are returned.

ExceptionsNone.

Method: window.prompt()

Availability BlackBerry® Device Software version 3.8 or later

The prompt() method displays a prompt dialog box that prompts users for input. A prompt dialog box includes a single lineinput field.

Use a prompt dialog when you need immediate feedback from the user. The user may not continue to browse or use the currentpage until they have closed the dialog box.

Syntaxwindow.prompt( message, defaultValue )

Parameters

Parameter Type Description

message String The text that is displayed as the dialog box message.

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

provided.

Return valuesReturns the user input as a string. If the user enters no input, this method returns an empty string.

ExceptionsNone.

See alsowindow.alert() , window.confirm()

Method: window.removeEventListener()

Availability BlackBerry® Device Software version 4.6 or later

JavaScript Reference Object: Window

321

The removeEventListener() method removes an event listener from the Window object.

Syntaxwindow.removeEventListener( type, listener, useCapture )

Parameters

Parameter Type Description

type String The type of event.

listener EventListener The event listener function to be removed.

useCapture boolean When true, indicates that the EventListener being

removed was registered as a capturing listener.

A listener may be registered twice, once as a capturing listener,

and once as a non-capturing listener. Each must be removed

separately.

Return valuesNone.

ExceptionsNone.

See alsoEvent , EventListener , Node.removeEventListener()

Method: window.resizeBy()

Availability BlackBerry® Device Software version 3.8 or later

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 )

Parameters

JavaScript Reference Object: Window

322

Parameter Type Description

deltaX int The number of pixels to resize the window by horizontally.

deltaY int The number of pixels to resize the window by vertically.

Return valuesNone.

ExceptionsNone.

See alsowindow.resizeTo()

Method: window.resizeTo()

Availability BlackBerry® Device Software version 3.8 or later

The resizeTo() method resizes the window to the specified width and height.

Syntaxwindow.resizeTo( width, height )

Parameters

Parameter Type Description

width int The new width of the viewport, in pixels.

height int The new height of the viewport, in pixels.

Return valuesNone.

ExceptionsNone.

See alsowindow.resizeBy()

JavaScript Reference Object: Window

323

Method: window.scroll()

Availability BlackBerry® Device Software version 3.8 or later

The scroll() method scrolls the content to a given set of coordinates. This method is functionally equivalent towindow.scrollTo() .

Syntaxwindow.scroll( x, y )

Parameters

Parameter Type Description

x int The position along the horizontal access, in pixels, to which to

scroll the document.

y int The position along the vertical access, in pixels, to which to scroll

the document.

Return valuesNone.

ExceptionsNone.

See alsowindow.scrollBy() , window.scrollTo()

Method: window.scrollBy()

Availability BlackBerry® Device Software version 3.8 or later

The scrollBy() method scrolls the content by the given number of pixels.

Syntaxwindow.scrollBy( deltaX, deltaY )

Parameters

JavaScript Reference Object: Window

324

Parameter Type Description

deltaX int The distance, in pixels, to scroll the document horizontally.

deltaY int The distance, in pixels, to scroll the document vertically.

Return valuesNone.

ExceptionsNone.

See alsowindow.scroll() , window.scrollTo()

Method: window.scrollTo()

Availability BlackBerry® Device Software version 3.8 or later

The scrollTo() method scrolls the content to a given set of coordinates. This method is functionally equivalent towindow.scroll() .

Syntaxwindow.scrollTo( x, y )

void

Parameters

Parameter Type Description

x int The position along the horizontal access, in pixels, to which to

scroll the document.

y int The position along the vertical access, in pixels, to which to scroll

the document.

Return valuesNone.

Exceptions

JavaScript Reference Object: Window

325

None.

See alsowindow.scroll() , window.scrollBy()

Method: window.stop()

Availability BlackBerry® Device Software version 3.8 or later

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

ParametersNone.

Return valuesNone.

ExceptionsNone.

Object: XMLHttpRequest

Availability BlackBerry® Device Software version 4.6 or later

The XMLHttpRequest object enables you to transfer data to and from the server without reloading or replacing the currentdocument.

To make an HTTP request, you create the instance of the object, open a URL, and send the request. The HTTP status code of theresult, 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 createextremely dynamic documents.

JavaScript Reference Object: XMLHttpRequest

326

XMLHttpRequest properties

Property name Type Description Status Availability

readyState unsigned

short

Returns the status of the server's response. Each time

the readyState property 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 4.6 or later

responseText String Returns the response text entity body. This might

return only a fragment of the entity body, if the request

response is still in the loading state.

read only 4.6 or later

responseXML String Returns the XML response entity body. This might

return only a fragment of the entity body, if the request

response is still in the loading state.

read only 4.6 or later

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 4.6 or later

JavaScript Reference Object: XMLHttpRequest

327

Property name Type Description Status Availability

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 4.6 or later

XMLHttpRequest event handlers

Property name Type Description Status Availability

onreadystatechange EventListen

er

Specifies the

function to perform

when a form control

loses focus after the

user has modified

the value.

writable 4.6 or later

XMLHttpRequest methods

Method name Description Availability

abort() Adds an EventListener object to a set of event listeners for the

window.

4.6 or later

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

given node.

4.6 or later

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

().

4.6 or later

getAllResponseHeaders() Returns a complete set of headers and their values. 4.6 or later

getResponseHeader() Returns the value of the given header. 4.6 or later

open() Assigns the HTTP method and destination URL, as well as some

additional optional parameters, for a pending request.

4.6 or later

removeEventListener() Removes an event listener from an EventTarget. 4.6 or later

send() Sends the request to the URL specified by

XMLHttpRequest.open().

4.6 or later

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

JavaScript Reference Object: XMLHttpRequest

328

Method: XMLHttpRequest.abort()

Availability BlackBerry® Device Software version 4.6 or later

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

ParametersNone.

Return valuesNone.

ExceptionsNone.

Method: XMLHttpRequest.addEventListener()

Availability BlackBerry® Device Software version 4.6 or later

The addEventListener() method adds an EventListener object to the XMLHttpRequest object.

SyntaxXMLHttpRequest.addEventListener( type, listener, useCapture )

Parameters

Parameter Type Description

type String The type of event to add.

listener EventListener The EventListener function to be invoked.

useCapture boolean When true, indicates all events of the specified type to the registered

EventListener before being dispatched to any EventTarget

objects beneath the given node in the tree. Bubbling events will not

trigger the EventListener.

JavaScript Reference Object: XMLHttpRequest

329

Parameter Type Description

When false, this method dispatches events of the specified type to

the registered EventListener before being dispatched to any

EventTarget objects above the given node in the tree.

Return valuesNone.

ExceptionsNone.

See alsoEvent , EventListener

Method: XMLHttpRequest.dispatchEvent()

Availability BlackBerry® Device Software version 4.6 or later

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

SyntaxXMLHttpRequest.dispatchEvent( event )

Parameters

Parameter Type Description

event Event The Event object to be dispatched.

Return valuesReturns true if the Event.preventDefault() was not called by any of the event listeners that handled the event. TheEvent.preventDefault() method prevents the default action for the event from occurring. Otherwise, returns false.

Exceptions

Exception Description

UNSPECIFIED_EVENT_TYPE_ERR This error is thrown if the event type was not specified by initializing the event

before calling dispatchEvent(), or if the event type was null.

JavaScript Reference Object: XMLHttpRequest

330

Method: XMLHttpRequest.getAllResponseHeaders()

Availability BlackBerry® Device Software version 4.6 or later

The getAllResponseHeaders() method returns a complete set of headers and their values.

SyntaxXMLHttpRequest.getAllResponseHeaders()

ParametersNone.

Return valuesReturns all the response headers as a single string, with each header separated by a carriage return and a line feed character.

Exceptions

Exception Description

INVALID_STATE_ERR This error is thrown if this method is called before any response headers have been

received (that is, before the XMLHttpRequest.readyState property has a value

of 2, indicating HEADERS_RECEIVED).

See alsoXMLHttpRequest.getResponseHeader()

Method: XMLHttpRequest.getResponseHeader()

Availability BlackBerry® Device Software version 4.6 or later

The getResponseHeader() method returns the value of a given header.

SyntaxXMLHttpRequest.getResponseHeader( header )

Parameters

JavaScript Reference Object: XMLHttpRequest

331

Parameter Type Description

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

Return valuesReturns the value of the given header, or null if the header is not present in the header list. If header matches more than oneheader in the list of response headers, the values are concatenated into a single comma-separated list.

Exceptions

Exception Description

INVALID_STATE_ERR This error is thrown if this method is called before any response headers have been

received (that is, before the XMLHttpRequest.readyState property has a value

of 2, indicating HEADERS_RECEIVED).

See alsoXMLHttpRequest.getAllResponseHeaders()

Method: XMLHttpResponse.open()

Availability BlackBerry® Device Software version 4.6 or later

The open() method assigns the HTTP method and destination URL, as well as some additional optional parameters, for apending request.

When this method is successfully invoked, the value for the XMLHttpRequest.readyState property is set to OPENED.

SyntaxXMLHttpRequest.open( method, url [, async] [, user] [, password] )

Parameters

Parameter Type Description

method String The HTTP method used to open the connection, This parameter may have

one of the following values:

• DELETE

• GET

• HEAD

JavaScript Reference Object: XMLHttpRequest

332

Parameter Type Description

• 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 property of the Document object reference that is created

when the XMLHttpRequest object is constructed.

async boolean Optional. When set to true, this parameter indicates that the request is

asynchronous. If no value is specified, a value of true is specified 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 is aborted.

Because of the variability of network speed and connection availability in a

wireless browsing 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 user authentication. If

this value is not specified and the destination URL requires the user to be

authenticated, the user will be prompted for their user credentials.

password String Optional. Specifies a password, if the server requires user authentication.

Return valuesNone.

Method: XMLHttpRequest.removeEventListener()

Availability BlackBerry® Device Software version 4.6 or later

The removeEventListener() method removes an event listener from an EventTarget.

Syntax

JavaScript Reference Object: XMLHttpRequest

333

XMLHttpRequest.removeEventListener( type, listener, useCapture )

Parameters

Parameter Type Description

type String The type of event.

listener EventListener The event listener function to be removed.

useCapture boolean When true, indicates that the EventListener being removed

was registered as a capturing listener.

A listener may be registered twice, once as a capturing listener, and

once as a non-capturing listener. Each must be removed separately.

Return valuesNone.

ExceptionsNone.

See alsoEvent , EventListener

Method: XMLHttpRequest.send()

Availability BlackBerry® Device Software version 4.6 or later

The send() method sends the request to the URL specified by XMLHttpRequest.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 calledonly after the request has been opened using XMLHttpRequest.open().

This method can pass data to the server either as a string of text or as a Document object.

If a value for the data parameter is specified, it becomes the entity body for the request. In order for the server to properlyhandle the data, you should specify the content type using XMLHttpRequest.setRequestHeader() before invoking thismethod.

If data is not specified, no entity body is sent with the request.

SyntaxXMLHttpRequest.send( [data] )

Parameters

JavaScript Reference Object: XMLHttpRequest

334

Parameter Type Description

data String | Document Optional. The data to send to the server.

If data is not a string or a Document object, the BlackBerry®

Browser attempts to convert it into a string before passing it on to

the server. If it is unable to do so, the request is sent as if data had

a null value.

Return valuesIf the request was asynchronous, this method returns the callback when the response has been successfully received.

Exceptions

Exception Description

ABORT_ERR This error is thrown if the request was 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 This error is thrown if there was a network error preventing the request from being

delivered to the destination URL, or if the destination URL is a redirection that violates

security or would result in an infinite loop.

See alsoXMLHttpRequest.open() , XMLHttpRequest.setRequestHeader()

Method: XMLHttpRequest.setRequestHeader()

Availability BlackBerry® Device Software version 4.6 or later

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

JavaScript Reference Object: XMLHttpRequest

335

Parameter Type Description

header String The header to set.

This parameter may not have as its value any of the following: Accept-

Charset, Accept-Encoding, Connection, Content-Length,

Content-Transfer-Encoding, Date, Expect, Host, Keep-Alive,

Referer, TE, Trailer, Transfer-Encoding, Upgrade, Via, or any

value starting with Proxy- or Sec-.

value String The value of the header.

Return valuesNone.

Exceptions

Exception Description

ABORT_ERR This error is thrown if the request was 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 This error is thrown if

• header is not recognized as a valid header name.

• value is not recognized as a valid header value.

See alsoXMLHttpRequest.open() , XMLHttpRequest.send()

Object: XMLSerializer

Availability BlackBerry® Device Software version 4.7.1 or later

The XMLSerializer object provides the serializeToString() method, which converts an XML document or subtreeinto a string.

JavaScript Reference Object: XMLSerializer

336

XMLSerializer methods

Method name Description Availability

serializeToString

()

Converts an XML document or subtree into a string. 4.7.1 or later

Method: XMLSerializer.serializeToString()

Availability BlackBerry® Device Software version 4.7.1 or later

The serialToString() method converts an XML document or subtree into a string.

SyntaxXMLSerializer.serializeToString( xmlDocument )

Parameters

Parameter Type Description

xmlDocument Node Specifies the XML document or subtree to convert.

Return valuesThis method returns a string representation of the given XML document or subtree.

Exceptions

Exception Description

TYPE_MISMATCH_ERR Thrown if xmlDocument is null.

Code sample: Converting a string into XML and back to a string againvar xmlString = "<?xml version='1.0' ?>\<root>\ <level1>\ <option>Option1</option>\ <option>Option2</option>\ <option>Option3</option>\ </level1>\</root>";

var parser = new DOMParser();

JavaScript Reference Object: XMLSerializer

337

var xmlDocument = parser.parseFromString( xmlString, "text/xml" );

var serializer = new XMLSerializer();var string = serializer.serializeToString( xmlDocument ); alert( string )

JavaScript Reference Object: XMLSerializer

338

Glossary 3

AJAXAsynchronous JavaScript® and XML

DESData Encryption Standard

DOMDocument Object Model

HTMLHypertext Markup Language

HTTPHypertext Transfer Protocol

HTTPSHypertext Transfer Protocol over Secure Sockets Layer

IPInternet Protocol

IPPPInternet Protocol Proxy Protocol

JSONJavaScript® Object Notation

LANlocal area network

MIMEMultipurpose Internet Mail Extensions

MPEGMoving Picture Experts Group

NTLMNT LAN Manager

PAPPush Access Protocol

JavaScript Reference Glossary

339

SSLSecure Sockets Layer

Triple DESTriple Data Encryption Standard

TCPTransmission Control Protocol

TLSTransport Layer Security

URIUniform Resource Identifier

WAPWireless Application Protocol

WLANwireless local area network

WMLWireless Markup Language

WTLSWireless Transport Layer Security

WTPWAP Transaction Protocol

XMLExtensible Markup Language

JavaScript Reference Glossary

340

Provide feedback 4

To provide feedback on this deliverable, visit www.blackberry.com/docsfeedback.

JavaScript Reference Provide feedback

341

Legal notice 5

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

ECMAScript is a trademark of Ecma International. Atom is a trademark of IETF Trust. iDEN is a trademark of Motorola, Inc.Kerberos is a trademark of the Massachusetts Institute of Technology. Netscape is a trademark of Netscape CommunicationCorporation. Java and JavaScript are trademarks of Sun Microsystems, Inc. Wi-Fi is a trademark of the Wi-Fi Alliance. All othertrademarks are the properties of their respective owners.

This documentation including all documentation incorporated by reference herein such as documentation provided or madeavailable 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 thisdocumentation. In order to protect RIM proprietary and confidential information and/or trade secrets, this documentation maydescribe some aspects of RIM technology in generalized terms. RIM reserves the right to periodically change information thatis 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 servicesincluding components and content such as content protected by copyright and/or third-party web sites (collectively the "ThirdParty 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 Servicesin 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, INCLUDINGWITHOUT LIMITATION, ANY CONDITIONS, ENDORSEMENTS, GUARANTEES, REPRESENTATIONS OR WARRANTIES OFDURABILITY, 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 DEALINGOR USAGE OF TRADE, OR RELATED TO THE DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-PERFORMANCEOF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED HEREIN, AREHEREBY EXCLUDED. YOU MAY ALSO HAVE OTHER RIGHTS THAT VARY BY STATE OR PROVINCE. SOME JURISDICTIONSMAY NOT ALLOW THE EXCLUSION OR LIMITATION OF IMPLIED WARRANTIES AND CONDITIONS. TO THE EXTENTPERMITTED BY LAW, ANY IMPLIED WARRANTIES OR CONDITIONS RELATING TO THE DOCUMENTATION TO THE EXTENTTHEY CANNOT BE EXCLUDED AS SET OUT ABOVE, BUT CAN BE LIMITED, ARE HEREBY LIMITED TO NINETY (90) DAYS FROMTHE 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 LIABLEFOR 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 REFERENCEDHEREIN INCLUDING WITHOUT LIMITATION ANY OF THE FOLLOWING DAMAGES: DIRECT, CONSEQUENTIAL, EXEMPLARY,

JavaScript Reference Legal notice

342

INCIDENTAL, INDIRECT, SPECIAL, PUNITIVE, OR AGGRAVATED DAMAGES, DAMAGES FOR LOSS OF PROFITS OR REVENUES,FAILURE TO REALIZE ANY EXPECTED SAVINGS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, LOSS OFBUSINESS OPPORTUNITY, OR CORRUPTION OR LOSS OF DATA, FAILURES TO TRANSMIT OR RECEIVE ANY DATA, PROBLEMSASSOCIATED 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 OFSUBSTITUTE GOODS, COSTS OF COVER, FACILITIES OR SERVICES, COST OF CAPITAL, OR OTHER SIMILAR PECUNIARYLOSSES, WHETHER OR NOT SUCH DAMAGES WERE FORESEEN OR UNFORESEEN, AND EVEN IF RIM HAS BEEN ADVISEDOF THE POSSIBILITY OF SUCH DAMAGES.

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

THE LIMITATIONS, EXCLUSIONS, AND DISCLAIMERS HEREIN SHALL APPLY: (A) IRRESPECTIVE OF THE NATURE OF THECAUSE 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 BREACHESOR 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 AIRTIMESERVICE PROVIDERS), AUTHORIZED RIM DISTRIBUTORS (ALSO INCLUDING AIRTIME SERVICE PROVIDERS) AND THEIRRESPECTIVE 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 LIABILITYARISING 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 yourairtime service provider has agreed to support all of their features. Some airtime service providers might not offer Internet browsingfunctionality with a subscription to the BlackBerry® Internet Service. Check with your service provider for availability, roamingarrangements, service plans and features. Installation or use of Third Party Products and Services with RIM's products and servicesmay require one or more patent, trademark, copyright, or other licenses in order to avoid infringement or violation of third partyrights. You are solely responsible for determining whether to use Third Party Products and Services and if any third party licensesare required to do so. If required you are responsible for acquiring them. You should not install or use Third Party Products andServices until all necessary licenses have been acquired. Any Third Party Products and Services that are provided with RIM'sproducts 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 relationthereto. Your use of Third Party Products and Services shall be governed by and subject to you agreeing to the terms of separatelicenses and other agreements applicable thereto with third parties, except to the extent expressly covered by a license or otheragreement with RIM.

Certain features outlined in this documentation require a minimum version of BlackBerry® Enterprise Server, BlackBerry® DesktopSoftware, and/or BlackBerry® Device Software.

JavaScript Reference Legal notice

343

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 WARRANTIESPROVIDED BY RIM FOR PORTIONS OF ANY RIM PRODUCT OR SERVICE OTHER THAN THIS DOCUMENTATION.

Research In Motion Limited295 Phillip StreetWaterloo, ON N2L 3W8Canada

Research In Motion UK Limited Centrum House 36 Station Road Egham, Surrey TW20 9LF United Kingdom

Published in Canada

JavaScript Reference Legal notice

344