previous next contents elements attributes properties index

30 April 2002

# Appendix B: SVG Document Object Model (DOM)

### Contents

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 the Document Object Model (DOM) Level 2 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 is builds upon and is compatible with the Document Object Model (DOM) Level 2 Specification [DOM2]. In particular:

- The SVG DOM requires complete support for the DOM2 core [DOM2-CORE]
- Wherever appropriate, the SVG DOM is modeled after and maintains consistency with the Document Object Model HTML [ DOM1-HTML].
- The SVG DOM requires complete support for the DOM2 views [DOM2-VIEWS]
- The SVG DOM requires support for relevant aspects of the DOM2 event model [DOM2-EVENTS]. (For the specific [DOM2-EVENTS] features that are required, see Relationship with DOM2 event model.)
- The traversal [ DOM2-TRAV] and range [ DOM2-RANGE] features from DOM2 are optional features within the SVG DOM.
- For implementations that support CSS, the SVG DOM requires complete support for the DOM2 style sheets [DOM2-SHEETS] and relevant aspects of the Document Object Model CSS [DOM2-CSS]. (For the specific [DOM2-CSS] features that are supported, see Relationship with DOM2 CSS object model.)

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.

## B.2 Naming Conventions

The SVG DOM follows similar naming conventions to the Document Object Model HTML [ DOM1-HTML].

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.3 Interface SVGException

Exception SVGException

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

  IDL Definition

        exception SVGException {
          unsigned short   code;
        };

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

## B.4 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 [DOM2-CORE] 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.0". For features that correspond to other languages, refer to the relevant other specifications to determine the appropriate version number for the given feature.

## B.5 Relationship with DOM2 events

The SVG DOM supports the following interfaces and event types from [DOM2-EVENTS]:

- The SVG DOM supports all of the interfaces defined in [DOM2-EVENTS].
- The SVG DOM supports the following UI event types [ DOM2-UIEVENTS]:
  - DOMFocusIn
  - DOMFocusOut
  - DOMActivate
- The SVG DOM supports the following mouse event types [ DOM2-MOUSEEVENTS]:
  - 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.
- The SVG DOM supports the following mutation event types [ DOM2-MUTEVENTS]:
  - 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 SVGZoomEvent)
- The following event types are triggered due to state changes in animations. (The definitions for these events can be found in the description of Interface TimeEvent in the SMIL Animation specification.)
  - beginEvemt
  - endEvent
  - repeatEvent

Each SVG element which has at least one event attribute assigned to it in the SVG DTD supports the DOM2 event registration interfaces [ DOM2-EVREG] and can be registered as an event listener for the corresponding DOM2 event using the event registration interfaces. Thus, for example, if the SVG DTD indicates that a given element supports the "onclick" event attribute, then an event listener for the "click" event can be registered with the given element as the event target.

Implementors may view the setting of event attributes as the creation and registration of an EventListener on the EventTarget. The value of useCapture defaults to 'false'. This EventListener behaves in the same manner as any other EventListeners 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.

SVG's animation elements also support the DOM2 event registration interfaces [ DOM2-EVREG]. Event listeners for animation events (i.e., start, end or repeat) can be registered on any of the animation elements.

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 the name of 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 an Event attribute become 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 say:

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

which will pass the Event object evt into function `MyActivateHandler`.

## B.6 Relationship with DOM2 CSS object model (CSS OM)

### B.6.1 Introduction

The section describes the facilities from the Document Object Model CSS [DOM2-CSS], the CSS OM, that are part of the SVG DOM.

### B.6.2 User agents that do not support styling with CSS

User agents that do not support styling with CSS are only required to support the following interfaces from [DOM2-CSS], along with any interfaces necessary to implement the interfaces, such as CSSPrimitiveValue and CSSValueList. These interfaces are used in conjunction with the getPresentationAttribute method call on interface SVGStylable. This method must be supported on all implementations of the SVG DOM:

- Interface RGBColor
- Interface CSSValue

### B.6.3 User agents that support styling with CSS

User agents that support Styling with CSS, the SVG DOM, and aural styling [CSS2-AURAL] must support all of the interfaces defined in [DOM2-CSS] which apply to aural properties.

For visual media [ CSS2-VISUAL], the SVG DOM supports all of the required interfaces defined in [DOM2-CSS]. All of the interfaces that are optional for [DOM2-CSS] are also optional for the SVG DOM.

### B.6.4 Extended interfaces

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 getPresentationAttribute method call on interface SVGStylable.

[DOM2-CSS] defines a set of extended interfaces [ DOM2-CSS-EI] for use in conjunction with interface CSSValue. The table below specifies the type of CSSValue [ DOM2-CSSVALUE] used to represent each SVG property that applies to visual media [ CSS2-VISUAL]. The expectation is that the CSSValue returned from the getPropertyCSSValue method on the CSSStyleDeclaration interface or the getPresentationAttribute method 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 valueType 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 valueType of the CSSValue is CSS_VALUE_LIST), the derived interface is CSSValueList. For all other properties (the valueType 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:

- SVGColor
- SVGICCColor
- SVGPaint

Property Name | Representation | (Extended interfaces only) Mandatory?
'alignment-baseline' | ident |
'baseline-shift' | ident, length, percentage |
'clip' | rect, ident |
'clip-path' | uri, ident |
'clip-rule' | ident |
'color' | rgbcolor, ident |
'color-interpolation' | ident |
'color-profile' | list of strings, uri's and idents |
'color-rendering' | ident |
'cursor' | uri, ident | no
'direction' | ident |
'display' | ident |
'dominant-baseline' | ident |
'enable-background' | list of idents and numbers |
'fill' | SVGPaint | yes
'fill-opacity' | number |
'fill-rule' | ident |
'filter' | uri, ident |
'flood-color' | SVGColor | yes
'flood-opacity' | number |
'font' | null |
'font-family' | list of strings and idents |
'font-size' | ident, length, percentage |
'font-size-adjust' | number, ident |
'font-stretch' | ident |
'font-style' | ident |
'font-variant' | ident |
'font-weight' | ident |
'glyph-orientation-horizontal' | ident |
'glyph-orientation-vertical' | ident |
'image-rendering' | ident |
'kerning' | ident, length |
'letter-spacing' | ident, length |
'lighting-color' | SVGColor | yes
'marker' | null |
'marker-end' | uri, ident |
'marker-mid' | uri, ident |
'marker-start' | uri, ident |
'mask' | uri, ident |
'opacity' | number |
'overflow' | ident |
'pointer-events' | ident |
'shape-rendering' | ident |
'stop-color' | SVGColor | yes
'stop-opacity' | number |
'stroke' | SVGPaint | yes
'stroke-dasharray' | ident or list of lengths |
'stroke-dashoffset' | length |
'stroke-linecap' | ident |
'stroke-linejoin' | ident |
'stroke-miterlimit' | length |
'stroke-opacity' | number |
'stroke-width' | length |
'text-anchor' | ident |
'text-decoration' | list of ident |
'text-rendering' | ident |
'unicode-bidi' | ident |
'visibility' | ident |
'word-spacing' | length, ident |
'writing-mode' | ident |

## B.7 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.

previous next contents elements attributes properties index