org.w3c.dom.svg
Interface SVGElement

All Superinterfaces:

Element, EventTarget, Node

All Known Subinterfaces:

SVGAnimationElement, SVGLocatableElement, SVGSVGElement

public interface SVGElement
extends Element, EventTarget

This interface represents an SVG element in the document tree. Element's id can be set only if it does not already have an id. DOMException with error code NO_MODIFICATION_ALLOWED_ERR is raised if an attempt is made to change an existing id. Elements with non-null id can be inserted, but cannot be removed from the DOM tree (see removeChild). This interface also provides methods to traverse elements in the DOM tree.

This interface can also be used read and manipulate the value of "traits" associated with this SVGElement. Each trait corresponds to an attribute or property,which is parsed and understood by the element and in most cases animatable. Unlike attributes, each element has a well-defined set of traits and attempting to access undefined trait is an error. Also unlike attributes traits are typed and their values are normalized; for instance SVG path specification is parsed and all path commands are converted to their absolute variants, it is not possible to say through the value of the trait if a path command was absolute or relative. When getting and setting trait values, accessor of the correct type must be used or exception will be thrown.

Initial trait values come from parsing corresponding attributes. If value is not specified, but corresponing attribute (or property for environments where styling is supported) is inherited, inherited value is returned as a result of the trait query method. If it is not inherited, default value is returned. Default values are also returned in the case when there is no parent to inherit from, for ex: when you create a new element, set a trait value to 'inherit', but there is no parent for inheritance. It is important to note that the value which is returned is always a base value (i.e. before animation is applied), and this is true for both static and animated content.

Setting a trait value has the same effect as changing a corresponding attribute, but trait setters can operate on typed values. The value which is modified is always a base value. For inheritable traits the trait value can always be set to "inherit" (but querying the value will always return the actual inherited value as explained above).

There are two situations where the various trait setter methods (such as setTrait, setFloatTrait or setPathTrait methods) consider a value invalid and throw a DOMException with the INVALID_ACCESS_ERR code. The first situation is when the trait value is invalid with regards to its definition (for example, trying to set the "stroke-linejoin" trait to "foo" would cause this exception). The second situation is when the trait value is invalid with regards to animations currently applied to the trait. The value is considered invalid because it would put the animation, and therefore the document, in an error state. For example, if a element has animations on its "d" attribute, trying to change the "d" attribute to a value incompatible with the animations will cause the exception to happen.

Note that SVG traits are in the so-called element's 'per-element type partitions namespaces' (see the Namespaces in XML" specification, section A.2). Invoking setTraitNS(null, traitName) is equivalent to invoking setTrait(traitName). In particular, this means that the SVG traits are not in the SVG namespace and invoking setTraitNS(SVG namespace, traitName) is not equivalent to invoking setTrait(traitName).

Traits supported in this specification, SVG Tiny 1.1 DOM

The table below shows the list of attributes and properties that SVG Tiny DOM 1.1 implementations must support. Implementations that support multiple versions of the SVG Tiny language must allow trait access to the most extensive set and support the types supported by each trait in the most extensive set. However, content relying on traits or trait types available in future versions may not work in all conformant JSR 226 1.0 implementations. Each light gray section lists one or multiple elements for which the subsequent attributes or properties apply. Each attribute row lists the allowed getter and setter (s). The last column specifies the default values that must be used for each attribute or property.

Note: For 'REQUIRED' attributes, there are two cases:

• i) The document is in error, if this attribute was not present at the time of loading.
• ii) When using uDOM API, the specified default value (in parenthesis) must be used.

Property	Trait Getter [possible return value(s)]	Trait Setter [allowed value(s)]	Default Values
<svg>, <rect>, <circle>, <ellipse>, <line>, <path>, <g>, <image>, <text>, <a>, and <use>
color	getRGBColorTrait [SVGRGBColor]	setTrait [inherit] setRGBColorTrait [SVGRGBColor]	rgb(0,0,0)
display	getTrait [inline | none ]	setTrait [inline | none | inherit ]	"inline"
fill	getRGBColorTrait [null, SVGRGBColor]	setRGBColorTrait [SVGRGBColor] setTrait(none | currentColor | inherit)	rgb(0,0,0)
fill-rule	getTrait [nonzero | evenodd]	setTrait [nonzero | evenodd | inherit]	"nonzero"
stroke	getRGBColorTrait [null, SVGRGBColor]	setRGBColorTrait [SVGRGBColor] setTrait [none | currentColor | inherit]	"none"
stroke-dashoffset	getFloatTrait	setTrait [inherit] setFloatTrait	0.0f
stroke-linecap	getTrait [butt | round | square]	setTrait [butt | round | square | inherit]	"butt"
stroke-linejoin	getTrait [miter | round | bevel ]	setTrait [miter | round | bevel | inherit]	"miter"
stroke-miterlimit	getFloatTrait [ value >= 1]	setTrait [inherit] setFloatTrait [value >= 1]	4.0f
stroke-width	getFloatTrait [value >= 0]	setTrait [inherit] setFloatTrait [value >= 0]	1.0f
visibility	getTrait [visible | hidden]	setTrait [visible | hidden | inherit]	"visible"
<svg>, <text>, <g>, <a>, and <use>;
font-family	getTrait [single, computed font-family value]	setTrait [same syntax as font-family attribute]	User-Agent
font-size	getFloatTrait [value >= 0]	setFloatTrait [value >= 0] setTrait [inherit]	User-Agent
font-style	getTrait [normal | italic | oblique ]	setTrait [normal | italic | oblique | inherit]	"normal"
font-weight	getTrait [100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 ]	setTrait [normal | bold | bolder | lighter | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | inherit]	"normal"
text-anchor	getTrait [start | middle | end]	setTrait [start | middle | end | inherit ]	"start"
Attribute	Trait Getter	Trait Setter	Default Values
<rect>, <circle>, <ellipse>, <line>, <path>, <g>, <image>, <text>, <a>, and <use>
transform	getMatrixTrait [SVGMatrix]	setMatrixTrait [SVGMatrix]	Identity matrix (1,0,0,1,0,0)
<rect>
height	getFloatTrait [ value >= 0]	setFloatTrait [ value >= 0]	REQUIRED (0.0f)
width	getFloatTrait [ value >= 0]	setFloatTrait [ value >= 0]	REQUIRED (0.0f)
x	getFloatTrait	setFloatTrait	0.0f
y	getFloatTrait	setFloatTrait	0.0f
rx	getFloatTrait [value >= 0]	setFloatTrait [value >= 0]	0.0f
ry	getFloatTrait [value >= 0]	setFloatTrait [value >= 0]	0.0f
<circle>
cx	getFloatTrait	setFloatTrait	0.0f
cy	getFloatTrait	setFloatTrait	0.0f
r	getFloatTrait [ value >= 0]	setFloatTrait [value >= 0]	REQUIRED (0.0f)
<ellipse>
cx	getFloatTrait	setFloatTrait	0.0f
cy	getFloatTrait	setFloatTrait	0.0f
rx	getFloatTrait [value >= 0]	setFloatTrait [value >= 0]	REQUIRED (0.0f)
ry	getFloatTrait [value >= 0]	setFloatTrait [value >= 0]	REQUIRED (0.0f)
<line>
x1	getFloatTrait	setFloatTrait	0.0f
x2	getFloatTrait	setFloatTrait	0.0f
y1	getFloatTrait	setFloatTrait	0.0f
y2	getFloatTrait	setFloatTrait	0.0f
<path> (path-length is not supported)
d	getPathTrait [SVGPath]	setPathTrait [SVGPath]	REQUIRED (Empty SVGPath)
<image>
x	getFloatTrait	setFloatTrait	0.0f
y	getFloatTrait	setFloatTrait	0.0f
width	getFloatTrait [value >= 0]	setFloatTrait [value >= 0]	REQUIRED (0.0f)
height	getFloatTrait [value >= 0]	setFloatTrait [value >= 0]	REQUIRED (0.0f)
xlink:href	getTrait NS[absolute URI]	setTraitNS [non local-URI value]	REQUIRED ( "" )
<use>
x	getFloatTrait	setFloatTrait	0.0f
y	getFloatTrait	setFloatTrait	0.0f
xlink:href	getTraitNS[absolute URI]	setTraitNS	""
<a>
target	getTrait	setTrait	""
xlink:href	getTraitNS[absolute URI]	setTraitNS	""
<text> (Notes: For 'x' and 'y', it is only possible to provide floating point scalar values; an array of x or y values is not supported. 'rotate' attribute is not supported.)
x	getFloatTrait	setFloatTrait	0.0f
y	getFloatTrait	setFloatTrait	0.0f
#text	getTrait [not null]	setTrait [not null]	""
<svg>
version	getTrait	Not available (readonly)	"1.1"
baseProfile	getTrait	Not available (readonly)	"tiny"
viewBox	getRectTrait [null, SVGRect]	setRectTrait [SVGRect]	null
zoomAndPan	getTrait [disable | magnify]	setTrait [disable | magnify]	"magnify"

Method Summary

Element	getFirstElementChild() Returns the first child element node of this element.
float	getFloatTrait(java.lang.String name) Get the trait value as float.
java.lang.String	getId() Returns the Element's Id, null if no id specified.
SVGMatrix	getMatrixTrait(java.lang.String name) Returns the trait value as SVGMatrix.
Element	getNextElementSibling() Returns the next sibling element node of this element.
SVGPath	getPathTrait(java.lang.String name) Returns the trait value as SVGPath.
SVGRect	getRectTrait(java.lang.String name) Returns the trait value as SVGRect.
SVGRGBColor	getRGBColorTrait(java.lang.String name) Returns the trait value as SVGRGBColor.
java.lang.String	getTrait(java.lang.String name) Returns the trait value as String.
java.lang.String	getTraitNS(java.lang.String namespaceURI, java.lang.String name) Same as getTrait, but for namespaced traits.
void	setFloatTrait(java.lang.String name, float value) Set the trait value as float.
void	setId(java.lang.String Id) Sets the Element's id attribute.
void	setMatrixTrait(java.lang.String name, SVGMatrix matrix) Set the trait value as SVGMatrix.
void	setPathTrait(java.lang.String name, SVGPath path) Set the trait value as SVGPath.
void	setRectTrait(java.lang.String name, SVGRect rect) Set the trait value as SVGRect.
void	setRGBColorTrait(java.lang.String name, SVGRGBColor color) Set the trait value as SVGRGBColor.
void	setTrait(java.lang.String name, java.lang.String value) Set the trait value as String.
void	setTraitNS(java.lang.String namespaceURI, java.lang.String name, java.lang.String value) Same as setTrait, but for namespaced traits.

Methods inherited from interface org.w3c.dom.Node

appendChild, getLocalName, getNamespaceURI, getParentNode, insertBefore, removeChild

Methods inherited from interface org.w3c.dom.events.EventTarget

addEventListener, removeEventListener

Method Detail

setId

void setId(java.lang.String Id)
           throws DOMException

Sets the Element's id attribute.

Parameters:

Id - the value of Id to be set for this Element.

Throws:

DOMException - with error code NO_MODIFICATION_ALLOWED_ERR is raised if an attempt is made to change an existing Id.

DOMException - with error code INVALID_ACCESS_ERR is raised if the Id is not unique i.e. if this Id already exists in the document.

java.lang.NullPointerException - if Id is null.

java.lang.SecurityException - if the application does not have the necessary privilege rights to access this (SVG) content.

getId

java.lang.String getId()

Returns the Element's Id, null if no id specified.

Returns:

the Element's Id.

getFirstElementChild

Element getFirstElementChild()

Returns the first child element node of this element. null if this element has no child elements.

Returns:

the first child element node of this element.

getNextElementSibling

Element getNextElementSibling()

Returns the next sibling element node of this element. null if this element has no element sibling nodes that come after this one in the document tree.

Returns:

the next sibling element node of this element.

getTrait

java.lang.String getTrait(java.lang.String name)
                          throws DOMException

Returns the trait value as String. In SVG Tiny only certain traits can be obtained as a String value. Syntax of the returned String matches the syntax of the corresponding attribute. This element is exactly equivalent to getTraitNS with namespaceURI set to null.

Parameters:

name - the name of the trait to retrieve.

Returns:

the trait value as String for the specified name.

Throws:

DOMException - with error code NOT_SUPPORTED_ERR if the requested trait is not supported on this element or null.

DOMException - with error code TYPE_MISMATCH_ERR if requested trait's computed value cannot be converted to a String (SVG Tiny only).

java.lang.SecurityException - if the application does not have the necessary privilege rights to access this (SVG) content.

getTraitNS

java.lang.String getTraitNS(java.lang.String namespaceURI,
                            java.lang.String name)
                            throws DOMException

Same as getTrait, but for namespaced traits. Parameter name must be a non-qualified trait name, i.e. without prefix.

Parameters:

namespaceURI - the namespaceURI of the trait to retrieve.

name - the name of the trait to retrieve.

Returns:

the trait value as String for the specified name.

Throws:

DOMException - with error code NOT_SUPPORTED_ERR if the requested trait is not supported on this element or null.

DOMException - with error code TYPE_MISMATCH_ERR if requested trait's computed value cannot be converted to a String (SVG Tiny only).

java.lang.SecurityException - if the application does not have the necessary privilege rights to access this (SVG) content.

getFloatTrait

float getFloatTrait(java.lang.String name)
                    throws DOMException

Get the trait value as float.

Parameters:

name - the name of the trait to retrieve.

Returns:

the trait value as float for the specified name.

Throws:

DOMException - with error code NOT_SUPPORTED_ERR if the requested trait is not supported on this element or null.

DOMException - with error code TYPE_MISMATCH_ERR if requested trait's computed value cannot be converted to a float

java.lang.SecurityException - if the application does not have the necessary privilege rights to access this (SVG) content.

getMatrixTrait

SVGMatrix getMatrixTrait(java.lang.String name)
                         throws DOMException

Returns the trait value as SVGMatrix. The returned object is a copy of the actual trait value and will not change if the corresponding trait changes.

Parameters:

name - the name of the trait to retrieve.

Returns:

the trait value as SVGMatrix for the specified name.

Throws:

DOMException - with error code NOT_SUPPORTED_ERR if the requested trait is not supported on this element or null.

DOMException - with error code TYPE_MISMATCH_ERR if requested trait's computed value cannot be converted to SVGMatrix

java.lang.SecurityException - if the application does not have the necessary privilege rights to access this (SVG) content.

getRectTrait

SVGRect getRectTrait(java.lang.String name)
                     throws DOMException

Returns the trait value as SVGRect. The returned object is a copy of the actual trait value and will not change if the corresponding trait changes.

Parameters:

name - the name of the trait to retrieve.

Returns:

the trait value as SVGRect for the specified name.

Throws:

DOMException - with error code NOT_SUPPORTED_ERR if the requested trait is not supported on this element or null.

DOMException - with error code TYPE_MISMATCH_ERR if requested trait's computed value cannot be converted to SVGRect

java.lang.SecurityException - if the application does not have the necessary privilege rights to access this (SVG) content.

getPathTrait

SVGPath getPathTrait(java.lang.String name)
                     throws DOMException

Returns the trait value as SVGPath. The returned object is a copy of the actual trait value and will not change if the corresponding trait changes.

Parameters:

name - the name of the trait to retrieve.

Returns:

the trait value as SVGPath for the specified name.

Throws:

DOMException - with error code NOT_SUPPORTED_ERR if the requested trait is not supported on this element or null.

DOMException - with error code TYPE_MISMATCH_ERR if requested trait's computed value cannot be converted to SVGPath

java.lang.SecurityException - if the application does not have the necessary privilege rights to access this (SVG) content.

getRGBColorTrait

SVGRGBColor getRGBColorTrait(java.lang.String name)
                             throws DOMException

Returns the trait value as SVGRGBColor. The returned object is a copy of the trait value and will not change if the corresponding trait changes. If the actual trait value is not an RGBColor (i.e. "none"), this method will return null.

Parameters:

name - the name of the trait to retrieve.

Returns:

the trait value as SVGRGBColor for the specified name.

Throws:

DOMException - with error code NOT_SUPPORTED_ERR if the requested trait is not supported on this element or null.

DOMException - with error code TYPE_MISMATCH_ERR if requested trait's computed value cannot be converted to SVGRGBColor

java.lang.SecurityException - if the application does not have the necessary privilege rights to access this (SVG) content.

setTrait

void setTrait(java.lang.String name,
              java.lang.String value)
              throws DOMException

Set the trait value as String. In SVG Tiny only certain traits can be set through a String value. The syntax of the String that should be given as a value must be the same as syntax of the corresponding XML attribute value. Exactly equivalent to setTraitNS with namespaceURI attribute set to null.

Parameters:

name - the name of the trait to be set.

value - the value of the trait to be set as String.

Throws:

DOMException - with error code NOT_SUPPORTED_ERR if the requested trait is not supported on this element or null.

DOMException - with error code TYPE_MISMATCH_ERR if the requested trait's value cannot be specified as a String

DOMException - with error code INVALID_ACCESS_ERR if the input value is an invalid value for the given trait or null.

DOMException - with error code NO_MODIFICATION_ALLOWED_ERR: if attempt is made to change readonly trait.

java.lang.SecurityException - if the application does not have the necessary privilege rights to access this (SVG) content.

setTraitNS

void setTraitNS(java.lang.String namespaceURI,
                java.lang.String name,
                java.lang.String value)
                throws DOMException

Same as setTrait, but for namespaced traits. Parameter name must be a non-qualified trait name, i.e. without prefix.

Parameters:

namespaceURI - the namespaceURI of the trait to be set.

name - the name of the trait to be set.

value - the value of the trait to be set as String.

Throws:

DOMException - with error code NOT_SUPPORTED_ERR if the requested trait is not supported on this element or null.

DOMException - with error code TYPE_MISMATCH_ERR if the requested trait's value cannot be specified as a String

DOMException - with error code INVALID_ACCESS_ERR if the input value is an invalid value for the given trait or null. This error is also thrown when the <use> element is hooked into the document tree and the the value of xlink:href is set invalid.

DOMException - with error code NO_MODIFICATION_ALLOWED_ERR: if attempt is made to change readonly trait.

java.lang.SecurityException - if the application does not have the necessary privilege rights to access this (SVG) content.

setFloatTrait

void setFloatTrait(java.lang.String name,
                   float value)
                   throws DOMException

Set the trait value as float.

Parameters:

name - the name of the trait to be set.

value - the value of the trait to be set as float.

Throws:

DOMException - with error code NOT_SUPPORTED_ERR if the requested trait is not supported on this element.

DOMException - with error code TYPE_MISMATCH_ERR if the requested trait's value cannot be specified as a float

DOMException - with error code INVALID_ACCESS_ERR if the input value is an invalid value for the given trait.

java.lang.SecurityException - if the application does not have the necessary privilege rights to access this (SVG) content.

setMatrixTrait

void setMatrixTrait(java.lang.String name,
                    SVGMatrix matrix)
                    throws DOMException

Set the trait value as SVGMatrix. Values in SVGMatrix are copied in the trait so subsequent changes to the given SVGMatrix have no effect on the value of the trait.

Parameters:

name - the name of the trait to be set.

matrix - the value of the trait to be set as SVGMatrix.

Throws:

DOMException - with error code NOT_SUPPORTED_ERR if the requested trait is not supported on this element or null.

DOMException - with error code TYPE_MISMATCH_ERR if the requested trait's value cannot be specified as an SVGMatrix

DOMException - with error code INVALID_ACCESS_ERR if the input matrix value is null.

java.lang.SecurityException - if the application does not have the necessary privilege rights to access this (SVG) content.

setRectTrait

void setRectTrait(java.lang.String name,
                  SVGRect rect)
                  throws DOMException

Set the trait value as SVGRect. Values in SVGRect are copied in the trait so subsequent changes to the given SVGRect have no effect on the value of the trait.

Parameters:

name - the name of the trait to be set.

rect - the value of the trait to be set as SVGRect.

Throws:

DOMException - with error code NOT_SUPPORTED_ERR if the requested trait is not supported on this element or null.

DOMException - with error code TYPE_MISMATCH_ERR if the requested trait's value cannot be specified as an SVGRect

DOMException - with error code INVALID_ACCESS_ERR if the input value is an invalid value for the given trait or null. SVGRect is invalid if the width or height values are set to negative.

java.lang.SecurityException - if the application does not have the necessary privilege rights to access this (SVG) content.

setPathTrait

void setPathTrait(java.lang.String name,
                  SVGPath path)
                  throws DOMException

Set the trait value as SVGPath. Values in SVGPath are copied in the trait so subsequent changes to the given SVGPath have no effect on the value of the trait.

Parameters:

name - the name of the trait to be set.

path - the value of the trait to be set as SVGPath.

Throws:

DOMException - with error code NOT_SUPPORTED_ERR if the requested trait is not supported on this element or null.

DOMException - with error code TYPE_MISMATCH_ERR if the requested trait's value cannot be specified as an SVGPath

DOMException - with error code INVALID_ACCESS_ERR if the input value is an invalid value for the given trait or null. SVGPath is invalid if it begins with any segment other than MOVE_TO segment. Note that an empty SVGPath is still a valid value.

java.lang.SecurityException - if the application does not have the necessary privilege rights to access this (SVG) content.

setRGBColorTrait

void setRGBColorTrait(java.lang.String name,
                      SVGRGBColor color)
                      throws DOMException

Set the trait value as SVGRGBColor. Values in SVGRGBColor are copied in the trait so subsequent changes to the given SVGRGBColor have no effect on the value of the trait.

Parameters:

name - the name of the trait to be set.

color - the value of the trait to be set as SVGRGBColor.

Throws:

DOMException - with error code NOT_SUPPORTED_ERR if the requested trait is not supported on this element or null.

DOMException - with error code TYPE_MISMATCH_ERR if the requested trait's value cannot be specified as an SVGRGBColor

DOMException - with error code INVALID_ACCESS_ERR if the input value is null.

java.lang.SecurityException - if the application does not have the necessary privilege rights to access this (SVG) content.