Appendix A: SVG Tiny 1.2 DOM

Contents

This appendix is normative.

A.1 Introduction

This appendix consists of the following parts:

A.2 Overview of the SVG Tiny 1.2 DOM

The SVG Tiny 1.2 DOM has the following features:

Here is a summary of features supported in the SVG 1.2 Tiny DOM:

Feature
 Support Options
Document Access
 Yes
Tree Navigation (i.e., accessing individual nodes)
 Limited to nodes with IDs
Element creation
 Yes, but restricted to specific element types
Text Node creation
 No (but see Text Node Access).
Element addition
 Yes, but restricted to specific element types
Element removal
 Yes, but restricted to specific element types
Attribute access (read)
 Yes, string based and typed
Attribute modification (write)
 Yes, string based and typed
Event dispatching
 No
Event Creation
 No
Event listener registration and removal
 Yes
Animation
 Yes, allows begin and end on 'indefinite' conditions.

The following sections describe the key features and constraints within the SVG Tiny 1.2 DOM.

Note: Like all other W3C DOM definitions, the SVG Tiny 1.2 DOM is scripting language independent. Although this appendix only contain ECMAScript and Java examples, the SVG Tiny 1.2 DOM is compatible with other scripting languages.

A.2.1 Document Access

All proposals assume that a Document object is present and is the root for accessing other features. The way the Document object becomes available depends on the usage context. For example, for code bound to an SVG document through a <handler> element, the Document would be passed to the corresponding XMLEventHandler implementation's init method.

Example:
<svg xmlns:ev="http://www.w3.org/2001/xml-events">



<rect id="myRect" x="10" y="20" width="200" height="300" fill="red"/>



<ev:listener ev:event="click" ev:observer="myRect"

           ev:handler="#myClickHandler" />



<!-- handler would be a new SVG element -->

<handler id="myClickHandler"

     type="application/java"

     xml:base="http://fooCompany.com/myJar.jar"

     xlink:href="#com.fooCompany.MyXMLEventHandler"/>

  <param name="offset" value="10" />

</svg>
with MyXMLEventHandler being:
package com.fooCompany;



import tbd.XMLEventHandler;

import org.w3c.dom.Document;

import org.w3c.dom.svg.SVGElement;

import org.w3c.dom.svg.SVGTraitAccessor;

import org.w3c.dom.events.Event;



public class MyXMLEventHandler implements XMLEventHandler {

   Document document;

   SVGTraitAccessor widthTraitAccessor;



   public void init(Document doc, Element handlerElement) {

        document = doc;

        SVGElement root = (SVGElement)document.getDocumentElement();

        widthTraitAccessor = root.getTraitAccessor("width");

        // ...

   }



   public void handleEvent(Event event) {

        SVGElement myRect = 

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

        

        float width = myRect.getTraitAsFloat(widthTraitAccessor);

        myRect.setTraitAsFloat(widthTraitAccessor, width + 10);

   }

}
In the remainder of this document, the variable 'document' is assumed to be an instance of the Document interface.

A.2.2 Tree Navigation

Tree navigation is the ability to access individual SVG Elements in a document tree.
SVG Tiny 1.2 DOM gives access to individual elements by identifier. It also allows some navigation of the document tree thanks to the Node's interface. From a Node, it is possible to access its parent Node and to the owner Document node:
Element myRect = document.getElementById("myRect");

Node myRectParent = myRect.getParentNode();

Document doc = myRect.getOwnerDocument();
SVG Tiny 1.2 DOM also gives access to the Document's root element:
Element svgRoot = document.documentElement();

A.2.3 Element Creation

SVG Tiny 1.2 DOM allows the creation of new Elements:
Element myRect = document.createElementNS(svgNS, "rect");
The type of elements which can be created through the createElementNS method is restricted to:
  1. The SVG namespace.
  2. The following elements: <rect>, <circle>, <ellipse>, <line>, <polyline>, <polygon>, <path>, <text>, <image> <anchor> and <use>

A.2.4 Element Addition

Node Addition is the ability to add new elements to a document tree.

SVG Tiny 1.2 DOM allows addition and insertion and insertion of a Node:
// 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);
The types of nodes which can be inserted into the Document is limited to the same list specified in the Element Creation section.

A.2.5 Element Removal

Node removal is the ability to remove an element from a document tree.

SVG Tiny 1.2 DOM allows the removal of Nodes: 
Element myRect = ...; // See Element creation

Element myGroup = document.getElementById("myGroup");

myGroup.appendChild(myRect);

....

myGroup.removeChild(myRect);
However, the API limits the removal of nodes to nodes which were added to the document tree by a prior call to insertBefore or appendChild.

A.2.6 Attribute Access

The following write-up describes the use of trait accessor to achieve typed access to attribute values, property values, and animated values. Trait accessors is the preferred approach within the SVG working group; however, it is important to note that three approaches have been considered, with trait accessors as one of the three.

Object/traits approach (The preferred approach within SVG working group. It requires that scripts acquire trait accessors before using them, but has the benefits that the approach scales to Basic and Full, scales to multiname documents, fits in well with RCC/XBL, promotes security (versus ENUMs), promotes small footprint implementations, and allows for performance optimization via implementation-private data within object.):
float width = MyRect.getTraitAsFloat(widthTraitAccessor);
width += 10;
MyRect.setTraitAsFloat(widthTraitAccessor, width);
ENUM approach (An alternate approach. Hardcoded enums have multiple problems, such as what happens with mixed namespace documents and custom elements/attributes, and security risks by possibility of indexing off of end of arrays.):
float width = MyRect.getTraitAsFloat(SVGTraits.WIDTH);
width += 10;
MyRect.setTraitAsFloat(SVGTraits.WIDTH, width);
String approach (An alternate approach. Simplest to use, but string lookups are required with each call.):
float width = MyRect.getTraitAsFloat("width");
width += 10;
MyRect.setTraitAsFloat("width", width);

Accessing attributes in the SVG Tiny 1.2 DOM is handled by the use 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. Previously, there was no uniform way to access the traits in SVG DOM or track their mutation. Also, the older APIs for typed access to trait values suffer from needless temporary object creation and require too many steps to get to the desired value. The new trait interfaces in SVG 1.2 address these problems and are designed to meet the lightweight implementation requirements of highly constrained mobile devices.

To access a trait, one first need to acquire a trait accessor. A trait accessor is a lightweight object that is associated with a given trait within a given namespace (or possibly no namespace, in the case of attributes or properties which have no namespace prefix). Trait accessors are element-independent; thus, a trait accessor for the 'width' trait with no namespace identification can be used to access to the 'width' attribute on multiple different element types; thus, a trait accessor for 'width' can access the 'width' attribute on <svg>, <image>, <rect> and several other elements in the SVG language.

To acquire a trait accessor, call either getTraitAccessor() or getTraitAccessorNS(), passing in the name of the trait. For example, to acquire a trait accessor for the 'width' attribute on any element, you might use the following call to getTraitAccessor():

SVGTraitAccessor widthTraitAccessor = RootSVGElement.getTraitAccessor("width");

Alternatively, you can also use getTraitAccessorNS(). This example shows how you would acquire a trait accessor to the 'href' attribute in the XLink namespace:

SVGTraitAccessor xlinkHrefTraitAccessor = RootSVGElement.getTraitAccessorNS

         ("http://www.w3.org/1999/xlink", "href");

The following ECMAScript example shows how a trait accessor for the 'width' attribute on a <rect> element can be used to change the width of two rectangles:

// This logic might be within the initialization logic

widthTraitAccessor = RootSVGElement.getTraitAccessor("width");



// This logic might be within an event handler

var width; 

float width = MyRect1.getTraitAsFloat(widthTraitAccessor); 

width += 10; 

MyRect1.setTraitAsFloat(widthTraitAccessor, width); 

float width = MyRect2.getTraitAsFloat(widthTraitAccessor); 

width += 20; 

MyRect2.setTraitAsFloat(widthTraitAccessor, width);

The following description of <traitDef> is in this appendix only temporarily. It should be replaced by a link to the definition of <traitDef> within the main specification.

Note that the data types of all attributes and properties defined in the SVG specification are known to the user agent. However, custom elements and custom traits (attribute or property) are unknown to the user agent, so the user agent doesn't know the data types on the traits. SVG 1.2 adds the <traitDef> element to register the data type of a particular trait. For example, to register an attribute named 'measurement' as being of type 'SVGLength', you do the following:

<traitDef name="measurement" valueType="SVGLength"/>

A.2.7 Text Node Access

In the SVG 1.2 Tiny DOM, text node access is only available via the DOM3 'textContent' attribute on the Node interface.

A.2.8 Event Listener Registration and Removal

Event Listener Registration and Removal is the ability to add and remove new event listeners from a Document.
SVG Tiny 1.2 DOM allows adding and removing EventListeners:
class MyEventListener implements EventListener {

    public void handleEvent(Event evt) {

        // Do whatever is needed here

    }

}

...

EventListener l = new MyEventListener();



// SVGElement implements EventTarget. All elements in the

// SVG namespace are SVGElement implementations.

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



// Listen to click events during the capture phase

myRect.addEventListener("click", l, true);



// Listen to mouseover events, during the buble phase

myRect.addEventListener("mouseover", l, false);

....



// Remove the click listener

myRect.removeEventListener("click", l, true);
Refer to the DOM Events Level 2 specification or the XML Events specification introduction for an explanation of the SVG event flow and the meaning of event targets, event current target, bubble and capture.

A.2.9 Animation

SVG Tiny 1.2 DOM allows code to start or end animation elements. 
AnimationElement animateColor 

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



animateColor.beginElement();

A.3 Interfaces from Core DOM

Interface 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 2 specification.


IDL Definition
interface Node { 

    const unsigned short ELEMENT_NODE = 1;

    const unsigned short DOCUMENT_NODE = 9;



           // Introduced in DOM Level 3:

           attribute DOMString       textContent;

                                        // raises(DOMException) on setting



  Node appendChild ( in Node newChild ) 

        raises( DOMException);

  readonly attribute unsigned short nodeType;

  readonly attribute Document ownerDocument;

  readonly attribute Node parentNode;

  Node insertBefore ( in Node newChild, in Node refChild ) 

        raises( DOMException);

  Node removeChild ( in Node oldChild ) 

        raises( DOMException);

};

Defined constants
DOCUMENT_NODE
The node is a Document
ELEMENT_NODE
The node is an Element
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 2 specification.
getOwnerDocument
Get the document associated with this node.
No Parameters
Return Value
Document
the Document associated with this node.
No Exceptions
getParentNode
Get the parent of this node.
No Parameters
Return Value
Node
the parent node
No Exceptions
getNodeType
Get the type of this node.
No Parameters
Return Value
unsigned short
the Node's type, one of the XXX_NODE constants.
No Exceptions

Interface 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 2 specification. Note that the getFirstChild method returns the root of the document.


IDL Definition
interface Document : Node { 

  Element createElementNS ( in DOMString namespaceURI, in DOMString qualifiedName ) 

        raises( DOMException);

  readonly attribute Element          documentElement;

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

Interface 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 2 specification. Note that in SVG Tiny 1.2 DOM implementations which support events, Element implementations also implement the EventTarget interface. Refer to the DOM Level 2 Events for details.


IDL Definition
interface Element : Node { 

  DOMString getAttribute ( in DOMString name ); 

  DOMString getAttributeNS ( in DOMString namespaceURI, in DOMString qualifiedName );

  void removeAttribute ( in DOMString name );

  void removeAttributeNS ( in DOMString namespaceURI, in DOMString qualifiedName );

  void setAttribute ( in DOMString name, in DOMString value ) 

        raises( DOMException);

  void setAttributeNS ( in DOMString namespaceURI, 

                        in DOMString qualifiedName, in DOMString value ) 

        raises( DOMException);

};

No Defined constants
Methods
getAttribute
Convenience method for getAttributeNS(null, name).
Parameters
in DOMString name
The name of the attribute to retrieve.
Return Value
DOMString
The attribute value.
No Exceptions
getAttributeNS
Get the value of an attribute.
Parameters
in DOMString namespaceURI
The namespace URI of the retrieved attribute.
in DOMString qualifiedName
The qualified name of the attribute to set on the element.
Return Value
DOMString
The attribute value.
No Exceptions
removeAttribute
Convenience method for removeAttributeNS(null, name).
Parameters
in DOMString name
The name of the attribute to remove.
No Return Value
No Exceptions
removeAttributeNS
Removes an attribute.
Parameters
in DOMString namespaceURI
The namespace URI of the attribute to remove.
in DOMString qualifiedName
The qualified name of the attribute to remove.
No Return Value
No Exceptions
setAttribute
Convenience method for setAttributeNS(null, name, value).
Parameters
in DOMString name
The name of the attribute to set on the element.
in DOMString value
The new attribute value.
No Return Value
Exceptions
DOMException
If the attribute value cannot be set.
setAttributeNS
Set an attribute with a given value.
Parameters
in DOMString namespaceURI
The namespace URI of the retrieved attribute.
in DOMString qualifiedName
The qualified name of the attribute to set on the element.
in DOMString value
The new attribute value.
No Return Value
Exceptions
DOMException
If the attribute value cannot be set.

Interface DOMException

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


IDL Definition
exception DOMException { 

    unsigned short code;

};

// DOMExceptionCode 

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;

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

A.4 Interfaces from DOM Events

Interface Event

Provides information about an event and its propagation. The interface allows listeners to stop the propagation. This interface is a subset of the Event interface defined in the DOM Level 2 Events specification. Please refer to that specification for details on what the different methods and members mean.


IDL Definition
interface Event { 

    const unsigned short AT_TARGET = 0

    const unsigned short BUBBLING_PHASE = 1;

    const unsigned short CAPTURING_PHASE = 2;



  readonly attribute EventTarget currentTarget;

  readonly attribute unsigned short eventPhase;

  readonly attribute EventTarget target;

  readonly attribute type;

  void stopPropagation ( );

};

Defined constants
AT_TARGET
The event is currently being evaluated at the target EventTarget.
BUBBLING_PHASE
The current event phase is the bubbling phase.
CAPTURING_PHASE
The current event phase is the capturing phase.
Defined attributes
(Incomplete)
Methods
stopPropagation
Prevents further propagation of the event. The event will still be dispatched to all listeners on the current target before the event flow stops.
No Parameters
No Return Value
No Exceptions

Interface EventListener

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


IDL Definition
interface 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

Interface 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 2 Events specification. Please refer to that specification for details on what the different methods and members mean.


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

Supported events

The following events are supported:

A.5 Interfaces for SVG DOM

Interface SVGDocument

SVGDocument provides an API to access SVG specific features, such as setting the viewport size


IDL Definition
interface SVGDocument : Document { 

  readonly attribute SVGSVGElement rootElement;

};

No Defined constants
Attributes
readonly SVGSVGElement rootElement
The root 'svg' element in the document hierarchy.
No defined methods

Interface SVGTraitAccessor

SVGTraitAccessor is an object to access trait values. It serves as a key to look up the value of the trait stored on the element. In SVGT trait accessor is an opaque object with no interface attached (so it can be implemented as either java.lang.String or java.lang.Integer). Trait accessors are not element-specific, that is trait accessor that can access "x" trait will work for all elements that have suh trait (e.g. rect, svg, text, etc.).


IDL Definition
interface SVGTraitAccessor {

    // trait accessor can be an opaque object instead in SVGT 

    readonly attribute DOMString name; 

    readonly attribute DOMString namespaceURI; 

};

No Defined constants
Attributes (not yet completed)
Methods (not yet completed)

Interface SVGTraitMutationEvent

SVGTraitMutationEvent is raised whenever a trait value changes.


IDL Definition
interface SVGTraitMutationEvent : Event { 

// event that is sent to trait mutation listeners

// name = "SVGTraitChanged" 

SVGTraitAccessor trait; 

};

No Defined constants
Attributes (not yet completed)
Methods (not yet completed)

Interface ElementWithTraits

ElementWithTraits is a base interface that allows typed access to the XML attributes and CSS properties on all elements in the document. Interface ElementWithTraits is available on all elements, whether or not they are in the SVG namespace.

On open issue is whether getTraitAccessor() and getTraitAccessorNS() should be moved from interface ElementWithTraits to SVGSVGElement.


IDL Definition
interface ElementWithTraits { 



    boolean traitIsSpecified( in SVGTraitAccessor traitAccessor ) raises SVGException; 



    DOMString getTraitAsString( in SVGTraitAccessor traitAccessor ) 

        raises SVGException; 

    DOMString getTraitAsStringAnimated( in SVGTraitAccessor traitAccessor ) 

        raises SVGException; 

    void setTraitAsString( in SVGTraitAccessor traitAccessor, DOMString newValue ) 

        raises SVGException;



    float getTraitAsFloat( in SVGTraitAccessor traitAccessor ) 

        raises SVGException; 

    float getTraitAsFloatAnimated( in SVGTraitAccessor traitAccessor ) 

        raises SVGException; 

    void setTraitAsFloat( in SVGTraitAccessor traitAccessor, float newValue ) 

        raises SVGException;



    long getTraitAsInteger( in SVGTraitAccessor traitAccessor ) 

        raises SVGException; 

    long getTraitAsIntegerAnimated( in SVGTraitAccessor traitAccessor ) 

        raises SVGException; 

    void setTraitAsInteger( in SVGTraitAccessor traitAccessor, long newValue ) 

        raises SVGException;



    SVGColor getTraitAsSVGColor( in SVGTraitAccessor traitAccessor ) 

        raises SVGException; 

    SVGColor getTraitAsSVGColorAnimated( in SVGTraitAccessor traitAccessor ) 

        raises SVGException; 

    void setTraitAsSVGColor( in SVGTraitAccessor traitAccessor, SVGColor newValue ) 

        raises SVGException;



    SVGPaint getTraitAsSVGPaint( in SVGTraitAccessor traitAccessor ) 

        raises SVGException; 

    SVGPaint getTraitAsSVGPaintAnimated( in SVGTraitAccessor traitAccessor ) 

        raises SVGException; 

    void setTraitAsSVGPaint( in SVGTraitAccessor traitAccessor, SVGPaint newValue ) 

        raises SVGException;



    SVGRect getTraitAsSVGRect( in SVGTraitAccessor traitAccessor ) 

        raises SVGException; 

    SVGRect getTraitAsSVGRectAnimated( in SVGTraitAccessor traitAccessor ) 

        raises SVGException; 

    void setTraitAsSVGRect( in SVGTraitAccessor traitAccessor, SVGRect newValue ) 

        raises SVGException;



    SVGMatrix getTraitAsSVGMatrix( in SVGTraitAccessor traitAccessor ) 

        raises SVGException; 

    SVGMatrix getTraitAsSVGMatrixAnimated( in SVGTraitAccessor traitAccessor ) 

        raises SVGException; 

    void setTraitAsSVGMatrix( in SVGTraitAccessor traitAccessor, SVGMatrix newValue ) 

        raises SVGException;



    SVGPoint getTraitAsSVGPoint( in SVGTraitAccessor traitAccessor ) 

        raises SVGException; 

    SVGPoint getTraitAsSVGPointAnimated( in SVGTraitAccessor traitAccessor ) 

        raises SVGException; 

    void setTraitAsSVGPoint( in SVGTraitAccessor traitAccessor, SVGPoint newValue ) 

        raises SVGException;



    void removeTrait( in SVGTraitAccessor traitAccessor ) 

        raises SVGException;

 

    SVGTraitAccessor getTraitAccessor( in DOMString name ) 

        raises SVGException; 

    SVGTraitAccessor getTraitAccessorNS( in DOMString namespace, in DOMString name ) 

        raises SVGException;



    void addTraitMutationListener( in SVGTraitAccessor traitAccessor, 

                          EventListener listener )     

        raises SVGException; 

    void removeTraitMutationListener ( in SVGTraitAccessor traitAccessor, 

                              EventListener listener ) 

        raises SVGException;



};

No Defined constants
Attributes (not yet completed)
Methods (not yet completed)

Interface SVGElement

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


IDL Definition

In SVG 1.1, Events::EventTarget are only on objects that might indeed receive events. Thus, Events::EventTarget is on SVGCircleElement, but not on SVGColorProfileElement. With the SVG Tiny 1.2 DOM, we want to minimize the number of interfaces. Thus, we are proposing to have SVGElement implement Events::EventTarget since all things that derive from SVGElement in the SVG Tiny 1.2 DOM can actually receive events. However, because SVG Basic/Full need to be upwardly compatible, this means all elements in the SVG DOM will implement Events::EventTarget, including SVGColorProfileElement. This seems OK because everything conceivably can receive attribute modified mutation events.

interface SVGElement  : Element, Events::EventTarget, ElementWithTraits { 

    attribute DOMString id;

                       // raises DOMException on setting

    SVGRect   getBBox (  );

};

No Defined constants
Attributes (not yet completed)
Methods (not yet completed)

Interface SVGSVGElement

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


IDL Definition
interface SVGSVGElement : SVGElement { 

  readonly attribute SVGRect           viewport;

           attribute float currentScale;

                         // raises DOMException on setting

  readonly attribute SVGPoint currentTranslate;

  unsigned long suspendRedraw ( in unsigned long max_wait_milliseconds ); 

  void unsuspendRedraw ( in unsigned long suspend_handle_id ) 

        raises( DOMException );

  void pauseAnimations ( );

  void unpauseAnimations ( );

  boolean animationsPaused (  );

  float getCurrentTime ( );

  void setCurrentTime ( in float seconds);

  boolean checkIntersection ( in SVGElement element, in SVGRect rect );

};

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. DOM attributes currentScale and currentTranslate are equivalent to the 2x3 matrix [a b c d e f] = [currentScale 0 0 currentScale currentTranslate.x currentTranslate.y]. 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).
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".
Methods
suspendRedraw
Takes a time-out value which indicates that redraw shall not occur until: (a) the corresponding unsuspendRedraw(suspend_handle_id) call has been made, (b) an unsuspendRedrawAll() call has been made, or (c) its timer has timed out. In environments that do not support interactivity (e.g., print media), then redraw shall not be suspended. suspend_handle_id = suspendRedraw(max_wait_milliseconds) and unsuspendRedraw(suspend_handle_id) must 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 = suspendRedraw(max_wait_milliseconds) and follow the changes with a method call similar to unsuspendRedraw(suspend_handle_id). Note that multiple suspendRedraw calls can be used at once and that each such method call is treated independently of the other suspendRedraw method calls.
Parameters
in unsigned long 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
unsigned long
A number which acts as a unique identifier for the given suspendRedraw() call. This value must be passed as the parameter to the corresponding unsuspendRedraw() method call.
No Exceptions
unsuspendRedraw
Cancels a specified suspendRedraw() by providing a unique suspend_handle_id.
Parameters
in unsigned long suspend_handle_id
A number which acts as a unique identifier for the desired suspendRedraw() call. The number supplied must be a value returned from a previous call to suspendRedraw()
No Return Value
Exceptions
DOMException
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.
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
checkIntersection
Returns true if the rendered content of the given element intersects the supplied rectangle, honoring the 'pointer-events' property value on each candidate graphics element.
Parameters
in SVGElement element
The element on which to perform the given test.
in SVGRect rect
The test rectangle. The values are in the initial coordinate system for the current 'svg' element.
Return value
boolean
True or false, depending on whether the given element intersects the supplied rectangle.
No Exceptions

Interface SVGColor


IDL Definition
interface SVGColor {

   // These are bit fields which indicate which components of SVG's <color> 

syntax

   // have been specified.

   const unsigned short SVG_COLORSPEC_RGB              = 1;

   const unsigned short SVG_COLORSPEC_CURRENTCOLOR      = 32768;

   readonly attribute unsigned short colorSpec;



   // If "current color" is specified, then float_r, float_g, float_b, r, 

g, or b hold the color value of that color.

   // Setting any of float_r, float_g, float_b, r, g, or b replaces any 

"current color"

   // settings within a presentation attribute on the current element with 

an explicit RGB color setting.

         unsigned short r; // Red color component, ranging 0 to 65535.

         unsigned short g; // Green color component, ranging 0 to 65535.

         unsigned short b; // Blue color component, ranging 0 to 65535.

};

Interface SVGPaint


IDL Definition
// NOTE: It's OK for Tiny implementers to flatten SVGPaint and SVGColor

// to remove inheritance so long as it achieves the same result.

interface SVGPaint : SVGColor {





   // These are bit fields which indicate which components of SVG's <paint> 

syntax

   // have been specified.

   // Note: If SVG_PAINTSPEC_COLOR is set, then you can access the color 

information

   // via the facilities from SVGColor, which SVGPaint inherits.

   // Given that Tiny is adding gradients, this would be required for Full, 

Basic and Tiny.

   const unsigned short SVG_PAINTSPEC_COLOR              = 1;

   const unsigned short SVG_PAINTSPEC_URI              = 2;

   readonly attribute unsigned short paintComponents;



   // Color keywords supported by Tiny (16 total).

   // This list is a strict subset of Full, and the ENUM values match exactly.

   const unsigned short SVG_COLOR_BLACK = ???;

   const unsigned short SVG_COLOR_SILVER = ???;

   const unsigned short SVG_COLOR_GRAY = ???;

   // and so on



   // Given that Tiny is adding gradients, this would be required for Full, 

Basic and Tiny.

   readonly attribute DOMString      uri;

};

Interface SVGRect

SVGRect is the same interface as the SVGRect interface in the SVG 1.1 specification.
For definition see SVGRect.

Interface SVGMatrix

SVGMatrix is a subset of the SVGMatrix interface in the SVG 1.1 specification. It only includes the a,b,c,d,e,f DOM attributes and the multiply(), rotate(), inverse(), scale() and translate() methods.
For definition see SVGMatrix.

Interface SVGPoint

SVGPoint is a subset of the SVGPoint interface in the SVG 1.1 specification. It only includes the x,y DOM attributes.
For definition see SVGPoint.

Interface GetSVGDocument

In the case where an SVG document is embedded by reference, such as when an XHTML document has an 'object' element whose href (or equivalent) attribute references an SVG document (i.e., a document whose MIME type is "image/svg+xml" and whose root element is thus an 'svg' element), the SVG user agent is required to implement the GetSVGDocument interface for the element which references the SVG document (e.g., the HTML 'object' or comparable referencing elements).

The GetSVGDocument interface also is the appropriate interface which should be supported on any classes that provide API access for a host application to gain access to the SVG DOM for a particular SVG object.


IDL Definition
interface GetSVGDocument { 

  SVGDocument getSVGDocument (  )

                  raises( DOMException );

};