SVG Document Object Model (DOM) – SVG 1.1 (Second Edition) (original) (raw)

Appendix B: SVG Document Object Model (DOM)

Contents

• B.1 SVG DOM overview
  • B.1.1 SVG DOM object initialization
• B.2 Elements in the SVG DOM
• B.3 Naming conventions
• B.4 Exception SVGException
• B.5 Feature strings for the hasFeature method call
• B.6 Relationship with DOM Level 2 Events
• B.7 Relationship with DOM Level 2 CSS
  • B.7.1 Introduction
  • B.7.2 User agents that do not support styling with CSS
  • B.7.3 User agents that support styling with CSS
  • B.7.4 Extended interfaces
• B.8 Read only nodes in the DOM
• B.9 Invalid values

This appendix is normative.

B.1 SVG DOM overview

This appendix provides an introduction to the SVG DOM and discusses the relationship of the SVG DOM with theDocument 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:

• Basic DOM interfaces
• Styling interfaces
• Document Structure interfaces
• Coordinate Systems, Transformations and Units interfaces
• Paths interfaces
• Basic Shapes interfaces
• Text interfaces
• Painting: Filling, Stroking and Marker Symbols interfaces
• Color interfaces
• Gradients and Patterns interfaces
• Clipping, Masking and Compositing interfaces
• Filter Effects interfaces
• Interactivity interfaces
• Linking interfaces
• Scripting interfaces
• Animation interfaces
• Fonts interfaces
• Metadata interfaces
• Extensibility interfaces

The SVG DOM builds upon and is compatible with DOM Level 2. In particular:

• The SVG DOM requires complete support forDOM Level 2 Core [DOM2]
• Wherever appropriate, the SVG DOM is modeled after and maintains consistency with theDocument Object Model HTML ([DOM1], chapter 2).
• The SVG DOM requires complete support for DOM Level 2 Views [DOM2VIEWS].
• The SVG DOM requires support for relevant aspects ofDOM Level 2 Events [DOM2EVENTS]. (For the specific features from DOM 2 Events that are required, see see Relationship with DOM Level 2 Events.)
• For implementations that support CSS, the SVG DOM requires complete support forDOM Level 2 Style Sheets ([DOM2STYLE], chapter 1) and relevant aspects ofDOM Level 2 CSS ([DOM2STYLE], chapter 2). (For the specific features from DOM 2 CSS that are required, seeRelationship with DOM Level 2 CSS.)

A DOM application can use the hasFeature method of the DOMImplementation interface to verify that the interfaces listed in this section are supported. The list of available interfaces is provided in section Feature strings for the hasFeature method call.

All SVG DOM objects that directly correspond to an attribute, e.g. the SVGAnimatedLength ry in anSVGRectElement, 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.

SVGTextContentElement.textLength

Initialized with the return-value of getComputedTextLength on the same element.

DOMString

Initialized as the empty string ("").

float

long

short

Initialized as 0.

boolean

Initialized as false.

SVGLength

Initialized as 0 user units (SVG_LENGTHTYPE_NUMBER).

SVGLengthList

SVGNumberList

SVGPointList

SVGStringList

SVGTransformList

Initialized as the empty list.

SVGAngle

Initialized as 0 in unspecified units (SVG_ANGLETYPE_UNSPECIFIED).

SVGZoomAndPan

Initialized as 0 (SVG_ZOOMANDPAN_UNKNOWN).

SVGPreserveAspectRatio

Initialized as 'xMidYMid meet'.

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

The SVG DOM follows similar naming conventions to theDocument Object Model HTML ([DOM1], chapter 2).

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.

exception SVGException { unsigned short code; };

// SVGException code const unsigned short SVG_WRONG_TYPE_ERR = 0; const unsigned short SVG_INVALID_VALUE_ERR = 1; const unsigned short SVG_MATRIX_NOT_INVERTABLE = 2;

SVG_WRONG_TYPE_ERR (unsigned short)

Raised when an object of the wrong type is passed to an operation.

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.

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 thehasFeature method call that is part of the SVG DOM's support for the DOMImplementation interface defined inDOM 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.

B.6 Relationship with DOM Level 2 Events

The SVG DOM supports all of the interfaces defined in, and the following event types from,DOM Level 2 Events[DOM2EVENTS]:

• These User Interface events ([DOM2EVENTS], section 1.6.1):
  • DOMFocusIn
  • DOMFocusOut
  • DOMActivate
• These mouse events ([DOM2EVENTS], section 1.6.2):
  • click
  • mousedown
  • mouseup
  • mouseover
  • mousemove
  • mouseout
    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.
• These mutation events ([DOM2EVENTS], section 1.6.4):
  • DOMSubtreeModified
  • DOMNodeInserted
  • DOMNodeRemoved
  • DOMNodeRemovedFromDocument
  • DOMNodeInsertedIntoDocument
  • DOMAttrModified
  • DOMCharacterDataModified
• The SVG DOM defines the following SVG-specific custom event interfaces. These event interfaces are mandatory for SVG user agents:
  • SVGLoad
  • SVGUnload
  • SVGAbort
  • SVGError
  • SVGResize
  • SVGScroll (triggered by either scroll or pan user actions)
    Note that the SVGLoad event does not fire until the document is fully loaded and is therefore subject to the processing of any ‘externalResourcesRequired’ attributes.
• The SVG DOM defines an additional custom event interface:
  • SVGZoom (definition can be found in the description of the SVGZoomEvent interface)
• The following event types are triggered due to state changes in animations. (The definitions for these events can be found in the description of the TimeEvent interface.)
  • beginEvent
  • endEvent
  • repeatEvent

While event listeners can be registered using anaddEventListener call on any element in the DOM, the use of event attributeson 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 theEventTarget. 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 registeredEventListener 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:

class MyAction1 implements EventListener { public void handleEvent(Event evt) { // process the event } } // ... later ... MyAction1 mc1 = new MyAction1(); myElement.addEventListener("DOMActivate", mc1, false);

In ECMAScript, one way to establish an event listener is to define a function and pass that function to the addEventListener method:

function myAction1(evt) { // process the event } // ... later ... myElement.addEventListener("DOMActivate", myAction1, false)

In ECMAScript, the character data content of anevent 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 isevt. For example, it is possible to write:

<rect onactivate="MyActivateHandler(evt)" .../>

which will pass the Event object evt into function MyActivateHandler.

B.7 Relationship with DOM Level 2 CSS

B.7.1 Introduction

The section describes the facilities from DOM Level 2 CSS([DOM2STYLE], chapter 2) that are part of the SVG DOM.

B.7.2 User agents that do not support styling with CSS

User agents that do not support styling with CSSare only required to support the following interfaces fromDOM Level 2 CSS([DOM2STYLE], chapter 2), along with any interfaces necessary to implement the interfaces, such asCSSPrimitiveValue and CSSValueList. These interfaces are used in conjunction with the getPresentationAttribute method call on interface SVGStylable, which must be supported on all implementations of the SVG DOM.

• Interface RGBColor
• Interface CSSValue

B.7.3 User agents that support styling with CSS

User agents that support Styling with CSS, the SVG DOM, and aural styling([CSS2], chapter 19) must support all of the interfaces defined inDOM Level 2 CSS([DOM2STYLE], chapter 2) which apply to aural properties.

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.

Whether or not a user agent supports styling with CSS, a user agent still must support interface CSSValue, as this is the type that is returned from the getPresentationAttributemethod call on interface SVGStylable.

DOM Level 2 CSS defines a set ofextended interfaces([DOM2STYLE], section 2.3) for use in conjunction with interface CSSValue. The table below specifies the type of CSSValue used to represent each SVG property that applies tovisual media([CSS2], section 7.3.1). The expectation is that the CSSValue returned from thegetPropertyCSSValue method on theCSSStyleDeclaration interface or the getPresentationAttributemethod on the SVGStylable interface can be cast down, using binding-specific casting methods, to the specific derived interface.

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 (thecssValueType of the CSSValue is CSS_VALUE_LIST), the derived interface is CSSValueList. For all other properties (the cssValueType of the CSSValueis 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:

• SVGColor
• SVGICCColor
• SVGPaint

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 asreadonly nodesby DOM Level 2 Core([DOM2], Glossary appendix). Specifically, Entityand EntityReferencenodes 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.