SVG 1.1 (Second Edition) – 22 June 2010

Appendix E: ECMAScript Language Binding

Contents

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:

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

IDL typeECMAScript type
booleanBoolean
floatNumber
longNumber
unsigned shortNumber
unsigned longNumber
DOMStringString

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);
SVG 1.1 (Second Edition) – 22 June 2010