previous   next   contents   properties   index  

Appendix D: SVG's Document Object Model (DOM)

D.1 SVG DOM Overview

The SVG DOM has the following general characteristics:

In particular, the following should be noted:

D.2 Naming Conventions

The SVG DOM follows similar naming conventions to the HTML DOM Level 1.

All names are defined as one or more English words concatenated together to form a single string. Property or method names start with the initial keyword in lowercase, and each subsequent word starts with a capital letter. For example, a property that returns document meta information such as the date the file was created might be named "fileDateCreated". In the ECMAScript binding, properties are exposed as properties of a given object. In Java, properties are exposed with get and set methods.

The return value of an attribute that has a data type that is a value list is always capitalized, independent of the case of the value in the source document. For example, if the value of the align attribute on a P element is "left" then it is returned as "Left". For attributes with the CDATA data type, the case of the return value is that given in the source document.

D.3 Objects related to SVG documents

Interface SVGDocument
An SVGDocument is the root of the SVG hierarchy and holds the entire content. Beside providing access to the hierarchy, it also provides some convenience methods for accessing certain sets of information from the document.
IDL Definition
interface SVGDocument : Document {

  // Same meanings as in HTML DOM Level 1
           attribute  DOMString            title;
  readonly attribute  DOMString            referrer;
  readonly attribute  DOMString            domain;
  readonly attribute  DOMString            URL;
  void                      open();
  void                      close();
  void                      write(in DOMString text);
  void                      writeln(in DOMString text);
  Element                   getElementById(in DOMString elementId);

  // Methods to eliminate flicker in animations.
  unsigned long suspend_redraw(in unsigned long max_wait_milliseconds);
  void          unsuspend_redraw(in unsigned long suspend_handle_id)
                                 raises(DOMException);
  void          unsuspend_redraw_all();

  // The following utility methods for matrix arithmetic will be
  // available from the DOM. (Details not yet available.)
  // matrix += Vector2D           - translation
  // matrix -= Vector2D           - translation
  // matrix *= number             - scaling
  // matrix /= number             - scaling
  // matrix *= Vector2D           - non-orthogonal scaling
  // matrix /= Vector2D           - non-orthogonal scaling
  // matrix *= Matrix2D           - matrix concatenation
  // matrix == number             - test scaling matrix identity
  // matrix == Vector2D           - test for simple scaling
  // matrix.FSimple()             - transformation is an offset/scale
  // matrix.Rotate(angle)         - rotation
  // matrix.Rotate(Vector2D)      - rotation defined by vector (atan(y/x))
  // matrix.FlipX()               - flip +x <-> -x
  // matrix.FlipY()               - flip +y <-> -y
  // matrix.SkewX()               - skew in direction of X axis
  // matrix.SkewY()               - skew in direction of Y axis
  // matrix.Inverse()             - invert the matrix
};
Attributes
title
The title of a document as specified by the title element within the defs sub-element of the svg element that encompasses the document (i.e., <svg><defs><title>Here is the title</title></defs><svg>
referrer
Returns the URI of the page that linked to this page. The value is an empty string if the user navigated to the page directly (not through a link, but, for example, via a bookmark).
domain
The domain name of the server that served the document, or a null string if the server cannot be identified by a domain name.
URL
The complete URI of the document.
Methods
open
Note. This method and the ones following allow a user to add to or replace the structure model of a document using strings of unparsed SVG. Open a document stream for writing. If a document exists in the target, this method clears it.
This method has no parameters.
This method returns nothing.
This method raises no exceptions.
close
Closes a document stream opened by open() and forces rendering.
This method has no parameters.
This method returns nothing.
This method raises no exceptions.
write
Write a string of text to a document stream opened by open(). The text is parsed into the document's structure model.
Parameters
text

The string to be parsed into some structure in the document structure model.


This method returns nothing.
This method raises no exceptions.
writeln
Write a string of text followed by a newline character to a document stream opened by open(). The text is parsed into the document's structure model.
Parameters
text

The string to be parsed into some structure in the document structure model.


This method returns nothing.
This method raises no exceptions.
getElementById
Returns the Element whose id is given by elementId. If no such element exists, returns null. Behavior is not defined if more than one element has this id.
Parameters
elementId

The unique id value for an element.

Return Value
The matching element.

This method raises no exceptions.
suspend_redraw
Takes a time-out value which indicates that redraw should not occur until: (a) the corresponding unsuspend_redraw(suspend_handle_id) call has been made, (b) an unsuspend_redraw_all() call has been made, or (c) its timer has timed out. In environments that do not support interactivity (e.g., print media), then redraw should not be suspended. suspend_handle_id = suspend_redraw(max_wait_milliseconds) and unsuspend_redraw(suspend_handle_id) should be packaged as balanced pairs. When you want to suspend redraw actions as a collection of SVG DOM changes occur, then precede the changes to the SVG DOM with a method call similar to suspend_handle_id = suspend_redraw(max_wait_milliseconds) and follow the changes with a method call similar to unsuspend_redraw(suspend_handle_id). Note that multiple suspend_redraw calls can be used at once and that each such method call is treated independently of the other suspend_redraw method calls.
Parameters
max_wait_milliseconds

The amount of time in milliseconds to hold off before redrawing the device. Values greater than 60 seconds will be truncated down to 60 seconds.

Return Value
A number which acts as a unique identifier for the given suspend_redraw() call. This value should be passed as the parameter to the corresponding unsuspend_redraw() method call.

This method raises no exceptions.
unsuspend_redraw
Cancels a specified suspend_redraw() by providing a unique suspend_handle_id.
Parameters
suspend_handle_id

A number which acts as a unique identifier for the desired suspend_redraw() call. The number supplied should be a value returned from a previous call to suspend_redraw().

Return Value
None.
This method will raise a DOMException with value NOT_FOUND_ERR if an invalid value (i.e., no such suspend_handle_id is active) for suspend_handle_id is provided.
unsuspend_redraw_all
Cancels all currently active suspend_redraw() method calls. This method is most useful at the very end of a set of SVG DOM calls to ensure that all pending suspend_redraw() method calls have been cancelled.
Parameters
None.
Return Value
None.
This method raises no exceptions.


Interface SVGElement

All SVG element interfaces derive from this class.

IDL Definition
interface SVGElement : Element {
  readonly attribute  SVGDocument ownerSVGDocument;
  CSSStyleDeclaration  style;
};


Interface SVGPathElement

Corresponds to the <path> element.

IDL Definition
interface SVGPathElement : SVGElement {
  // Create an empty SVGPathSeg, specifying the type via a number.
  // All values initialized to zero.
  SVGPathSeg  createSVGPathSeg(in unsigned short pathsegType)
	                             raises(DOMException);

  // Create an empty SVGPathSeg, specifying the type via a single character.
  // All values initialized to zero.
  SVGPathSeg  createSVGPathSegFromLetter(in DOMString pathsegTypeAsLetter)
	                                       raises(DOMException);

  // Create an SVGPathSeg, specifying the path segment as a string.
  // For example, "M 100 200". All irrelevant values are set to zero.
  SVGPathSeg  createSVGPathSegFromString(in DOMString pathsegString)
	                                       raises(DOMException);

  // This set of functions allows retrieval and modification
  // to the path segments attached to this path object.
  // All 20 defined types of path segments are available
  // through these attributes and methods.

  readonly attribute unsigned long  number_of_pathsegs;
  SVGPathSeg      getSVGPathSeg(in unsigned long index);
  DOMString       getSVGPathSegAsString(in unsigned long index);
  SVGPathSeg      insertSVGPathSegBefore(in SVGPathSeg newSVGPathSeg,
                                           in unsigned long index)
                                           raises(DOMException);
  SVGPathSeg      replaceSVGPathSeg(in SVGPathSeg newSVGPathSeg,
                                      in unsigned long index)
                                      raises(DOMException);
  SVGPathSeg      removeSVGPathSeg(in unsigned long index)
                                     raises(DOMException);
  SVGPathSeg      appendSVGPathSeg(in SVGPathSeg newSVGPathSeg)
                                     raises(DOMException);

  // This alternate set of functions also allows retrieval and modification
  // to the path segments attached to this path object.
  // These attributes and methods provide a "normalized" view of
  // the path segments where the path is expressed in terms of
  // the following subset of SVGPathSeg types:
  // kSVG_PATHSEG_MOVETO_ABS (M), kSVG_PATHSEG_LINETO_ABS (L),
  // kSVG_PATHSEG_CURVETO_CUBIC_ABS (C) and kSVG_PATHSEG_CLOSEPATH (z).
  // Note that number_of_pathsegs and number_of_normalized_pathsegs
  // may not be the same. In particular, elements such as arcs may
  // be expanded into multiple kSVG_PATHSEG_CURVETO_CUBIC_ABS (C)
  // pieces when retrieved in the "normalized" view of the path object.

  readonly attribute unsigned long  number_of_normalized_pathsegs;
  SVGPathSeg      getNormalizedSVGPathSeg(in unsigned long index);
  DOMString       getNormalizedSVGPathSegAsString(in unsigned long index);
  SVGPathSeg      insertNormalizedSVGPathSegBefore(in SVGPathSeg newSVGPathSeg,
                                in unsigned long index)
                                raises(DOMException);
  SVGPathSeg      replaceNormalizedSVGPathSeg(in SVGPathSeg newSVGPathSeg,
                                in unsigned long index)
                                raises(DOMException);
  SVGPathSeg      removeNormalizedSVGPathSeg(in unsigned long index)
                                raises(DOMException);
  SVGPathSeg      appendNormalizedSVGPathSeg(in SVGPathSeg newSVGPathSeg)
                                raises(DOMException);
};
Attributes
Details will be provided later.
Methods
Details will be provided later.
Implementation Notes

The following is recommended behavior (not required to be conforming) for SVG user agents regarding d="..." and the DOM.

  • The XML DOM already provides access to the raw strings as entered for the d="..." attributes on <path> and <data> elements. The recommended behavior is that if the path data has not been changed via the DOM, then any XML DOM calls to get the attribute values of the d="..." attributes should return (to the best degree possible) the strings as originally entered. (The simplest way to implement path data logic to make this possible is to retain all path data strings in their original form.)
  • Whenever the path data has been changed via the SVG DOM, the SVG DOM should attempt to preserve as much of the original d="..." attribute strings as possible. All path segments that were on a particular <path> or <data> elements should stay with the original element. The exception is when modifications to the path data via the SVG DOM causes particular d="..." attribute strings to exceed the 1023 character limit. The rule should be as follows: whenever a change to the DOM causes a particular d="..." attribute to have more characters that 1023, take segments off the end of the given d="..." attribute and push onto the beginning of the d="..." attribute of the subsequent <data> element (creating a new such element if necessary). If pushing new segments onto the beginning of a subsequent <data> element causes its d="..." attribute to exceed 1023 characters, then take segments off of its d="..." attribute and push onto the beginning of the d="..." attribute of its subsequent <data> element, until all d="..." attributes satisfy the 1023 character limit restriction.


Interface SVGPathSeg

Corresponds to a single segment within a path data specification.

IDL Definition
interface SVGPathSeg {
  // Path Segment Types
  const unsigned short kSVG_PATHSEG_UNKNOWN                      = 0;  // ?
  const unsigned short kSVG_PATHSEG_CLOSEPATH                    = 1;  // z
  const unsigned short kSVG_PATHSEG_MOVETO_ABS                   = 2;  // M
  const unsigned short kSVG_PATHSEG_MOVETO_REL                   = 3;  // m
  const unsigned short kSVG_PATHSEG_LINETO_ABS                   = 4;  // L
  const unsigned short kSVG_PATHSEG_LINETO_REL                   = 5;  // l
  const unsigned short kSVG_PATHSEG_CURVETO_CUBIC_ABS            = 6;  // C
  const unsigned short kSVG_PATHSEG_CURVETO_CUBIC_REL            = 7;  // c
  const unsigned short kSVG_PATHSEG_CURVETO_QUADRATIC_ABS        = 8;  // Q
  const unsigned short kSVG_PATHSEG_CURVETO_QUADRATIC_REL        = 9;  // q
  const unsigned short kSVG_PATHSEG_ARC_SWEEP_ABS                = 10; // A
  const unsigned short kSVG_PATHSEG_ARC_SWEEP_REL                = 11; // a
  const unsigned short kSVG_PATHSEG_ARC_VECTOR_ABS               = 12; // B
  const unsigned short kSVG_PATHSEG_ARC_VECTOR_REL               = 13; // b
  const unsigned short kSVG_PATHSEG_LINETO_HORIZONTAL_ABS        = 14; // H
  const unsigned short kSVG_PATHSEG_LINETO_HORIZONTAL_REL        = 15; // h
  const unsigned short kSVG_PATHSEG_LINETO_VERTICAL_ABS          = 16; // V
  const unsigned short kSVG_PATHSEG_LINETO_VERTICAL_REL          = 17; // v
  const unsigned short kSVG_PATHSEG_CURVETO_CUBIC_SMOOTH_ABS     = 18; // S
  const unsigned short kSVG_PATHSEG_CURVETO_CUBIC_SMOOTH_REL     = 19; // s
  const unsigned short kSVG_PATHSEG_CURVETO_QUADRATIC_SMOOTH_ABS = 20; // T
  const unsigned short kSVG_PATHSEG_CURVETO_QUADRATIC_SMOOTH_REL = 21; // t

  readonly attribute  unsigned short pathsegType;
  readonly attribute  DOMString      pathsegTypeAsLetter;

  // Attribute values for a path segment.
  // Each pathseg has slots for any possible path seg type.
  // (We don't want to define 20 different subclasses to PathSeg -
      our document is long enough already.)
  attribute  double       x;   // end point for pathseg (or center for A/a/B/b)
  attribute  double       y;   // end point for pathseg (or center for A/a/B/b)
  attribute  double       x0,y0;    // for control points (start point for B/b)
  attribute  double       x1,y1;    // for control points (end point for B/b)
  attribute  double       r1,r2;    // radii for A/a/B/b
  attribute  double       a1,a2,a3; // angles for A/a

  readonly attribute  Path parentPath;
  readonly attribute  SVGDocument ownerSVGDocument;
  readonly attribute  SVGPathSeg previousSibling;
  readonly attribute  SVGPathSeg nextSibling;
};