BlackBerry Browser

Version: 5.0

JavaScript Reference

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

Contents
1 JavaScript reference overview................................................................................................................................................... Supported JavaScript objects: Alphabetical................................................................................................................................ A................................................................................................................................................................................................ B................................................................................................................................................................................................ C................................................................................................................................................................................................ D............................................................................................................................................................................................... E................................................................................................................................................................................................ H............................................................................................................................................................................................... K................................................................................................................................................................................................ L................................................................................................................................................................................................ M............................................................................................................................................................................................... N............................................................................................................................................................................................... P................................................................................................................................................................................................ R................................................................................................................................................................................................ S................................................................................................................................................................................................ T................................................................................................................................................................................................ U............................................................................................................................................................................................... W............................................................................................................................................................................................... X................................................................................................................................................................................................ 18 18 18 18 18 19 20 20 23 23 23 24 24 25 25 25 26 26 26 27 27 27 28 28 29 29 30 30 31 31 33 35 36

2 JavaScript objects........................................................................................................................................................................ Object: Attr...................................................................................................................................................................................... Attr properties......................................................................................................................................................................... Object: blackberry........................................................................................................................................................................... blackberry properties............................................................................................................................................................. Object: blackberry.launch.............................................................................................................................................................. blackberry.launch methods................................................................................................................................................... Method: blackberry.launch.launchCamera()....................................................................................................................... Method: blackberry.launch.launchVideoRecorder().......................................................................................................... Method: blackberry.launch.launchVoicemail()................................................................................................................... Method: blackberry.launch.newAppointment().................................................................................................................. Method: blackberry.launch.newContact()........................................................................................................................... Method: blackberry.launch.newMap()................................................................................................................................. Method: blackberry.launch.newMemo()..............................................................................................................................

Method: blackberry.launch.newPhoneCall()....................................................................................................................... Method: blackberry.launch.newSMS()................................................................................................................................. Method: blackberry.launch.newTask()................................................................................................................................. JSON Object: Address........................................................................................................................................................... Object: blackberry.location............................................................................................................................................................ blackberry.location properties.............................................................................................................................................. blackberry.location methods................................................................................................................................................. Method: blackberry.location.onLocationUpdate()............................................................................................................. Method: blackberry.location.refreshLocation()................................................................................................................... Method: blackberry.location.removeLocationUpdate()..................................................................................................... Method: blackberry.location.setAidMode()......................................................................................................................... Object: CDATASection................................................................................................................................................................... Object: CharacterData................................................................................................................................................................... CharacterData properties...................................................................................................................................................... CharacterData methods........................................................................................................................................................ Method: CharacterData.appendData()............................................................................................................................... Method: CharacterData.deleteData().................................................................................................................................. Method: CharacterData.insertData()................................................................................................................................... Method: CharacterData.replaceData()................................................................................................................................ Method: CharacterData.substringData()............................................................................................................................ Object: Comment............................................................................................................................................................................ Object: Counter............................................................................................................................................................................... Counter properties................................................................................................................................................................. Object: CSSCharsetRule................................................................................................................................................................ CSSCharsetRule properties................................................................................................................................................... Object: CSSFontFaceRule.............................................................................................................................................................. CSSFontFaceRule properties................................................................................................................................................. Object: CSSImportRule.................................................................................................................................................................. CSSImportRule properties..................................................................................................................................................... Object: CSSMediaRule................................................................................................................................................................... CSSMediaRule properties...................................................................................................................................................... CSSMediaRule methods........................................................................................................................................................ Method: CSSMediaRule.deleteRule().................................................................................................................................. Method: CSSMediaRule.insertRule()................................................................................................................................... Object: CSSPageRule.....................................................................................................................................................................

37 38 38 40 40 41 42 42 43 44 44 45 46 46 46 47 47 48 49 50 50 51 51 51 51 52 52 52 52 53 53 53 53 54 55

CSSPageRule properties........................................................................................................................................................ Object: CSSPrimitiveValue............................................................................................................................................................ CSSPrimitiveValue properties............................................................................................................................................... CSSPrimitiveValue methods.................................................................................................................................................. Method: CSSPrimitiveValue.getCounterValue()................................................................................................................. Method: CSSPrimitiveValue.getFloatValue()...................................................................................................................... Method: CSSPrimitiveValue.getRectValue()....................................................................................................................... Method: CSSPrimitiveValue.getRGBColorValue().............................................................................................................. Method: getStringValue()...................................................................................................................................................... Method: CSSPrimitiveValue.setFloatValue()....................................................................................................................... Method: CSSPrimitiveValue.setStringValue()..................................................................................................................... Object: CSSRule.............................................................................................................................................................................. CSSRule properties................................................................................................................................................................. Object: CSSRuleList........................................................................................................................................................................ CSSRuleList properties........................................................................................................................................................... CSSRuleList methods............................................................................................................................................................. Method: CSSRuleList.item().................................................................................................................................................. Object: CSSStyleDeclaration......................................................................................................................................................... CSSStyleDeclaration properties........................................................................................................................................... CSSStyleDeclaration methods.............................................................................................................................................. Method: CSSStyleDeclaration.getPropertyPriority().......................................................................................................... Method: CSSStyleDeclaration.getPropertyCSSValue()..................................................................................................... Method: CSSStyleDeclaration.getPropertyValue()............................................................................................................ Method: CSSStyleDeclaration.item()................................................................................................................................... Method: CSSStyleDeclaration.removeProperty()............................................................................................................... Method: CSSStyleDeclaration.setProperty()....................................................................................................................... Object: CSSStyleRule..................................................................................................................................................................... CSSStyleRule properties........................................................................................................................................................ Object: CSSStyleSheet................................................................................................................................................................... CSSStyleSheet properties...................................................................................................................................................... CSSStyleSheet methods........................................................................................................................................................ Method: CSSStyleSheet.deleteRule()................................................................................................................................... Method: CSSStyleSheet.insertRule().................................................................................................................................... Object: CSSUnknownRule............................................................................................................................................................. Object: CSSValue............................................................................................................................................................................

55 55 56 57 58 58 60 61 62 62 64 65 66 66 67 67 67 68 68 73 73 74 75 75 76 76 77 77 78 78 78 78 79 80 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....................................................................................................................................................... DOMImplementation methods............................................................................................................................................. Method: DOMImplementation.createCSSStyleSheet()..................................................................................................... Method: DOMImplementation.createDocument()............................................................................................................ Method: DOMImplementation.createDocumentType().................................................................................................... Method: DOMImplementation.hasFeature()...................................................................................................................... Object: DOMParser........................................................................................................................................................................ DOMParser methods............................................................................................................................................................. Method: DOMParser.parseFromString()............................................................................................................................. Object: Element.............................................................................................................................................................................. Element properties................................................................................................................................................................. Element methods.................................................................................................................................................................... Method: Element.getAttribute()........................................................................................................................................... Method: Element.getAttributeNode().................................................................................................................................. Method: Element.getAttributeNodeNS()............................................................................................................................ Method: Element.getAttributeNS()...................................................................................................................................... Method: Element.getElementsByTagName()...................................................................................................................... Method: Element.getElementsByTagNameNS()................................................................................................................ Method: Element.hasAttribute()........................................................................................................................................... Method: Element.hasAttributeNS()..................................................................................................................................... Method: Element.removeAttribute().................................................................................................................................... Method: Element.removeAttributeNode()........................................................................................................................... Method: Element.removeAttributeNS()............................................................................................................................... Method: Element.setAttribute()............................................................................................................................................ Method: Element.setAttributeNode().................................................................................................................................. Method: Element.setAttributeNodeNS()............................................................................................................................. Method: setAttributeNS()...................................................................................................................................................... Object: Entity................................................................................................................................................................................... Entity properties..................................................................................................................................................................... Object: EntityReference................................................................................................................................................................. Object: Event................................................................................................................................................................................... Event properties...................................................................................................................................................................... Event methods........................................................................................................................................................................ Method: Event.initEvent()...................................................................................................................................................... Method: Event.preventDefault()...........................................................................................................................................

104 104 105 105 106 107 108 108 109 110 110 110 111 112 112 113 114 115 116 116 117 118 119 120 120 121 122 123 124 124 124 125 125 126 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........................................................................................................................................ Object: HTMLDirectoryElement.................................................................................................................................................... HTMLDirectoryElement properties....................................................................................................................................... Object: HTMLDivElement.............................................................................................................................................................. HTMLDivElement properties................................................................................................................................................. Object: HTMLDListElement........................................................................................................................................................... HTMLDListElement properties.............................................................................................................................................. Object: HTMLDocument................................................................................................................................................................ HTMLDocument properties................................................................................................................................................... HTMLDocument event handlers........................................................................................................................................... HTMLDocument methods..................................................................................................................................................... Method: HTMLDocument.close()......................................................................................................................................... Method: HTMLDocument.getElementByName()............................................................................................................... Method: HTMLDocument.open().......................................................................................................................................... Method: HTMLDocument.write()......................................................................................................................................... Method: HTMLDocument.writeln()...................................................................................................................................... Object: HTMLElement.................................................................................................................................................................... HTMLElement properties....................................................................................................................................................... HTMLElement event handlers............................................................................................................................................... Object: HTMLFieldsetElement...................................................................................................................................................... HTMLFieldsetElement properties......................................................................................................................................... Object: HTMLFontElement............................................................................................................................................................ HTMLFontElement properties............................................................................................................................................... Object: HTMLFormElement........................................................................................................................................................... HTMLFormElement properties.............................................................................................................................................. HTMLFormElement methods................................................................................................................................................ Method: HTMLFormElement.item()..................................................................................................................................... Method: HTMLFormElement.namedItem()......................................................................................................................... Method: HTMLFormElement.reset()..................................................................................................................................... Method: HTMLFormElement.submit()................................................................................................................................. Object: HTMLFrameElement......................................................................................................................................................... HTMLFrameElement properties............................................................................................................................................ Object: HTMLFrameSetElement................................................................................................................................................... HTMLFrameSetElement properties...................................................................................................................................... Object: HTMLHeadElement...........................................................................................................................................................

141 141 142 142 142 142 143 143 143 145 146 147 147 148 149 149 150 151 152 154 154 154 155 155 155 156 156 157 158 158 159 159 159 160 160

HTMLHeadElement properties............................................................................................................................................. Object: HTMLHeadingElement..................................................................................................................................................... HTMLHeadingElement properties........................................................................................................................................ Object: HTMLHRElement............................................................................................................................................................... HTMLHRElement properties................................................................................................................................................. Object: HTMLHtmlElement........................................................................................................................................................... HTMLHtmlElement properties.............................................................................................................................................. Object: HTMLIFrameElement........................................................................................................................................................ HTMLIFrameElement properties........................................................................................................................................... Object: HTMLImageElement......................................................................................................................................................... HTMLImageElement properties............................................................................................................................................ Object: HTMLInputElement........................................................................................................................................................... HTMLInputElement properties............................................................................................................................................. HTMLInputElement methods................................................................................................................................................ Method: HTMLInputElement.blur()...................................................................................................................................... Method: HTMLInputElement.click()..................................................................................................................................... Method: HTMLInputElement.focus().................................................................................................................................... Method: HTMLInputElement.select()................................................................................................................................... Method: HTMLInputElement.stepDown()........................................................................................................................... Method: HTMLInputElement.stepUp()................................................................................................................................ Object: HTMLIsIndexElement....................................................................................................................................................... HTMLIsIndexElement properties.......................................................................................................................................... Object: HTMLLabelElement........................................................................................................................................................... HTMLLabelElement properties............................................................................................................................................. Object: HTMLLegendElement....................................................................................................................................................... HTMLLegendElement properties.......................................................................................................................................... Object: HTMLLIElement................................................................................................................................................................. HTMLIElement properties...................................................................................................................................................... Object: HTMLLinkElement............................................................................................................................................................. HTMLLinkElement properties................................................................................................................................................ Object: HTMLMapElement............................................................................................................................................................ HTMLMapElement properties............................................................................................................................................... Object: HTMLMenuElement.......................................................................................................................................................... HTMLMenuElement properties............................................................................................................................................. Object: HTMLMetaElement...........................................................................................................................................................

160 160 161 161 161 161 162 162 162 163 163 164 164 167 167 168 168 169 169 170 170 171 171 171 172 172 172 173 173 173 174 174 175 175 175

HMTLMetaElement properties.............................................................................................................................................. Object: HTMLModElement............................................................................................................................................................ HTMLModElement properties............................................................................................................................................... Object: HTMLObjectElement........................................................................................................................................................ HTMLObjectElement properties........................................................................................................................................... Object: HTMLOListElement........................................................................................................................................................... HTMLOListElement properties............................................................................................................................................. Object: HTMLOptGroupElement.................................................................................................................................................. HTMLOptGroupElement properties..................................................................................................................................... Object: HTMLOptionElement........................................................................................................................................................ HTMLOptionElement properties.......................................................................................................................................... Object: HTMLOptionsCollection................................................................................................................................................... HTMLOptionsCollection properties..................................................................................................................................... HTMLOptionsCollection methods........................................................................................................................................ Method: HTMLOptionsCollection.item()............................................................................................................................. Method: HTMLOptionsCollection.namedItem()................................................................................................................. Method: HTMLOptionsCollection.item()............................................................................................................................. Method: HTMLOptionsCollection.namedItem()................................................................................................................. Object: HTMLParagraphElement.................................................................................................................................................. HTMLParagraphElement properties.................................................................................................................................... Object: HTMLParamElement......................................................................................................................................................... HTMLParamElement properties........................................................................................................................................... Object: HTMLPreElement.............................................................................................................................................................. HTMLPreElement properties................................................................................................................................................. Object: HTMLQuoteElement......................................................................................................................................................... HTMLQuoteElement properties............................................................................................................................................ Object: HTMLScriptElement.......................................................................................................................................................... HTMLScriptElement properties............................................................................................................................................. Object: HTMLSelectElement......................................................................................................................................................... HTMLSelectElement properties............................................................................................................................................ Methods................................................................................................................................................................................... Method: HTMLSelectElement.add()..................................................................................................................................... Method: HTMLSelectElement.blur()..................................................................................................................................... Method: HTMLSelectElement.focus().................................................................................................................................. Method: HTMLSelectElement.remove()...............................................................................................................................

175 176 176 176 176 178 178 178 178 179 179 179 180 180 180 181 182 182 183 183 184 184 184 185 185 185 185 186 186 187 188 188 189 190 190

Object: HTMLStyleElement........................................................................................................................................................... HTMLStyleElement properties.............................................................................................................................................. Object: HTMLTableCaptionElement............................................................................................................................................. HTMLTableCaptionElement properties................................................................................................................................ Object: HTMLTableCellElement.................................................................................................................................................... HTMLTableCellElement properties....................................................................................................................................... Object: HTMLTableColElement..................................................................................................................................................... HTMLTableColElement properties........................................................................................................................................ Object: HTMLTableElement........................................................................................................................................................... HTMLTableElement properties............................................................................................................................................. HTMLTableElement methods................................................................................................................................................ Method: HTMLTableElement.createCaption().................................................................................................................... Method: HTMLTableElement.createTFoot()........................................................................................................................ Method: HTMLTableElement.createTHead()...................................................................................................................... Method: HTMLTableElement.deleteCaption().................................................................................................................... Method: HTMLTableElement.deleteRow().......................................................................................................................... Method: HTMLTableElement.deleteTFoot()........................................................................................................................ Method: HTMLTableElement.deleteTHead()...................................................................................................................... Method: HTMLTableElement.insertRow()........................................................................................................................... Object: HTMLTableRowElement................................................................................................................................................... HTMLTableRowElement properties...................................................................................................................................... HTMLTableRowElement methods........................................................................................................................................ Method: HTMLTableRowElement.deleteCell().................................................................................................................... Method: HTMLTableRowElement.insertCell()..................................................................................................................... Object: HTMLTableSectionElement.............................................................................................................................................. HTMLTableSectionElement properties................................................................................................................................ HTMLTableSectionElement methods................................................................................................................................... Method: HTMLTableSectionElement.deleteRow()............................................................................................................. Method: HTMLTableSectionElement.insertRow().............................................................................................................. Object: HTMLTextAreaElement..................................................................................................................................................... HTMLTextAreaElement properties....................................................................................................................................... HTMLTextAreaElement methods.......................................................................................................................................... Method: HTMLTextAreaElement.blur()................................................................................................................................ Method: HTMLTextAreaElement.focus()............................................................................................................................. Method: HTMLTextAreaElement.select()............................................................................................................................

191 191 191 191 192 192 193 193 194 194 195 196 196 197 197 198 198 199 199 200 200 201 201 202 203 203 203 204 204 205 205 206 207 207 208

Object: HTMLTitleElement............................................................................................................................................................. HTMLTitleElement properties............................................................................................................................................... Object: HTMLUListElement........................................................................................................................................................... HTMLUListElement properties.............................................................................................................................................. Object: KeyboardEvent.................................................................................................................................................................. KeyboardEvent properties..................................................................................................................................................... Keyboard event types............................................................................................................................................................. KeyboardEvent methods........................................................................................................................................................ Method: KeyboardEvent.getModifierState()....................................................................................................................... Method: KeyboardEvent.initKeyboardEvent()..................................................................................................................... Method: KeyboardEvent.initKeyboardEventNS()............................................................................................................... Object: Location.............................................................................................................................................................................. Location properties................................................................................................................................................................. Location methods................................................................................................................................................................... Method: location.assign()...................................................................................................................................................... Method: location.reload()...................................................................................................................................................... Method: location.replace().................................................................................................................................................... Method: location.toString()................................................................................................................................................... Object: MediaList............................................................................................................................................................................ MediaList properties.............................................................................................................................................................. MediaList methods................................................................................................................................................................. Method: MediaList.appendMedium().................................................................................................................................. Method: MediaList.deleteMedium()..................................................................................................................................... Method: MediaList.item()...................................................................................................................................................... Object: MimeType........................................................................................................................................................................... MimeType properties............................................................................................................................................................. Object: MimeTypeArray................................................................................................................................................................. MimeTypeArray properties.................................................................................................................................................... MimeTypeArray methods....................................................................................................................................................... Method: MimeTypeArray.item()............................................................................................................................................ Method: MimeTypeArray.namedItem()............................................................................................................................... Object: MouseEvent....................................................................................................................................................................... MouseEvent properties.......................................................................................................................................................... Mouse event types.................................................................................................................................................................. MouseEvent methods.............................................................................................................................................................

208 208 208 209 209 209 210 211 211 211 213 214 214 215 215 216 217 217 218 218 218 219 219 220 221 221 221 221 222 222 222 223 223 224 226

Method: MouseEvent.initMouseEvent().............................................................................................................................. Object: MutationEvent................................................................................................................................................................... MutationEvent properties...................................................................................................................................................... Mutation event types............................................................................................................................................................. MutationEvent methods........................................................................................................................................................ Method: MutationEvent.initMutationEvent()...................................................................................................................... Object: NamedFrameMap............................................................................................................................................................. NamedFrameMap properties................................................................................................................................................ NamedFrameMap methods.................................................................................................................................................. Method: NamedFrameMap.item()....................................................................................................................................... Method: NamedFrameMap.getNamedItem()..................................................................................................................... Object: NamedNodeMap............................................................................................................................................................... NamedNodeMap properties................................................................................................................................................. NamedNodeMap methods.................................................................................................................................................... Method: NamedNodeMap.getNamedItem()...................................................................................................................... Method: NamedNodeMap.getNamedItemNS()................................................................................................................. Method: NamedNodeMap.item()......................................................................................................................................... Method: NamedNodeMap.removeNamedItem()............................................................................................................... Method: NamedNodeMap.removeNamedItemNS().......................................................................................................... Method: NamedNodeMap.setNamedItem()....................................................................................................................... Method: NamedNodeMap.setNamedItemNS()................................................................................................................. Object: Navigator........................................................................................................................................................................... Navigator properties.............................................................................................................................................................. Navigator methods................................................................................................................................................................. Method: navigator.javaEnabled()......................................................................................................................................... Object: Node................................................................................................................................................................................... Node properties...................................................................................................................................................................... Node methods........................................................................................................................................................................ Method: Node.removeEventListener()................................................................................................................................. Method: Node.removeChild()............................................................................................................................................... Method: Node.replaceChild()............................................................................................................................................... Method: Node.normalize().................................................................................................................................................... Method: Node.addEventListener()....................................................................................................................................... Method: Node.appendChild()............................................................................................................................................... Method: Node.cloneNode()..................................................................................................................................................

226 228 228 229 230 230 232 232 232 233 233 234 234 235 235 236 236 237 238 238 239 240 241 242 242 242 243 244 245 246 247 248 248 249 250

Method: Node.dispatchEvent()............................................................................................................................................. Method: Node.hasAttributes().............................................................................................................................................. Method: Node.hasChildNodes()........................................................................................................................................... Method: Node.insertBefore()................................................................................................................................................ Method: Node.isSupported()................................................................................................................................................ Object: NodeFilter.......................................................................................................................................................................... NodeFilter methods............................................................................................................................................................... Method: NodeFilter.acceptNode()....................................................................................................................................... Object: NodeList............................................................................................................................................................................. NodeList properties................................................................................................................................................................ NodeList methods.................................................................................................................................................................. Method: NodeList.item()....................................................................................................................................................... Object: Notation............................................................................................................................................................................. Notation properties................................................................................................................................................................ Object: NodeIterator...................................................................................................................................................................... NodeIterator properties......................................................................................................................................................... NodeIterator methods........................................................................................................................................................... Method: NodeIterator.detach()............................................................................................................................................ Method: NodeIterator.nextNode()....................................................................................................................................... Method: NodeIterator.previousNode()................................................................................................................................ Object: Plugin.................................................................................................................................................................................. Plugin properties.................................................................................................................................................................... Plugin methods....................................................................................................................................................................... Method: Plugin.item()............................................................................................................................................................ Method: Plugin.namedItem()................................................................................................................................................ Object: PluginArray........................................................................................................................................................................ PluginArray properties........................................................................................................................................................... PluginArray methods............................................................................................................................................................. Method: PluginArray.item()................................................................................................................................................... Method: PluginArray.namedItem()...................................................................................................................................... Object: ProcessingInstruction....................................................................................................................................................... ProcessingInstruction properties.......................................................................................................................................... Object: Range.................................................................................................................................................................................. Range properties.................................................................................................................................................................... Range methods.......................................................................................................................................................................

251 252 252 253 254 255 255 255 256 256 257 257 257 258 258 258 260 260 260 261 262 262 262 263 263 264 264 264 264 265 265 266 266 267 267

Method: Range.cloneContents().......................................................................................................................................... Method: Range.cloneRange()............................................................................................................................................... Method: Range.collapse()..................................................................................................................................................... Method: Range.compareBoundaryPoints()......................................................................................................................... Method: Range.deleteContents()......................................................................................................................................... Method: Range.detach()........................................................................................................................................................ Method: Range.extractContents()........................................................................................................................................ Method: Range.insertNode()................................................................................................................................................ Method: Range.selectNodeContents()................................................................................................................................ Method: Range.selectNode()................................................................................................................................................ Method: Range.setEndAfter()............................................................................................................................................... Method: Range.setEndBefore()............................................................................................................................................ Method: Range.setEnd()........................................................................................................................................................ Method: Range.setStartAfter()............................................................................................................................................. Method: Range.setStartBefore()........................................................................................................................................... Method: Range.setStart()...................................................................................................................................................... Method: Range.surroundContents().................................................................................................................................... Method: Range.toString()...................................................................................................................................................... Object: Rect..................................................................................................................................................................................... Rect properties........................................................................................................................................................................ Object: RGBColor............................................................................................................................................................................ RGBColor properties.............................................................................................................................................................. Object: Screen................................................................................................................................................................................. Screen properties................................................................................................................................................................... Object: Selection............................................................................................................................................................................. Selection properties............................................................................................................................................................... Selection methods.................................................................................................................................................................. Method: Selection.addRange()............................................................................................................................................. Method: Selection.collapseToEnd()...................................................................................................................................... Method: Selection.collapseToStart().................................................................................................................................... Method: Selection.collapse()................................................................................................................................................. Method: Selection.deleteFromDocument()......................................................................................................................... Method: Selection.getRangeAt().......................................................................................................................................... Method: Selection.removeAllRanges()................................................................................................................................ Method: Selection.removeRange().......................................................................................................................................

268 269 269 270 271 272 272 273 274 275 275 276 277 278 278 279 280 281 281 282 282 282 283 283 283 284 284 285 285 286 286 287 287 288 288

Method: Selection.selectAllChildren()................................................................................................................................. Object: StyleSheet.......................................................................................................................................................................... StyleSheet properties............................................................................................................................................................. Object: StyleSheetList.................................................................................................................................................................... StyleSheetList properties....................................................................................................................................................... StyleSheetList methods......................................................................................................................................................... Method: StyleSheetList.item().............................................................................................................................................. Object: Text..................................................................................................................................................................................... Text methods........................................................................................................................................................................... Method: Text.splitText()......................................................................................................................................................... Object: TextEvent............................................................................................................................................................................ TextEvent properties.............................................................................................................................................................. Text event types...................................................................................................................................................................... TextEvent methods................................................................................................................................................................. Method: TextEvent.initTextEvent()....................................................................................................................................... Method: TextEvent.initTextEventNS().................................................................................................................................. Object: TreeWalker......................................................................................................................................................................... TreeWalker properties............................................................................................................................................................ TreeWalker methods............................................................................................................................................................... Method: TreeWalker.firstChild()........................................................................................................................................... Method: TreeWalker.lastChild()............................................................................................................................................ Method: TreeWalker.nextNode().......................................................................................................................................... Method: TreeWalker.nextSibling()........................................................................................................................................ Method: TreeWalker.parentNode()...................................................................................................................................... Method: TreeWalker.previousNode()................................................................................................................................... Method: TreeWalker.previousSibling()................................................................................................................................. Object: UIEvent............................................................................................................................................................................... UIEvent properties................................................................................................................................................................. User interface events............................................................................................................................................................. UIEvent methods.................................................................................................................................................................... Method: UIEvent.initUIEvent()............................................................................................................................................. Object: Window............................................................................................................................................................................... Window properties.................................................................................................................................................................. Window event handlers.......................................................................................................................................................... Window methods....................................................................................................................................................................

289 289 289 291 292 292 292 293 293 293 294 294 294 295 295 295 296 297 298 299 299 300 300 301 301 302 302 302 303 303 303 304 304 306 310

Method: window.addEventListener()................................................................................................................................... Method: window.alert()......................................................................................................................................................... Method: window.back()......................................................................................................................................................... Method: window.blur()........................................................................................................................................................... Method: window.close()......................................................................................................................................................... Method: window.confirm().................................................................................................................................................... Method: window.dispatchEvent()......................................................................................................................................... Method: window.find()........................................................................................................................................................... Method: window.focus()........................................................................................................................................................ Method: window.forward().................................................................................................................................................... Method: window.getComputedStyle()................................................................................................................................. Method: window.home()........................................................................................................................................................ Method: window.moveBy().................................................................................................................................................... Method: window.moveTo().................................................................................................................................................... Method: window.open()......................................................................................................................................................... Method: window.print()......................................................................................................................................................... Method: window.prompt()..................................................................................................................................................... Method: window.removeEventListener()............................................................................................................................. Method: window.resizeBy()................................................................................................................................................... Method: window.resizeTo()................................................................................................................................................... Method: window.scroll()........................................................................................................................................................ Method: window.scrollBy().................................................................................................................................................... Method: window.scrollTo().................................................................................................................................................... Method: window.stop().......................................................................................................................................................... Object: XMLHttpRequest............................................................................................................................................................... XMLHttpRequest properties................................................................................................................................................. XMLHttpRequest event handlers......................................................................................................................................... XMLHttpRequest methods.................................................................................................................................................... Method: XMLHttpRequest.abort()........................................................................................................................................ Method: XMLHttpRequest.addEventListener()................................................................................................................... Method: XMLHttpRequest.dispatchEvent()........................................................................................................................ Method: XMLHttpRequest.getAllResponseHeaders()....................................................................................................... Method: XMLHttpRequest.getResponseHeader()............................................................................................................. Method: XMLHttpResponse.open()..................................................................................................................................... Method: XMLHttpRequest.removeEventListener()............................................................................................................

311 312 312 313 313 314 315 315 316 317 317 318 318 319 320 320 321 321 322 323 324 324 325 326 326 327 328 328 329 329 330 331 331 332 333

Method: XMLHttpRequest.send()........................................................................................................................................ Method: XMLHttpRequest.setRequestHeader()................................................................................................................. Object: XMLSerializer..................................................................................................................................................................... XMLSerializer methods.......................................................................................................................................................... Method: XMLSerializer.serializeToString()..........................................................................................................................

334 335 336 337 337

3 Glossary......................................................................................................................................................................................... 339 4 Provide feedback......................................................................................................................................................................... 341 5 Legal notice.................................................................................................................................................................................. 342

JavaScript Reference

JavaScript reference overview

JavaScript reference overview

Supported JavaScript objects: Alphabetical
A
Object
Attr

Description Represents an attribute of an Element object. C D E F G H I J K L M N O P Q R S T U V

Availability 4.6 or later W X Y Z

B
Object
blackberry blackberry. launch blackberry. location

Description

Availability

Provides network and global positioning information for a 3.8 or later BlackBerry device. Provides access to other BlackBerry applications on the 5.0 or later device. Provides access to the GPS location information for the 4.1 or later BlackBerry device. G H I J K L M N O P Q R S T U V W X Y Z

C
Object
CDATASection CharacterData

Description

Availability

Represents a block of escaped text, such as XML fragments, source code, 4.6 or later or other content that is otherwise interpreted as XML markup. Accesses character data in the DOM. 4.6 or later

18

JavaScript Reference

Supported JavaScript objects: Alphabetical

Object
Comment Counter CSSCharsetRule CSSFontFaceRule CSSImportRule CSSMediaRule CSSPageRule CSSPrimitiveValue CSSRule CSSRuleList CSSStyleDeclaration CSSStyleRule CSSStyleSheet CSSUnknownValue CSSValue CSSValueList CustomEvent

Description Represents the contents of a comment within a document. Represents any counter or counters function value. Represents an @charset rule, which holds an encoding definition. Represents an @font-face rule, which holds a set of font descriptions. Represents an @import rule, which imports style rules from other style sheets. Represents an @media rule, which defines style rules for a specific media type. Represents a @page rule, which specifies the dimensions, orientation, and margins for paged media. Represents a single CSS value. The base class that defines any rule in a CSS style sheet, including rule sets and @ rules. Represents an ordered collection of CSSRule objects. Represents a CSS declaration block that consists of CSS properties and their values. Represents a single rule set in a CSS style sheet. Represents a CSS style sheet. Represents an unsupported @ rule. Represents a simple or complex CSS property value. Represents an ordered collection of CSSValue objects. Represents an unknown event type, typically application-specific event types. G H I J K L M N O P Q R S T U V

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

D
Object
Document

Description

Availability

Represents the entire HTML or XML document. It acts as the root of the 4.6 or later tree, and provides the primary access to the data of the document.

19

JavaScript Reference

Supported JavaScript objects: Alphabetical

Object
DocumentFragment DocumentType DOMImplementation DOMParser

Description A lightweight Document object, that creates or extracts only part of a document. Represents the doctype for a document. If a document has a doctype, it will be a reference to this object. Defines the methods for performing the operations that are independent of any particular instance of the DOM, such as creating new documents. Enables you to parse strings into a DOM. G H I J K L M N O P Q R S T U V

Availability 4.6 or later 4.6 or later 4.6 or later 4.7.1 or later W X Y Z

E
Object
Element Entity EntityReference Event EventListener

Description Represents an element in an HTML or XML document. Represents any entity in an XML document. Represents a reference to an Entity object within the document. Provides contextual information about an event that event handlers can use. Represents an event listener that listens for and handles events as they occur. F G H I J K L M N O P Q R S T U V

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

H
Object
History HTMLAnchorElement HTMLAppletElement

Description Stores an array of the URLs that the user visited during the current browser session. Represents an <a> element in an HTML document. Represents an <applet> element in an HTML document.

Availability 4.6 or later 4.6 or later 4.6 or later

20

JavaScript Reference

Supported JavaScript objects: Alphabetical

Object
HTMLAreaElement

Description

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.7.1 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

Represents an <area> element in an HTML document. HTMLBaseElement Represents a <base> element in an HTML document. HTMLBaseFontElement Represent a <basefont> element in an HTML document. HTMLBodyElement Represents a <body> element in an HTML document. HTMLBRElement Represents a <br> element in an HTML document. HTMLButtonElement Represents a <button> element in an HTML document. HTMLCollection Contains an ordered collection of nodes, which are updated automatically when the underlying document is changed. HTMLDataListElement Represents a <datalist> element in an HTML document. HTMLDirectoryElement Represents a <dir> element in an HTML document. HTMLDivElement Represents a <div> element in an HTML document. HTMLDListElement Represents a <dl> element in an HTML document. HTMLDocument Provides access to the HTML hierarchy. HTMLElement The parent class of all HTML elements, which represents those HTML elements which support only core attributes. HTMLFieldsetElement Represents a <fieldset> element in an HTML document. HTMLFontElement Represents a <font> element in an HTML document. HTMLFormElement Represents a <form> element in an HTML document. HTMLFrameElement Represents a <frame> element in an HTML frameset. HTMLFrameSetElement Represents a <frameset> element in an HTML document. HTMLHeadElement Represents a <head> element in an HTML document. HTMLHeadingElement Represents a heading element (<h1> to <h6>) in an HTML document. HTMLHRElement Represents an <hr> element in an HTML document. HTMLHtmlElement Represents an <html> element in an HTML document. HTMLIFrameElement Represents an <iframe> element in an HTML document. HTMLImageElement Represents an <img> element in an HTML document. HTMLInputElement Represents an <input> element in an HTML document. HTMLIsIndexElement Represents an <isindex> element in an HTML document. HTMLLabelElement Represents a <label> element in an HTML document. HTMLLegendElement Represents a <legend> element in an HTML document. HTMLLIElement Represents an <li> element in an HTML document. HTMLLinkElement Represents a <link> element in an HTML document. HTMLMapElement Represents a <map> element in an HTML document.

21

JavaScript Reference

Supported JavaScript objects: Alphabetical

Object
HTMLMenuElement HTMLMetaElement HTMLModElement HTMLObjectElement HTMLOListElement HTMLOptGroupElement HTMLOptionElement HTMLOptionsCollecti on

Description Represents a <menu> element in an HTML document. Represents a <meta> element in an HTML document. Represents a <del> or <ins> element in an HTML document. Represents an <object> element in an HTML document. Represents an <ol> element in an HTML document. Represents an <optgroup> element in an HTML document. Represents an <option> element in an HTML document. Contains an array of HTMLOptionElement objects.

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later W X Y Z

HTMLParagraphElement Represents a <p> element in an HTML document. HTMLParamElement HTMLPreElement HTMLQuoteElement HTMLScriptElement HTMLSelectElement HTMLStyleElement HTMLTableCaptionEle ment HTMLTableCellElement Represents a <td> or <th> element in an HTML document. HTMLTableColElement HTMLTableElement HTMLTableRowElement HTMLTableSectionEle ment HTMLTextAreaElement HTMLTitleElement HTMLUListElement

Represents a <param> element in an HTML document. Represents a <pre> element in an HTML document. Represents a <blockquote> or <q> element in an HTML document. Represents a <script> element in an HTML document. Represents a <select> element in an HTML document. Represents a <style> element in an HTML document. Represents a <caption> element in an HTML document.

Represents a <col> or <colgroup> element in an HTML document. Represents a <table> element in an HTML document. Represents a <tr> element in an HTML document. Represents a <tbody>, <tfoot>, or <thead> element in an HTML document. Represents a <textarea> element in an HTML document. Represents a <title> element in an HTML document. Represents a <ul> element in an HTML document. G H I J K L M N O P Q R S T U V

22

JavaScript Reference

Supported JavaScript objects: Alphabetical

K
Object
KeyboardEvent

Description Represents an event generated by the BlackBerry device keyboard. E F G H I J K L M N O P Q R S T U V

Availability 4.6 or later W X Y Z

L
Object
Location

Description Accesses the URL of the web page that is currently displayed in the BlackBerry Browser. D E F G H I J K L M N O P Q R S T U V

Availability 4.6 or later

M
Object
MediaList MimeType MimeTypeArray MouseEvent MutationEvent

Description Represents an ordered collection of media. An empty list is equivalent to a list that contains a value of all. Represents a MIME type specification. Contains an ordered collection of MIME types. Represents an event that is generated by the BlackBerry device trackball, trackwheel, or touch screen. Represents an event that is generated when the structure of the document is modified. E F G H I J K L M N O P Q R S T U V

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

23

JavaScript Reference

Supported JavaScript objects: Alphabetical

N
Object
NamedFrameMap NamedNodeMap Navigator Node NodeFilter NodeIterator NodeList Notation

Description Represents a collection of frames that can be accessed by name. Represents a collection of nodes that can be accessed by name. Provides information about the version of the BlackBerry Browser. Represents a unique node within the DOM tree, and is the primary data type for the DOM. Specifies which nodes should be filtered when a document is traversed. Enables navigation up and down through a flat representation of the document tree. Contains an ordered collection of nodes. Represents a notation that is declared in a DTD. E F G H I J K L M N O P Q R S T U V

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later W X Y Z

P
Object
Plugin PluginArray ProcessingInstructi on

Description Represents an installed plug-in. Contains an ordered collection of Plugin objects. Represents a processing instruction for an XML document.

Availability 4.6 or later 4.6 or later 4.6 or later

24

JavaScript Reference

Supported JavaScript objects: Alphabetical

R
Object
Range

Description

Availability

Rect RGBColor

Represents a range of content between two boundary points, a start point 4.7.1 or later and an end point, in a Document, DocumentFragment, or Attr node. Represents a Rect value. 4.6 or later Represents an RGB color value. 4.6 or later 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
Screen Selection Stylesheet StylesheetList

Description Returns information about the dimensions and the color depth of the BlackBerry device display. Contains a Range object. Represents a single external or inline style sheet that is associated with a document. Represents an ordered collection of StyleSheet objects. F G H I J K L M N O P Q R S T U V

Availability 4.6 or later 4.7.1 or later 4.6 or later 4.6 or later W X Y Z

T
Object
Text TextEvent

Description

Availability

Represents the text contents of an element or attribute. 4.6 or later Represents an event that is generated by entering characters using the 4.6 or later BlackBerry keyboard or an input source such as a voice command.

25

JavaScript Reference

Supported JavaScript objects: Alphabetical

Object
TreeWalker

Description Enables you to navigate the document tree or subtree. E F G H I J K L M N O P Q R S T U V

Availability 4.6 or later W X Y Z

U
Object
UIEvent

Description Represents a UI event that is generated by user interaction with the trackwheel, trackball, touch screen, or keyboard on a BlackBerry device keyboard. D E F G H I J K L M N O P Q R S T U V

Availability 4.6 or later

W
Object
Window

Description Returns information about the browser window. C D E F G H I J K L M N O P Q R S T U V

Availability 3.8 or later W X Y Z

X
Object
XMLHttpRequest XMLSerializer

Description

Availability

Enables you to transfer data to and from a server without reloading or 4.6 or later replacing the current document. Enables you to convert a DOM document or a DOM subtree into a string. 4.7.1 or later F G H I J K L M N O P Q R S T U V W X Y Z

26

JavaScript Reference

JavaScript objects

JavaScript objects
Object: Attr
Availability Extends BlackBerry Device Software version 4.6 or later
Node

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

Attr properties
Property name
name

Type String

Description

Status

Availability 4.6 or later

ownerElement

Element

specified

boolean

Returns the name of the attribute. The value of the name read only property must be unique across all attributes attached to the same Element node. Returns the element node that this attribute is attached read only to. If the attribute is not yet attached to an element, the value of this property is null. When true, this property indicates that the value for the read only attribute has been explicitly set. If the attribute exists with a default value, this property has a value of false. Specifies the value of the attribute.

4.6 or later

4.6 or later

value

String

writable

4.6 or later

27

JavaScript Reference

Object: blackberry

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 BlackBerry device is running, and the global position of the BlackBerry device.

blackberry properties
Property name
location

Type
blackberry.loc ation

Description Returns a pointer to the

blackberry.location object.

Status read only

Availability 4.1 or later

network

String

This property is available for BlackBerry Device Software Version 4.1 or later. Returns the wireless network on which the read only BlackBerry device is communicating. The value may be one of:
3GPP CDMA iDEN Wi-Fi

4.0 or later

Multiple networks may be supported on a single BlackBerry device. If multiple networks are supported, they are returned as a commaseparated list. For example:
3GPP,Wi-Fi

28

JavaScript Reference

Object: blackberry.launch

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 through JavaScript. 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 the blackberry.launch object can open and create new items for an application, changes are not made to the application without confirmation from the user. For example, if you use the blackberry.launch object to make a phone call to a specific phone 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 open BlackBerry 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 JSON object are all optional. For example, you can specify an empty JSON object as the parameter to a method, as long as the JSON object (identified by the braces) is present. For example:
blackberry.launch.newMap({});

blackberry.launch methods
Method name
launchCamera()

Description

Availability 5.0 or later 5.0 or later 5.0 or later 5.0 or later 5.0 or later 5.0 or later 5.0 or later 5.0 or later 5.0 or later

Opens the Camera application. launchVideoRedorder() Opens the Video Camera application. launchVoicemail() Opens the Phone application to call the voice mail account that is associated with the BlackBerry device. newAppointment() Creates a new appointment in the Calendar application. newContact() Adds a new contact to the Contacts list. newMap() Opens the BlackBerry Maps application and displays the specified location. newMemo() Creates a new memo in the Memo application. newPhoneCall() Opens the phone application to call a specific phone number. newSMS() Creates a new SMS text message.

29

JavaScript Reference

Object: blackberry.launch

Method name
newTask()

Description Creates a new task in the Tasks application.

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

Syntax

blackberry.launch.launchCamera()

Parameters
None.

Return values
None.

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.

Syntax
blackberry.launch.launchVideoRecorder()

Parameters
None.

Return values

30

JavaScript Reference

Object: blackberry.launch

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.

Syntax

blackberry.launch.launchVoicemail()

Parameters
None.

Return values
None.

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 appointment before it is saved to the calendar.

Syntax

31

JavaScript Reference

Object: blackberry.launch

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

JSON object members

Member
summary location allDay start end freeBusy

Type String String Boolean Date Date integer

Description Briefly summarizes the reason for the appointment. This value is used to identify this appointment in the calendar. Specifies the location of the appointment. 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. Specifies the start time of the appointment. Specifies the end time of the appointment. 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 values
None.

Exceptions
None.

Code sample: Creating a new appointment for the calendar application

// Define the start and end times as JavaScript Date objects var 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

32

JavaScript Reference

Object: blackberry.launch

};

"note":"Refreshments will be served."

// Create a new appointment with the new JSON object as a parameter blackberry.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 contact before it is added to the contact list.

Syntax
blackberry.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
title firstName, lastName company jobTitle email

Type String String integer String array

Description Specifies the contact's title, such as Mr, Mrs, or Dr. Specify the contact's first name and last name. Specifies the organization that the contact belongs to. Specifies a job title for the contact. Specifies an array of email addresses for the contact. The array contains a comma-separated list of strings, each representing an email address. The contents of the array are enclosed in brackets. For example:
["email1@company1.com", "email2@company2.com"]

workPhone, workPhone2, homePhone, homePhone2, mobilePhone,

String

Specify assorted phone numbers for the contact.

33

JavaScript Reference

Object: blackberry.launch

Member
pagerPhone, faxPhone, otherPhone pin workAddress, homeAddress birthday, anniversary webpage user1, user2, user3, user4, note

Type

Description

String
Address

Date String String

Specifies a BlackBerry device PIN for the contact. Specify various addresses for the contact, represented by an Address JSON object. Specify important dates for the contact, represented by a JavaScript Date object. Specifies a web page for the contact. Specify additional information for the contact.

Return values
None.

Exceptions
None.

Code sample: Creating a new contact

var workAddress = { "address1":"295 Phillip Street", "city":"Waterloo", "country":"Canada", "stateProvince":"ON", "zipPostal":"N2L3WE" }; var bday = new Date(1978,3,22); var contactInfo={ "title":"Ms" "firstName":"Karen" "lastName":"Moser" "email":[ "too_cool@internet.com", "KM_2@work.com" ] "pin":"2100000A" "workAddress":workAddress "birthDay":bday }; blackberry.launch.newContact(contactInfo);

34

JavaScript Reference

Object: blackberry.launch

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 using one of three following ways: specify the latitude and longitude specify an address specify a location document

Syntax
blackberry.launch.newMap({ latitude, longitude })

OR
blackberry.launch.newMap({ address })

OR
blackberry.launch.newMap({ locationDocument })

JSON object members

Member
latitude

Type double

Description 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 43N, specify a value of 4,300,000. 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 80W, specify a value of -8,000,000. Specifies address information, represented by an Address JSON object. Specifies an XML location document. This XML structure is specific to BlackBerry Maps.

longitude

double

address locationDocument

Address

String

Return values
None.

Exceptions

35

JavaScript Reference

Object: blackberry.launch

None.

Code sample: Displaying a set of geographic coordinates in BlackBerry Maps

blackberry.launch.newMap({ "latitude":4346518, "longitude":-8052237 });

Code sample: Displaying an address in BlackBerry Maps

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

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

Syntax
blackberry.launch.newMemo({ title, note })

JSON object members

Member
title note

Type String String

Description Specifies the title for the memo. This value is used to identify this memo in the list of memo items in the memo application. Specifies the memo text.

Return values

36

JavaScript Reference

Object: blackberry.launch

None.

Code sample: Creating a new memo

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

Syntax
blackberry.launch.newPhoneCall({ dialString, smartDialing })

JSON object members

Member
dialString smartDialing

Type String Boolean

Description Specifies the phone number to call. The phone number is specified as a string and must be enclosed by quotation marks. 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 values
None.

Exceptions
None.

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>

37

JavaScript Reference

Object: blackberry.launch

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

Syntax
blackberry.launch.newSMS({ number, text })

JSON object members

Member
number text

Type String String

Description The number to send the SMS text message to. The number is specified as a string and must be enclosed by quotation marks. The text in the SMS text message to send to the specified number.

Return values
None.

Exceptions
None.

Code sample: Sending an SMS message

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

38

JavaScript Reference

Object: blackberry.launch

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

JSON object members

Member
summary status

Type String integer

Description Briefly summarizes the purpose of the task. This value is used to identify this task in the tasks application. 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 note

Date String

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

Return values
None.

Exceptions
None.

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 properties var taskProperties = { "summary":"Create new business proposal", "status":0, "priority":0,

39

JavaScript Reference

Object: blackberry.location

};

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

// create a new task with the new JSON object as a parameter blackberry.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.launch object.

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

JSON object members

Member
address1 address2 city stateProvince country zipPostal

Type String String String String String String

Description Specifies the street address. Specifies additional address information. Specifies the city that the address is located in. Specifies the state or province that the address is located in. Specifies the country that the address is located in. 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 the BlackBerry device. The GPS location refers to the geographical co-ordinates, latitude and longitude, of the BlackBerry device.

40

JavaScript Reference

Object: blackberry.location

blackberry.location properties
Property name
GPSSupported latitude

Type boolean double

Description

Status

Availability 4.1 or later 4.1 or later

When true, this property indicates that GPS positioning read only is supported by the BlackBerry device. Returns the current latitude, in degrees, of the read only 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

longitude

double

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

read only

4.1 or later

timestamp

unsigned long

the callback. Returns time (in milliseconds since epoch) at which the read only blackberry.location object was updated. This property is only supported on BlackBerry devices running BlackBerry Device Software version 4.6 or later.

4.6 or later

41

JavaScript Reference

Object: blackberry.location

blackberry.location methods
Method name
onLocationUpdate() refreshLocation() removeLocationUpdate () setAidMode()

Description Registers a callback method that is called when the location is updated using blackberry.location.refreshLocation(). Requests an update of the location of the BlackBerry device. Removes a previously registered callback method. Specifies which method the BlackBerry device will use to obtain the GPS location.

Availability 4.1 or later 4.1 or later 4.6 or later 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 as a string that is evaluated each time the location is refreshed. On BlackBerry devices running BlackBerry Device Software version 4.6 or later, you can pass a string, or use the method to register a callback function. Once onlocationUpdate() has been invoked, the callback occurs whenever there is an update to the location information. This can be as frequent as once every several seconds. If you have passed the method a function, you can cancel the callback using blackberry.location.removeLocationUpdate() . If you have passed a string, the callback cannot be removed.

Syntax
blackberry.location.onLocationUpdate( callbackFunction | callbackString )

Parameters
Parameter
callbackFunction

Type Function

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

42

JavaScript Reference

Object: blackberry.location

Parameter
callbackString

Type String

Description A string to be evaluated when the location information is updated.

Return values
None.

Exceptions
None.

See also
blackberry.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. To ensure that location information is updated before reading it, you should first register a listener using blackberry.location.onLocationUpdate() that reads blackberry.location.latitude and blackberry.location.longitude , and then call refreshLocation() afterwards.

Syntax

blackberry.location.refreshLocation()

Parameters
None.

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

Exceptions
None.

See also
blackberry.location.onLocationUpdate() , blackberry.location.removeLocationUpdate()

43

JavaScript Reference

Object: blackberry.location

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.

Syntax

blackberry.location.removeLocationUpdate( callbackFunction )

Parameters
Parameter
callbackFunction

Type Function

Description A JavaScript function previously registered by

blackberry.location.onLocationUpdate() .

Return values
None.

Exceptions
None.

See also
blackberry.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 Cellsite Value 0 Description 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.

44

JavaScript Reference

Object: CDATASection

Aid Mode Assisted

Value 1

Description This location method requires network connectivity and carrier support. 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. 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.

Autonomous

Syntax

blackberry.location.setAidMode( aidMode )

Parameters
Parameter
aidMode

Type int

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

Return values
None.

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

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

45

JavaScript Reference

Object: CharacterData

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

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

CharacterData properties
Property name
data length

Type String int

Description

Status

Availability 4.6 or later 4.6 or later

Specifies the character data of the current node. writable Returns the length of the content of the data property or read only the CharacterData.substringData() method.

CharacterData methods
Method name
appendData() deleteData() insertData() replaceData() substringData()

Description Appends the given string to the end of the data of the node. Removes the specified range of data. Inserts a string at the specified location in the data. Replaces the specified range of data with the given string. Returns the specified range of data from the node.

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

46

JavaScript Reference

Object: CharacterData

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.

Syntax
CharacterData.appendData( arg )

Parameters
Parameter
arg

Type String

Description The string to append.

Return values
None.

Exceptions
Exception
NO_MODIFICATION_ALLOWED_ERR

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

Syntax

CharacterData.deleteData( offset, count )

Parameters
Parameter
offset

Type int

Description The offset position from which to start removing.

47

JavaScript Reference

Object: CharacterData

Parameter
count

Type int

Description 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 values
None.

Exceptions
Exception
INDEX_SIZE_ERR NO_MODIFICATION_ALLOWED_ERR

Description This error is thrown if offset is negative, or is greater than the number of 16bit units in the data. 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.

Syntax

CharacterData.insertData( offset, arg )

Parameters
Parameter
offset arg

Type int String

Description The offset position from which to start inserting. The string to insert.

Return values
None.

Exceptions
Exception
INDEX_SIZE_ERR

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

48

JavaScript Reference

Object: CharacterData

Exception
NO_MODIFICATION_ALLOWED_ERR

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

Syntax
CharacterData.replaceData( offset, count, arg )

Parameters
Parameter
offset count

Type int int

Description The offset position from which to start replacing. The number of 16-bit units to replace. 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 replaced. The string with which to replace to the data.

arg

String

Return values
None.

Exceptions
Exception
INDEX_SIZE_ERR NO_MODIFICATION_ALLOWED_ERR

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

49

JavaScript Reference

Object: Comment

Method: CharacterData.substringData()
Availability BlackBerry Device Software version 4.6 or later

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

Syntax
CharacterData.substringData( offset, count )

Parameters
Parameter
offset count

Type int int

Description The offset position from which to start extracting. The number of 16-bit units to extract. 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 extracted.

Return values
Returns the specified range of data.

Exceptions
Exception
INDEX_SIZE_ERR NO_MODIFICATION_ALLOWED_ERR

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

Object: Comment
Availability Extends BlackBerry Device Software version 4.6 or later
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.

50

JavaScript Reference

Object: Counter

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
identifier listStyle separator

Type String String String

Description Returns the identifier of the counter. Returns the style of the list. Returns the string used to separate nested counters.

Status read only read only read only

Availability 4.6 or later 4.6 or later 4.6 or later

Object: CSSCharsetRule
Availability Extends BlackBerry Device Software version 4.6 or later
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 always UTF-16. After a style sheet is loaded, the value of the encoding property is the value found in the @charset rule. If there was no @charset in the original document, then no CSSCharsetRule object is created. The value of the encoding property may also be used as a hint for the encoding used on serialization of the style sheet. The value of the @charset rule (and therefore of the CSSCharsetRule object) may not correspond to the encoding the document actually came in; character encoding information, for example, in an HTTP header, has priority but this is not reflected in the CSSCharsetRule.

CSSCharsetRule properties
Property name
encoding

Type String

Description Specifies the encoding used in the @charset rule.

Status writable

Availability 4.6 or later

51

JavaScript Reference

Object: CSSFontFaceRule

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

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

CSSFontFaceRule properties
Property name
style

Type
CSSStyleDeclar ation

Description Returns the declaration block for this rule.

Status read only

Availability 4.6 or later

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

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

CSSImportRule properties
Property name
href

Type String

Description

Status

Availability 4.6 or later

media styleSheet

MediaList CSSStyleShe et

Returns the location of the style sheet to be imported. read only The attribute does not contain the url(...) specifier around the URI. Returns a list of media types that this style sheet can read only be used with. Returns a pointer to the CSSStyleSheet object read only that represents the imported style sheet.

4.6 or later 4.6 or later

52

JavaScript Reference

Object: CSSMediaRule

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

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

CSSMediaRule properties
Property name
CSSRules media

Type
CSSRuleList MediaList

Description Returns a list of the CSS rules contained within a media block. Returns a list of media types that this style sheet can be used with.

Status read only read only

Availabilit y 4.6 or later 4.6 or later

CSSMediaRule methods
Method name
deleteRule() insertRule()

Description Removes a rule from the media block. Adds a rule to the media block.

Availability 4.6 or later 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.

Syntax

CSSMediaRule.deleteRule( index )

Parameters

53

JavaScript Reference

Object: CSSMediaRule

Parameter
index

Type int

Description The position of the rule to remove in the media blocks collection of rules.

Return values
None.

Exceptions
Exception
INDEX_SIZE_ERR NO_MODIFICATION_ALLOWED_ERR

Description This error is thrown if index does not correspond to any rule in the media blocks collection of rules. 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.

Syntax

CSSMediaRule.insertRule( rule, index )

Parameters
Parameter
rule

Type String

Description 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. The position of the rule in the media blocks 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.

index

int

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

Exceptions

54

JavaScript Reference

Object: CSSPageRule

Exception
HIERARCHY_REQUEST_ERR INDEX_SIZE_ERR NO_MODIFICATION_ALLOWED_ERR SYNTAX_ERR

Description 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. This error is thrown if index does not correspond to any rule in the media blocks collection of rules. This error is thrown if the media rule is read only. The error is thrown if the rule has a syntax error and cannot be parsed.

Object: CSSPageRule
Availability Extends BlackBerry Device Software version 4.6 or later
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
selectorText style

Type String
CSSStyleDecla ration

Description Specifies the page selector for the rule. Returns the declaration block of the rule.

Status writable read only

Availability 4.6 or later 4.6 or later

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

The CSSPrimitiveValue object represents a single CSS value. A CSSPrimitiveValue object only occurs in the context of a CSS property.

55

JavaScript Reference

Object: CSSPrimitiveValue

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

CSSPrimitiveValue properties
Property name
primitiveTy pe

Type unsigned short

Description

Status

Availability 4.6 or later

Returns the property value type. The following read only 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 xheight. 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.

56

JavaScript Reference

Object: CSSPrimitiveValue

Property name

Type

Description
17 = CSS_KHZ: A frequency, in kiloHertz. 18 = CSS_DIMENSION: A number value of an

Status

Availability

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
getCounterValue() getFloatValue() getRectValue() getRGBColorValue() getStringValue() setFloatValue() setStringValue()

Description Retrieves a Counter value. Retrieves a float value. Retrieves a Rect value. Retrieves an RGBColor value. Retrieves a string value. Sets a float value with the specified unit. Sets a string value with the specified unit.

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

57

JavaScript Reference

Object: CSSPrimitiveValue

Method: CSSPrimitiveValue.getCounterValue()
Availability BlackBerry Device Software version 4.6 or later

The getCounterValue() method retrieves a Counter value.

Syntax
CSSPrimitiveValue.getCounterValue()

Parameters
None.

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

Exceptions
Exception
INVALID_ACCESS_ERR

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

See Also
Counter

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 the CSSPrimitiveValue.setFloatValue() method.

Syntax
CSSPrimitiveValue.getFloatValue( unitType )

Parameters

58

JavaScript Reference

Object: CSSPrimitiveValue

Parameter
unitType

Type unsigned short

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

59

JavaScript Reference

Object: CSSPrimitiveValue

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 values
Returns the float value in the given units.

Exceptions
Exception
INVALID_ACCESS_ERR

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

See Also
CSSPrimitiveValue.setFloatValue()

Method: CSSPrimitiveValue.getRectValue()
Availability BlackBerry Device Software version 4.6 or later

The getRectValue() method retrieves a Rect value.

Syntax
CSSPrimitiveValue.getRectValue()

Parameters
None.

Return values

60

JavaScript Reference

Object: CSSPrimitiveValue

Returns a Rect object representing the value of a CSS_RECT.

Exceptions
Exception
INVALID_ACCESS_ERR

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

See Also
Rect

Method: CSSPrimitiveValue.getRGBColorValue()
Availability BlackBerry Device Software version 4.6 or later

The getRGBColorValue() method retrieves an RGBColor value.

Syntax
CSSPrimitiveValue.getRGBColorValue()

Parameters
None.

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

Exceptions
Exception
INVALID_ACCESS_ERR

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

See Also
RGBColor

61

JavaScript Reference

Object: CSSPrimitiveValue

Method: getStringValue()
Availability BlackBerry Device Software version 4.6 or later

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

Syntax
CSSPrimitiveValue.getStringValue()

Parameters
None.

Return values
Returns the value of a string.

Exceptions
Exception
INVALID_ACCESS_ERR

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

See Also
CSSPrimitiveValue.setStringValue()

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 the given unit type or the float value, the value will not be changed, and an exception is thrown.

Syntax
CSSPrimitiveValue.setFloatValue( unitType, floatValue )

Parameters

62

JavaScript Reference

Object: CSSPrimitiveValue

Parameter
unitType

Type unsigned short

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

63

JavaScript Reference

Object: CSSPrimitiveValue

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 values
None.

Exceptions
Exception INVALID_ACCESS_ERR Description 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. This error is thrown if the property is read only.

NO_MODIFICATION_ALLOWED_ERR

See Also
CSSPrimitiveValue.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 accept the given unit type or the string value, the value will not be changed, and an exception is thrown.

Syntax
setStringValue( unitType, stringValue )

Parameters

64

JavaScript Reference

Object: CSSRule

Parameter
unitType

Type unsigned short

Description 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 values
None.

Exceptions
Exception
INVALID_ACCESS_ERR NO_MODIFICATION_ALLOWED_ERR

Description 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). This error is thrown if the property is read only.

See Also
CSSPrimitiveValue.getStringValue()

Object: CSSRule
Availability Extended by BlackBerry Device Software version 4.6 or later 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.

65

JavaScript Reference

Object: CSSRuleList

CSSRule properties
Property name
parentRule

Type
CSSRule

Description

Status

Availability 4.6 or later

parentStyleShee t type

CSSStyleSh eet

Returns the parent rule, if this rule is contained read only within another rule (for example, a style rule within an @media block). Returns the style sheet that contains this rule. read only 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 .

4.6 or later 4.6 or later

unsigned short

read only

Object: CSSRuleList
Availability BlackBerry Device Software version 4.6 or later The CSSRuleList object represents an ordered collection of CSSRule objects.

66

JavaScript Reference

Object: CSSRuleList

CSSRuleList properties
Property name
length

Type int

Description Returns the number of rules in the list.

Status read only

Availability 4.6 or later

CSSRuleList methods
Method name
item()

Description Returns the rule at the specified index in the collection.

Availability 4.6 or later

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

Syntax
CSSRuleList.item( index )

Parameters
Parameter
index

Type int

Description An integer that represents the CSS ruless position in rule list. Valid values are 0 to CSSRuleList.length -1.

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

Exceptions
None.

See Also
CSSRule

67

JavaScript Reference

Object: CSSStyleDeclaration

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. This object enables you to determine the style properties currently set in a block or to set style properties explicitly within the block. This object also provides access to the computed values of an element. It does not provide access to the specified or actual values of the CSS cascade.

CSSStyleDeclaration properties
Property name
azimuth background backgroundAttachmen t backgroundColor backgroundImage backgroundPosition backgroundRepeat border borderBottom borderBottomColor borderBottomStyle borderBottomWidth borderCollapse borderColor

Type String String String String String String String String String String String String String String

Description Specifies the direction from which a sound originates. Specifies any or all background properties. Specifies whether the background scrolls with the page. Specifies the background color for an element. Specifies an image resource to use as the background. Specifies the starting position of a background image. Specifies how or if a background image is repeated. Specifies any or all border properties for an element. Specifies any or all bottom border properties for an element. Specifies the bottom border color for an element Specifies the bottom border style for an element. Specifies the bottom border width of an element. Specifies whether the table borders are collapsed into a single border. Specifies the border color for an element.

Status writable writable writable writable writable writable writable writable writable writable writable writable writable writable

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

68

JavaScript Reference

Object: CSSStyleDeclaration

Property name
borderLeft borderLeftColor borderLeftStyle borderLeftWidth borderRight borderRightColor borderRightStyle borderRightWidth borderSpacing borderStyle borderTop borderTopColor borderTopStyle borderTopWidth borderWidth bottom captionSide clear clip color content counterIncrement counterReset cue

Type String String String String String String String String String String String String String String String String String String String String String String String String

Description Specifies any or all left border properties for an element. Specifies the left border color for an element. Specifies the left border style for an element. Specifies the left border width of an element. Specifies any or all right border properties for an element. Specifies the right border color for an element. Specifies the right border style for an element. Specifies the right border width of an element. Specifies the distance between the cell borders when not collapsed. Specifies the border style for an element. Specifies any or all top border properties for an element. Specifies the top border color for an element. Specifies the top border style for an element. Specifies the top border width of an element. Specifies the border width of an element. Specifies the distance of the bottom edge of an element above or below the parent element. Specifies the location of the table caption. Specifies the side(s) of an element that may not be adjacent to floating elements. Specifies the shape of the element. Specifies the foreground color for an element. Used with the :before and :after pseudo-elements to generate content. Specifies how much the counter is incremented for every occurrence of the element. Resets a counter for an element. Specifies any or all cue properties.

Status writable writable writable writable writable writable writable writable writable writable writable writable writable writable writable writable writable writable writable writable writable writable writable writable

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

69

JavaScript Reference

Object: CSSStyleDeclaration

Property name
cueAfter cueBefore cursor direction display elevation emptyCells CSSFloat font fontFamily fontSize fontStyle fontVariant fontWeight height left length letterSpacing lineHeight listStyle listStyleImage listStylePosition listStyleType margin

Type String String String String String String String String String String String String String String String String int String String String String String String String

Description Specifies a URI containing a sound that is played after an element. Specifies a URI containing a sound that is played before an element. Specifies the type of cursor. Specifies the base direction of the text. Specifies how or if an element is displayed. Specifies the elevation from which a sound originates. Specifies whether empty cells are displayed when the borders are not merged. Specifies where an image or text will appear in another element. Specifies any or all of the font properties for an element. Specifies the font family for an element. Specifies the font size for an element. Specifies the style of the font for an element. Specifies whether the font for an element is rendered in small caps. Specifies the thickness of the font for an element. Specifies the height of an element. Specifies the distance of the left edge of an element from the right or left edge of the parent element. Returns the number of properties that have been explicitly set. Specifies the spacing between the characters. Specifies the height of each line in an element. Specifies any or all of the list properties. Specifies the image used for the list marker. Specifies the location of the list marker. Specifies the type of list marker. Specifies the margin around all sides of an element.

Status writable writable writable writable writable writable writable writable writable writable writable writable writable writable writable writable read only writable writable writable writable writable writable writable

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

70

JavaScript Reference

Object: CSSStyleDeclaration

Property name
marginBottom marginLeft marginRight marginTop maxHeight maxWidth minHeight minWidth orphans outline outlineColor outlineStyle outlineWidth overflow

Type String String String String String String String String String

Description

Status writable writable writable writable writable writable writable writable writable writable writable writable writable writable

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

padding paddingBottom paddingLeft paddingRight paddingTop pageBreakAfter pageBreakBefore pageBreakInside parentRule

Specifies the margin below an element. Specifies the margin to the left of an element. Specifies the margin to the right of an element. Specifies the margin above an element. Specifies the maximum height for an element. Specifies the maximum width for an element. Specifies the minimum height for an element. Specifies the minimum width for an element. Specifies the minimum number of lines left at the bottom of a page. String Specifies any or all of the outline properties. String Specifies the outline color for an element. String Specifies the outline style for an element. String Specifies the outline width for an element. String Specifies the behavior when the content of an element overflows the available space for that element. String Specifies the padding around all sides of an element. String Specifies the padding applied below an element. String Specifies the padding applied to the left of an element. String Specifies the padding applied to the right of an element. String Specifies the padding applied above an element. String Specifies how the page breaks after the element are handled. String Specifies how the page breaks before the element are handled. String Specifies how the page breaks within the element are handled. CSSRule Returns the CSSRule that contains this declaration block.

writable writable writable writable writable writable writable writable read only

4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

71

JavaScript Reference

Object: CSSStyleDeclaration

Property name
pause pauseAfter pauseBefore pitch pitchRange playDuring position quotes richness right

Type String String String String String String String String String String

Description Specifies any or all of the pause properties. Specifies a pause to be observed after an element. Specifies a pause to be observed before an element. Specifies the average pitch of the speaking voice. Specifies the variation in average pitch. Specifies a sound to be played in the background while an elements content is spoken. Specifies the position of the element. Specifies the quotation marks to use for embedded quotations. Specifies the brightness of the speaking voice. Specifies the distance of the right edge of the of an element from the right or left edge of the parent element. Specifies whether text will be rendered aurally. Specifies how table headers are rendered aurally. Specifies how numerals are spoken. Specifies how punctuation is spoken. Specifies the speaking rate. Specifies the level of intonation of a voice. Specifies whether the column width is fixed or determined by the width of the content. Specifies the horizontal alignment of the text for an element. Specifies the decoration applied to the text. Specifies the indentation of the first line of text in a block of text. Specifies how the text is capitalized. Specifies the distance of the top edge of an element above or below the parent element. Specifies the Unicode bidirectional algorithm to use. Specifies the vertical alignment of an element.

Status writable writable writable writable writable writable writable writable writable writable

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

speak speakHeader speakNumeral speakPunctuation speechRate stress tableLayout textAlign

String String String String String String String String String String String String String String

writable writable writable writable writable writable writable writable writable writable writable writable writable writable writable

4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

textDecoration textIndent textTransform top unicodeBidi verticalAlign

72

JavaScript Reference

Object: CSSStyleDeclaration

Property name
visibility voiceFamily volume whitespace widows width wordSpacing zIndex

Type String String String String String String String String

Description Specifies whether elements are rendered or not. Specifies a list of voice family names. Specifies the median volume of the wave form. Specifies how white space in an element is handled. Specifies the minimum number of lines left at the top of a page. Specifies the width of an element. Specifies the spacing between words. Specifies the stack order of an element.

Status writable writable writable writable writable writable writable writable

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

CSSStyleDeclaration methods
Method name
getPropertyCSSValue () getPropertyPriority () getPropertyValue() item() removeProperty() setProperty()

Description

Availability

Returns the value of a CSS property as an object, if the property has been 4.6 or later explicitly set. Returns the priority of a CSS property. 4.6 or later Returns the value of a CSS property as a string, if the property has been explicitly set. Returns the name of the CSS property at the specified index in the collection. Removes a CSS property from the style declaration block. Sets the value of a CSS property for the style declaration block. 4.6 or later 4.6 or later 4.6 or later 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 whether the !important qualifier has been specified.

Syntax

73

JavaScript Reference

Object: CSSStyleDeclaration

CSSStyleDeclaration.getPriorityProperty( propertyName )

Parameters
Parameter
propertyName

Type String

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

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

Exceptions
None.

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 modified as strings, using CSSStyleDeclaration.getPropertyValue() and CSSStyleDeclaration.setProperty() .

Syntax
CSSStyleDeclaration.getPropertyCSSValue( propertyName )

Parameters
Parameter
propertyName

Type String

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

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

Exceptions
None.

74

JavaScript Reference

Object: CSSStyleDeclaration

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.

Syntax
CSSStyleDeclaration.getPropertyValue( propertyName )

Parameters
Parameter
propertyName

Type String

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

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

Exceptions
None.

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.

Syntax
CSSStyleDeclaration.item( index )

Parameters
Parameter
index

Type int

Description An integer that represents the CSS propertys position in style declaration block.

Return values

75

JavaScript Reference

Object: CSSStyleDeclaration

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

Exceptions
None.

Method: CSSStyleDeclaration.removeProperty()
Availability BlackBerry Device Software version 4.6 or later

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

Syntax
CSSStyleDeclaration.removeProperty( propertyName )

Parameters
Parameter
propertyName

Type String

Description The name of the CSS property to remove.

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

Exceptions
Exception
NO_MODIFICATION_ALLOWED_ERR

Description 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

76

JavaScript Reference

Object: CSSStyleRule

CSSStyleDeclaration.setProperty( propertyName, value, priority )

Parameters
Parameter
propertyName value priority

Type String String String

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

Return values
None.

Exceptions
Exception
NO_MODIFICATION_ALLOWED_ERR SYNTAX_ERR

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

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

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

CSSStyleRule properties
Property name
selectorText style

Type String
CSSStyleDeclar ation

Description Specifies the name of the CSS selector for the rule set. Returns the style values for the CSS selector.

Status writable read only

Availability 4.6 or later 4.6 or later

77

JavaScript Reference

Object: CSSStyleSheet

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

The CSSStyleSheet object represents a CSS style sheet.

CSSStyleSheet properties
Property name
CSSRules ownerRule

Type
CSSRuleLis t CSSRule

Description

Status

Availability 4.6 or later 4.6 or later

Returns an array of the CSSRule objects in the style read only sheet. Returns the CSSImportRule object for imported read only style sheets. If the style sheet is not imported, the value for this property is null.

CSSStyleSheet methods
Method name
deleteRule() insertRule()

Description Deletes a CSS Rule at the given position in the CSS style sheet. Adds a CSS Rule at the given position in the CSS style sheet.

Availability 4.6 or later 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.

Syntax
CSSStyleSheet.deleteRule( index )

Parameters

78

JavaScript Reference

Object: CSSStyleSheet

Parameter
index

Type int

Description An integer that represents the CSS ruless position in the style sheets collection of rules.

Return values
None.

Exceptions
Exception
NO_MODIFICATION_ALLOWED_ERR INDEX_SIZE_ERR

Description This error is thrown if the style sheet is read only. This error is thrown if index does not correspond to any rule in the style sheets 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.

Syntax
CSSStyleSheet.insertRule( rule, index )

Parameters
Parameter
rule

Type String

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

79

JavaScript Reference

Object: CSSUnknownRule

Parameter
index

Type int

Description An integer that represents the position in the style sheets 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 values
Returns the position of the newly added style sheet in the style sheets collection of rules.

Exceptions
Exception
NO_MODIFICATION_ALLOWED_ERR INDEX_SIZE_ERR

Description This error is thrown if the style sheet is read only. This error is thrown if index does not correspond to any rule in the style sheets collection of rules.

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

The CSSUnknownRule represents an unsupported @ rule.

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

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

80

JavaScript Reference

Object: CSSValueList

CSSValue properties
Property name
CSSValueType

Type unsigned short

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

Status read only

Availability 4.6 or later

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

The CSSValueList objects represents an ordered collection of CSSValue objects. Some properties allow an empty list into their syntax. In that case, these properties take the none identifier. So, an empty list means that the property has the value none.

CSSValueList properties
Property name
length

Type int

Description Returns the number of property values in the list.

Status read only

Availability 4.6 or later

81

JavaScript Reference

Object: CustomEvent

CSSValueList methods
Method name
item()

Description Returns the CSSValue object at the specified index in the CSSValueList.

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

Syntax
CSSValueList.item( index )

Parameters
Parameter
index

Type int

Description An integer that represents the CSS property values position in rule list. Valid values are 0 to CSSValueList.length -1.

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

Exceptions
None.

Object: CustomEvent
Availability Extends BlackBerry Device Software version 4.6 or later
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".

82

JavaScript Reference

Object: CustomEvent

Properties
Property name
detail

Type
Object

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

Status read only

Availability 4.6 or later

CustomEvent methods
Method name
initCustomEventNS()

Description Initializes the value of a CustomEvent created by Document.createEvent() .

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

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

Parameters
Parameter
arg canBubbleArg cancelableArg detailArg

Type int boolean boolean long

Description The event type. If true, specifies that the event can bubble. If true, specifies that the event can be cancelled. The events detail.

Return values
None.

Exceptions
None.

83

JavaScript Reference

Object: Document

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

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

Document properties
Property name
defaultView doctype documentElement implementation parentWindow

Type
AbstractView DocumentType Element DOMImplementa tion Window

Description Returns the default view of the document. Returns the document type declaration associated with the document. Returns the root element in a document. Returns the DOMImplementation object that handles this document. Returns a reference to the parent window. If no parent window exists, this property points to the current active window. Returns an array of all the style sheets in the document.

Status read only read only read only read only read only

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

styleSheets

StyleSheetLis t

read only

4.6 or later

Document methods
Method name
adoptNode() createAttribute() createAttributeNS()

Description Adopts a node and its children from an external document to the current document. Creates a new Attr object with the given name. Creates a new Attr object with the given qualified name and namespace URI.

Availability 4.7.1 or later 4.6 or later 4.6 or later

84

JavaScript Reference

Object: Document

Method name
createCDATASection() createComment() createDocumentFragment() createElement() createElementNS() createEntityReference() createEvent() createNodeIterator() createProcessingInstruct ion() createRange() createTextNode() createTreeWalker() getElementById() getElementsByTagName() getElementsByTagNameNS()

Description Creates a new CDATASection object, which represents a block of uninterpreted content. Creates a new Comment object with the given text as content. Creates an empty DocumentFragment object. Creates a new Element object of the specified type. Creates a new Element object of the given qualified name and namespace URI. Creates a new EntityReference object with the given name. Creates a new Event object of the given type. Creates a new NodeIterator object, which you can use to iterate through a set of Document nodes rooted at the given node. Creates a new ProcessingInstruction object with the given name and data. Creates a new Range object. Creates a new Text node containing the given text. Creates a TreeWalker object, which you can use to traverse the specified document subtree. Returns the element node with the given ID value. Returns a NodeList object that contains an array of a documents descendent element nodes with the specified tag name. Returns a NodeList object that contains an array of a documents descendent element nodes with the given local name and namespace URI. Retrieves the override CSSStyleDeclaration object for the given element. Imports a node from a different document.

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.7.1 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

getOverrideStyle() importNode()

4.6 or later 4.6 or later

85

JavaScript Reference

Object: Document

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 the Document.importNode() method, which imports a copy of the source node, the adoptNode() method removes a node from 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, then changes 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.

Syntax
Document.adoptNode( sourceNode )

Parameters
Parameter
sourceNode

Type
Node

Description Specifies the node to move to the current document.

Return values
This method returns the new node, or null if the operation is unsuccessful.

Exceptions
Exception NO_MODIFICATION_ALLOWED_ERR NOT_SUPPORTED_ERR Description Thrown if sourceNode is read-only. 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 can be bound to an element using Element.setAttributeNode() . This method only populates the Node.nodeName property for the created attribute and sets the attributes value to null.

86

JavaScript Reference

Object: Document

To create an attribute with a qualified name and namespace URI, use Document.createAttributeNS() .

Syntax
Document.createAttribute( name )

Parameters
Parameter
name

Type String

Description The name of the attribute to create.

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

Exceptions
Exception
INVALID_CHARACTER_ERR

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

See also
Attr , 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. Once created, the attribute instance can be bound to an element using Element.setAttributeNode() .

Syntax
Document.createAttributeNS( namespaceURI, qualifiedName )

Parameters
Parameter
namespaceURI qualifiedName

Type String String

Description The namespace of the new attribute. The qualified name of the attribute to create.

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

87

JavaScript Reference

Object: Document

Property
Node.nodeName Node.namespaceURI Node.prefix Node.localName Node.nodeValue Attr.name

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

Exceptions
Exception
INVALID_CHARACTER_ERR NAMESPACE_ERR

Description This error is thrown if qualifiedName contains an illegal character. 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

NOT_SUPPORTED_ERR

qualifiedName is xmlns, but namespaceURI is not http:// www.w3.org/2000/xmlns/

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

See also
Attr , 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 uninterpreted content. HTML documents do not support CDATASection objects.

Syntax

88

JavaScript Reference

Object: Document

Document.createCDATASection( data )

Parameters
Parameter
data

Type String

Description The contents of the CDATASection node.

Return values
Returns the new CDATASection object.

Exceptions
None.

See also
CDATASection

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.

Syntax
Document.createComment( data )

Parameters
Parameter
data

Type String

Description The contents of the Comment node.

Return values
Returns the new Comment object.

Exceptions
None.

See also
Comment

89

JavaScript Reference

Object: Document

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 documentsuch as multiple parent nodes and their childrenat once.

Syntax
Document.createDocumentFragment()

Parameters
None.

Return values
Returns the new DocumentFragment object.

Exceptions
None.

See also
DocumentFragment

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 the returned object. If the Element type returned has any attributes with default values, those attributes will be created and attached to the element with their default values.

Syntax
Document.createElement( tagName )

Parameters

90

JavaScript Reference

Object: Document

Parameter
tagName

Type String

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

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

Exceptions
Exception
INVALID_CHARACTER_ERR

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

See also
Attr , 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. Attributes can be set directly on the returned object.

Syntax
Document.createElementNS( namespaceURI, qualifiedName )

Parameters
Parameter
namespaceURI qualifiedName

Type String String

Description The namespace of the new attribute. The qualified name of the attribute to create.

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

91

JavaScript Reference

Object: Document

Property
Node.nodeName Node.namespaceURI Node.prefix Node.nodeValue Element.tagName

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

Exceptions
Exception
INVALID_CHARACTER_ERR NAMESPACE_ERR

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

See also
Element

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 objects list of child nodes is made the same as the corresponding Entity node.

Syntax
Document.createEntityReference( name )

Parameters

92

JavaScript Reference

Object: Document

Parameter
name

Type String

Description The name of the entity to reference.

Return values
Returns the new EntityReference object.

Exceptions
Exception
INVALID_CHARACTER_ERR NOT_SUPPORTED_ERR

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

See also
Entity , 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 after the event has been created, and before it is dispatched, in order to initialize the events values. This method is used to create events when it is inconvenient or unnecessary for the user to create an event themselves.

Syntax
Document.createEvent( eventType )

Parameters
Parameter
eventType

Type String

Description The type of event to create.

Return values
Returns the new Event object.

Exceptions

93

JavaScript Reference

Object: Document

Exception
NOT_SUPPORTED_ERR

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

See also
Event

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 of Document nodes rooted at the given node.

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

Parameters
Parameter
root whatToShow

Type
Node

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

unsigned long

0x00000008 = SHOW_CDATA_SECTION 0x00000010 = SHOW_ENTITY_REFERENCE 0x00000020 = SHOW_ENTITY 0x00000040 = SHOW_PROCESSING_INSTRUCTION 0x00000080 = SHOW_COMMENT 0x00000100 = SHOW_DOCUMENT

94

JavaScript Reference

Object: Document

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 objects 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. The filter to use with this NodeIterator object. This parameter may be null. When true, this method specifies that entity reference nodes should be expanded.

filter entityReferenceE xpansion

NodeFilter

boolean

Return values
Returns the new NodeIterator object.

Exceptions
Exception
NOT_SUPPORTED_ERR

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

See also
NodeIterator

Method: Document.createProcessingInstruction()
Availability BlackBerry Device Software version 4.6 or later

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

Syntax
Document.createProcessingInstruction( target, data )

Parameters

95

JavaScript Reference

Object: Document

Parameter
target data

Type String String

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

Return values
Returns the new ProcessingInstruction object.

Exceptions
Exception
INVALID_CHARACTER_ERR NOT_SUPPORTED_ERR

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

See also
ProcessingInstruction

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 DocumentFragment or Attr objects for which this document is the owner.

Syntax
Document.createRange()

Parameters
None.

Return values
This method returns the new empty Range object. The boundary points of the Range object that is returned from this method are positioned at the beginning of the corresponding document, before any content.

Exceptions
None.

See also

96

JavaScript Reference

Object: Document

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 single node later on.

Syntax
Document.createTextNode( text )

Parameters
Parameter
text

Type String

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

Return values
Returns the new Text object.

Exceptions
None.

See also
Text

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 document subtree.

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

Parameters

97

JavaScript Reference

Object: Document

Parameter
root whatToShow

Type
Node

Description The node that will serve as the root for this TreeWalker object. The TreeWalker.currentNode property is set to the value of root . 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

unsigned long

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 objects 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. The filter to use with this TreeWalker object. This parameter may be null. When true, this method specifies that entity reference nodes should be expanded.

filter entityReferenceExpa nsion

NodeFilt er

boolean

Return values
Returns the new TreeWalker object.

Exceptions

98

JavaScript Reference

Object: Document

Exception
NOT_SUPPORTED_ERR

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

See also
TreeWalker

Method: Document.getElementById()
Availability BlackBerry Device Software version 4.6 or later

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

Syntax
Document.getElementById( elementID )

Parameters
Parameter
elementID

Type String

Description The ID of the element to retrieve.

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

Exceptions
None.

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

See also
Element

99

JavaScript Reference

Object: Document

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 documents descendent Element nodes with the specified tag name.

Syntax
Document.getElementsByTagName( tagName )

Parameters
Parameter
tagName

Type String

Description The name of the tag to match on. Specify a value of * to match all elements.

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

Exceptions
None.

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

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 documents descendent Element nodes with the given local name and namespace URI.

Syntax
Document.getElementsByTagNameNS( namespaceURI, localName )

Parameters

100

JavaScript Reference

Object: Document

Parameter
namespaceURI localName

Type String String

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

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

Exceptions
None.

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

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 declaration maintain precedence and cannot be overridden using this method. Using this method, you can override an explicitly linked style sheet without changing the authored style sheet itself.

Syntax
Document.getOverrideStyle( elt, pseudoElt )

Parameters
Parameter
elt pseudoElt

Type
Element

Description The element for which to modify the style. The pseudo-element for which to modify the style. This parameter may be null.

String

Return values

101

JavaScript Reference

Object: Document

Returns the CSSStyleDeclaration object.

Exceptions
None.

See also
CSSStyleDeclaration

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 creates a new copy of the source node. Importing a node creates a new Node object owned by the document the node is imported into, with values identical to the Node.nodeName and Node.nodeType , plus the attributes related to namespaces. Additional information is copied as appropriate to the node type.

Syntax
Document.importNode( importedNode, deep )

Parameters
Parameter
importedNode deep

Type
Node

Description The node to import into the current document. 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.

boolean

Return values
Returns the imported Node.

Exceptions

102

JavaScript Reference

Object: DocumentFragment

Exception
NOT_SUPPORTED_ERR

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

See also
Node.cloneNode()

Object: DocumentFragment
Availability Extends BlackBerry Device Software version 4.6 or later
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 without creating an entirely new document. When the children of a DocumentFragment object are inserted into a Document object, only the children of the DocumentFragment, and not the DocumentFragment itself, are inserted into the node.

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

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

DocumentType properties
Property name
entities

Type
NamedNode Map

Description Returns a list of all the general entities defined within the DTD.

Status read only

Availability 4.6 or later

103

JavaScript Reference

Object: DOMImplementation

Property name
internalSubset

Type String

Description Returns the contents of the DTD subset. Contains the string between the [ and ] characters. Returns the name of the DTD. Returns a list of all the notations defined within the DTD. Returns the public identifier of the external subset. Returns the system identifier of the external subset.

Status read only

Availability 4.6 or later

name notations publicId systemId

String
NamedNode Map

read only read only read only read only

4.6 or later 4.6 or later 4.6 or later 4.6 or later

String String

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 instance of the DOM, such as creating new documents. You can check the object to determine if the DOMImplementation supports a given feature.

DOMImplementation methods
Method name
createCSSStyleSheet () createDocument() createDocumentType() hasFeature()

Description Creates a new CSS stylesheet document object. Creates a new XML or HTML document object. Creates an empty document type node. Determines whether the DOM implementation implements a specific feature.

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later

104

JavaScript Reference

Object: DOMImplementation

Method: DOMImplementation.createCSSStyleSheet()
Availability BlackBerry Device Software version 4.6 or later

The createCSSStyleSheet() method creates a new CSSStyleSheet object.

Syntax
DOMImplementation.createCSSStyleSheet( title, media )

Parameters
Parameter
title media

Type String String

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

Return values
Returns the new CSSStyleSheet object.

Exceptions
Exception
SYNTAX_ERR

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

See also
CSSStyleSheet

Method: DOMImplementation.createDocument()
Availability BlackBerry Device Software version 4.6 or later

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

Syntax
DOMImplementation.createDocument( namespaceURI, qualifiedName, doctype )

Parameters

105

JavaScript Reference

Object: DOMImplementation

Parameter
namespaceURI qualifiedName doctype

Type String String

DocumentTy pe

Description The namespace of the new document. The qualified name of the document to create. The type of document to be created, or null.

Return values
Returns the new Document object.

Exceptions
Exception
SYNTAX_ERR NAMESPACE_ERR

Description This error is thrown if qualifiedName contains an illegal character. 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 WRONG_DOCUMENT_ERR

This error is thrown if the document does not support XML namespaces. This error is thrown if doctype has already been used with a different document or was created from a different implementation.

See also
Document

Method: DOMImplementation.createDocumentType()
Availability BlackBerry Device Software version 4.6 or later

The createDocumentType() method creates an empty DocumentType node.

Syntax

106

JavaScript Reference

Object: DOMImplementation

DOMImplementation.createDocumentType( qualifiedName, publicId, systemId )

Parameters
Parameter
qualifiedName publicId systemId

Type String String String

Description The qualified name of the document. The qualified name of the document to create. The type of document to be created, or null.

Return values
Returns the new DocumentType object.

Exceptions
Exception
INVALID_CHARACTER_ERR NAMESPACE_ERR

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

See also
DocumentType

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 equivalent to functionality provided using Node.isSupported().

Syntax
DOMImplementation.hasFeature( feature, version )

107

JavaScript Reference

Object: DOMParser

Parameters
Parameter
feature version

Type String String

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

Return values
Returns:
true, if the specified version of the specified feature is supported. false, if the specified version of the specified feature is not supported.

Exceptions
None.

See also
Node.isSupported()

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 XML string that you construct, or an XML string that you retrieve from a remote location.

DOMParser methods
Method name
parseFromString()

Description Converts a string into an XML document.

Availability 4.7.1 or later

108

JavaScript Reference

Object: DOMParser

Method: DOMParser.parseFromString()
Availability BlackBerry Device Software version 4.7.1 or later

The parseFromString() method converts a string into an XML document.

Syntax
DOMParser.parseFromString( string, mimeType )

Parameters
Parameter
string mimeType

Type String String

Description Specifies the string of text. 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 values
This method returns an XML document. If the parsing process fails, an error document is returned.

Exceptions
No 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 again
var 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 )

109

JavaScript Reference

Object: Element

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

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

Element properties
Property name
tagName

Type String

Description The name of the element.

Status read only

Availability 4.6 or later

Element methods
Method name
getAttribute() getAttributeNode() getAttributeNodeNS() getAttributeNS() getElementsByTagName () getElementsByTagName NS() hasAttribute() hasAttributeNS()

Description Retrieves the value of the attribute of the given name. Retrieves the attribute node of the given name. Retrieves the attribute node with the given namespace URI and local name. Retrieves the value of the attribute with the given namespace URI and local name. Returns a NodeList object that contains an array of an elements descendent element nodes with the specified tag name. Returns a NodeList object that contains an array of an elements descendent element nodes with the given local name and namespace URI. Determines whether an attribute of the given name is specified on the element. Determines whether an attribute of the given namespace and local name is specified on the element.

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

110

JavaScript Reference

Object: Element

Method name
removeAttribute() removeAttributeNode () removeAttributeNS() setAttribute() setAttributeNode() setAttributeNodeNS() setAttributeNS()

Description Removes the attribute of the given name from the element node. Removes the specified attribute node from the element node. Removes the attribute node with the given namespace URI and local name from the element node. Adds a new attribute to an element, and sets it to the given value. Adds a new attribute node to an element. Adds a new attribute node to an element. Adds a new attribute to an element, and sets it to the given value.

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 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.

Syntax
Element.getAttribute( name )

Parameters
Parameter
name

Type String

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

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

Exceptions
None.

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

111

JavaScript Reference

Object: Element

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 the Node.attributes property.

Syntax
Element.getAttributeNode( name )

Parameters
Parameter
name

Type String

Description The name of the Attr node to retrieve.

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

Exceptions
None.

See also
Attr , 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.

Syntax
Element.getAttributeNodeNS( namespaceURI, localName )

Parameters

112

JavaScript Reference

Object: Element

Parameter
namespaceURI localName

Type String String

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

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

Exceptions
Exception
NOT_SUPPORTED_ERR

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

See also
Attr

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.

Syntax
Element.getAttributeNS( namespaceURI, localName )

Parameters
Parameter
namespaceURI

Type String

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

localName

String

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

Exceptions

113

JavaScript Reference

Object: Element

Exception
NOT_SUPPORTED_ERR

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

See also
Attr

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 elements descendent Element nodes with the specified tag name. This method is identical to Document.getElementsByTagName() , except that it allows you to search a smaller subset of
Element nodes.

Syntax
Element.getElementsByTagName( tagName )

Parameters
Parameter
tagName

Type String

Description The name of the tag to match on. Specify a value of * to match all elements.

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

Exceptions
None.

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

114

JavaScript Reference

Object: Element

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 elements descendent Element nodes with the given local name and namespace URI. This method is identical to Document.getElementsByTagNameNS() , except that it allows you to search a smaller subset of Element nodes.

Syntax
Element.getElementsByTagNameNS( namespaceURI, localName )

Parameters
Parameter
namespaceURI

Type String

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

localName

String

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

Exceptions
Exception
NOT_SUPPORTED_ERR

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

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

115

JavaScript Reference

Object: Element

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 use this method to verify that an attribute is attached to an element before retrieving it.

Syntax
Element.hasAttribute( name )

Parameters
Parameter
name

Type String

Description The name of the attribute to check.

Return values
Returns:
true, if the specified attribute exists on the element false, if the attribute does not exist

Exceptions
None.

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 the element. You can use this method to verify that an attribute is attached to an element before retrieving it.

Syntax
Element.hasAttributeNS( namespaceURI, localName )

Parameters
Parameter
namespaceURI

Type String

Description The namespace of the attribute to check.

116

JavaScript Reference

Object: Element

Parameter
localName

Type String

Description The local name of the attribute to check.

Return values
Returns:
true, if the specified attribute exists on the element false, if the attribute does not exist

Exceptions
Exception
NOT_SUPPORTED_ERR

Description 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 immediately be reattached to the element with its default value, as well as its corresponding namespace URI, local name, and prefix, if applicable. If the attribute has no specified or default value, this method has no effect.

Syntax
Element.removeAttribute( name )

Parameters
Parameter
name

Type String

Description The name of the Attr node to remove.

Return values
None.

Exceptions

117

JavaScript Reference

Object: Element

Exception
NO_MODIFICATION_ALLOWED_ERR NOT_FOUND_ERR

Description This error is thrown if the Element node is read only. This error is thrown if no node exists in the Element with a Node.nodeName value of name .

See also
Attr

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 immediately be reattached to the element with its default value, as well as its corresponding namespace URI, local name, and prefix, if applicable.

Syntax
Element.removeAttributeNode( oldAttr )

Parameters
Parameter
oldAttr

Type
Attr

Description The Attr node to remove from the attribute list.

Return values
None.

Exceptions
Exception
NO_MODIFICATION_ALLOWED_ERR NOT_FOUND_ERR

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

See also
Attr

118

JavaScript Reference

Object: Element

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 the element node. If you are removing an attribute from the Element object that is known to have a default value, the attribute will immediately be reattached to the element with its default value, as well as its corresponding namespace URI, local name, and prefix, if applicable. If the attribute has no specified or default value, this method has no effect.

Syntax
Element.removeAttributeNS( namespaceURI, localName )

Parameters
Parameter
namespaceURI localName

Type String String

Description The namespace of the attribute to remove. The local name of the attribute to remove.

Return values
None.

Exceptions
Exception
NO_MODIFICATION_ALLOWED_ERR NOT_SUPPORTED_ERR

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

See also
Attr

119

JavaScript Reference

Object: Element

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 the given name already exists on the Element node, its value is changed to the given value. This method only sets values as text strings, not entities. If the value contains any markup syntax (for example, if the value is an EntityReference), it will not be parsed and it must be properly escaped. If you want to assign values containing entities, you should use Element.setAttributeNode() or Element.setAttributeNodeNS() .

Syntax
Element.setAttribute( name, value )

Parameters
Parameter
name value

Type String String

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

Return values
None.

Exceptions
Exception
INVALID_CHARACTER_ERR NO_MODIFICATION_ALLOWED_ERR

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

See also
Attr , 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 the new Attr node already exists on an element, that Attr node is replaced.

120

JavaScript Reference

Object: Element

Unlike Element.setAttribute() , this method allows you to add DOM nodes, instead of specifying separate arguments for the attribute name and value. Note that your attribute nodes cannot be reused in multiple elements; you must either clone the Attr node, or remove an Attr node from another element before adding it to a new element.

Syntax
Element.setAttributeNode( newAttr )

Parameters
Parameter
newAttr

Type
Attr

Description The Attr node to add to the attribute list.

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

Exceptions
Exception
INUSE_ATTRIBUTE_ERR NO_MODIFICATION_ALLOWED_ERR WRONG_DOCUMENT_ERR

Description 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. This error is thrown if the Element object is read only. This error is thrown if newAttr was created from a different document than the one that created this Element object.

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

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 namespace and local name as the new Attr node already exists on an element, that attribute node is replaced. Unlike Element.setAttributeNS() , this method allows you to add DOM nodes, instead of specifying separate arguments for the attribute name and value. Note that your attribute nodes cannot be reused in multiple elements; you must either clone the Attr node, or remove an Attr node from another element before adding it to a new element.

Syntax

121

JavaScript Reference

Object: Element

Element.setAttributeNodeNS( newAttr )

Parameters
Parameter
newAttr

Type
Attr

Description The Attr node to add to the attribute list.

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

Exceptions
Exception
INUSE_ATTRIBUTE_ERR

Description 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. This error is thrown if the Element object is read only. This error is thrown if the document does not support XML namespaces. This error is thrown if newAttr was created from a different document than the one that created this Element object.

NO_MODIFICATION_ALLOWED_ERR NOT_SUPPORTED_ERR WRONG_DOCUMENT_ERR

See also
Attr , 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 with the given namespace and local name already exists on the Element node, its prefix is change to the prefix portion of the qualified name, and its value is changed to the given value. This method only sets values as text strings, not entities. If the value contains any markup syntax (for example, if the value is an
EntityReference ), it will not be parsed and it must be properly escaped. If you want to assign values containing entities, you should use Element.setAttributeNode() or Element.setAttributeNodeNS() .

Syntax
Element.setAttributeNS( namespaceURI, qualifiedName, value )

Parameters

122

JavaScript Reference

Object: Entity

Parameter
newAttr qualifiedName value

Type String String String

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

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

Exceptions
Exception
INVALID_CHARACTER_ERR NAMESPACE_ERR

Description This error is thrown if name contains an illegal character. 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 NOT_SUPPORTED_ERR

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

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

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

The Entity object represents any entity in an XML document. Entities are declarations of abbreviated text or other nodes within an XML document, which can be inserted at various places in an XML document using EntityReference objects.

123

JavaScript Reference

Object: EntityReference

The Entity name is stored in the Node.nodeName property. However, the actual content of the entity is contained within the Entity nodes children. An Entity node has no parent; the Node.parentNode property for an entity will always be null.
Entity nodes and their children are read only and can not be modified once they have been added to a document. If you need to change the content of an Entity object, you must create a new one, then update all the EntityReference objects that referred to the old Entity so that they refer to the new Entity instead.

Entity properties
Property name
notationName

Type String

Description

Status

Availability 4.6 or later

publicId systemId

String String

For unparsed entities, the name of the notation for the read only entity. For parsed entities, the value of this property is null. The public identifier associated with the entity. read only The system identifier associated with this entity. read only

4.6 or later 4.6 or later

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

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

Object: Event
Availability Extended by BlackBerry Device Software version 4.6 or later CustomEvent , MutationEvent , UIEvent

The Event object represents provides contextual information about an event that Event handlers can use, such as the originating element, what stage the event is currently in within the event system, and so forth. The properties and methods exposed by Event are minimal, and provide the basic functionality required by events of all types. More specific event objects should be used to acquire context information specific to a certain event type.

124

JavaScript Reference

Object: Event

For example, the MouseEvent object, which inherits from Event through the UIEvent object, supplies additional properties supplying information such as the MouseEvent.button , MouseEvent.screenX and MouseEvent.screenY for where the current mouse event took place.

Event properties
Property name
bubbles cancelable cancelBubble currentTarget eventPhase

Type boolean boolean boolean

EventTarget

Description When true, the event is a bubbling event. When true, the action of the event can be cancelled using Event.preventDefault() . When true, bubbling of the event is cancelled. The node of the Document object that is currently handling the event. The phase that the event is currently in. Valid values include:
1: Indicates that the event is in the capturing

Status read only read only writable read only read only

Availability 4.6. or later 4.6. or later 4.6. or later 4.6. or later 4.6. or later

unsigned short

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 read only read only 4.6. or later 4.6 or later 4.6 or later

target timeStamp type

EventTarget

unsigned long String

The target node to which the event was dispatched. The time (in milliseconds since epoch) at which the event was created. The name of the event.

Event methods
Method name
initEvent() preventDefault()

Description Initializes the properties of an Event object created by Document.createEvent() . Cancels the event, preventing the default action from occurring.

Availability 4.6 or later 4.6 or later

125

JavaScript Reference

Object: Event

Method name
stopPropagation()

Description Prevents further propagation of this event during an event flow.

Availability 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() . This method must be called before the event has been dispatched using Node.dispatchEvent() .

Syntax
Event.initEvent( eventTypeArg, canBubbleArg, cancelableArg )

Parameters
Parameter
eventTypeArge canBubbleArg cancelableArg

Type String boolean boolean

Description Specifies the event type. When true, this parameter indicates that the event will bubble. When true, this parameter indicates that Event.preventDefault() can cancel the event.

Return values
None.

Exceptions
None.

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

Method: Event.preventDefault()
Availability BlackBerry Device Software version 4.6 or later

The preventDefault() method cancels the event, preventing the default action from occurring.

126

JavaScript Reference

Calling this method for an event whose cancelable property is set to false will have no effect.

Syntax
Event.preventDefault()

Parameters
None.

Return values
None.

Exceptions
None.

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 by any EventListener , the event will no longer propagate through the tree. The event will complete the dispatch to all listeners on the current EventTarget before the event flow stops. This method can be used at any stage of the event flow.

Syntax
Event.stopPropagation()

Parameters
None.

Return values
None.

Exceptions
None.

127

JavaScript Reference

Object: EventListener

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 after it has been used.

EventListener methods
Method name
handleEvent()

Description Called whenever an event occurs the EventListener object was registered to listen for.

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

Syntax
EventListener.handleEvent( evt )

Parameters
Parameter
evt

Type
Event

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

Return values
None.

Exceptions
None.

128

JavaScript Reference

Object: History

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 current browser session.

History properties
Property name
current length

Type String int

Description Returns the complete URL of the current history entry. Returns the number of URLs in the history list.

Status read only read only

Availability 4.6 or later 4.6 or later

History methods
Method name
back() forward() go()

Description

Availability

Displays the previous URL in the BlackBerry Browser History list. 4.6 or later Displays the next element in the BlackBerry Browser History list. 4.6 or later Causes the to display the URL that is the specified number of URLs before or after 4.6 or later the current item in the BlackBerry Browser History list.

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 equivalent to the user clicking Back in the BlackBerry Browser menu or clicking the Escape key during a browser session, or specifying History.go(-1).

Syntax
history.back()

129

JavaScript Reference

Object: History

Parameters
None.

Return values
None.

Exceptions
None.

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

See also
history.forward() , history.go() , window.history

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 equivalent to the user clicking Forward in the BlackBerry Browser menu, or specifying History.go(1).

Syntax
history.forward()

Parameters
None.

Return values
None.

Exceptions
None.

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

See also

130

JavaScript Reference

Object: HTMLAnchorElement

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 URL that is the specified number of URLs before or after the current item in the BlackBerry Browser History list.

Syntax
history.go( targetURLposition )

Parameters
Parameter
targetURLposition

Type int

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

Return values
None.

Exceptions
None.

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

See also
history.back() , history.forward() , window.history

Object: HTMLAnchorElement
Availability BlackBerry Device Software version 4.6 or later

131

JavaScript Reference

Object: HTMLAnchorElement

Extends

HTMLElement

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

HTMLAnchorElement properties
Property name
accessKey charset

Type String String

Description Specifies the keypad key that gives access to the element. Specifies the character encoding used in the referenced document; the value must be the name of a standard character set. Specifies a comma-separated list of the coordinates of HTMLAnchorElement.shape, which defines the active region in an image map. Specifies the URI of the target of the link. Specifies the language code of the target resource. Specifies a name for the anchor. Specifies the link type between the current document and the referenced resource. Specifies the link type between the referenced resource and the current document. Specifies the shape of an active region in an image map. The coordinates of the shape are specified by HTMLAnchorElement.coords. Specifies the elements position in the tabbing order. Specifies the frame in which to render the target document. Specifies the MIME type of the target document.

Status writable writable

Availability 4.6 or later 4.6 or later

coords

String

writable

4.6 or later

href hreflang name rel rev shape

String String String String String String

writable writable writable writable writable writable

4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

tabIndex target type

int String String

writable writable writable

4.6 or later 4.6 or later 4.6 or later

132

JavaScript Reference

Object: HTMLAnchorElement

HTMLAnchorElement methods
Method name
blur() focus()

Description Removes keypad focus from the element. Gives keypad focus to the element.

Availability 4.6 or later 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.

Syntax
HTMLAnchorElement.blur()

Parameters
None.

Return values
None.

Exceptions
None.

Method: HTMLAnchorElement.focus()
Availability BlackBerry Device Software version 4.6 or later

The focus() method removes keypad focus from the element.

Syntax
HTMLAnchorElement.focus()

Parameters
None.

Return values

133

JavaScript Reference

Object: HTMLAreaElement

None.

Exceptions
None.

Object: HTMLAreaElement
Availability Extends BlackBerry Device Software version 4.6 or later
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
accessKey alt coords

Type String String String

Description Specifies the keypad key that gives access to the element. Specifies alternate text that is rendered when the normal content of the element is not. Specifies a comma-separated list of the coordinates for HTMLAreaElement.shape, which defines the active region in an image map. Specifies the URI of the target of the link. When true, indicates that the area is inactive and does not link to another resource. Specifies the shape of an active region in an image map. The coordinates of the shape are specified by HTMLAreaElement.coords. Specifies the elements position in the tabbing order. Specifies the frame in which to render the target document.

Status writable writable writable

Availability 4.6 or later 4.6 or later 4.6 or later

href noHref shape

String boolean String

writable writable writable

4.6 or later 4.6 or later 4.6 or later

tabIndex target

int String

writable writable

4.6 or later 4.6 or later

134

JavaScript Reference

Object: HTMLAppletElement

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

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

on the document layout.

HTMLAppletElement properties
Property name
align alt archive code codeBase height hspace name object

Type String String String String String String int String String

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

Status writable writable writable writable writable writable writable writable writable

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

vspace

int

writable

4.6 or later

135

JavaScript Reference

Object: HTMLBaseElement

Property name
width

Type String

Description Specifies the width of the object.

Status writable

Availability 4.6 or later

Object: HTMLBaseElement
Availability Extends BlackBerry Device Software version 4.6 or later
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
href target

Type String String

Description

Status

Availability 4.6 or later 4.6 or later

Specifies the base URI used to resolve all relative URLs writable in the document. Specifies the frame in which to render target documents writable by default.

Object: HTMLBaseFontElement
Availability Extends BlackBerry Device Software version 4.6 or later
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
color

Type String

Description Specifies the color of the base font.

Status writable

Availability 4.6 or later

136

JavaScript Reference

Object: HTMLBodyElement

Property name
face size

Type String String

Description Specifies a list of font names, listed in order of preference, in which the base font is rendered. Specifies the size of the base font.

Status writable writable

Availability 4.6 or later 4.6 or later

Object: HTMLBodyElement
Availability Extends BlackBerry Device Software version 4.6 or later
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
aLink background bgColor link text vlink

Type String String String String String String

Description Specifies the color of active links. Specifies the URI of an image to use as the page background. Specifies the background color for the page body. Specifies the color of unvisited links. Specifies the color of the body text. Specifies the color of visited links.

Status writable writable writable writable writable writable

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

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

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

137

JavaScript Reference

Object: HTMLButtonElement

HTMLBRElement properties
Property name
clear

Type String

Description Specifies the control flow of text around adjacent floats.

Status writable

Availability 4.6 or later

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

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

HTMLButtonElement properties
Property name
accessKey disabled form name

Type String boolean

HTMLFormEleme nt

Description Specifies the key that gives access to the form control. When true, indicates that the form control is not available. Returns the parent <form> element for the form control. Specifies the name of the form control. This is the name portion of the name-value pair that is submitted with the form. Specifies the tabbing order of the form control. Returns the type of form control. The value for this property may be button, reset, or submit. Specifies the current value of the form control. This is the value portion of the name-value pair that is submitted with the form.

Status writable writable read only writable

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later

String

tabIndex type value

int String String

writable read only writable

4.6 or later 4.6 or later 4.6 or later

138

JavaScript Reference

Object: HTMLCollection

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 are automatically updated when the underlying document is changed. You can access an individual node within a collection by its index position using HTMLCollection.item() , by its name or id attribute using HTMLCollection.namedItem() , or you can index the object directly. For example, if you create an instance of a HTMLCollection object called myHTMLNodes, then specifying
myHTMLNodes.item(2) myHTMLNodes.namedItem(item)

is equivalent to specifying
myHTMLNodes[2] myHTMLNodes[item]

HTMLCollection properties
Property name
length

Type int

Description Returns the number of nodes in the list.

Status read only

Availability 4.6 or later

HTMLCollection methods
Method name
item() namedItem()

Description Returns the node at the specified index. Retrieves the node with the given name from the collection.

Availability 4.6 or later 4.6 or later

139

JavaScript Reference

Object: HTMLCollection

Method: HTMLCollection.item()
Availability BlackBerry Device Software version 4.6 or later

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

Syntax
HTMLCollection.item( index )

Parameters
Parameter
index

Type int

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

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

Exceptions
None.

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 given name, then searches for a node with a name attribute that matches the given name if no matching id attribute exists. When searching HTML documents, this method is case insensitive. If the document is an XHTML document, this method only searches for nodes with an id attribute that matches the given name. When searching XHTML documents, this method is case sensitive.

Syntax

140

JavaScript Reference

Object: HTMLDataListElement

HTMLCollection.namedItem( name )

Parameters
Parameter
name

Type String

Description The name of the node to retrieve.

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

Exceptions
None.

Object: HTMLDataListElement
Availability Extends BlackBerry Device Software version 4.7.1 or later
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
options

Type
HTMLCollectio n

Description Returns a list of the options contained by the HTMLDataList object.

Status read-only

Availability 4.7.1 or later

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

The HTMLDirectoryElement object represents a <dir> element in an HTML document. The <dir> element specifies that the enclosed text is a directory list.

141

JavaScript Reference

Object: HTMLDivElement

HTMLDirectoryElement properties
Property name
compact

Type boolean

Description

Status

Availability 4.6 or later

When true, indicates reduced spacing between list items. writable

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

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

HTMLDivElement properties
Property name Type
align

Description

Status

Availability 4.6 or later

String

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

Object: HTMLDListElement
Availability Extends BlackBerry Device Software version 4.6 or later
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.

142

JavaScript Reference

Object: HTMLDocument

HTMLDListElement properties
Property name
compact

Type boolean

Description

Status

Availability 4.6 or later

When true, indicates reduced spacing between list items. writable

Object: HTMLDocument
Availability Extends BlackBerry Device Software version 3.8 or later
Document

The HTMLDocument object provides access to the HTML hierarchy.

HTMLDocument properties
Property name Type
anchors HTMLCollecti on applets HTMLCollecti on

Description

Status

Availability 3.8 or later

body

HTMLElement

Returns an index of the <a> elements contained within read only the document. Index positions begin at 0 and continue to HTMLCollection.length -1. Returns an index of the <applet> elements and read only <object> elements containing applets contained within the document. Index positions begin at 0 and continue to HTMLCollection.length -1. Returns the element that contains the content of the writable 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.

3.8 or later

3.8 or later

143

JavaScript Reference

Object: HTMLDocument

Property name Type

compatMode

Description

Status

Availability 3.8 or later

String

cookie

String

Returns whether or not this document is rendered in strict read only mode. A value of CSS1Compat indicates strict mode is enforced. A value of BackCompat indicates that strict mode is not enforced. When the BlackBerry Browser reads this property, it writable 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. Specifies the domain name from which the document was served. Returns an index of the <form> elements contained within the document. Index positions begin at 0 and continue to HTMLCollection.length -1. Returns an index of the <img> elements contained within the document. Index positions begin at 0 and continue to HTMLCollection.length -1. Returns an index of the <link> elements contained in the document. Index positions begin at 0 and continue to HTMLCollection.length -1. Specifies information about the URI of the document. Returns the URL of the document that linked to the active document. Specifies the text contained within the <title> element of the active document. Returns the complete URL of the active document.

3.8 or later

domain forms

String
HTMLCollecti on

writable read only

3.8 or later 3.8 or later

images

HTMLCollecti on

read only

3.8 or later

links

HTMLCollecti on

read only

3.8 or later

location referrer title URL

Location

String String String

writable read only writable read only

3.8 or later 3.8 or later 3.8 or later 3.8 or later

144

JavaScript Reference

Object: HTMLDocument

HTMLDocument event handlers

Property name
onblur

Type
EventListene r

Description Specifies the function to perform when an element loses focus by either the pointer or by tabbed navigation. Specifies the function to perform when a form control loses focus after the user has modified the value. Specifies the function to perform when the user clicks the trackball or trackwheel on a BlackBerry device. Specifies the function to perform when an element gains focus by either the pointer or by tabbed navigation. Specifies the function to perform when a key is pressed down while the pointer is over an element. Specifies the function to perform when a key is pressed and released while the pointer is over an element. Specifies the function to perform when a key is released while the pointer is over an element.

Status writable

Availability 4.6 or later

onchange

EventListene r

writable

4.6 or later

onclick

EventListene r

writable

3.8 or later

onfocus

EventListene r

writable

4.6 or later

onkeydown

EventListene r

writable

4.6 or later

onkeypress

EventListene r

writable

4.6 or later

onkeyup

EventListene r

writable

4.6 or later

145

JavaScript Reference

Object: HTMLDocument

Property name
onmousedown

Type
EventListene r

Description Specifies the function to perform when the user depresses the trackwheel or trackball on a BlackBerry device. Specifies the function to perform when the user moves the pointer over an element. Specifies the function to perform when the user moves the pointer off of an element. Specifies the function to perform when the user moves the pointer over an element. Specifies the function to perform when the user releases the trackwheel or trackball on a BlackBerry device. Specifies the function to perform when the user resets a form. Specifies the function to perform when the user selects some text in a text field. Specifies the function to perform when the user submits a form.

Status writable

Availability 3.8 or later

onmousemove

EventListene r

writable

4.6 or later

onmouseout

EventListene r

writable

4.6 or later

onmouseover

EventListene r

writable

4.6 or later

onmouseup

EventListene r

writable

4.6 or later

onreset

EventListene r

writable

3.8 or later

onselect

EventListene r

writable

4.6 or later

onsubmit

EventListene r

writable

3.8 or later

HTMLDocument methods
Method name
close()

Description

Availability

Closes the document opened by HTMLDocument.open() and forces rendering. 3.8 or later

146

JavaScript Reference

Object: HTMLDocument

Method name
getElementByName () open() write() writeln()

Description Returns an array of all the elements in the document with the specified name. Opens a document stream for writing. Writes a string of text to a document stream opened by HTMLDocument.open () . Writes a string of text, followed by a new line character to a document stream opened by HTMLDocument.open() .

Availability 4.6 or later 3.8 or later 3.8 or later 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.

Syntax
HTMLDocument.close()

Parameters
None.

Return values
None.

Exceptions
None.

See also
HTMLDocument.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:

147

JavaScript Reference

Object: HTMLDocument

If the document is an HTML document, this method returns all elements with the specified name. When searching HTML documents, this element is case-insensitive. If the document is an XHTML document, this method only returns form control elements with the specified name. When searching XHTML documents, this method is case sensitive.

Syntax
HTMLDocument.getElementsByName( elementName )

Parameters
Parameter
elementName

Type String

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

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

Exceptions
None.

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

Method: HTMLDocument.open()
Availability BlackBerry Device Software version 3.8 or later

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

Syntax
HTMLDocument.open()

Parameters
None.

Return values
None.

Exceptions

148

JavaScript Reference

Object: HTMLDocument

None.

See also
HTMLDocument.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() .

Syntax
HTMLDocument.write( text )

Parameters
Parameter
text

Type String

Description The text to be parsed.

Return values
None.

Exceptions
None.

See also
HTMLDocument.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 by HTMLDocument.open() .

Syntax
HTMLDocument.writeln( text )

Parameters

149

JavaScript Reference

Object: HTMLElement

Parameter
text

Type String

Description The text to be parsed.

Return values
None.

Exceptions
None.

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

Object: HTMLElement
Availability Extends Extended by BlackBerry Device Software version 4.6 or later
Element 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 ,

150

JavaScript Reference

Object: HTMLElement

HTMLTableCellElement , HTMLTableColElement , HTMLTableElement , HTMLTableRowElement , HTMLTableSectionElement , HTMLTextAreaElement , HTMLTitleElement , HTMLUListElement

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

HTMLElement properties
Property name Type
className dir id innerHTML

Description Specifies the class attribute of an element. Specifies the dir attribute of an element. Specifies the id attribute of an element. 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. Specifies the lang attribute of an element. Returns the height of the element, in pixels. Returns the number of pixels the left edge of the element is offset from the left edge of the containing element. 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. Returns the number of pixels the top edge of the element is offset from the top edge of the containing element. Returns the width of the element, in pixels.

Status writable writable writable writable

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later

String String String String

lang offsetHeig ht offsetLeft

String int int

writable read only read only

4.6 or later 4.6 or later 4.6 or later

offsetPare nt

Node

read only

4.6 or later

offsetTop

int

read only

4.6 or later

offsetWidt h

int

read only

4.6 or later

151

JavaScript Reference

Object: HTMLElement

Property name Type

style title CSSStyleDecla ration

Description

Status

Availability 4.6 or later 4.6 or later

String

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

HTMLElement event handlers

Property name
onblur

Type
EventListen er

Description Specifies the function to perform when an element loses focus by either the pointer or by tabbed navigation. Specifies the function to perform when a form control loses focus after the user has modified the value. Specifies the function to perform when the user clicks the trackball or trackwheel on a BlackBerry device. Specifies the function to perform when an element gains focus by either the pointer or by tabbed navigation. Specifies the function to perform when a key is pressed down while the pointer is over an element. Specifies the function to perform when a key is pressed and released while the pointer is over an element.

Status writable

Availability 4.6 or later

onchange

EventListen er

writable

4.6 or later

onclick

EventListen er

writable

4.6 or later

onfocus

EventListen er

writable

4.6 or later

onkeydown

EventListen er

writable

4.6 or later

onkeypress

EventListen er

writable

4.6 or later

152

JavaScript Reference

Object: HTMLElement

Property name
onkeyup

Type
EventListen er

Description Specifies the function to perform when a key is released while the pointer is over an element. Specifies the function to perform when the BlackBerry Browser finishes loading a new page or a complete frameset. Specifies the function to perform when the user depresses the trackwheel or trackball on a BlackBerry device. Specifies the function to perform when the user moves the pointer over an element. Specifies the function to perform when the user moves the pointer off of an element. Specifies the function to perform when the user moves the pointer over an element. Specifies the function to perform when the user releases the trackwheel or trackball on a BlackBerry device. Specifies the function to perform when the user resets a form. Specifies the function to perform when the user selects some text in a text field.

Status writable

Availability 4.6 or later

onload

EventListen er

writable

4.6 or later

onmousedown

EventListen er

writable

4.6 or later

onmousemove

EventListen er

writable

4.6 or later

onmouseout

EventListen er

writable

4.6 or later

onmouseover

EventListen er

writable

4.6 or later

onmouseup

EventListen er

writable

4.6 or later

onreset

EventListen er

writable

4.6 or later

onselect

EventListen er

writable

4.6 or later

153

JavaScript Reference

Object: HTMLFieldsetElement

Property name
onsubmit

Type
EventListen er

Description Specifies the function to perform when the user submits a form. Specifies the function to perform when the BlackBerry Browser removes a new page or a frameset.

Status writable

Availability 4.6 or later

onunload

EventListen er

writable

4.6 or later

Object: HTMLFieldsetElement
Availability Extends BlackBerry Device Software version 4.6 or later
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
form HTMLFormEleme nt

Description Returns the parent <form> element for the form control.

Status read only

Availability 4.6 or later

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

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

154

JavaScript Reference

Object: HTMLFormElement

HTMLFontElement properties
Property name
color face size

Type String String String

Description Specifies the color of the font. Specifies a list of font names, listed in order of preference, in which the font is rendered. Specifies the size of the font.

Status writable writable writable

Availability 4.6 or later 4.6 or later 4.6 or later

Object: HTMLFormElement
Availability Extends BlackBerry Device Software version 4.6 or later
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
acceptCharset action elements

Type String String

HTMLCollecti on

Description

Status

Availability 4.6.0 4.6.0 4.6.0

Specifies a list of valid character sets for form data. writable Specifies a URI to which the form is submitted. writable Returns an index of the form control elements read only 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.

155

JavaScript Reference

Object: HTMLFormElement

Property name
enctype length method name target

Type String int String String String

Description Specifies the content type the form data is encoded with. Returns the number of form control elements contained within the form. Specifies the HTTP method used to send the data to the server. Specifies a unique name for the form. Specifies where the target document is opened.

Status writable read only writable read only writable

Availability 4.6.0 4.6.0 4.6.0 4.6.0 4.6.0

HTMLFormElement methods
Method name
item() namedItem() reset() submit()

Description Returns the form control element at he specified index of the collection. Retrieves the form control element or elements whose id or name attributes that match the given name from the collection. Restores the default values to the form element. Submits the current values of the form element.

Availability 4.7.1 or later 4.7.1 or later 4.6 or later 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.elements collection. Image buttons (<input> elements for which type="image") are not included in the collection, and are therefore not returned with this method. This method is equivalent to invoking HTMLFormElement.elements[ index ].

Syntax
HTMLFormElement.item( index )

Parameters

156

JavaScript Reference

Object: HTMLFormElement

Parameter
index

Type int

Description Specifies the index position of the element to be returned. Valid values are from 0 and HTMLFormElement.elements -1.

Return values
This method returns the element at the index th position in the HTMLFormElement.elements collection, or null if an invalid index position is specified.

Exceptions
None.

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 specified name from the HTMLFormElement.elements collection. Image buttons (<input> elements for which type="image") are not included in the collection, and are therefore not returned with this method. This method is equivalent to invoking HTMLFormElement.elements["name"].

Syntax
HTMLFormElement.namedItem( name )

Parameters
Parameter
name

Type String

Description Specifies the name of the element to retrieve.

Return values
This method returns the element that has an id or name attribute of name , or null if no element with the specified name exists within the HTMLFormElement.elements collection. If multiple elements match, this method returns a NodeList object that contains all the matching elements.

Exceptions
None.

157

JavaScript Reference

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 clicking a Reset button.

Syntax
HTMLFormElement.reset()

Parameters
None.

Return values
None.

Exceptions
None.

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 clicking a Submit button.

Syntax
HTMLFormElement.submit()

Parameters
None.

Return values
None.

Exceptions
None.

158

JavaScript Reference

Object: HTMLFrameElement

Object: HTMLFrameElement
Availability Extends BlackBerry Device Software version 4.6 or later
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
contentDocumen t contentWindow frameBorder longDesc marginHeight marginWidth name noResize scrolling src Window

Type
Document

Description Returns a reference to the Document object that the frame contains. Returns a reference to the Window object that contains the frame. Specifies whether or not a separator is displayed around the frame. Specifies a URL where the content of the frame is described. Specifies the top and bottom margins for the frame. The value must be greater than 0. Specifies the left and right margins of the frames. The value must be greater than 0. Specifies a unique name for the frame. When true, indicates that the user cannot resize the frame. Specifies the scrolling behavior. Specifies the URL of the source content for the frame.

Status read only read only writable writable writable writable writable writable writable writable

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

String String String String String boolean String String

Object: HTMLFrameSetElement
Availability BlackBerry Device Software version 4.6 or later

159

JavaScript Reference

Object: HTMLHeadElement

Extends

HTMLElement

The HTMLFrameSetElement object represents a <frame> element in an HTML document. The <frameset> element presents multiple documents within a single browser window, and defines the layout of the contained frames.

HTMLFrameSetElement properties
Property name Type
cols rows

Description Specifies the layout of columns in the frameset. Specifies the layout of rows in the frameset.

Status writable writable

Availability 4.6 or later 4.6 or later

String String

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

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

HTMLHeadElement properties
Property name
profile

Type String

Description Specifies the URLs that contain metadata about the document.

Status writable

Availability 4.6 or later

Object: HTMLHeadingElement
Availability BlackBerry Device Software version 4.6 or later

160

JavaScript Reference

Object: HTMLHRElement

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
align

Type String

Description Specifies the horizontal alignment of the heading text.

Status writable

Availability 4.6 or later

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

The HTMLHRElement object represents an <hr> element in an HTML document. The <hr> element renders a horizontal line.

HTMLHRElement properties
Property name Type
align noShade size width

Description Specifies the horizontal alignment of the horizontal line on the page. When true, indicates that no shading is applied to the horizontal line. Specifies the height of the horizontal line. Specifies the width of the horizontal line.

Status writable writable writable writable

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later

String boolean String String

Object: HTMLHtmlElement
Availability BlackBerry Device Software version 4.6 or later

161

JavaScript Reference

Object: HTMLIFrameElement

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
version

Description

Status

Availability 4.6 or later

String

Specifies version information about the document DTD. writable

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

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

HTMLIFrameElement properties
Property name
align contentDocumen t contentWindow frameBorder height longDesc Window

Type String
Document

Description Specifies the horizontal alignment of the horizontal line on the page. Returns a reference to the Document object that the frame contains. Returns a reference to the Window object that contains the frame. Specifies whether or not a separator is displayed around the frame. Specifies the height of the frame. Specifies a URL where the content of the frame is described.

Status writable read only writable writable writable writable

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

String String String

162

JavaScript Reference

Object: HTMLImageElement

Property name
marginHeight marginWidth name scrolling src width

Type String String String String String String

Description Specifies the top and bottom margins for the frame. The value must be greater than 0. Specifies the left and right margins of the frames. The value must be greater than 0. Specifies a unique name for the frame. Specifies the scrolling behavior. Specifies the URL of the source content for the frame. Specifies the width of the frame.

Status writable writable writable writable writable writable

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

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

The HTMLImageElement object represents an <img> element in an HTML document. The <img> element defines an image to display.

HTMLImageElement properties
Property name
align alt border height hspace isMap

Type String String String int int boolean

Description Specifies the vertical or horizontal alignment of the image on the page. Specifies the text that appears when an image is unavailable or cannot be displayed. Specifies the width of a border around an image. Specifies the width of a border around an image. Specifies the amount of whitespace padding added to the left and right of the image. When true, indicates that the image uses a serverside image map.

Status writable writable writable writable writable writable

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

163

JavaScript Reference

Object: HTMLInputElement

Property name
longDesc name src usemap vspace width

Type String String String String int int

Description Specifies the URI of a document that provides a long description of the image. Specifies a unique name for the image. Specifies the URI of the source image. Specifies the client-side map to use with this image. Specifies the amount of whitespace padding added to the top and bottom of the image. Specifies the width of the image, with the unit of measurement.

Status writable writable writable writable writable writable

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

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

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

HTMLInputElement properties
Property name
accept accessKey align alt

Type String String String String

Description Specifies a comma-separated list of content types that this form accepts. Specifies the keypad key that gives access to the element. Specifies the vertical or horizontal alignment of the image on the page. When HTMLInputElement.type has a value of image, specifies the text that appears when an image is unavailable or cannot be displayed.

Status writable writable writable writable

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later

164

JavaScript Reference

Object: HTMLInputElement

Property name
checked

Type boolean

Description

Status

Availability 4.6 or later

defaultChecked

boolean

When true and HTMLInputElement.type has writable 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. When true and HTMLInputElement.type has writable 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. When HTMLInputElement.type has a value writable 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. When true, indicates that the form control is not available. Returns the parent <form> element for the form control. Returns the associated <datalist> element containing the list of value suggestions, if one exists. If no associated <datalist> element exists, this property returns null. 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. Specifies the amount of whitespace padding added to the top and bottom of the image. 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.

4.6 or later

defaultValue

String

4.6 or later

disabled form list

boolean
HTMLFormEle ment HTMLElement

writable read only read only

4.6 or later 4.6 or later 4.7.1 or later

maxLength

int

writable

4.6 or later

name readonly

String boolean

writable writable

4.6 or later 4.6 or later

165

JavaScript Reference

Object: HTMLInputElement

Property name
size src tabIndex type

Type int String int String

Description Specifies the size of the form control. When HTMLInputElement.type has a value of image, specifies the URI of the source image. Specifies the elements position in the tabbing order. 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)

Status writable writable writable writable

Availability 4.6 or later 4.6 or later 4.6 or later typedependent

useMap

String

When HTMLInputElement.type has a value of writable image, specifies the client-side map to use with this image.

4.6 or later

166

JavaScript Reference

Object: HTMLInputElement

Property name
value

Type String

Description Specifies the current value of the form control. This is the value portion of the name-value pair that is submitted with the form. 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 timebased input types, excluding the datetimelocal input type. Specifies the value of the element interpreted as a number. This property can be used with the number and range input types.

Status writable

Availability 4.6 or later

valueAsDate

long

writable

4.7.1 or later

valueAsNumber

float

writable

4.7.1 or later

HTMLInputElement methods
Method name
blur() click() focus() select() stepDown() stepUp()

Description Removes keypad focus from the element. Simulates a mouse click. Gives keypad focus to the element. Selects the contents of the element. Reduces the value of the form control element by the given value. Increases the value of the form control element by the given value.

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.7.1 or later 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

167

JavaScript Reference

Object: HTMLInputElement

HTMLInputElement.blur()

Parameters
None.

Return values
None.

Exceptions
None.

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.

Syntax
HTMLInputElement.click()

Parameters
None.

Return values
None.

Exceptions
None.

Method: HTMLInputElement.focus()
Availability BlackBerry Device Software version 4.6 or later

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

Syntax
HTMLInputElement.focus()

Parameters

168

JavaScript Reference

Object: HTMLInputElement

None.

Return values
None.

Exceptions
None.

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.type has a value of file, password, or text.

Syntax
HTMLInputElement.select()

Parameters
None.

Return values
None.

Exceptions
None.

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.

Syntax
HTMLInputElement.stepDown( increment )

Parameters
Parameter
increment

Type long

Description Specifies the amount by which the value is decreased.

169

JavaScript Reference

Object: HTMLIsIndexElement

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 values
None.

Exceptions
None.

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.

Syntax
HTMLInputElement.stepUp( increment )

Parameters
Parameter
increment

Type long

Description 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 values
None.

Exceptions
None.

Object: HTMLIsIndexElement
Availability BlackBerry Device Software version 4.6 or later

170

JavaScript Reference

Object: HTMLLabelElement

Extends

HTMLElement

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

HTMLIsIndexElement properties
Property name Type
form prompt HTMLFormElem ent

Description Returns the parent <form> element for the form control. Specifies the prompt message.

Status read only writable

Availability 4.6 or later 4.6 or later

String

Object: HTMLLabelElement
Availability Extends BlackBerry Device Software version 4.6 or later
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 name
accessKey form

Type String
HTMLFormEle ment

Description

Status

Availability 4.6 or later 4.6 or later

Specifies the keypad key that gives access to the element. writable Returns the parent <form> element for the form control. read only

171

JavaScript Reference

Object: HTMLLegendElement

Property name
htmlFor

Type String

Description

Status

Availability 4.6 or later

Specifies the form control with which the label is writable associated. The value must be the value of the id attribute of the related element.

Object: HTMLLegendElement
Availability Extends BlackBerry Device Software version 4.6 or later
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
accessKey align form

Description

Status

Availability 4.6 or later 4.6 or later 4.6 or later

String String
HTMLFormElem ent

Specifies the keypad key that gives access to the element. writable Specifies the horizontal or vertical alignment of the writable caption relative to the parent <fieldset> element. Returns the parent <form> element for the form control. read only

Object: HTMLLIElement
Availability Extends BlackBerry Device Software version 4.6 or later
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.

172

JavaScript Reference

Object: HTMLLinkElement

HTMLIElement properties
Property name Type
type value

Description Specifies the bullet or number style for the list. 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.

Status writable writable

Availability 4.6 or later 4.6 or later

String int

Object: HTMLLinkElement
Availability Extends BlackBerry Device Software version 4.6 or later
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
charset

Description Specifies the character encoding used in the referenced document; the value must be the name of a standard character set. When true, indicates that this link is disabled. Specifies the target of the link. Specifies the base language of the target document. Specifies the destination medium for the link. Specifies the relationship between the current page and the referenced document. For example, stylesheet. Describes a link relationship from the referenced target document to the source document.

Status writable

Availability 4.6 or later

String

disabled href hreflang media rel

boolean String String String String

writable writable writable writable writable

4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

rev

String

writable

4.6 or later

173

JavaScript Reference

Object: HTMLMapElement

Property name Type

sheet target StyleShe et

Description The StyleSheet object associated with the element.

Status read only

Availability 4.6 or later 4.6 or later

String

Specifies where the target document will be opened. The writable 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.

Object: HTMLMapElement
Availability Extends BlackBerry Device Software version 4.6 or later
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
areas

Type
HTMLCollecti on

Description

Status

Availability 4.6 or later

name

String

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

4.6 or later

174

JavaScript Reference

Object: HTMLMenuElement

Object: HTMLMenuElement
Availability Extends BlackBerry Device Software version 4.6 or later
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
compact

Description When true, indicates reduced spacing between list items.

Status writable

Availability 4.6 or later

boolean

Object: HTMLMetaElement
Availability Extends BlackBerry Device Software version 4.6 or later
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
content httpEquiv name scheme

Type String String String String

Description Specifies the value of a property. Specifies the HTTP response header name. Specifies the name used to identify the meta information. Specifies the name of the scheme used to interpret the value of the content property.

Status writable writable writable writable

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later

175

JavaScript Reference

Object: HTMLModElement

Object: HTMLModElement
Availability Extends BlackBerry Device Software version 4.6 or later
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
cite dateTime

Type String String

Description Specifies the URI of a document that explains why the text was modified. Specifies the date and time that the enclosed text was modified.

Status writable writable

Availability 4.6 or later 4.6 or later

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

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

HTMLObjectElement properties
Property name
align archive

Type String String

Description

Status

Availability 4.6 or later 4.6 or later

Specifies the horizontal or vertical alignment of writable the object. Specifies a whitespace-separated list of URLs for writable archives which contain resources for the object.

176

JavaScript Reference

Object: HTMLObjectElement

Property name
border code codeBase codeType contentDocumen t data declare form

Type String String String String

Document

Description Specifies the width of the border around the object. Specifies the location of the class ID for the object. Specifies the root location for the objects code and data. Specifies the MIME type for the data downloaded for use by the object. Returns the document this object contains, if there is one. If the object contains no document, this property returns null. Specifies the URI that defines the location of the objects data. When true, indicates that this object should be declared, but not instantiated. Returns the form that contains this object. If the object is not contained by a form, this property returns null. Specifies the height of the object. Specifies the amount of whitespace, in pixels, inserted to the left and right of the object. Specifies the name for the object. Specifies text to display while the object is loading. Specifies the object's position in the tabbing order. Specifies the MIME type for the data specified by the data property. Specifies the location of a client side map used with the object, if the object is an image. Specifies the amount of white space, in pixels, inserted above and below the object. Specifies the width of the object.

Status writable writable writable writable read only

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

String boolean
HTMLFormEleme nt

writable writable writable

4.6 or later 4.6 or later 4.6 or later

height hspace name standby tabIndex type useMap vspace width

String int String String int String String int String

writable writable writable writable writable writable writable writable writable

4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

177

JavaScript Reference

Object: HTMLOListElement

Object: HTMLOListElement
Availability Extends BlackBerry Device Software version 4.6 or later
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
compact start type

Type boolean int String

Description

Status

Availability 4.6 or later 4.6 or later 4.6 or later

When true, indicates reduced spacing between list writable items. Specifies the starting value for the numbering sequence. writable Specifies the numbering style to use. writable

Object: HTMLOptGroupElement
Availability Extends BlackBerry Device Software version 4.6 or later
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
disabled label

Type
boolean

Description

Status

Availability 4.6 or later 4.6 or later

String

When true, indicates that the option group is disabled. writable Specifies a label for the option group. writable

178

JavaScript Reference

Object: HTMLOptionElement

Object: HTMLOptionElement
Availability Extends BlackBerry Device Software version 4.6 or later
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
defaultSelect ed disabled form

Type boolean boolean

HTMLFormElem ent

Description When true, indicates that the option is selected by default. When true, indicates that the option is not available. Returns the form that contains the option. If this element is not contained by a form, this property returns null. Returns the position of this option within the parent <select> element. Specifies a label for the option. When true, indicates that the option is currently selected. Specifies the text contained within the <option> element. Specifies the value of the option that is sent to the server when the form is submitted.

Status writable writable read only

Availability 4.6 or later 4.6 or later 4.6 or later

index label selected text value

int String boolean String String

read only writable writable writable writable

4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

Object: HTMLOptionsCollection
Availability BlackBerry Device Software version 4.6 or later

179

JavaScript Reference

Object: HTMLOptionsCollection

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. For example, if you create an instance of a HTMLOptionsCollection object called myHTMLOptions, then specifying
myHTMLOptions.item(2) myHTMLOptions.namedItem(item)

is equivalent to specifying
myHTMLOptions[2] myHTMLOptions[item]

HTMLOptionsCollection properties
Property name
length

Type int

Description Returns the number of HTMLOptionElement objects contained in the list.

Status read only

Availability 4.6 or later

HTMLOptionsCollection methods
Method name
item() namedItem()

Description

Availability

Retrieves a specific option node, by index, from the collection. 4.6 or later Retrieves the option node with the given name or id property value from the 4.6 or later collection.

Method: HTMLOptionsCollection.item()
Availability BlackBerry Device Software version 4.6 or later

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

Syntax

180

JavaScript Reference

Object: HTMLOptionsCollection

HTMLOptionsCollection.item( index )

Parameters
Parameter
index

Type int

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

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

Exceptions
None.

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 given name, then searches for a node with a name attribute that matches the given name if no matching id attribute exists. When searching HTML documents, this method is case insensitive. If the document is an XHTML document, this method only searches for nodes with an id attribute that matches the given name. When searching XHTML documents, this method is case sensitive.

Syntax
HTMLOptionsCollection.namedItem( name )

Parameters
Parameter
name

Type String

Description The name of the node to retrieve.

Return values

181

JavaScript Reference

Object: HTMLOptionsCollection

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

Exceptions
None.

Method: HTMLOptionsCollection.item()
Availability BlackBerry Device Software version 4.6 or later

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

Syntax
HTMLOptionsCollection.item( index )

Parameters
Parameter
index

Type int

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

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

Exceptions
None.

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 given name, then searches for a node with a name attribute that matches the given name if no matching id attribute exists. When searching HTML documents, this method is case insensitive.

182

JavaScript Reference

Object: HTMLParagraphElement

If the document is an XHTML document, this method only searches for nodes with an id attribute that matches the given name. When searching XHTML documents, this method is case sensitive.

Syntax
HTMLOptionsCollection.namedItem( name )

Parameters
Parameter
name

Type String

Description The name of the node to retrieve.

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

Exceptions
None.

Object: HTMLParagraphElement
Availability Extends BlackBerry Device Software version 4.6 or later
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
align

Type String

Description Specifies the horizontal alignment of the paragraph on the page.

Status writable

Availability 4.6 or later

183

JavaScript Reference

Object: HTMLParamElement

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

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

HTMLParamElement properties
Property name
name type value valueType

Type String String String String

Description Specifies a unique name for the parameter. Specifies the content type. Specifies the value of the parameter. 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

Status writable writable writable writable

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later

a string.
object: The specified value is an object

declaration in the same document. ref: The value is a URI that specifies where the runtime values are located.

Object: HTMLPreElement
Availability Extends BlackBerry Device Software version 4.6 or later
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.

184

JavaScript Reference

Object: HTMLQuoteElement

HTMLPreElement properties
Property name
width

Type int

Description Specifies the width of the content block.

Status writable

Availability 4.6 or later

Object: HTMLQuoteElement
Availability Extends BlackBerry Device Software version 4.6 or later
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
cite

Type String

Description Specifies a URL citation to indicate the source of the quotation.

Status writable

Availability 4.6 or later

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

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

185

JavaScript Reference

Object: HTMLSelectElement

HTMLScriptElement properties
Property name
charset defer

Type String boolean

Description Specifies the character encoding used in the script. When true, indicates that the script does not generate any document content and that the BlackBerry Browser can therefore defer processing the script. This property is not currently defined in the DOM HTML specification. This property is not currently defined in the DOM HTML specification. Specifies the URI where an external script document is located. Specifies the script content. 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.

Status writable writable

Availability 4.6 or later 4.6 or later

event htmlFor src text type

String String String String String

undefined undefined writable writable writable

4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

Object: HTMLSelectElement
Availability Extends BlackBerry Device Software version 4.6 or later
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.

186

JavaScript Reference

Object: HTMLSelectElement

HTMLSelectElement properties
Property name
disabled form

Type boolean
HTMLFormElement

Description When true, indicates that the form control is not available. Returns the form that contains the form control. If this element is not contained by a form, this property returns null. Specifies the number of <option> elements the selection list contains. When true, indicates that more than one option may be selected from the list. Specifies the name of the form control. This is the name portion of the name-value pair that is submitted with the form. Returns an index of the <option> elements contained within the selection list. Index positions begin at 0 and continue to HTMLOptionsCollection.length -1. Specifies the index position of the selected option. Specifies the number of visible rows. Specifies the tabbing order of the form control. Returns the type of form control. The value returned depends on the value of HTMLSelectElement.multiple: When
HTMLSelectElement.multiple has

Status writable read only

Availability 4.6 or later 4.6 or later

length multiple name

int boolean String

writable writable writable

4.6 or later 4.6 or later 4.6 or later

options

HTMLOptionsCollec tion

read only

4.6 or later

selectIndex int size tabIndex type

writable writable writable read only

4.6 or later 4.6 or later 4.6 or later 4.6 or later

int int String

a value of true, the value for this property is select-multiple.

187

JavaScript Reference

Object: HTMLSelectElement

Property name

Type

Description When
HTMLSelectElement.multiple has

Status

Availability

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 namevalue pair that is submitted with the form.

writable

4.6 or later

Methods
Method name
add() blur() focus() remove()

Description Adds a new option to the selection list. Removes keypad focus from the element. Gives keypad focus to the element. 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, this method functions the same as Node.insertBefore() .

Syntax
HTMLSelectElement.add( element, before )

Parameters
Parameter
element before

Type
HTMLElement HTMLElement

Description The element to insert. The existing child element before which element is inserted.

188

JavaScript Reference

Object: HTMLSelectElement

Parameter

Type

Description If before is not specified or is null, element is inserted at the end of the list of children.

Return values
None.

Exceptions
Exception
NOT_FOUND_ERR

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

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

Method: HTMLSelectElement.blur()
Availability BlackBerry Device Software version 4.6 or later

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

Syntax
HTMLSelectElement.blur()

Parameters
None.

Return values
None.

Exceptions
None.

189

JavaScript Reference

Method: HTMLSelectElement.focus()
Availability BlackBerry Device Software version 4.6 or later

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

Syntax
HTMLSelectElement.focus()

Parameters
None.

Return values
None.

Exceptions
None.

Method: HTMLSelectElement.remove()
Availability BlackBerry Device Software version 4.6 or later

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

Syntax
HTMLSelectElement.remove( index )

Parameters
Parameter
index

Type int

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

Return values
None.

Exceptions
None.

190

JavaScript Reference

Object: HTMLStyleElement

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

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

HTMLStyleElement properties
Property name
disabled media sheet type

Type boolean String

StyleShe et

Description When true, indicates that the style sheet is not applied to the document. Specifies the destination medium for the style information. Returns the StyleSheet object associated with the element. Specifies the content type of the style sheet language.

Status writable writable read only writable

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later

String

Object: HTMLTableCaptionElement
Availability Extends BlackBerry Device Software version 4.6 or later
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
align

Type String

Description

Status

Availability 4.6 or later

Specifies the horizontal alignment of the table caption. writable

191

JavaScript Reference

Object: HTMLTableCellElement

Object: HTMLTableCellElement
Availability Extends BlackBerry Device Software version 4.6 or later
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
abbr align axis bgColor cellIndex ch chOff colSpan headers height noWrap rowSpan scope

Type String String String String int String String int String String boolean int String

Description Specifies an abbreviated version of the cell text. Specifies the horizontal alignment of the cell data. Specifies a list of category names used to organize cell content. This property is not currently defined in the DOM HTML specification. Returns the index position of the cell in the parent rows HTMLTableRowElement.cells array. Specifies the alignment character for cells in a column. Specifies the distance between the alignment character and the first adjacent character. Specifies the number of columns the table cell spans. Specifies for which sides of the table the border will be visible. Specifies the height of the table cell. When true, indicates that text is not wrapped in the cell. Specifies the number of rows the table cell spans. Specifies whether the cell provides header information for the column, column group, row, or row group.

Status writable writable undefined writable read only writable writable writable writable writable writable writable writable

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

192

JavaScript Reference

Object: HTMLTableColElement

Property name
vAlign width

Type String String

Description Specifies the vertical alignment of the content within the table cell. Specifies the width of the table cell.

Status writable writable

Availability 4.6 or later 4.6 or later

Object: HTMLTableColElement
Availability Extends BlackBerry Device Software version 4.6 or later
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 of table columns. These elements are not supported by the BlackBerry Browser.
HTMLTableColElement is supported in the BlackBerry Browsers JavaScript implementation to conform with HTML DOM Level 2 specification. However, <col> and <colgroup> elements will not be visually displayed in the browser and will not

have any impact on the document layout.

HTMLTableColElement properties
Property name
align ch chOff span vAlign width

Type String String String int String String

Description Specifies the horizontal alignment of the cell data. Specifies the alignment character for cells in a column. Specifies the distance between the alignment character and the first adjacent character. Specifies the number of columns included in a column group. Specifies the vertical alignment of the content within the table cell. Specifies the width of the table cell.

Status writable writable writable writable writable writable

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

193

JavaScript Reference

Object: HTMLTableElement

Object: HTMLTableElement
Availability Extends BlackBerry Device Software version 4.6 or later
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
align bgColor border caption

Type String String String

HTMLTableCaptionEl ement

Description Specifies the horizontal alignment of the table. Specifies the background color for the table. Specifies the thickness of the border around the table cells. 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. Specifies the amount of white space, in pixels, to add between cell content and its borders. Specifies the amount of white space, in pixels, to add between cells. Specifies for which sides of the table the border will be visible. Returns an index of the rows contained within the table, starting at 0. Specifies the location of rules in the table. Specifies summary text that describes the contents of the table.

Status writable writable writable writable

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later

cellPadding cellSpacing frame rows rules summary

String String String

HTMLCollection

writable writable writable read only writable writable

4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

String String

194

JavaScript Reference

Object: HTMLTableElement

Property name
tBodies tFoot

Type
HTMLCollection HTMLTableCaptionEl ement

Description

Status

Availability 4.6 or later 4.6 or later

Returns an index of all the <tbody> element read only in the table. Specifies a pointer to the <tfoot> element for writable 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. Specifies a pointer to the <thead> element for writable 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. Specifies the width of the table, in pixels, or as a percentage of the BlackBerry Browser window.

tHead

HTMLTableCaptionEl ement

4.6 or later

width

String

writable

4.6 or later

HTMLTableElement methods
Method name
createCaption() createTFoot() createTHead() deleteCaption() deleteRow() deleteTFoot() deleteTHead() insertRow()

Description Creates a new table caption, if the table does not already contain one. Creates a new table footer, it the table does not already contain one. Creates a new table header, if the table does not already contain one. Removes the caption from the table, if one exists. Removes the row at the given index position from the table. Removes the footer from the table, if one exists. Removes the header from the table, if one exists. Inserts a new empty row into the table at the given index position.

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

195

JavaScript Reference

Object: HTMLTableElement

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

Syntax
HTMLTableElement.createCaption()

Parameters
None.

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

Exceptions
None.

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 already exists, this method returns it.

Syntax
HTMLTableElement.createTFoot()

Parameters
None.

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

Exceptions
None.

196

JavaScript Reference

Object: HTMLTableElement

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 already exists, this method returns it.

Syntax
HTMLTableElement.createTHead()

Parameters
None.

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

Exceptions
None.

Method: HTMLTableElement.deleteCaption()
Availability BlackBerry Device Software version 4.6 or later

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

Syntax
HTMLTableElement.deleteCaption()

Parameters
None.

Return values
None.

Exceptions
None.

197

JavaScript Reference

Object: HTMLTableElement

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.

Syntax
HTMLTableElement.deleteRow( index )

Parameters
Parameter
index

Type
int

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

Return values
None.

Exceptions
Exception
INDEX_SIZE_ERR

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

Syntax
HTMLTableElement.deleteTFoot()

Parameters
None.

Return values
198

JavaScript Reference

Object: HTMLTableElement

None.

Exceptions
None.

Method: HTMLTableElement.deleteTHead()
Availability BlackBerry Device Software version 4.6 or later

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

Syntax
HTMLTableELement.deleteTHead()

Parameters
None.

Return values
None.

Exceptions
None.

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

Syntax
HTMLTableElement.insertRow( index )

Parameters
Parameter
index

Type
int

Description The index position at which to insert the new row in the table.

199

JavaScript Reference

Object: HTMLTableRowElement

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 values
Returns the newly added row.

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

See Also
HTMLTableRowElement.insertCell()

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

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

HTMLTableRowElement properties
Property name
align bgColor cells ch

Type String String

HTMLCollectio n

Description Specifies the horizontal alignment of the cell data. Specifies the background color for the table cell. Returns an index of the table cells contained within the table row, starting at 0. Specifies the alignment character for cells in a column.

Status writable writable read only writable

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later

String

200

JavaScript Reference

Object: HTMLTableRowElement

Property name
chOff

Type String

Description Specifies the distance the distance between the alignment character and the first adjacent character. Returns the index position of the row in the parent tables HTMLTableElement.rows array. Returns the index position of the row in the parent table sections HTMLTableSectionElement.rows array. Specifies the vertical alignment of the content within the table cell.

Status writable

Availability 4.6 or later

rowIndex sectionRowInde x vAlign

int int

read only read only

4.6 or later 4.6 or later

String

writable

4.6 or later

HTMLTableRowElement methods
Method name
deleteCell() insertCell()

Description Removes the table cell at the given index position. Inserts a new empty table cell into the row at the given index position.

Availability 4.6 or later 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.

Syntax
HTMLTableRowElement.deleteCell( index )

Parameters
Parameter
index

Type
int

Description The index position of the row to remove from the table.

201

JavaScript Reference

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 values
None.

Exceptions
Exception
INDEX_SIZE_ERR

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

Syntax
HTMLTableRowElement.insertCell( index )

Parameters
Parameter
index

Type
int

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

Return values
Returns the newly added table cell.

Exceptions
Exception
INDEX_SIZE_ERR

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

202

JavaScript Reference

Object: HTMLTableSectionElement

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

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

HTMLTableSectionElement properties
Property name
align ch chOff rows vAlign

Type String String String

HTMLCollect ion

Description Specifies the horizontal alignment of the cell data. Specifies the alignment character for cells in a column. Specifies the distance the distance between the alignment character and the first adjacent character. Returns an index of the rows contained within the table section, starting at 0. Specifies the vertical alignment of the content within the table cell.

Status writable writable writable read only writable

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

String

HTMLTableSectionElement methods
Method name
deleteRow() insertRow()

Description Removes the row at the given index position from the table section. Inserts a new empty row into the table section at the given index position.

Availability 4.6 or later 4.6 or later

203

JavaScript Reference

Object: HTMLTableSectionElement

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.

Syntax
HTMLTableSectionElement.deleteRow( index )

Parameters
Parameter
index

Type
int

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

Return values
None.

Exceptions
Exception
INDEX_SIZE_ERR

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

Syntax
HTMLTableSectionElement.insertRow( index )

Parameters
204

JavaScript Reference

Object: HTMLTextAreaElement

Parameter
index

Type
int

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

Return values
Returns the newly added row.

Exceptions
Exception
INDEX_SIZE_ERR

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

See Also
HTMLTableRowElement.insertCell()

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

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

HTMLTextAreaElement properties
Property name
accessKey cols

Type String int

Description

Status

Availability 4.6 or later 4.6 or later

Specifies the keypad key that gives access to the form writable control. Specifies the width of the text area control, in writable characters.

205

JavaScript Reference

Object: HTMLTextAreaElement

Property name
defaultValue

Type String

Description

Status

Availability 4.6 or later

disabled form

boolean
HTMLFormEleme nt

Specifies the initial contents of the text area. The writable value of this property does not change if the contents of the text area control within the form changes. When true, indicates that the text area control is not writable available. Returns the parent <form> element for the form read only control. Specifies the amount of white space, in pixels, to add between cell content and its borders. Specifies the name of the form control. This is the name portion of the name-value pair that is submitted with the form. When true, indicates that the form control cannot be modified by a user. Specifies the height of the form control, in text rows. Specifies the tabbing order of the form control. Returns the type of form control. The value for this property is textarea. Specifies the current contents of the form control. This is the value portion of the name-value pair that is submitted with the form.

4.6 or later 4.6 or later

name

String

writable

4.6 or later

readonly rows tabIndex type value

boolean int int String String

writable writable writable read only writable

4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

HTMLTextAreaElement methods
Method name
blur() focus() select()

Description Removes keypad focus from the element. Gives keypad focus to the element. Selects the entire contents of the element.

Availability 4.6 or later 4.6 or later 4.6 or later

206

JavaScript Reference

Object: HTMLTextAreaElement

Method: HTMLTextAreaElement.blur()
Availability BlackBerry Device Software version 4.6 or later

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

Syntax
HTMLTextAreaElement.blur()

Parameters
None.

Return values
None.

Exceptions
None.

Method: HTMLTextAreaElement.focus()
Availability BlackBerry Device Software version 4.6 or later

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

Syntax
HTMLTextAreaElement.focus()

Parameters
None.

Return values
None.

Exceptions
None.

207

JavaScript Reference

Object: HTMLTitleElement

Method: HTMLTextAreaElement.select()
Availability BlackBerry Device Software version 4.6 or later

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

Syntax
HTMLTextAreaElement.select()

Parameters
None.

Return values
None.

Exceptions
None.

Object: HTMLTitleElement
Availability Extends BlackBerry Device Software version 4.6 or later
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
text

Type String

Description Specifies the title of the HTML document.

Status writable

Availability 4.6 or later

Object: HTMLUListElement
Availability BlackBerry Device Software version 4.6 or later

208

JavaScript Reference

Object: KeyboardEvent

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

Type boolean String

Description When true, indicates reduced spacing between list items. Specifies the bullet style used in the list.

Status writable writable

Availability 4.6 or later 4.6 or later

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

The KeyboardEvent object extends the UIEvent object and represents an event generated by the BlackBerry device keyboard. It provides specific contextual information associated with keyboard devices. Each keyboard event references a key using an identifier. Keyboard events are commonly directed at the element that has the focus. To create an instance of a KeyboardEvent, you must invoke Document.createEvent() with an input parameter of
KeyboardEvent.

KeyboardEvent properties
Property name
altKey ctrlKey keyCode

Type boolean boolean int

Description Returns true if the ALT key is pressed or if the ALT key is locked. Returns false. BlackBerry devices have no CTRL key. Returns the key code associated with the key in this event. Returns the identifier of the key.

Status read only read only read only read only

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later

keyIdentifier String

209

JavaScript Reference

Object: KeyboardEvent

Property name
keyLocation metaKey shiftKey

Type int boolean boolean

Description Returns a value of

DOM_KEY_LOCATION_STANDARD.

Status read only read only read only

Availability 4.6 or later 4.6 or later 4.6 or later

Returns false. BlackBerry devices have no Meta key. Returns true if the SHIFT key is pressed.

Keyboard event types

Event type
keydown

Bubbles yes

Cancelable yes

Description 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

210

JavaScript Reference

Object: KeyboardEvent

KeyboardEvent methods
Method name
getModifierState() initKeyboardEvent() initKeyboardEventNS()

Description

Availability

Checks the state of a modifier key. 4.6 or later Initializes the value of a KeyboardEvent. 4.6 or later Initializes the value of a KeyboardEvent with the given namespace 4.6 or later URI.

Method: KeyboardEvent.getModifierState()
Availability BlackBerry Device Software version 4.6 or later

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

Syntax
KeyboardEvent.getModifierState( keyIdentifierArg )

Parameters
Parameter
keyIdentifierArg

Type String

Description Specifies a modifier key identifier, such as ALT.

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

Exceptions
None.

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

211

JavaScript Reference

Object: KeyboardEvent

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

Parameters
Parameter
typeArg

Type String

Description Specifies the Keyboard event type. This parameter may have one of the following values:
keydown keypress keyup

canBubbleArg

boolean

cancelableArg

boolean

viewArg keyIdentifierArg keyLocationArg

AbstractView

String String

When true, this parameter indicates that the event can bubble upwards through the DOM tree. This parameter sets the value of Event.bubbles . When true, this parameter indicates that the events default action can be cancelled. This parameter sets the value of Event.cancelable . Specifies the window or frame that is generating the event. This parameter sets the value of UIEvent.view . Specifies the identifier of the key. This parameter sets the value of KeyboardEvent.keyIdentifier . 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 values
None.

Exceptions
None.

See also

212

JavaScript Reference

Object: KeyboardEvent

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.

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

String

Parameters
Parameter
namespaceURI typeArg

Type String String

Description Specifies a modifier key identifier, such as ALT. Specifies the Keyboard event type. This parameter may have one of the following values:
keydown keypress keyup

canBubbleArg

boolean

cancelableArg

boolean

viewArg keyIdentifierArg keyLocationArg

AbstractView

String String

When true, this parameter indicates that the event can bubble upwards through the DOM tree. This parameter sets the value of Event.bubbles . When true, this parameter indicates that the events default action can be cancelled. This parameter sets the value of Event.cancelable . Specifies the window or frame that is generating the event. This parameter sets the value of UIEvent.view . Specifies the identifier of the key. This parameter sets the value of KeyboardEvent.keyIdentifier . Specifies the location of the key on the device that started the key event. This parameter sets the value of KeyboardEvent.keyLocation .

213

JavaScript Reference

Object: Location

Parameter
modifiersList

Type String

Description Specifies a whitespace-separated list of modifier key identifiers to be activated on the object.

Return values
None.

Exceptions
None.

See also
KeyboardEvent.initKeyboardEvent()

Object: Location
Availability Extends BlackBerry Device Software version 4.6 or later
Window

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

Location properties
Property name
hash

Type String

Description Specifies the anchor portion of the URL, including the leading hash mark, if one exists. Specifies the URL hostname and port. Specifies the hostname portion of the URL. Specifies the entire URL.

Status writable

Availability 4.6 or later

host hostname href

String String String

writable writable writable

4.6 or later 4.6 or later 4.6 or later

214

JavaScript Reference

Object: Location

Property name
pathname port protocol search

Type String String String String

Description Specifies the pathname portion of the URL. Specifies the port portion of the URL. Specifies the protocol portion of the URL. Specifies the URL query string portion of the URL, including the question mark.

Status writable read only writable writable

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later

Location methods
Method name
assign() replace() reload() toString()

Description Loads a new document. Replaces the current web page with the web page at the given URL. Reloads the current web page. Returns the URL of the Location objects URL.

Availability 4.6 or later 4.6 or later 4.6 or later 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 URL is still available in the BlackBerry Browser History list.

Syntax
location.assign( URL )

Parameters
Parameter
URL

Type String

Description The URL to load.

Return values

215

JavaScript Reference

Object: Location

None.

Exceptions
None.

See also
location.replace()

Method: location.reload()
Availability BlackBerry Device Software version 4.6 or later

The reload() method reloads the current web page.

Syntax
location.reload( forceGet )

Parameters
Parameter
forceGet

Type boolean

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

Return values
None.

Exceptions
None.

See also
location.assign()

216

JavaScript Reference

Object: Location

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 from Location.assign() in that when the old URL is replaced, it is not saved in the History list. As a result, the user will have no way to navigate back to it.

Syntax
location.replace( URL )

Parameters
Parameter
URL

Type String

Description The URL to replace the current URL with.

Return values
None.

Exceptions
None.

See also
Location.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.

Syntax
location.toString()

Parameters
None.

Return values

217

JavaScript Reference

Object: MediaList

Returns the current URL (the value of location.href) as a string value.

Exceptions
None.

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

Description Returns the number of media in the list. 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.

Status read only writable

Availability 4.6 or later 4.6 or later

int String

MediaList methods
Method name
appendMedium() deleteMedium() item()

Description Adds the given medium to the end of the MediaList object. Removes the given medium from the MediaList object. Returns the medium at the given index in the collection.

Availability 4.6 or later 4.6 or later 4.6 or later

218

JavaScript Reference

Object: MediaList

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.

Syntax
MediaList.appendMedium( newMedium )

Parameters
Parameter
newMedium

Type String

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

Return values
None.

Exceptions
Exception
NO_MODIFICATION_ALLOWED_ERR INVALID_CHARACTER_ERR

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

See also
MediaList.deleteMedium()

Method: MediaList.deleteMedium()
Availability BlackBerry Device Software version 4.6 or later

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

Syntax
MediaList.deleteMedium( oldMedium )

Parameters

219

JavaScript Reference

Parameter
oldMedium

Type String

Description The medium to remove from MediaList.

Return values
None.

Exceptions
Exception
NO_MODIFICATION_ALLOWED_ERR NOT_FOUND_ERR

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

See also
MediaList.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.

Syntax
MediaList.item( index )

Parameters
Parameter
index

Type int

Description An integer that represents the items position in MediaList object. Valid values are between 0 and MediaList.length-1 inclusive.

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

Exceptions
None.

220

JavaScript Reference

Object: MimeType

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 content from the server. This object represents a MIME type specification.

MimeType properties
Property name
description enabledPlugi n suffixes type

Type String
Plugin

Description Returns a description of the MIME type. Returns a reference to the Plugin object currently set to display any incoming data formatted according to the MIME type. Returns a list of possible file extensions associated with the MIME type. Returns the name of the MIME type.

Status read only read only

Availability 4.6 or later 4.6 or later

String String

read only read only

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

Type int

Description Returns the number of MIME types in the list.

Status read only

Availability 4.6 or later

221

JavaScript Reference

Object: MimeTypeArray

MimeTypeArray methods
Method name
item() namedItem()

Description Retrieves a specific node, by index, from the collection. Retrieves the node with the given name property value from the collection.

Availability 4.6 or later 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.

Syntax
MimeTypeArray.item( index )

Parameters
Parameter
index

Type int

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

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

Exceptions
None.

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

222

JavaScript Reference

Object: MouseEvent

MimeTypeArray.namedItem( name )

Parameters
Parameter
name

Type String

Description The name of the MIME type to retrieve.

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

Exceptions
None.

Object: MouseEvent
Availability Extends BlackBerry Device Software version 4.6 or later
UIEvent

The MouseEvent object extends the UIEvent object and represents an event generated by the BlackBerry device trackball or trackwheel. It provides contextual information associated with clicking the trackball or trackwheel and moving the pointer in the BlackBerry Browser window. To create an instance of a MouseEvent, you must invoke Document.createEvent() with an input parameter of MouseEvent.

MouseEvent properties
Property name
altKey button

Type boolean short

Description

Status

Availability 4.6 or later 4.6 or later

clientX

int

Returns true if the ALT key is pressed or ALT lock is read only on. Returns a value indicating which mouse button read only changed state. Because BlackBerry devices have a single button (the trackball or trackwheel), this parameter will always return a value of 0. Returns the horizontal coordinate within the read only BlackBerry Browser window where the event occurred.

4.6 or later

223

JavaScript Reference

Object: MouseEvent

Property name
clientY ctrlKey metaKey relatedTarg et screenX screenY shiftKey

Type int boolean boolean

EventTarget

Description Returns the vertical coordinate within the BlackBerry Browser window where the event occurred. Returns false. The BlackBerry device does not have a CTRL key. Returns false. The BlackBerry device does not have a Meta key. Returns the EventTarget that the pointer is moving over or moving off of. Returns the horizontal coordinate on the BlackBerry device screen where the event occurred. Returns the vertical coordinate on the BlackBerry device screen where the event occurred. Returns true if the SHIFT key is pressed.

Status read only read only read only read only read only read only read only

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

int int boolean

Mouse event types

Event type
click

Bubbles yes

Cancelable yes

Description 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 Occurs when the user depresses the trackwheel or trackball on a BlackBerry device.

mousedown

yes

yes

This event type includes the following context information:

224

JavaScript Reference

Object: MouseEvent

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:

225

JavaScript Reference

Object: MouseEvent

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

Description Initializes the value of a MouseEvent.

Availability 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() . This method can only be called before the MouseEvent has been dispatched.

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

Parameters
Parameter
typeArg

Type String

Description Specifies the MouseEvent type. This parameter may have one of the following values:
click mousedown mousemove mouseout mouseover

226

JavaScript Reference

Parameter
canBubbleArg cancelableArg viewArg detailArg screenXArg screenYArg clientXArg clientYArg ctrlKeyArg altKeyArg shiftKeyArg metaKeyArg buttonArg relatedTargetAr g

Type boolean boolean

AbstractView

Description
mouseup

long long long long long boolean boolean boolean boolean unsigned short
EventTarget

When true, this parameter indicates that the event can bubble upwards through the DOM tree. This parameter sets the value of Event.bubbles . When true, this parameter indicates that the events default action can be cancelled. This parameter sets the value of Event.cancelable . Specifies the window or frame that is generating the event. This parameter sets the value of UIEvent.view . Specifies the number of clicks associated with the event. This parameter sets the value of UIEvent.detail . Specifies the horizontal coordinate on the BlackBerry device screen where the event occurred. Specifies the vertical coordinate on the BlackBerry device screen where the event occurred. Specifies the horizontal coordinate within the BlackBerry Browser window where the event occurred. Specifies the vertical coordinate within the BlackBerry Browser window where the event occurred. Specifies whether the CTRL key was pressed during the event. Specifies whether the ALT key was pressed during the event. Specifies whether the SHIFT key was pressed during the event. Specifies whether the meta key was pressed during the event. Specifies which button was clicked. Specifies the events 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 values
None.

Exceptions
None.

227

JavaScript Reference

Object: MutationEvent

Object: MutationEvent
Availability Extends BlackBerry Device Software version 4.6 or later
Event

The MutationEvent object extends the Event object and represents an event generated when the structure of document is modified. To create an instance of a MutationEvent, you must invoke Document.createEvent() with an input parameter of MutationEvent.

MutationEvent properties
Property name
attrChange

Type unsigned short

Description

Status

Availability 4.6 or later

Returns the type of change that triggered the read only 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 read only 4.6 or later 4.6 or later

attrName newValue

String String

Returns the name of the changed Attr node in a DOMAttrModified event. Returns the new value of: the Attr node in a DOMAttrModified event the CharacterData node in a DOMCharacterDataModified event

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

228

JavaScript Reference

Object: MutationEvent

Property name
relatedNode

Type
Node

Description

Status

Availability 4.6 or later

Returns the secondary node affected by a mutation event. read only

Mutation event types

Event type
DOMAttrModified

Bubbles yes

Cancelable Description 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 DOMNodeInserted

no yes

no no

Occurs when the BlackBerry Browser has completely parsed the document, before any onload events are triggered. 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.

229

JavaScript Reference

Object: MutationEvent

Event type
DOMNodeInsertedIntoDo cument DOMNodeRemoved

Bubbles yes yes

Cancelable Description no no Occurs when a node has been inserted into the document, either directly or as part of a subtree. 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

DOMNodeRemovedFromDoc ument DOMSubtreeModified

yes yes

no no

the parent node of the node being removed. Occurs when a node has been removed from the document, either directly or as part of a subtree. Occurs when any modification has been made to the document, encompassing all other MutationEvent types.

MutationEvent methods
Method name
initMutationEven t()

Description Initializes the value of a MutationEvent.

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

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

Parameters

230

JavaScript Reference

Object: MutationEvent

Parameter
typeArg

Type String

Description Specifies the mutation event type. This parameter may have one of the following values:
DOMAttrModified DOMCharacterDataModified DOMContentLoaded DOMNodeInserted DOMNodeInsertedIntoDocument DOMNodeRemoved DOMNodeRemovedFromDocument DOMSubtreeModified

canBubbleArg cancelableArg relatedNodeArg prevValueArg

boolean boolean
Node

String

When true, this parameter indicates that the event can bubble upwards through the DOM tree. This parameter sets the value of Event.bubbles . When true, this parameter indicates that the events default action can be cancelled. This parameter sets the value of Event.cancelable . Specifies the secondary node impacted by the mutation event. This parameter sets the value of MutationEvent.relatedNode . 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 attrNameArg attrChangeArg

String String short

Specifies the previous value of a changed Attr or CharacterData node. This parameter sets the value of MutationEvent.newValue . Specifies the name of a changed Attr node. This parameter sets the value of MutationEvent.attrName . 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.

231

JavaScript Reference

Object: NamedFrameMap

Parameter

Type

Description This parameter sets the value of MutationEvent.attrChange .

Return values
None.

Exceptions
None.

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 or id attribute using NamedFrameMap.getNamedItem() , or you can index the object directly. For example, if you create an instance of a NamedFrameMap object called myNamedFrameMap, then specifying
myNamedFrameMap.item(2) myNamedFrameMap.getNamedItem(item)

is equivalent to specifying
myNamedFrameMap[2] myNamedFrameMap[item]

NamedFrameMap properties
Property name
length

Type unsigned long

Description Returns the number of nodes in the map.

Status read only

Availability 4.6 or later

NamedFrameMap methods
Method name
getNamedItem()

Description Retrieves the frame with the given name.

Availability 4.6 or later

232

JavaScript Reference

Object: NamedFrameMap

Method name
item()

Description Returns the frame at the given index in the map.

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

Syntax
NamedFrameMap.item( index )

Parameters
Parameter
index

Type int

Description An integer that represents the frames position in the frame map. Valid values are between 0 and NamedFrameMap.length -1 inclusive.

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

Exceptions
None.

Method: NamedFrameMap.getNamedItem()
Availability BlackBerry Device Software version 4.6 or later

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

Syntax
NamedFrameMap.getNamedItem( name )

Parameters

233

JavaScript Reference

Object: NamedNodeMap

Parameter
name

Type String

Description The value of the Node.nodeName property of the frame to retrieve.

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

Exceptions
None.

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 or id attribute using NamedNodeMap.getNamedItem() , or you can index the object directly. For example, if you create an instance of a NamedNodeMap object called myNamedNodeMap, then specifying
myNamedNodeMap.item(2) myNamedNodeMap.getNamedItem(item)

is equivalent to specifying
myNamedNodeMap[2] myNamedNodeMap[item]

NamedNodeMap properties
Property name
length

Type unsigned long

Description Returns the number of nodes in the map.

Status read only

Availability 4.6 or later

234

JavaScript Reference

Object: NamedNodeMap

NamedNodeMap methods
Method name
getNamedItem() getNamedItemNS() item() removeNamedItem() removeNamedItemNS() setNamedItem() setNamedItemNS()

Description Retrieves the node with the given name. Retrieves the node with the given name and namespace URI. Returns the node at the given index in the map. Removes the node with the given name from the map. Removes the node with the given name and namespace URI from the map. Adds a node using the Node.nodeName attribute. Adds a node using the Node.nodeName attribute and the namespace URI.

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 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.

Syntax
NamedNodeMap.getNamedItem( name )

Parameters
Parameter
name

Type String

Description The value of the Node.nodeName property of the node to retrieve.

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

Exceptions
None.

See also
NamedNodeMap.getNamedItemNS()

235

JavaScript Reference

Object: NamedNodeMap

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.

Syntax
NamedNodeMap.getNamedItemNS( namespaceURI, localName )

Parameters
Parameter
namespaceURI localName

Type String String

Description The namespace of the node to retrieve. The local name of the node to retrieve.

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

Exceptions
Exception
NOT_SUPPORTED_ERR

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

See also
NamedNodeMap.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.

Syntax
NamedNodeMap.item( index )

Parameters

236

JavaScript Reference

Object: NamedNodeMap

Parameter
index

Type int

Description An integer that represents the nodes position in the node map. Valid values are between 0 and NamedNodeMap.length -1 inclusive.

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

Exceptions
None.

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, the removed 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.

Syntax
NamedNodeMap.removeNamedItem( name )

Parameters
Parameter
name

Type String

Description The value of Node.nodeName property of the node to remove.

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

Exceptions
Exception
NO_MODIFICATION_ALLOWED_ERR NOT_FOUND_ERR

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

237

JavaScript Reference

Object: NamedNodeMap

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 will immediately be reattached to the element with its default value, as well as its corresponding namespace URI, local name, and prefix, if applicable.

Syntax
NamedNodeMap.removeNamedItemNS( namespaceURI, localName )

Parameters
Parameter
namespaceURI localName

Type String String

Description The namespace of the node to remove. The local name of the node to remove.

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

Exceptions
Exception
NO_MODIFICATION_ALLOWED_ERR NOT_FOUND_ERR NOT_SUPPORTED_ERR

Description This error is thrown if the NamedNodeMap object is read only. This error is thrown if no node with a Node.nodeName value of name exists in the NamedNodeMap. 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 same Node.nodeName value already exists in the map, the existing node is removed and is replaced by the new node and the removed node is returned.

238

JavaScript Reference

Object: NamedNodeMap

As the Node.nodeName property is used to store the new node in the map, in order to prevent name clashes, you may not add multiple nodes of those node types that always have the same Node.nodeName value. For example, a text node will always have a Node.nodeName value of #text. Therefore, only a single text node may be included in any NamedNodeMap object.

Syntax
NamedNodeMap.setNamedItem( arg )

Parameters
Parameter
arg

Type
Node

Description The node to add to the map.

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

Exceptions
Exception
HIERARCHY_REQUEST_ERR

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

INUSE_ATTRIBUTE_ERR

NO_MODIFICATION_ALLOWED_ERR WRONG_DOCUMENT_ERR

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

Syntax
NamedNodeMap.setNamedItemNS( arg )

Parameters

239

JavaScript Reference

Object: Navigator

Parameter
arg

Type
Node

Description The node to add to the map.

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

Exceptions
Exception
HIERARCHY_REQUEST_ERR

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

INUSE_ATTRIBUTE_ERR

NO_MODIFICATION_ALLOWED_ERR NOT_SUPPORTED_ERR WRONG_DOCUMENT_ERR

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.

240

JavaScript Reference

Object: Navigator

Navigator properties
Property name
appCodeName

Type String

Description 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". Returns the name of the browser. In the case of the BlackBerry Browser, the value is always BlackBerry. Returns the version of the BlackBerry Device Software that is running on the BlackBerry device (for example, 4.6.0). Returns the build identifier of the version of the BlackBerry Device Software running on the device. Returns true if cookies are enabled in the BlackBerry Browser. Returns the two-letter language code (for example, de, en, or ja) that represents the default language translation of the BlackBerry Browser. Returns a list of the MIME types that the target BlackBerry Browser supports. Returns BlackBerry. This property is treated as a constant. Returns a list of the embedded plugins in the document. 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.

Status read only

Availability 3.8 or later

appName

String

read only

3.8 or later

appVersion

String

read only

3.8 or later

buildID cookieEnabled language

String boolean String

read only read only read only

4.6 or later 4.6 or later 3.8 or later

mimeTypes platform plugins userAgent

MimeTypeArr ay

read only read only read only read only

3.8 or later 3.8 or later 4.6 or later 3.8 or later

String
PluginArray

String

241

JavaScript Reference

Object: Node

Navigator methods
Method name
javaEnabled()

Description Tests whether the browser supports Java or not.

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

Syntax
navigator.javaEnabled()

Parameters
None.

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

Exceptions
None.

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

242

JavaScript Reference

Object: Node

Extended by

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

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

Node properties
Property name
attributes

Type
NamedNodeM ap

Description Returns a NamedNodeMap object that contains the attributes of the given element node, or null, if the node is not an element. Returns a NodeList object that contains all the child elements of the given node. Returns the first child of the given node. Returns the last child of the given node. Returns the local part of the qualified name for the given node. Returns the namespace URI for the given node, or null if it is not specified. Returns the node immediately following the given node. Returns the name of the given node. Returns a code representing the type of the given node. Specifies the value of the given node. When setting a value for this property, the following error may be thrown:

Status read only

Availability 4.6 or later

childNodes firstChild lastChild localName namespaceURI nextSibling nodeName nodeType nodeValue

NodeList Node Node

read only read only read only read only read only read only read only read only writable

4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

String String
Node

String unsigned short String

243

JavaScript Reference

Object: Node

Property name

Type

Description
NO_MODIFICATION_ERR: Thrown if the Node object is read only.

Status

Availability

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 parentNode prefix Document Node

String

Returns the Document object associated with the given node. Returns the parent of the given node. 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

read only read only writable

4.6 or later 4.6 or later 4.6 or later

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

previousSiblin g

Node

Returns the node immediately preceding the current read only node.

Node methods
Method name
addEventListener() appendChild() cloneNode()

Description Adds an EventListener object to a set of event listeners for the given node. Adds a node to the end of the array of child nodes for the given node. Returns a duplicate of the given node. The duplicate node has no parent.

Availability 4.6 or later 4.6 or later 4.6 or later

244

JavaScript Reference

Object: Node

Method name
dispatchEvent() hasAttributes() hasChildNodes() insertBefore() isSupported() normalize() removeChild() removeEventListener () replaceChild()

Description Dispatches an Event object created by Document.createEvent() . Returns whether the given node has any attributes. Returns whether the given node has any children. Inserts a new node before the given node. Tests whether the given node supports a specific feature. Merges text nodes adjacent to the given element node to create a normalized DOM. Removes the specified child from the given element node and returns it. Removes an event listener from an EventTarget.

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

Removes the specified child from the given and replaces it with another node, 4.6 or later then returns the removed node.

Method: Node.removeEventListener()
Availability BlackBerry Device Software version 4.6 or later

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

Syntax
Node.removeEventListener( type, listener, useCapture )

Parameters
Parameter
type listener useCapture

Type String
EventListener

Description The type of event. The EventListener function to be removed. 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.

boolean

Return values

245

JavaScript Reference

Object: Node

None.

Exceptions
None.

See also
Event , 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.

Syntax
Node.removeChild( oldChild )

Parameters
Parameter
oldChild

Type
Node

Description The child node to remove.

Return values
Returns the removed node.

Exceptions
Exception
NO_MODIFICATION_ALLOWED_ERR NOT_FOUND_ERR

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

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

246

JavaScript Reference

Object: Node

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, then returns the replaced node.

Syntax
Node.replaceChild( newChild, oldChild )

Parameters
Parameter
newChild

Type
Node

Description 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. The child node to replace.

oldChild

Node

Return values
Returns the replaced node.

Exceptions
Exception
HIERARCHY_REQUEST_ERR

Description This error is thrown if either newChild or oldChild is one of the current nodes ancestors, or if the current node does not allow children of the type of newChild node. This error is thrown if the current node is read only. This error is thrown if oldChild is not a child of the current node.

NO_MODIFICATION_ALLOWED_ERR NOT_FOUND_ERR

247

JavaScript Reference

Object: Node

Exception
WRONG_DOCUMENT_ERR

Description This error is thrown if newChild was created from a different document than the current node.

See also
Node.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 a normalized DOM.

Syntax
Node.normalize()

Parameters
None.

Return values
None.

Exceptions
None.

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.

Syntax
Node.addEventListener( type, listener, useCapture )

Parameters
Parameter
type listener

Type String
EventListener

Description The type of event to add. The event listener function to be invoked.

248

JavaScript Reference

Object: Node

Parameter
useCapture

Type boolean

Description When true, indicates all events of the specified type to the registered EventListener before being dispatched to any EventTargets beneath the given node in the tree. Bubbling events will not trigger the EventListener. When false, this method dispatches events of the specified type to the registered EventListener before being dispatched to any EventTargets above the given node in the tree.

Return values
None.

Exceptions
None.

See also
Event , EventListener

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.

Syntax
Node.appendChild( newChild )

Parameters
Parameter
newChild

Type
Node

Description The node to add. If newChild is a DocumentFragment object, then the entire contents of the document fragment are appended to the given node.

249

JavaScript Reference

Object: Node

Parameter

Type

Description If newChild already exists in the tree, it is removed, and then replaced.

Return values
Returns the added node.

Exceptions
Exception
HIERARCHY_REQUEST_ERR

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

NO_MODIFICATION_ALLOWED_ERR WRONG_DOCUMENT_ERR

See also
Node.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 the Element 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 attribute is set to true). Cloning any other type of node simply returns a copy of the node.

Syntax
Node.cloneNode( deep )

Parameters

250

JavaScript Reference

Object: Node

Parameter
deep

Type boolean

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

Return values
Returns the duplicate node.

Exceptions
None.

Method: Node.dispatchEvent()
Availability BlackBerry Device Software version 4.6 or later

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

Syntax
Node.dispatchEvent( event )

Parameters
Parameter
event

Type
Event

Description The Event object to be dispatched.

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

Exceptions

251

JavaScript Reference

Object: Node

Exception
UNSPECIFIED_EVENT_TYPE_ERR

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

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

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

Syntax
Node.hasAttributes()

Parameters
None.

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

Exceptions
None.

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

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

Syntax
Node.hasChildNodes()

Parameters

252

JavaScript Reference

Object: Node

None.

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

Exceptions
None.

See also
Node.childNodes

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

Syntax
Node.insertBefore( newChild, refChild )

Parameters
Parameter
newChild

Type
Node

Description 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. The existing child node before which newChild is inserted. If refChild is not specified or is null, then newChild is inserted at the end of the list of children.

refChild

Node

Return values
Returns the inserted node.

Exceptions

253

JavaScript Reference

Object: Node

Exception
HIERARCHY_REQUEST_ERR

Description This error is thrown if newChild is an ancestor of refChild , or if refChild does not allow children of the type of newChild node. This error is thrown if the given node is read only. This error is thrown if refChild is not a child of the current node. This error is thrown if newChild was created from a different document than the current node.

NO_MODIFICATION_ALLOWED_ERR NOT_FOUND_ERR WRONG_DOCUMENT_ERR

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

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

Syntax
Node.isSupported( feature, version )

Parameters
Parameter
feature version

Type String String

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

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

Exceptions
None.

See also

254

JavaScript Reference

Object: NodeFilter

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 applies the filter before it returns the next node. If the filter says to accept the node, the traversal object, either a NodeIterator or TreeWalker, returns it; otherwise, the traversal object looks for the next node and acts as if that the node that was rejected was not there.

NodeFilter methods
Method name
acceptNode()

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

Availability 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 or TreeWalker . This method is normally called by the NodeIterator or TreeWalker object, rather than as part of the JavaScript code.

Syntax

NodeFilter.acceptNode( n )

Parameters
Parameter
n

Type
Node

Description The node to check.

Return values
Returns a constant that that determines whether the node is accepted, rejected, or skipped.

255

JavaScript Reference

Object: NodeList

Constant
1 2

Definition
FILTER_ACCEPT FILTER_REJECT

Description Navigation methods defined for NodeIterator or TreeWalker will return the node. 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. Navigation methods defined for NodeIterator or TreeWalker will not return the node; however, children of this node are still considered.

FILTER_SKIP

Exceptions
None.

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 the object directly. For example, if you create an instance of a NodeList object called myNodeList, then specifying
myNodelist.item(2)

is equivalent to specifying
myNodelist[2]

NodeList properties
Property name
length

Type unsigned long

Description Returns the number of Node s in the list.

Status read only

Availability 4.6 or later

256

JavaScript Reference

Object: Notation

NodeList methods
Method name
item()

Description Returns the Node at the specified index in the collection.

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

Syntax
NodeList.item( index )

Parameters
Parameter
index

Type int

Description An integer that represents the nodes position in NodeList . Valid values are between 0 and NodeList.length -1 inclusive.

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

Exceptions
None.

Object: Notation
Availability Extends BlackBerry Device Software version 4.6 or later
Node

The Notation object represents a notation declared in a DTD. A Notation declares the format of an unparsed entity, or is used to formally declare ProcessingInstruction targets. The Node.nodeName property is set to the declared name of the Notation.

257

JavaScript Reference

Object: NodeIterator

Notation properties
Property name
publicId systemId

Type String String

Description

Status

Availability 4.6 or later 4.6 or later

Returns the public identifier of the Notation, or null if read only no identifier has been specified. Returns the system identifier of the Notation, or null if read only no identifier has been specified.

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 object is similar to the TreeWalker objects, except that TreeWalker presents nodes in a tree-oriented view, rather than the list view presented by NodeIterator. Create a NodeIterator using Document.createNodeIterator() .

NodeIterator properties
Property name
expandEntityReferen ces filter root NodeFilte r Node

Type boolean

Description Returns whether or not the NodeIterator expands the entity references it encounters as it traverses the document. Returns the NodeFilter used to filter nodes for traversal. Returns the Node at which the NodeIterator begins traversing the document. Returns which node types are presented by the NodeIterator. The value may be one or more of:

Status read only

Availability 4.6 or later

read only read only

4.6 or later 4.6 or later

whatToShow

unsigned long

read only

4.6 or later

258

JavaScript Reference

Object: NodeIterator

Property name

Type

Description
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

Status

Availability

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.

259

JavaScript Reference

Object: NodeIterator

NodeIterator methods
Method name
detach() nextNode() previousNode()

Description

Availability

Detaches the NodeIterator from the set which it iterated over. 4.6 or later Moves the NodeIterator to the next visible Node in the document order, 4.6 or later relative to the current node. Moves the NodeIterator to the previous visible Node in the document order, 4.6 or later relative to the current node.

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 been detached, attempting to use NodeIterator.nextNode() or NodeIterator.previousNode() results in an error.

Syntax
NodeIterator.detach()

Parameters
None.

Return values
None.

Exceptions
None.

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 current node. The first call to this method after a NodeIterator is created returns the first Node in the set.

Syntax

260

JavaScript Reference

NodeIterator.nextNode()

Parameters
None.

Return values
Returns the node, or null, if there is no node after the current node in the NodeIterators logical view.

Exceptions
Exception
INVALID_STATE_ERR

Description 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 to the current node.

Syntax
NodeIterator.previousNode()

Parameters
None.

Return values
Returns the node, or null, if there is no node before the current node in the NodeIterators logical view.

Exceptions
Exception
INVALID_STATE_ERR

Description This error is thrown if this method is called after the NodeIterator has been detached from the set that it iterated over.

261

JavaScript Reference

Object: Plugin

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 id attribute using Plugin.namedItem() , or you can index the object directly. For example, if you create an instance of a Plugin object called myPlugins, then specifying
myPlugins.item(2) myPlugins.namedItem(item)

is equivalent to specifying
myPlugins[2] myPlugins[item]

Plugin properties
Property name
description filename length name

Type String String unsigned long String

Description Returns the description of the Plugin. Returns the Plugin filename. Returns the number of MIME types associated with the Plugin. Returns the name of the Plugin.

Status read only read only read only read only

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later

Plugin methods
Method name
item() namedItem()

Description Returns the Plugin at the specified index in the collection. Returns the Plugin with the given name.

Availability 4.6 or later 4.6 or later

262

JavaScript Reference

Object: Plugin

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.

Syntax
Plugin.item( index )

Parameters
Parameter
index

Type int

Description The index position of the Plugin to be returned. Valid values are between 0 and Plugin.length -1 inclusive.

Return values
Returns the plugin at the index th position in Plugin, or null if an invalid index position is specified.

Exceptions
None.

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.

Syntax
Plugin.namedItem( name )

Parameters
Parameter
name

Type String

Description The name of the Plugin to retrieve.

Return values

263

JavaScript Reference

Object: PluginArray

Returns the Plugin with the given name, or null if no Plugin with the given name exists in the array.

Exceptions
None.

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
length

Type unsigned long

Description Returns the number of Plugin objects in the collection.

Status read only

Availability 4.6 or later

PluginArray methods
Method name
item() namedItem()

Description Returns the Plugin at the specified index in the collection. Retrieves the Plugin with the given name from the collection.

Availability 4.6 or later 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.

Syntax
PluginArray.item( index )

Parameters

264

JavaScript Reference

Object: ProcessingInstruction

Parameter
index

Type int

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

Return values
Returns the Plugin at the index th position in PluginArray, or null if an invalid index position is specified.

Exceptions
None.

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.

Syntax
PluginArray.namedItem( name )

Parameters
Parameter
name

Type String

Description The name of the Plugin object to retrieve.

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

Exceptions
None.

Object: ProcessingInstruction
Availability BlackBerry Device Software version 4.6 or later

265

JavaScript Reference

Object: Range

Extends

Node

The ProcessingInstruction object represents a Processing Instruction for an XML document, which enables you to keep processor-specific information within the context of the document. Processing instructions are specified within the <? and ?> markers. For instance, instructions on which style sheets to apply can be defined in a processing instruction, even though that is not directly related to the content of the document.

ProcessingInstruction properties
Property name
data

Type String

Description Specifies the content of the processing instruction. This content includes everything contained between the processing instruction markers. Returns the style sheet associated with the processing instruction. Returns the target of the processing instruction.

Status writable

Availability 4.6 or later

sheet target

String String

read only read only

4.6 or later 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 using Selection.getRangeAt .

266

JavaScript Reference

Object: Range

Range properties
Property name
collapsed commonAncestorContainer

Type boolean
Node

Description Returns true if the start point and end point of the range are the same. Returns the deepest node that contains the startContainer and endContainer nodes. Returns the node that contains the end point of the range. Returns a number that represents the end point of the range within the endContainer node. Returns the node that contains the start point of the range. Returns a number that represents the start point of the range within the startContainer node.

Status read-only read-only

Availability 4.7.1 or later 4.7.1 or later

endContainer endOffset

Node

read-only read-only

4.7.1 or later 4.7.1 or later

int

startContainer startOffset

Node

read-only read-only

4.7.1 or later 4.7.1 or later

int

Range methods
Method name
cloneContents() cloneRange()

Description

Availability 4.7.1 or later 4.7.1 or later 4.7.1 or later 4.7.1 or later 4.7.1 or later 4.7.1 or later

Duplicates the contents of a specified range. Creates a new Range object with the same start point and end point as the specified range. collapse() Collapses a range onto its start point or end point. compareBoundaryPoints() Compares the start points and end points of two ranges. deleteContents() Deletes the contents of the range from the Document or DocumentFragment node. detach() Immediately releases the Range object from the object model.

267

JavaScript Reference

Object: Range

Method name
extractContents()

Description Extracts the entire contents of the range from a Document or DocumentFragment node and moves it to a new DocumentFragment object. Inserts a new node at the start of the range. Populates the range with a specified node and its contents. Populates the range with the contents of a specified node. Sets the end point of the range. Sets the end point of a range at a position that is after the specified node. Sets the end point of a range at a position that is before the specified node. Sets the start point of the range. Sets the start point of a range at a position that is after the specified node. Sets the start point of a range at a position that is before the specified node. Moves the contents of the range to a new node object, and inserts the new node at the start point of the range. Returns the contents of the range as a string.

Availability 4.7.1 or later

insertNode() selectNode() selectNodeContents() setEnd() setEndAfter() setEndBefore() setStart() setStartAfter() setStartBefore() surroundContents() toString()

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

Syntax
Range.cloneContents()

Parameters
None.

Return values
This method returns a DocumentFragment object that contains the same contents as the range.

Exceptions

268

JavaScript Reference

Object: Range

Exception HIERARCHY_REQUEST_ERR INVALID_STATE_ERR

Description Thrown if the result of this action is that a DocumentType node is inserted into the DocumentFragment object. 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.

Syntax
Range.cloneRange()

Parameters
None.

Return values
This method returns the new Range object.

Exceptions
Exception INVALID_STATE_ERR Description 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.

Syntax
Range.collapse( toStart )

Parameters

269

JavaScript Reference

Object: Range

Parameter
toStart

Type boolean

Description 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 values
None.

Exceptions
Exception INVALID_STATE_ERR Description 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.

Syntax
Range.compareBoundaryPoints( how, sourceRange )

Parameters
Parameter
how

Type short

Description 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

270

JavaScript Reference

Object: Range

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 end

point of sourceRange . 0: Indicates that the specified start point or end point of the given range is identical to the corresponding start point or end point of sourceRange . 1: Indicates that the specified start point or end point of the given range is after the corresponding start point or end point of sourceRange .

Exceptions
Exception INVALID_STATE_ERR WRONG_DOCUMENT_ERR Description Thrown if the Range.detach() method is already invoked on the Range object. 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.

Syntax
Range.deleteContents()

Parameters
None.

Return values
None.

Exceptions
Exception INVALID_STATE_ERR NO_MODIFICATION_ALLOWED_ERR Description Thrown if the Range.detach() method is already invoked on the Range object. 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.

271

JavaScript Reference

Object: Range

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 stop using a Range object when you are finished with it, the browser will continue to expend some resources maintaining it. Detaching a Range object informs the browser that it can release those resources, making them available to other objects. As a result, it is 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.

Syntax
Range.detach()

Parameters
None.

Return values
None.

Exceptions
Exception INVALID_STATE_ERR Description 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 DocumentFragment node and moves it to a new DocumentFragment object.

Syntax
Range.extractContents()

Parameters
None

Return values

272

JavaScript Reference

Object: Range

This method returns a new DocumentFragment object that contains the extracted range contents.

Exceptions
Exception HIERARCHY_REQUEST_ERR INVALID_STATE_ERR NO_MODIFICATION_ALLOWED_ERR Description Thrown if this action would result in a DocumentType node being inserted into the DocumentFragment object. Thrown if the Range.detach() method is already invoked on the Range object. 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 node is inserted between the resulting pair of Text nodes.

Syntax
Range.insertNode( newNode )

Parameters
Parameter
newNode

Type
Node

Description 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 values
None.

Exceptions
Exception HIERARCHY_REQUEST_ERR INVALID_NODE_TYPE_ERR Description Thrown if this action would result in a DocumentType node being inserted into the DocumentFragment object. Thrown if newNode is an Attr , Entity , Notation , or Document node.

273

JavaScript Reference

Object: Range

Exception INVALID_STATE_ERR NO_MODIFICATION_ALLOWED_ERR WRONG_DOCUMENT_ERR

Description Thrown if the Range.detach() method is already invoked on the Range object. 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. 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.

Syntax
Range.selectNodeContents( refNode )

Parameters
Parameter
refNode

Type
Node

Description 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 values
None.

Exceptions
Exception INVALID_NODE_TYPE_ERR INVALID_STATE_ERR Description Thrown if refNode or an ancestor of refNode is an Attr , Entity , Notation , or Document node. Thrown if the Range.detach() method is already invoked on the Range object.

274

JavaScript Reference

Object: Range

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.

Syntax
Range.selectNode( refNode )

Parameters
Parameter
refNode

Type
Node

Description 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 values
None.

Exceptions
Exception INVALID_NODE_TYPE_ERR Description 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. Thrown if the Range.detach() method is already invoked on the Range object.

INVALID_STATE_ERR

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.

Syntax
Range.setEndAfter( refNode )

Parameters

275

JavaScript Reference

Object: Range

Parameter
refNode

Type
Node

Description 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 values
None.

Exceptions
Exception INVALID_NODE_TYPE_ERR Description 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. Thrown if the Range.detach() method is already invoked on the Range object.

INVALID_STATE_ERR

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.

Syntax
Range.setEndBefore( refNode )

Parameters
Parameter
refNode

Type
Node

Description 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 values
None.

Exceptions

276

JavaScript Reference

Object: Range

Exception INVALID_NODE_TYPE_ERR

Description 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. Thrown if the Range.detach() method is already invoked on the Range object.

INVALID_STATE_ERR

Method: Range.setEnd()
Availability BlackBerry Device Software version 4.7.1 or later

The setEnd() method sets the end point of the range.

Syntax
Range.setEnd( endNode, endOffset )

Parameters
Parameter
endNode endOffset

Type
Node

Description Specifies the node at which the range ends. This parameter must not be null. Specifies the offset for the end of the range from the start of endNode .

int

Return values
None.

Exceptions
Exception INDEX_SIZE_ERR Description 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. Thrown if endNode or an ancestor of endNode is an Entity , Notation , or DocumentType node. Thrown if the Range.detach() method is already invoked on the Range object.

INVALID_NODE_TYPE_ERR INVALID_STATE_ERR

277

JavaScript Reference

Object: Range

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.

Syntax
Range.setStartAfter( refNode )

Parameters
Parameter
refNode

Type
Node

Description 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 values
None.

Exceptions
Exception INVALID_NODE_TYPE_ERR Description 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. Thrown if the Range.detach() method is already invoked on the Range object.

INVALID_STATE_ERR

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.

Syntax
Range.setStartBefore( refNode )

Parameters

278

JavaScript Reference

Object: Range

Parameter
refNode

Type
Node

Description 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 values
None.

Exceptions
Exception INVALID_NODE_TYPE_ERR Description 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. Thrown if the Range.detach() method is already invoked on the Range object.

INVALID_STATE_ERR

Method: Range.setStart()
Availability BlackBerry Device Software version 4.7.1 or later

The setStart() method sets the start point of the range.

Syntax
Range.setStart( startNode, startOffset )

Parameters
Parameter
startNode startOffset

Type
Node

Description Specifies the node at which the range begins. This parameter must not be null. Specifies the offset for the start of the range from the start of startNode .

int

Return values
None.

Exceptions
Exception INDEX_SIZE_ERR Description Thrown if startOffset is greater than the number of child units in startNode .

279

JavaScript Reference

Object: Range

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. Thrown if startNode or an ancestor of startNode is an Entity , Notation , or DocumentType node. Thrown if the Range.detach() method is already invoked on the Range object.

INVALID_NODE_TYPE_ERR INVALID_STATE_ERR

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 the start point of the range.

Syntax
Range.surroundContents( newNode )

Parameters
Parameter
newNode

Type
Node

Description Specifies the node with which to surround the contents.

Return values
None.

Exceptions
Exception BAD_BOUNDARYPOINTS_ERR HIERARCHY_REQUEST_ERR Description Thrown if the range partially selects a non-text node. 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

280

JavaScript Reference

Object: Rect

Exception INVALID_NODE_TYPE_ERR INVALID_STATE_ERR NO_MODIFICATION_ALLOWED_ERR WRONG_DOCUMENT_ERR

Description Thrown if newNode is an Attr , Document , DocumentFragment , DocumentType , Entity , or Notation node. Thrown if the Range.detach() method is already invoked on the Range object. Thrown if an ancestor container of either start point or the end point of the range is read-only. 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.

Syntax
Range.toString()

Parameters
None.

Return values
This method returns the contents of the range as a string.

Exceptions
Exception INVALID_STATE_ERR Description 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.

281

JavaScript Reference

Object: RGBColor

Rect properties
Property name
bottom left right top

Type String String String String

Description Returns the style for the bottom of the Rect. Returns the style for the left side of the Rect. Returns the style for the right side of the Rect. Returns the style for the top of the Rect.

Status read only read only read only read only

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later

Object: RGBColor
Availability Extends BlackBerry Device Software version 4.6 or later
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 overall color. Valid color channel values can be either a numerical value between 0 and 255, or a percentage between 0% and 100%, although values outside of those ranges are not clipped.

RGBColor properties
Property name
blue green red

Type
CSSPrimitiveValu e CSSPrimitiveValu e CSSPrimitiveValu e

Description Returns the blue value of the RGB value. Returns the green value of the RGB value. Returns the red value of the RGB value.

Status read only read only read only

Availability 4.6 or later 4.6 or later 4.6 or later

282

JavaScript Reference

Object: Screen

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
availHeight

Type int

Description 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. 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. Returns the screen space available above the browser window. In the case of the BlackBerry Browser, this property always returns a value of 0. 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. Returns the bit depth of the color palette. This property behaves identically to the pixelDepth property. Returns the height of the BlackBerry device screen, in pixels. Returns the color resolution, in bits per pixel, of the display. Returns the width of the BlackBerry device screen, in pixels.

Status read only

Availability 3.8 or later

availLeft

int

read only

3.8 or later

availTop

int

read only

3.8 or later

availWidth

int

read only

3.8 or later

colorDepth height pixelDepth width

int int int int

read only read only read only read only

3.8 or later 3.8 or later 3.8 or later 3.8 or later

Object: Selection
Availability BlackBerry Device Software version 4.7.1 or later

283

JavaScript Reference

Object: Selection

The Selection object contains one or more Range objects.

Selection properties
Property name
anchorNode anchorOffset focusNode focusOffset isCollapsed

Type
Node

Description Returns the node in which the selection begins. Returns the number of characters within the anchorNode that the selection begins. Returns the node in which the selection ends. Returns the number of characters within the focusNode that the selection ends. Returns true if the start point and end point of the selection are at the same position; returns false if they are not. Returns the number of Range objects contained by the Selection object.

Status read-only read-only read-only read-only read-only

Availability 4.7.1 or later 4.7.1 or later 4.7.1 or later 4.7.1 or later 4.7.1 or later

int
Node

int boolean

rangeCount

int

read-only

4.7.1 or later

Selection methods
Method name
addRange() collapse() collapseToEnd() collapseToStart() deleteFromDocument() getRangeAt() removeRange() removeAllRanges() selectAllChildren()

Description Adds a Range object to the selection. Collapses a selection onto a single boundary point. Moves the anchor of the selection to the same point as the focus. Moves the focus of the selection to the same point as the anchor. Deletes the text contained within the selection from the Document object. Returns a Range object that is present in the selection. Removes the specified Range object from the selection. Removes all Range objects from the selection. Adds all the child nodes of a specified node to the selection.

Availability 4.7.1 or later 4.7.1 or later 4.7.1 or later 4.7.1 or later 4.7.1 or later 4.7.1 or later 4.7.1 or later 4.7.1 or later 4.7.1 or later

284

JavaScript Reference

Object: Selection

Method: Selection.addRange()
Availability BlackBerry Device Software version 4.7.1 or later

The addRange() method adds a Range object to the selection.

Syntax
Selection.addRange( range )

Parameters
Parameter
range

Type
Range

Description Specifies the Range to add to the selection.

Return values
None.

Exceptions
None.

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.

Syntax
Selection.collapseToEnd()

Parameters
None.

Return values
None.

Exceptions
None.

285

JavaScript Reference

Object: Selection

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.

Syntax
Selection.collapseToStart()

Parameters
None.

Return values
None.

Exceptions
None.

Method: Selection.collapse()
Availability BlackBerry Device Software version 4.7.1 or later

The collapse() method collapses a selection onto a single point.

Syntax
Selection.collapse( parentNode, offset )

Parameters
Parameter
parentNode offset

Type
Node

Description Specifies the node into which the selection is collapsed. 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 .

int

Return values

286

JavaScript Reference

Object: Selection

None.

Exceptions
None.

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.

Syntax
Selection.deleteFromDocument()

Parameters
None.

Return values
None.

Exceptions
None.

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.

Syntax
Selection.getRangeAt( index )

Parameters
Parameter
index

Type int

Description Specifies an integer that represents the Range objects position in the frame map. Valid values are from 0 to Selection.rangeCount -1.

Return values

287

JavaScript Reference

Object: Selection

This method returns the Range object at the specified index.

Exceptions
None.

Method: Selection.removeAllRanges()
Availability BlackBerry Device Software version 4.7.1 or later

The removeAllRanges() method removes all Range objects from the selection.

Syntax
Selection.removeAllRanges()

Parameters
None.

Return values
None.

Exceptions
None.

Method: Selection.removeRange()
Availability BlackBerry Device Software version 4.7.1 or later

The removeRange() method removes the specified Range object from the selection.

Syntax
Selection.removeRange( range )

Parameters
Parameter
range

Type
Range

Description Specifies the Range object to remove from the selection.

Return values
None.

Exceptions
288

JavaScript Reference

Object: StyleSheet

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 already populated, the contents are replaced.

Syntax
Selection.selectAllChildren( parentNode )

Parameters
Parameter
parentNode

Type
Node

Description Specifies the node that is the parent of the nodes to add to the selection. The parentNode is not added.

Return values
None.

Exceptions
None.

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 represent either an external style sheet, or an inline style element.

StyleSheet properties
Property name
disabled

Type boolean

Description When true, indicates that the style sheet is not applied.

Status writable

Availability 4.6 or later

289

JavaScript Reference

Object: StyleSheet

Property name

Type

Description 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. Returns the URI of an external style sheet. 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.

Status

Availability

href media

String
MediaList

read only read only

4.6 or later 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. Returns the StyleSheet object that contains the style sheet, if one exists.

read only

4.6 or later

parentStyleShee t

StyleShee t

read only

4.6 or later

290

JavaScript Reference

Object: StyleSheetList

Property name

Type

Description If the style sheet is not the child of another style sheet, this property returns null. Returns the title of the style sheet. The title is often specified in
StyleSheet.ownerNod e.

Status

Availability

title

String

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 you can index the object directly. For example, if you create an instance of a StyleSheetList object called myStyleSheets, then specifying
myStyleSheets.item(2)

is equivalent to specifying
myStyleSheets[2]

291

JavaScript Reference

Object: StyleSheetList

StyleSheetList properties
Property name
length

Type unsigned long

Description Returns the number of style sheets in the list.

Status read only

Availability 4.6 or later

StyleSheetList methods
Method name
item()

Description Returns the StyleSheet object at the specified index in the StyleSheetList.

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

Syntax
StyleSheetList.item( index )

Parameters
Parameter
index

Type int

Description An integer that represents the stylesheets position in stylesheet list. Valid values are 0 to StyleSheetList.length -1.

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

Exceptions
None.

292

JavaScript Reference

Object: Text

Object: Text
Availability Extends BlackBerry Device Software version 4.6 or later
CharacterData

The Text object represents the textual content of an element or attribute. If an element contains no child elements, any text is contained in a single text node in the DOM. Although it is possible to place multiple text objects are adjacent to one another in a document, adjacent text nodes have no meaning in a document. Hence, using Text.splitText() has no visual effect on the document unless one of the nodes is wrapped by an element.

Text methods
Method name
splitText()

Description Breaks the node into two nodes at the specified offset location.

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

Syntax
Text.splitText( offset )

Parameters
Parameter
offset

Type long

Description The offset position at which to split the text.

Return values
Returns the second half of the text as a new Text node, which is automatically added to the DOM tree adjacent to the original Text node.

Exceptions

293

JavaScript Reference

Object: TextEvent

Exception
INDEX_SIZE_ERR NO_MODIFICATION_ALLOWED_ERR

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

Object: TextEvent
Availability Extends BlackBerry Device Software version 4.6 or later
UIEvent

The TextEvent object extends the UIEvent object and represents an event generated by entering characters using either the BlackBerry device or some other input source, such as a voice command. Unlike with KeyboardEvent objects, TextEvent objects can comprise multiple key presses, essentially creating an event after one or more characters have been entered. To create an instance of a TextEvent, you must invoke Document.createEvent() with an input parameter of TextEvent.

TextEvent properties
Property name
data

Type String

Description

Status

Availability 4.6 or later

Returns the value of the characters generated by the read only 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.

Text event types

Event type
textInput

Bubbles yes

Cancelable Description yes Occurs when one or more characters have been entered. This event type includes the following context information:
TextEvent.data , UIEvent.view

294

JavaScript Reference

Object: TextEvent

TextEvent methods
Method name
initTextEvent() initTextEventNS()

Description Initializes the value of a TextEvent. Initializes the value of a TextEvent with the given namespace URI.

Availability 4.6 or later 4.6 or later

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

Syntax
TextEvent.initTextEvent( typeArg, canBubbleArg, cancelableArg, viewArg, dataArg )

Parameters
Parameter
typeArg canBubbleArg cancelableArg viewArg dataArg

Type String boolean boolean

AbstractView

Description Specifies the event type. When true, this parameter indicates that the event can bubble. When true, this parameter indicates that the event can be cancelled. Specifies the window or frame that is generating the event. Specifies the characters generated by the input device. This parameter sets the value of TextEvent.data .

String

Return values
None.

Exceptions
None.

Method: TextEvent.initTextEventNS()
The initTextEventNS() method initializes the value of a TextEvent created by Document.createEvent() with the given namespace URI.

Syntax

295

JavaScript Reference

Object: TreeWalker

TextEvent.initTextEventNS( namespaceURI, typeArg, canBubbleArg, cancelableArg, viewArg, dataArg )

Parameters
Parameter
namespaceURI typeArg canBubbleArg cancelableArg viewArg dataArg

Type String String boolean boolean

AbstractView

Description Specifies the namespace URI associated with this event, or null if no namespace exists. Specifies the event type. When true, this parameter indicates that the event can bubble. When true, this parameter indicates that the event can be cancelled. Specifies the window or frame that is generating the event. Specifies the characters generated by the input device. This parameter sets the value of TextEvent.data .

String

Return values
None.

Exceptions
None.

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 NodeIterator objects, except that TreeWalker presents nodes in a tree-oriented view, rather than the list view presented by NodeIterator. This allows you to use TreeWalker to navigate directly to a parent or child, rather than simply up and down in the list using NodeIterator. Create a TreeWalker using Document.createTreeWalker() .

296

JavaScript Reference

Object: TreeWalker

TreeWalker properties
Property name
currentNode expandEntityReferenc es filter root whatToShow NodeFilt er Node

Type
Node

Description Specifies the current position of the TreeWalker. Returns whether or not the TreeWalker expands the entity references it encounters as it traverses the document. Returns the NodeFilter used to filter nodes for traversal. Returns the Node at which the TreeWalker begins traversing the document. 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

Status writable read only

Availability 4.6 or later 4.6 or later

boolean

read only read only read only

4.6 or later 4.6 or later 4.6 or later

unsigned long

297

JavaScript Reference

Object: TreeWalker

Property name

Type

Description
0x00000800 = SHOW_NOTATION

Status

Availability

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 TreeWalkers 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
firstChild() lastChild() nextNode() nextSibling() parentNode() previousNode() previousSibling()

Description Moves the TreeWalker to the first visible child of the current node. Moves the TreeWalker to the last visible child of the current node. Moves the TreeWalker to the next visible node in the document order, relative to the current node. Moves the TreeWalker to the next sibling of the current node. Moves the TreeWalker to the closest visible ancestor node of the current node. Moves the TreeWalker to the previous visible node in the document order, relative to the current node. Moves the TreeWalker to the previous sibling of the current node.

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

298

JavaScript Reference

Object: TreeWalker

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 of TreeWalker.currentNode is updated to reflect the TreeWalkers new location in the tree. If no visible children exist in the TreeWalkers view, the value of TreeWalker.currentNode remains unchanged.

Syntax
TreeWalker.firstChild()

Parameters
None.

Return values
Returns the node, or null, if the current node has no visible children in the TreeWalkers logical view.

Exceptions
None.

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 of TreeWalker.currentNode is updated to reflect the TreeWalkers new location in the tree. If no visible children exist in the TreeWalkers view, the value of TreeWalker.currentNode remains unchanged.

Syntax
TreeWalker.lastChild()

Parameters
None.

Return values
Returns the node, or null, if the current node has no visible children in the TreeWalkers logical view.

Exceptions
None.

299

JavaScript Reference

Object: TreeWalker

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 current node. The value of TreeWalker.currentNode is updated to reflect the TreeWalkers new location in the tree. If no node exists after the current node in the TreeWalkers view, the value of TreeWalker.currentNode remains unchanged.

Syntax
TreeWalker.nextNode()

Parameters
None.

Return values
Returns the node, or null, if there is no node after the current node in the TreeWalkers logical view.

Exceptions
None.

Method: TreeWalker.nextSibling()
The nextSibling() method moves the TreeWalker to the next sibling of the current node. The value of TreeWalker.currentNode is updated to reflect the TreeWalkers new location in the tree. If no visible sibling node exists after the current node in the TreeWalkers view, the value of TreeWalker.currentNode remains unchanged.

Syntax
TreeWalker.nextSibling()

Parameters
None.

Return values
Returns the node, or null, if the current node has no visible siblings after it in the TreeWalkers logical view.

Exceptions
None.

300

JavaScript Reference

Object: TreeWalker

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 of TreeWalker.currentNode is updated to reflect the TreeWalkers new location in the tree. If no visible ancestor node exists in the TreeWalkers view, the value of TreeWalker.currentNode remains unchanged.

Syntax
TreeWalker.parentNode()

Parameters
None.

Return values
Returns the node, or null, if the current node has no visible ancestor in the TreeWalkers logical view.

Exceptions
None.

Method: TreeWalker.previousNode()
The previousNode() method moves the TreeWalker to the previous visible Node in the document order, relative to the current node. The value of TreeWalker.currentNode is updated to reflect the TreeWalkers new location in the tree. If no node exists before the current node in the TreeWalkers view, the value of TreeWalker.currentNode remains unchanged.

Syntax
TreeWalker.previousNode()

Parameters
None.

Return values
Returns the node, or null, if there is no node before the current node in the TreeWalkers logical view.

Exceptions
None.

301

JavaScript Reference

Object: UIEvent

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 of TreeWalker.currentNode is updated to reflect the TreeWalkers new location in the tree. If no visible sibling node exists before the current node in the TreeWalkers view, the value of TreeWalker.currentNode remains unchanged.

Syntax
TreeWalker.previousSibling()

Parameters
None.

Return values
Returns the node, or null, if the current node has no visible sibling before it in the TreeWalkers logical view.

Exceptions
None.

Object: UIEvent
Availability Extends Extended by BlackBerry Device Software version 4.6 or later
Event 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
detail

Type long

Description Returns detail information about the event.

Status read only

Availability 4.6 or later

302

JavaScript Reference

Object: UIEvent

Property name
view

Type
AbstractVie w

Description Returns a reference to the AbstractView that generated the event.

Status read only

Availability 4.6 or later

User interface events

Event type
DOMFocusIn DOMFocusOut DOMActivate

Bubbles yes yes yes

Cancelable Description no no yes Occurs when an EventTarget receives focus. Occurs when an EventTarget loses focus. 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
initUIEvent()

Description Initializes the value of a UIEvent.

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

Syntax
UIEvent.initUIEvent( typeArg, canBubbleArg, cancelableArg, viewArg, detailArg )

Parameters
Parameter
typeArg

Type String

Description Specifies the event type.

303

JavaScript Reference

Object: Window

Parameter
canBubbleArg cancelableArg viewArg detailArg

Type boolean boolean

AbstractView

Description When true, this parameter indicates that the event can bubble. When true, this parameter indicates that the event can be cancelled. Specifies the window or frame that is generating the event. Specifies the code for the event detail.

long

Return values
None.

Exceptions
None.

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. It returns information about the window.

Window properties
Property name
blackberry closed document frameElement

Type
blackberry

Description Returns a reference to the blackberry object. Returns whether the window is open or closed. This property always has a value of false. Returns the Document object that is contained within the window. Returns the element in which the window is embedded, or null if the window is not embedded in any frame. Returns a NamedFrameMap object that contains a collection of the frames contained by the frameset.

Status read only read only read only read only

Availability 3.8 or later 3.8 or later 3.8 or later 3.8 or later

boolean
Document HTMLElement

frames

NamedFrameMa p

read only

3.8 or later

304

JavaScript Reference

Object: Window

Property name
history innerHeight innerWidth length location navigator name opener orientation

Type
History

Description Returns the History object that contains a collection of recently accessed URLs. Returns the height of the content area, including the horizontal scroll bar, if rendered. Returns the width of the content area, including the vertical scroll bar, if rendered. Returns the number of frames in the parent window. Specifies the URL of the document displayed in the browser window. Returns the Navigator object, which provides information about the BlackBerry Browser. Specifies the name of the window. Returns the Window object that created the window. 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

Status read only read only read only read only writable read only writable read only read only

Availability 3.8 or later 3.8 or later 3.8 or later 3.8 or later 3.8 or later 3.8 or later 3.8 or later 3.8 or later 4.7 or later

int int unsigned long

Location Navigator String Window

int

mode and is turned to the right 90: the BlackBerry device is in landscape mode and turned to the left. read only read only read only read only 3.8 or later 3.8 or later 3.8 or later 3.8 or later

parent screen self top

Window Screen Window Window

Returns the parent Window object. Returns the Screen object, which provides information about the BlackBerry device screen. Returns a reference to the current window. Returns a reference to the top window.

305

JavaScript Reference

Object: Window

Property name
window

Type
Window

Description

Status

Availability 3.8 or later

Returns a reference to the current window. Using read only 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.

Window event handlers

Property name
onabort

Type
EventListene r

Description Specifies the function to perform when the loading of a page or image is aborted. Specifies the function to perform when a form control loses focus after the user has modified the value. Specifies the function to perform when the user clicks the trackball or

Status writable

Availability 4.6 or later

onchange

EventListene r

writable

4.6 or later

onclick

EventListene r

writable

3.8 or later

306

JavaScript Reference

Object: Window

Property name

Type

Description trackwheel on a BlackBerry device. Specifies the function to perform when a key is pressed down while the pointer is over an element. Specifies the function to perform when a key is pressed and released while the pointer is over an element. Specifies the function to perform when a key is released while the pointer is over an element. Specifies the function to perform when the BlackBerry Browser finishes loading a new page or a complete frameset.

Status

Availability

onkeydown

EventListene r

writable

4.6 or later

onkeypress

EventListene r

writable

4.6 or later

onkeyup

EventListene r

writable

4.6 or later

onload

EventListene r

writable

4.6 or later

307

JavaScript Reference

Object: Window

Property name
onmousedown

Type
EventListene r

Description Specifies the function to perform when the user depresses the trackwheel or trackball on a BlackBerry device. Specifies the function to perform when the user moves the pointer while it is over an element. Specifies the function to perform when the user moves the pointer off of an element. Specifies the function to perform when the user moves the pointer over an element. Specifies the function to perform when the user releases the trackwheel

Status writable

Availability 4.6 or later

onmousemove

EventListene r

writable

4.6 or later

onmouseout

EventListene r

writable

4.6 or later

onmouseover

EventListene r

writable

4.6 or later

onmouseup

EventListene r

writable

4.6 or later

308

JavaScript Reference

Object: Window

Property name

Type

Description or trackball on a BlackBerry device. 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. Specifies the function to perform when the user resets a form. Specifies the function to perform when the user selects some text in a text field. Specifies the function to perform when the user submits a form.

Status

Availability

onorientationchan ge

EventListene r

writable

4.7 or later

onreset

EventListene r

writable

3.8 or later

onselect

EventListene r

writable

4.6 or later

onsubmit

EventListene r

writable

3.8 or later

309

JavaScript Reference

Object: Window

Property name
onunload

Type
EventListene r

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

Status writable

Availability 4.6 or later

Window methods
Method name
addEventListener() alert() back() blur() close() confirm() dispatchEvent() find() focus() forward() getComputedStyle() home() moveBy() moveTo() open()

Description Adds an EventListener object to a set of event listeners for the window. Displays a standard alert dialog box with an OK button. Displays the previous URL in the history list. Removes focus from the window. Closes the active window. Displays a standard confirmation dialog box with an OK button and a Cancel button. Dispatches an Event object created by Document.createEvent(). Displays a dialog box that allows a user to enter a string of text and search for it in the current document. Gives focus to the current window. Displays the next element in the history list of the browser. Retrieves the computed style values for an element. Returns to the page that the user set as the browser home page. Moves the window a specified number of pixels in relation to its current co-ordinates. Moves the window's left and top edge to the specified co-ordinates. Opens a new browser window.

Availability 4.6 or later 3.8 or later 3.8 or later 3.8 or later 3.8 or later 3.8 or later 4.6 or later 4.6 or later 3.8 or later 3.8 or later 4.6 or later 3.8 or later 3.8 or later 3.8 or later 3.8 or later

310

JavaScript Reference

Object: Window

Method name
print() prompt() removeEventListener() resizeBy() resizeTo() scroll() scrollBy() scrollTo() stop()

Description Prints the current contents of the window. Displays a prompt dialog box that prompts users for input. Removes an event listener from an EventTarget. Resizes the viewport relative to the current viewport size. Resizes the viewport to the specified width and height. Scrolls the content to a given set of coordinates. Scrolls the content by the given number of pixels. Scrolls the content to a given set of coordinates. Stops the current download.

Availability 3.8 or later 3.8 or later 4.6 or later 3.8 or later 3.8 or later 3.8 or later 3.8 or later 3.8 or later 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.

Syntax
window.addEventListener( type, listener, useCapture )

Parameters
Parameter
type listener useCapture

Type String
EventListener

Description The type of event to add. The EventListener function to be invoked. 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.

boolean

Return values

311

JavaScript Reference

Object: Window

None.

Exceptions
None.

See also
Event , 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.

Syntax
window.alert( message )

Parameters
Parameter
message

Type String

Description The text that is displayed as the dialog box message.

Return values
None.

Exceptions
None.

See also
window.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

312

JavaScript Reference

Object: Window

window.back()

Parameters
None.

Return values
None.

Exceptions
None.

See also
history.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.

Syntax
window.blur()

Parameters
None.

Return values
This method is ignored. No values are returned.

Exceptions
None.

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

313

JavaScript Reference

Object: Window

If no earlier item exists in the window.history array, the BlackBerry Browser is closed and the browser session ends.

Syntax
window.close()

Parameters
None.

Return values
This method is ignored. No values are returned.

Exceptions
None.

See also
history.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 not continue to browse or use the current page until they have closed the dialog box.

Syntax
window.confirm( message )

Parameters
Parameter
message

Type String

Description The text that is displayed as the dialog box message.

Return values
Returns a value of true if the OK button was clicked; returns false if Cancel was clicked.

Exceptions
None.

See also
window.alert() , window.prompt()

314

JavaScript Reference

Object: Window

Method: window.dispatchEvent()
Availability BlackBerry Device Software version 4.6 or later

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

Syntax
window.dispatchEvent( event )

Parameters
Parameter
event

Type
Event

Description The Event object to be dispatched.

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

Exceptions
Exception
UNSPECIFIED_EVENT_TYPE_ERR

Description 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, the search stops and returns a value of true. If the search is restarted with the same term, the browser continues searching from the location of the last search result. If you provide a new search term, the browser begins searching at the start of the document and stops and returns a value of true when the given term is found. Note that the caseSensitive and searchInFrames parameters are optional, but mutually inclusive. That is, you must either specify both of the parameters or neither of them.

Syntax
315

JavaScript Reference

Object: Window

window.find( str [, caseSensitive, searchInFrames ] )

Parameters
Parameter
str caseSensitive searchInFrames

Type String boolean boolean

Description The string of text to search for in the current document. Optional. If true, indicates that the case of the search term should be considered when searching. Optional. If true, indicates that the browser should search for the given term in all currently displayed frames.

Return values
Return a value of true if the string is found; otherwise, returns false.

Exceptions
None.

Method: window.focus()
Availability BlackBerry Device Software version 3.8 or later

The focus() method gives focus to the window.

Syntax
window.focus()

Parameters
None.

Return values
None.

Exceptions
None.

316

JavaScript Reference

Object: Window

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 to history.forward() .

Syntax
window.forward()

Parameters
None.

Return values
None.

Exceptions
None.

See also
history.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 style declaration as a read only value.

Syntax
window.getComputedStyle( elt, pseudoElt )

Parameters
Parameter
elt pseudoElt

Type
Element

Description The element for which to view the style. The pseudo-element for which to modify the style, or null if none.

String

Return values

317

JavaScript Reference

Object: Window

Returns the computed style value for the specified element.

Exceptions
None.

See also
HTMLElement.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.

Syntax
window.home()

Parameters
None.

Return values
None.

Exceptions
None.

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.

Syntax
window.moveBy ( deltaX, deltaY )

Parameters

318

JavaScript Reference

Object: Window

Parameter
deltaX deltaY

Type int int

Description The number of pixels to move the window horizontally. The number of pixels to move the window vertically.

Return values
This method is ignored. No values are returned.

Exceptions
None.

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 .

Syntax
window.moveTo ( deltaX, deltaY )

Parameters
Parameter
deltaX deltaY

Type int int

Description The number of pixels from the left edge of the screen to move the window. The number of pixels from the top edge of the screen to move the window.

Return values
This method is ignored. No values are returned.

Exceptions
None.

319

JavaScript Reference

Object: Window

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 whenever the user opens a link on a page or enters a new URL via the Go to menu item. Consequently, this method essentially has the same net effect in the BlackBerry Browser as specifying a new value for Window.location .

Syntax
window.open( URL [, name ] )

Parameters
Parameter
URL name

Type int String

Description The URL to be displayed in the child window. Optional. The name of the window that is being opened.

Return values
Returns a reference to the new Window object.

Exceptions
None.

See also
window.close()

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.

Syntax
window.print()

Parameters

320

JavaScript Reference

Object: Window

None.

Return values
This method is ignored. No values are returned.

Exceptions
None.

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 line input field. Use a prompt dialog when you need immediate feedback from the user. The user may not continue to browse or use the current page until they have closed the dialog box.

Syntax
window.prompt( message, defaultValue )

Parameters
Parameter
message defaultValue

Type String String

Description The text that is displayed as the dialog box message. The default value of the input field, or null if no default is to be provided.

Return values
Returns the user input as a string. If the user enters no input, this method returns an empty string.

Exceptions
None.

See also
window.alert() , window.confirm()

Method: window.removeEventListener()
Availability BlackBerry Device Software version 4.6 or later

321

JavaScript Reference

Object: Window

The removeEventListener() method removes an event listener from the Window object.

Syntax
window.removeEventListener( type, listener, useCapture )

Parameters
Parameter
type listener useCapture

Type String
EventListener

Description The type of event. The event listener function to be removed. 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.

boolean

Return values
None.

Exceptions
None.

See also
Event , 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() .

Syntax
window.resizeBy( deltaX, deltaY )

Parameters

322

JavaScript Reference

Object: Window

Parameter
deltaX deltaY

Type int int

Description The number of pixels to resize the window by horizontally. The number of pixels to resize the window by vertically.

Return values
None.

Exceptions
None.

See also
window.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.

Syntax
window.resizeTo( width, height )

Parameters
Parameter
width height

Type int int

Description The new width of the viewport, in pixels. The new height of the viewport, in pixels.

Return values
None.

Exceptions
None.

See also
window.resizeBy()

323

JavaScript Reference

Object: Window

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 to window.scrollTo() .

Syntax
window.scroll( x, y )

Parameters
Parameter
x y

Type int int

Description The position along the horizontal access, in pixels, to which to scroll the document. The position along the vertical access, in pixels, to which to scroll the document.

Return values
None.

Exceptions
None.

See also
window.scrollBy() , window.scrollTo()

Method: window.scrollBy()
Availability BlackBerry Device Software version 3.8 or later

The scrollBy() method scrolls the content by the given number of pixels.

Syntax
window.scrollBy( deltaX, deltaY )

Parameters

324

JavaScript Reference

Object: Window

Parameter
deltaX deltaY

Type int int

Description The distance, in pixels, to scroll the document horizontally. The distance, in pixels, to scroll the document vertically.

Return values
None.

Exceptions
None.

See also
window.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 to window.scroll() .

Syntax
window.scrollTo( x, y )

void

Parameters
Parameter
x y

Type int int

Description The position along the horizontal access, in pixels, to which to scroll the document. The position along the vertical access, in pixels, to which to scroll the document.

Return values
None.

Exceptions

325

JavaScript Reference

Object: XMLHttpRequest

None.

See also
window.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.

Syntax
window.stop()

Parameters
None.

Return values
None.

Exceptions
None.

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 current document. To make an HTTP request, you create the instance of the object, open a URL, and send the request. The HTTP status code of the result, as well as the result document are available in the request object afterwards. Because it allows you to communicate with a server in the background, the XMLHttpRequest object enables you to create extremely dynamic documents.

326

JavaScript Reference

Object: XMLHttpRequest

XMLHttpRequest properties
Property name
readyState

Type unsigned short

Description

Status

Availability 4.6 or later

Returns the status of the server's response. Each time read only 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.

responseText

String

responseXML

String

status

unsigned short

Returns the response text entity body. This might read only return only a fragment of the entity body, if the request response is still in the loading state. Returns the XML response entity body. This might read only return only a fragment of the entity body, if the request response is still in the loading state. Returns the HTTP status code sent by the server, or, if read only no status code is available, throws an INVALID_STATE_ERR exception.

4.6 or later

4.6 or later

4.6 or later

327

JavaScript Reference

Object: XMLHttpRequest

Property name
statusText

Type String

Description Returns the HTTP status text sent by the server, or, if no status text is available, throws an INVALID_STATE_ERR exception.

Status read only

Availability 4.6 or later

XMLHttpRequest event handlers

Property name
onreadystatechange

Type
EventListen er

Description Specifies the function to perform when a form control loses focus after the user has modified the value.

Status writable

Availability 4.6 or later

XMLHttpRequest methods
Method name
abort() addEventListener() dispatchEvent() getAllResponseHeaders() getResponseHeader() open() removeEventListener() send() setRequestHeader()

Description Adds an EventListener object to a set of event listeners for the window. Adds an EventListener object to a set of event listeners for the given node. Dispatches an Event object created by Document.createEvent (). Returns a complete set of headers and their values. Returns the value of the given header. Assigns the HTTP method and destination URL, as well as some additional optional parameters, for a pending request. Removes an event listener from an EventTarget. Sends the request to the URL specified by XMLHttpRequest.open(). Specifies the value of a header to be sent with the request.

Availability 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later 4.6 or later

328

JavaScript Reference

Object: XMLHttpRequest

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.

Syntax
XMLHttpRequest.abort()

Parameters
None.

Return values
None.

Exceptions
None.

Method: XMLHttpRequest.addEventListener()
Availability BlackBerry Device Software version 4.6 or later

The addEventListener() method adds an EventListener object to the XMLHttpRequest object.

Syntax
XMLHttpRequest.addEventListener( type, listener, useCapture )

Parameters
Parameter
type listener useCapture

Type String
EventListener

Description The type of event to add. The EventListener function to be invoked. 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.

boolean

329

JavaScript Reference

Object: XMLHttpRequest

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 values
None.

Exceptions
None.

See also
Event , EventListener

Method: XMLHttpRequest.dispatchEvent()
Availability BlackBerry Device Software version 4.6 or later

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

Syntax
XMLHttpRequest.dispatchEvent( event )

Parameters
Parameter
event

Type
Event

Description The Event object to be dispatched.

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

Exceptions
Exception
UNSPECIFIED_EVENT_TYPE_ERR

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

330

JavaScript Reference

Object: XMLHttpRequest

Method: XMLHttpRequest.getAllResponseHeaders()
Availability BlackBerry Device Software version 4.6 or later

The getAllResponseHeaders() method returns a complete set of headers and their values.

Syntax
XMLHttpRequest.getAllResponseHeaders()

Parameters
None.

Return values
Returns all the response headers as a single string, with each header separated by a carriage return and a line feed character.

Exceptions
Exception
INVALID_STATE_ERR

Description This error is thrown if this method is called before any response headers have been received (that is, before the XMLHttpRequest.readyState property has a value of 2, indicating HEADERS_RECEIVED).

See also
XMLHttpRequest.getResponseHeader()

Method: XMLHttpRequest.getResponseHeader()
Availability BlackBerry Device Software version 4.6 or later

The getResponseHeader() method returns the value of a given header.

Syntax
XMLHttpRequest.getResponseHeader( header )

Parameters

331

JavaScript Reference

Object: XMLHttpRequest

Parameter
header

Type String

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

Return values
Returns the value of the given header, or null if the header is not present in the header list. If header matches more than one header in the list of response headers, the values are concatenated into a single comma-separated list.

Exceptions
Exception
INVALID_STATE_ERR

Description This error is thrown if this method is called before any response headers have been received (that is, before the XMLHttpRequest.readyState property has a value of 2, indicating HEADERS_RECEIVED).

See also

XMLHttpRequest.getAllResponseHeaders()

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 a pending request. When this method is successfully invoked, the value for the XMLHttpRequest.readyState property is set to OPENED.

Syntax
XMLHttpRequest.open( method, url [, async] [, user] [, password] )

Parameters
Parameter
method

Type String

Description The HTTP method used to open the connection, This parameter may have one of the following values:
DELETE GET HEAD

332

JavaScript Reference

Object: XMLHttpRequest

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. 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. 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. Optional. Specifies a password, if the server requires user authentication.

async

boolean

user

String

password

String

Return values
None.

Method: XMLHttpRequest.removeEventListener()
Availability BlackBerry Device Software version 4.6 or later

The removeEventListener() method removes an event listener from an EventTarget.

Syntax

333

JavaScript Reference

Object: XMLHttpRequest

XMLHttpRequest.removeEventListener( type, listener, useCapture )

Parameters
Parameter
type listener useCapture

Type String
EventListener

Description The type of event. The event listener function to be removed. 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.

boolean

Return values
None.

Exceptions
None.

See also
Event , 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 called only 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 properly handle the data, you should specify the content type using XMLHttpRequest.setRequestHeader() before invoking this method. If data is not specified, no entity body is sent with the request.

Syntax
XMLHttpRequest.send( [data] )

Parameters

334

JavaScript Reference

Object: XMLHttpRequest

Parameter
data

Type String | Document

Description 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 values
If the request was asynchronous, this method returns the callback when the response has been successfully received.

Exceptions
Exception
ABORT_ERR INVALID_STATE_ERR NETWORK_ERR

Description This error is thrown if the request was cancelled by the user. This error is thrown if this method is called before the request has been opened using XMLHttpRequest.open() . 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 also
XMLHttpRequest.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() .

Syntax
XMLHttpRequest.setRequestHeader( header, value )

Parameters

335

JavaScript Reference

Object: XMLSerializer

Parameter
header

Type String

Description The header to set. This parameter may not have as its value any of the following: AcceptCharset, 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-. The value of the header.

value

String

Return values
None.

Exceptions
Exception
ABORT_ERR INVALID_STATE_ERR NETWORK_ERR

Description This error is thrown if the request was cancelled by the user. This error is thrown if this method is called before the request has been opened using XMLHttpRequest.open() . This error is thrown if
header is not recognized as a valid header name. value is not recognized as a valid header value.

See also
XMLHttpRequest.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 subtree into a string.

336

JavaScript Reference

Object: XMLSerializer

XMLSerializer methods
Method name
serializeToString ()

Description Converts an XML document or subtree into a string.

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

Syntax
XMLSerializer.serializeToString( xmlDocument )

Parameters
Parameter
xmlDocument

Type
Node

Description Specifies the XML document or subtree to convert.

Return values
This method returns a string representation of the given XML document or subtree.

Exceptions
Exception TYPE_MISMATCH_ERR Description Thrown if xmlDocument is null.

Code sample: Converting a string into XML and back to a string again
var xmlString = "<?xml version='1.0' ?>\ <root>\ <level1>\ <option>Option1</option>\ <option>Option2</option>\ <option>Option3</option>\ </level1>\ </root>"; var parser = new DOMParser();

337

JavaScript Reference

Object: XMLSerializer

var xmlDocument = parser.parseFromString( xmlString, "text/xml" ); var serializer = new XMLSerializer(); var string = serializer.serializeToString( xmlDocument ); alert( string )

338

JavaScript Reference

Glossary

Glossary
AJAX Asynchronous JavaScript and XML DES Data Encryption Standard DOM Document Object Model HTML Hypertext Markup Language HTTP Hypertext Transfer Protocol HTTPS Hypertext Transfer Protocol over Secure Sockets Layer IP Internet Protocol IPPP Internet Protocol Proxy Protocol JSON JavaScript Object Notation LAN local area network MIME Multipurpose Internet Mail Extensions MPEG Moving Picture Experts Group NTLM NT LAN Manager PAP Push Access Protocol

339

JavaScript Reference

Glossary

SSL Secure Sockets Layer Triple DES Triple Data Encryption Standard TCP Transmission Control Protocol TLS Transport Layer Security URI Uniform Resource Identifier WAP Wireless Application Protocol WLAN wireless local area network WML Wireless Markup Language WTLS Wireless Transport Layer Security WTP WAP Transaction Protocol XML Extensible Markup Language

340

JavaScript Reference

Provide feedback

Provide feedback
To provide feedback on this deliverable, visit www.blackberry.com/docsfeedback.

341

JavaScript Reference

Legal notice

Legal notice

2010 Research In Motion Limited. All rights reserved. BlackBerry, RIM, Research In Motion, SureType, SurePress and related 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 Communication Corporation. Java and JavaScript are trademarks of Sun Microsystems, Inc. Wi-Fi is a trademark of the Wi-Fi Alliance. All other trademarks are the properties of their respective owners. This documentation including all documentation incorporated by reference herein such as documentation provided or made available at www.blackberry.com/go/docs is provided or made accessible "AS IS" and "AS AVAILABLE" and without condition, endorsement, guarantee, representation, or warranty of any kind by Research In Motion Limited and its affiliated companies ("RIM") and RIM assumes no responsibility for any typographical, technical, or other inaccuracies, errors, or omissions in this documentation. In order to protect RIM proprietary and confidential information and/or trade secrets, this documentation may describe some aspects of RIM technology in generalized terms. RIM reserves the right to periodically change information that is contained in this documentation; however, RIM makes no commitment to provide any such changes, updates, enhancements, or other additions to this documentation to you in a timely manner or at all. This documentation might contain references to third-party sources of information, hardware or software, products or services including components and content such as content protected by copyright and/or third-party web sites (collectively the "Third Party Products and Services"). RIM does not control, and is not responsible for, any Third Party Products and Services including, without limitation the content, accuracy, copyright compliance, compatibility, performance, trustworthiness, legality, decency, links, or any other aspect of Third Party Products and Services. The inclusion of a reference to Third Party Products and Services in this documentation does not imply endorsement by RIM of the Third Party Products and Services or the third party in any way. EXCEPT TO THE EXTENT SPECIFICALLY PROHIBITED BY APPLICABLE LAW IN YOUR JURISDICTION, ALL CONDITIONS, ENDORSEMENTS, GUARANTEES, REPRESENTATIONS, OR WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY CONDITIONS, ENDORSEMENTS, GUARANTEES, REPRESENTATIONS OR WARRANTIES OF DURABILITY, FITNESS FOR A PARTICULAR PURPOSE OR USE, MERCHANTABILITY, MERCHANTABLE QUALITY, NONINFRINGEMENT, SATISFACTORY QUALITY, OR TITLE, OR ARISING FROM A STATUTE OR CUSTOM OR A COURSE OF DEALING OR USAGE OF TRADE, OR RELATED TO THE DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED HEREIN, ARE HEREBY EXCLUDED. YOU MAY ALSO HAVE OTHER RIGHTS THAT VARY BY STATE OR PROVINCE. SOME JURISDICTIONS MAY NOT ALLOW THE EXCLUSION OR LIMITATION OF IMPLIED WARRANTIES AND CONDITIONS. TO THE EXTENT PERMITTED BY LAW, ANY IMPLIED WARRANTIES OR CONDITIONS RELATING TO THE DOCUMENTATION TO THE EXTENT THEY CANNOT BE EXCLUDED AS SET OUT ABOVE, BUT CAN BE LIMITED, ARE HEREBY LIMITED TO NINETY (90) DAYS FROM THE DATE YOU FIRST ACQUIRED THE DOCUMENTATION OR THE ITEM THAT IS THE SUBJECT OF THE CLAIM. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, IN NO EVENT SHALL RIM BE LIABLE FOR ANY TYPE OF DAMAGES RELATED TO THIS DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NONPERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED HEREIN INCLUDING WITHOUT LIMITATION ANY OF THE FOLLOWING DAMAGES: DIRECT, CONSEQUENTIAL, EXEMPLARY,

342

JavaScript Reference

Legal notice

INCIDENTAL, INDIRECT, SPECIAL, PUNITIVE, OR AGGRAVATED DAMAGES, DAMAGES FOR LOSS OF PROFITS OR REVENUES, FAILURE TO REALIZE ANY EXPECTED SAVINGS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, LOSS OF BUSINESS OPPORTUNITY, OR CORRUPTION OR LOSS OF DATA, FAILURES TO TRANSMIT OR RECEIVE ANY DATA, PROBLEMS ASSOCIATED WITH ANY APPLICATIONS USED IN CONJUNCTION WITH RIM PRODUCTS OR SERVICES, DOWNTIME COSTS, LOSS OF THE USE OF RIM PRODUCTS OR SERVICES OR ANY PORTION THEREOF OR OF ANY AIRTIME SERVICES, COST OF SUBSTITUTE GOODS, COSTS OF COVER, FACILITIES OR SERVICES, COST OF CAPITAL, OR OTHER SIMILAR PECUNIARY LOSSES, WHETHER OR NOT SUCH DAMAGES WERE FORESEEN OR UNFORESEEN, AND EVEN IF RIM HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, RIM SHALL HAVE NO OTHER OBLIGATION, DUTY, OR LIABILITY WHATSOEVER IN CONTRACT, TORT, OR OTHERWISE TO YOU INCLUDING ANY LIABILITY FOR NEGLIGENCE OR STRICT LIABILITY. THE LIMITATIONS, EXCLUSIONS, AND DISCLAIMERS HEREIN SHALL APPLY: (A) IRRESPECTIVE OF THE NATURE OF THE CAUSE OF ACTION, DEMAND, OR ACTION BY YOU INCLUDING BUT NOT LIMITED TO BREACH OF CONTRACT, NEGLIGENCE, TORT, STRICT LIABILITY OR ANY OTHER LEGAL THEORY AND SHALL SURVIVE A FUNDAMENTAL BREACH OR BREACHES OR THE FAILURE OF THE ESSENTIAL PURPOSE OF THIS AGREEMENT OR OF ANY REMEDY CONTAINED HEREIN; AND (B) TO RIM AND ITS AFFILIATED COMPANIES, THEIR SUCCESSORS, ASSIGNS, AGENTS, SUPPLIERS (INCLUDING AIRTIME SERVICE PROVIDERS), AUTHORIZED RIM DISTRIBUTORS (ALSO INCLUDING AIRTIME SERVICE PROVIDERS) AND THEIR RESPECTIVE DIRECTORS, EMPLOYEES, AND INDEPENDENT CONTRACTORS. IN ADDITION TO THE LIMITATIONS AND EXCLUSIONS SET OUT ABOVE, IN NO EVENT SHALL ANY DIRECTOR, EMPLOYEE, AGENT, DISTRIBUTOR, SUPPLIER, INDEPENDENT CONTRACTOR OF RIM OR ANY AFFILIATES OF RIM HAVE ANY LIABILITY ARISING FROM OR RELATED TO THE DOCUMENTATION. Prior to subscribing for, installing, or using any Third Party Products and Services, it is your responsibility to ensure that your airtime service provider has agreed to support all of their features. Some airtime service providers might not offer Internet browsing functionality with a subscription to the BlackBerry Internet Service. Check with your service provider for availability, roaming arrangements, service plans and features. Installation or use of Third Party Products and Services with RIM's products and services may require one or more patent, trademark, copyright, or other licenses in order to avoid infringement or violation of third party rights. You are solely responsible for determining whether to use Third Party Products and Services and if any third party licenses are required to do so. If required you are responsible for acquiring them. You should not install or use Third Party Products and Services until all necessary licenses have been acquired. Any Third Party Products and Services that are provided with RIM's products and services are provided as a convenience to you and are provided "AS IS" with no express or implied conditions, endorsements, guarantees, representations, or warranties of any kind by RIM and RIM assumes no liability whatsoever, in relation thereto. Your use of Third Party Products and Services shall be governed by and subject to you agreeing to the terms of separate licenses and other agreements applicable thereto with third parties, except to the extent expressly covered by a license or other agreement with RIM. Certain features outlined in this documentation require a minimum version of BlackBerry Enterprise Server, BlackBerry Desktop Software, and/or BlackBerry Device Software.

343

JavaScript Reference

Legal notice

The terms of use of any RIM product or service are set out in a separate license or other agreement with RIM applicable thereto. NOTHING IN THIS DOCUMENTATION IS INTENDED TO SUPERSEDE ANY EXPRESS WRITTEN AGREEMENTS OR WARRANTIES PROVIDED BY RIM FOR PORTIONS OF ANY RIM PRODUCT OR SERVICE OTHER THAN THIS DOCUMENTATION. Research In Motion Limited 295 Phillip Street Waterloo, ON N2L 3W8 Canada Research In Motion UK Limited Centrum House 36 Station Road Egham, Surrey TW20 9LF United Kingdom Published in Canada

344