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.

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.

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.

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.

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

This section and all the following are normative. Conforming SVG Viewers must support all constants, attributes and methods of all the interfaces defined in the SVG uDOM unless an interface explicitly allows for exceptions to this rule.

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.

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

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

A.4
Module: dom

A.4.1
DOMException

An exception that occurred due to a DOM operation, as defined in the
Fundamental Interfaces: Core Module
section of DOM Level 3 Core
([DOM3], section 1.4). Note that since the
SVG uDOM is a subset of DOM Level 3 Core, some of the exception codes defined
for this exception may never occur (such as
INUSE_ATTRIBUTE_ERR,
and VALIDATION_ERR).
However, in the interest of facilitating implementations that support both the
uDOM and the complete DOM Level 3 Core, none of the exception codes are removed.

This subset does not support the NodeType and DocumentPosition definition groups, since
the nodeType
field and the
compareDocumentPosition
method are not members of the subsetted interface.

Concerning textContent,
there is no requirement to create a Text node on setting since this subset
has no interface representing Text nodes. However, the behaviour of
textContent must be as if
the Text node described in the
the definition of textContent
had indeed been created.

An alternate way of accessing text content on elements defined within
the SVG specification is with the use of the #text trait.

A.4.5
ElementTraversal

This interface provides a way to traverse elements in the uDOM tree. It is needed mainly because SVG Tiny uDOM does not
expose character data nodes. Each element in the SVG Tiny document tree implements this interface, including elements
in foreign namespaces. For the normative definition of this interface see the ElementTraversal specification [ET]; it is only repeated informatively below.

A.4.6
Location

Location objects provide a representation of their document's address.

IDL Definition

interface Location
{
void assign(in DOMString iri);
void reload();
};

No defined constants

No defined attributes

Methods

assign

When this method is invoked, the user agent must navigate to the given IRI. The result of the traversal must be identical to the traversal caused by an 'a' hyperlink with the 'target' attribute set to '_replace'. The difference is that the 'a' hyperlink is activated on user interaction but assign is activated from script.
The current document location is the IRI of the Document object pointed to by the AbstractView.document field.
Relative IRI references are resolved based on the base IRI of the current document. If the base IRI differs from that of the current document, the current document is discarded, and loading and parsing of the
document at the specified IRI then begins. If the previous step resulted in loading of a new document, the timeline is restarted and a new load event is fired.
Note: For HTTP, a pragma:no-cache ([RFC2616], section 14.32) is not issued and thus a fresh copy from the server is not forced if there is a cache.

When this method is invoked, the user agent is forced to reload the resource identified by the Location.
The current document location is the IRI of the Document object pointed to by the AbstractView.document field.

The Window
object that is the parent view of this document's default view. If the
Window has no notion of
parent (e.g. if the document is displayed as the top level document in a
viewer), then the value of this attribute is null.

A.5
Module: views

The SVG Tiny 1.2 uDOM does not provide access to any views of the document other
than the default view.
The default view is accessible through
DocumentView::defaultView.
Note that the default view is required to also implement the
SVGGlobal interface.
In the ECMAScript language binding, the global script object must also be the
object that represents the default view.

A.5.1
AbstractView

This interface is a copy of the
AbstractView
interface from DOM Level 2 Views
([DOM2VIEWS], section 1.2), and must
be implemented by the object that represents the the
default view
of the document. In the ECMAScript language binding, the global script
object must implement this interface.

Please note that SVG Tiny 1.2 user agents are not required
to support the capture phase, and conformant SVG Tiny 1.2 content must not
make use of it. If an attempt to specify event operations on the capture
phase is made an SVG Tiny user agent that does not support it must
ignore them as if addEventListener had not been called.
(See Event flow for details.)

A.6.2
EventListener

The EventListener
interface is implemented by script to handle an event. The interface can be
implemented in ECMAScript by using a Function object (or by using an object
with a handleEvent property), and in Java by implementing the
interface directly. The EventListener
object can then be registered as a listener using
EventTarget::addEventListener.

The distance the wheel has rotated around the y-axis. A positive value shall indicate that the wheel has been
rotated away from the user on vertically-aligned devices or in a left-hand manner on horizontally aligned devices, and a
negative value shall indicate that the wheel has been rotated towards the user on vertically-aligned devices or in a
right-hand manner on horizontally-aligned devices.

data holds the value of the characters generated by the character device. This may be a single Unicode character or a non-empty sequence of Unicode characters [UNICODE]. Characters should be normalized to Unicode normalization form NFC, defined in Unicode Normalization Forms [UAX15]. This attribute will not be null or contain an empty string.

No defined methods

A.6.7
KeyboardEvent

Provides specific contextual information associated with keyboard devices. Each
KeyboardEvent
references a key using an identifier.

keyIdentifier holds the identifier of the key. The key identifiers are defined in the Key identifiers set, below. Implementations that are unable to identify a key must use the key identifier "Unidentified".

No defined methods

Key identifiers set

The list of key identifiers contained in this section is not exhaustive and input devices may have to define their own key identifiers. It is expected that DOM Level 3 Events will define an algorithm to determine which key identifier to use. Future SVG specifications will defer to DOM Level 3 Events for a definitive treatment of keyboard events and key identifiers.

A.6.9
ProgressEvent

Many resources, such as raster images, movies and complex SVG content
can take a substantial amount of time to download. In some use cases
the author would prefer to delay the display of content or the
beginning of an animation until the entire content of a file has been
downloaded. In other cases, the author may wish to give the viewer some
feedback that a download is in progress (e.g. a loading progress
screen).

The ProgressEvent
occurs when the user agent makes progress loading a resource (external)
referenced by an 'xlink:href' attribute.

The user agent must dispatch a
ProgressEvent at
the beginning of a load operation (i.e. just before starting to access the resource).
This event is of type loadstart.

The user agent must dispatch a
ProgressEvent at
the end of a load operation (i.e. after load is complete and the user agent is
ready to render the corresponding resource). This event is of type
loadend.

If false the total number of bytes (total) cannot be computed and the value
of total should be ignored. This might occur if the size of the downloaded
resource is unknown or if the data has already arrived.

loaded

Specifies the number of bytes downloaded since the beginning of the download.
This value is ignored for a loadstart
or loadend event.

total

Specifies the expected total number of bytes expected in a load operation. For a
progress event,
it should specify the total number of bytes expected.

Creates a begin instance time for the current time plus or minus the specified offset. The new instance time is added to the
begin instance times list.

Parameters

in floatoffset

The offset in seconds at which to begin the element.

No return value

No exceptions

beginElement

Creates a begin instance time for the current time. The new instance time is added to the
begin instance times list.
This is equivalent to beginElementAt(0).

No parameters

No return value

No exceptions

endElementAt

Creates an end instance time for the current time plus or minus the specified offset. The new instance time is added to the end instance times list.

Parameters

in floatoffset

The offset in seconds at which to end the element.

No return value

No exceptions

endElement

Creates an end instance time for the current time. The new instance time is added to the
end instance times list. This is equivalent to endElementAt(0).

No parameters

No return value

No exceptions

A.7.2
TimeEvent

TimeEvent is an interface used to provide contextual information for
events fired by animations in the document. It is a subset of the
TimeEvent
interface defined in
SMIL Animation
([SMILANIM], section 6.2).

In the example below, three 'use' elements use the same 'rect' element. Each 'use' has different 'fill' properties that are inherited down to the used 'rect'. The result is three 'rect' elements with different 'fill' colors. Clicking one of these three 'rect' elements will cause a fourth 'rect' to change color to match the clicked one. Worth noticing is that if the original 'rect' had not been in the 'defs' element the script would throw an exception when the original 'rect' is clicked. This is because the currentTarget attribute would return an SVGElement that doesn't have the correspondingUseElement attribute.

A.8.5
SVGSVGElement

User Agent Transforms

The uDOM attributes currentScale,
currentRotate and
currentTranslate
are combined to form a user agent transformation which is applied at the outermost
level on the SVG document (i.e. outside the
'svg' element).
Their values can potentially be modified through user agent specific UI, if
"magnification" is enabled (i.e.,
'zoomAndPan'
attribute is set to magnify). User agent transformation
can be obtained by multiplying the matrix

Indicates that focus must move to the next focusable object according to the user agent's own algorithm.

NAV_NEXT

Indicates that focus must move to the next focusable
object according to current 'nav-next' value.

NAV_PREV

Indicates that focus must move to the previous focusable
object according to current nav-prev value.

NAV_UP

Indicates a request that focus must move in the given direction.

NAV_UP_RIGHT

Indicates a request that focus must move in the given direction.

NAV_RIGHT

Indicates a request that focus must move in the given direction.

NAV_DOWN_RIGHT

Indicates a request that focus must move in the given direction.

NAV_DOWN

Indicates a request that focus must move in the given direction.

NAV_DOWN_LEFT

Indicates a request that focus must move in the given direction.

NAV_LEFT

Indicates a request that focus must move in the given direction.

NAV_UP_LEFT

Indicates a request that focus must move in the given direction.

Attributes

currentScale

The current user agent scale (zoom) coefficient. The initial value for
currentScale is 1.

currentRotate

The current user agent rotation angle in degrees. The initial value for
currentRotate is 0.

currentTranslate

The current user agent translation used for scrolling or panning. The returned
SVGPoint object is
"live" and setting its x and
y components will change the user
agent's translation. The initial for currentTranslate
is an SVGPoint object
with the value (0, 0).

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.

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 CSS 2 specification.)
If the parent element does not have a coordinate system, then the user agent should provide reasonable default values
for this attribute.

For stand-alone SVG documents, both 'x' and 'y' must be zero, the 'width' must be the width of the viewport which the host environment provides to the SVG user agent into which it can render its content, and the 'height' must be the height of the viewport, with all values expressed in the pixel coordinate system from the host environment, preferably such that this pixel coordinate system matches the same pixel coordinate system presented to HTML and matches the model for pixel coordinates described in the CSS 2 specification.
Note that "pixel coordinate systems" are host-specific. Two possible
approaches that hosts might use for pixel coordinate systems are
actual device pixels or (particularly for high-resolution devices)
pseudo device pixels which exactly match SVG and CSS's "px"
coordinates.

The object itself and its contents are both readonly. A DOMException with error code NO_MODIFICATION_ALLOWED_ERR
is raised if an attempt is made to modify it. The returned SVGRect object is "live", i.e. its x, y, width and height attributes are
automatically updated if the viewport size or position changes.

The current
document time,
in seconds, or 0 if the document timeline has not yet begun.

No parameters

No exceptions

setCurrentTime

Sets the
document time
(in seconds). This API is required to support seeking forwards and backwards in
the timeline. After a seek, animation continues to play (forwards) from the new
time. If seconds is negative, then the
document will seek to time 0s.

If setCurrentTime
is called before the document timeline has begun (for example, by script running
in a 'script'
element before the rootmost 'svg' element's
load event is dispatched, when
'playbackOrder'
is set to 'onLoad'), then the value of
seconds in the most recent invocation
of the method gives the time that the document time will be seeked to once
the document timeline has begun.

Creates a new SVGMatrix object. This object can be used to modify the value of traits which are compatible with the SVGMatrix type using the setMatrixTrait method. The internal representation of the matrix is as follows:

Creates a new SVGRect object. This object can be used to modify the value of traits which are compatible with the SVGRect
type using the setRectTrait method. The initial values for x, y, width and height of this new SVGRect are zero.

Creates a new SVGRGBColor object. This object can be used to modify the value of traits which are compatible with the SVGRGBColor type using the setRGBColorTrait method. The parameters are floats, one per color component. 0.0 represents zero intensity and 255.0 represents full intensity of a given color component. Colors originally in the rgb(%,%,%) syntax may have fractional components. Out of gamut colors may have component values less than 0.0 or greater than 255.0.

Moves the current focus to a different object based on the value of the parameter. The user agent must take into account the
currently focused object in the document in order to find the new focused object.

If this method succeeds:

A DOMFocusOut event must be dispatched which has the previously focused object as the event target.

After that, a DOMFocusIn event must dispatched which has the the new focused object as the event target.

A reference to the new focused object can be obtained using the EventTarget interface of the generated DOMFocusIn event.

Refer to the navigation section for a description of how navigation is managed. The behavior for this method must be the same as if an
equivalent move was done by the end user (for example by using a joystick or pressing the Tab key) and not by scripting.

Whenever the method fails (that is, when a DOMException is raised), focus must stay on the currently focused object and no DOMFocusOut/DOMFocusIn event is dispatched.

Note: For stand-alone SVG documents, the user agent must always have a currently focused object. At the beginning, the SVGDocument has focus.

INVALID_ACCESS_ERR: Raised if the currently focused object doesn't have a navigation attribute value corresponding to the requested motion type. For instance, if a moveFocus(NAV_UP) is called on an element which has no 'nav-up' attribute.

INVALID_STATE_ERR: Raised if the currently focused object has a navigation attribute value corresponding to the requested motion type but the target indicated in this attribute can not be found or is not a focusable object. For instance, if a moveFocus(NAV_UP) is called on an object which has a 'nav-up' attribute but the value of this attribute references an element which is not focusable.

setFocus

A request to put the focus on the given object.

If this method succeeds:

A DOMFocusOut event must be dispatched which has the previously focused object as the event target.

After that, a DOMFocusIn event must be dispatched which has the the new focused object as the event target.

A reference to the newly focused object can be obtained using the EventTarget interface of the generated DOMFocusIn event.

Whenever the method fails (that is, when a DOMException is raised), focus must stay on the currently focused object and no DOMFocusOut or DOMFocusIn event is dispatched.

Note: For stand-alone SVG documents, the user agent must always have a currently focused object. At the beginning, the SVGDocument has focus.

NOT_SUPPORTED_ERR: Raised if the in parameter is not a Node or SVGElementInstance, or if the requested element is not focusable (i.e. its 'focusable' attribute indicates that the element is not focusable).

getCurrentFocusedObject

Returns a reference to the object which has the focus. This returns an EventTarget.

A.8.6
SVGRGBColor

This interface represents a color value made up of red, green, and blue components.
It can be used to read and write traits that store color values (using getRGBColorTrait)
such as 'fill', 'stroke', and 'color'.

This matrix transforms source coordinates (x, y) into destination coordinates (x', y') by
considering them to be a column vector and multiplying the coordinate vector by the matrix
according to the following process:

SVG_MATRIX_NOT_INVERTABLE: Raised when the determinant of this matrix is zero.

mTranslate

Post-multiplies a translation transformation on the current matrix and returns the resulting current matrix.
This is equivalent to calling mMultiply(T), where T is an
SVGMatrix object represented by the following
matrix:

[ 1 0 x ]
[ 0 1 y ]
[ 0 0 1 ]

Parameters

in floatx

The distance by which coordinates are translated
in the x-axis direction.

in floaty

The distance by which coordinates are translated
in the y-axis direction.

Post-multiplies a uniform scale transformation on the current matrix and returns the resulting current matrix.
This is equivalent to calling mMultiply(S), where S is an SVGMatrix
object represented by the following matrix:

Post-multiplies a rotation transformation on the current matrix and returns the resulting current matrix.
This is equivalent to calling mMultiply(R), where R is an
SVGMatrix object represented by the following matrix:

The bounding box. The returned
object is a copy of the current bounding box value and will
not change if the corresponding bounding box changes.

No exceptions

getScreenCTM

Returns the transformation matrix from current user units to the initial viewport coordinate system. The clientX and clientY coordinates of a MouseEvent are in the initial viewport coordinate system. Note that null is returned if this element is not hooked into the document tree. This method would have been more aptly named as getClientCTM, but the name getScreenCTM is kept for historical reasons. Also note that getScreenCTM reflects a snapshot of the current animated state, i.e. if one or several transforms that affect the element that getScreenCTM is called upon are animated then the returned transformation matrix reflects the current state of each such animated transform when calculating the returned matrix.

The bounding box in screen coordinate space. The returned object
is a copy of the current screen bounding box value and will not change
if the corresponding screen bounding box changes.

No exceptions

The following examples further clarify the behavior of the getBBox()
method. The examples have a short explanation, an SVG fragment and are
followed by a set of bounding box values which have the following
format:

[elementId] : {x, y, width, height} | {null}

where x, y, width and height define the values of the SVGRect objects
returned from a getBBox call on the element with the specified ID.
There are a few cases where the bounding box may be null (see example
6).

Example #1: Simple groups and bounds
This first example shows the values returned by the getBBox method for
various simple basic shapes and groups. In particular, it shows that
the transform, on an element, does not change the value of its user
space bounding box.

Example #2: Bounding box on zero width or height rectangle
This example illustrates that the bounding box on elements is based on
the element's geometry coordinates. For example, the bounding box on a
zero-width rectangle is defined (see below), even though the rectangle
is not rendered.

Example #3: Bounding Box on zero radius ellipses.
This is another example of how bounding boxes are based on the
element's geometry. Here, the bounding box of an ellipse with a zero
x-axis radius is still defined, even though the ellipse is not rendered.

Example #4: Viewports do not clip bounding boxes
This example shows that no matter what the viewport is on the
rootmost 'svg' element,
the bounding boxes, based on the geometry, are still defined.
Here, even though the rootmost 'svg' element
has a zero width, the bounding boxes for the root itself and its children is precisely defined.

Example #5: getBBox on <use>
This example shows that the bounding box for a 'use' element
accounts for the 'x' and 'y' attributes defined on the element, just like
the 'x' and 'y' attributes impact the bounding box computation on a
'rect' or on an 'image' element.

Example #6: Empty group
This example shows that the bounding box for an empty group is null. By
the same token, the bounding box of a 'path' with an empty
SVGPath (i.e. one with no path commands, which may happen after
creating a new 'path' element with a createElementNS
call) is also null.

<g xml:id="emptyG"/>

Result:
[emptyG] : {null}

Example #7: Impact of display="none" and visibility="hidden"
This example shows how the bounding box of children with display="none"
are not accounted for in the computation of their parent's bounding
box. This reflects the definition of the 'display' property and its
impact on rendering and bounding box computation. The example also
shows that elements with 'visibility' set to hidden still contribute to
their parent's bounding box computation.

Example #8: Concatenating bounding boxes in the container's user space
This example shows how the concatenation and computation of bounding
boxes for container element happens in the container's user space.

A.8.13
TraitAccess

Trait manipulation interface. This interface is used to read and manipulate the value of "traits" associated with an
SVGElement. Each trait corresponds to an attribute or property, which is parsed and
understood by the element and in most cases animatable. Unlike attributes, each element has a well-defined set of
traits and attempting to access an unsupported trait must throw an exception. Also, unlike
attributes, traits are typed and their values are normalized; for instance path data specified on a 'path' element
is parsed and all path commands are converted to their absolute variants, and it is not possible to
determine from the value of the trait if a path command was absolute or relative. When getting and
setting trait values, an accessor of the correct type must be used or an exception will be thrown.

For a trait corresponding to a property, the computed value is used: if the value of a given property is not specified on that element, then for inherited properties the value on the parent is used. For non-inherited values, or on the root element, the initial value of the property is used.

For a trait corresponding to a non-property attribute, if the attribute is inherited (such as 'xml:lang') the value of the parent is used. If the attribute is not inherited, or on the root element, the lacuna value for the attribute is used, if known. If not known (for example, for an unknown attribute, or a known attribute with no specified default), null is returned.

Note that when using the TraitAccess interface for getting traits on elements outside of the tree, for example on elements just created or removed, what values are returned is user agent dependent.

Setting a trait value has the same effect as changing a corresponding attribute, but trait
setters can operate on typed values. The value which is modified is always a base value.
For inheritable traits corresponding to properties, the trait value can
always be set to inherit (but querying the
value will always return the actual inherited value as explained above).

Note about invalid/unsupported trait values: There are two situations
where the various trait setter methods (such as the
setTrait,
setFloatTrait and
setPathTrait
methods) consider a value invalid and throw a
DOMException with
the INVALID_ACCESS_ERR code. The first situation is when the trait value is
invalid with regards to its definition. (For example, trying to set the
'stroke-linejoin'
trait to 'foo' would result in this exception
being thrown). The trait methods will consider the value to be invalid if
it is an
unsupported value.
However, if the trait value being set is an
IRI reference,
such as when setting a <FuncIRI>
value on the 'fill'
property or when setting the
'xlink:href'
attribute on an 'image'
element, an SVG user agent
must not consider that trait value invalid if it is syntactically correct but
is otherwise an
invalid IRI reference.
Thus, the DOMException with code
INVALID_ACCESS_ERR must not be thrown in this case. This obviates the need for an
SVG user agent
to fetch the IRI
upon setting the trait solely to determine whether it is an
invalid IRI reference.

The second situation is when the trait value is invalid
with regards to animations currently applied to the trait. The value is
considered invalid because it would put the animation, and therefore the
document, in an error state. For example, if a 'path' element has
animations on its 'd' attribute, trying to change the 'd' attribute to a
value incompatible with the animations will cause the exception to happen.

Returns the trait value (possibly normalized) as a
DOMString.
In SVG Tiny only certain traits can be obtained as a
DOMString value. Syntax of the
returned DOMString matches the syntax of the corresponding attribute.
This method is exactly equivalent to getTraitNS with namespaceURI set to null.

TYPE_MISMATCH_ERR: Raised if requested trait's computed value cannot be converted to a sequence<float>.

getMatrixTrait

Returns the trait value as an SVGMatrix.
The returned object is a copy of the actual trait value and will not change if the corresponding trait changes. Parameter name must be a
non-qualified trait name, i.e. without prefix.

TYPE_MISMATCH_ERR: Raised if requested trait's computed value cannot be converted to an SVGMatrix.

getRectTrait

Returns the trait value as an SVGRect.
The returned object is a copy of the actual trait value and will not change if the corresponding trait changes.
If the actual trait value is not an
SVGRect, e.g. the 'none' value on the 'viewBox' attribute, this method will return null. Parameter name must be a
non-qualified trait name, i.e. without prefix.

TYPE_MISMATCH_ERR: Raised if requested trait's computed value cannot be converted to an SVGRect.

getPathTrait

Returns the trait value as an SVGPath.
The returned object is a copy of the actual trait value and will not change if the corresponding trait changes.
Parameter name must be a
non-qualified trait name, i.e. without prefix.

TYPE_MISMATCH_ERR: Raised if requested trait's computed value cannot be converted to an SVGPath.

getRGBColorTrait

Returns the trait value as an SVGRGBColor. The returned object is a copy of the trait value and will not change if
the corresponding trait changes. If the actual trait value is not an SVGRGBColor,
i.e. 'none' or a link to a paint server (e.g. to a gradient or a 'solidColor'), this method must return null.
Parameter name must be a
non-qualified trait name, i.e. without prefix.

TYPE_MISMATCH_ERR: Raised if requested trait's computed value cannot be converted to an SVGRGBColor.

getPresentationTrait

Returns
the trait presentation value as a DOMString.
In SVG Tiny only certain traits can be obtained as a DOMString value.
Syntax of the returned DOMString matches the syntax of the corresponding attribute.
This method is exactly equivalent to getPresentationTraitNS with namespaceURI set to null.

TYPE_MISMATCH_ERR: Raised if requested trait's computed value cannot be converted to a sequence<float>.

getMatrixPresentationTrait

Returns the trait presentation value as an SVGMatrix.
The returned object is a copy of the actual trait value and will not change if the corresponding trait changes or as animation continue to affect the trait presentation value.
Parameter name must be a
non-qualified trait name, i.e. without prefix.

TYPE_MISMATCH_ERR: Raised if requested trait's computed value cannot be converted to an SVGMatrix.

getRectPresentationTrait

Returns the trait presentation value as an SVGRect.
The returned object is a copy of the actual trait value and will not change if the corresponding trait changes or as animation continue to affect the trait presentation value.
If the actual trait value is not an
SVGRect, e.g. the 'none' value on the 'viewBox' attribute, this method will return null. Parameter name must be a
non-qualified trait name, i.e. without prefix.

TYPE_MISMATCH_ERR: Raised if requested trait's computed value cannot be converted to an SVGRect.

getPathPresentationTrait

Returns the trait presentation value as an SVGPath.
The returned object is a copy of the actual trait value and will not change if the corresponding trait changes or as animation continue to affect the trait presentation value.
Parameter name must be a
non-qualified trait name, i.e. without prefix.

TYPE_MISMATCH_ERR: Raised if requested trait's computed value cannot be converted to an SVGPath.

getRGBColorPresentationTrait

Returns the trait presentation value as an SVGRGBColor.
The returned object is a copy of the trait value and will not change if the corresponding trait changes or as animation continue to affect
the trait presentation value. If the actual trait value is not an SVGRGBColor,
i.e. 'none' or a link to a paint server (e.g. to a gradient or a 'solidColor'), this method must return null.
Parameter name must be a
non-qualified trait name, i.e. without prefix.

TYPE_MISMATCH_ERR: Raised if requested trait's computed value cannot be converted to an SVGRGBColor.

setTrait

Set the trait value as a DOMString. In SVG Tiny only certain traits can be set through a DOMString value. The syntax of the DOMString
that should be given as a value must be the same as syntax of the corresponding XML attribute value. Exactly equivalent
to setTraitNS with the namespaceURI attribute set to null.

INVALID_ACCESS_ERR: Raised if the input value is an invalid value for the given trait or null is specified.

setMatrixTrait

Set the trait value as an SVGMatrix. Values in SVGMatrix
are copied in the trait so subsequent changes to the given SVGMatrix have no effect on the value of the trait.
Parameter name must be a
non-qualified trait name, i.e. without prefix.

Set the trait value as an SVGRect. Values in SVGRect are copied in the trait so subsequent changes to the given
SVGRect have no effect on the value of the trait.
Parameter name must be a
non-qualified trait name, i.e. without prefix.

INVALID_ACCESS_ERR: Raised if the input value is an invalid value for the given trait or null is specified. An SVGRect is invalid if the width or height values are set to negative.

setPathTrait

Set the trait value as an SVGPath. Values in SVGPath are copied in the trait so subsequent changes to the given
SVGPath have no effect on the value of the trait.
Parameter name must be a
non-qualified trait name, i.e. without prefix.

INVALID_ACCESS_ERR: Raised if the input value is an invalid value for the given trait or null is specified.
An SVGPath is invalid if it begins with any segment other than MOVE_TO segment.Note: An empty SVGPath is still a valid value.

setRGBColorTrait

Set the trait value as an SVGRGBColor. Values in SVGRGBColor are copied in the trait so subsequent changes to the given
SVGRGBColor have no effect on the value of the trait.
Parameter name must be a
non-qualified trait name, i.e. without prefix.

Traits supported in this specification, SVG Tiny 1.2 uDOM

Trait access is not required on all of the SVG Tiny 1.2 attributes and properties. The table below shows
the attributes and properties that SVG Tiny 1.2 uDOM implementations must support trait access to.
Each attribute row lists the allowed getters and setters.
The "Lacuna Value" column specifies the lacuna value that must be used for each attribute or
property. If a "Lacuna Value" column entry is empty, there is no lacuna value. Unless explicitly stated in the "Comments" column, a supported attribute is accessible on all elements it can belong to. See the
attribute table for a list of
attributes and which elements they belong to.

Implementations that support multiple versions of SVG must
allow trait access to the most extensive set and support the types
supported by each trait in the most extensive set. However, content relying on
traits or trait types available in future versions may not work in all
conformant SVG Tiny 1.2 uDOM implementations.

The user agent must raise a NOT_SUPPORTED_ERR whenever there is an attempt to use trait methods for traits which are not supported by the user agent.

For some of the attributes and data types additional rules apply. These rules are defined below the table.

Wherever the table indicates that a user agent must support one of the typed (i.e., non-string) trait getter methods (e.g., getFloatTrait), it must also support the corresponding trait presentation getter method (e.g.,
getFloatPresentationTrait).

Wherever the table indicates that a user agent must support the setTrait method, it must also support the setTraitNS method.

Traits can only be used for accessing attribute and property values. They cannot be used for accessing font descriptors.

A.8.14 Additional accessing rules

The 'transform' attribute in SVG Tiny 1.2 can have three types of values.
The "normal" transformation list (e.g. scale, translate, rotate, matrix, etc.),
the newly introduced 'ref(svg)' type or 'none'. getMatrixTrait
returns the current evaluated matrix in
all cases. If the user needs to know that the 'transform' attribute value was a 'ref' or a 'none', getTrait must be used. By using setTrait the user can set the 'transform' attribute to 'ref(svg)' or 'none'.

Due to backward compatibility reasons the 'display' values accessible via the trait mechanism are limited to 'none' and 'inline', all other values are translated into 'none' or 'inline'. (For a list of all possible 'display' values, see Controlling visibility.) If other 'display' values are of interest, e.g. the user want to set display to 'block', the more generic getAttributeNS/setAttributeNS must be used. Note however that an SVG Tiny 1.2 user agent is allowed to normalize its attribute data as described in Display normalization.

Accessing rules for animation related elements

These elements can be inserted and removed from the tree but
they cannot be modified using the TraitAccess methods
once inserted into the tree. If an attempt is made to do so,
the TraitAccess
method will throw a DOMException
with code NOT_SUPPORTED_ERR. Modifying the element
using the setAttribute and
setAttributeNS
methods of the Element
interface will change the document, but will have no effect on
the animation.

This restriction means that if the author
wishes to add animations via script, the attributes of the animation elements
must be modified before being inserted into the tree. The following is an example of adding
an animation to the document, setting the relevant attributes prior to insertion.

Accessing rules for 'x' and 'y' attributes

If getFloatTrait
is used to retrieve the value of the
'x' or
'y'
attribute on a 'text'
element, where the attribute value has more than one
<coordinate>, a
DOMException with
error code TYPE_MISMATCH_ERR must be raised. When the attribute value has only one coordinate, this
is the value returned by getFloatTrait.

Accessing rules for 'width' and 'height' attributes

If getFloatTrait
is used to retrieve the value of the
'width' or
'height'
attribute on an 'svg'
element, where the value is specified as a percentage or unit value,
a DOMException with
error code TYPE_MISMATCH_ERR must be raised.

Accessing rules for font properties

Accessing rules for path attributes

If the getPathTrait method is used to get an SVGPath and
the path attribute was syntactically invalid at some point, the return value must be an SVGPath containing all
valid path segments until the point of the error.

A.8.19
SVGTimer

The SVGTimer interface provides an API for scheduling a one time or repetitive event. A SVGTimer object is always either in the running (attribute running is true) or waiting (attribute running is false) state. After each interval of the timer, an Event of type SVGTimer is triggered.

SVGTimer events are triggered only when the timer is in the running state. The SVGTimer event is limited to the target phase. Since SVGTimer is an EventTarget, EventListeners can be registered on it using addEventListener with SVGTimer as the event type. Event listeners can access their corresponding SVGTimer object through the event object's target property.

This attribute specifies the time remaining in milliseconds until the next event is fired. When the SVGTimer is in the running state this attribute is dynamically updated to reflect the remaining time in the current interval. When the SVGTimer is waiting the delay reflects the time that remained when stopped. Getting the delay attribute returns the current value, i.e. a snapshot value of the remaining delay. After delay period has passed while the object is in the running state, the SVGTimer object will trigger an Event of type SVGTimer. The delay will then be updated with the repeatInterval value and a new count down will start. Setting the delay resets the current interval to the new value. If this attribute is 0, it means that the event will be triggered as soon as possible. Assigning a negative value is equivalent to calling the stop() method. The initial value is set through the initialInterval parameter in the createTimer method on the SVGGlobal interface, and defines the first interval of the SVGTimer.

repeatInterval

This attribute specifies in milliseconds the interval for each repeat of the SVGTimer, i.e. each timer interval subsequent to the initial interval. The initial value of this attribute is set through the repeatInterval parameter in the createTimer method on the SVGGlobal interface. Assigning a negative value disables the repetitive triggering of the event making it a one time timer which triggers an event after the delay.

running

SVGTimer state. Value is true if the timer is running, false if the timer is waiting. Note that the repeatInterval and delay properties can be non-negative if the timer is stopped (but if delay is negative, the timer is stopped).

Methods

start

Changes the SVGTimer state into running. If the timer is already in the running state, it has no effect. Initially the timer is waiting, and must be started with this method. If the timer delay had a negative value when started, for example if the time had been stopped by setting the delay to a negative value, the delay value is reset to repeatInterval when the this method is called.

No parameters

No return value

No exceptions

stop

Changes the SVGTimer state into waiting. If the timer is already in the waiting state, calling this method has no effect.

No parameters

No return value

No exceptions

A.8.20
SVGGlobal

Many scripted SVG documents in existence make use of functions on a
browser specific Window interface. SVG Tiny 1.2 specifies an
SVGGlobal interface,
on which some of these de facto standard functions are defined, as well as
some functions for new features defines in this specification. The
SVGGlobal interface
must be implemented by the object that represents the
default view
of the document ([DOM2VIEWS], section 1.1).
This object also implements
AbstractView.
Thus, in the ECMAScript language binding, the global script object implements
SVGGlobal. The
SVGGlobal object
for a document can also be obtained through
DocumentView::defaultView.

Creates a SVGTimer with the provided initial and repeat Intervals. The SVGTimer will initially be in the waiting state.

Parameters

in longinitialInterval

Specifies the first interval in milliseconds for a repetitive SVGTimer, i.e. sets the initial value of the delay attribute on the timer. In the case the SVGTimer is not repetitive, it specifies the interval for the one time timer. Setting this parameter with a negative value will create an SVGTimer which is in the waiting state.

in longrepeatInterval

Specifies the time interval on which the SVGTimer repeats subsequent to the initial interval. A negative value will make the SVGTimer a one time timer.

Given an IRI and an
AsyncStatusCallback
object on which to call a callback function, this method will attempt to fetch
the resource at that IRI. If the IRI uses the HTTP or HTTPS scheme, the HTTP
GET method will be used. Implementations may support other schemes, but are
not required to.

Processing requirements

This method call must take place asynchronously. When called, control returns
immediately to the calling context, and once the request is completed the
callback is called. Multiple calls to this method must be executed in FIFO
order.

User agents are required to support the gzip content coding for HTTP
requests and must decode such content before passing it on to the
callback. User agents are not required to support gzip encoding
content that they send, though they are encouraged to. Cookies should
be supported so that state can be maintained across requests. User
agents may provide the user with means to interact with the request
(e.g. to enter authentication information) but are not required to.

It is important to note that for security reasons, user agents are strongly
encouraged to restrict these requests by origin. When enforcing such
restrictions, the callback is called immediately with its
AsyncURLStatus
object's success field set to false
and other fields set to null. Redirection responses (3xx HTTP
status codes) must not be exposed through the API but rather they must be
processed internally according to the HTTP specification.

The object on which the callback will be called upon completion of the request.

No return value

No exceptions

postURL

Given an IRI, data to be
transmitted, an
AsyncStatusCallback
object on which to call a callback function, a media type, and a content
coding, this method will post the data to the specified IRI using the
requested media type and content coding. User agents must support
postURL being invoked with an HTTP or
HTTPS IRI, but may support other IRI schemes if they indicate protocols that
are functionally compatible with HTTP. Once the request has been completed
the callback is invoked as described in the
AsyncStatusCallback
interface. If postURL is invoked with an
IRI that does not support posting content, or which does not post content
in a manner compatible with HTTP, a
DOMException
with code NOT_SUPPORTED_ERR must be thrown.

Processing requirements are the same as for
getURL, with the following
notes and additions.

The data passed in does not get any HTML form encoding applied to it, so that
applications that wish to transmit content corresponding to what an HTML form
would must produce the encoding themselves

When the content type parameter is set then the Content-Type header of the request
must be set accordingly. If the syntax of the content type parameter does
not match that of a media type, it must be ignored. If this parameter is not
specified, then it must default to text/plain.

When the encoding parameter is set then the user agent must encode the submitted
data with that HTTP content coding and set the Content-Encoding header accordingly,
if it supports it. If it does not support it, then it must ignore it, must
not set the Content-Encoding header, and must transmit the data with no encoding.
The only required content coding is identity.

When parsing the input string, the contextDoc parameter is used only for setting
the ownerDocument field in the parsed nodes.

If during parsing a 'script' element is encountered, it must not be executed at that time. It will only be executed if it inserted into the current SVG document.

There is no requirement to load any external resources, e.g. external entities, stylesheets, scripts, raster images, video,
audio, etc., for the parsing to complete. XSL stylesheets must not be applied.

If the contextDoc parameter is
defined, this method returns an Element object the ownerDocument
field of which must be set to be the provided Document object. In effect when
the contextDoc parameter is specified the processing must be equivalent to applying the following steps:

calling importNode on the Document object passed to parseXML
with the Element from the previous step as its first parameter and the
deep parameter set to true. (Please note that importNode is part of DOM 3 Core but not of the uDOM. It is mentioned here to indicate that the effect must be as if importNode had been used, but not to require that it be supported in implementations.)

INVALID_CHARACTER_ERR: Raised if one of the parsed XML names is
not an XML name according to the XML version of the
contextDoc document.

A.8.21
AsyncStatusCallback

This interface is implemented by code that intends to process content
retrieved through
getURL or
postURL, both of which take
an instance of this interface as a parameter. The
operationComplete
method of the object implementing this interface is called upon completion of
the request.

This method is implemented by code in order to be notified of the
result of fetching a resource using
getURL or
postURL. Upon completion
of the request, the method is called with an
AsyncURLStatus
object that holds the resource contents and information about the request.

For HTTP requests with response status codes in the 200 range, this
attribute must be set to true, and for status codes in the 400 and
500 ranges it must be set to false. Status codes in the 100 range
must be ignored and those in the 300 range must be processed as
indicated in getURL's processing
requirements.

When fetching non-HTTP resources, this attribute must be set to true
if the resource was successfully retrieved in full, and false
otherwise.

contentType

A string containing the media type of the response.

For HTTP requests, this attribute must be set to the value of the
Content-Type HTTP header. If there was no Content-Type header,
the attribute must be set to null.

When fetching non-HTTP resources, this attribute must be set to
null.

content

A string containing the contents of the fetched resource.

If the resource is not a valid sequence of characters (as
interpreted according to the media type and other headers for an
HTTP request, or as appropriate for non-HTTP resources), then this
attribute must be set to null.

For HTTP requests, if the media type of the response body was in the
text/* hierarchy and specified a charset parameter, then the text
must be converted into the host programming language's native form
if the encoding is supported. If the encoding is not supported, the
value of this field must be null. The only required encodings are
UTF-8 and UTF-16 (BE and LE). If the HTTP response body had one or
more content codings applied to it then it must be fully decoded
before setting this field. If the HTTP response status code was an
error code but carried a body, the content of that body must still
be exposed.

No defined methods

A.8.23
EventListenerInitializer2

The EventListenerInitializer2 interface
is used to provide a way for scripts written in languages that do not have
a concept of a "global object" to initialize their event listeners. Specifically,
it is used for Java event listeners, but this general approach is suggested
for other such scripting languages. See the description of the
'script'
element for details on how the object implementing
EventListenerInitializer2 is discovered
and used.