org.w3c.dom.svg
Interface SVGElement

All Superinterfaces:

Element, Node, EventTarget

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.

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. 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"

Since:

BlackBerry API 4.6.0

Field Summary

Fields inherited from interface org.w3c.dom.Node

ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE

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

Methods inherited from interface org.w3c.dom.Element

getAttribute, getAttributeNS, getAttributeNode, getAttributeNodeNS, getElementsByTagName, getElementsByTagNameNS, getSchemaTypeInfo, getTagName, hasAttribute, hasAttributeNS, removeAttribute, removeAttributeNS, removeAttributeNode, setAttribute, setAttributeNS, setAttributeNode, setAttributeNodeNS, setIdAttribute, setIdAttributeNS, setIdAttributeNode

Methods inherited from interface org.w3c.dom.Node

appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData

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

addEventListener, dispatchEvent, removeEventListener

Method Detail

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.

Since:

BlackBerry API 4.6.0

setId

void setId(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.

NullPointerException - if Id is null.

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

Since:

BlackBerry API 4.6.0

getId

String getId()

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

Returns:

the Element's Id

Since:

BlackBerry API 4.6.0

getTrait

String getTrait(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).

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

Since:

BlackBerry API 4.6.0

getTraitNS

String getTraitNS(String namespaceURI,
                  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).

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

Since:

BlackBerry API 4.6.0

getFloatTrait

float getFloatTrait(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

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

Since:

BlackBerry API 4.6.0

getMatrixTrait

SVGMatrix getMatrixTrait(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

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

Since:

BlackBerry API 4.6.0

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.

Since:

BlackBerry API 4.6.0

getRectTrait

SVGRect getRectTrait(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

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

Since:

BlackBerry API 4.6.0

getPathTrait

SVGPath getPathTrait(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

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

Since:

BlackBerry API 4.6.0

getRGBColorTrait

SVGRGBColor getRGBColorTrait(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 retreive.

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

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

Since:

BlackBerry API 4.6.0

setTrait

void setTrait(String name,
              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.

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

Since:

BlackBerry API 4.6.0

setTraitNS

void setTraitNS(String namespaceURI,
                String name,
                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.

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

Since:

BlackBerry API 4.6.0

setFloatTrait

void setFloatTrait(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.

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

Since:

BlackBerry API 4.6.0

setMatrixTrait

void setMatrixTrait(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.

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

Since:

BlackBerry API 4.6.0

setRectTrait

void setRectTrait(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.

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

Since:

BlackBerry API 4.6.0

setPathTrait

void setPathTrait(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.

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

Since:

BlackBerry API 4.6.0

setRGBColorTrait

void setRGBColorTrait(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.

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

Since:

BlackBerry API 4.6.0