3 Basic Data Types and Interfaces
Contents
3.1 Basic data types
The common data types for SVG's properties and attributes fall into
the following categories:
-
<angle>:
An angle value is a <number>
optionally followed immediately with an angle unit identifier.
Angle unit identifiers are:
- deg: degrees
- grad: grads
- rad: radians
For properties defined in [CSS2],
an angle unit identifier must be provided.
For SVG-specific attributes and properties, the angle unit identifier
is optional.
If not provided, the angle value is assumed to be in degrees.
The corresponding SVG DOM interface definition for <angle> is SVGAngle.
-
<color>:
The basic type <color> is a CSS2-compatible specification for
a color in the sRGB color space [SRGB].
<color> applies to SVG's use of the 'color'
property and is a component of the definitions of properties 'fill',
'stroke'
and 'stop-color',
which also offer optional ICC-based color specifications.
A <color> is either a keyword or a numerical RGB specification. The list of keyword color names is: aqua, black, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, white, and yellow. These 16 colors are defined in HTML 4.0
([HTML4]). The format of an RGB value in hexadecimal notation is a '#' immediately followed by either three or six hexadecimal characters. The three-digit RGB notation (#rgb) is converted into six-digit form (#rrggbb) by replicating digits, not by adding zeros. For example, #fb0 expands to #ffbb00. This ensures that white (#ffffff) can be specified with the short notation (#fff) and removes any dependencies on the color depth of the display. The format of an RGB value in the functional notation is 'rgb(' followed by a comma-separated list of three numerical values (either three integer values or three percentage values) followed by ')'. The integer value 255 corresponds to 100%, and to F or FF in the hexadecimal notation: rgb(255,255,255) = rgb(100%,100%,100%) = #FFF.
White space characters are allowed around the numerical values. All RGB colors are specified in the sRGB color space (see [SRGB]). Using sRGB provides an unambiguous and objectively measurable definition of of the color, which can be related to international standards (see [COLORIMETRY]).
The corresponding SVG DOM interface definitions for <color> are defined in [DOM2-CSS];
in particular, see the [DOM2-CSS-RGBCOLOR].
SVG's extension to color, including the ability to specify ICC-based colors,
are represented in DOM interface
SVGColor.
-
<coordinate>:
The format of a <coordinate> is a <number>
optionally followed immediately by a CSS unit identifier.
If the <coordinate> is expressed as a simple number without a CSS unit identifier (e.g., 48), then the value represents a coordinate value in the current user coordinate system.
If one of the CSS unit identifiers is provided (e.g., 12mm), the <coordinate> represents the X-coordinate in the user coordinate system that is the given distance (measured in the viewport coordinate system) from the origin of the user coordinate system. (See Processing rules for CSS units and percentages.)
If a percentage is provided (e.g., 10%), the <coordinate> represents the X-coordinate in the user coordinate system that is the given distance (measured as a percentage of the width of the viewport coordinate system) from the origin of the user coordinate system. (See Processing rules for CSS units and percentages.)
Within the SVG DOM, a <coordinate> is represented as an SVGLength since both values have the same syntax (although the semantics are not identical).
-
<frequency>:
Frequency values are used with aural cascading style sheets (see [CSS2]).
A frequency value is a <number> immediately followed by a frequency
unit identifier.
Frequency unit identifiers are:
- Hz: Hertz
- kHz: kilo Hertz
Frequency values may not be negative.
The corresponding SVG DOM interface definitions for <frequency> are defined in [DOM2-CSS].
-
<integer>:
An <integer> is specified as an optional sign character ('+'
or '-', with '+' being the default) followed by one or more digits "0" to "9".
Unless stated otherwise for a particular attribute or property, the range for a <integer> encompasses (at a minimum) -2147483648 to -2147483647.
Within the SVG DOM, an <integer> is represented as an SVGInteger.
-
<length>:
A length is a distance measurement.
The format of a <length> is a <number>
optionally followed immediately by a CSS unit identifier.
(Note that a <number>
has different formulations depending on whether it is applied to a
CSS property or an XML attribute.)
If the <length> is expressed as a value without a CSS unit identifier (e.g., 48), then the <length> represents a distance in the current user coordinate system.
If one of the CSS unit identifiers is provided
(e.g., 12mm), then the <length>
represents a width, height or length value in the viewport coordinate system,
depending on the value which is being represented.
(See Processing rules for CSS units and percentages.)
If a percentage is provided (e.g., 10%),
then the given percentage represents a percentage of the width, height or weighted average of
the width and height of the viewport,
depending on the value which is being represented.
(See Processing rules for CSS units and percentages.)
Within the SVG DOM, a <length> is represented as an SVGLength.
-
<list of xxx>
(where xxx represents a value of some type): A list consists of a separated
sequence of values.
The specification of lists is different for CSS property values than
for XML attribute values.
- Lists in CSS property values are comma-separated, with optional
white space before or after the comma.
- Lists within SVG's XML attributes are either comma-separated, with
optional white space before
or after the comma, or white space-separated.
White space in lists is defined as one or more of the following
consecutive characters: "space" (Unicode code 32), "tab" (9), "line
feed" (10), "carriage return" (13) and "form-feed" (12).
Within the SVG DOM, a <list of xxx> is represented by various custom interfaces, such as SVGTransformList.
-
<number>
(real number value): The specification of real number values is different
for CSS property values than for XML attribute values.
- CSS2 [CSS2] states that a property
value which is a <number> is specified in decimal notation
(i.e., a <decimal-number>),
which consists of either an <integer>,
or an optional sign character followed by zero or more digits followed
by a dot (.) followed by zero or more digits with at least one digit
required either before or after the dot.
Thus, for conformance with CSS2, any property in SVG which accepts
<number> values is specified in decimal notation only.
- For SVG's XML attributes, to provide as much scalability in numeric
values as possible, real number values can be provided either in decimal notation
or in scientific notation
(i.e., a <scientific-number>),
which consists of a <decimal-number>
immediately followed by the letter "e" or "E" immediately followed
by an <integer>.
Unless stated otherwise for a particular attribute or property,
a <number> has the capacity for at least a single-precision floating
point number (see [ICC32])
and has a range (at a minimum) of -3.4e+38F to +3.4e+38F.
It is recommended that higher precision floating point storage and computation be performed on operations such as coordinate system transformations to provide the best possible precision and to prevent round-off errors.
Conforming High-Quality SVG Viewers are required to use at least double-precision floating point (see [ICC32]) intermediate calculations on certain numerical operations.
Within the SVG DOM, a <number> is represented as an SVGNumber.
-
<paint>
: The values for properties 'fill'
and 'stroke'
are specifications of the type of paint to use when filling or stroking
a given graphics element.
The available options and syntax for <paint>
is described in Specifying paint.
Within the SVG DOM, <paint> is represented as an SVGPaint.
-
<percentage>:
The format of a percentage value is a <number>
immediately followed by a '%'.
Percentage values are always relative to another value, for example
a length.
Each attribute or property that allows percentages also defines the
reference distance measurement to which the percentage refers.
Within the SVG DOM, a <percentage> is represented as an SVGLength.
-
<time>:
A time value is a <number> immediately followed by a time unit
identifier.
Time unit identifiers are:
- ms: milliseconds
- s: seconds
Time values are used in CSS properties and may not be negative.
The corresponding SVG DOM interface definitions for <time> are defined in [DOM2-CSS].
-
<transform-list>
: The detailed description of the possible values for a <transform-list>
are detailed in Modifying the User Coordinate System: the transform attribute.
Within the SVG DOM, <transform-list> is represented as an SVGTransformList.
-
<uri>
(Uniform Resource Identifiers [URI] references): A URI is the address
of a resource on the Web.
For the specification of URI references in SVG, see URI references.
Within the SVG DOM, <uri> is represented as a DOMString.
3.2 Basic DOM interfaces
The following interfaces are defined below:
SVGAngle,
SVGInteger,
SVGLength,
SVGNumber,
SVGRect,
SVGList,
SVGLengthList,
SVGUnitTypes.
Interface SVGAngle
The SVGAngle interface corresponds to the <angle> basic data type.
IDL Definition
-
interface SVGAngle {
// Angle Unit Types
constant unsigned short SVG_ANGLETYPE_UNKNOWN = 0;
constant unsigned short SVG_ANGLETYPE_UNSPECIFIED = 1;
constant unsigned short SVG_ANGLETYPE_DEG = 2;
constant unsigned short SVG_ANGLETYPE_RAD = 3;
constant unsigned short SVG_ANGLETYPE_GRAD = 4;
readonly attribute unsigned short unitType;
attribute float value;
attribute float valueInSpecifiedUnits;
attribute DOMString valueAsString;
readonly attribute float animatedValue;
void newValueSpecifiedUnits ( in unsigned short unitType, in float valueInSpecifiedUnits )
raises( SVGException );
void convertToSpecifiedUnits ( in unsigned short unitType )
raises( SVGException );
};
- Definition group Angle Unit Types
-
- Defined constants
-
SVG_ANGLETYPE_UNKNOWN |
|
The unit type is not one of predefined unit types.
It is invalid to attempt to define a new value of this type
or to attempt to switch an existing value to this type.
|
SVG_ANGLETYPE_UNSPECIFIED |
|
No unit type was provided (i.e., a unitless value was specified).
For angles, a unitless value is treated the same as if degrees were specified.
|
SVG_ANGLETYPE_DEG |
|
The unit type was explicitly set to degrees.
|
SVG_ANGLETYPE_RAD |
|
The unit type is radians.
|
SVG_ANGLETYPE_GRAD |
|
The unit type is grads.
|
- Attributes
-
- readonly unsigned short unitType
-
The type of the value as specified by one of the constants specified above.
- float value
-
The angle value as a floating point value, in degrees.
Setting this attribute will cause valueInSpecifiedUnits and valueAsString to be updated automatically to reflect this setting.
- float valueInSpecifiedUnits
-
The angle value as a floating point value, in the units expressed by unitType.
Setting this attribute will cause value and valueAsString to be updated automatically to reflect this setting.
- DOMString valueAsString
-
The angle value as a string value, in the units expressed by unitType.
Setting this attribute will cause value and valueInSpecifiedUnits to be updated automatically to reflect this setting.
- readonly float animatedValue
-
If the given attribute or property is being animated, contains the current animated
value of the attribute or property.
If the given attribute or property is not currently being animated, contains the same
value as value.
The value is in degrees.
- Methods
-
- newValueSpecifiedUnits
-
Reset the value as a number with an associated unitType, thereby replacing the values
for all of the attributes on the object.
- Parameters
-
in
unsigned short
unitType
|
|
The unitType for the angle value (e.g., SVG_ANGLETYPE_DEG).
|
in
float
valueInSpecifiedUnits
|
|
The angle value.
|
- No Return Value
- Exceptions
-
SVGException
|
|
SVG_WRONG_TYPE_ERR: Raised if an invalid unitType is specified.
|
- convertToSpecifiedUnits
-
Preserve the same value, but convert to the specified unitType.
Object attributes unitType, valueAsSpecified and valueAsString
might be modified as a result of this method,
- Parameters
-
in
unsigned short
unitType
|
|
The unitType to switch to (e.g., SVG_ANGLETYPE_DEG).
|
- No Return Value
- Exceptions
-
SVGException
|
|
SVG_WRONG_TYPE_ERR: Raised if an invalid unitType is specified.
|
Interface SVGInteger
The SVGInteger interface corresponds to the <integer> basic data type.
IDL Definition
-
interface SVGInteger {
attribute long value;
readonly attribute long animatedValue;
};
- Attributes
-
- long value
-
The value as an integer.
- readonly long animatedValue
-
If the given attribute or property is being animated, contains the current animated
value of the attribute or property.
If the given attribute or property is not currently being animated, contains the same
value as DOM property value.
Interface SVGLength
The SVGLength interface corresponds to the <length> basic data type.
IDL Definition
-
interface SVGLength {
// Length Unit Types
constant unsigned short SVG_LENGTHTYPE_UNKNOWN = 0;
constant unsigned short SVG_LENGTHTYPE_NUMBER = 1;
constant unsigned short SVG_LENGTHTYPE_PERCENTAGE = 2;
constant unsigned short SVG_LENGTHTYPE_EMS = 3;
constant unsigned short SVG_LENGTHTYPE_EXS = 4;
constant unsigned short SVG_LENGTHTYPE_PX = 5;
constant unsigned short SVG_LENGTHTYPE_CM = 6;
constant unsigned short SVG_LENGTHTYPE_MM = 7;
constant unsigned short SVG_LENGTHTYPE_IN = 8;
constant unsigned short SVG_LENGTHTYPE_PT = 9;
constant unsigned short SVG_LENGTHTYPE_PC = 10;
readonly attribute unsigned short unitType;
attribute float value;
attribute float valueInSpecifiedUnits;
attribute DOMString valueAsString;
readonly attribute float animatedValue;
void newValueSpecifiedUnits ( in unsigned short unitType, in float valueInSpecifiedUnits )
raises( SVGException );
void convertToSpecifiedUnits ( in unsigned short unitType )
raises( SVGException );
};
- Definition group Length Unit Types
-
- Defined constants
-
SVG_LENGTHTYPE_UNKNOWN |
|
The unit type is not one of predefined unit types.
It is invalid to attempt to define a new value of this type
or to attempt to switch an existing value to this type.
|
SVG_LENGTHTYPE_NUMBER |
|
No unit type was provided (i.e., a unitless value was specified),
which indicates a value in user units.
|
SVG_LENGTHTYPE_PERCENTAGE |
|
A percentage value was specified.
|
SVG_LENGTHTYPE_EMS |
|
A value was specified using the "em" units defined in CSS2.
|
SVG_LENGTHTYPE_EXS |
|
A value was specified using the "ex" units defined in CSS2.
|
SVG_LENGTHTYPE_PX |
|
A value was specified using the "px" units defined in CSS2.
|
SVG_LENGTHTYPE_CM |
|
A value was specified using the "cm" units defined in CSS2.
|
SVG_LENGTHTYPE_MM |
|
A value was specified using the "mm" units defined in CSS2.
|
SVG_LENGTHTYPE_IN |
|
A value was specified using the "in" units defined in CSS2.
|
SVG_LENGTHTYPE_PT |
|
A value was specified using the "pt" units defined in CSS2.
|
SVG_LENGTHTYPE_PC |
|
A value was specified using the "pc" units defined in CSS2.
|
- Attributes
-
- readonly unsigned short unitType
-
The type of the value as specified by one of the constants specified above.
- float value
-
The value as an floating point value, in user units.
Setting this attribute will cause valueInSpecifiedUnits and valueAsString to be updated automatically to reflect this setting.
- float valueInSpecifiedUnits
-
The value as an floating point value, in the units expressed by unitType.
Setting this attribute will cause value and valueAsString to be updated automatically to reflect this setting.
- DOMString valueAsString
-
The value as a string value, in the units expressed by unitType.
Setting this attribute will cause value and valueInSpecifiedUnits to be updated automatically to reflect this setting.
- readonly float animatedValue
-
If the given attribute or property is being animated, contains the current animated
value of the attribute or property.
If the given attribute or property is not currently being animated, contains the same
value as DOM property value.
The value is in user units.
- Methods
-
- newValueSpecifiedUnits
-
Reset the value as a number with an associated unitType, thereby replacing the values
for all of the attributes on the object.
- Parameters
-
in
unsigned short
unitType
|
|
The unitType for the value (e.g., SVG_LENGTHTYPE_MM).
|
in
float
valueInSpecifiedUnits
|
|
The new value.
|
- No Return Value
- Exceptions
-
SVGException
|
|
SVG_WRONG_TYPE_ERR: Raised if an invalid unitType is specified.
|
- convertToSpecifiedUnits
-
Preserve the same value, but convert to the specified unitType.
Object attributes unitType, valueAsSpecified and valueAsString
might be modified as a result of this method,
- Parameters
-
in
unsigned short
unitType
|
|
The unitType to switch to (e.g., SVG_LENGTHTYPE_MM).
|
- No Return Value
- Exceptions
-
SVGException
|
|
SVG_WRONG_TYPE_ERR: Raised if an invalid unitType is specified.
|
Interface SVGNumber
The SVGNumber interface corresponds to the <number> basic data type.
IDL Definition
-
interface SVGNumber {
attribute float value;
readonly attribute float animatedValue;
};
- Attributes
-
- float value
-
The value as a floating point number.
- readonly float animatedValue
-
If the given attribute or property is being animated, contains the current animated
value of the attribute or property.
If the given attribute or property is not currently being animated, contains the same
value as DOM property value.
Interface SVGRect
Rectangles are defined as consisting of a (x,y) coordinate pair
identifying a minimum X value, a minimum Y value, and a width and height,
which are usually constrained to be non-negative.
IDL Definition
-
interface SVGRect {
attribute SVGNumber x;
attribute SVGNumber y;
attribute SVGNumber width;
attribute SVGNumber height;
};
- Attributes
-
- SVGNumber x
- Corresponds to attribute x on the given element.
- SVGNumber y
- Corresponds to attribute y on the given element.
- SVGNumber width
- Corresponds to attribute width on the given element.
- SVGNumber height
- Corresponds to attribute height on the given element.
Interface SVGList
This interface defines a set of generic list handling attributes and methods.
IDL Definition
-
interface SVGList {
readonly attribute unsigned long numberOfItems;
void clear ( );
Object initialize ( in Object newItem )
raises( SVGException );
Object createItem ( );
Object getItem ( in unsigned long index )
raises( DOMException );
Object insertBefore ( in Object newItem, in unsigned long index )
raises( SVGException );
Object replace ( in Object newItem, in unsigned long index )
raises( DOMException, SVGException );
Object remove ( in unsigned long index )
raises( DOMException );
Object append ( in Object newItem )
raises( SVGException );
};
- Attributes
-
- readonly unsigned long numberOfItems
-
The number of items in the list.
- Methods
-
- clear
-
Clears all existing current items from the list, with the result being an empty list.
- No Parameters
- No Return Value
- No Exceptions
- initialize
-
Clears all existing current items from the list and re-initializes the list to hold the
single item specified by the parameter.
- Parameters
-
in
Object
newItem
|
|
The item which should become the only member of the list.
|
- Return value
-
Object
|
|
The item being inserted into the list.
|
- Exceptions
-
SVGException
|
|
SVG_WRONG_TYPE_ERR: Raised if parameter newItem is the wrong type of object for the given list.
|
- createItem
-
Creates an initialized item of the appropriate type for this list.
- No Parameters
- Return value
-
- No Exceptions
- getItem
-
Returns the specified item from the list.
- Parameters
-
in
unsigned long
index
|
|
The index of the item from the list which is to be returned. The first item is number 1.
|
- Return value
-
Object
|
|
The selected item.
|
- Exceptions
-
DOMException
|
|
INDEX_SIZE_ERR: Raised if the index number is less than 1 or greater than number_of_items.
|
- insertBefore
-
Inserts a new item into the list at the specified position.
- Parameters
-
in
Object
newItem
|
|
The item which is to be inserted into the list.
|
in
unsigned long
index
|
|
The index of the item before which the new item is to be inserted.
If the index is less than or equal to 1, then the new item is inserted
at the front of the list.
If the index is greater than number_of_items, then the new item
is appended to the end of the list.
|
- Return value
-
Object
|
|
The inserted item.
|
- Exceptions
-
SVGException
|
|
SVG_WRONG_TYPE_ERR: Raised if parameter newItem is the wrong type of object for the given list.
|
- replace
-
Replaces an existing item in the list with a new item.
- Parameters
-
in
Object
newItem
|
|
The item which is to be inserted into the list.
|
in
unsigned long
index
|
|
The index of the item which is to be replaced.
|
- Return value
-
Object
|
|
The inserted item.
|
- Exceptions
-
DOMException
|
|
INDEX_SIZE_ERR: Raised if the index number is less than 1 or greater than number_of_items.
|
SVGException
|
|
SVG_WRONG_TYPE_ERR: Raised if parameter newItem is the wrong type of object for the given list.
|
- remove
-
Removes an existing item from the list.
- Parameters
-
in
unsigned long
index
|
|
The index of the item which is to be removed.
|
- Return value
-
- Exceptions
-
DOMException
|
|
INDEX_SIZE_ERR: Raised if the index number is less than 1 or greater than number_of_items.
|
- append
-
Inserts a new item at the end of the list.
- Parameters
-
in
Object
newItem
|
|
The item which is to be inserted into the list.
|
- Return value
-
Object
|
|
The inserted item.
|
- Exceptions
-
SVGException
|
|
SVG_WRONG_TYPE_ERR: Raised if parameter newItem is the wrong type of object for the given list.
|
Interface SVGLengthList
Used for values that can be expressed as an array of SVGLengths.
The various methods inherited from SVGList,
which are defined in SVGList to accept parameters and return values of type Object,
must receive parameters of type SVGLength
and return values of type SVGLength.
IDL Definition
-
interface SVGLengthList : SVGList;
Interface SVGUnitTypes
The SVGUnitTypes interface
defines a commonly used set of constants and
is a base interface used by
SVGGradientElement,
SVGPatternElement,
SVGClipPathElement,
SVGMaskElement,
and
SVGFilterElement.
IDL Definition
-
interface SVGUnitTypes {
// Unit Types
constant unsigned short SVG_UNIT_TYPE_UNKNOWN = 0;
constant unsigned short SVG_UNIT_TYPE_USERSPACE = 1;
constant unsigned short SVG_UNIT_TYPE_USERSPACEONUSE = 2;
constant unsigned short SVG_UNIT_TYPE_OBJECTBOUNDINGBOX = 3;
};
- Definition group Unit Types
-
- Defined constants
-
SVG_UNIT_TYPE_UNKNOWN |
|
The type is not one of predefined types.
It is invalid to attempt to define a new value of this type
or to attempt to switch an existing value to this type.
|
SVG_UNIT_TYPE_USERSPACE |
|
Corresponds to value userSpace.
|
SVG_UNIT_TYPE_USERSPACEONUSE |
|
Corresponds to value userSpaceOnUse.
|
SVG_UNIT_TYPE_OBJECTBOUNDINGBOX |
|
Corresponds to value objectBoundingBox.
|