Scalable Vector Graphics (SVG) Tiny 1.2 Specification

The created SVGMatrix object.

No exceptions

createSVGRect

Creates a new SVGRect object. This object can be used to modify the value of traits which are compatible with the SVGRect type using the setRectTrait method. The initial values for x, y, width and height of this new SVGRect are zero.

No parameters

Return value

The created SVGRect.

No exceptions

createSVGPoint

Creates a new SVGPoint object. The initial values for x and y of this new SVGPoint are zero.

No parameters

Return value

SVGPoint

The created SVGPoint.

No exceptions

createSVGPath

Creates a new SVGPath object. This object can be used to modify the value of traits which are compatible with the SVGPath type using the setPathTrait method.

No parameters

Return value

SVGPath

The created SVGPath.

No exceptions

createSVGRGBColor

Creates a new SVGRGBColor object. This object can be used to modify the value of traits which are compatible with the SVGRGBColor type using the setRGBColorTrait method. The parameters are floats, one per color component. 0.0 represents zero intensity and 255.0 represents full intensity of a given color component. Colors originally in the rgb(%,%,%) syntax may have fractional components. Out of gamut colors may have component values less than 0.0 or greater than 255.0.

Parameters

in float red	The red component of the SVGRGBColor.
in float green	The green component of the SVGRGBColor.
in float blue	The blue component of the SVGRGBColor.

Return value

SVGRGBColor

The created SVGRGBColor.

No exceptions

moveFocus

Moves the current focus to a different object based on the value of the parameter. The user agent must take into account the currently focused object in the document in order to find the new focused object.

If this method succeeds:

A DOMFocusOut event must be dispatched which has the previously focused object as the event target.
After that, a DOMFocusIn event must dispatched which has the the new focused object as the event target.

A reference to the new focused object can be obtained using the EventTarget interface of the generated DOMFocusIn event.

Refer to the navigation section for a description of how navigation is managed. The behavior for this method must be the same as if an equivalent move was done by the end user (for example by using a joystick or pressing the Tab key) and not by scripting.

Whenever the method fails (that is, when a DOMException is raised), focus must stay on the currently focused object and no DOMFocusOut/DOMFocusIn event is dispatched.

Note: For stand-alone SVG documents, the user agent must always have a currently focused object. At the beginning, the SVGDocument has focus.

Parameters

in short motionType

The type of motion.

No return value

Exceptions

DOMException		NOT_SUPPORTED_ERR: Raised if the requested motion type is not supported (i.e. not one of the interface constants).
DOMException		INVALID_ACCESS_ERR: Raised if the currently focused object doesn't have a navigation attribute value corresponding to the requested motion type. For instance, if a `moveFocus(NAV_UP)` is called on an element which has no 'nav-up' attribute.
DOMException		INVALID_STATE_ERR: Raised if the currently focused object has a navigation attribute value corresponding to the requested motion type but the target indicated in this attribute can not be found or is not a focusable object. For instance, if a `moveFocus(NAV_UP)` is called on an object which has a 'nav-up' attribute but the value of this attribute references an element which is not focusable.

setFocus

A request to put the focus on the given object.

If this method succeeds:

A DOMFocusOut event must be dispatched which has the previously focused object as the event target.
After that, a DOMFocusIn event must be dispatched which has the the new focused object as the event target.

A reference to the newly focused object can be obtained using the EventTarget interface of the generated DOMFocusIn event.

Whenever the method fails (that is, when a DOMException is raised), focus must stay on the currently focused object and no DOMFocusOut or DOMFocusIn event is dispatched.

Note: For stand-alone SVG documents, the user agent must always have a currently focused object. At the beginning, the SVGDocument has focus.

Parameters

in EventTarget theObject

The object which should receive focus.

No return value

Exceptions

NOT_SUPPORTED_ERR: Raised if the in parameter is not a Node or SVGElementInstance, or if the requested element is not focusable (i.e. its 'focusable' attribute indicates that the element is not focusable).

getCurrentFocusedObject

Returns a reference to the object which has the focus. This returns an EventTarget.

No parameters

Return value

EventTarget

object

The currently focused object.

No exceptions

A.8.6 SVGRGBColor

This interface represents a color value made up of red, green, and blue components. It can be used to read and write traits that store color values (using getRGBColorTrait) such as 'fill', 'stroke', and 'color'.

IDL Definition

interface SVGRGBColor
{
	attribute unsigned long red;
	attribute unsigned long green;
	attribute unsigned long blue;
};

No defined constants

Attributes

red: Returns the red component of the SVGRGBColor.

green: Returns the green component of the SVGRGBColor.

blue: Returns the blue component of the SVGRGBColor.

No defined methods

A.8.7 SVGRect

This interface represents an SVGRect datatype, consisting of a minimum x, minimum y, width and height values.

This interface is identical to SVGRect interface defined in SVG 1.1 ([SVG11], section 4.3).

IDL Definition

interface SVGRect
{
	attribute float x;
	attribute float y;
	attribute float width;
	attribute float height;
};

No defined constants

Attributes

x: See x.

y: See y.

width: See width.

height: See height.

No defined methods

A.8.8 SVGPoint

Represents an SVGPoint datatype, identified by its x and y components.

This interface is identical to SVGPoint interface defined in SVG 1.1 ([SVG11], section 4.3).

IDL Definition

interface SVGPoint
{
	attribute float x;
	attribute float y;
	SVGPoint matrixTransform(in SVGMatrix matrix);
};

No defined constants

Attributes

x: See x.

y: See y.

Methods

matrixTransform: See matrixTransform.

A.8.9 SVGPath

This interface represents an SVGPath datatype used to define path geometry.

Path data created or modified using this interface must be normalized as per the rules given in Path Normalization. However, path data that is just queried need not be normalized.

IDL Definition

interface SVGPath
{
	const unsigned short MOVE_TO = 77;
	const unsigned short LINE_TO = 76;
	const unsigned short CURVE_TO = 67;
	const unsigned short QUAD_TO = 81;
	const unsigned short CLOSE = 90;
	readonly attribute unsigned long numberOfSegments;
	unsigned short getSegment(in unsigned long cmdIndex) 
		raises(DOMException);
	float getSegmentParam(in unsigned long cmdIndex, in unsigned long paramIndex) 
		raises(DOMException);
	void moveTo(in float x, in float y);
	void lineTo(in float x, in float y);
	void quadTo(in float x1, in float y1, in float x2, in float y2);
	void curveTo(in float x1, in float y1, in float x2, in float y2, in float x3, in float y3);
	void close();
};

Constants

MOVE_TO: Represents a "move to" command. The numeric value is the Unicode codepoint of the letter "M".

LINE_TO: Represents a "line to" command. The numeric value is the Unicode codepoint of the letter "L".

CURVE_TO: Represents a "cubic Bézier curve to" command. The numeric value is the Unicode codepoint of the letter "C".

QUAD_TO: Represents a "quadrative Bézier curve to" command. The numeric value is the Unicode codepoint of the letter "Q".

CLOSE: Represents a "close" command. The numeric value is the Unicode codepoint of the letter "Z".

Attributes

numberOfSegments: Return number of segments in this path.

Methods

getSegment

Returns segment command by zero-based command index.

Parameters

in unsigned long cmdIndex

The command index for the segment command to retrieve.

Return value

unsigned short The segment command. One of MOVE_TO, LINE_TO, CURVE_TO, QUAD_TO or CLOSE.

Exceptions

INDEX_SIZE_ERR: Raised if the segment index is out of bounds.

getSegmentParam

Returns segment parameter by zero-based command index and zero-based parameter index.

Parameters

in unsigned long cmdIndex	The command index for the segment command.
in unsigned long paramIndex	The parameter index to retrieve.

Return value

float

The segment parameter.

Exceptions

INDEX_SIZE_ERR: Raised if the segment index is out of bounds, or the parameter index is out of bounds for the specified segment's type.

moveTo

Appends an 'M' (absolute move) segment to the path with the specified coordinates.

Parameters

in float x	The x-axis coordinate for the specified point.
in float y	The y-axis coordinate for the specified point.

No return value

No exceptions

lineTo

Appends an 'L' (absolute line) segment to the path with the specified coordinates.

Parameters

in float x	The x-axis coordinate for the specified point.
in float y	The y-axis coordinate for the specified point.

No return value

No exceptions

quadTo

Appends a 'Q' (absolute quadratic curve) segment to the path.

Parameters

in float x1	The x-axis coordinate of the first control point.
in float y1	The y-axis coordinate of the first control point.
in float x2	The x-axis coordinate of the final end point.
in float y2	The y-axis coordinate of the final end point.

No return value

No exceptions

curveTo

Appends a 'C' (absolute cubic curve) segment to the path.

Parameters

in float x1	The x-axis coordinate of the first control point.
in float y1	The y-axis coordinate of the first control point.
in float x2	The x-axis coordinate of the second end point.
in float y2	The y-axis coordinate of the second end point.
in float x3	The x-axis coordinate of the final end point.
in float y3	The y-axis coordinate of the final end point.

No return value

No exceptions

close: Appends a 'z' (close path) segment to the path.

A.8.10 SVGMatrix

This interface is a matrix, as is used to represent an affine transform. It can be used to read and modify the values of the 'transform' attribute.

Note: The mTranslate, inverse, mMultiply, mScale and mRotate methods in this interface mutate the SVGMatrix object and return a reference to the SVGMatrix instance itself, after performing the necessary matrix operation.

This matrix transforms source coordinates (x, y) into destination coordinates (x', y') by considering them to be a column vector and multiplying the coordinate vector by the matrix according to the following process:

    [ x' ]    [  a  c  e  ]   [ x ]    [ a.x + c.y + e ]
    [ y' ] =  [  b  d  f  ]   [ y ] =  [ b.x + d.y + f ]
    [ 1  ]    [  0  0  1  ]   [ 1 ]    [        1      ]

IDL Definition

interface SVGMatrix
{
	float getComponent(in unsigned long index) 
		raises(DOMException);
	SVGMatrix mMultiply(in SVGMatrix secondMatrix);
	SVGMatrix inverse() 
		raises(SVGException);
	SVGMatrix mTranslate(in float x, in float y);
	SVGMatrix mScale(in float scaleFactor);
	SVGMatrix mRotate(in float angle);
};

No defined constants

No defined attributes

Methods

getComponent

Returns a component of the matrix by the component's zero-based index. getComponent(0) is a, getComponent(1) is b, etc.

Parameters

in unsigned long index

The index of the matrix component to retrieve.

Return value

float

The matrix component.

Exceptions

INDEX_SIZE_ERR: Raised if the index is invalid (i.e., outside the range [0, 5]).

mMultiply

Performs matrix multiplication. This matrix is post-multiplied by another matrix, returning the resulting current matrix.

Parameters

in SVGMatrix secondMatrix

The matrix to post-multiply with.

Return value

The resulting current matrix.

No exceptions

inverse

Returns a new instance of SVGMatrix containing the inverse of the current matrix.

No parameters

Return value

The inverse of the current matrix.

Exceptions

SVGException

SVG_MATRIX_NOT_INVERTABLE: Raised when the determinant of this matrix is zero.

mTranslate

Post-multiplies a translation transformation on the current matrix and returns the resulting current matrix. This is equivalent to calling mMultiply(T), where T is an SVGMatrix object represented by the following matrix:

        [   1    0    x  ]
        [   0    1    y  ]
        [   0    0    1  ]

Parameters

in float x	The distance by which coordinates are translated in the `x`-axis direction.
in float y	The distance by which coordinates are translated in the `y`-axis direction.

Return value

The resulting current matrix.

No exceptions

mScale

Post-multiplies a uniform scale transformation on the current matrix and returns the resulting current matrix. This is equivalent to calling mMultiply(S), where S is an SVGMatrix object represented by the following matrix:

        [   scaleFactor      0          0   ]
        [   0          scaleFactor      0   ]
        [   0                0          1   ]

Parameters

in float scaleFactor

The factor by which coordinates are scaled along the x- and y-axis.

Return value

The resulting current matrix.

No exceptions

mRotate

Post-multiplies a rotation transformation on the current matrix and returns the resulting current matrix. This is equivalent to calling mMultiply(R), where R is an SVGMatrix object represented by the following matrix:

    [ cos(angle) -sin(angle) 0 ]
    [ sin(angle)  cos(angle) 0 ]
    [ 0           0          1 ]

Parameters

in float angle

The angle of rotation in degrees.

Return value

The resulting current matrix.

No exceptions

A.8.11 SVGLocatable

Interface for getting information about the location of elements.

IDL Definition

interface SVGLocatable
{
	SVGRect   getBBox();
	SVGMatrix getScreenCTM();
	SVGRect   getScreenBBox();
};

No defined constants

No defined attributes

Methods

getBBox

Returns the bounding box of the element.

No parameters

Return value

The bounding box. The returned object is a copy of the current bounding box value and will not change if the corresponding bounding box changes.

No exceptions

getScreenCTM

Returns the transformation matrix from current user units to the initial viewport coordinate system. The clientX and clientY coordinates of a MouseEvent are in the initial viewport coordinate system. Note that null is returned if this element is not hooked into the document tree. This method would have been more aptly named as getClientCTM, but the name getScreenCTM is kept for historical reasons. Also note that getScreenCTM reflects a snapshot of the current animated state, i.e. if one or several transforms that affect the element that getScreenCTM is called upon are animated then the returned transformation matrix reflects the current state of each such animated transform when calculating the returned matrix.

No parameters

Return value

The transformation matrix. The returned object is a copy of the current screen CTM value and will not change if the corresponding screen CTM changes.

No exceptions

getScreenBBox

Returns the bounding box of the element in screen coordinate space. The box coordinates are in the initial viewport coordinate system, which is connected to the current user coordinate space by the matrix returned by the SVGLocatable::getScreenCTM method.

No parameters

Return value

The bounding box in screen coordinate space. The returned object is a copy of the current screen bounding box value and will not change if the corresponding screen bounding box changes.

No exceptions

The following examples further clarify the behavior of the getBBox() method. The examples have a short explanation, an SVG fragment and are followed by a set of bounding box values which have the following format:

[elementId] : {x, y, width, height} | {null}

where x, y, width and height define the values of the SVGRect objects returned from a getBBox call on the element with the specified ID. There are a few cases where the bounding box may be null (see example 6).

Example #1: Simple groups and bounds
This first example shows the values returned by the getBBox method for various simple basic shapes and groups. In particular, it shows that the transform, on an element, does not change the value of its user space bounding box.

<g xml:id="group1" transform="translate(10, 20)" fill="red">
    <rect xml:id="rect1" transform="scale(2)" x="10" y="10" width="50" height="50"/>
    <rect xml:id="rect2" x="10" y="10" width="100" height="100"/>
    <g xml:id="group2" transform="translate(10, 20)">
        <rect xml:id="rect3" x="0" y="10" width="150" height="50"/>
        <circle xml:id="circle1" cx="20" cy="20" r="100" />
    </g>
</g>

Result:
[group1] : {-70.0, -60.0, 230.0, 200.0} [rect1] : {10.0, 10.0, 50.0, 50.0} [rect2] : {10.0, 10.0, 100.0, 100.0} [group2] : {-80.0, -80.0, 230.0, 200.0} [rect3] : {0.0, 10.0, 150.0, 50.0} [circle1] : {-80.0, -80.0, 200.0, 200.0}

Example #2: Bounding box on zero width or height rectangle
This example illustrates that the bounding box on elements is based on the element's geometry coordinates. For example, the bounding box on a zero-width rectangle is defined (see below), even though the rectangle is not rendered.

<g xml:id="group1" transform="translate(10, 20)" fill="red">
    <rect xml:id="rect2" x="10" y="10" width="400" height="0"/>
    <g xml:id="group2" transform="translate(10, 20)">
        <rect xml:id="rect3" x="0" y="10" width="150" height="50"/>
    </g>
</g>

Result:
[group1] : {10.0, 10.0, 400.0, 70.0} [rect2] : {10.0, 10.0, 400.0, 0.0} [group2] : {0.0, 10.0, 150.0, 50.0} [rect3] : {0.0, 10.0, 150.0, 50.0}

Example #3: Bounding Box on zero radius ellipses.
This is another example of how bounding boxes are based on the element's geometry. Here, the bounding box of an ellipse with a zero x-axis radius is still defined, even though the ellipse is not rendered.

<svg xml:id="mySVG" version="1.2" baseProfile="tiny" width="10" height="20">
    <g xml:id="group1" transform="translate(10, 20)" fill="red">
        <rect xml:id="rect1" x="10" y="10" width="100" height="100"/>
        <ellipse xml:id="ellipse1" cx="20" cy="20" rx="0" ry="70" />
    </g>
</svg>

Result:
[mySVG] : {20.0, -30.0, 100.0, 160.0} [group1] : {10.0, -50.0, 100.0, 160.0} [rect1] : {10.0, 10.0, 100.0, 100.0} [ellipse1] : {20.0, -50.0, 0.0, 140.0}

Example #4: Viewports do not clip bounding boxes
This example shows that no matter what the viewport is on the rootmost 'svg' element, the bounding boxes, based on the geometry, are still defined. Here, even though the rootmost 'svg' element has a zero width, the bounding boxes for the root itself and its children is precisely defined.

<svg xml:id="mySVG" version="1.2" baseProfile="tiny" width="0" height="50">
    <g xml:id="group1" transform="translate(10, 20)" fill="red" >
        <rect xml:id="rect1" x="10" y="10" width="50" height="50"/>
        <g xml:id="group2" transform="translate(10, 20)">
            <rect xml:id="rect2" x="0" y="10" width="150" height="0"/>
            <circle xml:id="circle1" cx="20" cy="20" r="500"/>
        </g>
    </g>
</svg>

Result:
[mySVG] : {-460.0, -440.0, 1000.0, 1000.0} [group1] : {-470.0, -460.0, 1000.0, 1000.0} [rect1] : {10.0, 10.0, 50.0, 50.0} [group2] : {-480.0, -480.0, 1000.0, 1000.0} [rect2] : {0.0, 10.0, 150.0, 0.0} [circle1] : {-480.0, -480.0, 1000.0, 1000.0}

Example #5: getBBox on <use>
This example shows that the bounding box for a 'use' element accounts for the 'x' and 'y' attributes defined on the element, just like the 'x' and 'y' attributes impact the bounding box computation on a 'rect' or on an 'image' element.

<svg version="1.2" baseProfile="tiny">
    <defs>
        <rect xml:id="myRect" x="0" y="0" width="60" height="40"/>
    </defs>
    <use xml:id="myUse" xlink:href="#myRect" x="-30" y="-20"/>
</svg>

Result:
[myRect] : {0.0, 0.0, 60.0, 40.0} [myUse] : {-30.0, -20.0, 60.0, 40.0}

Example #6: Empty group
This example shows that the bounding box for an empty group is null. By the same token, the bounding box of a 'path' with an empty SVGPath (i.e. one with no path commands, which may happen after creating a new 'path' element with a createElementNS call) is also null.

<g xml:id="emptyG"/>

Result:
[emptyG] : {null}

Example #7: Impact of display="none" and visibility="hidden"
This example shows how the bounding box of children with display="none" are not accounted for in the computation of their parent's bounding box. This reflects the definition of the 'display' property and its impact on rendering and bounding box computation. The example also shows that elements with 'visibility' set to hidden still contribute to their parent's bounding box computation.

<g xml:id="g1">
    <g xml:id="g1.1.display.none" display="none">
        <rect xml:id="rect1" x="10" y="10" width="40" height="40"/>
    </g>
    <rect xml:id="rect2.visibility.hidden" visibility="hidden" x="30" y="60" width="10" height="20"/>
</g>

Result:
[g1] : {30.0, 60.0, 10.0, 20.0} [g1.1.display.none] : {10.0, 10.0, 40.0, 40.0} [rect1] : {10.0, 10.0, 40.0, 40.0} [rect2.visibility.hidden] : {30.0, 60.0, 10.0, 20.0}

Example #8: Concatenating bounding boxes in the container's user space
This example shows how the concatenation and computation of bounding boxes for container element happens in the container's user space.

<g xml:id="g1">
    <line xml:id="line1" x2="100" y2="100" transform="rotate(-45)"/>
</g>

Result:
[g1] : {0.0, 0.0, 141.42136, 0} [line1] : {0.0, 0.0, 100.0, 100.0}

Example #9: No influence of stroke-width
This example illustrates that stroking has no impact on the computation of bounding boxes.

<g>
    <line xml:id="thickLine" stroke-width="10" x2="100" y2="0"/>
</g>

Result:
[thickLine] : {0.0, 0.0, 100.0, 0.0}

Example #10: No influence of viewBox
This example illustrates that the viewBox has no impact on the computation of bounding boxes.

<svg xml:id="rootSvg" version="1.2" baseProfile="tiny" width="500" height="300" viewBox="0 0 200 100">
    <rect x="-100" y="-200" width="500" height="100"/>
</svg>

Result:
[rootSVG] : {-100, -200, 500, 100}

Example #11: Impact of elements which are not in the rendering tree
This example illustrates that elements which are not in the rendering tree have no impact on the computation of bounding boxes.

        <g xml:id="g1">
          <linearGradient xml:id="MyGradient"/>
            <stop offset="0.05" stop-color="#F60"/>
            <stop offset="0.95" stop-color="#FF6"/>
          </linearGradient>
        </g>

Result:
[g1] : {null}

A.8.12 SVGLocatableElement

This interface represents an element that has a physical location on the screen.

This interface is implemented by: 'rect', 'circle', 'ellipse', 'line', 'path', 'use', 'image', 'text', 'textArea', 'tspan', 'svg', 'a', 'video', 'animation', 'switch', 'foreignObject', 'polygon', 'polyline' and 'g'.

IDL Definition

interface SVGLocatableElement : SVGElement, SVGLocatable
{
};

No defined constants

No defined attributes

No defined methods

A.8.13 TraitAccess

Trait manipulation interface. This interface is used to read and manipulate the value of "traits" associated with an 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 an unsupported trait must throw an exception. Also, unlike attributes, traits are typed and their values are normalized; for instance path data specified on a 'path' element is parsed and all path commands are converted to their absolute variants, and it is not possible to determine from the value of the trait if a path command was absolute or relative. When getting and setting trait values, an accessor of the correct type must be used or an exception will be thrown.

For a trait corresponding to a property, the computed value is used: if the value of a given property is not specified on that element, then for inherited properties the value on the parent is used. For non-inherited values, or on the root element, the initial value of the property is used.

For a trait corresponding to a non-property attribute, if the attribute is inherited (such as 'xml:lang') the value of the parent is used. If the attribute is not inherited, or on the root element, the lacuna value for the attribute is used, if known. If not known (for example, for an unknown attribute, or a known attribute with no specified default), null is returned.

Note that when using the TraitAccess interface for getting traits on elements outside of the tree, for example on elements just created or removed, what values are returned is user agent dependent.

The trait getter methods (getTrait, getTraitNS, getFloatTrait, etc.) return base values (i.e., before animation is applied), and this is true for both static and animated content. Note however that if the attribute is inherited from an animated parent value, it will inherit the animated value. The trait presentation value getter methods (getPresentationTrait, getPresentationTraitNS, getFloatPresentationTrait, etc.) return either the current animated value if the given trait is currently being animated or the base value if the given trait is not currently being animated. Not all attributes are accessible by traits — see the table of supported attributes for details.

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 corresponding to properties, the trait value can always be set to inherit (but querying the value will always return the actual inherited value as explained above).

Note about invalid/unsupported trait values: There are two situations where the various trait setter methods (such as the setTrait, setFloatTrait and 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 result in this exception being thrown). The trait methods will consider the value to be invalid if it is an unsupported value. However, if the trait value being set is an IRI reference, such as when setting a <FuncIRI> value on the 'fill' property or when setting the 'xlink:href' attribute on an 'image' element, an SVG user agent must not consider that trait value invalid if it is syntactically correct but is otherwise an invalid IRI reference. Thus, the DOMException with code INVALID_ACCESS_ERR must not be thrown in this case. This obviates the need for an SVG user agent to fetch the IRI upon setting the trait solely to determine whether it is an invalid IRI reference.

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 'path' 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.

IDL Definition

interface TraitAccess
{
	DOMString getTrait(in DOMString name) 
		raises(DOMException);
	DOMString getTraitNS(in DOMString namespaceURI, in DOMString name) 
		raises(DOMException);
	float getFloatTrait(in DOMString name) 
		raises(DOMException);
	sequence<float> getFloatListTrait(in DOMString name) 
		raises(DOMException);
	SVGMatrix getMatrixTrait(in DOMString name) 
		raises(DOMException);
	SVGRect getRectTrait(in DOMString name) 
		raises(DOMException);
	SVGPath getPathTrait(in DOMString name) 
		raises(DOMException);
	SVGRGBColor getRGBColorTrait(in DOMString name) 
		raises(DOMException);
	DOMString getPresentationTrait(in DOMString name) 
		raises(DOMException);
	DOMString getPresentationTraitNS(in DOMString namespaceURI, in DOMString name) 
		raises(DOMException);
	float getFloatPresentationTrait(in DOMString name) 
		raises(DOMException);
	sequence<float> getFloatListPresentationTrait(in DOMString name) 
		raises(DOMException);
	SVGMatrix getMatrixPresentationTrait(in DOMString name) 
		raises(DOMException);
	SVGRect getRectPresentationTrait(in DOMString name) 
		raises(DOMException);
	SVGPath getPathPresentationTrait(in DOMString name) 
		raises(DOMException);
	SVGRGBColor getRGBColorPresentationTrait(in DOMString name) 
		raises(DOMException);
	void setTrait(in DOMString name, in DOMString value) 
		raises(DOMException);
	void setTraitNS(in DOMString namespaceURI, in DOMString name, in DOMString value) 
		raises(DOMException);
	void setFloatTrait(in DOMString name, in float value) 
		raises(DOMException);
	void setFloatListTrait(in DOMString name, in sequence<float> value) 
		raises(DOMException);
	void setMatrixTrait(in DOMString name, in SVGMatrix matrix) 
		raises(DOMException);
	void setRectTrait(in DOMString name, in SVGRect rect) 
		raises(DOMException);
	void setPathTrait(in DOMString name, in SVGPath path) 
		raises(DOMException);
	void setRGBColorTrait(in DOMString name, in SVGRGBColor color) 
		raises(DOMException);
};

No defined constants

No defined attributes

Methods

getTrait

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

Parameters

in DOMString name

The name of the trait to retrieve.

Return value

The trait value.

Exceptions

DOMException		NOT_SUPPORTED_ERR: Raised if the requested trait is not supported on this element or `null`.
DOMException		TYPE_MISMATCH_ERR: Raised if requested trait's computed value cannot be converted to a DOMString (SVG Tiny only).

getTraitNS

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

Parameters

in DOMString namespaceURI	The namespace of the trait to retrieve.
in DOMString name	The name of the trait to retrieve.

Return value

The trait value.

Exceptions

DOMException		NOT_SUPPORTED_ERR: Raised if the requested trait is not supported on this element or `null`.
DOMException		TYPE_MISMATCH_ERR: Raised if requested trait's computed value cannot be converted to a DOMString (SVG Tiny only).

getFloatTrait

Get the trait value as a float. Parameter name must be a non-qualified trait name, i.e. without prefix.

Parameters

in DOMString name

The name of the trait to retrieve.

Return value

float The trait value as a float.

Exceptions

DOMException		NOT_SUPPORTED_ERR: Raised if the requested trait is not supported on this element or `null`.
DOMException		TYPE_MISMATCH_ERR: Raised if requested trait's computed value is a non-numeric `float` (for example, when calling `getFloatTrait("width")` on the rootmost 'svg' element whose width attribute uses a percentage).

getFloatListTrait

Get the trait value as a sequence<float>. Parameter name must be a non-qualified trait name, i.e. without prefix.

Parameters

in DOMString name

The name of the trait to retrieve.

Return value

sequence<float> The trait value as a sequence<float>.

Exceptions

DOMException		NOT_SUPPORTED_ERR: Raised if the requested trait is not supported on this element or `null`.
DOMException		TYPE_MISMATCH_ERR: Raised if requested trait's computed value cannot be converted to a `sequence<float>`.

getMatrixTrait

Returns the trait value as an SVGMatrix. The returned object is a copy of the actual trait value and will not change if the corresponding trait changes. Parameter name must be a non-qualified trait name, i.e. without prefix.

Parameters

in DOMString name

The name of the trait to retrieve.

Return value

The trait value as an SVGMatrix.

Exceptions

DOMException		NOT_SUPPORTED_ERR: Raised if the requested trait is not supported on this element or `null`.
DOMException		TYPE_MISMATCH_ERR: Raised if requested trait's computed value cannot be converted to an SVGMatrix.

getRectTrait

Returns the trait value as an SVGRect. The returned object is a copy of the actual trait value and will not change if the corresponding trait changes. If the actual trait value is not an SVGRect, e.g. the 'none' value on the 'viewBox' attribute, this method will return null. Parameter name must be a non-qualified trait name, i.e. without prefix.

Parameters

in DOMString name

The name of the trait to retrieve.

Return value

The trait value as an SVGRect.

Exceptions

DOMException		NOT_SUPPORTED_ERR: Raised if the requested trait is not supported on this element or `null`.
DOMException		TYPE_MISMATCH_ERR: Raised if requested trait's computed value cannot be converted to an SVGRect.

getPathTrait

Returns the trait value as an SVGPath. The returned object is a copy of the actual trait value and will not change if the corresponding trait changes. Parameter name must be a non-qualified trait name, i.e. without prefix.

Parameters

in DOMString name

The name of the trait to retrieve.

Return value

SVGPath

The trait value as an SVGPath.

Exceptions

DOMException		NOT_SUPPORTED_ERR: Raised if the requested trait is not supported on this element or `null`.
DOMException		TYPE_MISMATCH_ERR: Raised if requested trait's computed value cannot be converted to an SVGPath.

getRGBColorTrait

Returns the trait value as an 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 SVGRGBColor, i.e. 'none' or a link to a paint server (e.g. to a gradient or a 'solidColor'), this method must return null. Parameter name must be a non-qualified trait name, i.e. without prefix.

Parameters

in DOMString name

The name of the trait to retrieve.

Return value

SVGRGBColor

The trait value as an SVGRGBColor.

Exceptions

DOMException		NOT_SUPPORTED_ERR: Raised if the requested trait is not supported on this element or `null`.
DOMException		TYPE_MISMATCH_ERR: Raised if requested trait's computed value cannot be converted to an SVGRGBColor.

getPresentationTrait

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

Parameters

in DOMString name

The name of the trait to retrieve.

Return value

The trait presentation value.

Exceptions

DOMException		NOT_SUPPORTED_ERR: Raised if the requested trait is not supported on this element or `null`.
DOMException		TYPE_MISMATCH_ERR: Raised if requested trait's computed value cannot be converted to a DOMString (SVG Tiny only).

getPresentationTraitNS

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

Parameters

in DOMString namespaceURI	The namespace of the trait to retrieve.
in DOMString name	The name of the trait to retrieve.

Return value

The trait presentation value.

Exceptions

DOMException		NOT_SUPPORTED_ERR: Raised if the requested trait is not supported on this element or `null`.
DOMException		TYPE_MISMATCH_ERR: Raised if requested trait's computed value cannot be converted to a DOMString (SVG Tiny only).

getFloatPresentationTrait

Get the trait presentation value as a float. Parameter name must be a non-qualified trait name, i.e. without prefix.

Parameters

in DOMString name

The name of the trait to retrieve.

Return value

float The trait presentation value as a float.

Exceptions

DOMException		NOT_SUPPORTED_ERR: Raised if the requested trait is not supported on this element or `null`.
DOMException		TYPE_MISMATCH_ERR: Raised if requested trait's computed value is a non-numeric `float` (for example, when calling `getFloatTrait("width")` on the rootmost 'svg' element whose width attribute uses a percentage).

getFloatListPresentationTrait

Get the trait presentation value as a sequence<float>. Parameter name must be a non-qualified trait name, i.e. without prefix.

Parameters

in DOMString name

The name of the trait to retrieve.

Return value

sequence<float> The trait presentation value as a sequence<float>.

Exceptions

DOMException		NOT_SUPPORTED_ERR: Raised if the requested trait is not supported on this element or `null`.
DOMException		TYPE_MISMATCH_ERR: Raised if requested trait's computed value cannot be converted to a `sequence<float>`.

getMatrixPresentationTrait

Returns the trait presentation value as an SVGMatrix. The returned object is a copy of the actual trait value and will not change if the corresponding trait changes or as animation continue to affect the trait presentation value. Parameter name must be a non-qualified trait name, i.e. without prefix.

Parameters

in DOMString name

The name of the trait to retrieve.

Return value

The trait presentation value as an SVGMatrix.

Exceptions

DOMException		NOT_SUPPORTED_ERR: Raised if the requested trait is not supported on this element or `null`.
DOMException		TYPE_MISMATCH_ERR: Raised if requested trait's computed value cannot be converted to an SVGMatrix.

getRectPresentationTrait

Returns the trait presentation value as an SVGRect. The returned object is a copy of the actual trait value and will not change if the corresponding trait changes or as animation continue to affect the trait presentation value. If the actual trait value is not an SVGRect, e.g. the 'none' value on the 'viewBox' attribute, this method will return null. Parameter name must be a non-qualified trait name, i.e. without prefix.

Parameters

in DOMString name

The name of the trait to retrieve.

Return value

The trait presentation value as an SVGRect.

Exceptions

DOMException		NOT_SUPPORTED_ERR: Raised if the requested trait is not supported on this element or `null`.
DOMException		TYPE_MISMATCH_ERR: Raised if requested trait's computed value cannot be converted to an SVGRect.

getPathPresentationTrait

Returns the trait presentation value as an SVGPath. The returned object is a copy of the actual trait value and will not change if the corresponding trait changes or as animation continue to affect the trait presentation value. Parameter name must be a non-qualified trait name, i.e. without prefix.

Parameters

in DOMString name

The name of the trait to retrieve.

Return value

SVGPath

The trait presentation value as an SVGPath.

Exceptions

DOMException		NOT_SUPPORTED_ERR: Raised if the requested trait is not supported on this element or `null`.
DOMException		TYPE_MISMATCH_ERR: Raised if requested trait's computed value cannot be converted to an SVGPath.

getRGBColorPresentationTrait

Returns the trait presentation value as an SVGRGBColor. The returned object is a copy of the trait value and will not change if the corresponding trait changes or as animation continue to affect the trait presentation value. If the actual trait value is not an SVGRGBColor, i.e. 'none' or a link to a paint server (e.g. to a gradient or a 'solidColor'), this method must return null. Parameter name must be a non-qualified trait name, i.e. without prefix.

Parameters

in DOMString name

The name of the trait to retrieve.

Return value

SVGRGBColor

The trait presentation value as an SVGRGBColor.

Exceptions

DOMException		NOT_SUPPORTED_ERR: Raised if the requested trait is not supported on this element or `null`.
DOMException		TYPE_MISMATCH_ERR: Raised if requested trait's computed value cannot be converted to an SVGRGBColor.

setTrait

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

Parameters

in DOMString name	The name of the trait to be set.
in DOMString value	The value of the trait.

No return value

Exceptions

DOMException		NOT_SUPPORTED_ERR: Raised if the requested trait is not supported on this element.
DOMException		TYPE_MISMATCH_ERR: Raised if the requested trait's value cannot be specified as a DOMString.
DOMException		INVALID_ACCESS_ERR: Raised if the input value is an invalid value for the given trait or `null` is specified.
DOMException		NO_MODIFICATION_ALLOWED_ERR: Raised if attempt is made to change a readonly trait.

setTraitNS

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

Parameters

in DOMString namespaceURI	The namespace of the trait to be set.
in DOMString name	The name of the trait to be set.
in DOMString value	The value of the trait.

No return value

Exceptions

DOMException		NOT_SUPPORTED_ERR: Raised if the requested trait is not supported on this element.
DOMException		TYPE_MISMATCH_ERR: Raised if the requested trait's value cannot be specified as a DOMString.
DOMException		INVALID_ACCESS_ERR: Raised if the input value is an invalid value for the given trait or `null` is specified.
DOMException		NO_MODIFICATION_ALLOWED_ERR: Raised if attempt is made to change a readonly trait.

setFloatTrait

Set the trait value as a float. Parameter name must be a non-qualified trait name, i.e. without prefix.

Parameters

in DOMString name	The name of the trait to be set.
in `float` value	The value of the trait.

No return value

Exceptions

DOMException		NOT_SUPPORTED_ERR: Raised if the requested trait is not supported on this element.
DOMException		TYPE_MISMATCH_ERR: Raised if the requested trait's value cannot be specified as a numeric `float` (e.g. `NaN`).
DOMException		INVALID_ACCESS_ERR: Raised if the input value is an invalid value for the given trait or `null` is specified.

setFloatListTrait

Set the trait value as a sequence<float>. Parameter name must be a non-qualified trait name, i.e. without prefix.

Parameters

in DOMString name	The name of the trait to be set.
in `sequence<float>` value	The value of the trait.

No return value

Exceptions

DOMException		NOT_SUPPORTED_ERR: Raised if the requested trait is not supported on this element.
DOMException		TYPE_MISMATCH_ERR: Raised if the requested trait's value cannot be specified as a `sequence<float>`).
DOMException		INVALID_ACCESS_ERR: Raised if the input value is an invalid value for the given trait or `null` is specified.

setMatrixTrait

Set the trait value as an 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. Parameter name must be a non-qualified trait name, i.e. without prefix.

Parameters

in DOMString name	The name of the trait to be set.
in SVGMatrix value	The value of the trait.

No return value

Exceptions

DOMException		NOT_SUPPORTED_ERR: Raised if the requested trait is not supported on this element.
DOMException		TYPE_MISMATCH_ERR: Raised if the requested trait's value cannot be specified as an SVGMatrix.
DOMException		INVALID_ACCESS_ERR: Raised if the input value is `null`.

setRectTrait

Set the trait value as an 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. Parameter name must be a non-qualified trait name, i.e. without prefix.

Parameters

in DOMString name	The name of the trait to be set.
in SVGRect value	The value of the trait.

No return value

Exceptions

DOMException		NOT_SUPPORTED_ERR: Raised if the requested trait is not supported on this element.
DOMException		TYPE_MISMATCH_ERR: Raised if the requested trait's value cannot be specified as an SVGRect.
DOMException		INVALID_ACCESS_ERR: Raised if the input value is an invalid value for the given trait or `null` is specified. An SVGRect is invalid if the width or height values are set to negative.

setPathTrait

Set the trait value as an 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. Parameter name must be a non-qualified trait name, i.e. without prefix.

Parameters

in DOMString name	The name of the trait to be set.
in SVGPath value	The value of the trait.

No return value

Exceptions

DOMException		NOT_SUPPORTED_ERR: Raised if the requested trait is not supported on this element.
DOMException		TYPE_MISMATCH_ERR: Raised if the requested trait's value cannot be specified as an SVGPath.
DOMException		INVALID_ACCESS_ERR: Raised if the input value is an invalid value for the given trait or `null` is specified. An SVGPath is invalid if it begins with any segment other than MOVE_TO segment. Note: An empty SVGPath is still a valid value.

setRGBColorTrait

Set the trait value as an 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. Parameter name must be a non-qualified trait name, i.e. without prefix.

Parameters

in DOMString name	The name of the trait to be set.
in SVGRGBColor value	The value of the trait.

No return value

Exceptions

DOMException		NOT_SUPPORTED_ERR: Raised if the requested trait is not supported on this element.
DOMException		TYPE_MISMATCH_ERR: Raised if the requested trait's value cannot be specified as an SVGRGBColor.
DOMException		INVALID_ACCESS_ERR: Raised if the input value is `null`.

Traits supported in this specification, SVG Tiny 1.2 uDOM

Trait access is not required on all of the SVG Tiny 1.2 attributes and properties. The table below shows the attributes and properties that SVG Tiny 1.2 uDOM implementations must support trait access to. Each attribute row lists the allowed getters and setters. The "Lacuna Value" column specifies the lacuna value that must be used for each attribute or property. If a "Lacuna Value" column entry is empty, there is no lacuna value. Unless explicitly stated in the "Comments" column, a supported attribute is accessible on all elements it can belong to. See the attribute table for a list of attributes and which elements they belong to.

Implementations that support multiple versions of SVG 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 SVG Tiny 1.2 uDOM implementations.

The user agent must raise a NOT_SUPPORTED_ERR whenever there is an attempt to use trait methods for traits which are not supported by the user agent.

For some of the attributes and data types additional rules apply. These rules are defined below the table.

Note: In the table below:

Wherever the table indicates that a user agent must support the getTrait method, it must also support the getTraitNS, getPresentationTrait, and getPresentationTraitNS methods.
Wherever the table indicates that a user agent must support the getTraitNS method, it must also support the getPresentationTraitNS method.
Wherever the table indicates that a user agent must support one of the typed (i.e., non-string) trait getter methods (e.g., getFloatTrait), it must also support the corresponding trait presentation getter method (e.g., getFloatPresentationTrait).
Wherever the table indicates that a user agent must support the setTrait method, it must also support the setTraitNS method.
Traits can only be used for accessing attribute and property values. They cannot be used for accessing font descriptors.

Trait Target	Trait Getter [Return Value]	Trait Setter [Argument Value]	Lacuna Value	Comments
Element text content	`getTrait("#text")` [The element text content]	`setTrait("#text", ...)` [New element text content]		See Text Content Access.
accumulate, attribute	`getTrait("accumulate")` [none \| sum]	`setTrait("accumulate", ...)` [none \| sum]	"none"
additive, attribute	`getTrait("additive")` [replace \| sum]	`setTrait("additive", ...)` [replace \| sum]	"replace"
attributeName, attribute	`getTrait("attributeName")`	`setTrait("attributeName", ...)`
audio-level, property	`getFloatTrait("audio-level")` [0 ≤ `value` ≤ 1]	`setFloatTrait("audio-level", ...)` [0 ≤ `value` ≤ 1] `setTrait("audio-level", ...)` [inherit]	1.0
baseProfile, attribute	`getTrait("baseProfile")`	`setTrait("baseProfile", ...)`	"none"
begin, attribute	N/A	`setTrait("begin", ...)`
calcMode, attribute	`getTrait("calcMode")` [discrete \| linear \| paced \| spline]	`setTrait("calcMode", ...)` [discrete \| linear \| paced \| spline]	"paced" when accessed on an 'animateMotion' element, "linear" otherwise
color, property	`getRGBColorTrait("color")` [null, SVGRGBColor]	`setRGBColorTrait("color, ...")` [SVGRGBColor] `setTrait("color", ...)` [inherit \| <color>]	rgb(0,0,0)
cx, attribute	`getFloatTrait("cx")`	`setFloatTrait("cx", ...)`	0.5 when accessed on a 'radialGradient' element, 0.0 otherwise
cy, attribute	`getFloatTrait("cy")`	`setFloatTrait("cy", ...)`	0.5 when accessed on a 'radialGradient' element, 0.0 otherwise
d, attribute	`getPathTrait("d")` [SVGPath]	`setPathTrait("d", ...)` [SVGPath]	An SVGPath object with no path segments	See Accessing rules for path attributes.
display, property	`getTrait("display")` [inline \| none]	`setTrait("display", ...)` [inline \| none \| inherit]	"inline"	See Accessing rules for 'display' property.
dur, attribute	N/A	`setTrait("dur", ...)`
editable, attribute	`getTrait("editable")` [simple \| none]	`setTrait("editable, ...)` [simple \| none]	"none"
end, attribute	N/A	`setTrait("end", ...)`
fill, property	`getRGBColorTrait("fill")` [null, SVGRGBColor] `getTrait("fill")` [none \| <FuncIRI> \| <color> \| <system paint>]	`setRGBColorTrait("fill", ...)` [SVGRGBColor] `setTrait("fill", ...)` [none \| currentColor \| <FuncIRI> \| <color> \| <system paint> \| inherit]	rgb(0,0,0)	There are no trait accessors for the animation element 'fill' attribute.
fill-opacity, property	`getFloatTrait("fill-opacity")` [0 ≤ `value` ≤ 1]	`setFloatTrait("fill-opacity", ...)` [0 ≤ `value` ≤ 1] `setTrait("fill-opacity", ...)` [inherit]	1.0
fill-rule, property	`getTrait("fill-rule")` [nonzero \| evenodd]	`setTrait("fill-rule", ...)` [nonzero \| evenodd \| inherit]	"nonzero"
focusable, attribute	`getTrait("focusable")` [true \| false]	`setTrait("focusable", ...)` [true \| false \| auto]	"auto"
focusHighlight, attribute	`getTrait("focusHighlight")` [auto \| none]	`setTrait("focusHighlight", ...)` [auto \| none]	"auto"
font-family, property	`getTrait("font-family")` [<font-family-value>]	`setTrait("font-family", ...)` [<font-family-value> \| inherit]	User agent specific	See Accessing rules for font properties.
font-size, property	`getFloatTrait("font-size")` [`value` ≥ 0]	`setFloatTrait("font-size", ...)` [`value` ≥ 0] `setTrait("font-size", ...)` [xx-small \| x-small \| small \| medium \| large \| x-large \| xx-large \| larger \| smaller \| inherit]	User agent specific
font-style, property	`getTrait("font-style")` [normal \| italic \| oblique]	`setTrait("font-style", ...)` [normal \| italic \| oblique \| inherit]	"normal"	See Accessing rules for font properties.
font-weight, property	`getTrait("font-weight")` [100 \| 200 \| 300 \| 400 \| 500 \| 600 \| 700 \| 800 \| 900]	`setTrait("font-weight", ...)` [normal \| bold \| bolder \| lighter \| 100 \| 200 \| 300 \| 400 \| 500 \| 600 \| 700 \| 800 \| 900 \| inherit]	"normal"	See Accessing rules for font properties.
from, attribute	N/A	`setTrait("from", ...)`
gradientUnits, attribute	`getTrait("gradientUnits")` [userSpaceOnUse \| objectBoundingBox]	`setTrait("gradientUnits", ...)` [userSpaceOnUse \| objectBoundingBox]	"objectBoundingBox"
height, attribute	`getFloatTrait("height")` [`value` ≥ 0] `getTrait("height")` ["auto"]	`setFloatTrait("height", ...)` [`value` ≥ 0] `setTrait("height", ...)` ["auto"]	"auto" when accessed on a 'textArea' element, 0.0 otherwise	See Accessing rules for 'width' and 'height' attributes.
id, attribute	`getTrait("id")`	`setTrait("id", ...)`
keyPoints, attribute	N/A	`setTrait("keyPoints", ...)`
keySplines, attribute	N/A	`setTrait("keySplines", ...)`
keyTimes, attribute	N/A	`setTrait("keyTimes", ...)`
max, attribute	N/A	`setTrait("max", ...)`
min, attribute	N/A	`setTrait("min", ...)`
nav-right, attribute	`getTrait("nav-right")` [auto \| self \| <FuncIRI>]	`setTrait("nav-right", ...)` [auto \| self \| <FuncIRI>]	"auto"
nav-next, attribute	`getTrait("nav-next")` [auto \| self \| <FuncIRI>]	`setTrait("nav-next", ...)` [auto \| self \| <FuncIRI>]	"auto"
nav-up, attribute	`getTrait("nav-up")` [auto \| self \| <FuncIRI>]	`setTrait("nav-up", ...)` [auto \| self \| <FuncIRI>]	"auto"
nav-up-right, attribute	`getTrait("nav-up-right")` [auto \| self \| <FuncIRI>]	`setTrait("nav-up-right", ...)` [auto \| self \| <FuncIRI>]	"auto"
nav-up-left, attribute	`getTrait("nav-up-left")` [auto \| self \| <FuncIRI>]	`setTrait("nav-up-left", ...)` [auto \| self \| <FuncIRI>]	"auto"
nav-prev, attribute	`getTrait("nav-prev")` [auto \| self \| <FuncIRI>]	`setTrait("nav-prev", ...)` [auto \| self \| <FuncIRI>]	"auto"
nav-down, attribute	`getTrait("nav-down")` [auto \| self \| <FuncIRI>]	`setTrait("nav-down", ...)` [auto \| self \| <FuncIRI>]	"auto"
nav-down-right, attribute	`getTrait("nav-down-right")` [auto \| self \| <FuncIRI>]	`setTrait("nav-down-right", ...)` [auto \| self \| <FuncIRI>]	"auto"
nav-down-left, attribute	`getTrait("nav-down-left")` [auto \| self \| <FuncIRI>]	`setTrait("nav-down-left", ...)` [auto \| self \| <FuncIRI>]	"auto"
nav-left, attribute	`getTrait("nav-left")` [auto \| self \| <FuncIRI>]	`setTrait("nav-left", ...)` [auto \| self \| <FuncIRI>]	"auto"
offset, attribute	`getFloatTrait("offset")` [0 ≤ `value` ≤ 1]	`setFloatTrait("offset", ...)` [0 ≤ `value` ≤ 1]	0.0
opacity, property	`getFloatTrait("opacity")` [0 ≤ `value` ≤ 1]	`setFloatTrait("opacity", ...)` [0 ≤ `value` ≤ 1] `setTrait("opacity", ...)` [inherit]	1.0
path, attribute	`getPathTrait("path")` [SVGPath]	`setPathTrait("path", ...)` [SVGPath]	An SVGPath object with no path segments	See Accessing rules for path attributes.
points, attribute	`getFloatListTrait("points")`	`setFloatListTrait("points", ...)`
r, attribute	`getFloatTrait("r")` [`value` ≥ 0]	`setFloatTrait("r", ...)` [`value` ≥ 0]	0.5 when accessed on a 'radialGradient' element, 0.0 otherwise
repeatCount, attribute	N/A	`setTrait("repeatCount", ...)`
repeatDur, attribute	N/A	`setTrait("repeatDur", ...)`
restart, attribute	`getTrait("restart")` [always \| whenNotActive \| never]	`setTrait("restart", ...)` [always \| whenNotActive \| never]	"always"
rx, attribute	`getFloatTrait("rx")` [`value` ≥ 0]	`setFloatTrait("rx", ...)` [`value` ≥ 0]	0.0
ry, attribute	`getFloatTrait("ry")` [`value` ≥ 0]	`setFloatTrait("ry", ...)` [`value` ≥ 0]	0.0
snapshotTime, attribute	`getFloatTrait("snapshotTime")` [`value` ≥ 0]	`setFloatTrait("snapshotTime", ...)` [`value` ≥ 0]	0.0
solid-color, property	`getRGBColorTrait("solid-color")` [null, SVGRGBColor]	`setRGBColorTrait("solid-color", ...)` [SVGRGBColor] `setTrait("solid-color", ...)` [<color> \| inherit]	rgb(0,0,0)
solid-opacity, property	`getFloatTrait("solid-opacity")` [0 ≤ `value` ≤ 1]	`setFloatTrait("solid-opacity", ...)` [0 ≤ `value` ≤ 1] `setTrait("solid-opacity")` [inherit]	1.0
stop-color, property	`getRGBColorTrait("stop-color")` [null, SVGRGBColor] `getTrait("stop-color")` [none \| <color>]	`setRGBColorTrait("stop-color", ...)` [SVGRGBColor] `setTrait("stop-color")` [none \| currentColor \| <color> \| inherit]	rgb(0,0,0)
stop-opacity, property	`getFloatTrait("stop-opacity")` [0 ≤ `value` ≤ 1]	`setFloatTrait("stop-opacity", ...)` [0 ≤ `value` ≤ 1] `setTrait("stop-opacity", ...)` [inherit]	1.0
stroke, property	`getRGBColorTrait("stroke")` [null, SVGRGBColor] `getTrait("stroke")` [none \| <FuncIRI> \| <color> \| <system paint>]	`setRGBColorTrait("stroke", ...)` [SVGRGBColor] `setTrait("stroke", ...)` [none \| currentColor \| <FuncIRI> \| <color> \| <system paint> \| inherit]	"none"
stroke-dasharray, property	`getFloatListTrait("stroke-dasharray")` `getTrait("stroke-dasharray")` [none, inherit]	`setFloatListTrait("stroke-dasharray", ...)` `setTrait("stroke-dasharray", ...)` [none, inherit]	"none"
stroke-dashoffset, property	`getFloatTrait("stroke-dashoffset")`	`setFloatTrait("stroke-dashoffset", ...)` `setTrait("stroke-dashoffset", ...)` [inherit]	0.0
stroke-linecap, property	`getTrait("stroke-linecap")` [butt \| round \| square]	`setTrait("stroke-linecap", ...)` [butt \| round \| square \| inherit]	"butt"
stroke-linejoin, property	`getTrait("stroke-linejoin")` [miter \| round \| bevel]	`setTrait("stroke-linejoin", ...)` [miter \| round \| bevel \| inherit]	"miter"
stroke-miterlimit, property	`getFloatTrait("stroke-miterlimit")` [`value` ≥ 1]	`setFloatTrait("stroke-miterlimit")` [`value` ≥ 1] `setTrait("stroke-miterlimit", ...)` [inherit]	4.0
stroke-opacity, property	`getFloatTrait("stroke-opacity")` [0 ≤ `value` ≤ 1]	`setFloatTrait("stroke-opacity", ...)` [0 ≤ `value` ≤ 1] `setTrait("stroke-opacity", ...)` [inherit]	1.0
stroke-width, property	`getFloatTrait("stroke-width")` [`value` ≥ 0]	`setFloatTrait("stroke-width", ...)` [`value` ≥ 0] `setTrait("stroke-width", ...)` [inherit]	1.0
target, attribute	`getTrait("target")`	`setTrait("target", ...)`	"_self"
text-anchor, property	`getTrait("text-anchor")` [start \| middle \| end]	`setTrait("text-anchor", ...)` [start \| middle \| end \| inherit]	"start"
to, attribute	N/A	`setTrait("to", ...)`
transform, attribute	`getMatrixTrait("transform")` [SVGMatrix] `getTrait("transform")` [<transform-list> \| <transform-ref>]	`setMatrixTrait("transform", ...)` [SVGMatrix] `setTrait("transform", ...)` [<transform-list> \| <transform-ref> \| none]	Identity matrix (1,0,0,1,0,0)	See Accessing rules for 'transform' attribute.
type, attribute	`getTrait("type")` [translate \| scale \| rotate \| skewX \| skewY]	`setTrait("type", ...)` [translate \| scale \| rotate \| skewX \| skewY]		These are the trait accessors for the 'type' attribute on the 'animateTransform' element. There are no trait accessors for the 'type' attribute on the 'audio', 'handler', 'image', 'script' and 'video' elements.
values, attribute	N/A	`setTrait("values", ...)`
vector-effect, property	`getTrait("vector-effect")` [none \| non-scaling-stroke]	`setTrait("vector-effect", ...)` [none \| non-scaling-stroke \| inherit]	"none"
version, attribute	`getTrait("version")`	`setTrait("version", ...)`	User agent specific
viewBox, attribute	`getRectTrait("viewBox")` [`null` \| SVGRect]	`setRectTrait("viewBox", ...)` [SVGRect] `setTrait("viewBox", ...)` [none]	`null`	If the 'viewBox' attribute has the value 'none', the `getRectTrait` method will return `null`.
viewport-fill, property	`getRGBColorTrait("viewport-fill")` [null, SVGRGBColor] `getTrait("viewport-fill")` [none \| <color>]	`setRGBColorTrait("viewport-fill", ...)` [SVGRGBColor] `setTrait("viewport-fill", ...)` [none \| currentColor \| <color> \| inherit]	"none"
viewport-fill-opacity, property	`getFloatTrait("viewport-fill-opacity")` [0 ≤ `value` ≤ 1]	`setFloatTrait("viewport-fill-opacity", ...)` [0 ≤ `value` ≤ 1] `setTrait("viewport-fill-opacity", ...)` [inherit]	1.0
visibility, property	`getTrait("visibility")` [visible \| hidden]	`setTrait("visibility", ...)` [visible \| hidden \| inherit]	"visible"
width, attribute	`getFloatTrait("width")` [`value` ≥ 0] `getTrait("width")` ["auto"]	`setFloatTrait("width", ...)` [`value` ≥ 0] `setTrait("width", ...)` ["auto" ]	"auto" when accessed on a 'textArea' element, 0.0 otherwise	See Accessing rules for 'width' and 'height' attributes.
x, attribute	`getFloatTrait("x")` `getFloatListTrait("x")`	`setFloatTrait("x", ...)` `setFloatListTrait("x", ...)`	0.0	See Accessing rules for 'x' and 'y' attributes.
x1, attribute	`getFloatTrait("x1")`	`setFloatTrait("x1", ...)`	0.0
x2, attribute	`getFloatTrait("x2")`	`setFloatTrait("x2", ...)`	1.0 when accessed on a 'linearGradient' element, 0.0 otherwise
xlink:href, attribute	`getTraitNS("http://www.w3.org/1999/xlink", "href")` [absolute IRI]	`setTraitNS("http://www.w3.org/1999/xlink", "href", ...)`	""
y, attribute	`getFloatTrait("y")` `getFloatListTrait("y")`	`setFloatTrait("y", ...)` `setFloatListTrait("y", ...)`	0.0	See Accessing rules for 'x' and 'y' attributes.
y1, attribute	`getFloatTrait("y1")`	`setFloatTrait("y1", ...)`	0.0
y2, attribute	`getFloatTrait("y2")`	`setFloatTrait("y2", ...)`	0.0
zoomAndPan, attribute	`getTrait("zoomAndPan")` [disable \| magnify]	`setTrait("zoomAndPan", ...)` [disable \| magnify]	"magnify"

A.8.14 Additional accessing rules

Accessing rules for 'transform' attribute

The 'transform' attribute in SVG Tiny 1.2 can have three types of values. The "normal" transformation list (e.g. scale, translate, rotate, matrix, etc.), the newly introduced 'ref(svg)' type or 'none'. getMatrixTrait returns the current evaluated matrix in all cases. If the user needs to know that the 'transform' attribute value was a 'ref' or a 'none', getTrait must be used. By using setTrait the user can set the 'transform' attribute to 'ref(svg)' or 'none'.

Accessing rules for 'display' property

Due to backward compatibility reasons the 'display' values accessible via the trait mechanism are limited to 'none' and 'inline', all other values are translated into 'none' or 'inline'. (For a list of all possible 'display' values, see Controlling visibility.) If other 'display' values are of interest, e.g. the user want to set display to 'block', the more generic getAttributeNS/setAttributeNS must be used. Note however that an SVG Tiny 1.2 user agent is allowed to normalize its attribute data as described in Display normalization.

Accessing rules for animation related elements

The following rule applies to SMIL animation elements ('animate', 'animateTransform', 'animateColor', 'animateMotion', 'set' , 'discard').

These elements can be inserted and removed from the tree but they cannot be modified using the TraitAccess methods once inserted into the tree. If an attempt is made to do so, the TraitAccess method will throw a DOMException with code NOT_SUPPORTED_ERR. Modifying the element using the setAttribute and setAttributeNS methods of the Element interface will change the document, but will have no effect on the animation.

This restriction means that if the author wishes to add animations via script, the attributes of the animation elements must be modified before being inserted into the tree. The following is an example of adding an animation to the document, setting the relevant attributes prior to insertion.

Example: Animating via the uDOM

<svg version="1.2" baseProfile="tiny" xmlns="http://www.w3.org/2000/svg" xml:id="svg-root"
      width="100%" height="100%" viewBox="0 0 480 360">
    <rect xml:id="myRect" fill="green" x="10" y="10" width="200" height="100" stroke="black" stroke-width="2"/>
</svg>

A script such as the following Java code might be used to add an animation to the rectangle:

SVGElement newAnimate = (SVGElement)document.createElementNS(svgNS, "animate");
newAnimate.setTrait("attributeName", "fill");
newAnimate.setTrait("from", "red");
newAnimate.setTrait("to", "blue");
newAnimate.setTrait("dur", "5");
newAnimate.setTrait("repeatCount", "10");
Element myRect = document.getElementById("myRect");
myRect.appendChild(newAnimate);

Accessing rules for 'x' and 'y' attributes

If getFloatTrait is used to retrieve the value of the 'x' or 'y' attribute on a 'text' element, where the attribute value has more than one <coordinate>, a DOMException with error code TYPE_MISMATCH_ERR must be raised. When the attribute value has only one coordinate, this is the value returned by getFloatTrait.

If getFloatListTrait or setFloatListTrait are used on elements other than a 'text' element, a DOMException with error code TYPE_MISMATCH_ERR must be raised.

Accessing rules for 'width' and 'height' attributes

If getFloatTrait is used to retrieve the value of the 'width' or 'height' attribute on an 'svg' element, where the value is specified as a percentage or unit value, a DOMException with error code TYPE_MISMATCH_ERR must be raised.

Accessing rules for font properties

If trait accessors are used to get or set the 'font-family', 'font-style' or 'font-weight' properties on a 'font-face' element, a DOMException with error code NOT_SUPPORTED_ERR must be raised.

Accessing rules for path attributes

If the getPathTrait method is used to get an SVGPath and the path attribute was syntactically invalid at some point, the return value must be an SVGPath containing all valid path segments until the point of the error.

Accessing rules for multimedia elements

The following rule applies to multimedia elements ('audio', 'video', 'animation').

SVG timing attributes cannot be modified using the TraitAccess methods once inserted into the tree. If an attempt is made to do so, the TraitAccess method will throw a DOMException with code NOT_SUPPORTED_ERR. Modifying these attributes using the setAttribute and setAttributeNS methods of the Element interface will change the document, but will have no effect on the element.

A.8.15 SVGElement

This interface represents an SVG element in the document tree. It provides methods to traverse elements in the uDOM tree and allows setting and getting the 'id' of an element.

Note: See the definition of 'id' and 'xml:id' for the rules of how to treat 'id' and 'xml:id'.

IDL Definition

interface SVGElement : Element, EventTarget, TraitAccess
{
	attribute DOMString id;
};

No defined constants

Attributes

id

On read, returns the element's 'xml:id' or 'id' attribute according to the rules defined in the Structure chapter, or null if no ID specified.

On write, sets the element's 'xml:id' or 'id' attributes according to the rules defined in the Structure chapter.

No defined methods

A.8.16 SVGTimedElement

This interface represents an SVGTimedElement which is implemented by timed elements and the 'svg' element.

IDL Definition

interface SVGTimedElement : SVGElement, smil::ElementTimeControl
{
	void pauseElement();
	void resumeElement();
	readonly attribute boolean isPaused;
};

No defined constants

Attributes

isPaused: true if the timed element is paused. false otherwise. See Paused element and the active duration ([SMIL21], section 10.4.3). Note that an element that is stopped (has reached the end of its active duration) is not paused.

Methods

pauseElement

Pauses the timed element. See Paused element and the active duration ([SMIL21], section 10.4.3).

No parameters

No return value

No exceptions

resumeElement

Resumes the timed element. See Paused element and the active duration ([SMIL21], section 10.4.3).

No parameters

No return value

No exceptions

A.8.17 SVGAnimationElement

This interface is implemented by the following SMIL animation elements: 'animate', 'animateTransform', 'animateColor', 'animateMotion' and 'set'. It is included for historical reasons and has been deprecated. Note that this interface is unrelated to the new 'animation' element.

IDL Definition

interface SVGAnimationElement : SVGTimedElement
{
};

No defined constants

No defined attributes

No defined methods

A.8.18 SVGVisualMediaElement

This interface represents a media element that is visual, i.e. has a physical location on the screen. It is implemented by: 'animation' and 'video'.

IDL Definition

interface SVGVisualMediaElement : SVGLocatableElement, SVGTimedElement
{
};

No defined constants

No defined attributes

No defined methods

A.8.19 SVGTimer

The SVGTimer interface provides an API for scheduling a one time or repetitive event. A SVGTimer object is always either in the running (attribute running is true) or waiting (attribute running is false) state. After each interval of the timer, an Event of type SVGTimer is triggered.

SVGTimer events are triggered only when the timer is in the running state. The SVGTimer event is limited to the target phase. Since SVGTimer is an EventTarget, EventListeners can be registered on it using addEventListener with SVGTimer as the event type. Event listeners can access their corresponding SVGTimer object through the event object's target property.

SVGTimer instances are created using the createTimer method of the SVGGlobal interface.

IDL Definition

interface SVGTimer : events::EventTarget
{
	attribute long delay;
	attribute long repeatInterval;
	readonly attribute boolean running;
	void start();
	void stop();
};

No defined constants

Attributes

delay: This attribute specifies the time remaining in milliseconds until the next event is fired. When the SVGTimer is in the running state this attribute is dynamically updated to reflect the remaining time in the current interval. When the SVGTimer is waiting the delay reflects the time that remained when stopped. Getting the delay attribute returns the current value, i.e. a snapshot value of the remaining delay. After delay period has passed while the object is in the running state, the SVGTimer object will trigger an Event of type SVGTimer. The delay will then be updated with the repeatInterval value and a new count down will start. Setting the delay resets the current interval to the new value. If this attribute is 0, it means that the event will be triggered as soon as possible. Assigning a negative value is equivalent to calling the stop() method. The initial value is set through the initialInterval parameter in the createTimer method on the SVGGlobal interface, and defines the first interval of the SVGTimer.

repeatInterval: This attribute specifies in milliseconds the interval for each repeat of the SVGTimer, i.e. each timer interval subsequent to the initial interval. The initial value of this attribute is set through the repeatInterval parameter in the createTimer method on the SVGGlobal interface. Assigning a negative value disables the repetitive triggering of the event making it a one time timer which triggers an event after the delay.

running: SVGTimer state. Value is true if the timer is running, false if the timer is waiting. Note that the repeatInterval and delay properties can be non-negative if the timer is stopped (but if delay is negative, the timer is stopped).

Methods

start

Changes the SVGTimer state into running. If the timer is already in the running state, it has no effect. Initially the timer is waiting, and must be started with this method. If the timer delay had a negative value when started, for example if the time had been stopped by setting the delay to a negative value, the delay value is reset to repeatInterval when the this method is called.

No parameters

No return value

No exceptions

stop

Changes the SVGTimer state into waiting. If the timer is already in the waiting state, calling this method has no effect.

No parameters

No return value

No exceptions

A.8.20 SVGGlobal

Many scripted SVG documents in existence make use of functions on a browser specific Window interface. SVG Tiny 1.2 specifies an SVGGlobal interface, on which some of these de facto standard functions are defined, as well as some functions for new features defines in this specification. The SVGGlobal interface must be implemented by the object that represents the default view of the document ([DOM2VIEWS], section 1.1). This object also implements AbstractView. Thus, in the ECMAScript language binding, the global script object implements SVGGlobal. The SVGGlobal object for a document can also be obtained through DocumentView::defaultView.

IDL Definition

interface SVGGlobal
{
	SVGTimer createTimer(in long initialInterval, in long repeatInterval);
	void getURL(in DOMString iri, in AsyncStatusCallback callback);
	void postURL(in DOMString iri, in DOMString data, in AsyncStatusCallback callback, 
	             in DOMString type, in DOMString encoding);
	Node parseXML(in DOMString data, in Document contextDoc);
};

No defined constants

No defined attributes

Methods

createTimer

Creates a SVGTimer with the provided initial and repeat Intervals. The SVGTimer will initially be in the waiting state.

Parameters

in long initialInterval	Specifies the first interval in milliseconds for a repetitive SVGTimer, i.e. sets the initial value of the `delay` attribute on the timer. In the case the `SVGTimer` is not repetitive, it specifies the interval for the one time timer. Setting this parameter with a negative value will create an `SVGTimer` which is in the waiting state.
in long repeatInterval	Specifies the time interval on which the SVGTimer repeats subsequent to the initial interval. A negative value will make the `SVGTimer` a one time timer.

Return value

SVGTimer

The created SVGTimer.

No exceptions

getURL

Given an IRI and an AsyncStatusCallback object on which to call a callback function, this method will attempt to fetch the resource at that IRI. If the IRI uses the HTTP or HTTPS scheme, the HTTP GET method will be used. Implementations may support other schemes, but are not required to.

Processing requirements

This method call must take place asynchronously. When called, control returns immediately to the calling context, and once the request is completed the callback is called. Multiple calls to this method must be executed in FIFO order.

User agents are required to support the gzip content coding for HTTP requests and must decode such content before passing it on to the callback. User agents are not required to support gzip encoding content that they send, though they are encouraged to. Cookies should be supported so that state can be maintained across requests. User agents may provide the user with means to interact with the request (e.g. to enter authentication information) but are not required to.

It is important to note that for security reasons, user agents are strongly encouraged to restrict these requests by origin. When enforcing such restrictions, the callback is called immediately with its AsyncURLStatus object's success field set to false and other fields set to null. Redirection responses (3xx HTTP status codes) must not be exposed through the API but rather they must be processed internally according to the HTTP specification.

Parameters

in DOMString iri	The IRI of the resource that is being requested.
in AsyncStatusCallback callback	The object on which the callback will be called upon completion of the request.

No return value

No exceptions

postURL

Given an IRI, data to be transmitted, an AsyncStatusCallback object on which to call a callback function, a media type, and a content coding, this method will post the data to the specified IRI using the requested media type and content coding. User agents must support postURL being invoked with an HTTP or HTTPS IRI, but may support other IRI schemes if they indicate protocols that are functionally compatible with HTTP. Once the request has been completed the callback is invoked as described in the AsyncStatusCallback interface. If postURL is invoked with an IRI that does not support posting content, or which does not post content in a manner compatible with HTTP, a DOMException with code NOT_SUPPORTED_ERR must be thrown.

Processing requirements are the same as for getURL, with the following notes and additions.

The data passed in does not get any HTML form encoding applied to it, so that applications that wish to transmit content corresponding to what an HTML form would must produce the encoding themselves
When the content type parameter is set then the Content-Type header of the request must be set accordingly. If the syntax of the content type parameter does not match that of a media type, it must be ignored. If this parameter is not specified, then it must default to text/plain.
When the encoding parameter is set then the user agent must encode the submitted data with that HTTP content coding and set the Content-Encoding header accordingly, if it supports it. If it does not support it, then it must ignore it, must not set the Content-Encoding header, and must transmit the data with no encoding. The only required content coding is identity.

Parameters

in DOMString iri	The IRI of the resource that is being requested.
in DOMString data	The data that will be the body of the POST request.
in AsyncStatusCallback callback	The object on which the callback will be called upon completion of the request.
in DOMString type	The content type of the POST request.
in DOMString encoding	The encoding of the POST request.

No return value

No exceptions

parseXML

Given a string and a Document object, parse the string as an XML document and return a Node representing it. If the XML in the string is not well-formed according to either XML 1.0 or XML 1.1 or not namespace-well-formed according to Namespaces in XML 1.0 or Namespaces in XML 1.1 respectively, this method must return a null value.

When parsing the input string, the contextDoc parameter is used only for setting the ownerDocument field in the parsed nodes.

If during parsing a 'script' element is encountered, it must not be executed at that time. It will only be executed if it inserted into the current SVG document.

There is no requirement to load any external resources, e.g. external entities, stylesheets, scripts, raster images, video, audio, etc., for the parsing to complete. XSL stylesheets must not be applied.

If the contextDoc parameter is defined, this method returns an Element object the ownerDocument field of which must be set to be the provided Document object. In effect when the contextDoc parameter is specified the processing must be equivalent to applying the following steps:

parsing the XML into a Document
retrieving its documentElement element
calling importNode on the Document object passed to parseXML with the Element from the previous step as its first parameter and the deep parameter set to true. (Please note that importNode is part of DOM 3 Core but not of the uDOM. It is mentioned here to indicate that the effect must be as if importNode had been used, but not to require that it be supported in implementations.)
return the result of the last step

Parameters

in DOMString data	The data that is to be parsed as XML.
in Document contextDoc	The Document object in the context of which to perform the parsing.

Return value

Node

A Node (either a Document or an Element) representing the content that was parsed.

Exceptions