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.

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:

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:
JDE 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.
 SVGRect getRectTrait(String name)
           Returns the trait value as SVGRect.
 SVGRGBColor getRGBColorTrait(String name)
           Returns the trait value as SVGRGBColor.
 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 setRectTrait(String name, SVGRect rect)
           Set the trait value as SVGRect.
 void setRGBColorTrait(String name, SVGRGBColor color)
           Set the trait value as SVGRGBColor.
 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, getAttributeNode, getAttributeNodeNS, getAttributeNS, getElementsByTagName, getElementsByTagNameNS, getSchemaTypeInfo, getTagName, hasAttribute, hasAttributeNS, removeAttribute, removeAttributeNode, removeAttributeNS, setAttribute, setAttributeNode, setAttributeNodeNS, setAttributeNS, setIdAttribute, setIdAttributeNode, setIdAttributeNS
 
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

public 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:
JDE 4.6.0

getFloatTrait

public 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:
JDE 4.6.0

getId

public String getId()

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

Returns:
the Element's Id
Since:
JDE 4.6.0

getMatrixTrait

public 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:
JDE 4.6.0

getNextElementSibling

public 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:
JDE 4.6.0

getPathTrait

public 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:
JDE 4.6.0

getRectTrait

public 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:
JDE 4.6.0

getRGBColorTrait

public 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:
JDE 4.6.0

getTrait

public 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:
JDE 4.6.0

getTraitNS

public 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:
JDE 4.6.0

setFloatTrait

public 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:
JDE 4.6.0

setId

public 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:
JDE 4.6.0

setMatrixTrait

public 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:
JDE 4.6.0

setPathTrait

public 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:
JDE 4.6.0

setRectTrait

public 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:
JDE 4.6.0

setRGBColorTrait

public 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:
JDE 4.6.0

setTrait

public 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:
JDE 4.6.0

setTraitNS

public 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:
JDE 4.6.0



Copyright 1999-2009 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.