The following sections describe the key features and constraints
within the SVG Tiny 1.2 DOM.
Note: Like all other W3C DOM definitions, the SVG
Tiny 1.2 DOM is scripting language independent. Although this
appendix only contain ECMAScript and Java examples, the SVG Tiny
1.2 DOM is compatible with other scripting languages.
A.2.1 Document Access
All proposals assume that a
Document object is present and is the root
for accessing other features. The way the Document object becomes
available depends on the usage context. For example, for code bound
to an SVG document through a <handler> element, the Document
would be passed to the corresponding XMLEventHandler
implementation's init method.
Example:
<svg xmlns:ev="http://www.w3.org/2001/xml-events">
<rect id="myRect" x="10" y="20" width="200" height="300" fill="red"/>
<ev:listener ev:event="click" ev:observer="myRect"
ev:handler="#myClickHandler" />
<!-- handler would be a new SVG element -->
<handler id="myClickHandler"
type="application/java"
xml:base="http://fooCompany.com/myJar.jar"
xlink:href="#com.fooCompany.MyXMLEventHandler"/>
<param name="offset" value="10" />
</svg>
with
MyXMLEventHandler
being:
package com.fooCompany;
import tbd.XMLEventHandler;
import org.w3c.dom.Document;
import org.w3c.dom.svg.SVGElement;
import org.w3c.dom.svg.SVGTraitAccessor;
import org.w3c.dom.events.Event;
public class MyXMLEventHandler implements XMLEventHandler {
Document document;
SVGTraitAccessor widthTraitAccessor;
public void init(Document doc, Element handlerElement) {
document = doc;
SVGElement root = (SVGElement)document.getDocumentElement();
widthTraitAccessor = root.getTraitAccessor("width");
// ...
}
public void handleEvent(Event event) {
SVGElement myRect =
(SVGElement)document.getElementById("myRect");
float width = myRect.getTraitAsFloat(widthTraitAccessor);
myRect.setTraitAsFloat(widthTraitAccessor, width + 10);
}
}
In the remainder of this document, the variable
'document' is assumed to be an
instance of the
Document interface.
A.2.2 Tree Navigation
Tree navigation is the ability to access
individual SVG
Elements in a document tree.
SVG Tiny 1.2 DOM gives access to individual elements by identifier.
It also allows some navigation of the document tree thanks to the
Node's interface. From a
Node, it is possible to access its
parent
Node and to the
owner
Document node:
Element myRect = document.getElementById("myRect");
Node myRectParent = myRect.getParentNode();
Document doc = myRect.getOwnerDocument();
SVG Tiny 1.2 DOM also gives access to the
Document's root element:
Element svgRoot = document.documentElement();
A.2.3 Element Creation
SVG Tiny 1.2 DOM allows the creation of new
Elements:
Element myRect = document.createElementNS(svgNS, "rect");
The type of elements which can be created through the
createElementNS method is restricted to:
- The SVG namespace.
- The following elements: <rect>, <circle>,
<ellipse>, <line>, <polyline>, <polygon>,
<path>, <text>, <image> <anchor> and
<use>
A.2.4 Element Addition
Node Addition is the ability to add new
elements to a document tree.
SVG Tiny 1.2 DOM allows addition and insertion and insertion of a
Node:
// Create a new <rect> element
Element myRect
= document.createElementNS(svgNS, "rect");
// Set the various <rect> properties before appending
...
// Add element to the root of the document
Element svgRoot = document.documentElement();
svgRoot.appendChild(myRect);
// Create a new <ellipse> element
Element myEllipse
= document.createElementNS(svgNS, "ellipse");
// Set the various <ellipse> properties before insertion
...
// Insert the ellipse before the rectangle
svgRoot.insertBefore(myEllipse, myRect);
The types of nodes which can be inserted into the
Document
is limited to the same list specified in the
Element Creation section.
A.2.5 Element Removal
Node removal is the ability to remove an
element from a document tree.
SVG Tiny 1.2 DOM allows the removal of
Nodes:
Element myRect = ...; // See Element creation
Element myGroup = document.getElementById("myGroup");
myGroup.appendChild(myRect);
....
myGroup.removeChild(myRect);
However, the API limits the removal of nodes to nodes which were
added to the document tree by a prior call to
insertBefore or
appendChild.
A.2.6 Attribute Access
The following write-up describes the use of trait accessor to
achieve typed access to attribute values, property values, and
animated values. Trait accessors is the preferred approach within
the SVG working group; however, it is important to note that three
approaches have been considered, with trait accessors as one of the
three.
- Object/traits approach (The preferred approach within SVG
working group. It requires that scripts acquire trait accessors
before using them, but has the benefits that the approach scales to
Basic and Full, scales to multiname documents, fits in well with
RCC/XBL, promotes security (versus ENUMs), promotes small footprint
implementations, and allows for performance optimization via
implementation-private data within object.):
- float width = MyRect.getTraitAsFloat(widthTraitAccessor);
- width += 10;
- MyRect.setTraitAsFloat(widthTraitAccessor, width);
- ENUM approach (An alternate approach. Hardcoded enums have
multiple problems, such as what happens with mixed namespace
documents and custom elements/attributes, and security risks by
possibility of indexing off of end of arrays.):
- float width = MyRect.getTraitAsFloat(SVGTraits.WIDTH);
- width += 10;
- MyRect.setTraitAsFloat(SVGTraits.WIDTH, width);
- String approach (An alternate approach. Simplest to use, but
string lookups are required with each call.):
- float width = MyRect.getTraitAsFloat("width");
- width += 10;
- MyRect.setTraitAsFloat("width", width);
Accessing attributes in the SVG Tiny 1.2 DOM is handled by the use
of traits. A trait is a potentially animatable parameter associated
with an element. Trait is the typed value (e.g., a number, not just
a string) that gets assigned through an XML attribute, CSS property
or a SMIL animation. Previously, there was no uniform way to access
the traits in SVG DOM or track their mutation. Also, the older APIs
for typed access to trait values suffer from needless temporary
object creation and require too many steps to get to the desired
value. The new trait interfaces in SVG 1.2 address these problems
and are designed to meet the lightweight implementation
requirements of highly constrained mobile devices.
To access a trait, one first need to acquire a trait
accessor. A trait accessor is a lightweight object that is
associated with a given trait within a given namespace (or possibly
no namespace, in the case of attributes or properties which have no
namespace prefix). Trait accessors are element-independent; thus, a
trait accessor for the 'width' trait with no namespace
identification can be used to access to the 'width' attribute on
multiple different element types; thus, a trait accessor for
'width' can access the 'width' attribute on <svg>,
<image>, <rect> and several other elements in the SVG
language.
To acquire a trait accessor, call either
getTraitAccessor()
or
getTraitAccessorNS()
, passing in the name of the
trait. For example, to acquire a trait accessor for the 'width'
attribute on any element, you might use the following call to
getTraitAccessor()
:
SVGTraitAccessor widthTraitAccessor = RootSVGElement.getTraitAccessor("width");
Alternatively, you can also use
getTraitAccessorNS()
. This example shows how you would
acquire a trait accessor to the 'href' attribute in the XLink
namespace:
SVGTraitAccessor xlinkHrefTraitAccessor = RootSVGElement.getTraitAccessorNS
("http://www.w3.org/1999/xlink", "href");
The following ECMAScript example shows how a trait accessor for
the 'width' attribute on a <rect> element can be used to
change the width of two rectangles:
// This logic might be within the initialization logic
widthTraitAccessor = RootSVGElement.getTraitAccessor("width");
// This logic might be within an event handler
var width;
float width = MyRect1.getTraitAsFloat(widthTraitAccessor);
width += 10;
MyRect1.setTraitAsFloat(widthTraitAccessor, width);
float width = MyRect2.getTraitAsFloat(widthTraitAccessor);
width += 20;
MyRect2.setTraitAsFloat(widthTraitAccessor, width);
The following description of <traitDef> is in
this appendix only temporarily. It should be replaced by a link to
the definition of <traitDef> within the main
specification.
Note that the data types of all attributes and properties
defined in the SVG specification are known to the user agent.
However, custom elements and custom traits (attribute or property)
are unknown to the user agent, so the user agent doesn't know the
data types on the traits. SVG 1.2 adds the <traitDef> element
to register the data type of a particular trait. For example, to
register an attribute named 'measurement' as being of type
'SVGLength', you do the following:
<traitDef name="measurement" valueType="SVGLength"/>
A.2.7 Text Node Access
In the SVG 1.2 Tiny DOM, text node access is
only available via the DOM3 'textContent' attribute on the Node interface.
A.2.8
Event Listener Registration and Removal
Event Listener Registration and Removal is
the ability to add and remove new event listeners from a
Document.
SVG Tiny 1.2 DOM allows adding and removing
EventListeners:
class MyEventListener implements EventListener {
public void handleEvent(Event evt) {
// Do whatever is needed here
}
}
...
EventListener l = new MyEventListener();
// SVGElement implements EventTarget. All elements in the
// SVG namespace are SVGElement implementations.
SVGElement myRect = (SVGElement)document.getElementById("myRect");
// Listen to click events during the capture phase
myRect.addEventListener("click", l, true);
// Listen to mouseover events, during the buble phase
myRect.addEventListener("mouseover", l, false);
....
// Remove the click listener
myRect.removeEventListener("click", l, true);
Refer to the
DOM Events Level 2 specification or the
XML Events specification
introduction for an explanation of the SVG event flow and the
meaning of event targets, event current target, bubble and
capture.
A.2.9 Animation
SVG Tiny 1.2 DOM allows code to start or end
animation elements.
AnimationElement animateColor
= (AnimationElement) document.getElementById("myAnimation");
animateColor.beginElement();
A.3 Interfaces from Core DOM
Interface Node
The Node
interface is the interface for all XML
tree model content. This interface is a subset of the
Node
interface defined in the DOM Core
Level 2 specification.
IDL Definition
-
interface Node {
const unsigned short ELEMENT_NODE = 1;
const unsigned short DOCUMENT_NODE = 9;
// Introduced in DOM Level 3:
attribute DOMString textContent;
// raises(DOMException) on setting
Node appendChild ( in Node newChild )
raises( DOMException);
readonly attribute unsigned short nodeType;
readonly attribute Document ownerDocument;
readonly attribute Node parentNode;
Node insertBefore ( in Node newChild, in Node refChild )
raises( DOMException);
Node removeChild ( in Node oldChild )
raises( DOMException);
};
- Defined constants
-
DOCUMENT_NODE |
|
The node is a Document |
ELEMENT_NODE |
|
The node is an Element |
- Attributes (not yet completed)
- Methods
-
- appendChild
- Adds
newChild
to the end of the children list for
this node.
- Parameters
-
in Node
newChild |
|
The new Node to add. |
- Return Value
-
Node |
|
the newly added node |
- Exceptions
-
DOMException |
|
If the operation is not allowed (e.g., if the
newChild node type is incompatible with this node) or if addition
of the given Node type is not supported by the implementation. |
- insertBefore
- Inserts
newChild
before refChild
.
- Parameters
-
in Node
newChild |
|
The Node to insert. |
in Node
refChild |
|
The Node before which newChild is
inserted |
- Return Value
-
Node |
|
the newly inserted node |
- Exceptions
-
DOMException |
|
If the operation is not allowed or not
supported. |
- removeChild
- Removes a child node.
- Parameters
-
in Node
oldChild |
|
The Node to remove. |
- Return Value
-
- Exceptions
-
DOMException |
|
See the DOM Level 2 specification. |
- getOwnerDocument
- Get the document associated with this node.
- No Parameters
- Return Value
-
Document |
|
the Document associated with this node. |
- No Exceptions
- getParentNode
- Get the parent of this node.
- No Parameters
- Return Value
-
- No Exceptions
- getNodeType
- Get the type of this node.
- No Parameters
- Return Value
-
unsigned short |
|
the Node 's type, one of the XXX_NODE
constants. |
- No Exceptions
Interface Document
The Document
interface is the interface for an XML
Document
model. This interface is a subset of the
Document
interface defined in the DOM Core
Level 2 specification. Note that the getFirstChild
method returns the root of the document.
IDL Definition
-
interface Document : Node {
Element createElementNS ( in DOMString namespaceURI, in DOMString qualifiedName )
raises( DOMException);
readonly attribute Element documentElement;
Element getElementById(in DOMString elementId);
};
- No Defined constants
- Defined attributes
- (Incomplete)
- Methods
-
- createElementNS
- Create a new element.
- Parameters
-
in DOMString namespaceURI |
|
The namespace uri for the newly created element. |
in DOMString qualifiedName |
|
The qualified name for the newly created element. |
- Return Value
-
Element |
|
The newly created element |
- Exceptions
-
DOMException |
|
See DOM Level 2 specification. In addition, a
DOMException (NOT_SUPPORTED_ERR) is thrown if the type of element
is not supported by the implementation. |
- getElementById
- Get an element with a given id.
- Parameters
-
in DOMString elementId |
|
The unique id of the retrieved element. |
- Return Value
-
Element |
|
The matching element or null if none. |
- No Exceptions
Interface Element
The Element
interface represents an XML element in
a Document
. This interface is a subset of the
Element
interface defined in the DOM Core
Level 2 specification. Note that in SVG Tiny 1.2 DOM
implementations which support events, Element
implementations also implement the EventTarget
interface. Refer to the DOM
Level 2 Events for details.
IDL Definition
-
interface Element : Node {
DOMString getAttribute ( in DOMString name );
DOMString getAttributeNS ( in DOMString namespaceURI, in DOMString qualifiedName );
void removeAttribute ( in DOMString name );
void removeAttributeNS ( in DOMString namespaceURI, in DOMString qualifiedName );
void setAttribute ( in DOMString name, in DOMString value )
raises( DOMException);
void setAttributeNS ( in DOMString namespaceURI,
in DOMString qualifiedName, in DOMString value )
raises( DOMException);
};
- No Defined constants
- Methods
-
- getAttribute
- Convenience method for
getAttributeNS(null, name)
.
- Parameters
-
in DOMString name |
|
The name of the attribute to retrieve. |
- Return Value
-
DOMString |
|
The attribute value. |
- No Exceptions
- getAttributeNS
- Get the value of an attribute.
- Parameters
-
in DOMString namespaceURI |
|
The namespace URI of the retrieved attribute. |
in DOMString qualifiedName |
|
The qualified name of the attribute to set on the element. |
- Return Value
-
DOMString |
|
The attribute value. |
- No Exceptions
- removeAttribute
- Convenience method for
removeAttributeNS(null,
name)
.
- Parameters
-
in DOMString name |
|
The name of the attribute to remove. |
- No Return Value
- No Exceptions
- removeAttributeNS
- Removes an attribute.
- Parameters
-
in DOMString namespaceURI |
|
The namespace URI of the attribute to remove. |
in DOMString qualifiedName |
|
The qualified name of the attribute to remove. |
- No Return Value
- No Exceptions
- setAttribute
- Convenience method for
setAttributeNS(null, name,
value)
.
- Parameters
-
in DOMString name |
|
The name of the attribute to set on the element. |
in DOMString value |
|
The new attribute value. |
- No Return Value
- Exceptions
-
DOMException |
|
If the attribute value cannot be set. |
- setAttributeNS
- Set an attribute with a given value.
- Parameters
-
in DOMString namespaceURI |
|
The namespace URI of the retrieved attribute. |
in DOMString qualifiedName |
|
The qualified name of the attribute to set on the element. |
in DOMString value |
|
The new attribute value. |
- No Return Value
- Exceptions
-
DOMException |
|
If the attribute value cannot be set. |
Interface DOMException
The DOMException
class defines a subset of the
error codes defined in the DOM Core
Level 2 specification.
IDL Definition
-
exception DOMException {
unsigned short code;
};
// DOMExceptionCode
const unsigned short WRONG_DOCUMENT_ERR = 4;
const unsigned short NO_MODIFICATION_ALLOWED_ERR = 7;
const unsigned short NOT_FOUND_ERR = 8;
const unsigned short NOT_SUPPORTED_ERR = 9;
const unsigned short INVALID_MODIFICATION_ERR = 13;
const unsigned short INVALID_ACCESS_ERR = 15;
- Defined constants
-
WRONG_DOCUMENT_ERR |
|
If a node is used in a different document than the
one that created it (that doesn't support it) |
NO_MODIFICATION_ALLOWED_ERR |
|
If an attempt is made to modify an object where
modifications are not allowed. |
NOT_FOUND_ERR |
|
If an attempt is made to reference a node in a
context where it does not exist . |
NOT_SUPPORTED_ERR |
|
If the implementation does not support the
requested type of object or operation. |
INVALID_MODIFICATION_ERR |
|
If an attempt is made to modify the type of the
underlying object. |
INVALID_ACCESS_ERR |
|
If a parameter or an operation is not supported by
the underlying object. |
A.4 Interfaces from DOM Events
Interface Event
Provides information about an event and its propagation. The
interface allows listeners to stop the propagation. This interface
is a subset of the Event
interface defined in the
DOM
Level 2 Events specification. Please refer to that
specification for details on what the different methods and members
mean.
IDL Definition
-
interface Event {
const unsigned short AT_TARGET = 0
const unsigned short BUBBLING_PHASE = 1;
const unsigned short CAPTURING_PHASE = 2;
readonly attribute EventTarget currentTarget;
readonly attribute unsigned short eventPhase;
readonly attribute EventTarget target;
readonly attribute type;
void stopPropagation ( );
};
- Defined constants
-
AT_TARGET |
|
The event is currently being evaluated at the
target EventTarget . |
BUBBLING_PHASE |
|
The current event phase is the bubbling
phase. |
CAPTURING_PHASE |
|
The current event phase is the capturing
phase. |
- Defined attributes
- (Incomplete)
- Methods
-
- stopPropagation
- Prevents further propagation of the event. The event will still
be dispatched to all listeners on the current target before the
event flow stops.
- No Parameters
- No Return Value
- No Exceptions
Interface EventListener
Interface used to receive Event
s from an
EventTarget
This interface is a subset of the
EventListener
interface defined in the DOM
Level 2 Events specification. Please refer to that
specification for details on what the different methods and members
mean.
IDL Definition
-
interface EventListener {
void handleEvent ( in Event evt);
};
- No Defined constants
- Methods
-
- handleEvent
- Handle event.
- Parameters
-
in Event evt |
|
Contains contextual information about the
event. |
- No Return Value
- No Exceptions
Interface EventTarget
The interface for DOM nodes which can receive and dispatch
Event
s to EventListener
s. This interface
is a subset of the EventTarget
interface defined in
the DOM
Level 2 Events specification. Please refer to that
specification for details on what the different methods and members
mean.
IDL Definition
-
interface EventTarget {
void addEventListener ( in DOMString type, in EventListener listener,
in boolean useCapture );
void removeEventListener ( in DOMString type, in EventListener listener,
in boolean useCapture );
};
- No Defined constants
- Methods
-
- addEventListener
- Adds a new listener to this target, for the specified event
type, during the desired phase.
- Parameters
-
in DOMString type |
|
The type of event to listen to. |
in EventListener listener |
|
Will be notified when an event of the desired type
happens on this target or one of its descendant. |
in boolean useCapture |
|
If true, the listener will be called during the
event flow capture phase. Otherwise, the listener will be called
during the bubble phase. If the event's target is this target, then
the listener will be called during the 'at target' phase of event
flow. |
- No Return Value
- No Exceptions
- removeEventListener
- Removes a listener previously added with an
addEventListener
call.
- Parameters
-
in DOMString type |
|
The type of event that was listened to. |
in EventListener listener |
|
The listener that was previously registered. |
in boolean useCapture |
|
If true, the listener was listening to events in
the capture phase of event flow. |
- No Return Value
- No Exceptions
Supported events
The following events are supported:
- DOMActivate
- DOMFocusIn
- DOMFocusOut
- (Text events will be added later)
A.5 Interfaces for SVG DOM
Interface SVGDocument
SVGDocument
provides an API to access SVG specific
features, such as setting the viewport size
IDL Definition
-
interface SVGDocument : Document {
readonly attribute SVGSVGElement rootElement;
};
- No Defined constants
- Attributes
-
- readonly SVGSVGElement rootElement
- The root 'svg' element in the
document hierarchy.
- No defined methods
Interface SVGTraitAccessor
SVGTraitAccessor
is an object to access trait
values. It serves as a key to look up the value of the trait stored
on the element. In SVGT trait accessor is an opaque object with no
interface attached (so it can be implemented as either
java.lang.String or java.lang.Integer). Trait accessors are not
element-specific, that is trait accessor that can access "x" trait
will work for all elements that have suh trait (e.g. rect, svg,
text, etc.).
IDL Definition
-
interface SVGTraitAccessor {
// trait accessor can be an opaque object instead in SVGT
readonly attribute DOMString name;
readonly attribute DOMString namespaceURI;
};
- No Defined constants
- Attributes (not yet completed)
- Methods (not yet completed)
Interface SVGTraitMutationEvent
SVGTraitMutationEvent
is raised whenever a trait
value changes.
IDL Definition
-
interface SVGTraitMutationEvent : Event {
// event that is sent to trait mutation listeners
// name = "SVGTraitChanged"
SVGTraitAccessor trait;
};
- No Defined constants
- Attributes (not yet completed)
- Methods (not yet completed)
Interface ElementWithTraits
ElementWithTraits
is a base interface that allows
typed access to the XML attributes and CSS properties on all
elements in the document. Interface ElementWithTraits is available
on all elements, whether or not they are in the SVG namespace.
On open issue is whether getTraitAccessor() and
getTraitAccessorNS() should be moved from interface
ElementWithTraits to SVGSVGElement.
IDL Definition
-
interface ElementWithTraits {
boolean traitIsSpecified( in SVGTraitAccessor traitAccessor ) raises SVGException;
DOMString getTraitAsString( in SVGTraitAccessor traitAccessor )
raises SVGException;
DOMString getTraitAsStringAnimated( in SVGTraitAccessor traitAccessor )
raises SVGException;
void setTraitAsString( in SVGTraitAccessor traitAccessor, DOMString newValue )
raises SVGException;
float getTraitAsFloat( in SVGTraitAccessor traitAccessor )
raises SVGException;
float getTraitAsFloatAnimated( in SVGTraitAccessor traitAccessor )
raises SVGException;
void setTraitAsFloat( in SVGTraitAccessor traitAccessor, float newValue )
raises SVGException;
long getTraitAsInteger( in SVGTraitAccessor traitAccessor )
raises SVGException;
long getTraitAsIntegerAnimated( in SVGTraitAccessor traitAccessor )
raises SVGException;
void setTraitAsInteger( in SVGTraitAccessor traitAccessor, long newValue )
raises SVGException;
SVGColor getTraitAsSVGColor( in SVGTraitAccessor traitAccessor )
raises SVGException;
SVGColor getTraitAsSVGColorAnimated( in SVGTraitAccessor traitAccessor )
raises SVGException;
void setTraitAsSVGColor( in SVGTraitAccessor traitAccessor, SVGColor newValue )
raises SVGException;
SVGPaint getTraitAsSVGPaint( in SVGTraitAccessor traitAccessor )
raises SVGException;
SVGPaint getTraitAsSVGPaintAnimated( in SVGTraitAccessor traitAccessor )
raises SVGException;
void setTraitAsSVGPaint( in SVGTraitAccessor traitAccessor, SVGPaint newValue )
raises SVGException;
SVGRect getTraitAsSVGRect( in SVGTraitAccessor traitAccessor )
raises SVGException;
SVGRect getTraitAsSVGRectAnimated( in SVGTraitAccessor traitAccessor )
raises SVGException;
void setTraitAsSVGRect( in SVGTraitAccessor traitAccessor, SVGRect newValue )
raises SVGException;
SVGMatrix getTraitAsSVGMatrix( in SVGTraitAccessor traitAccessor )
raises SVGException;
SVGMatrix getTraitAsSVGMatrixAnimated( in SVGTraitAccessor traitAccessor )
raises SVGException;
void setTraitAsSVGMatrix( in SVGTraitAccessor traitAccessor, SVGMatrix newValue )
raises SVGException;
SVGPoint getTraitAsSVGPoint( in SVGTraitAccessor traitAccessor )
raises SVGException;
SVGPoint getTraitAsSVGPointAnimated( in SVGTraitAccessor traitAccessor )
raises SVGException;
void setTraitAsSVGPoint( in SVGTraitAccessor traitAccessor, SVGPoint newValue )
raises SVGException;
void removeTrait( in SVGTraitAccessor traitAccessor )
raises SVGException;
SVGTraitAccessor getTraitAccessor( in DOMString name )
raises SVGException;
SVGTraitAccessor getTraitAccessorNS( in DOMString namespace, in DOMString name )
raises SVGException;
void addTraitMutationListener( in SVGTraitAccessor traitAccessor,
EventListener listener )
raises SVGException;
void removeTraitMutationListener ( in SVGTraitAccessor traitAccessor,
EventListener listener )
raises SVGException;
};
- No Defined constants
- Attributes (not yet completed)
- Methods (not yet completed)
Interface SVGElement
SVGElement
is the base interface used by all
elements in the SVG namespace.
IDL Definition
-
In SVG 1.1, Events::EventTarget are only on objects
that might indeed receive events. Thus, Events::EventTarget is on
SVGCircleElement, but not on SVGColorProfileElement. With the SVG
Tiny 1.2 DOM, we want to minimize the number of interfaces. Thus,
we are proposing to have SVGElement implement Events::EventTarget
since all things that derive from SVGElement in the SVG Tiny 1.2
DOM can actually receive events. However, because SVG Basic/Full
need to be upwardly compatible, this means all elements in the SVG
DOM will implement Events::EventTarget, including
SVGColorProfileElement. This seems OK because everything
conceivably can receive attribute modified mutation events.
interface SVGElement : Element, Events::EventTarget, ElementWithTraits {
attribute DOMString id;
// raises DOMException on setting
SVGRect getBBox ( );
};
- No Defined constants
- Attributes (not yet completed)
- Methods (not yet completed)
Interface SVGSVGElement
SVGSVGElement
provides an API to access APIs
corresponding to the <svg> element
IDL Definition
-
interface SVGSVGElement : SVGElement {
readonly attribute SVGRect viewport;
attribute float currentScale;
// raises DOMException on setting
readonly attribute SVGPoint currentTranslate;
unsigned long suspendRedraw ( in unsigned long max_wait_milliseconds );
void unsuspendRedraw ( in unsigned long suspend_handle_id )
raises( DOMException );
void pauseAnimations ( );
void unpauseAnimations ( );
boolean animationsPaused ( );
float getCurrentTime ( );
void setCurrentTime ( in float seconds);
boolean checkIntersection ( in SVGElement element, in SVGRect rect );
};
- No Defined constants
- Attributes
-
- readonly SVGRect 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. The position and size values are unitless values in the
coordinate system of the parent element. If no parent element
exists (i.e., 'svg' element
represents the root of the document tree), 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 CSS2 specification.) If the parent
element does not have a coordinate system, then the user agent
should provide reasonable default values for this attribute.
The object itself and its contents are both readonly.
- float currentScale
- This attribute indicates the current scale factor relative to
the initial view to take into account user magnification and
panning operations, as described under Magnification and panning.
DOM attributes currentScale and
currentTranslate are equivalent
to the 2x3 matrix [a b c d e f] = [currentScale 0 0 currentScale
currentTranslate.x currentTranslate.y]. If "magnification" is
enabled (i.e., zoomAndPan="magnify"), then the effect is as if an
extra transformation were placed at the outermost level on the SVG
document fragment (i.e., outside the outermost 'svg' element).
- Exceptions on setting
-
DOMException |
|
NO_MODIFICATION_ALLOWED_ERR: Raised on an attempt to change
the value of a readonly attribute.
|
- readonly SVGPoint currentTranslate
- The corresponding translation factor that takes into account
user "magnification".
- Methods
-
- suspendRedraw
- Takes a time-out value which indicates that redraw shall not
occur until: (a) the corresponding
unsuspendRedraw(suspend_handle_id) call has been made,
(b) an unsuspendRedrawAll() call has been made, or (c)
its timer has timed out. In environments that do not support
interactivity (e.g., print media), then redraw shall not be
suspended. suspend_handle_id =
suspendRedraw(max_wait_milliseconds) and
unsuspendRedraw(suspend_handle_id) must be packaged as
balanced pairs. When you want to suspend redraw actions as a
collection of SVG DOM changes occur, then precede the changes to
the SVG DOM with a method call similar to suspend_handle_id =
suspendRedraw(max_wait_milliseconds) and follow the changes
with a method call similar to
unsuspendRedraw(suspend_handle_id). Note that multiple
suspendRedraw calls can be used at once and that each
such method call is treated independently of the other
suspendRedraw method calls.
- Parameters
-
in unsigned
long max_wait_milliseconds |
|
The amount of time in milliseconds to hold off before redrawing
the device. Values greater than 60 seconds will be truncated down
to 60 seconds. |
- Return value
-
unsigned
long |
|
A number which acts as a unique identifier for the given
suspendRedraw() call. This value must be passed as the
parameter to the corresponding unsuspendRedraw()
method call. |
- No Exceptions
- unsuspendRedraw
- Cancels a specified suspendRedraw() by providing a
unique suspend_handle_id.
- Parameters
-
in unsigned
long suspend_handle_id |
|
A number which acts as a unique identifier for the desired
suspendRedraw() call. The number supplied must be a
value returned from a previous call to
suspendRedraw() |
- No Return Value
- Exceptions
-
DOMException |
|
This method will raise a DOMException with value
NOT_FOUND_ERR if an invalid value (i.e., no such
suspend_handle_id is active) for
suspend_handle_id is provided.
|
- pauseAnimations
- Suspends (i.e., pauses) all currently running animations that
are defined within the SVG document fragment corresponding to this
'svg' element, causing the
animation clock corresponding to this document fragment to stand
still until it is unpaused.
- No Parameters
- No Return Value
- No Exceptions
- unpauseAnimations
- Unsuspends (i.e., unpauses) currently running animations that
are defined within the SVG document fragment, causing the animation
clock to continue from the time at which it was suspended.
- No Parameters
- No Return Value
- No Exceptions
- animationsPaused
- Returns true if this SVG document fragment is in a paused
state.
- No Parameters
- Return value
-
boolean |
|
Boolean indicating whether this SVG document fragment is in a
paused state. |
- No Exceptions
- getCurrentTime
- Returns the current time in seconds relative to the start time
for the current SVG document fragment.
- No Parameters
- Return value
-
float |
|
The current time in seconds. |
- No Exceptions
- setCurrentTime
- Adjusts the clock for this SVG document fragment, establishing
a new current time.
- Parameters
-
in float
seconds |
|
The new current time in seconds relative to the start time for
the current SVG document fragment. |
- No Return Value
- No Exceptions
- checkIntersection
- Returns true if the rendered content of the given element
intersects the supplied rectangle, honoring the 'pointer-events'
property value on each candidate graphics element.
- Parameters
-
in SVGElement element |
|
The element on which to perform the given test. |
in SVGRect
rect |
|
The test rectangle. The values are in the initial coordinate
system for the current 'svg' element. |
- Return value
-
boolean |
|
True or false, depending on whether the given element
intersects the supplied rectangle. |
- No Exceptions
Interface SVGColor
IDL Definition
-
interface SVGColor {
// These are bit fields which indicate which components of SVG's <color>
syntax
// have been specified.
const unsigned short SVG_COLORSPEC_RGB = 1;
const unsigned short SVG_COLORSPEC_CURRENTCOLOR = 32768;
readonly attribute unsigned short colorSpec;
// If "current color" is specified, then float_r, float_g, float_b, r,
g, or b hold the color value of that color.
// Setting any of float_r, float_g, float_b, r, g, or b replaces any
"current color"
// settings within a presentation attribute on the current element with
an explicit RGB color setting.
unsigned short r; // Red color component, ranging 0 to 65535.
unsigned short g; // Green color component, ranging 0 to 65535.
unsigned short b; // Blue color component, ranging 0 to 65535.
};
Interface SVGPaint
IDL Definition
-
// NOTE: It's OK for Tiny implementers to flatten SVGPaint and SVGColor
// to remove inheritance so long as it achieves the same result.
interface SVGPaint : SVGColor {
// These are bit fields which indicate which components of SVG's <paint>
syntax
// have been specified.
// Note: If SVG_PAINTSPEC_COLOR is set, then you can access the color
information
// via the facilities from SVGColor, which SVGPaint inherits.
// Given that Tiny is adding gradients, this would be required for Full,
Basic and Tiny.
const unsigned short SVG_PAINTSPEC_COLOR = 1;
const unsigned short SVG_PAINTSPEC_URI = 2;
readonly attribute unsigned short paintComponents;
// Color keywords supported by Tiny (16 total).
// This list is a strict subset of Full, and the ENUM values match exactly.
const unsigned short SVG_COLOR_BLACK = ???;
const unsigned short SVG_COLOR_SILVER = ???;
const unsigned short SVG_COLOR_GRAY = ???;
// and so on
// Given that Tiny is adding gradients, this would be required for Full,
Basic and Tiny.
readonly attribute DOMString uri;
};
Interface SVGRect
SVGRect
is the same interface as the
SVGRect
interface in the SVG 1.1 specification.
For definition see SVGRect.
Interface SVGMatrix
SVGMatrix
is a subset of the SVGMatrix
interface in the SVG 1.1 specification. It only includes the
a,b,c,d,e,f DOM attributes and the multiply(), rotate(), inverse(),
scale() and translate() methods.
For definition see SVGMatrix.
Interface SVGPoint
SVGPoint
is a subset of the SVGPoint
interface in the SVG 1.1 specification. It only includes the x,y
DOM attributes.
For definition see SVGPoint.
Interface GetSVGDocument
In the case where an SVG document is embedded by reference, such
as when an XHTML document has an 'object' element whose href (or equivalent) attribute references an SVG
document (i.e., a document whose MIME type is "image/svg+xml" and
whose root element is thus an 'svg' element), the SVG user agent is
required to implement the GetSVGDocument interface for the element
which references the SVG document (e.g., the HTML 'object' or comparable referencing
elements).
The GetSVGDocument
interface also is the appropriate interface which should be
supported on any classes that provide API access for a host
application to gain access to the SVG DOM for a particular SVG
object.
IDL Definition
-
interface GetSVGDocument {
SVGDocument getSVGDocument ( )
raises( DOMException );
};