This document was uploaded by user and they confirmed that they have the permission to share
it. If you are author or own the copyright of this book, please report to us by using this DMCA
report form. Report DMCA
Overview
Download & View Javascript Reference as PDF for free.
LOSS OF BUSINESS INFORMATION, LOSS OF BUSINESS OPPORTUNITY, OR CORRUPTION OR LOSS OF DATA, FAILURES TO TRANSMIT OR RECEIVE ANY DATA, PROBLEMS ASSOCIATED WITH ANY APPLICATIONS USED IN CONJUNCTION WITH RIM PRODUCTS OR SERVICES, DOWNTIME COSTS, LOSS OF THE USE OF RIM PRODUCTS OR SERVICES OR ANY PORTION THEREOF OR OF ANY AIRTIME SERVICES, COST OF SUBSTITUTE GOODS, COSTS OF COVER, FACILITIES OR SERVICES, COST OF CAPITAL, OR OTHER SIMILAR PECUNIARY LOSSES, WHETHER OR NOT SUCH DAMAGES WERE FORESEEN OR UNFORESEEN, AND EVEN IF RIM HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, RIM SHALL HAVE NO OTHER OBLIGATION, DUTY, OR LIABILITY WHATSOEVER IN CONTRACT, TORT, OR OTHERWISE TO YOU INCLUDING ANY LIABILITY FOR NEGLIGENCE OR STRICT LIABILITY. THE LIMITATIONS, EXCLUSIONS, AND DISCLAIMERS HEREIN SHALL APPLY: (A) IRRESPECTIVE OF THE NATURE OF THE CAUSE OF ACTION, DEMAND, OR ACTION BY YOU INCLUDING BUT NOT LIMITED TO BREACH OF CONTRACT, NEGLIGENCE, TORT, STRICT LIABILITY OR ANY OTHER LEGAL THEORY AND SHALL SURVIVE A FUNDAMENTAL BREACH OR BREACHES OR THE FAILURE OF THE ESSENTIAL PURPOSE OF THIS AGREEMENT OR OF ANY REMEDY CONTAINED HEREIN; AND (B) TO RIM AND ITS AFFILIATED COMPANIES, THEIR SUCCESSORS, ASSIGNS, AGENTS, SUPPLIERS (INCLUDING AIRTIME SERVICE PROVIDERS), AUTHORIZED RIM DISTRIBUTORS (ALSO INCLUDING AIRTIME SERVICE PROVIDERS) AND THEIR RESPECTIVE DIRECTORS, EMPLOYEES, AND INDEPENDENT CONTRACTORS. IN ADDITION TO THE LIMITATIONS AND EXCLUSIONS SET OUT ABOVE, IN NO EVENT SHALL ANY DIRECTOR, EMPLOYEE, AGENT, DISTRIBUTOR, SUPPLIER, INDEPENDENT CONTRACTOR OF RIM OR ANY AFFILIATES OF RIM HAVE ANY LIABILITY ARISING FROM OR RELATED TO THE DOCUMENTATION. Prior to subscribing for, installing, or using any Third Party Products and Services, it is your responsibility to ensure that your airtime service provider has agreed to support all of their features. Installation or use of Third Party Products and Services with RIM's products and services may require one or more patent, trademark, copyright, or other licenses in order to avoid infringement or violation of third party rights. You are solely responsible for determining whether to use Third Party Products and Services and if any third party licenses are required to do so. If required you are responsible for acquiring them. You should not install or use Third Party Products and Services until all necessary licenses have been acquired. Any Third Party Products and Services that are provided with RIM's products and services are provided as a convenience to you and are provided "AS IS" with no express or implied conditions, endorsements, guarantees, representations, or warranties of any kind by RIM and RIM assumes no liability whatsoever, in relation thereto. Your use of Third Party Products and Services shall be governed by and subject to you agreeing to the terms of separate licenses and other agreements applicable thereto with third parties, except to the extent expressly covered by a license or other agreement with RIM. The terms of use of any RIM product or service are set out in a separate license or other agreement with RIM applicable thereto. NOTHING IN THIS DOCUMENTATION IS INTENDED TO SUPERSEDE ANY EXPRESS WRITTEN AGREEMENTS OR WARRANTIES PROVIDED BY RIM FOR PORTIONS OF ANY RIM PRODUCT OR SERVICE OTHER THAN THIS DOCUMENTATION.
Research In Motion Limited 295 Phillip Street Waterloo, ON N2L 3W8 Canada Published in 2008
Research In Motion UK Limited 200 Bath Road Slough, Berkshire SL1 3XE United Kingdom
JavaScript objects Object: Attr Availability BlackBerry® Device Software version 4.6 and later Extends
Node
The Attr object represents an attribute in an Element object. Although Attr objects describe Element objects, they are not actually child nodes of the element they describe. Instead, attributes are treated as properties of elements, and reside outside of the DOM tree. As a result, the Node.parentNode, Node.previousSibling, and Node.nextSibling properties are null for Attr objects. If a declaration for an attribute exists that defines a default value, but that attribute does not yet exist, the attribute is automatically created and attached to an element with the given value.
Properties Property name
Type
Description
Status
Availability
name
String
Returns the name of the attribute. The value of the name property must be unique across all attributes attached to the same Element node.
read only
4.6 and later
ownerElement
Element
Returns the element node that this attribute is attached to. If the read only attribute is not yet attached to an element, the value of this property is null.
4.6 and later
specified
boolean
When true, this property indicates that the value for the attribute has read only been explicitly set.
4.6 and later
If the attribute exists with a default value, this property has a value of false. value
String
Specifies the value of the attribute.
writable
4.6 and later
BlackBerry Browser JavaScript Reference
Object: Blackberry Availability BlackBerry® Device Software version 4.0 and 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.
Properties Property name Type
Description
Status
Availability
location
Returns a pointer to the BlackberryLocation object.
read only
4.1 and later
read only
4.0 and later
BlackberryLocation
This property is available for BlackBerry Device Software Version 4.1 or later. network
String
Returns the wireless network on which the BlackBerry device is communicating. The value may be one of: • • • •
3GPP CDMA iDEN Wi-Fi
Multiple networks may be supported on a single BlackBerry device. If multiple networks are supported, they are returned as a commaseparated list. For example: 3GPP,Wi-Fi
20
JavaScript objects
Object: BlackberryLocation Availability BlackBerry® Device Software version 4.1 and later The BlackberryLocation object is a property of the Blackberry object. It provides access to the GPS location of the BlackBerry device. The GPS location refers to the geographical co-ordinates, latitude and longitude, of the BlackBerry device.
Properties Property name
Type
Description
Status
Availability
GPSSupported
boolean
When true, this property indicates that GPS positioning is supported by the BlackBerry device.
read only
4.1 and later
latitude
double
Returns the current latitude, in degrees, of the BlackBerry device. Positive values indicate northern latitude, negative values indicate southern latitude.
read only
4.1 and later
read only
4.1 and later
read only
4.6 and later
To ensure that the most accurate co-ordinate is returned, you should register a listener using BlackberryLocation.onLocationUpdate() and read acquire the location information within the callback. longitude
double
Returns the current longitude, in degrees, of the BlackBerry device. Positive values indicate eastern longitude, negative values indicate western longitude. To ensure that the most accurate co-ordinate is returned, you should register a listener using BlackberryLocation.onLocationUpdate() and read acquire the location information within the callback.
timestamp
unsigned long
Returns time (in milliseconds since epoch) at which the BlackBerryLocation object was updated. This property is only supported on BlackBerry devices running BlackBerry Device Software version 4.6 or later.
Methods Method name
Description
Availability
onLocationUpdate()
Registers a callback method that is called when the location is updated using BlackberryLocation.refreshLocation().
4.1 and later
refreshLocation()
Requests an update of the location of the BlackBerry device.
4.1 and later
removeLocationUpdate()
Removes a previously registered callback method.
4.6 and later
setAidMode()
Specifies which method the BlackBerry device will use to obtain the GPS location.
4.1 and later
21
BlackBerry Browser JavaScript Reference
Method: onLocationUpdate() The onLocationUpdate() method registers a listener that evaluates a string or calls function whenever the BlackBerry® device receives updated location information. On BlackBerry devices running versions of BlackBerry® Device Software earlier than version 4.6, this method must be passed as a string that is evaluated each time the location is refreshed. On BlackBerry devices running BlackBerry Device Software version 4.6 or later, you can pass a string, or use the method to register a callback function. Once onlocationUpdate() has been invoked, the callback occurs whenever there is an update to the location information. This can be as frequent as once every several seconds. If you have passed the method a function, you can cancel the callback using BlackberryLocation.removeLocationUpdate(). If you have passed a string, the callback cannot be removed. Syntax blackberry.location.onLocationUpdate( callbackFunction | callbackString )
Parameters Parameter
Type
Description
callbackFunction
Function
A JavaScript function. For BlackBerry devices running versions of the BlackBerry Device Software that are earlier than version 4.6, you must specify the callback as a string.
callbackString
String
A string to be evaluated when the location information is updated.
Return values None. Exceptions None. See also BlackberryLocation.refreshLocation(), BlackberryLocation.removeLocationUpdate()
22
JavaScript objects
Method: refreshLocation() The refreshLocation() method requests an update of the location of the BlackBerry® device. This method is asynchronous, so the script continues regardless of whether updated location information has been received. To ensure that location information is updated before reading it, you should first register a listener using BlackberryLocation.onLocationUpdate() that reads BlackberryLocation.latitude and BlackberryLocation.longitude, and call refreshLocation() afterwards. 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 BlackberryLocation.onLocationUpdate(), BlackberryLocation.removeLocationUpdate()
23
BlackBerry Browser JavaScript Reference
Method: removeLocationUpdate() The removeLocationUpdate() method removes a previously registered callback method. This method is only supported on BlackBerry® devices running BlackBerry® Device Software version 4.6 or later. Syntax blackberry.location.removeLocationUpdate( callbackFunction )
Parameters Parameter
Type
Description
callbackFunction
Function
A JavaScript function previously registered by BlackberryLocation.onLocationUpdate().
Return values None. Exceptions None. See also BlackberryLocation.onLocationUpdate(), BlackberryLocation.refreshLocation()
24
JavaScript objects
Method: setAidMode() The BlackberryLocation.setAidMode() specifies which method the BlackBerry® device will use to obtain the GPS location. The device can obtain location information in one of three ways. Aid Mode
Value
Cellsite
0
Assisted
1
Autonomous
2
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. Note: 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. Note: 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.
Syntax blackberry.location.setAidMode( int aidMode )
Parameters Parameter
Type
Description
aidMode
int
The method used to obtain the GPS location. The value for this parameter may be one of: • • •
0 — Cellsite 1 — Assisted 2 —Autonomous
Return values None.
25
BlackBerry Browser JavaScript Reference
Object: CDATASection Availability BlackBerry® Device Software version 4.6 and later Extends
Text
The CDATASection object represents CDATA sections, which escape entire blocks of text, such as XML fragments, source code, or other content that would otherwise be interpreted as XML markup. Only the strings (which represents the end) are parsed. Although this object inherits from the Node object, Node.normalize() does not merge adjacent CDATASection nodes.
26
JavaScript objects
Object: CharacterData Availability BlackBerry® Device Software version 4.6 and later Extends
Node
Extended by Comment, Text The CharacterData object extends the Node object and can be used to access character data in the DOM. No DOM objects directly correspond to CharacterData; rather, the methods and properties are always inherited by other objects that require this functionality, such as Comment, Text, and CDATASection. The content of this node is represented as UTF-16. CharacterData methods all work with numeric character offsets and text ranges, and manipulate ranges of text as a sequence of 16-bit units. Before invoking these methods, you should already know the ranges that you are manipulating.
Properties Property name
Type
Description
Status
data
String
The character data of the current node.
writable
length
int
The length of the content of the data property or the CharacterData.substringData() method.
read only
Methods Method name
Description
appendData()
Appends the given string to the end of the data of the node.
deleteData()
Removes the specified range of data.
insertData()
Inserts a string at the specified location in the data.
replaceData()
Replaces the specified range of data with the given string.
substringData()
Returns the specified range of data from the node.
27
BlackBerry Browser JavaScript Reference
Method: appendData() The appendData() method appends the given string to the end of the data of the node. Syntax CharacterData.appendData( arg )
Parameters Parameter
Type
Description
arg
String
The string to append.
Return values None. Exceptions
28
Exception
Description
NO_MODIFICATION_ALLOWED_ERR
This error is thrown if the Node is read only.
JavaScript objects
Method: deleteData() The deleteData() method removes the specified range of data. Syntax CharacterData.deleteData( offset, count )
Parameters Parameter
Type
Description
offset
int
The offset position from which to start removing.
count
int
The number of 16-bit units to delete. If the sum of offset and count exceeds length, then all 16-bit units from the offset to the end of the data are deleted.
Return values None. Exceptions Exception
Description
INDEX_SIZE_ERR
This error is thrown if offset is negative, or is greater than the number of 16-bit units in the data.
NO_MODIFICATION_ALLOWED_ERR
This error is thrown if the Node is read only.
29
BlackBerry Browser JavaScript Reference
Method: insertData() The insertData() method inserts a string at the specified location in the data. Syntax CharacterData.insertData( offset, arg )
Parameters Parameter
Type
Description
offset
int
The offset position from which to start inserting.
arg
String
The string to insert.
Return values None. Exceptions
30
Exception
Description
INDEX_SIZE_ERR
This error is thrown if offset is negative, or is greater than the number of 16-bit units in the data.
NO_MODIFICATION_ALLOWED_ERR
This error is thrown if the Node is read only.
JavaScript objects
Method: replaceData() The replaceData() method replaces the specified range of data with the given string. Syntax CharacterData.replaceData( offset, count, arg )
Parameters Parameter
Type
Description
offset
int
The offset position from which to start replacing.
count
int
The number of 16-bit units to replace. If the sum of offset and count exceeds length, then all 16-bit units from the offset to the end of the data are replaced.
arg
String
The string with which to replace to the data.
Return values None. Exceptions Exception
Description
INDEX_SIZE_ERR
This error is thrown if offset is negative, or is greater than the number of 16-bit units in the data.
NO_MODIFICATION_ALLOWED_ERR
This error is thrown if the Node is read only.
31
BlackBerry Browser JavaScript Reference
Method: substringData() The substringData() method returns the specified range of data from the node. Syntax CharacterData.substringData( offset, count )
Parameters Parameter
Type
Description
offset
int
The offset position from which to start extracting.
count
int
The number of 16-bit units to extract. If the sum of offset and count exceeds length, 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
32
Exception
Description
INDEX_SIZE_ERR
This error is thrown if offset is negative, or is greater than the number of 16-bit units in the data.
NO_MODIFICATION_ALLOWED_ERR
This error is thrown if the Node is read only.
JavaScript objects
Object: Comment Availability BlackBerry® Device Software version 4.6 and later Extends
CharacterData
The Comment object inherits from the CharacterData object and represents the content of a comment, which begins with . The contents of this node include any characters that exist between those two markers.
33
BlackBerry Browser JavaScript Reference
Object: Counter Availability BlackBerry® Device Software version 4.6 and later The Counter interface is used to represent any counter or counters function value.
Properties Property name
Type
Description
Status
identifier
String
The identifier of the counter.
read only
listStyle
String
The style of the list.
read only
separator
String
The string used to separate nested counters.
read only
34
JavaScript objects
Object: CSSCharsetRule Availability BlackBerry® Device Software version 4.6 and later Extends
CSSRule
The CSSCharsetRule object represents an @charset rule in a CSS style sheet. The @charset rule holds an encoding definition. The value of the encoding attribute does not affect the encoding of text data in the DOM objects; this encoding is always UTF-16. After a style sheet is loaded, the value of the encoding attribute is the value found in the @charset rule. If there was no @charset in the original document, then no CSSCharsetRule object is created. The value of the encoding attribute may also be used as a hint for the encoding used on serialization of the style sheet. The value of the @charset rule (and therefore of the CSSCharsetRule) may not correspond to the encoding the document actually came in; character encoding information e.g. in an HTTP header, has priority (see CSS document representation) but this is not reflected in the CSSCharsetRule.
Properties Property name
Type
Description
Status
encoding
String
The encoding used in the @charset rule.
writable
35
BlackBerry Browser JavaScript Reference
Object: CSSFontFaceRule Availability BlackBerry® Device Software version 4.6 and later Extends
CSSRule
The CSSFontFaceRule interface represents an @font-face rule in a CSS style sheet. The @font-face rule is used to hold a set of font descriptions.
Properties Property name
Type
Description
Status
style
CSSStyleDeclaration
The declaration block for this rule.
read only
36
JavaScript objects
Object: CSSImportRule Availability BlackBerry® Device Software version 4.6 and later Extends
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.
Properties Property name
Type
Description
Status
href
String
The location of the style sheet to be imported. The attribute will not contain the “url(...)” specifier around the URI.
read only
media
MediaList
A list of media types that this style sheet can be used with.
read only
styleSheet
CSSStyleSheet
A pointer to the CSSStyleSheet object that represents the imported style sheet.
read only
37
BlackBerry Browser JavaScript Reference
Object: CSSMediaRule Availability BlackBerry® Device Software version 4.6 and later Extends
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.
Properties Property name
Type
Description
Status
CSSRules
CSSRuleList
A list of the CSS Rules contained within a media block.
read only
media
MediaList
A list of the media types to which this rule applies.
read only
Methods Method name
Description
deleteRule()
Removes a rule from the media block.
insertRule()
Adds a rule to the media block.
38
JavaScript objects
Method: deleteRule() The deleteRule() method removes a rule from the media block within a CSS style sheet. Syntax CSSMediaRule.deleteRule( index )
Parameters Parameter
Type
Description
index
int
The position of the rule to remove in the media block’s collection of rules.
Return values None. Exceptions Exception
Description
INDEX_SIZE_ERR
This error is thrown if index does not correspond to any rule in the media block’s collection of rules.
NO_MODIFICATION_ALLOWED_ERR
This error is thrown if the media rule is read only.
39
BlackBerry Browser JavaScript Reference
Method: insertRule() The insertRule() method adds a rule to the media block. Syntax CSSMediaRule.insertRule( rule, index )
Parameters Parameter
Type
Description
rule
String
The text representing the rule. For rule sets, this contains both the selector and the style declaration. For at rules, this contains both the at-identifier and the rule content.
index
int
The position of the rule in the media block’s collection of rules before which to insert the new rule. If index is equal to the length of the index, the new rule will be added to the end of the media block.
Return values Returns the index position of the newly added rule. Exceptions
40
Exception
Description
HIERARCHY_REQUEST_ERR
This error is thrown if rule is not permitted at the specified index, for example, if you tried to insert an @import rule after a standard rule set or other at-rule.
INDEX_SIZE_ERR
This error is thrown if index does not correspond to any rule in the media block’s collection of rules.
NO_MODIFICATION_ALLOWED_ERR
This error is thrown if the media rule is read only.
SYNTAX_ERR
The error is thrown if the rule has a syntax error and cannot be parsed.
JavaScript objects
Object: CSSPageRule Availability BlackBerry® Device Software version 4.6 and later Extends
CSSRule
The CSSPageRule interface represents a @page rule within a CSS style sheet. The @page rule is used to specify the dimensions, orientation, margins, for paged media.
Properties Property name
Type
Description
Status
selectorText
String
The page selector for the rule.
writable
style
CSSStyleDeclaration
The declaration block of the rule.
read only
41
BlackBerry Browser JavaScript Reference
Object: CSSPrimitiveValue Availability BlackBerry® Device Software version 4.6 and later Extends
CSSValue
The CSSPrimitiveValue object represents a single CSS value. A CSSPrimitiveValue object only occurs in a context of a CSS property. This object has methods to determine the current value of a specific style property, or to explicitly set a style property. Conversions are allowed between absolute values (from millimeters to centimeters, from degrees to radians, and so on) but not between relative values. For example, a pixel value cannot be converted to a centimeter value. With the exception of values representing colors, percentage values can not be converted, since they are relative to another value. Because a color percentage value is relative to a known range (0 to 255), however, a color percentage value can be converted to a number.
Properties Property name
Type
Description
Status
primitiveType
unsigned short
The property value type. The following constants represent the numerical values used to define which units are applied to the property value:
0 = CSS_UNKNOWN: The value is not recognized. 1 = CSS_NUMBER: A simple number value. 2 = CSS_PERCENTAGE: A percentage value. 3 = CSS_EMS: A length value, based on font size. 4 = CSS_EXS: A length value, based on font x-height. 5 = CSS_PX: A length value, in pixels. 6 = CSS_CM: A length value, in centimeters. 7 = CSS_MM: A length value, in millimeters. 8 = CSS_IN: A length value, in inches. 9 = CSS_PT: A length value, in points. 10 = CSS_PC: A length value, in picas. 11 = CSS_DEG: An angle value, in degrees. 12 = CSS_RAD: An angle value, in radians. 13 = CSS_GRAD: An angle value, in grads. 14 = CSS_MS: A time value, in milliseconds. 15 = CSS_S: A time value, in seconds. 16 = CSS_HZ: A frequency value, in Hertz. 17 = CSS_KHZ: A frequency, in kilo Hertz. 18 = CSS_DIMENSION: A number value of an unknown dimension. 19 = CSS_STRING: A simple string value. 20 = CSS_URI: A string value representing a URI. 21 = CSS_IDENT: A string value representing an identifier. 22 = CSS_ATTR: A string value representing an attribute function. 23 = CSS_COUNTER: A counter or counters function. 24 = CSS_RECT: A Rect function. 25 = CSS_RGBCOLOR: An RGB color.
JavaScript objects
Methods Method name
Description
getCounterValue()
Retrieves a Counter value.
getFloatValue()
Retrieves a float value.
getRectValue()
Retrieves a Rect value.
getRGBColorValue()
Retrieves an RGB color value.
getStringValue()
Retrieves a string value.
setFloatValue()
Sets a float value with the specified unit.
setStringValue()
Sets a string value with the specified unit.
43
BlackBerry Browser JavaScript Reference
Method: getCounterValue() The getCounterValue() method retrieves a Counter value. Syntax CSSPrimitiveValue.getCounterValue()
Parameters None. Return values Returns a Counter object representing the value of a CSS_COUNTER. Exceptions Exception
Description
INVALID_ACCESS_ERR
This error is thrown if the CSS value contains no Counter value (that is, if it is not of type CSS_COUNTER).
See Also Counter
44
JavaScript objects
Method: getFloatValue() The getFloatValue() method retrieves a float value in the given unit. You can modify the value using the CSSPrimitiveValue.setFloatValue() method. Syntax CSSPrimitiveValue.getFloatValue( unitType )
Parameters Parameter
Type
Description
unitType
unsigned short
The unit code of the units into which the value should be converted. The unit code must represent one of the following float unit types: • • • • • • • • • • • • • • • • • • •
0 = CSS_UNKNOWN: The value is not recognized. 1 = CSS_NUMBER: A simple number value. 2 = CSS_PERCENTAGE: A percentage value. 3 = CSS_EMS: A length value, based on font size. 4 = CSS_EXS: A length value, based on font x-height. 5 = CSS_PX: A length value, in pixels. 6 = CSS_CM: A length value, in centimeters. 7 = CSS_MM: A length value, in millimeters. 8 = CSS_IN: A length value, in inches. 9 = CSS_PT: A length value, in points. 10 = CSS_PC: A length value, in picas. 11 = CSS_DEG: An angle value, in degrees. 12 = CSS_RAD: An angle value, in radians. 13 = CSS_GRAD: An angle value, in grads. 14 = CSS_MS: A time value, in milliseconds. 15 = CSS_S: A time value, in seconds. 16 = CSS_HZ: A frequency value, in Hertz. 17 = CSS_KHZ: A frequency, in kilo Hertz. 18 = CSS_DIMENSION: A number value of an unknown dimension.
Return values Returns the float value in the given units. Exceptions Exception
Description
INVALID_ACCESS_ERR
This error is thrown if the CSS value contains no float value (that is, if it is not of type CSS_NUMBER, CSS_PERCENTAGE, CSS_EMS, CSS_EXS, CSS_PX, CSS_CM, CSS_MM, CSS_IN, CSS_PT, CSS_PC, CSS_DEG, CSS_RAD, CSS_GRAD, CSS_MS, CSS_S, CSS_HZ, CSS_KHZ, or CSS_DIMENSION), or if the float value cannot be converted into the specified units.
See Also CSSPrimitiveValue.setFloatValue()
45
BlackBerry Browser JavaScript Reference
Method: getRectValue() The getRectValue() method retrieves a Rect value. Syntax CSSPrimitiveValue.getRectValue()
Parameters None. Return values Returns a Rect object representing the value of a CSS_RECT. Exceptions Exception
Description
INVALID_ACCESS_ERR
This error is thrown if the CSS value contains no Rect value (that is, if it is not of type CSS_RECT).
See Also Rect
46
JavaScript objects
Method: getRGBColorValue() 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
Description
INVALID_ACCESS_ERR
This error is thrown if the CSS value contains no RGB color value (that is, if it is not of type CSS_RGB_COLOR).
See Also RGBColor
47
BlackBerry Browser JavaScript Reference
Method: getStringValue() 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
Description
INVALID_ACCESS_ERR
This error is thrown if the CSS value contains no string value (that is, if it is not of type CSS_STRING, CSS_URI, CSS_IDENT, or CSS_ATTR).
See Also CSSPrimitiveValue.setStringValue()
48
JavaScript objects
Method: setFloatValue() The setFloatValue() method sets a float value with the given unit. If the property attached to this value cannot accept the given unit type or the float value, the value will not be changed, and an exception is thrown. Syntax CSSPrimitiveValue.setFloatValue( unitType, floatValue )
Parameters Parameter
Type
Description
unitType
unsigned short
The unit code for the property value. The unit code must represent one of the following float unit types: • • • • • • • • • • • • • • • • • • •
floatValue
float
0 = CSS_UNKNOWN: The value is not recognized. 1 = CSS_NUMBER: A simple number value. 2 = CSS_PERCENTAGE: A percentage value. 3 = CSS_EMS: A length value, based on font size. 4 = CSS_EXS: A length value, based on font x-height. 5 = CSS_PX: A length value, in pixels. 6 = CSS_CM: A length value, in centimeters. 7 = CSS_MM: A length value, in millimeters. 8 = CSS_IN: A length value, in inches. 9 = CSS_PT: A length value, in points. 10 = CSS_PC: A length value, in picas. 11 = CSS_DEG: An angle value, in degrees. 12 = CSS_RAD: An angle value, in radians. 13 = CSS_GRAD: An angle value, in grads. 14 = CSS_MS: A time value, in milliseconds. 15 = CSS_S: A time value, in seconds. 16 = CSS_HZ: A frequency value, in Hertz. 17 = CSS_KHZ: A frequency, in kilo Hertz. 18 = CSS_DIMENSION: A number value of an unknown dimension.
The new float value for the property.
Return values None. Exceptions Exception
Description
INVALID_ACCESS_ERR
This error is thrown if the CSS value contains no float value (that is, if it is not of type CSS_NUMBER, CSS_PERCENTAGE, CSS_EMS, CSS_EXS, CSS_PX, CSS_CM, CSS_MM, CSS_IN, CSS_PT, CSS_PC, CSS_DEG, CSS_RAD, CSS_GRAD, CSS_MS, CSS_S, CSS_HZ, CSS_KHZ, or CSS_DIMENSION), or if the float value cannot be converted into the specified units.
NO_MODIFICATION_ALLOWED_ERR
This error is thrown if the property is read only.
See Also CSSPrimitiveValue.getFloatValue()
49
BlackBerry Browser JavaScript Reference
Method: setStringValue() The setStringValue() method sets a string value with the given unit. If the property attached to this value cannot accept the given unit type or the string value, the value will not be changed, and an exception is thrown. Syntax setStringValue( unitType, stringValue )
Parameters Parameter
Type
Description
unitType
unsigned short
The unit code for the property value. The unit code must represent one of the following string unit types: • • • •
stringValue
String
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.
The new string value for the property.
Return values None. Exceptions Exception
Description
INVALID_ACCESS_ERR
This error is thrown if the CSS value contains no string value (that is, if it is not of type CSS_STRING, CSS_URI, CSS_IDENT, or CSS_ATTR).
NO_MODIFICATION_ALLOWED_ERR
This error is thrown if the property is read only.
See Also CSSPrimitiveValue.getStringValue()
50
JavaScript objects
Object: CSSRule Availability BlackBerry® Device Software version 4.6 and later Extended by CSSCharsetRule, CSSFontFaceRule, CSSImportRule, CSSMediaRule, CSSPageRule, CSSStyleRule, CSSUnknownRule The CSSRule object is the base class used to define any rule in a CSS Style sheet, including both rule sets and @ rules.
Properties Property name
Type
Description
Status
parentRule
CSSRule
The parent rule, if this rule is contained within another rule (for example, a style rule within an @media block).
read only
parentStyleSheet
CSSStyleSheet
The style sheet that contains this rule.
read only
type
unsigned short
The type of rule. The following constants represent the numerical values used read only 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.
51
BlackBerry Browser JavaScript Reference
Object: CSSRuleList Availability BlackBerry® Device Software version 4.6 and later The CSSRuleList object represents an ordered collection of CSSRule objects.
Properties Property name
Type
Description
Status
length
int
The number of rules in the list.
read only
Methods Method name
Description
item()
Returns the rule at the specified index in the collection.
52
JavaScript objects
Method: item() The item() method returns the CSSRule object at the specified index in the CSSRuleList. Syntax CSSRuleList.item( index )
Parameters Parameter
Type
Description
index
int
An integer that represents the CSS rules’s position in rule list. Valid values are 0 to CSSRuleList.length-1.
Return values Returns the rule at the indexth position in CSSRuleList, or null if an invalid index position is specified. Exceptions None. See also CSSRule
53
BlackBerry Browser JavaScript Reference
Object: CSSStyleDeclaration Availability BlackBerry® Device Software version 4.6 and 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.
Properties Property name
Type
Description
Status
azimuth
String
Specifies the direction from which a sound originates.
writable
background
String
Specifies any or all background properties.
writable
backgroundAttachment
String
Specifies whether the background scrolls with the page.
writable
backgroundColor
String
Specifies the background color for an element.
writable
backgroundImage
String
Specifies an image resource to use as the background.
writable
backgroundPosition
String
Specifies the starting position of a background image.
writable
backgroundRepeat
String
Specifies how or if a background image is repeated.
writable
border
String
Specifies any or all border properties for an element.
writable
borderBottom
String
Specifies any or all bottom border properties for an element.
writable
borderBottomColor
String
Specifies the bottom border color for an element
writable
borderBottomStyle
String
Specifies the bottom border style for an element.
writable
borderBottomWidth
String
Specifies the bottom border width of an element.
writable
borderCollapse
String
Specifies whether the table borders are collapsed into a single border. writable
borderColor
String
Specifies the border color for an element
writable
borderLeft
String
Specifies any or all left border properties for an element.
writable
borderLeftColor
String
Specifies the left border color for an element
writable
borderLeftStyle
String
Specifies the left border style for an element.
writable
borderLeftWidth
String
Specifies the left border width of an element.
writable
borderRight
String
Specifies any or all right border properties for an element.
writable
borderRightColor
String
Specifies the right border color for an element
writable
borderRightStyle
String
Specifies the right border style for an element.
writable
borderRightWidth
String
Specifies the right border width of an element.
writable
borderSpacing
String
Specifies the distance between the cell borders when not collapsed.
writable
borderStyle
String
Specifies the border style for an element.
writable
borderTop
String
Specifies any or all top border properties for an element.
writable
borderTopColor
String
Specifies the top border color for an element
writable
borderTopStyle
String
Specifies the top border style for an element.
writable
54
JavaScript objects
Property name
Type
Description
Status
borderTopWidth
String
Specifies the top border width of an element.
writable
borderWidth
String
Specifies the border width of an element.
writable
bottom
String
Specifies the distance of the bottom edge of an element above or below the parent element.
writable
captionSide
String
Specifies the location of the table caption.
writable
clear
String
Specifies the side(s) of an element that may not be adjacent to floating elements.
writable
clip
String
Specifies the shape of the element.
writable
color
String
Specifies the foreground color for an element.
writable
content
String
Used with the :before and :after pseudo-elements to generate content.
writable
counterIncrement
String
Specifies how much the counter is incremented for every occurrence of the element.
writable
counterReset
String
Resets a counter for an element.
writable
cue
String
Specifies any or all cue properties.
writable
cueAfter
String
Specifies a URI containing a sound that is played after an element.
writable
cueBefore
String
Specifies a URI containing a sound that is played before an element.
writable
cursor
String
Specifies the type of cursor.
writable
direction
String
Specifies the base direction of the text.
writable
display
String
Specifies how or if an element is displayed.
writable
elevation
String
Specifies the elevation from which a sound originates.
writable
emptyCells
String
Specifies whether empty cells are displayed when the borders are not writable merged.
CSSFloat
String
Specifies where an image or text will appear in another element.
writable
font
String
Specifies any or all of the font properties for an element.
writable
fontFamily
String
Specifies the font family for an element.
writable
fontSize
String
Specifies the font size for an element.
writable
fontStyle
String
Specifies the style of the font for an element.
writable
fontVariant
String
Specifies whether the font for an element is rendered in small caps.
writable
fontWeight
String
Specifies the thickness of the font for an element.
writable
height
String
Specifies the height of an element.
writable
left
String
Specifies the distance of the left edge of an element from the right or writable left edge of the parent element.
length
int
The number of properties that have been explicitly set.
read only
letterSpacing
String
Specifies the spacing between the characters.
writable
lineHeight
String
Specifies the height of each line in an element.
writable
listStyle
String
Specifies any or all of the list properties.
writable
listStyleImage
String
Specifies the image used for the list marker.
writable
listStylePosition
String
Specifies the location of the list marker.
writable
listStyleType
String
Specifies the type of list marker.
writable
margin
String
Specifies the margin around all sides of an element.
writable
55
BlackBerry Browser JavaScript Reference
Property name
Type
Description
Status
marginBottom
String
Specifies the margin below an element.
writable
marginLeft
String
Specifies the margin to the left of an element.
writable
marginRight
String
Specifies the margin to the right of an element.
writable
marginTop
String
Specifies the margin above an element.
writable
maxHeight
String
Specifies the maximum height for an element.
writable
maxWidth
String
Specifies the maximum width for an element.
writable
minHeight
String
Specifies the minimum height for an element.
writable
minWidth
String
Specifies the minimum width for an element.
writable
orphans
String
Specifies the minimum number of lines left at the bottom of a page.
writable
outline
String
Specifies any or all of the outline properties.
writable
outlineColor
String
Specifies the outline color for an element
writable
outlineStyle
String
Specifies the outline style for an element.
writable
outlineWidth
String
Specifies the outline width for an element.
writable
overflow
String
Specifies the behavior when the content of an element overflows the writable available space for that element.
padding
String
Specifies the padding around all sides of an element
writable
paddingBottom
String
Specifies the padding applied below an element.
writable
paddingLeft
String
Specifies the padding applied to the left of an element.
writable
paddingRight
String
Specifies the padding applied to the right of an element.
writable
paddingTop
String
Specifies the padding applied above an element.
writable
pageBreakAfter
String
Specifies how the page breaks after the element are handled.
writable
pageBreakBefore
String
Specifies how the page breaks before the element are handled.
writable
pageBreakInside
String
Specifies how the page breaks within the element are handled.
writable
parentRule
CSSRule
The CSS Rule that contains this declaration block.
read only
pause
String
Specifies any or all of the pause properties.
writable
pauseAfter
String
Specifies a pause to be observed after an element.
writable
pauseBefore
String
Specifies a pause to be observed before an element.
writable
pitch
String
Specifies the average pitch of the speaking voice.
writable
pitchRange
String
Specifies the variation in average pitch.
writable
playDuring
String
Specifies a sound to be played in the background while an element’s content is spoken.
writable
position
String
Specifies the position of the element.
writable
quotes
String
Specifies the quotation marks to use for embedded quotations.
writable
richness
String
Specifies the brightness of the speaking voice.
writable
right
String
Specifies the distance of the right edge of the of an element from the writable right or left edge of the parent element.
speak
String
Specifies whether text will be rendered aurally.
writable
speakHeader
String
Specifies how table headers are rendered aurally.
writable
speakNumeral
String
Specifies how numerals are spoken.
writable
speakPunctuation
String
Specifies how punctuation is spoken.
writable
speechRate
String
Specifies the speaking rate.
writable
56
JavaScript objects
Property name
Type
Description
Status
stress
String
Specifies the level of intonation of a voice.
writable
tableLayout
String
Specifies whether the column width is fixed or determined by the width of the content.
writable
textAlign
String
Specifies the horizontal alignment of the text for an element.
writable
textDecoration
String
Specifies the decoration applied to the text.
writable
textIndent
String
Specifies the indentation of the first line of text in a block of text.
writable
textTransform
String
Specifies how the text is capitalized.
writable
top
String
Specifies the distance of the top edge of an element above or below the parent element.
writable
unicodeBidi
String
Specifies the Unicode bidirectional algorithm to use.
writable
verticalAlign
String
Specifies the vertical alignment of an element.
writable
visibility
String
Specifies whether elements are rendered or not.
writable
voiceFamily
String
Specifies a list of voice family names.
writable
volume
String
Specifies the median volume of the wave form.
writable
whitepsace
String
Specifies how white space in an element is handled.
writable
widows
String
Specifies the minimum number of lines left at the top of a page.
writable
width
String
Specifies the width of an element.
writable
wordSpacing
String
Specifies the spacing between words.
writable
zIndex
String
Specifies the stack order of an element.
writable
Methods Method name
Description
getPropertyCSSValue()
Returns the value of a CSS property as an object, if the property has been explicitly set.
getPropertyPriority()
Returns the priority of a CSS property.
getPropertyValue()
Returns the value of a CSS property as a string, if the property has been explicitly set.
item()
Returns the name of the CSS property at the specified index in the collection.
removeProperty()
Removes a CSS property from the style declaration block.
setProperty()
Sets the value of a CSS property for the style declaration block.
57
BlackBerry Browser JavaScript Reference
Method: getPropertyCSSValue() The getPropertyCSSValue() method returns the value of a CSS property as an object, if the property has been explicitly set. This method cannot access the shorthand property values. The values for shorthand properties can only be accessed and modified as strings, using CSSStyleDeclaration.getPropertyValue() and CSSStyleDeclaration.setProperty() Syntax CSSStyleDeclaration.getPropertyCSSValue( propertyName )
Parameters Parameter
Type
Description
propertyName
String
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.
58
JavaScript objects
Method: getPropertyPriority() The getPropertyPriority() method returns the priority of a CSS property. This method can be used to determine whether the “!important” qualifier has been specified. Syntax CSSStyleDeclaration.getPriorityProperty( propertyName )
Parameters Parameter
Type
Description
propertyName
String
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.
59
BlackBerry Browser JavaScript Reference
Method: getPropertyValue() The getPropertyValue() method returns the value of a CSS property as a string, if the property has been explicitly set. Syntax CSSStyleDeclaration.getPropertyValue( propertyName )
Parameters Parameter
Type
Description
propertyName
String
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.
60
JavaScript objects
Method: item() The item() method returns the name of the CSS property at the specified index in the collection. Syntax CSSStyleDeclaration.item( index )
Parameters Parameter
Type
Description
index
int
An integer that represents the CSS property’s position in style declaration block.
Return values Returns the name of the CSS property at the indexth position in CSSStyleDeclaration, or an empty string if no property exists at the index position specified. Exceptions None.
61
BlackBerry Browser JavaScript Reference
Method: removeProperty() The removeProperty() method removes a CSS property from the style declaration block. Syntax CSSStyleDeclaration.removeProperty( propertyName )
Parameters Parameter
Type
Description
propertyName
String
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
62
Exception
Description
NO_MODIFICATION_ALLOWED_ERR
This error is thrown if either the style declaration or the property is read only.
JavaScript objects
Method: setProperty() The setProperty() method sets the value of a CSS property for the style declaration block. Syntax CSSStyleDeclaration.setProperty( propertyName, value, priority )
Parameters Parameter
Type
Description
propertyName
String
The name of the new CSS property.
value
String
The value of the new property.
priority
String
The priority of the new property, or an empty string, if no priority is to be set.
Return values None. Exceptions Exception
Description
NO_MODIFICATION_ALLOWED_ERR
This error is thrown if either the style declaration or the property is read only.
SYNTAX_ERR
This error is thrown if the given value has a syntax error and cannot be parsed.
63
BlackBerry Browser JavaScript Reference
Object: CSSStyleRule Availability BlackBerry® Device Software version 4.6 and later Extends
CSSRule
The CSSStyleRule object represents a single rule set in a CSS style sheet.
Properties Property name
Type
Description
Status
selectorText
String
The name of the CSS selector for the rule set.
writable
style
CSSStyleDeclaration
The style values for the CSS selector.
read only
64
JavaScript objects
Object: CSSStyleSheet Availability BlackBerry® Device Software version 4.6 and later Extends
StyleSheet
The CSSStyleSheet object represents a CSS style sheet.
Properties Property name
Type
Description
Status
CSSRules
CSSRuleList
An array of the CSSRule objects in the style sheet.
read only
ownerRule
CSSRule
The CSSImportRule object for imported style sheets. If the style sheet read only is not imported, the value for this property is null.
Methods Method name
Description
deleteRule()
Deletes a CSS Rule at the given position in the CSS style sheet.
insertRule()
Adds a CSS Rule at the given position in the CSS style sheet.
65
BlackBerry Browser JavaScript Reference
Method: deleteRule() The deleteRule() method deletes a CSS Rule at the given position in the CSS style sheet. Syntax CSSStyleSheet.deleteRule( index )
Parameters Parameter
Type
Description
index
int
An integer that represents the CSS rules’s position in the style sheet’s collection of rules.
Return values None. Exceptions
66
Exception
Description
NO_MODIFICATION_ALLOWED_ERR
This error is thrown if the style sheet is read only.
INDEX_SIZE_ERR
This error is thrown if index does not correspond to any rule in the style sheet’s collection of rules.
JavaScript objects
Method: insertRule() The insertRule() method adds a CSS Rule at the given position in the CSS style sheet. Syntax CSSStyleSheet.insertRule( rule, index )
Parameters Parameter
Type
Description
rule
String
The parsable text for the CSS Rule to add. • •
index
int
For rule sets, rule includes both the selector and the style declaration. For at-rules, rule includes both the at-identifier and the rule content.
An integer that represents the position in the style sheet’s collection of rules at which the new rule is inserted. If index is equal to StyleSheet.length, the rule is added to the end of the list of rules.
Return values Returns the position of the newly added style sheet in the style sheet’s collection of rules. Exceptions Exception
Description
NO_MODIFICATION_ALLOWED_ERR
This error is thrown if the style sheet is read only.
INDEX_SIZE_ERR
This error is thrown if index does not correspond to any rule in the style sheet’s collection of rules.
67
BlackBerry Browser JavaScript Reference
Object: CSSUnknownRule Availability BlackBerry® Device Software version 4.6 and later Extends
CSSRule
The CSSUnknownRule represents an unsupported @ rule.
68
JavaScript objects
Object: CSSValue Availability BlackBerry® Device Software version 4.6 and later Extended by CSSPrimitiveValue, CSSValueList The CSSValue object represents a simple or a complex CSS property value.
Properties Property name
Type
Description
Status
CSSValueType
unsigned short
The type of value. The following constants represent the numerical values used to define the value type:
read only
• • • •
0 = CSS_INHERIT: The value is inherited. 1 = CSS_PRIMITIVE: The value is a CSSPrimitiveValue. 2 = CSS_VALUE_LIST: The value is a CSSValueList. 3 = CSS_CUSTOM: The rule is a custom value.
69
BlackBerry Browser JavaScript Reference
Object: CSSValueList Availability BlackBerry® Device Software version 4.6 and later Extends
CSSValue
The CSSValueList objects represents an ordered collection of CSSValue objects. Some properties allow an empty list into their syntax. In that case, these properties take the none identifier. So, an empty list means that the property has the value “none”.
Properties Property name
Type
Description
Status
length
int
The number of property values in the list.
read only
Methods Method name
Description
item()
Returns the CSSValue object at the specified index in the CSSValueList.
70
JavaScript objects
Method: item() The item() method returns the CSSValue object at the specified index in the CSSValueList. Syntax CSSValueList.item( index )
Parameters Parameter
Type
Description
index
int
An integer that represents the CSS property value’s position in value list. Valid values are 0 to CSSValueList.length-1.
Return values Returns the property value at the indexth position in CSSValueList, or null if an invalid index position is specified. Exceptions None.
71
BlackBerry Browser JavaScript Reference
Object: CustomEvent Availability BlackBerry® Device Software version 4.6 and later Extends
Event
The CustomEvent object represents an unknown event type. This object is typically used for application-specific event types. To create an instance of a CustomEvent, you must invoke Document.createEvent() with an input parameter of ”CustomEvent”.
Properties Property name
Type
Description
detail
Object
Specifies some detail information about the Event, depending on the read only type of event.
Methods Method name
Description
initCustomEventNS()
Initializes the value of a CustomEvent created by Document.createEvent().
72
Status
JavaScript objects
Method: initCustomEventNS() The initCustomEventNS() method initializes the value of a CustomEvent created by Document.createEvent(). Syntax CustomEvent.initCustomEvent( arg, canBubbleArg, cancelableArg, detailArg )
Parameters Parameter
Type
Description
arg
int
The event type.
canBubbleArg
boolean
If true, specifies that the event can bubble.
cancelableArg
boolean
If true, specifies that the event can be cancelled.
detailArg
long
The event’s detail.
Return values None. Exceptions None.
73
BlackBerry Browser JavaScript Reference
Object: Document Availability BlackBerry® Device Software version 4.6 and later Extends
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.
Properties Property name
Type
Description
Status
defaultView
AbstractView
The default view of the document.
read only
doctype
DocumentType
The document type declaration associated with the document.
read only
documentElement
Element
The root element in a document.
read only
implementation
DOMImplementation The DOMImplementation object that handles this document.
parentWindow
Window
A reference to the parent window. If no parent window exists, this property read only points to the current active window.
styleSheets
StyleSheetList
An array of all the style sheets in the document.
read only
read only
Methods Method name
Description
createAttribute()
Creates a new attribute node with the given name.
createAttributeNS()
Creates a new attribute object with the given qualified name and namespace URI.
createCDATASection()
Creates a new CDATASection object, which represents a block of uninterpreted content.
createComment()
Creates a new Comment object with the given text as content.
createDocumentFragment()
Creates an empty DocumentFragment object.
createElement()
Creates a new Element object of the specified type.
createElementNS()
Creates a new Element object of the given qualified name and namespace URI.
createEntityReference()
Creates a new EntityReference object with the given name.
createEvent()
Creates a new Event object of the given type.
createNodeIterator()
Creates a new NodeIterator object, which you can use to iterate through a set of Document nodes rooted at the given node.
createProcessingInstruction()
Creates a new ProcessingInstruction object with the given name and data.
createTextNode()
Creates a new text node containing the given text.
createTreeWalker()
Creates a TreeWalker object, which you can use to traverse the specified document subtree.
getElementById()
Returns the element node with the given ID value.
getElementsByTagName()
Returns a NodeList object that contains an array of a document’s descendent element nodes with the specified tag name.
getElementsByTagNameNS()
Returns a NodeList object that contains an array of a document’s descendent element nodes with the given local name and namespace URI.
74
JavaScript objects
Method name
Description
getOverrideStyle()
Retrieves the override CSSStyleDeclaration object for the given element.
importNode()
Imports a node from a different document.
75
BlackBerry Browser JavaScript Reference
Method: createAttribute() The createAttribute() method creates a new Attr node with the given name. Once created, the attribute instance can be bound to an element using Element.setAttributeNode() This method only populates the Node.nodeName property for the created attribute and sets the attribute’s value to null. To create an attribute with a qualified name and namespace URI, use Document.createAttributeNS(). Syntax Document.createAttribute( name )
Parameters Parameter
Type
Description
name
String
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
Description
INVALID_CHARACTER_ERR
This error is thrown if newChild is one of the given node’s ancestors, or if the given node does not allow children of the type of newChild node.
See also Attr, Element.setAttribute(), Element.setAttributeNode()
76
JavaScript objects
Method: createAttributeNS() The createAttributeNS() method creates a new Attr object with the given qualified name and namespace URI. Once created, the attribute instance can be bound to an element using Element.setAttributeNode(). Syntax Document.createAttribute( namespaceURI, qualifiedName )
Parameters Parameter
Type
Description
namespaceURI
String
The namespace of the new attribute.
qualifiedName
String
The qualified name of the attribute to create.
Return values Returns the new attribute object with the following properties set: Property
Description
Node.nodeName
The qualified name.
Node.namespaceURI
The namespace URI for the attribute.
Node.prefix
The prefix, extracted from the qualified name of the new attribute. If there is no prefix, this property is set to null.
Node.localName
The local name for the attribute, extracted from the qualified name.
Node.nodeValue
An empty string.
Attr.name
Equivalent to Node.nodeName.
Exceptions Exception
Description
INVALID_CHARACTER_ERR
This error is thrown if qualifiedName contains an illegal character.
NAMESPACE_ERR
This error is thrown if: • • • •
NOT_SUPPORTED_ERR
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/”
This error is thrown if the document does not support XML namespaces.
See also Attr, Element.setAttributeNode()
77
BlackBerry Browser JavaScript Reference
Method: createCDATASection() The createCDATASection() method creates a new CDATASection object, which represents a block of uninterpreted content. HTML documents do not support CDATASection objects. Syntax Document.createCDATASection( data )
Parameters Parameter
Type
Description
data
String
The contents of the CDATASection node.
Return values Returns the new CDATASection object. Exceptions Exception
Description
NOT_SUPPORTED_ERR
This error is thrown if the document is an HTML document.
See also CDATASection
78
JavaScript objects
Method: createComment() The createComment() method creates a new Comment object with the given text as content. Syntax Document.createComment( data )
Parameters Parameter
Type
Description
data
String
The contents of the Comment node.
Return values Returns the new Comment object. Exceptions None. See also Comment
79
BlackBerry Browser JavaScript Reference
Method: createDocumentFragment() The createDocumentFragment() method creates an empty DocumentFragment object. A DocumentFragment object can be used to hold and move a portion of a document—such as multiple parent nodes and their children—at once. Syntax Document.createDocumentFragment()
Parameters None. Return values Returns the new empty DocumentFragment object. Exceptions None. See also DocumentFragment
80
JavaScript objects
Method: createElement() The createElement() method creates a new Element object of the specified type. Attributes can be set directly on the returned object. If the Element type returned has any attributes with default values, those attributes will be created and attached to the element with their default values. Syntax Document.createElement( tagName )
Parameters Parameter
Type
Description
tagName
String
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
Description
INVALID_CHARACTER_ERR
This error is thrown if tagName contains an illegal character.
See also Attr, Element
81
BlackBerry Browser JavaScript Reference
Method: createElementNS() The createElementNS() method creates a new Element object of the given qualified name and namespace URI. Attributes can be set directly on the returned object. Syntax Document.createElementNS( namespaceURI, qualifiedName )
Parameters Parameter
Type
Description
namespaceURI
String
The namespace of the new element.
qualifiedName
String
The qualified name of the element to create.
Return values Returns the new Element object, with the following properties set: Property
Description
Node.nodeName
The qualified name.
Node.namespaceURI
The namespace URI for the attribute.
Node.prefix
The prefix, extracted from the qualified name of the new attribute. If there is no prefix, this property is set to null.
Node.nodeValue
An empty string.
Element.tagName
Equivalent to Node.nodeName.
Exceptions Exception
Description
INVALID_CHARACTER_ERR
This error is thrown if qualifiedName contains an illegal character.
NAMESPACE_ERR
This error is thrown if: • • • •
See also Attr, Element
82
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/”
JavaScript objects
Method: createEntityReference() The createEntityReference() method creates a new EntityReference object with the given name. If the referenced entity is known, then that object’s list of child nodes is made the same as the corresponding Entity node. Syntax Document.createEntityReference( name )
Parameters Parameter
Type
Description
name
String
The name of the entity to reference.
Return values Returns the new EntityReference object. Exceptions Exception
Description
INVALID_CHARACTER_ERR
This error is thrown if name contains an illegal character.
NOT_SUPPORTED_ERR
This error is thrown if the document is an HTML document.
See also Entity, EntityReference
83
BlackBerry Browser JavaScript Reference
Method: createEvent() The createEvent() method creates a new Event object of the given type. If the event is to be dispatched via Node.dispatchEvent(), then the appropriate initialization method must be called after the event has been created, and before it is dispatched, in order to initialize the event’s values. This method is used to create events when it is inconvenient or unnecessary for the user to create an event themselves. Syntax Document.createEvent( eventType )
Parameters Parameter
Type
Description
eventType
String
The type of event to create.
Return values Returns the new Event object. Exceptions Exception
Description
NOT_SUPPORTED_ERR
This error is thrown if the implementation does not support the specified Event interface.
See also Event
84
JavaScript objects
Method: createNodeIterator() The createNodeIterator() method creates a new NodeIterator object, which you can use to iterate through a set of Document nodes rooted at the given node. Syntax Document.createNodeIterator( root, whatToShow, filter, entityReferenceExpansion )
Parameters Parameter
Type
Description
root
Node
The node to be iterated with its children. The NodeIterator object is initially positioned just before this node. The value of root must not be null.
whatToShow
unsigned long
The types of nodes to show in the tree view presented by the NodeIterator. The value may be one or more of: • • • • • • • • • • • • •
Multiple values may be specified using a bitwise OR. Note that because attributes, entities, and notations are not the child of any other node, they never appear in the NodeIterator’s logical view unless root is defined as a Node of that type. If the respective object is not defined as the root, then SHOW_ATTRIBUTE, SHOW_ENTITY, and SHOW NOTATION have no meaning. filter
NodeFilter
entityReferenceExpansion boolean
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.
Return values Returns the new NodeIterator object. Exceptions Exception
Description
NOT_SUPPORTED_ERR
This error is thrown if the specified root is null.
See also NodeIterator
85
BlackBerry Browser JavaScript Reference
Method: createProcessingInstruction() The createProcessingInstruction() method creates a new ProcessingInstruction object with the given name and data. Syntax Document.createProcessingInstruction( target,data )
Parameters Parameter
Type
Description
target
String
The target of the processing instruction.
data
String
The data to store in the processing instruction.
Return values Returns the new ProcessingInstruction object. Exceptions Exception
Description
INVALID_CHARACTER_ERR
This error is thrown if target contains an illegal character.
NOT_SUPPORTED_ERR
This error is thrown if the document is an HTML document.
See also ProcessingInstruction
86
JavaScript objects
Method: createTextNode() The createTextNode() method creates a new Text node containing the given text. You can create new text nodes to add text to an existing node, then use Node.normalize() to merge them into a single node later on. Syntax Document.createTextNode( text )
Parameters Parameter
Type
Description
text
String
The string of text that the Text node is to contain.
Return values Returns the new Text object. Exceptions Exception
Description
INVALID_CHARACTER_ERR
This error is thrown if name contains an illegal character.
NOT_SUPPORTED_ERR
This error is thrown if the document is an HTML document.
See also Text
87
BlackBerry Browser JavaScript Reference
Method: createTreeWalker() 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 Parameter
Type
Description
root
Node
The node that will serve as the root for this TreeWalker object. The TreeWalker.currentNode property to the value of root.
whatToShow
unsigned long
The types of nodes to show in the tree view. The value may be one or more of: • • • • • • • • • • • • •
Multiple values may be specified using a bitwise OR. Note that because attributes, entities, and notations are not the child of any other node, they never appear in the TreeWalker’s logical view unless root is defined as a Node of that type. If the respective object is not defined as the root, then SHOW_ATTRIBUTE, SHOW_ENTITY, and SHOW NOTATION have no meaning. filter
NodeFilter
entityReferenceExpansion boolean
The filter to use with this TreeWalker object. This parameter may be null. When true, this method expands entity reference nodes.
Return values Returns the new TreeWalker object. Exceptions Exception
Description
NOT_SUPPORTED_ERR
This error is thrown if the specified root is null.
See also TreeWalker
88
JavaScript objects
Method: getElementById() The getElementById() method returns the Element node with the given ID value. Syntax Document.getElementById( elementID )
Parameters Parameter
Type
Description
elementID
String
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. Example The following example appends a text node as a child of a new Paragraph element, then appends the Paragraph node as a child of the node divb. Function appendTextNode() { var divb = document.getElementById(‘b’); var str = document.getElementById(‘a’).value; var pnode = document.createElement(‘p’); var tnode = document.createTextNode(str); pnode.appendChild(tnode); divb.appendChild(pnode); }
See also Element
89
BlackBerry Browser JavaScript Reference
Method: getElementsByTagName() The getElementsByTagName() method returns a NodeList object that contains an array of a document’s descendent Element nodes with the specified tag name. Syntax Document.getElementsByTagName( tagName )
Parameters Parameter
Type
Description
tagName
String
The name of the tag to match on. Specify a value of “*” to match all elements.
Return 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
90
JavaScript objects
Method: getElementsByTagNameNS() The getElementsByTagNameNS() method returns a NodeList object that contains an array of a document’s descendent Element nodes with the given local name and namespace URI. Syntax Document.getElementsByTagNameNS( namespaceURI, localName )
Parameters Parameter
Type
Description
namespaceURI
String
The namespace of the elements to match on. Specify a value of “*” to match all elements.
localName
String
The local name of the elements to match on (that is, the qualified name minus the prefix). Specify a value of “*” to match all local elements.
Return 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
91
BlackBerry Browser JavaScript Reference
Method: getOverrideStyle() The getOverrideStyle() method retrieves the override CSSStyleDeclaration object for the given element. Override styles take precedence over authored styles, although authored styles which contain the “!important” declaration maintain precedence and cannot be overridden using this method. Using this method, you can override an explicitly linked style sheet without changing the authored style sheet itself. Syntax Document.getOverrideStyle( elt, pseudoElt )
Parameters Parameter
Type
Description
elt
Element
The element for which to modify the style.
pseudoElt
String
The pseudo-element for which to modify the style. This parameter may be null.
Return values Returns the CSSStyleDeclaration object. Exceptions None. See also CSSStyleDeclaration
92
JavaScript objects
Method: importNode() The importNode() method imports a node from a different document. This method is similar to Node.cloneNode(), except that it functions across documents. The returned node has no parent, and the source node is not altered or removed from the original document; this method creates a new copy of the source node. Importing a node creates a new node object owned by the document the node is imported into, with values identical to the Node.nodeName and Node.nodeType, plus the attributes related the namespaces. Additional information is copied as appropriate to the node type. Syntax Document.importNode( importedNode, deep )
Parameters Parameter
Type
Description
importedNode
Node
The node to import into the current document.
deep
boolean
When true, this method imports the given node and the subtree. When false, this method only imports the given node; it does not include the subtree. This parameter has no effect when the given node is an Attr, EntityReference, or Notation node.
Return values Returns the imported node. Exceptions Exception
Description
NOT_SUPPORTED_ERR
This error is thrown if the node type being imported is not supported.
See also Node.cloneNode()
93
BlackBerry Browser JavaScript Reference
Object: DocumentFragment Availability BlackBerry® Device Software version 4.6 and later Extends
Node
The DocumentFragment object is a lightweight Document object, used to create or extract only a portion of a document. A DocumentFragment behaves like a conventional Node object, except that it does not need to be fully formed. 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.
94
JavaScript objects
Object: DocumentType Availability BlackBerry® Device Software version 4.6 and later Extends
Node
The DocumentType object represents the doctype for a document. If a document has a doctype, it will be a reference to this object.
Properties Property name
Type
Description
Status
entities
NamedNodeMap
A list of all the general entities defined within the DTD.
read only
internalSubset
String
The contents of the DTD subset. Contains the string between the “[“ and “]” read only characters.
name
String
The name of the DTD.
read only
notations
NamedNodeMap
A list of all the notations defined within the DTD.
read only
publicId
String
The public identifier of the external subset.
read only
systemId
String
The system identifier of the external subset.
read only
95
BlackBerry Browser JavaScript Reference
Object: DOMException Availability BlackBerry® Device Software version 4.6 and later The DOMException object represents an error which prevents an operation from completing.
Constants Error code
Exception
Description
1
INDEX_SIZE_ERR
This error is thrown if an index or size is negative, or is greater than the permitted value.
2
DOMSTRING_SIZE_ERR
This error is thrown if a range of text does not fit into a DOMString.
3
HIERARCHY_REQUEST_ERR
This error is thrown if a node is inserted where it is not permitted.
4
WRONG_DOCUMENT_ERR
This error is thrown if a node is used in a different document than the one that created it.
5
INVALID_CHARACTER_ERR
This error is thrown if an invalid or illegal character is used.
6
NO_DATA_ALLOWED_ERR
This error is thrown if data is specified for a node which does not permit data.
7
NO_MODIFICATION_ALLOWED_ERR
This error is thrown if an attempt is made to modify an object which does not permit modifications.
8
NOT_FOUND_ERR
This error is thrown if an attempt is made to reference a node that does not exist.
9
NOT_SUPPORTED_ERR
This error is thrown if the implementation does not support the requested type of object or operation.
10
INUSE_ATTRIBUTE_ERR
This error is thrown if an attribute added to an Element is already an attribute of another Element object.
11
INVALID_STATE_ERR
This error is thrown if an attempt is made to use an object that is not usable.
12
SYNTAX_ERR
Thie error is thrown if an invalid or illegal string is specified.
13
INVALID_MODIFICATION_ERR
This error is thrown if an attempt is made to modify the type of an underlying object.
14
NAMESPACE_ERR
This error is thrown if an attempt is made to create or modify an object in a way that does not comply with namespaces.
15
INVALID_ACCESS_ERR
This error is thrown if a parameter or operation is not supported by the underlying object.
96
JavaScript objects
Object: DOMImplementation Availability BlackBerry® Device Software version 4.6 and 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.
Methods Method name
Description
createCSSStyleSheet()
Creates a new CSS stylesheet document object.
createDocument()
Creates a new XML or HTML document object.
createDocumentType()
Creates an empty document type node.
hasFeature()
Determines whether the DOM implementation implements a specific feature.
97
BlackBerry Browser JavaScript Reference
Method: createCSSStyleSheet() The createCSSStyleSheet() method creates a new CSSStyleSheet object. Syntax DOMImplementation.createCSSStyleSheet( title, media )
Parameters Parameter
Type
Description
title
String
The title of the CSS style sheet.
media
String
A comma-separated list of media types associated with the new style sheet.
Return values Returns the new CSSStyleSheet object. Exceptions Exception
Description
SYNTAX_ERR
This error is thrown if media has a syntax error that prevents the browser from being able to parse it.
See also CSSStyleSheet
98
JavaScript objects
Method: createDocument() The createDocument() method creates a new XML or HTML Document object. Syntax DOMImplementation.createDocument( namespaceURI, qualifiedName, doctype )
Parameters Parameter
Type
Description
namespaceURI
String
The namespace of the new document.
qualifiedName
String
The qualified name of the document to create.
doctype
DocumentType
The type of document to be created, or null.
Return values Returns the new Document object. Exceptions Exception
Description
INVALID_CHARACTER_ERR
This error is thrown if qualifiedName contains an illegal character.
NAMESPACE_ERR
This error is thrown if: • • • •
qualifiedName is malformed, qualifiedName has a prefix, but namespaceURI is null prefix is “xml”, but namespaceURI is not “http://www.w3.org/XML/1998/namespace” qualifiedName is “xmlns”, but namespaceURI is not “http://www.w3.org/2000/xmlns/”
NOT_SUPPORTED_ERR
This error is thrown if the document does not support XML namespaces.
WRONG_DOCUMENT_ERR
This error is thrown if doctype has already been used with a different document or was created from a different implementation.
See also Document
99
BlackBerry Browser JavaScript Reference
Method: createDocumentType() The createDocumentType() method creates an empty DocumentType node. Syntax DOMImplementation.createDocumentType( qualifiedName, publicId, systemId )
Parameters Parameter
Type
Description
qualifiedName
String
The qualified name of the document.
publicId
String
The qualified name of the document to create.
systemId
String
The type of document to be created, or null.
Return values Returns the new DocumentType object. Exceptions Exception
Description
INVALID_CHARACTER_ERR
This error is thrown if qualifiedName contains an illegal character.
NAMESPACE_ERR
This error is thrown if: • • • •
See also DocumentType
100
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/”
JavaScript objects
Method: hasFeature() The hasFeature() method determines whether the DOM implementation implements a specific feature. This is equivalent to functionality provided using Node.isSupported(). Syntax DOMImplementation.hasFeature( feature, version )
Parameters Parameter
Type
Description
feature
String
The name of the feature to test.
version
String
The version of the feature to test. This parameter may be null. If version is not specified, this method returns true if any version of the feature is supported.
Return 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()
101
BlackBerry Browser JavaScript Reference
Object: Element Availability BlackBerry® Device Software version 4.6 and later Extends
Node
Extended by HTMLElement The Element object represents an element in an HTML or XML document. Elements may have attributes associated with them. You can use the Node.attributes property to retrieve a map of all the attributes attached to the element. This object provides several methods for handling all the available attributes, individual attribute values, or individual Attr objects.
Properties Property name
Type
Description
Status
tagName
String
The name of the element.
read only
Methods Method name
Description
getAttribute()
Retrieves the value of the attribute of the given name.
getAttributeNode()
Retrieves the attribute node of the given name.
getAttributeNodeNS()
Retrieves the attribute node with the given namespace URI and local name.
getAttributeNS()
Retrieves the value of the attribute with the given namespace URI and local name.
getElementsByTagName()
Returns a NodeList object that contains an array of an element’s descendent element nodes with the specified tag name.
getElementsByTagNameNS()
Returns a NodeList object that contains an array of an element’s descendent element nodes with the given local name and namespace URI.
hasAttribute()
Determines whether an attribute of the given name is specified on the element.
hasAttributeNS()
Determines whether an attribute of the given namespace and local name is specified on the element.
removeAttribute()
Removes the attribute of the given name from the element node.
removeAttributeNode()
Removes the specified attribute node from the element node.
removeAttributeNS()
Removes the attribute node with the given namespace URI and local name from the element node.
setAttribute()
Adds a new attribute to an element, and sets it to the given value.
setAttributeNode()
Adds a new attribute node to an element.
setAttributeNodeNS()
Adds a new attribute node to an element.
setAttributeNS()
Adds a new attribute to an element, and sets it to the given value.
102
JavaScript objects
Method: getAttribute() The getAttribute() method retrieves the value of the attribute of the given name. Note that this method returns a copy of the value, rather than the value itself. As a result, you cannot use this method to actually change the value; you must use methods such as Element.getAttributeNode() or Element.getAttributeNodeNS() to change the value of the attribute. Syntax Element.getAttribute( name )
Parameters Parameter
Type
Description
name
String
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
103
BlackBerry Browser JavaScript Reference
Method: getAttributeNode() The getAttributeNode() method retrieves the attribute node of the given name. Unlike Element.getAttribute(), this method allows you to access the Attr object without having to iterate over the Node.attributes property. Syntax Element.getAttributeNode( name )
Parameters Parameter
Type
Description
name
String
The name of the attribute node to retrieve.
Return values Returns the Attr object with a Node.nodeName property of name, or a value of null the specified attribute doesn’t exist. Exceptions None. See also Attr, Element.getAttribute(), Element.getAttributeNodeNS(), Element.getAttributeNS(), Node.attributes
104
JavaScript objects
Method: getAttributeNodeNS() The getAttributeNodeNS() method retrieves the Attr node with the given namespace URI and local name. Syntax Element.getAttributeNodeNS( namespaceURI, localName )
Parameters Parameter
Type
Description
namespaceURI
String
The namespace of the attribute to retrieve. Specifying a value of null makes this method functionally equivalent to Element.getAttributeNode().
localName
String
The local name of the attribute to retrieve.
Return values Returns the Attr object with the given namespace URL and local name, or a value of null the specified attribute doesn’t exist. Exceptions Exception
Description
NOT_SUPPORTED_ERR
This error is thrown if the document does not support XML namespaces.
See also Attr
105
BlackBerry Browser JavaScript Reference
Method: getAttributeNS() The getAttribute() method retrieves the value of the Attr with the given namespace URI and local name. Syntax Element.getAttribute( namespaceURI, localName )
Parameters Parameter
Type
Description
namespaceURI
String
The namespace of the attribute for which to retrieve the value. Specifying a value of null makes this method functionally equivalent to Element.getAttribute().
localName
String
The local name of the attribute for which to retrieve the value.
Return 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
Description
NOT_SUPPORTED_ERR
This error is thrown if the document does not support XML namespaces.
See also Attr
106
JavaScript objects
Method: getElementsByTagName() The getElementsByTagName() method returns a NodeList object that contains an array of an element’s descendent Element nodes with the specified tag name. This method is identical to Document.getElementsByTagName(), except that it allows you to search a smaller subset of Element nodes. Syntax Element.getElementsByTagName( name )
Parameters Parameter
Type
Description
tagName
String
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()
107
BlackBerry Browser JavaScript Reference
Method: getElementsByTagNameNS() The getElementsByTagNameNS() method returns a NodeList object that contains an array of an element’s descendent Element nodes with the given local name and namespace URI. This method is identical to Document.getElementsByTagNameNS(), except that it allows you to search a smaller subset of Element nodes. Syntax Element.getElementsByTagNameNS( namespaceURI, localName)
Parameters Parameter
Type
Description
namespaceURI
String
The namespace of the elements to match on. Specify a value of “*” to match all elements. Specifying a value of null makes this method functionally equivalent to Element.getElementsByTagName().
localName
String
The local name of the elements to match on (that is, the qualified name minus the prefix). Specify a value of “*” to match all local elements.
Return 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
Description
NOT_SUPPORTED_ERR
This error is thrown if the document does not support XML namespaces.
See also Document.getElementsByTagName(), Document.getElementsByTagNameNS(), Element.getElementsByTagName()
108
JavaScript objects
Method: hasAttribute() The hasAttribute() method determines whether an attribute of the given name is specified on the element. You can use this method to verify that an attribute is attached to an element before retrieving it. Syntax Element.hasAttribute( name )
Parameters Parameter
Type
Description
name
String
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.
109
BlackBerry Browser JavaScript Reference
Method: hasAttributeNS() The hasAttribute() method determines whether an attribute of the given namespace and local name is specified on the element. You can use this method to verify that an attribute is attached to an element before retrieving it. Syntax Element.hasAttributeNS( namespaceURI, localName)
Parameters Parameter
Type
Description
namespaceURI
String
The namespace of the attribute to check.
localName
String
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
110
Exception
Description
NOT_SUPPORTED_ERR
This error is thrown if the document does not support XML namespaces.
JavaScript objects
Method: removeAttribute() The removeAttribute() method removes the Attr node of the given name from the element node. If you are removing an attribute from the Element object that is known to have a default value, the attribute will immediately be reattached to the element with its default value, as well as its corresponding namespace URI, local name, and prefix, if applicable. If the attribute has no specified or default value, this method has no effect. Syntax Element.removeAttribute( name )
Parameters Parameter
Type
Description
name
String
The name of the attribute node to remove.
Return values None. Exceptions Exception
Description
NO_MODIFICATION_ALLOWED_ERR
This error is thrown if the Element node is read only.
NOT_FOUND_ERR
This error is thrown if no node exists in the Element with a nodeName vlaue of name.
See also Attr
111
BlackBerry Browser JavaScript Reference
Method: removeAttributeNode() The removeAttributeNode() method removes the specified Attr node from the element node. If you are removing an attribute from the Element object that is known to have a default value, the attribute will immediately be reattached to the element with its default value, as well as its corresponding namespace URI, local name, and prefix, if applicable. Syntax Element.removeAttributeNode( oldAttr )
Parameters Parameter
Type
Description
oldAttr
Attr
The Attribute node to remove from the attribute list.
Return values The removed Attr object. Exceptions Exception
Description
NO_MODIFICATION_ALLOWED_ERR
This error is thrown if the Element node is read only.
NOT_FOUND_ERR
This error is thrown if the oldAttr node does not exist in the Element.
See also Attr
112
JavaScript objects
Method: removeAttributeNS() The removeAttributeNS() method removes the Attr node with the given namespace URI and local name from the element node. If you are removing an attribute from the Element object that is known to have a default value, the attribute will immediately be reattached to the element with its default value, as well as its corresponding namespace URI, local name, and prefix, if applicable. If the attribute has no specified or default value, this method has no effect. Syntax Element.removeAttributeNS( namespaceURI, localName )
Parameters Parameter
Type
Description
namespaceURI
String
The namespace of the attribute to retrieve.
localName
String
The local name of the attribute to retrieve.
Return values None. Exceptions Exception
Description
NO_MODIFICATION_ALLOWED_ERR
This error is thrown if the Element node is read only.
NOT_SUPPORTED_ERR
This error is thrown if the document does not support XML namespaces.
See also Attr
113
BlackBerry Browser JavaScript Reference
Method: setAttribute() The setAttribute() method adds a new Attr node to an element, and sets it to the given value. If an attribute with the given name already exists on the Element node, its value is changed to the given value. This method only sets values as text strings, not entities. If the value contains any markup syntax (for example, if the value is an EntityReference), it will not be parsed and it must be properly escaped. If you want to assign values containing entities, you should use Element.setAttributeNode() or Element.setAttributeNodeNS(). Syntax Element.getAttribute( name, value )
Parameters Parameter
Type
Description
name
String
The nam e of the attribute to create or modify.
value
String
The value to set the attribute to, in string form.
Return values None. Exceptions Exception
Description
INVALID_CHARACTER_ERR
This error is thrown if name contains an illegal character.
NO_MODIFICATION_ALLOWED_ERR
This error is thrown if the Element node is read only.
See also Attr, Element.setAttributeNode(), Element.setAttributeNodeNS(), Element.setAttributeNS()
114
JavaScript objects
Method: setAttributeNode() The setAttributeNode() method adds a new Attr node to an element. If an attribute node with the same name as the new Attr node already exists on an element, that Attr node is replaced. Unlike Element.setAttribute(), this method allows you to add DOM nodes, instead of specifying separate arguments for the attribute name and value. Note that your attribute nodes cannot be reused in multiple elements; you must either clone the Attr node, or remove an Attr node from another element before adding it to a new element. Syntax Element.setAttributeNode( newAttr )
Parameters Parameter
Type
Description
newAttr
Attr
The node of the Attribute 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
Description
INUSE_ATTRIBUTE_ERR
This error is thrown if newAttr is already an attribute of of another Element object. To add an attribute used elsewhere, you must clone it, and then add it.
NO_MODIFICATION_ALLOWED_ERR
This error is thrown if the Element object is read only.
WRONG_DOCUMENT_ERR
This error is thrown if newAttr was created from a different document than the one that created this Element object.
See also Attr, Element.setAttribute(), Element.setAttributeNodeNS(), Element.setAttributeNS()
115
BlackBerry Browser JavaScript Reference
Method: setAttributeNodeNS() The setAttributeNodeNS() method adds a new Attr node to an element. If an Attr node with the same namespace and local name as the new Attr node already exists on an element, that attribute node is replaced. Unlike Element.setAttributeNS(), this method allows you to add DOM nodes, instead of specifying separate arguments for the attribute name and value. Note that your attribute nodes cannot be reused in multiple elements; you must either clone the Attr node, or remove an Attr node from another element before adding it to a new element. Syntax Element.getAttributeNodeNS( newAttr )
Parameters Parameter
Type
Description
newAttr
Attr
The node of the Attribute 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
Description
INUSE_ATTRIBUTE_ERR
This error is thrown if newAttr is already an attribute of of another Element object. To add an attribute used elsewhere, you must clone it, and then add it.
NO_MODIFICATION_ALLOWED_ERR
This error is thrown if the Element object is read only.
NOT_SUPPORTED_ERR
This error is thrown if the document does not support XML namespaces.
WRONG_DOCUMENT_ERR
This error is thrown if newAttr was created from a different document than the one that created this Element object.
See also Attr, Element.setAttribute(), Element.setAttributeNode(), Element.setAttributeNS()
116
JavaScript objects
Method: setAttributeNS() The setAttributeNS() method adds a new Attr node to an element, and sets it to the given value. If an attribute with the given namespace and local name already exists on the Element node, its prefix is change to the prefix portion of the qualified name, and its value is changed to the given value. This method only sets values as text strings, not entities. If the value contains any markup syntax (for example, if the value is an EntityReference), it will not be parsed and it must be properly escaped. If you want to assign values containing entities, you should use Element.setAttributeNode() or Element.setAttributeNodeNS(). Syntax Element.setAttributeNS( namespaceURI, qualifiedName, value )
Parameters Parameter
Type
Description
namespaceURI
String
The namespace of the attribute to create or modify.
qualifiedName
String
The qualified name of the attribute to create or modify.
value
String
The value of the attribute, in string form.
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
Description
INVALID_CHARACTER_ERR
This error is thrown if name contains an illegal character.
NAMESPACE_ERR
This error is thrown if: • • • •
qualifiedName is malformed, qualifiedName has a prefix, but namespaceURI is null prefix is “xml”, but namespaceURI is not “http://www.w3.org/XML/1998/namespace” qualifiedName is “xmlns”, but namespaceURI is not “http://www.w3.org/2000/xmlns/”
NO_MODIFICATION_ALLOWED_ERR
This error is thrown if the Element node is read only.
NOT_SUPPORTED_ERR
This error is thrown if the document does not support XML namespaces.
See also Attr, Element.setAttribute(), Element.setAttributeNode(), Element.setAttributeNodeNS()
117
BlackBerry Browser JavaScript Reference
Object: Entity Availability BlackBerry® Device Software version 4.6 and later Extends
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. The Entity name is stored in the Node.nodeName property. However, the actual content of the entity is contained within the Entity’s children. An Entity node has no parent; the Node.parentNode property for an entity will always be null. Entity nodes and their children are read only and can not be modified once they have been added to a document. If you need to change the content of an Entity object, you must create a new one, then update all the EntityReference objects that referred to the old Entity to refer to the new Entity instead.
Properties Property name
Type
Description
Status
notationName
String
For unparsed entities, the name of the notation for the entity. For parsed entities, the value of this property is null.
read only
publicId
String
The public identifier associated with the entity.
read only
systemId
String
The system identifier associated with this entity.
read only
118
JavaScript objects
Object: EntityReference Availability BlackBerry® Device Software version 4.6 and later Extends
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.
119
BlackBerry Browser JavaScript Reference
Object: Event Availability BlackBerry® Device Software version 4.6 and later Extended by 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. For example, the MouseEvent object, which inherits from Event through the UIEvent object, supplies additional properties supplying information such as the MouseEvent.button, MouseEvent.screenX and MouseEvent.screenY for where the current mouse event took place.
Properties Property name
Type
Description
Status
bubbles
boolean
When true, the event is a bubbling event.
read only
cancelable
boolean
When true, the action of the event can be cancelled using preventDefault().
read only
cancelBubble
boolean
When true, bubbling of the event is disabled.
writable
currentTarget
EventTarget
The node of the Document object that is currently handling the event.
read only
eventPhase
unsigned short
The phase that the event is currently in. Valid values include:
read only
• • •
1: Indicates that the event is in the capturing phase. 2: Indicates that the event is in being handled by the target node. 3: Indicates that the event is in the bubbling phase.
target
EventTarget
The target node to which the event was dispatched.
read only
timeStamp
unsigned long
The time (in milliseconds since epoch) at which the event was created.
read only
type
String
The name of the event.
read only
Methods Method name
Description
initEvent()
Initializes the properties of an Event object created by Document.createEvent().
preventDefault()
Cancels the event, preventing the default action from occuring.
stopPropagation()
Prevents further propagation of this event during an event flow.
120
JavaScript objects
Method: initEvent() The Event.initEvent() initializes the properties of an Event object created by Document.createEvent(). This method must be called before the event has been dispatched using Node.dispatchEvent(). Syntax Event.initEvent( eventTypeArg, canBubbleArg, cancelableArg )
Parameters Parameter
Type
Description
eventTypeArge
String
Specifies the event type.
canBubbleArg
boolean
When true, this parameter indicates that the event will bubble.
cancelableArg
boolean
When true, this parameter indicates that Event.preventDefault() can cancel the event.
Return values None. Exceptions None. See also CustomEvent.initCustomEventNS(), KeyboardEvent.initKeyboardEvent(), MouseEvent.initMouseEvent(), MutationEvent.initMutationEvent(), TextEvent.initTextEvent(), UIEvent.initUIEvent()
121
BlackBerry Browser JavaScript Reference
Method: preventDefault() The preventDefault() method cancels the event, preventing the default action from occuring. Calling this method for an event whose cancelable property is set to false will have no effect. Syntax Event.preventDefault()
Method: stopPropagation() The stopPropagation() method prevents further propagation of this event during an event flow. If this method is called by any EventListener, the event will no longer propagate through the tree. The event will complete the dispatch to all listeners on the current EventTarget before the event flow stops. This method can be used at any stage of the event flow. Syntax Event.stopPropagation()
Object: EventException Availability BlackBerry® Device Software version 4.6 and later The EventException object represents an error that occurs when initializing or dispatching an event.
Constants Error code
Exception
Description
0
UNSPECIFIED_EVENT_TYPE_ERR
This error is thrown if the Event object’s type was not specified by initializing the event before the method was called, or if the type was given a value of null or an empty string.
1
DISPATCH_REQUEST_ERR
This error is thrown if an attempt is made to dispatch an Event object that has already been dispatched.
124
JavaScript objects
Object: EventListener Availability BlackBerry® Device Software version 4.6 and later The EventListener object represents an event listener, which is used to listen for and handle events as they occur. EventListeners are registered on an EventTarget, the node(s) within the DOM that may be impacted by an event. Events may be registered against Node, Window, or XMLHttpRequest. Listeners should be removed from the target after it has been used.
Methods Method name
Description
handleEvent()
Called whenever an event occurs the EventListener object was registered to listen for.
125
BlackBerry Browser JavaScript Reference
Method: handleEvent() The handleEvent() method is called whenever an event occurs on the object for which the EventListener was registered. Syntax EventListener.handleEvent( evt )
Parameters Parameter
Type
Description
evt
Event
The event type that the EventListener is registered to listen for.
Return values None. Exceptions None.
126
JavaScript objects
Object: History Availability BlackBerry® Device Software version 4.2 and 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.
Properties Property name
Type
Description
Status
current
String
Returns the complete URL of the current history entry.
read only
length
int
Returns the number of URLs in the history list.
read only
Methods Method name
Description
back()
Displays the previous URL in the BlackBerry® Browser History list.
forward()
Displays the next element in the BlackBerry Browser History list.
go()
Causes the BlackBerry Browser to display the URL that is the specified number of URLs before or after the current item in the BlackBerry Browser History list.
127
BlackBerry Browser JavaScript Reference
Method: back() The back() method displays the previous URL in the BlackBerry® Browser History list. This method is functionally equivalent to the user clicking Back in the BlackBerry Browser menu or clicking the Escape key during a browser session, or specifying History.go(-1). Syntax history.back()
Parameters None. Return values None. Exceptions None. Example The following code fragment adds a custom button to an HTML page that displays the previous item in the History list:
See also History.forward(), History.go(), Window.history
128
JavaScript objects
Method: forward() The forward() method displays the next element in the BlackBerry® Browser History list. This method is functionally equivalent to the user clicking Forward in the BlackBerry Browser menu, or specifying History.go(1). Syntax history.forward()
Parameters None. Return values None. Exceptions None. Example The following code fragment adds a custom button to an HTML page that displays the next item in the History list:
See also History.back(), History.go(), Window.history
129
BlackBerry Browser JavaScript Reference
Method: go() The go() method causes the BlackBerry® Browser to display the given URL, or the URL at the given index location in the URL that is the specified number of URLs before or after the current item in the BlackBerry Browser History list. Syntax history.go( targetURLposition )
Parameters Parameter
Type
Description
targetURLposition
int
The position of the URL to display, relative to the current URL in the History list. A positive value moves forward in the history list; a negative value moves backward.
Return values None. Exceptions None. Example The following code fragment adds a custom button that causes the browser to display the URL three positions earlier than the current URL in the History list:
See also History.back(), History.forward(), Window.history
130
JavaScript objects
Object: HTMLAnchorElement Availability BlackBerry® Device Software version 4.6 and later Extends