Object: CSSPrimitiveValue

Help Center

Search This Document

Download PDF

Availability	BlackBerry® Device Software version 4.6 or later
Extends	`CSSValue`

The CSSPrimitiveValue object represents a single CSS value. A CSSPrimitiveValue object only occurs in the 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.

CSSPrimitiveValue properties

Property name	Type	Description	Status	Availability
`primitiveType`	unsigned short	Returns the property value type. The following constants represent the numerical values used to define which units are applied to the property value: `0` = `CSS_UNKNOWN`: The value is not recognized. `1` = `CSS_NUMBER`: A simple number value. `2` = `CSS_PERCENTAGE`: A percentage value. `3` = `CSS_EMS`: A length value, based on font size. `4` = `CSS_EXS`: A length value, based on font x-height. `5` = `CSS_PX`: A length value, in pixels. `6` = `CSS_CM`: A length value, in centimeters. `7` = `CSS_MM`: A length value, in millimeters. `8` = `CSS_IN`: A length value, in inches. `9` = `CSS_PT`: A length value, in points. `10` = `CSS_PC`: A length value, in picas. `11` = `CSS_DEG`: An angle value, in degrees. `12` = `CSS_RAD`: An angle value, in radians. `13` = `CSS_GRAD`: An angle value, in grads. `14` = `CSS_MS`: A time value, in milliseconds. `15` = `CSS_S`: A time value, in seconds. `16` = `CSS_HZ`: A frequency value, in Hertz. `17` = `CSS_KHZ`: A frequency, in kiloHertz. `18` = `CSS_DIMENSION`: A number value of an unknown dimension. `19` = `CSS_STRING`: A simple string value. `20` = `CSS_URI`: A string value representing a URI. `21` = `CSS_IDENT`: A string value representing an identifier. `22` = `CSS_ATTR`: A string value representing an attribute function. `23` = `CSS_COUNTER`: A counter or counters function. `24` = `CSS_RECT`: A `Rect` function. `25` = `CSS_RGBCOLOR`: An `RGBColor` function.	read only	4.6 or later

Property name

Type

Description

Status

Availability

primitiveType

unsigned short

Returns the property value type. The following constants represent the numerical values used to define which units are applied to the property value:

0 = CSS_UNKNOWN: The value is not recognized.
1 = CSS_NUMBER: A simple number value.
2 = CSS_PERCENTAGE: A percentage value.
3 = CSS_EMS: A length value, based on font size.
4 = CSS_EXS: A length value, based on font x-height.
5 = CSS_PX: A length value, in pixels.
6 = CSS_CM: A length value, in centimeters.
7 = CSS_MM: A length value, in millimeters.
8 = CSS_IN: A length value, in inches.
9 = CSS_PT: A length value, in points.
10 = CSS_PC: A length value, in picas.
11 = CSS_DEG: An angle value, in degrees.
12 = CSS_RAD: An angle value, in radians.
13 = CSS_GRAD: An angle value, in grads.
14 = CSS_MS: A time value, in milliseconds.
15 = CSS_S: A time value, in seconds.
16 = CSS_HZ: A frequency value, in Hertz.
17 = CSS_KHZ: A frequency, in kiloHertz.
18 = CSS_DIMENSION: A number value of an unknown dimension.
19 = CSS_STRING: A simple string value.
20 = CSS_URI: A string value representing a URI.
21 = CSS_IDENT: A string value representing an identifier.
22 = CSS_ATTR: A string value representing an attribute function.
23 = CSS_COUNTER: A counter or counters function.
24 = CSS_RECT: A Rect function.
25 = CSS_RGBCOLOR: An RGBColor function.

read only

4.6 or later

CSSPrimitiveValue methods

Method name	Description	Availability
`getCounterValue()`	Retrieves a `Counter` value.	4.6 or later
`getFloatValue()`	Retrieves a float value.	4.6 or later
`getRectValue()`	Retrieves a `Rect` value.	4.6 or later
`getRGBColorValue()`	Retrieves an `RGBColor` value.	4.6 or later
`getStringValue()`	Retrieves a string value.	4.6 or later
`setFloatValue()`	Sets a float value with the specified unit.	4.6 or later
`setStringValue()`	Sets a string value with the specified unit.	4.6 or later

Method: CSSPrimitiveValue.getCounterValue()

Availability

BlackBerry® Device Software version 4.6 or later

The getCounterValue() method retrieves a Counter value.

Syntax

CSSPrimitiveValue.getCounterValue()

Parameters

None.

Return values

Returns a Counter object representing the value of a CSS_COUNTER.

Exceptions

Exception	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` ).

Method: CSSPrimitiveValue.getFloatValue()

Availability

BlackBerry® Device Software version 4.6 or later

The getFloatValue() method retrieves a float value in the given unit. You can modify the value using the CSSPrimitiveValue.setFloatValue() method.

Syntax

CSSPrimitiveValue.getFloatValue( unitType )

Parameters

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 kiloHertz. `18` = `CSS_DIMENSION`: A number value of an unknown dimension.

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

Method: CSSPrimitiveValue.getRectValue()

Availability

BlackBerry® Device Software version 4.6 or later

The getRectValue() method retrieves a Rect value.

Syntax

CSSPrimitiveValue.getRectValue()

Parameters

None.

Return values

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

Method: CSSPrimitiveValue.getRGBColorValue()

Availability

BlackBerry® Device Software version 4.6 or later

The getRGBColorValue() method retrieves an RGBColor value.

Syntax

CSSPrimitiveValue.getRGBColorValue()

Parameters

None.

Return values

Returns an RGBColor object representing the value of a CSS_RGBCOLOR.

Exceptions

Exception	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`).

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

Method: getStringValue()

Availability

BlackBerry® Device Software version 4.6 or later

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

Syntax

CSSPrimitiveValue.getStringValue()

Parameters

None.

Return values

Returns the value of a string.

Exceptions

Exception	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`).

Method: CSSPrimitiveValue.setFloatValue()

Availability

BlackBerry® Device Software version 4.6 or later

The setFloatValue() method sets a float value with the given unit. If the property attached to this value cannot accept the given unit type or the float value, the value will not be changed, and an exception is thrown.

Syntax

CSSPrimitiveValue.setFloatValue( unitType, floatValue )

Parameters

Parameter	Type	Description
`unitType`	unsigned short	The property value type. The following constants represent the numerical values used to define which units are applied to the property value: `0` = `CSS_UNKNOWN`: The value is not recognized. `1` = `CSS_NUMBER`: A simple number value. `2` = `CSS_PERCENTAGE`: A percentage value. `3` = `CSS_EMS`: A length value, based on font size. `4` = `CSS_EXS`: A length value, based on font x-height. `5` = `CSS_PX`: A length value, in pixels. `6` = `CSS_CM`: A length value, in centimeters. `7` = `CSS_MM`: A length value, in millimeters. `8` = `CSS_IN`: A length value, in inches. `9` = `CSS_PT`: A length value, in points. `10` = `CSS_PC`: A length value, in picas. `11` = `CSS_DEG`: An angle value, in degrees. `12` = `CSS_RAD`: An angle value, in radians. `13` = `CSS_GRAD`: An angle value, in grads. `14` = `CSS_MS`: A time value, in milliseconds. `15` = `CSS_S`: A time value, in seconds. `16` = `CSS_HZ`: A frequency value, in Hertz. `17` = `CSS_KHZ`: A frequency, in kiloHertz. `18` = `CSS_DIMENSION`: A number value of an unknown dimension.
`floatValue`	float	The new float value for the property.

Parameter

Type

Description

unitType

unsigned short

The property value type. The following constants represent the numerical values used to define which units are applied to the property value:

0 = CSS_UNKNOWN: The value is not recognized.
1 = CSS_NUMBER: A simple number value.
2 = CSS_PERCENTAGE: A percentage value.
3 = CSS_EMS: A length value, based on font size.
4 = CSS_EXS: A length value, based on font x-height.
5 = CSS_PX: A length value, in pixels.
6 = CSS_CM: A length value, in centimeters.
7 = CSS_MM: A length value, in millimeters.
8 = CSS_IN: A length value, in inches.
9 = CSS_PT: A length value, in points.
10 = CSS_PC: A length value, in picas.
11 = CSS_DEG: An angle value, in degrees.
12 = CSS_RAD: An angle value, in radians.
13 = CSS_GRAD: An angle value, in grads.
14 = CSS_MS: A time value, in milliseconds.
15 = CSS_S: A time value, in seconds.
16 = CSS_HZ: A frequency value, in Hertz.
17 = CSS_KHZ: A frequency, in kiloHertz.
18 = CSS_DIMENSION: A number value of an unknown dimension.

floatValue

float

The new float value for the property.

Return values

None.

Exceptions

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

Method: CSSPrimitiveValue.setStringValue()

Availability

BlackBerry® Device Software version 4.6 or later

The setStringValue() method sets a string value with the given unit. If the property attached to this value cannot accept the given unit type or the string value, the value will not be changed, and an exception is thrown.

Syntax

setStringValue( unitType, stringValue )

Parameters

Parameter	Type	Description
`unitType`	unsigned short	The unit code for the prdoperty value. The unit code must represent one of the following string unit types: `19` = `CSS_STRING`: A simple string value. `20` = `CSS_URI`: A string value representing a URI. `21` = `CSS_IDENT`: A string value representing an identifier. `22` = `CSS_ATTR`: A string value representing an attribute function.
`stringValue`	String	The new string value for the property.

Parameter

Type

Description

unitType

unsigned short

The unit code for the prdoperty value. The unit code must represent one of the following string unit types:

19 = CSS_STRING: A simple string value.
20 = CSS_URI: A string value representing a URI.
21 = CSS_IDENT: A string value representing an identifier.
22 = CSS_ATTR: A string value representing an attribute function.

stringValue

String

The new string value for the property.

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

Global Navigation

Help Center

Local Navigation