Appendix E: ECMAScript Language Binding

Contents

• E.1 Exceptions
• E.2 Constants
• E.3 Types
• E.4 Objects

This appendix is normative.

This appendix describes how to expose the SVG DOM to an ECMAScript language environment [ECMA-262].

For descriptions of how interfaces and exceptions defined in other specifications are to be exposed to an ECMAScript language environment, consult the relevant specification:

• For DOM Level 2 Core interfaces and exceptions, see the DOM Level 2 Core ECMAScript Language Binding appendix ([DOM2], appendix E).
• For DOM Level 2 Events interfaces, see the DOM Level 2 Events ECMAScript Language Binding appendix ([DOM2EVENTS], appendix C).
• For DOM Level 2 Views interfaces, see the DOM Level 2 Views ECMAScript Language Binding appendix ([DOM2VIEWS], appendix C).
• For DOM Level 2 Style interfaces, see the DOM Level 2 Style ECMAScript Language Binding appendix ([DOM2STYLE], appendix C).

E.1 Exceptions

The SVG DOM defines a single exception, SVGException, which is exposed to an ECMAScript language environment as follows.

The ECMAScript global object has a property named "SVGException" whose value is an object with the following properties:

• A read only property named "SVG_WRONG_TYPE_ERR", whose value is the Number value 1.
• A read only property named "SVG_INVALID_VALUE_ERR", whose value is the Number value 2.
• A read only property named "SVG_MATRIX_NOT_INVERTABLE", whose value is the Number value 3.

A host object that is an SVGException also has these three properties on itself, or somewhere in its prototype chain. Every such host object also has a read only property named "code" whose value is a Number, corresponding to the code exception member on SVGException.

E.2 Constants

For every interface defined in the SVG DOM that has one or more constants defined on it, there exists a property on the ECMAScript global object whose name is the name of the interface, and whose value is an object with a read only property for each of the constants. The name of each of these read only properties is the name of the corresponding constant, and the value is a Number with the same value as that of the constant.

A host object that implements an interface with constants defined on it has, on itself or somewhere in its prototype chain, these properties that correspond to the constants.

E.3 Types

The following table gives the corresponding ECMAScript type for the IDL primitive types used in the SVG DOM.

When an ECMAScript Number is assigned to a property that corresponds to an attribute of an IDL integer type (long, unsigned short or unsigned long), or it is passed as an argument passed to an operation for which the argument type is an IDL integer type, then behavior is undefined if the Number value is not an integer within the range of that type.

For an interface type, a host object that implements the given interface is used.

E.4 Objects

A host object that implements a given interface has properties on itself, or in its prototype chain, that correspond to the operations and attributes defined on that interface and all its superinterfaces.

A property that corresponds to an attribute is read only if the attribute is read only, and has a name that is the same as the name of the attribute. When getting the property, a value of a type according to the Types section above is returned. When setting the property, if it is not read only, then behavior is defined only if a value of a type according to the Types section is assigned to it.

For example, if a is a host object that implements the SVGLength interface, then evaluating the statement:

a.valueAsString = "10";

has defined behavior, but evaluating the statement:

a.valueAsString = 10;

does not.

A property that corresponds to an operation has a name that is the same as the name of the operation, and has a value that is a Function object. The value returned from the Function is of a type according to the table in the Types section above. When calling the Function, behavior is only defined if the correct number of arguments is passed, and the type of each argument is the type according to the Types table. Also, behavior is only defined for invoking the Function with a this value that is equal to the object from which the Function was obtained.

For example, if L1 and L2 are two distinct host objects that implement the SVGPointList interface and p is a host object that implements the SVGPoint interface, then evaluating the following statement has defined behavior:

L1.insertItemBefore(p, 0);

Evaluating any of the following statements, however, does not:

L1.insertItemBefore(p, '0');
L1.insertItemBefore(p, -1);
L1.insertItemBefore(p, 0.5);
L1.insertItemBefore(p);
L1.insertItemBefore(p, 0, 0);
L1.insertItemBefore({ x: 10, y: 20 }, 0);
L1.insertItemBefore.call([], p, 0);
L1.insertItemBefore.call(L2, p, 0);