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:
["[email protected]", "[email protected]"]
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":[ "[email protected]", "[email protected]" ] "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