previous next contents properties index

# 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

      Object |  | The created item.

    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

      Object |  | The removed item.

    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.

previous next contents properties index