Global ECMAScript Constructors

From SVG
Jump to: navigation, search

This is a proposal to require ECMAScript constructor objects for SVG types (from Cameron McCormack, via CVS.

Introduction

It is currently cumbersome to create SVG type objects in script, since the objects must be created using factory methods on an SVGSVGElement instance, and these factory methods do not take arguments to initialise the newly created object. For example, if you wanted to create a new SVGMatrix object to pass to the matrixTransform() method of an SVGPoint p, then you need to use eight statements:

 var m = document.documentElement.createSVGMatrix();
 m.a = a;
 m.b = b;
 m.c = c;
 m.d = d;
 m.e = e;
 m.f = f;
 p.matrixTransform(m);

With an appropriate constructor, this can be reduced to one statement:

 p.matrixTransform(new SVGMatrix(a, b, c, d, e, f));

This proposal suggests having constructors for each of the SVG data type interfaces. These constructors can be specified using Web IDL.

I haven't specified constructors for the various SVGPathSeg interfaces. I'm not sure how useful they would be, since the factory methods on SVGPathElement all take parameters.

Note that currently Web IDL disallows overloading between a DOMString and a float. I'm considering relaxing that requirement, though.


SVGNumber

 [Constructor,
  Constructor(in float value)]
 interface SVGNumber {
   /* ...existing SVGNumber members... */
 };

SVGNumber()

 Returns a newly created SVGNumber object whose value attribute is set
 to 0, just as if SVGSVGElement.createSVGNumber() were called.

SVGNumber(in float value)

 Returns a newly created SVGNumber object whose value attribute is set
 to value.


SVGLength

 [Constructor,
  Constructor(in float value),
  Constructor(in short unitType, in float value),
  Constructor(in DOMString value)]
 interface SVGLength {
   /* ...existing SVGLength members here... */
 };

SVGLength()

 Returns a newly created SVGLength object not associated with any
 element, whose value attribute is set to 0, and whose unitType
 attribute is set to SVGLength.SVG_LENGTHTYPE_NUMBER.

SVGLength(in float value)

 Returns a newly created SVGLength object not associated with any
 element, whose value attribute is set to value, and whose unitType
 attribute is set to SVGLength.SVG_LENGTHTYPE_NUMBER.

SVGLength(in short unitType, in float value)

 Returns a newly created SVGLength object not associated with any
 element, whose value attribute is set to value, and whose unitType
 attribute is set to unitType.
 The effect of invoking this constructor is the same as running the
 following steps:
   1. Create a new SVGLength object L by inovking the zero-argument
      SVGLength constructor.
   2. Call the newValueSpecifiedUnits() method on L, passing unitType
      and value as its two arguments.
   3. Return L.

SVGLength(in DOMString valueAsString)

 Returns a newly created SVGLength object not associated with any
 element, whose valueAsString attribute is set to valueAsString.
 The effect of invoking this constructor is the same as running the
 following steps:
   1. Create a new SVGLength object L by inovking the zero-argument
      SVGLength constructor.
   2. Assign valueAsString to the valueAsString attribute on L.
   3. Return L.
 Note that the second step above may result in an exception being
 thrown.


SVGAngle

 [Constructor,
  Constructor(in float value),
  Constructor(in short unitType, in float value),
  Constructor(in DOMString value)]
 interface SVGAngle {
   /* ...existing SVGAngle members here... */
 };

SVGAngle()

 Returns a newly created SVGAngle object whose value attribute is set
 to 0, and whose unitType attribute is set to
 SVGAngle.SVG_ANGLETYPE_UNSPECIFIED.

SVGAngle(in float value)

 Returns a newly created SVGAngle object whose value attribute is set
 to value, and whose unitType attribute is set to
 SVGAngle.SVG_ANGLETYPE_UNSPECIFIED.

SVGAngle(in short unitType, in float value)

 Returns a newly created SVGAngle object whose value attribute is
 set to value, and whose unitType attribute is set to unitType.
 The effect of invoking this constructor is the same as running the
 following steps:
   1. Create a new SVGAngle object A by inovking the zero-argument
      SVGAngle constructor.
   2. Call the newValueSpecifiedUnits() method on A, passing unitType
      and value as its two arguments.
   3. Return A.

SVGAngle(in DOMString valueAsString)

 Returns a newly created SVGAngle object whose valueAsString attribute
 is set to valueAsString.
 The effect of invoking this constructor is the same as running the
 following steps:
   1. Create a new SVGAngle object A by invoking the zero-argument
      SVGAngle constructor.
   2. Assign valueAsString to the valueAsString attribute on A.
   3. Return A.
 Note that the second step above may result in an exception being
 thrown.


SVGPoint

 [Constructor,
  Constructor(in float x, in float y),
  Constructor(in DOMString valueAsString)]
 interface SVGPoint {
   /* ...existing members of SVGPoint... */
 };

SVGPoint()

 Returns a newly created SVGPoint object whose x and y attributes are
 both set to 0.

SVGPoint(in float x, in float y)

 Returns a newly created SVGPoint object whose x and y attributes are
 set to x and y, respectively.

SVGPoint(in DOMString coordinates)

 Returns a newly created SVGPoint object whose x and y attributes are
 set to values determined by parsing coordinates as a
 <coordinate-pair>.  The first coordinate parsed from coordinates is
 used as the x attribute value, and the second coordinate parsed from
 coordinates is used as the y attribute value.
 If coordinates could not be parsed as a <coordinate-pair>, then a
 DOMException with code SYNTAX_ERR is thrown.


SVGMatrix

 [Constructor,
  Constructor(in float a, in float b, in float c,
              in float d, in float e, in float f),
  Constructor(in DOMString components)]
 interface SVGMatrix {
   /* ...existing members of SVGMatrix... */
 };

SVGMatrix()

 Returns a newly created SVGMatrix object whose a, b, c, d, e and f
 attributes are all set to 0.

SVGMatrix(in float a, in float b, in float c, in float d, in float e, in float f)

 Returns a newly created SVGMatrix object whose a, b, c, d, e and f
 attributes are set to the values of the respective argument passed to
 the constructor.

SVGMatrix(in DOMString components)

 Returns a newly created SVGMatrix object whose a, b, c, d, e and f
 attributes are set to values determined by parsing components as
 a <matrix-components>.  
 The first number parsed from components is used as the a attribute
 value, the second as the b attribute value, and so on.
 If coordinates could not be parsed as a <matrix-components>, then a
 DOMException with code SYNTAX_ERR is thrown.


SVGRect

 [Constructor,
  Constructor(in float x, in float y, in float width, in float height),
  Constructor(in DOMString value)]
 interface SVGRect {
   /* ...existing members of SVGRect... */
 };

SVGRect()

 Returns a newly created SVGRect object whose x, y, width and height
 attributes are all set to 0.

SVGRect(in float x, in float y, in float width, in float height)

 Returns a newly created SVGRect object whose x, y, width and height
 attributes are set to x, y, width and height, respectively.

SVGRect(in DOMString value)

 Returns a newly created SVGPoint object whose x and y attributes are
 set to values determined by parsing value as a <rect-components>.
   The first number parsed from value
 is is used as the x attribute value, the second number is used as the
 y attribute value, and so on.
 If value could not be parsed as a <rect-components>, then a
 DOMException with code SYNTAX_ERR is thrown.


SVGTransform

 [Constructor,
  Constructor(in SVGMatrix matrix),
  Constructor(in DOMString value)]
 interface SVGTransform {
   /* ...existing members of SVGTransform... */
 };

SVGTransform()

 Returns a newly created SVGTransform object whose type attribute is
 set to SVGTransform.SVG_TRANSFORM_MATRIX and whose matrix attribute
 is set to an SVGMatrix object that represents the identity matrix.

SVGTransform(in SVGMatrix matrix)

 Returns a newly created SVGTransform object whose type attribute is
 set to SVGTransform.SVG_TRANSFORM_MATRIX and whose matrix attribute
 is set to an SVGMatrix object whose attributes are all initialized
 to be the same as the corresponding attributes in matrix.

SVGTransform(in DOMString value)

 Returns a newly created SVGTransform object whose type and matrix
 attributes are set to values determined by parsing value as a
 <transform>.
 If value could not be parsed as a <transform>, then a DOMException
 with code SYNTAX_ERR is thrown.
 The effect of invoking this constructor is the same as running the
 following steps:
   1. If value does not match the <transform> production, throw a
      DOMException with code SYNTAX_ERR.
   2. Create a new SVGGElement object, G.
   3. Set the 'transform' attribute to value.
   4. Let T be the SVGTransform object obtained by calling
      G.transform.baseVal.getItem(0).
   4. Return a new SVGTransform object whose attributes are set to
      the corresponding attributes in T.