B.1 SVG DOM overview

This appendix provides an introduction to the SVG DOM and
discusses the relationship of the SVG DOM with the
Document Object Model (DOM) Level 2 Core Specification
[DOM2]. The
specific SVG DOM interfaces that correspond to particular
sections of the SVG specification are defined at the end of
corresponding chapters in this specification, as follows:

All SVG DOM objects that directly correspond to an attribute, e.g.
the SVGAnimatedLengthry in an
SVGRectElement, are live.
This means that any changes made to the attribute are immediately
reflected in the corresponding SVG DOM object.

B.1.1 SVG DOM object initialization

The SVG DOM allows attributes to be accessed even though they haven't been
specified explicitly in the document markup. When this happens an appropriate object
is created, initialized and returned. This newly constructed object does not affect rendering until
it is modified for the first time. After the first modification the object
becomes live, such that any modifications made to the corresponding
attribute are immediately reflected in the object.

For example, if rectElement.x.baseVal is accessed
and the ‘x’ attribute was not specified in the document, the
returned SVG DOM object would represent the value 0 user units.

For cases where an attribute has a default value the returned SVG DOM object that must reflect that value,
and for all other cases the object is initialized as described below.
If a particular SVG DOM interface is not listed below that means
that the object initialization shall be done using the values for the
objects that the interface contains, e.g DOMString in the
case of SVGAnimatedString, or four floats in the case of SVGRect.

B.2 Elements in the SVG DOM

Every Element object that corresponds to an SVG element (that is,
an element with namespace URI "http://www.w3.org/2000/svg" and a
local name that is one of the elements defined in this specification)
must also implement the DOM interface identified in element definition.
For example, in The ‘rect’ element,
the SVGRectElement interface is identified. This means that every
Element object whose namespace URI is "http://www.w3.org/2000/svg"
and whose local name is "rect" must also implement SVGRectElement.

B.3 Naming conventions

All names are defined as one or more English words
concatenated together to form a single string. Property or
method names start with the initial keyword in lowercase, and
each subsequent word starts with a capital letter. For example,
a property that returns document meta information such as the
date the file was created might be named "fileDateCreated". In
the ECMAScript binding, properties are exposed as properties of
a given object. In Java, properties are exposed with get and
set methods.

For attributes with the CDATA data type, the case of the
return value is that given in the source document.

B.4 Exception SVGException

This exception is raised when a specific SVG operation is impossible to
perform.

Note that no operation is defined to raise an SVGException with
this code in SVG 1.1 Second Edition. The constant remains defined here
for consistency with SVG 1.1 First Edition.

SVG_INVALID_VALUE_ERR (unsigned short)

Raised when an invalid value is passed to an operation or assigned to an
attribute.

SVG_MATRIX_NOT_INVERTABLE (unsigned short)

Raised when an attempt is made to invert a matrix that is not
invertible.

Note the unusual spelling of this constant, which is necessary for
compatibility with existing content.

Exception members:

code (unsigned short)

A code identifying the reason why the requested operation could not be
performed. The value of this member will be one of the constants
in the SVGException code group.

B.5 Feature strings for the hasFeature method call

The feature strings that are available for the
hasFeature method call that is part of the SVG
DOM's support for the DOMImplementation interface
defined in
DOM Level 2 Core
[DOM2]
are the same features strings available for the ‘requiredFeatures’ attribute that is
available for many SVG elements.

For all features that correspond to the SVG language and are
documented in this specification (see appendix Feature Strings for a list of features
in the SVG language), the version number for
the hasFeature method call is "1.1". For
features that correspond to other languages, refer to the
relevant other specifications to determine the appropriate
version number for the given feature.

clientX and clientY parameters for mouse
events represent the mouse coordinates at which the event
occurred relative to the DOM Implementation's client area.
relatedTarget is used to identify a secondary
EventTarget related to a UI event. Currently this attribute
is used with the mouseover event to indicate the
EventTarget which the pointing device exited and with the
mouseout event to indicate the EventTarget which the
pointing device entered.

While event listeners can be registered using an
addEventListener call on any element in the DOM,
the use of event attributes
on elements where those attributes are disallowed will not result in their
being invoked if the relevant event is dispatched to the element.
For example, if the ‘onclick’ attribute were specified on
a ‘title’ element, its contents would never be run in
response to a click event:

See the Attribute Index for details on
which elements a given event attribute is allowed to be specified on.

Implementors may view the setting of event attributes as the
creation and registration of an EventListener on the
EventTarget. Such event listeners are invoked only for
the "bubbling" and "at target" phases, as if false were specified
for the useCapture argument to addEventListener.
This EventListener behaves in the same manner as any other
which may be registered on the EventTarget.

If the attribute representing the event listener is changed,
this may be viewed as the removal of the previously registered
EventListener and the registration of a new one. Futhermore, no
specification is made as to the order in which event attributes
will receive the event with regards to the other EventListeners
on the EventTarget.

In Java, one way that event listeners can be established is
to define a class which implements the EventListener interface,
such as:

In ECMAScript, the character data content of an
event attribute becomes
the definition of the ECMAScript function which gets invoked in
response to the event. As with all registered ECMAScript event
listener functions, this function receives an Event object as a
parameter, and the name of the Event object is
evt. For example, it is possible to write:

For visual media
([CSS2], section 7.3.1),
user agents must support all of the required interfaces defined in
DOM Level 2 CSS. All of the interfaces that are optional for DOM Level 2 CSS
are also optional for user agents implementing the SVG DOM.

B.7.4 Extended interfaces

Note: the getPresentationAttribute method and the interfaces that extend CSSValue are deprecated, and may be dropped from future versions of the SVG specification.

For properties that are represented by a custom interface
(the cssValueType of the CSSValue is CSS_CUSTOM),
the name of the derived interface is specified in the table. For these
properties, the table below indicates which extended interfaces
are mandatory and which are not.

For properties that consist of lists of values (the
cssValueType of the CSSValue is
CSS_VALUE_LIST), the derived interface is CSSValueList. For all other
properties (the cssValueType of the CSSValue
is CSS_PRIMITIVE_VALUE), the derived interface is CSSPrimitiveValue.

For shorthand properties, a CSSValue always will have a value
of null. Shorthand property values can only be accessed and modified as
strings.

The SVG DOM defines the following SVG-specific custom property
interfaces, all of which are mandatory for SVG user agents:

B.8 Read only nodes in the DOM

Some operations and attributes in the SVG DOM are defined to raise an
exception when an attempt is made to modify a node in the DOM that
is read only. Such read only nodes are not related to attributes declared
in IDL with the readonly keyword. Rather, they are nodes
that cannot be modified by virtue of being defined as
readonly nodes
by DOM Level 2 Core
([DOM2], Glossary appendix).
Specifically, Entity
and EntityReference
nodes and their descendants are read only ([DOM2], section 1.3).

B.9 Invalid values

If a script sets a DOM attribute to an invalid value (e.g.,
a negative number for an attribute that requires a non-negative
number or an out-of-range value for an enumeration), unless
this specification indicates otherwise, no exception shall be
raised on setting, but the given document fragment shall become
technically in error as described
in Error
processing.