A.2 Overview of the SVG Tiny 1.2 DOM

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

Note that, like all other W3C DOM definitions, the SVG Tiny
1.2 DOM is programming-language independent. Although this
appendix only contain ECMAScript and Java examples, the SVG Tiny
1.2 DOM is compatible with other programming 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. One
way to gain access to the Document
object is to implement interface EventListenerInitializer
within your programming logic. The SVG Tiny user agent will
invoke your initializeEventListeners(dom::Document
doc) method once your programming logic has been
loaded and is ready to bind to the document. The
Document object typically will be
available via various other means, also.

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

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 the following elements in
the SVG namespace: <rect>, <circle>,
<ellipse>, <line>, <path>, <text>,
<image>, <use>, <a> and <g>.

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:

Any element nodes in the document can be removed, including
both element nodes that were created via the DOM and element nodes
that existed in the original document.

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:

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

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:

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.

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 NodenewChild

The Node to insert.

in NoderefChild

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 NodeoldChild

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.

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 DOMStringelementId

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.

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.

SVGLocatable

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.

DOMException with error code
NOT_SUPPORTED_ERROR if the requested trait is not
supported on this element.

setRGBColorTrait

Sets the specified value for the
trait with the given localName.

Parameters

in DOMString localName. The trait's local
name

in SVGRGBColor value. The trait's new
specified value.

No return value

Exceptions

DOMException with error code
TYPE_MISMATCH_ERR if the requested trait's value
cannot be specified as an SVGRGBColor.

DOMException with error code
NOT_SUPPORTED_ERROR if the requested trait is not
supported on this element.

DOMException with error code
INVALID_ACCESS_ERR if the input value is an
invalid value for the given trait.

DOMException with error code
NO_MODIFICATION_ALLOWED_ERR if attempt is made to
change readonly trait.

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.

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).

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.

floatcurrentScale

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.

floatcurrentRotate

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.

readonlySVGPointcurrentTranslate

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 floatseconds

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.

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.