A The SVG Micro DOM (uDOM)

Contents

• A.1 Introduction
• A.2 Overview of the SVG uDOM
  • A.2.1 Document access
  • A.2.2 Tree navigation
  • A.2.3 Element creation
  • A.2.4 Element insertion
  • A.2.5 Element removal
  • A.2.6 Attribute and property access
  • A.2.7 Event listener registration and removal
  • A.2.8 Animation
  • A.2.9 Multimedia control
  • A.2.10 Java package naming
• A.3 Conforming to the SVG uDOM
  • A.3.1 Float values
  • A.3.2 Attribute/property normalization
  • A.3.3 Text content access
• A.4 Module: dom
  • A.4.1 DOMException
  • A.4.2 Node
  • A.4.3 Element
  • A.4.4 Document
  • A.4.5 ElementTraversal
  • A.4.6 Location
  • A.4.7 Window
• A.5 Module: views
  • A.5.1 AbstractView
  • A.5.2 DocumentView
• A.6 Module: events
  • A.6.1 EventTarget
  • A.6.2 EventListener
  • A.6.3 Event
  • A.6.4 MouseEvent
  • A.6.5 MouseWheelEvent
  • A.6.6 TextEvent
  • A.6.7 KeyboardEvent
  • A.6.8 UIEvent
  • A.6.9 ProgressEvent
• A.7 Module: smil
  • A.7.1 ElementTimeControl
  • A.7.2 TimeEvent
• A.8 Module: svg
  • A.8.1 SVGException
  • A.8.2 SVGDocument
  • A.8.3 SVGUseElement
  • A.8.4 SVGElementInstance
  • A.8.5 SVGSVGElement
  • A.8.6 SVGRGBColor
  • A.8.7 SVGRect
  • A.8.8 SVGPoint
  • A.8.9 SVGPath
  • A.8.10 SVGMatrix
  • A.8.11 SVGLocatable
  • A.8.12 SVGLocatableElement
  • A.8.13 TraitAccess
  • A.8.14 Additional accessing rules
  • A.8.15 SVGElement
  • A.8.16 SVGTimedElement
  • A.8.17 SVGAnimationElement
  • A.8.18 SVGVisualMediaElement
  • A.8.19 SVGTimer
  • A.8.20 SVGGlobal
  • A.8.21 AsyncStatusCallback
  • A.8.22 AsyncURLStatus
  • A.8.23 EventListenerInitializer2

This appendix is normative.

A.1 Introduction

During the later stages of development of the SVG Mobile 1.1 specification [SVGM11] it became obvious that there was a requirement to subset the SVG and XML DOM in order to reduce the burden on implementations. SVG Tiny 1.2 adds new features to the uDOM, allowing for as much necessary functionality as possible, still being suitable for SVG Tiny implementations.

Furthermore, it should be possible to implement the uDOM on devices that support SVG Tiny 1.1 although, in this case, the scripting would be external to the SVG document (since SVG Tiny 1.1 does not support inline scripting).

The goal of the uDOM definition is to provide an API that allows access to initial and computed attribute and property values, to reduce the number of interfaces compared to the traditional SVG DOM, to reduce run-time memory footprint using necessary features of the core XML DOM, as well as the most useful SVG features (such as transformation matrices). A subset of the uDOM (corresponding to SVG Tiny 1.1) is already successfully implemented by various implementations of JSR 226: Scalable 2D Vector Graphics API for J2ME, compatibility with which is another goal of the uDOM [JSR226].

The uDOM makes normative reference to DOM Level 2 Events [DOM2EVENTS], and informative reference to DOM Level 3 Events [DOM3EVENTS]. A minimal subset of DOM Level 3 Events was included in the uDOM to specify functionality as currently implemented on mobile devices, since DOM Level 3 Events was not yet a Recommendation at the time of publication. It is anticipated that DOM Level 3 Events may change to reflect the needs of the current Web environment, and any conflicting changes will supersede the functionality specified here for later SVG specifications.

The IDL definition for the uDOM is provided.

This appendix consists of the following parts:

• Overview of the SVG uDOM — an informative introduction to the uDOM, including a summary of supported features and descriptions by topic of the key features and constraints together with examples.

• Conforming to the SVG uDOM — a normative section that states conformance criteria for the SVG uDOM as well as descriptions of key features.

• A normative definition of all the interfaces in the SVG uDOM (DOM Core APIs, DOM Views APIs, SMIL DOM APIs, DOM Events APIs and SVG DOM APIs).

A.2 Overview of the SVG uDOM

The following sections provides an informative overview of the SVG uDOM's key features and constraints.

Note: Like other W3C DOM definitions, the SVG uDOM is programming-language independent. Although this appendix only contains ECMAScript and Java language examples, the SVG uDOM is compatible with other programming languages.

A.2.1 Document access

The SVG uDOM offers access to a Document object which is the root for accessing other features. The way the Document object becomes available depends on the usage context. In some languages, such as Java, the Document object can be obtained by implementing the EventListenerInitializer2 interface. The SVG user agent will invoke the implementation's initializeEventListeners method once the script has been loaded and is ready to bind to the document. The Document object is sometimes accessible through other means, for example through the AbstractView::document member which is available on the global object in ECMAScript.

A.2.2 Tree navigation

The SVG uDOM only allows navigation of the document node and the element nodes in the DOM tree. Two options are available for navigating the hierarchy of elements:

• Individual element nodes with an ID value are accessible directly via the getElementById method on the Document interface.
• The hierarchy of element nodes are traversable using the facilities on the ElementTraversal interface, along with the parentNode attribute on the Node interface.

The ElementTraversal interface provides firstElementChild, lastElementChild, previousElementSibling and nextElementSibling, which are particularly suitable for constrained devices [ET]. These traversal mechanisms skip over intervening nodes between element nodes, such as text nodes which might only contain white space.

A.2.3 Element creation

The SVG uDOM allows the creation of new elements using the createElementNS method of the Document interface.

String svgNS = "http://www.w3.org/2000/svg";
Element myRect = document.createElementNS(svgNS, "rect");

A.2.4 Element insertion

Elements can be inserted into the document tree by calling the appendChild or insertBefore methods on the Node that is to be the parent.

var svgNS = "http://www.w3.org/2000/svg";
// Create a new <rect> element
var myRect = document.createElementNS(svgNS, "rect");
// Set the various <rect> properties before appending
...

// Add element to the root of the document
var svgRoot = document.documentElement;
svgRoot.appendChild(myRect);

// Create a new <ellipse> element
var myEllipse = document.createElementNS(svgNS, "ellipse");

// Set the various <ellipse> properties before insertion
...

// Insert the ellipse before the rectangle
svgRoot.insertBefore(myEllipse, myRect);

A.2.5 Element removal

An element can be removed from the document tree by calling the removeChild method on its parent Node.

var myRect = ...;
var myGroup = document.getElementById("myGroup");
myGroup.appendChild(myRect);
...
myGroup.removeChild(myRect);

A.2.6 Attribute and property access

The SVG Tiny 1.2 uDOM supports two ways of accessing XML attributes and CSS properties; the standard way via getAttributeNS and setAttributeNS on the Element interface, and via a new concept called traits.

A trait is the typed value (e.g. a number, not just a string), associated with an element by an XML attribute or a CSS property. The trait facilities in the SVG uDOM allow for strongly-typed access to certain attribute and property values. For example, there is a getFloatTrait method for getting an attribute or property value directly as a float, in contrast with the getAttributeNS method which always returns a string. The trait facilities in the SVG uDOM are available on the TraitAccess interface, which is implemented by all DOM objects representing SVG elements.

float width = myRect.getFloatTrait("width");
width += 10;
myRect.setFloatTrait("width", width);

An important difference between getTraitNS (along with all other trait getter methods) and getAttributeNS is that getTraitNS returns the computed attribute value but getAttributeNS returns the specified attribute value (which might not exactly match the original specified value due to the possibility of user agent value normalization as described in Attribute/property normalization).

<g fill="red">
  <rect id="r1" x="1" y="1" width="5" height="5"/>
  <rect id="r2" fill="inherit" x="1" y="1" width="5" height="5"/>
</g>

In the above example:

• r1.getTraitNS(null, "fill") returns "red" (or an equivalent normalized form, see Attribute/property normalization).
• r2.getTraitNS(null, "fill") returns "red" (or an equivalent normalized form, see Attribute/property normalization).
• r1.getAttributeNS(null, "fill") returns "".
• r2.getAttributeNS(null, "fill") returns "inherit".

Traits may also be animated, by animating the underlying XML attribute or property. To access the animated value of a trait, the getPresentationTrait, along with the other similarly named presentation trait getter methods on the TraitAccess interface, can be used.

A.2.7 Event listener registration and removal

The SVG uDOM utilizes DOM Level 2 Events, using the EventTarget interface, to support the ability to add and remove event listeners to nodes in a document.

class MyEventListener implements EventListener {
    public void handleEvent(Event evt) {
        // Do whatever is needed here
    }
}
...

// Create a listener
EventListener listen1 = new MyEventListener();

// Listen to click events, during the bubbling phase
SVGElement myRect = (SVGElement)document.getElementById("myRect");
myRect.addEventListener("click", listen1, false);
...

// Remove the click listener
myRect.removeEventListener("click", listen1, false);

A.2.8 Animation

Animation elements can be started and stopped using the methods available on the ElementTimeControl interface.

var animateColor = document.getElementById("myAnimation");

// Start the animation 2.5 seconds from now.
animateColor.beginElementAt(2.5);

A.2.9 Multimedia control

Control of multimedia elements, such as the 'audio', 'video', and 'animation' elements is available through a combination of the ElementTimeControl and SVGTimedElement interfaces. Some common controls, and the interface methods to access them, are listed below:

• play: beginElement method of the ElementTimeControl interface
• stop: endElement method of the ElementTimeControl interface
• pause: pauseElement method of the SVGTimedElement interface
• unpause: resumeElement method of the SVGTimedElement interface
• seek: beginElementAt method of the ElementTimeControl interface (for example, a line graphic could be used to represent the timeline of a video, and a click event on a certain point on the line could serve as the offset for the new begin time of the video).

Note that SVG 1.2 Tiny does not define controlling the rate of playback (such as fast-forward or reverse) for time container elements. This functionality may be included in a future specification.

A.2.10 Java package naming

The SVG uDOM uses the same Java package names as the upcoming SVG 1.2 Full DOM (e.g. org.w3c.dom, org.w3c.dom.events, org.w3c.dom.svg). This allows Java applications which restrict themselves to the features in the SVG uDOM to also run in implementations that support the SVG 1.2 Full DOM.

A.3 Conforming to the SVG uDOM

A.3.1 Float values

The SVG uDOM uses IEEE-754 single precision floating point values to represent float values in the IDL [IEEE-754]. While such values support a number of non-finite values — a set of NaN (Not a Number) values and positive & negative infinity — these values are never used by the uDOM. Thus, unless otherwise specified in the prose for an operation or attribute, a DOMException with error code NOT_SUPPORTED_ERR must be thrown if a non-finite value is passed as an operation argument, or assigned to an attribute, whose type is float, or if a list of floating point values containing a non-finite value is passed as an operation argument, or assigned to an attribute, whose type is sequence<float>.

In addition, none of the operations or attributes in the uDOM distinguish between positive and negative zero. A negative zero must be treated as a positive zero when passed as an operation argument, or assigned to an attribute, whose type is float or sequence<float>.

Operations and attributes in the uDOM will never return a non-finite or negative zero value from an operation or attribute.

A.3.2 Attribute/property normalization

A viewer implementing the uDOM is allowed to return normalized attribute values ([DOM3], section 1.4) from getAttributeNS and the various trait getter methods (getTrait, getTraitNS, getFloatTrait, etc.) and trait presentation value getter methods (getPresentationTrait, getPresentationTraitNS, getFloatPresentationTrait, etc.). The following is a list of possible attribute normalizations:

Color normalization

"red" may be returned as "rgb(255,0,0)", "#ff0000", or another semantically identical form.

Out-of-range normalization

Values that are only of relevance within a certain range may be returned as a value clamped to that range. E.g. fill-opacity="1.3" may be returned as "1".

Numerical precision

"3.0" may be returned as "3", "3.00" or another semantically identical form.

Whitespace normalization

" 3.0 " may be returned as "3.0". Whitespace normalization also includes unquoted font names in the 'font-family' property. Font family names containing whitespace should be quoted. If quoting is omitted, any whitespace characters before and after the font name may be ignored and any sequence of whitespace characters inside the font name may be converted to a single space.

Font weight normalization

"normal" may be returned as "400", "bold" may be returned as "700".

Transform normalization

Any transform value may be returned as the corresponding matrix. E.g. "scale(2,2)" may be returned as "matrix(2,0,0,2,0,0)", and "scale(2,2) translate(10,5) rotate(45)" may be returned as "matrix(1.4142, 1.4142, -2.5857, 1.4142, 20, 10)".

Path normalization

The full set of path data comamnds as used by 'd' and 'path' may be mapped down to a smaller set of commands.

• Relative commands (c, h, l, m, q, s, t, v, and z) are converted to their absolute counterparts.
• Horizontal and Vertical lines (H, h, V, and v) are converted to general lines (L and l).
• Translate command S to command C.
• Translate command T to command C.
• A command Z is always normalized to command Z, even in the cases where an implicit lineto is added before the path is joined.

Display normalization

All possible 'display' values may be mapped to 'none', 'inline' or 'inherit' since they cover all the possible 'display' outputs for a pure SVG Tiny 1.2 viewer. For example, "block" may be returned as "inline". For viewers in multiple namespaces, e.g. a CDF viewer, the different 'display' properties are of importance and therefore an SVG Tiny 1.2 viewer intended for use in a multiple namespace environment is strongly recommended to keep the full range of 'display' values.

A.3.3 Text content access

In the SVG uDOM, there are two alternative ways to access an element's textual content. Text access via the TraitAccess interface is available on all SVGElements. This was available in the SVG Tiny 1.1 uDOM (used in the JSR 226 specification [JSR226]) and is still available in order to keep backward compability. The SVG Tiny 1.2 uDOM specification introduces the textContent attribute on the Node interface as a more generic text access mechanism.

To access or set the text string value for an element via traits you invoke getTrait() or setTrait() on that element and pass #text as the name of the trait you want to get or set. For example, MyTextElement.setTrait("#text", "Hello"); Text access via the #text mechanism must be supported on text content, 'desc', 'title' and 'metadata' elements. Text access to other elements defined within this specification (see list of elements) is not supported and an implementation should ignore any text on these elements.

The result of getting and setting text content via the #text mechanism is exactly the same as when using the textContent attribute. Therefore the user should be aware of the fact that styling by child 'tspan' elements (i.e. 'tspan' elements that are children of the element which text content is retrieved) will be lost if a text string is retrieved from an element and then set back again.

The #text trait is included for compatibility with the JSR 226 specification [JSR226]. It is recommended that where compatibility with JSR 226 implementations is not required content developers use textContent instead as it is more generally applicable and supports better compatibility with DOM Level 3 Core [DOM3].

<svg xmlns="http://www.w3.org/2000/svg"
     xmlns:xlink="http://www.w3.org/1999/xlink"
     xmlns:ev="http://www.w3.org/2001/xml-events"
     version="1.2" baseProfile="tiny" width="300" height="430">

  <script><![CDATA[
    function showImage(imageHref) {
      var image = document.getElementById('myImage');
      image.setTraitNS("http://www.w3.org/1999/xlink", "href", imageHref);
    }

    function imageLoadStart(evt) {
      var progressBar = document.getElementById('progressBar');
      var loadingAnimation = document.getElementById('loadingAnimation');
      progressBar.setFloatTrait("width", 0);
      loadingAnimation.beginElement();
    }

    function imageLoadProgress(evt) {
      if (evt.lengthComputable) {
        var progressBar = document.getElementById('progressBar');
        progressBar.setFloatTrait("width", 100 * (evt.loaded / evt.total));
        progressBar.setTrait("display", "inline");
      }
    }

    function imageLoadComplete(evt) {
      var progressBar = document.getElementById('progressBar');
      var loadingAnimation = document.getElementById('loadingAnimation');
      progressBar.setTrait("display", "none");
      loadingAnimation.endElement();
    }
  ]]></script>

  <image xml:id="myImage" xlink:href="imageA.png" width="300" height="400">
    <handler ev:event="loadstart">
      imageLoadStart(evt);
    </handler>

    <handler ev:event="progress">
      imageLoadProgress(evt);
    </handler>

    <handler ev:event="loadend">
      imageLoadComplete(evt);
    </handler>
  </image>

  <rect rx="4" x="50" y="400" width="200" height="30" cursor="pointer">
    <handler ev:event="click">
      showImage('imageB.png');
    </handler>
  </rect>
  <text x="150" y="420" font-size="15" fill="white" text-anchor="middle"
        text-decoration="underline" pointer-events="none">
    Load other image
  </text>

  <g display="none">
    <rect x="100" y="300" height="10" width="100" fill="black"/>
    <rect xml:id="progressBar" x="100" y="300" width="50" height="10" fill="lime"/>
  </g>
  <text x="150" y="330" font-size="15" text-anchor="middle" display="none">
    Loading...
    <animate xml:id="loadingAnimation" attributeName="display"
             begin="indefinite" dur="2s" repeatDur="indefinite"
             calcMode="discrete" values="inline; none"/>
  </text>
</svg>

<svg xmlns="http://www.w3.org/2000/svg"
     xmlns:xlink="http://www.w3.org/1999/xlink"
     xmlns:ev="http://www.w3.org/2001/xml-events"
     version="1.2" baseProfile="tiny" width="640" height="480" viewBox="0 0 640 480">

  <defs>
    <rect xml:id="r1" width="90" height="65"/>
  </defs>

  <use xlink:href="#r1" x="50" y="200" fill="red"/>
  <use xlink:href="#r1" x="250" y="200" fill="blue"/>
  <use xlink:href="#r1" x="450" y="200" fill="green"/>

  <rect xml:id="r2" x="250" y="50" width="90" height="65"/>

  <ev:listener observer="r1" event="ev:click" handler="#handler"/>

  <handler xml:id="handler" type="application/ecmascript">changeColor(evt);</handler>

  <script type="application/ecmascript">
    var target = document.getElementById("r2");

    function changeColor(evt) {
      var useElement = evt.currentTarget.correspondingUseElement;
      target.setRGBColorTrait("fill", useElement.getRGBColorTrait("fill"));
    }
  </script>
</svg>

 [currentScale      0       currentTranslate.x]         [cos(currentRotate) -sin(currentRotate 0]
 [     0      currentScale  currentTranslate.y]  by     [sin(currentRotate) cos(currentRotate) 0]
 [     0            0               1         ]         [         0                  0         1]
 

    [ x' ]    [  a  c  e  ]   [ x ]    [ a.x + c.y + e ]
    [ y' ] =  [  b  d  f  ]   [ y ] =  [ b.x + d.y + f ]
    [ 1  ]    [  0  0  1  ]   [ 1 ]    [        1      ]
 

<g xml:id="group1" transform="translate(10, 20)" fill="red">
    <rect xml:id="rect1" transform="scale(2)" x="10" y="10" width="50" height="50"/>
    <rect xml:id="rect2" x="10" y="10" width="100" height="100"/>
    <g xml:id="group2" transform="translate(10, 20)">
        <rect xml:id="rect3" x="0" y="10" width="150" height="50"/>
        <circle xml:id="circle1" cx="20" cy="20" r="100" />
    </g>
</g>
    

<g xml:id="group1" transform="translate(10, 20)" fill="red">
    <rect xml:id="rect2" x="10" y="10" width="400" height="0"/>
    <g xml:id="group2" transform="translate(10, 20)">
        <rect xml:id="rect3" x="0" y="10" width="150" height="50"/>
    </g>
</g>
    

<svg xml:id="mySVG" version="1.2" baseProfile="tiny" width="10" height="20">
    <g xml:id="group1" transform="translate(10, 20)" fill="red">
        <rect xml:id="rect1" x="10" y="10" width="100" height="100"/>
        <ellipse xml:id="ellipse1" cx="20" cy="20" rx="0" ry="70" />
    </g>
</svg>
    

<svg xml:id="mySVG" version="1.2" baseProfile="tiny" width="0" height="50">
    <g xml:id="group1" transform="translate(10, 20)" fill="red" >
        <rect xml:id="rect1" x="10" y="10" width="50" height="50"/>
        <g xml:id="group2" transform="translate(10, 20)">
            <rect xml:id="rect2" x="0" y="10" width="150" height="0"/>
            <circle xml:id="circle1" cx="20" cy="20" r="500"/>
        </g>
    </g>
</svg>
    

<svg version="1.2" baseProfile="tiny">
    <defs>
        <rect xml:id="myRect" x="0" y="0" width="60" height="40"/>
    </defs>
    <use xml:id="myUse" xlink:href="#myRect" x="-30" y="-20"/>
</svg>
    

<g xml:id="emptyG"/>
    

<g xml:id="g1">
    <g xml:id="g1.1.display.none" display="none">
        <rect xml:id="rect1" x="10" y="10" width="40" height="40"/>
    </g>
    <rect xml:id="rect2.visibility.hidden" visibility="hidden" x="30" y="60" width="10" height="20"/>
</g>
    

<g xml:id="g1">
    <line xml:id="line1" x2="100" y2="100" transform="rotate(-45)"/>
</g>
    

<g>
    <line xml:id="thickLine" stroke-width="10" x2="100" y2="0"/>
</g>
    

<svg xml:id="rootSvg" version="1.2" baseProfile="tiny" width="500" height="300" viewBox="0 0 200 100">
    <rect x="-100" y="-200" width="500" height="100"/>
</svg>
    

        <g xml:id="g1">
          <linearGradient xml:id="MyGradient"/>
            <stop offset="0.05" stop-color="#F60"/>
            <stop offset="0.95" stop-color="#FF6"/>
          </linearGradient>
        </g>
      

<svg version="1.2" baseProfile="tiny" xmlns="http://www.w3.org/2000/svg" xml:id="svg-root"
      width="100%" height="100%" viewBox="0 0 480 360">
    <rect xml:id="myRect" fill="green" x="10" y="10" width="200" height="100" stroke="black" stroke-width="2"/>
</svg>

SVGElement newAnimate = (SVGElement)document.createElementNS(svgNS, "animate");
newAnimate.setTrait("attributeName", "fill");
newAnimate.setTrait("from", "red");
newAnimate.setTrait("to", "blue");
newAnimate.setTrait("dur", "5");
newAnimate.setTrait("repeatCount", "10");
Element myRect = document.getElementById("myRect");
myRect.appendChild(newAnimate);