Appendix A: SVG Tiny 1.2 DOM

A.2.2 Tree Navigation

SVG Tiny 1.2 DOM only allows navigation of the element nodes in the DOM tree. Two options are available for navigating the hierarchy of elements:

• Individual element nodes with an ID value can be accessed directly via the getElementById method on the Document interface.
• The hierarchy of element nodes can be traversed 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. These traversal mechanisms skip over intervening nodes between element nodes, such as text nodes which might only contain spaces, tabs and newlines.

A.2.3 Element Creation

Element myRect = document.createElementNS(svgNS, "rect");

A.2.4 Element Addition

String svgNS = "http://www.w3.org/2000/svg";
// Create a new <rect> element
Element myRect 
    = document.createElementNS(svgNS, "rect");

// Set the various <rect> properties before appending
...

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

// Create a new <ellipse> element
Element 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

Element myRect = ...; // See Element creation
Element myGroup = document.getElementById("myGroup");
myGroup.appendChild(myRect);
....
myGroup.removeChild(myRect);

A.2.6 Attribute and Property Access

SVG 1.2 adds a new ability to access XML attribute and CSS property values through the SVG DOM through the concept of traits. A trait is a potentially animatable parameter associated with an element. Trait is the typed value (e.g., a number, not just a string) that gets assigned through an XML attribute, CSS property or a SMIL animation [SMILANIM]. Traits can be thought of as a unification and generalization of some of the notions of XML attributes and CSS properties.

The trait facilities in the SVG DOM 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. This contrasts the DOM Core getAttributeNS(...) method which always returns a string.

The SVG Tiny 1.2 DOM includes a subset of the trait facilities in the full SVG 1.2 DOM. The trait facilities in the SVG Tiny 1.2 DOM are available on the TraitAccess interface.

Here is an example which uses the trait facilities to get and set the width of a rectangle:

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

A.2.7 Text Node Access

In the SVG 1.2 Tiny DOM, text node access is available via trait getters and setters. To access or set the text string value for a text element (e.g., a <text> element), you invoke getTrait() or setTrait() on that text element and pass #text as the name of the trait you want to get or set. For example, MyTextElement.setTrait("#text", "Hello");

A.2.8 Event Listener Registration and Removal

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

SVGElement myRect = (SVGElement)document.getElementById("myRect");

// Listen to click events, during the bubbling phase
myRect.addEventListener("click", l, false);
....

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

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

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

A.2.10 Package naming

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

A.3 Interfaces from DOM Core

DOMException

The DOMException class defines a subset of the error codes defined in the DOM Core Level 3 specification.

IDL Definition

exception DOMException
{
        unsigned short   code;
};

// ExceptionCode
const unsigned short INDEX_SIZE_ERR = 1;
const unsigned short HIERARCHY_REQUEST_ERR = 3;
const unsigned short WRONG_DOCUMENT_ERR = 4;
const unsigned short NO_MODIFICATION_ALLOWED_ERR = 7; 
const unsigned short NOT_FOUND_ERR = 8; 
const unsigned short NOT_SUPPORTED_ERR = 9;
const unsigned short INVALID_MODIFICATION_ERR = 13; 
const unsigned short INVALID_ACCESS_ERR = 15;
const unsigned short TYPE_MISMATCH_ERR = 17;
    

Defined constants

INDEX_SIZE_ERR		If index or size is negative, or greater than the allowed value.
HIERARCHY_REQUEST_ERR		If any Node is inserted somewhere it doesn't belong.
WRONG_DOCUMENT_ERR		If a node is used in a different document than the one that created it (that doesn't support it)
NO_MODIFICATION_ALLOWED_ERR		If an attempt is made to modify an object where modifications are not allowed.
NOT_FOUND_ERR		If an attempt is made to reference a node in a context where it does not exist .
NOT_SUPPORTED_ERR		If the implementation does not support the requested type of object or operation.
INVALID_MODIFICATION_ERR		If an attempt is made to modify the type of the underlying object.
INVALID_ACCESS_ERR		If a parameter or an operation is not supported by the underlying object.
TYPE_MISMATCH_ERR		If the type of an object is incompatible with the expected type of the parameter associated to the object.

Node

The Node interface is the interface for all XML tree model content. This interface is a subset of the Node interface defined in the DOM Core Level 3 specification.

IDL Definition

interface Node
{
        readonly attribute Node parentNode;
        readonly attribute DOMString namespaceURI;
        readonly attribute DOMString localName;

        Node insertBefore(in Node newChild, in Node refChild) raises(DOMException);
        Node removeChild(in Node oldChild) raises(DOMException);
        Node appendChild(in Node newChild) raises(DOMException);
};

No defined constants

Attributes (not yet completed)

Methods

appendChild

Adds newChild to the end of the children list for this node.

Parameters

in Node newChild

The new Node to add.

Return Value

Node

the newly added node

Exceptions

DOMException

If the operation is not allowed (e.g., if the newChild node type is incompatible with this node) or if addition of the given Node type is not supported by the implementation.

insertBefore

Inserts newChild before refChild.

Parameters

in Node newChild		The Node to insert.
in Node refChild		The Node before which newChild is inserted

Return Value

Node

the newly inserted node

Exceptions

DOMException

If the operation is not allowed or not supported.

removeChild

Removes a child node.

Parameters

in Node oldChild

The Node to remove.

Return Value

Node

the removed node

Exceptions

DOMException

See the DOM Level 3 specification.

Element

The Element interface represents an XML element in a Document. This interface is a subset of the Element interface defined in the DOM Core Level 3 specification.

IDL Definition

interface Element : Node
{
};

No Defined constants

No methods

Document

The Document interface is the interface for an XML Document model. This interface is a subset of the Document interface defined in the DOM Core Level 3 specification. Note that the getFirstChild method returns the root of the document.

IDL Definition

interface Document : Node
{
        readonly attribute Element documentElement;
        Element createElementNS(in DOMString namespaceURI, in DOMString qualifiedName) raises(DOMException);
        Element getElementById(in DOMString elementId);
};

No Defined constants

Defined attributes

(Incomplete)

Methods

createElementNS

Create a new element.

Parameters

in DOMString namespaceURI		The namespace uri for the newly created element.
in DOMString qualifiedName		The qualified name for the newly created element.

Return Value

Element

The newly created element

Exceptions

DOMException

See DOM Level 3 specification. In addition, a DOMException (NOT_SUPPORTED_ERR) is thrown if the type of element is not supported by the implementation.

getElementById

Get an element with a given id.

Parameters

in DOMString elementId

The unique id of the retrieved element.

Return Value

Element

The matching element or null if none.

No Exceptions

A.4 Interfaces from DOM Events

EventTarget

The interface for DOM nodes which can receive and dispatch Events to EventListeners. This interface is a subset of the EventTarget interface defined in the DOM Level 3 Events specification. Please refer to that specification for details on what the different methods and members mean.

The SVG Tiny DOM only supports the event bubbling phase. If useCapture is true, a DOMException of type NOT_SUPPORTED_ERR is raised.

IDL Definition

interface EventTarget
{
        void addEventListener(in DOMString type, in EventListener listener, in boolean useCapture);
        void removeEventListener(in DOMString type, in EventListener listener, in boolean useCapture);
};

No Defined constants

Methods

addEventListener

Adds a new listener to this target, for the specified event type, during the desired phase.

Parameters

in DOMString type		The type of event to listen to.
in EventListener listener		Will be notified when an event of the desired type happens on this target or one of its descendant.
in boolean useCapture		If true, the listener will be called during the event flow capture phase. Otherwise, the listener will be called during the bubble phase. If the event's target is this target, then the listener will be called during the 'at target' phase of event flow.

No Return Value

No Exceptions

removeEventListener

Removes a listener previously added with an addEventListener call.

Parameters

in DOMString type		The type of event that was listened to.
in EventListener listener		The listener that was previously registered.
in boolean useCapture		If true, the listener was listening to events in the capture phase of event flow.

No Return Value

No Exceptions

EventListener

Interface used to receive Events from an EventTarget This interface is a subset of the EventListener interface defined in the DOM Level 3 Events specification. Please refer to that specification for details on what the different methods and members mean.

IDL Definition

iinterface EventListener
{
        void handleEvent(in Event evt);
};

No Defined constants

Methods

handleEvent

Handle event.

Parameters

in Event evt

Contains contextual information about the event.

No Return Value

No Exceptions

Event

Provides information about an event and its propagation. This interface is a subset of the Event interface defined in the DOM Level 3 Events specification and defines additional constraints.

IDL Definition

interface Event
{
        readonly attribute DOMString type;
        readonly attribute EventTarget currentTarget;
};

No defined constants

Defined attributes

(Incomplete)

MouseEvent

The MouseEvent interface provides specific contextual information associated with Mouse events.

IDL Definition

interface MouseEvent : Event
{
        readonly attribute long screenX;
        readonly attribute long screenY;
        readonly attribute long clientX;
        readonly attribute long clientY;
        readonly attribute unsigned short button;
};

No defined constants

Defined attributes

(Incomplete)

Supported events

The following events are supported:

• mousemove
• mouseover
• mouseout
• mousedown
• mouseup
• click
• DOMActivate
• DOMFocusIn
• DOMFocusOut
• SVGLoad
• SVGScroll
• SVGResize
• SVGZoom
• beginEvent
• endEvent
• repeat
• (Text events will be added in the next draft)

A.6 Interfaces from SMIL DOM

ElementTimeControl

IDL Definition

interface ElementTimeControl
{
        boolean beginElementAt( in float offset );
        boolean endElementAt( in float offset );
};

A.6 Interfaces for SVG DOM

SVGException

IDL Definition

exception SVGException
{
        unsigned short   code;
};

// SVGExceptionCode
const unsigned short SVG_INVALID_VALUE_ERR        = 1;
const unsigned short SVG_MATRIX_NOT_INVERTABLE    = 2;

Interface SVGRect

IDL Definition

interface SVGRect
{ 
        attribute float x;
        attribute float y;
        attribute float width;
        attribute float height;
};

SVGPoint

IDL Definition

interface SVGPoint
{ 
        attribute float x;
        attribute float y;
};

SVGMatrix

IDL Definition

interface SVGMatrix
{ 
        float getComponent(in unsigned long index) raises(dom::DOMException);

        SVGMatrix multiply( in SVGMatrix secondMatrix );
        SVGMatrix inverse() raises( SVGException );
        SVGMatrix translate( in float x, in float y );
        SVGMatrix scale( in float scaleFactor );
        SVGMatrix rotate( in float angle );
};

SVGPath

SVGPath provides an API to access and manipulate the 'd' attribute on the <path> element

IDL Definition

interface SVGPath
{
        const unsigned short MOVE_TO = 0x4d; // 'M'
        const unsigned short LINE_TO = 0x4C; // 'L'
        const unsigned short CURVE_TO = 0x43;// 'C'
        const unsigned short QUAD_TO = 0x51; // 'Q'
        const unsigned short CLOSE = 0x5a;   // 'Z'

        readonly attribute unsigned long numberOfSegments;

        unsigned short getSegment( in unsigned long index ) raises(dom::DOMException);
        float getSegmentParam( in unsigned long cmdIndex, in unsigned long paramIndex ) raises(dom::DOMException);

        void moveTo( float x, float y );
        void lineTo( float x, float y );
        void quadTo( float x1, float y1, float x2, float y2 );
        void curveTo( float x1, float y1, float x2, float y2, float x3, float y3 );
        void close();
};

SVGRGBColor

IDL Definition

interface SVGRGBColor
{
        readonly attribute unsigned long red;
        readonly attribute unsigned long green;
        readonly attribute unsigned long blue;
};

SVGLocatable

IDL Definition

interface SVGLocatable
{ 
        SVGRect   getBBox();
        SVGMatrix getScreenCTM();
        SVGRect   getScreenBBox();
};

TraitAccess

TraitAccess is an interface to access trait values (see Attribute Access). A trait is a potentially animatable parameter associated with an element. Trait is the typed value (e.g., a number, not just a string) that gets assigned through an XML attribute, CSS property or a SMIL animation [SMILANIM]. Traits can be thought of as a unification and generalization of some of the notions of XML attributes and CSS properties. The trait facilities 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. This contrasts the DOM Core getAttributeNS(...) method which always returns a string.

Each trait corresponds to an attribute or property which is parsed and understood by the element and in most cases animatable. For any given profile there is a well-defined set of traits that all implementations must support. Each increasing profile may support a larger set of traits. If an implementation does not support a trait it must throw an exception. Unlike attributes traits are typed and their values are normalized; for instance SVG path specification is parsed and all path commands are converted to their absolute variants, it is not possible to say through the value of the trait if a path command was absolute or relative. When getting and setting trait values, accessor of the correct type must be used or exception will be thrown.

For XML attributes, the setter methods (e.g., setTrait(...), setFloatTrait(...)) add a new attribute for the given element. If an attribute with that name is already present on the element, its value is changed to be that of the value parameter. For CSS properties, the setter methods set the specified value for the given property, with equivalent specificity rules to using setAttributeNS(...) on a presentation attribute (see presentation attributes). The value which is modified is always a base value (in terms of SMIL animation). For inheritable traits the trait value can always be set to "inherit" (but quering the value will always return the actual inherited value as explained above).

The XML attributes, the getter methods (e.g., getTrait(...), getFloatTrait(...)) return the attribute value for the named attribute. If the given attribute has a value, then return that value; else if the attribute does not have a value, and if the attribute is a CSS property then return the computed value; else if the attribute is inheritable and an inheritable value is available, then return the inherited value; else if there is a default value, then return the default value; otherwise, an INVALID_ACCESS_ERR DOMException is raised. In either case (i.e., XML attributes or CSS properties), the returned value corresponds to the base value before animation is applied and not the presentation value (aka, animated value), where base value and presentation value corresponds to the SMIL Animation definitions of these terms (see [SMILANIM]). For the attribute "xlink:href" then the returned value follows the processing rules of xml:base.

For both the getter and setter methods, if the trait name does not correspond to a defined attribute or property, an exception is raised.

IDL Definition

interface TraitAccess
{ 
        DOMString getTrait( in DOMString name ) raises (DOMException);
        DOMString getTraitNS( in DOMString namespaceURI, in DOMString name ) raises (DOMException);
        float getFloatTrait( in DOMString name ) raises (DOMException);
        SVGMatrix getMatrixTrait( in DOMString name ) raises (DOMException);
        SVGRect getRectTrait( in DOMString name ) raises (DOMException);
        SVGPath getPathTrait( in DOMString name ) raises (DOMException);
        SVGRGBColor getRGBColorTrait( in DOMString name ) raises (DOMException);

        void setTrait( in DOMString name, in DOMString value ) raises (DOMException);
        void setTraitNS( in DOMString namespaceURI, in DOMString name, in DOMString value ) raises (DOMException);
        void setFloatTrait( in DOMString name, in float value ) raises (DOMException);
        void setMatrixTrait( in DOMString name, in SVGMatrix matrix ) raises (DOMException);
        void setRectTrait( in DOMString name, in SVGRect rect ) raises (DOMException);
        void setPathTrait( in DOMString name, in SVGPath path ) raises (DOMException);
        void setRGBColorTrait( in DOMString name, in SVGRGBColor color ) raises (DOMException);
};

Attributes

Methods

ElementTraversal

This interface provides a way to traverse elements in the DOM tree. It is needed mainly because SVG Tiny DOM does not expose character data Nodes. Each element in SVG Tiny document tree implements this interface. This applies to elements in the foreign namespaces as well.

IDL Definition

interface ElementTraversal
{
        readonly attribute Element firstElementChild;
        readonly attribute Element lastElementChild;
        readonly attribute Element nextElementSibling;
        readonly attribute Element previousElementSibling;
};

Attributes

readonly Element firstElementChild

First child element node of this element.

readonly Element lastElementChild

Last child element node of this element.

readonly Element nextElementSibling

Next sibling element node of this element.

readonly Element previousElementSibling

Previous sibling element node of this element.

SVGElement

SVGElement is the base interface used by all elements in the SVG namespace.

An element's id can be set only if it does not already have an id. DOMException with error code NO_MODIFICATION_ALLOWED_ERR is raised if an attempt is made to change an existing id. Elements with non-null id can be inserted, but cannot be removed from the DOM tree (see removeChild).

IDL Definition

interface SVGElement : dom::Element, ElementTraversal, events::EventTarget, TraitAccess
{ 
        attribute DOMString id; // raises (DOMException) on setting
};

SVGLocatableElement

SVGLocatableElement is the base interface used by all graphics and container elements in the SVG namespace.

IDL Definition

interface SVGLocatableElement : SVGElement, SVGLocatable
{ 
};

SVGAnimationElement

SVGAnimationElement is the base interface used by all animation elements in the SVG namespace.

IDL Definition

interface SVGAnimationElement : SVGElement, smil::ElementTimeControl
{ 
};

SVGSVGElement

SVGSVGElement provides an API to access APIs corresponding to the <svg> element

The DOM attributes currentScale, currentRotate and currentTranslate are equivalent to the 2x3 matrix [a b c d e f] = [currentScale 0 0 currentScale currentTranslate.x currentTranslate.y].[cos(currentRotate) sin(currentRotate) -sin(currentRotate cos(currentRotate) 0 0]. If "magnification" is enabled (i.e., zoomAndPan="magnify"), then the effect is as if an extra transformation were placed at the outermost level on the SVG document fragment (i.e., outside the outermost 'svg' element).

IDL Definition

interface SVGSVGElement : SVGLocatableElement
{ 
        attribute float currentScale; // raises (DOMException) on setting
        attribute float currentRotate; // raises (DOMException) on setting
        readonly attribute SVGPoint currentTranslate;

        readonly attribute SVGRect viewport; 

        void            pauseAnimations();
        void            unpauseAnimations();
        boolean         animationsPaused();
        float           getCurrentTime();
        void            setCurrentTime( in float seconds );

        SVGMatrix       createSVGMatrixComponents( float a, float b, float c, float d, float e, float f );
        SVGRect         createSVGRect();

        SVGPath     createSVGPath();
        SVGRGBColor     createSVGRGBColor( in unsigned long red, in unsigned long green, in unsigned long blue )
                                        raises(SVGException);
};

No Defined constants

Attributes

readonly SVGRect viewport

The position and size of the viewport (implicit or explicit) that corresponds to this 'svg' element. When the user agent is actually rendering the content, then the position and size values represent the actual values when rendering. The position and size values are unitless values in the coordinate system of the parent element. If no parent element exists (i.e., 'svg' element represents the root of the document tree), if this SVG document is embedded as part of another document (e.g., via the HTML 'object' element), then the position and size are unitless values in the coordinate system of the parent document. (If the parent uses CSS or XSL layout, then unitless values represent pixel units for the current CSS or XSL viewport, as described in the CSS2 specification.) If the parent element does not have a coordinate system, then the user agent should provide reasonable default values for this attribute.

The object itself and its contents are both readonly.

float currentScale

This attribute indicates the current scale factor relative to the initial view to take into account user magnification and panning operations, as described under Magnification and panning.

Exceptions on setting

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised on an attempt to change the value of a readonly attribute.

float currentRotate

This attribute indicates the current rotation in the user transform, relative to the coordinate system's origin. The value is in degrees.

Exceptions on setting

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised on an attempt to change the value of a readonly attribute.

readonly SVGPoint currentTranslate

The corresponding translation factor that takes into account user magnification and panning.

Methods

pauseAnimations

Suspends (i.e., pauses) all currently running animations that are defined within the SVG document fragment corresponding to this 'svg' element, causing the animation clock corresponding to this document fragment to stand still until it is unpaused.

No Parameters

No Return Value

No Exceptions

unpauseAnimations

Unsuspends (i.e., unpauses) currently running animations that are defined within the SVG document fragment, causing the animation clock to continue from the time at which it was suspended.

No Parameters

No Return Value

No Exceptions

animationsPaused

Returns true if this SVG document fragment is in a paused state.

No Parameters

Return value

boolean

Boolean indicating whether this SVG document fragment is in a paused state.

No Exceptions

getCurrentTime

Returns the current time in seconds relative to the start time for the current SVG document fragment.

No Parameters

Return value

float

The current time in seconds.

No Exceptions

setCurrentTime

Adjusts the clock for this SVG document fragment, establishing a new current time.

Parameters

in float seconds

The new current time in seconds relative to the start time for the current SVG document fragment.

No Return Value

No Exceptions

EventListenerInitializer

Interface used to set up event initializers, typically at document load time.

The EventListenerInitializer interface needs to be implemented by scripts written in Java (or other compiled languages). It is called when code is loaded and can be bound to a document.

IDL Definition

interface EventListenerInitializer
{
        void initializeEventListeners(dom::Document doc);
};

The use of this interface in the Java environment, with jar files and manifests, is not yet defined.

A.7 Traits supported in the SVG Tiny 1.2 DOM

Proposed list of supported traits

The table below shows the list of attributes and properties that Tiny DOM implementations must support. Each light gray section lists one or multiple elements for which the subsequent attributes or properties apply. Each attribute row lists the allowed getter and setter (s). This table is not normative.