SVG 1.2 - 27 October 2004
The SVG 1.2 DOM builds upon and is compatible with the Document Object Model (DOM) Level 3 Specification. In particular:
Other than those areas listed above, the SVG 1.2 DOM follows the same requirements as the SVG 1.1 DOM.
With the addition of audio and video to SVG 1.2, there is a expanded set of interfaces for media elements. Each of the interfaces for the audio, video, image and feImage elements have an attribute for accessing the media object.
There is an oversight in the SVG 1.0 DOM in that the SVGImageElement interface does not allow access to the DOM of the image it refers to (if that image is an SVG document).
To provide this functionality, SVG 1.2 adds a document attribute to the SVGMedia interface, which is the Document interface of the referenced meda, if one is available. It is unlikely that the SVG specification will describe the format for the returned Document except in the case of a referenced SVG image.
Many media streams have embedded metadata. For example, most digital cameras export images in the EXIF format that embeds information on the photograph, such as the presence of a flash, the date the picture was taken and the model of camera used. SVG 1.2 provides an interface to the referenced media metadata, if the user agent is able to access and process it.
While it would have been consistent to provide an XML-like DOM interface to the referenced media's metadata, this is difficult due to the vast range of metadata schemes across the large number of media formats. Instead, SVG 1.2 provides attribute access to the most common metadata, such as the width and height of visual media, and the duration of timed media. For other properties, there is method for string-based lookup.
The SVG Media interfaces are described below:
interface SVGMedia {
readonly dom::Document document;
// we can have a simple metadata access this way:
DOMString getMetadata( in DOMString name );
};
interface SVGVisualMedia : SVGMedia {
// width and height in pixels (or natural width and height for vector fomats)
readonly unsigned float width;
readonly unsigned float height;
};
interface SVGImage : SVGVisualMedia {
// Defined for binary (pixel-based) images only
unsigned SVGColor getPixel( in unsigned long x, in unsigned long y );
};
interface SVGVideo : SVGVisualMedia {
readonly unsigned float duration;
};
interface SVGAudibleMedia : SVGMedia {
readonly unsigned float duration;
};
interface SVGAudio : SVGAudibleMedia {
// empty
};
Note that the getPixel() method on SVGImage may return invalid data in the cases where the image has not yet been loaded.
The above interfaces are accessed from each of the image, feImage, video and audio interfaces as shown below:
interface SVGImageElement {
....
readonly SVGImage image;
....
};
interface SVGFeImageElement {
....
readonly SVGImage image;
....
};
interface SVGVideoElement {
....
readonly SVGVideo video;
....
};
interface SVGAudiolement {
....
readonly SVGAudio audio;
....
};
While it is possible to convert client space coordinates, such as from a pointer event, to user coordinates using the SVG DOM, SVG 1.2 adds a more convenient way to process the conversion.
Below is the new method to be added to the SVGLocatable interface.
interface SVGLocatable {
// ...
// converts (clientXArg, clientYArg) coordinates into the
// current element's user space
SVGPoint convertClientXY(in long clientXArg, in long clientYArg)
}
When an event listener is attached to an element, that listener receives all matching events dispatched by the element. In many cases the listener only requires events that match certain criteria (e.g. a particular attribute name for DOM mutation events or only events in the bubbling phase).
The SVGEventFilter interface is an event listener and event target that filters some events, allowing the script or user agent to only process what is necessary.
interface SVGEventFilter : events::EventTarget, events::EventListener
{
// value for phase and button that prevents filtering
const unsigned short DONT_FILTER = 0xFFFF;
attribute unsigned short phase;
attribute EventTarget target; // null does not filter out anything
attribute unsigned short button; // for mouse events
// for mouse motion events, false does not filter out anything
attribute boolean dragOnly;
// for mutation events, null does not filter out anything
attribute DOMString attrLocalName;
// for mutation events, active only when attrLocalName is non-null
attribute DOMString attrNamespace;
};
SVGEventFilters are created using the SVGGlobal interface.
The default state of the created filter does not filter any events. The user must set the properties in order to filter.
SVGEventFilter is an event listener and is also an event target, so that other event listeners can be registered with it. It matches the event it receives against the set of criteria that are expressed as properties and either passes that event object to all of its own event listeners if it finds a match or ignores the event if it does not find a match.
SVG 1.2 updates the definition of the getScreenCTM() method.
Returns the transformation matrix from current user units (i.e., after application of the transform attribute, if any) to the screen coordinate system - the coordinate system used by screenX/Y of the MouseEvent interface.
SVG 1.2 adds the method getClientCTM() to the SVGLocatable interface.
Returns the transformation matrix from current user units (i.e., after application of the transform attribute, if any) to the client coordinate system - the coordinate system used by clientX/Y of the MouseEvent interface.
Many devices today have a rotational input method, such as the wheel on a mouse or the "jog dial" of a phone or PDA.
The "wheel" event is triggered when the user rotates the rotational input device. This event may only be registered on the root-most svg element.
interface WheelEvent : UIEvent {
readonly attribute int wheelDelta;
}
Indicates the number of "clicks" the wheel has been rotated. A positive value indicates that the wheel has been rotated away from the user (or in a right-hand manner on horizontally aligned devices) and a negative value indicates that the wheel has been rotated towards the user (or in a left-hand manner on horizontally aligned devices).
A "click" is defined to be a unit of rotation. On some devices this is a finite physical step. On devices with smooth rotation, a "click" becomes the smallest measurable amount of rotation.
In SVG 1.2, the SVGLocatable interface is extended with two new methods:
interface SVGLocatable {
...
SVGRect getResultBBox();
SVGRect getRegionBBox();
...
};
Returns the bounding box of the object, taking into account the geometry and geometry-based drawing operations (stroke, clip, markers, vectoreffects, markers with stroke)
Returns the bounding box of the object, taking into account all geometry and rendering operations (including filters and masks using regions).
The svg:ShapeChange event is fired when the raw geometry of an object is changed. Only basic shapes and paths fire this event. This does not take into account markers, masks, clipping or filters but focuses only on core geometry attributes of a given element. However, animations do trigger shape change events. The event target is the element (basic shapes or path) that has had its shape changed.
interface svg:ShapeChange : Event { }
The svg:RenderedBBoxChange event is fired when the bounding box of an element's rendered output is modified. This takes into account all SVG features that impact on the rendering of an object: clipping, masking, vector-effects, stroking, filling, filters, markers, the display property and animation. The target of the event is the element on which the event listener has been registered.
interface svg:RenderedBBoxChange : Event {
readonly attribute SVGRect boundingBox;
};
The new bounding box of rendered content for the target.