Chapter 3: Basic Data Types and Interfaces
Contents
3.1. Attribute syntax
In this specification, attributes are defined with an attribute definition
table, which looks like this:
Name |
Value |
Initial value |
Animatable |
exampleattr |
<length> | none |
none |
yes |
In the Value column is a description of the attribute's syntax. There are
five methods for describing an attribute's syntax:
- Using the CSS Value
Definition Syntax [CSS3VALUES].
This is the notation used to define the syntax for most attributes in this
specification and is the default.
- By reference to an
EBNF symbol defined
in this or another specification [XML10]. This is
indicated by [EBNF] appearing in the Value
column.
- By reference to an
ABNF symbol defined
in another specification [STD68]. This is
indicated by [ABNF] appearing in the Value
column.
- As a URL as defined by the URL
Standard [URL]. This is indicated by
[URL] appearing in the Value column.
- In prose, below the attibute definition table. This is indicated by the
text "(see below)" appearing in the Value column.
When a presentation attribute
defined using the CSS Value Definition Syntax is parsed, this is done as
follows:
- Let value be the value of the attribute.
- Let grammar be the grammar given in the attribute definition
table's Value column.
- Replace all instances of <length> in grammar with
[<length> | <number>].
- Replace all instances of <angle> in grammar with
[<angle> | <number>].
- Return the result of
parsing
value with grammar.
The insertion of the <number> symbols allows for
unitless length and angles to be used in presentation attribute while
disallowing them in corresponding property values.
Note that all presentation attributes, since they are
defined by reference to their corresponding CSS properties, are defined using
the CSS Value Definition Syntax.
When any other attribute defined using the CSS Value
Definition Syntax is parsed, this is done by
parsing the
attribute's value according to the grammar given in attribute definition
table.
Note that this allows CSS comments and escapes to be used
in such attributes. For example, a value of '10\px/**/'
would successfully parse as '10px' in
the ‘x’ presentation attribute of the ‘rect’ element.
When an attribute defined as a URL is parsed, this is
done by invoking the
URL parser with
the attribute's value as input and the document's URL as
base [URL].
The Initial value column gives the initial value for the attribute.
When an attribute fails to parse according to the specified CSS Value Definition Syntax,
EBNF or EBNF grammar, or if parsing according to the URL Standard
or by the prose describing how to parse the attribute indicates failure,
the attribute is assumed to have been specified as the given initial value.
The initial value of a presentation attribute is its
corresponding property's initial value. Since the use of an invalid value
in a presentation attribute will be treated as if the initial value
was specified, this value can override values that come from lower priority
style sheet rules, such as those from the user agent style sheet.
For example, although the user agent style sheet sets the value of the
‘overflow
’ property to hidden
for ‘svg’ elements, specifying an invalid presentation attribute such
as overflow="invalid" will result
in a rule setting ‘overflow
’ to visible,
overriding the user agent style sheet value.
The Animatable column indicates whether the attribute can be animated using
animation elements; see the Animation chapter
for details.
The following common definitions are used for attributes that are defined in
terms of an EBNF grammar:
wsp ::= (#x9 | #x20 | #xA | #xC | #xD)
comma-wsp ::= (wsp+ ","? wsp*) | ("," wsp*)
3.2. Real number precision
Unless stated otherwise, numeric values in SVG attributes and in
properties that are defined to have an effect on SVG elements must
support at least all finite IEEE 754 single-precision values.
It is recommended that higher precision floating point
storage and computation be performed on operations such as
coordinate system transformations to provide the best
possible precision and to prevent round-off errors.
Conforming SVG Viewers
are required to perform numerical computation in accordance with their
conformance class, as described in Conformance Criteria.
3.3. Basic DOM interfaces
We need some explicit wording about attributes being "reflected"
using these interfaces.
This should also describe how reflection works for attributes that were
promoted to properties, such as ‘transform
’.
(Some discussion.)
Consider combining the definitions of all the list interfaces;
there is a lot of duplicated text currently.
3.3.1. Interface SVGElement
All of the SVG DOM interfaces that correspond directly to elements in the
SVG language (such as the SVGPathElement interface for the
‘path’ element) derive from the SVGElement interface.
The CSSOM specification
augments
SVGElement with a style IDL attribute, so that the ‘style’
attribute can be accessed in the same way as on HTML elements.
interface SVGElement : Element {
readonly attribute SVGAnimatedString className;
readonly attribute SVGSVGElement? ownerSVGElement;
readonly attribute SVGElement? viewportElement;
attribute long tabIndex;
void focus();
void blur();
};
SVGElement implements GlobalEventHandlers;
-
- className (readonly SVGAnimatedString)
-
This attribute is deprecated and may be removed in a
future version of this specification. Authors are advised to use
Element.classList intead.
Corresponds to attribute ‘class’ on the given element.
- ownerSVGElement (readonly SVGSVGElement)
-
- viewportElement (readonly SVGElement)
-
The element which established the current viewport. Often, the nearest
ancestor
‘svg’ element. Null if the given element is the
outermost svg element.
- tabIndex (long)
-
The tabIndex attribute must
reflect the value of the
tabindex content attribute. Its default value is 0 for elements that are directly focusable, such as through keyboard tabbing in browsers that support that functionality, and −1 for elements that are not focusable without programmatic intervention.
- Operations:
-
- void focus()
-
Focuses the element.
Link to a definition of what the UA has to do to "focus an element" (e.g reference https://html.spec.whatwg.org/multipage/interaction.html#dom-focus).
- void blur()
-
Unfocuses the element. Use of this method is discouraged. Focus another element instead.
Link to a definition of what the UA has to do to "blur an element" (e.g reference https://html.spec.whatwg.org/multipage/interaction.html#dom-blur).
Do not use this method to hide the focus ring. Do not use any other method that hides the focus ring from keyboard users, in particular do not use a CSS rule to override the ‘outline
’ property.
Removal of the focus ring leads to serious accessibility issues for users who navigate and interact with interactive content using the keyboard.
3.3.2. Interface SVGAnimatedBoolean
Used for attributes of type boolean which can be animated.
interface SVGAnimatedBoolean {
attribute boolean baseVal;
readonly attribute boolean animVal;
};
-
- baseVal (boolean)
-
The base value of the given attribute before applying any animations.
- animVal (readonly boolean)
-
If the given attribute or property is being animated, contains the
current animated value of the attribute or property. If the given
attribute or property is not currently being animated, contains the
same value as
baseVal.
3.3.3. Interface SVGAnimatedString
Used for attributes of type DOMString which can be animated.
interface SVGAnimatedString {
attribute DOMString baseVal;
readonly attribute DOMString animVal;
};
-
- baseVal (DOMString)
-
The base value of the given attribute before applying any animations.
- animVal (readonly DOMString)
-
If the given attribute or property is being animated, contains the
current animated value of the attribute or property. If the given
attribute or property is not currently being animated, contains the
same value as
baseVal.
3.3.4. Interface SVGStringList
This interface defines a list of DOMString values.
SVGStringList has the same attributes and methods as other
SVGxxxList interfaces.
The supported property indices
of an SVGStringList object is all non-negative integers less than
the length of the list.
interface SVGStringList {
readonly attribute unsigned long length;
readonly attribute unsigned long numberOfItems;
void clear();
DOMString initialize(DOMString newItem);
getter DOMString getItem(unsigned long index);
DOMString insertItemBefore(DOMString newItem, unsigned long index);
DOMString replaceItem(DOMString newItem, unsigned long index);
DOMString removeItem(unsigned long index);
DOMString appendItem(DOMString newItem);
setter void (unsigned long index, DOMString newItem);
};
-
- length (readonly unsigned long)
-
The number of items in the list.
- numberOfItems (readonly unsigned long)
-
The number of items in the list.
-
- void clear()
-
Clears all existing current items from the list, with the result being
an empty list.
-
- DOMException, code NO_MODIFICATION_ALLOWED_ERR
- Raised when the list
cannot be modified.
- DOMString initialize(DOMString newItem)
-
Clears all existing current items from the list and re-initializes the
list to hold the single item specified by the parameter.
-
-
DOMString newItem
The item which should become the only member of the list.
-
The item being inserted into the list.
-
- DOMException, code NO_MODIFICATION_ALLOWED_ERR
- Raised when the list
cannot be modified.
- DOMString getItem(unsigned long index)
-
Returns the specified item from the list.
-
-
unsigned long index
The index of the item from the list which is to be
returned. The first item is number 0.
-
The selected item.
-
- DOMException, code INDEX_SIZE_ERR
- Raised if the index number is
greater than or equal to numberOfItems.
- DOMString insertItemBefore(DOMString newItem, unsigned long index)
-
Inserts a new item into the list at the specified position. The first
item is number 0.
-
-
DOMString newItem
The item which is to be inserted into the list.
-
unsigned long index
The index of the item before which the new item is to be
inserted. The first item is number 0. If the index is equal to 0,
then the new item is inserted at the front of the list. If the index
is greater than or equal to
numberOfItems, then the new item is
appended to the end of the list.
-
The inserted item.
-
- DOMException, code NO_MODIFICATION_ALLOWED_ERR
- Raised when the list
cannot be modified.
- DOMString replaceItem(DOMString newItem, unsigned long index)
-
Replaces an existing item in the list with a new item.
-
-
DOMString newItem
The item which is to be inserted into the list.
-
unsigned long index
The index of the item which is to be replaced. The first
item is number 0.
-
The inserted item.
-
- DOMException, code NO_MODIFICATION_ALLOWED_ERR
- Raised when the list
cannot be modified.
- DOMException, code INDEX_SIZE_ERR
- Raised if the index number is
greater than or equal to numberOfItems.
- DOMString removeItem(unsigned long index)
-
Removes an existing item from the list.
-
-
unsigned long index
The index of the item which is to be removed. The first
item is number 0.
-
The removed item.
-
- DOMException, code NO_MODIFICATION_ALLOWED_ERR
- Raised when the list
cannot be modified.
- DOMException, code INDEX_SIZE_ERR
- Raised if the index number is
greater than or equal to numberOfItems.
- DOMString appendItem(DOMString newItem)
-
Inserts a new item at the end of the list.
-
-
DOMString newItem
The item which is to be inserted. The first item is
number 0.
-
The inserted item.
-
- DOMException, code NO_MODIFICATION_ALLOWED_ERR
- Raised when the list
cannot be modified.
- setter void (unsigned long index, DOMString newItem)
-
Replaces the item at index index with newItem.
3.3.5. Interface SVGAnimatedEnumeration
Used for attributes whose value must be a constant from a particular
enumeration and which can be animated.
interface SVGAnimatedEnumeration {
attribute unsigned short baseVal;
readonly attribute unsigned short animVal;
};
-
- baseVal (unsigned short)
-
The base value of the given attribute before applying any animations.
- animVal (readonly unsigned short)
-
If the given attribute or property is being animated, contains the
current animated value of the attribute or property. If the given
attribute or property is not currently being animated, contains the
same value as
baseVal.
3.3.6. Interface SVGAnimatedInteger
Used for attributes of basic type
<integer> which can be
animated.
interface SVGAnimatedInteger {
attribute long baseVal;
readonly attribute long animVal;
};
-
- baseVal (long)
-
The base value of the given attribute before applying any animations.
- animVal (readonly long)
-
If the given attribute or property is being animated, contains the
current animated value of the attribute or property. If the given
attribute or property is not currently being animated, contains the
same value as
baseVal.
3.3.7. Interface SVGNumber
Used for attributes of basic type
<number>.
interface SVGNumber {
attribute float value;
};
-
- value (float)
-
The value of the given attribute.
3.3.8. Interface SVGAnimatedNumber
Used for attributes of basic type
<number> which can be
animated.
interface SVGAnimatedNumber {
attribute float baseVal;
readonly attribute float animVal;
};
-
- baseVal (float)
-
The base value of the given attribute before applying any animations.
- animVal (readonly float)
-
If the given attribute or property is being animated, contains the
current animated value of the attribute or property. If the given
attribute or property is not currently being animated, contains the
same value as
baseVal.
3.3.9. Interface SVGNumberList
This interface defines a list of SVGNumber objects.
SVGNumberList has the same attributes and methods as other
SVGxxxList interfaces.
The supported property indices
of an SVGNumberList object is all non-negative integers less than
the length of the list.
An SVGNumberList object can be designated as read only,
which means that attempts to modify the object will result in an exception
being thrown, as described below.
interface SVGNumberList {
readonly attribute unsigned long length;
readonly attribute unsigned long numberOfItems;
void clear();
SVGNumber initialize(SVGNumber newItem);
getter SVGNumber getItem(unsigned long index);
SVGNumber insertItemBefore(SVGNumber newItem, unsigned long index);
SVGNumber replaceItem(SVGNumber newItem, unsigned long index);
SVGNumber removeItem(unsigned long index);
SVGNumber appendItem(SVGNumber newItem);
setter void (unsigned long index, SVGNumber newItem);
};
-
- length (readonly unsigned long)
-
The number of items in the list.
- numberOfItems (readonly unsigned long)
-
The number of items in the list.
-
- void clear()
-
Clears all existing current items from the list, with the result being
an empty list.
-
- DOMException, code NO_MODIFICATION_ALLOWED_ERR
- Raised when the list is
read only.
- SVGNumber initialize(SVGNumber newItem)
-
Clears all existing current items from the list and re-initializes the
list to hold a single item specified by the parameter. If
newItem
is in a list, then a new
SVGNumber object is created with the same
values as
newItem and this item is inserted into the list.
Otherwise,
newItem itself is inserted into the list.
-
-
The item which should become the only member of the list.
-
The item being inserted into the list.
-
- DOMException, code NO_MODIFICATION_ALLOWED_ERR
- Raised when the list is
read only.
- SVGNumber getItem(unsigned long index)
-
Returns the specified item from the list. The returned item is the
item itself and not a copy. Any changes made to the item are
immediately reflected in the list.
-
-
unsigned long index
The index of the item from the list which is to be
returned. The first item is number 0.
-
The selected item.
-
- DOMException, code INDEX_SIZE_ERR
- Raised if the index number is
greater than or equal to numberOfItems.
- SVGNumber insertItemBefore(SVGNumber newItem, unsigned long index)
-
Inserts a new item into the list at the specified position. The first
item is number 0. If
newItem is already in a list, then
a new
SVGNumber object is created with the same values as
newItem and this item is inserted into the list. Otherwise,
newItem itself is inserted into the list.
-
-
The item which is to be inserted into the list.
-
unsigned long index
The index of the item before which the new item is to be
inserted. The first item is number 0. If the index is equal to 0,
then the new item is inserted at the front of the list. If the index
is greater than or equal to
numberOfItems, then the new item is
appended to the end of the list.
-
The inserted item.
-
- DOMException, code NO_MODIFICATION_ALLOWED_ERR
- Raised when the list is
read only.
- SVGNumber replaceItem(SVGNumber newItem, unsigned long index)
-
Replaces an existing item in the list with a new item. If
newItem is already in a list, then a new
SVGNumber
object is created with the same values as
newItem and
this item is inserted into the list. Otherwise,
newItem
itself is inserted into the list.
-
-
The item which is to be inserted into the list.
-
unsigned long index
The index of the item which is to be replaced. The first
item is number 0.
-
The inserted item.
-
- DOMException, code NO_MODIFICATION_ALLOWED_ERR
- Raised when the list is
read only.
- DOMException, code INDEX_SIZE_ERR
- Raised if the index number is
greater than or equal to numberOfItems.
- SVGNumber removeItem(unsigned long index)
-
Removes an existing item from the list.
-
-
unsigned long index
The index of the item which is to be removed. The first
item is number 0.
-
The removed item.
-
- DOMException, code NO_MODIFICATION_ALLOWED_ERR
- Raised when the list
cannot be modified.
- DOMException, code INDEX_SIZE_ERR
- Raised if the index number is
greater than or equal to numberOfItems.
- SVGNumber appendItem(SVGNumber newItem)
-
Inserts a new item at the end of the list. If
newItem is
already in a list, then a new
SVGNumber object is created
with the same values as
newItem and this item is inserted
into the list. Otherwise,
newItem itself is inserted into
the list.
-
-
The item which is to be inserted. The first item is
number 0.
-
The inserted item.
-
- DOMException, code NO_MODIFICATION_ALLOWED_ERR
- Raised when the list
cannot be modified.
- setter void (unsigned long index, SVGNumber newItem)
-
3.3.10. Interface SVGAnimatedNumberList
Used for attributes which take a list of numbers and which can be animated.
interface SVGAnimatedNumberList {
readonly attribute SVGNumberList baseVal;
readonly attribute SVGNumberList animVal;
};
-
- baseVal (readonly SVGNumberList)
-
The base value of the given attribute before applying any animations.
- animVal (readonly SVGNumberList)
-
A
read only SVGNumberList representing the current animated value of
the given attribute. If the given attribute is not currently being
animated, then the
SVGNumberList will have the same contents
as
baseVal. The object referenced by
animVal will always
be distinct from the one referenced by
baseVal, even when
the attribute is not animated.
3.3.11. Interface SVGLength
The SVGLength interface corresponds to the
<length> and
<percentage> basic data types,
and represents a length or percentage that consists of a numerical factor and a unit,
where the unit is one of the set of units described in
Units (em, ex, px, pt, pc, cm, mm and in),
a percentage, a unitless number (user units), or "unknown".
An SVGLength object can be designated as read only,
which means that attempts to modify the object will result in an exception
being thrown, as described below.
An SVGLength object can be associated
with a particular element, as well as being designated with a directionality:
horizontal, vertical or unspecified. The associated element and the directionality of the
length are used to resolve percentage values to user units. Unless otherwise
described, an SVGLength object is not associated with any element and
has unspecified directionality.
We need to define the behavior of converting values from/to percentages
when the viewport width/height/size is zero.
(ACTION-3722 on Cameron.)
The use of numeric length unit type constants is an anti-pattern and
new constant values will not be introduced for any other units or length types supported by
SVGLength. If other types of lengths are supported and used, the SVGLength
uses the SVG_LENGTHTYPE_UNKNOWN
unit type. See below for details on how the other properties of an SVGLength
operate with these types of lengths.
interface SVGLength {
// Length Unit Types
const unsigned short SVG_LENGTHTYPE_UNKNOWN = 0;
const unsigned short SVG_LENGTHTYPE_NUMBER = 1;
const unsigned short SVG_LENGTHTYPE_PERCENTAGE = 2;
const unsigned short SVG_LENGTHTYPE_EMS = 3;
const unsigned short SVG_LENGTHTYPE_EXS = 4;
const unsigned short SVG_LENGTHTYPE_PX = 5;
const unsigned short SVG_LENGTHTYPE_CM = 6;
const unsigned short SVG_LENGTHTYPE_MM = 7;
const unsigned short SVG_LENGTHTYPE_IN = 8;
const unsigned short SVG_LENGTHTYPE_PT = 9;
const unsigned short SVG_LENGTHTYPE_PC = 10;
readonly attribute unsigned short unitType;
attribute float value;
attribute float valueInSpecifiedUnits;
attribute DOMString valueAsString;
void newValueSpecifiedUnits(unsigned short unitType, float valueInSpecifiedUnits);
void convertToSpecifiedUnits(unsigned short unitType);
};
-
- SVG_LENGTHTYPE_UNKNOWN (unsigned short)
-
The unit type is not one of predefined unit types. It is invalid to
attempt to define a new value of this type or to attempt to switch an
existing value to this type.
- SVG_LENGTHTYPE_NUMBER (unsigned short)
-
No unit type was provided (i.e., a unitless value was specified), which
indicates a value in user units.
- SVG_LENGTHTYPE_PERCENTAGE (unsigned short)
-
A percentage value was specified.
- SVG_LENGTHTYPE_EMS (unsigned short)
-
A value was specified using the em units defined in CSS 2.1.
- SVG_LENGTHTYPE_EXS (unsigned short)
-
A value was specified using the ex units defined in CSS 2.1.
- SVG_LENGTHTYPE_PX (unsigned short)
-
A value was specified using the px units defined in CSS 2.1.
- SVG_LENGTHTYPE_CM (unsigned short)
-
A value was specified using the cm units defined in CSS 2.1.
- SVG_LENGTHTYPE_MM (unsigned short)
-
A value was specified using the mm units defined in CSS 2.1.
- SVG_LENGTHTYPE_IN (unsigned short)
-
A value was specified using the in units defined in CSS 2.1.
- SVG_LENGTHTYPE_PT (unsigned short)
-
A value was specified using the pt units defined in CSS 2.1.
- SVG_LENGTHTYPE_PC (unsigned short)
-
A value was specified using the pc units defined in CSS 2.1.
-
- unitType (readonly unsigned short)
-
The type of the value as specified by one of the SVG_LENGTHTYPE_*
constants defined on this interface.
The SVG_LENGTHTYPE_UNKNOWN unit type is returned when the
length value uses a unit that does not correspond to one of the
integer constants, such as ch, or is a
non-scalar value, such as a calc()
value.
- value (float)
-
The value of the length in user units.
On getting, returns the value converted to user units.
If the length cannot be converted to user units,
for example because it is a percentage with no
basis against which to resolve the percentage,
then the value of valueInSpecifiedUnits
is returned.
For example, (new SVGLength("10%")).value
evalutes to 10, since the SVGLength is not associated with
an element and thus has no percentage basis to resolve against.
On setting, sets the numerical factor to the assigned value and
the unit type to user units.
-
- DOMException, code NO_MODIFICATION_ALLOWED_ERR
- Raised when the length is read only.
- valueInSpecifiedUnits (float)
-
The numerical factor of the length value.
On getting, returns the numerical factor
if the length is a scalar value (such as '20px'
or '50%'), or
returns 0 if the length is not a scalar value (such as a
calc() value).
On setting, modifies the numerical factor of
the length value using the same unit. If the length
not a scalar value, then assigning to
valueInSpecifiedUnits
sets the length to be the specified number of
user units.
-
- DOMException, code NO_MODIFICATION_ALLOWED_ERR
- Raised when the length is read only.
- valueAsString (DOMString)
-
The length value as a string. On getting, returns a
string as follows:
- If the unit type of the length is unknown or user units,
the string is simply the numeric factor converted to a string.
- If the unit type of the length is a percentage, the string
is the result of concatenating the numeric factor converted to a string
with the string "%".
- Otherwise, the string is the result of concatenating the numeric
factor converted to a string with the CSS length unit in lowercase.
What about serializing non-scalar values, such
as calc() values?
On setting, updates the numeric factor and units type of the
SVGLength object according to the result of parsing the
assigned string as a <length> or <percentage>.
-
- DOMException, code SYNTAX_ERR
- Raised if the assigned string cannot be parsed as a valid <length> or <percentage>.
- DOMException, code NO_MODIFICATION_ALLOWED_ERR
- Raised when the length is read only.
-
- void newValueSpecifiedUnits(unsigned short unitType, float valueInSpecifiedUnits)
-
Sets the numeric factor of the length value to valueInSpecifiedUnits
and the unit type to unitType.
-
-
unsigned short unitType
-
float valueInSpecifiedUnits
The new value.
-
- DOMException, code NOT_SUPPORTED_ERR
- Raised if unitType is SVG_LENGTHTYPE_UNKNOWN
or not a valid unit type constant (one of the other SVG_LENGTHTYPE_* constants
defined on this interface).
- DOMException, code NO_MODIFICATION_ALLOWED_ERR
- Raised when the length is read only.
- void convertToSpecifiedUnits(unsigned short unitType)
-
Sets the unit type of the length value to the type specified by
unitType and sets the numeric factor value such that it
represents the same absolute length.
For example, if the original value were "0.5cm" and the method was
invoked to convert to millimeters, then unitType would return
SVG_LENGTHTYPE_MM and valueInSpecifiedUnits would return the
numeric value 5.
If the old or new unit type
is percentage and the SVGLength object has no associated
element, then the percentages are considered to resolve against
a length of 100 user units. For example, converting an SVGLength
whose value is 20px to a percentage will result in the value being 20%.
-
-
unsigned short unitType
-
- DOMException, code NOT_SUPPORTED_ERR
- Raised if unitType is SVG_LENGTHTYPE_UNKNOWN
or not a valid unit type constant (one of the other SVG_LENGTHTYPE_* constants
defined on this interface).
- DOMException, code NO_MODIFICATION_ALLOWED_ERR
- Raised when the length is read only.
3.3.12. Interface SVGAnimatedLength
Used for attributes of basic type
<length> which can be
animated.
interface SVGAnimatedLength {
readonly attribute SVGLength baseVal;
readonly attribute SVGLength animVal;
};
-
- baseVal (readonly SVGLength)
-
The base value of the given attribute before applying any animations.
- animVal (readonly SVGLength)
-
A
read only SVGLength representing the current animated value of
the given attribute. If the given attribute is not currently being
animated, then the
SVGLength will have the same contents
as
baseVal. The object referenced by
animVal will always
be distinct from the one referenced by
baseVal, even when
the attribute is not animated.
3.3.13. Interface SVGLengthList
This interface defines a list of SVGLength objects.
SVGLengthList has the same attributes and methods as other
SVGxxxList interfaces.
The supported property indices
of an SVGLengthList object is all non-negative integers less than
the length of the list.
An SVGLengthList object can be designated as read only,
which means that attempts to modify the object will result in an exception
being thrown, as described below.
interface SVGLengthList {
readonly attribute unsigned long length;
readonly attribute unsigned long numberOfItems;
void clear();
SVGLength initialize(SVGLength newItem);
getter SVGLength getItem(unsigned long index);
SVGLength insertItemBefore(SVGLength newItem, unsigned long index);
SVGLength replaceItem(SVGLength newItem, unsigned long index);
SVGLength removeItem(unsigned long index);
SVGLength appendItem(SVGLength newItem);
setter void (unsigned long index, SVGLength newItem);
};
-
- length (readonly unsigned long)
-
The number of items in the list.
- numberOfItems (readonly unsigned long)
-
The number of items in the list.
-
- void clear()
-
Clears all existing current items from the list, with the result being
an empty list.
-
- DOMException, code NO_MODIFICATION_ALLOWED_ERR
- Raised when the list is
read only.
- SVGLength initialize(SVGLength newItem)
-
Clears all existing current items from the list and re-initializes the
list to hold a single item specified by the parameter. If
newItem
is in a list, then a new
SVGLength object is created with the same
values as
newItem and this item is inserted into the list.
Otherwise,
newItem itself is inserted into the list.
-
-
The item which should become the only member of the list.
-
The item being inserted into the list.
-
- DOMException, code NO_MODIFICATION_ALLOWED_ERR
- Raised when the list is
read only.
- SVGLength getItem(unsigned long index)
-
Returns the specified item from the list. The returned item is the
item itself and not a copy. Any changes made to the item are
immediately reflected in the list.
-
-
unsigned long index
The index of the item from the list which is to be
returned. The first item is number 0.
-
The selected item.
-
- DOMException, code NO_MODIFICATION_ALLOWED_ERR
- Raised when the list is
read only.
- SVGLength insertItemBefore(SVGLength newItem, unsigned long index)
-
Inserts a new item into the list at the specified position. The first
item is number 0. If
newItem is already in a list, then
a new
SVGLength object is created with the same values as
newItem and this item is inserted into the list. Otherwise,
newItem itself is inserted into the list.
-
-
The item which is to be inserted into the list.
-
unsigned long index
The index of the item before which the new item is to be
inserted. The first item is number 0. If the index is equal to 0,
then the new item is inserted at the front of the list. If the index
is greater than or equal to
numberOfItems, then the new item is
appended to the end of the list.
-
The inserted item.
-
- DOMException, code NO_MODIFICATION_ALLOWED_ERR
- Raised when the list is
read only.
- SVGLength replaceItem(SVGLength newItem, unsigned long index)
-
Replaces an existing item in the list with a new item. If
newItem is already in a list, then a new
SVGLength
object is created with the same values as
newItem and
this item is inserted into the list. Otherwise,
newItem
itself is inserted into the list.
-
-
The item which is to be inserted into the list.
-
unsigned long index
The index of the item which is to be replaced. The first
item is number 0.
-
The inserted item.
-
- DOMException, code NO_MODIFICATION_ALLOWED_ERR
- Raised when the list is
read only.
- DOMException, code INDEX_SIZE_ERR
- Raised if the index number is
greater than or equal to numberOfItems.
- SVGLength removeItem(unsigned long index)
-
Removes an existing item from the list.
-
-
unsigned long index
The index of the item which is to be removed. The first
item is number 0.
-
The removed item.
-
- DOMException, code NO_MODIFICATION_ALLOWED_ERR
- Raised when the list is
read only.
- DOMException, code INDEX_SIZE_ERR
- Raised if the index number is
greater than or equal to numberOfItems.
- SVGLength appendItem(SVGLength newItem)
-
Inserts a new item at the end of the list. If
newItem is
already in a list, then a new
SVGLength object is created
with the same values as
newItem and this item is inserted
into the list. Otherwise,
newItem itself is inserted into
the list.
-
-
The item which is to be inserted. The first item is
number 0.
-
The inserted item.
-
- DOMException, code NO_MODIFICATION_ALLOWED_ERR
- Raised when the list is
read only.
- setter void (unsigned long index, SVGLength newItem)
-
3.3.14. Interface SVGAnimatedLengthList
Used for attributes of type SVGLengthList which can be animated.
interface SVGAnimatedLengthList {
readonly attribute SVGLengthList baseVal;
readonly attribute SVGLengthList animVal;
};
-
- baseVal (readonly SVGLengthList)
-
The base value of the given attribute before applying any animations.
- animVal (readonly SVGLengthList)
-
A
read only SVGLengthList representing the current animated value of
the given attribute. If the given attribute is not currently being
animated, then the
SVGLengthList will have the same contents
as
baseVal. The object referenced by
animVal will always
be distinct from the one referenced by
baseVal, even when
the attribute is not animated.
3.3.15. Interface SVGAngle
The SVGAngle interface corresponds to the
<angle> basic data type,
and represents an angle that consists of a numerical factor and a unit,
where the unit is degrees, radians, grads, unitless numbers or "unknown".
An SVGAngle object can be designated as read only,
which means that attempts to modify the object will result in an exception
being thrown, as described below.
The use of numeric angle unit type constants is an anti-pattern and
new constant values will not be introduced for any other units or angle types supported by
SVGAngle. If other types of angles are supported and used, the SVGAngle
uses the SVG_ANGLETYPE_UNKNOWN
unit type. See below for details on how the other properties of an SVGAngle
operate with these types of angles.
interface SVGAngle {
// Angle Unit Types
const unsigned short SVG_ANGLETYPE_UNKNOWN = 0;
const unsigned short SVG_ANGLETYPE_UNSPECIFIED = 1;
const unsigned short SVG_ANGLETYPE_DEG = 2;
const unsigned short SVG_ANGLETYPE_RAD = 3;
const unsigned short SVG_ANGLETYPE_GRAD = 4;
readonly attribute unsigned short unitType;
attribute float value;
attribute float valueInSpecifiedUnits;
attribute DOMString valueAsString;
void newValueSpecifiedUnits(unsigned short unitType, float valueInSpecifiedUnits);
void convertToSpecifiedUnits(unsigned short unitType);
};
-
- SVG_ANGLETYPE_UNKNOWN (unsigned short)
-
The unit type is not one of predefined unit types. It is invalid to
attempt to define a new value of this type or to attempt to switch an
existing value to this type.
- SVG_ANGLETYPE_UNSPECIFIED (unsigned short)
-
No unit type was provided (i.e., a unitless value was specified). For
angles, a unitless value is treated the same as if degrees were
specified.
- SVG_ANGLETYPE_DEG (unsigned short)
-
The unit type was explicitly set to degrees.
- SVG_ANGLETYPE_RAD (unsigned short)
-
The unit type is radians.
- SVG_ANGLETYPE_GRAD (unsigned short)
-
The unit type is grads.
-
- unitType (readonly unsigned short)
-
The type of the value as specified by one of the SVG_ANGLETYPE_*
constants defined on this interface.
The SVG_ANGLETYPE_UNKNOWN unit type is returned when the
length value uses a unit that does not correspond to one of the
integer constants, such as turn.
- value (float)
-
The value of the angle in degrees.
On getting, returns the value converted to degrees. If
the type of the
SVGAngle is unknown, the numerical factor
of the angle is returned. On setting, sets the numerical
factor to the assigned value and the unit type to unitless numbers.
-
- DOMException, code NO_MODIFICATION_ALLOWED_ERR
- Raised when the angle is read only.
- valueInSpecifiedUnits (float)
-
The numerical factor of the angle value.
-
- DOMException, code NO_MODIFICATION_ALLOWED_ERR
- Raised when the angle is read only.
- valueAsString (DOMString)
-
The angle value as a string. On getting, returns a
string as follows:
- If the unit type of the angle is unknown or unitless numbers,
the string is simply the numeric factor converted to a string.
- Otherwise, the string is the result of concatenating the numeric
factor converted to a string with the CSS angle unit in lowercase.
On setting, updates the numeric factor and units type of the
SVGAngle object according to the result of parsing the
assigned string as an <angle>.
-
- DOMException, code SYNTAX_ERR
- Raised if the assigned string cannot be parsed as a valid <angle>.
- DOMException, code NO_MODIFICATION_ALLOWED_ERR
- Raised when the angle is read only.
-
- void newValueSpecifiedUnits(unsigned short unitType, float valueInSpecifiedUnits)
-
Sets the numeric factor of the angle value to valueInSpecifiedUnits
and the unit type to unitType.
-
-
unsigned short unitType
-
float valueInSpecifiedUnits
The new value.
-
- DOMException, code NOT_SUPPORTED_ERR
- Raised if unitType is SVG_ANGLETYPE_UNKNOWN
or not a valid unit type constant (one of the other SVG_ANGLETYPE_* constants
defined on this interface).
- DOMException, code NO_MODIFICATION_ALLOWED_ERR
- Raised when the angle is read only.
- void convertToSpecifiedUnits(unsigned short unitType)
-
Sets the unit type of the angle value to the type specified by
unitType and sets the numeric factor value such that it
represents the same absolute angle.
For example, if the original value were "180deg" and the method was
invoked to convert to radians, then unitType would return
SVG_ANGLETYPE_RAD and valueInSpecifiedUnits would return the
numeric value π.
-
-
unsigned short unitType
-
- DOMException, code NOT_SUPPORTED_ERR
- Raised if unitType is SVG_ANGLETYPE_UNKNOWN
or not a valid unit type constant (one of the other SVG_ANGLETYPE_* constants
defined on this interface).
- DOMException, code NO_MODIFICATION_ALLOWED_ERR
- Raised when the angle is read only.
3.3.16. Interface SVGAnimatedAngle
Used for attributes of basic data type <angle>
that can be animated.
interface SVGAnimatedAngle {
readonly attribute SVGAngle baseVal;
readonly attribute SVGAngle animVal;
};
-
- baseVal (readonly SVGAngle)
-
The base value of the given attribute before applying any animations.
- animVal (readonly SVGAngle)
-
A
read only SVGAngle representing the current animated value of
the given attribute. If the given attribute is not currently being
animated, then the
SVGAngle will have the same contents
as
baseVal. The object referenced by
animVal will always
be distinct from the one referenced by
baseVal, even when
the attribute is not animated.
3.3.17. Interface SVGAnimatedRect
Used for attributes of type DOMRect which can be animated.
interface SVGAnimatedRect {
readonly attribute DOMRectReadOnly baseVal;
readonly attribute DOMRectReadOnly animVal;
};
-
- baseVal (readonly DOMRectReadOnly)
-
The base value of the given attribute before applying any animations.
- animVal (readonly DOMRectReadOnly)
-
A
DOMRectReadOnly representing the current animated value of
the given attribute. If the given attribute is not currently being
animated, then the
DOMRectReadOnly will have the same contents
as
baseVal. The object referenced by
animVal will always
be distinct from the one referenced by
baseVal, even when
the attribute is not animated.
3.3.18. Interface SVGUnitTypes
The SVGUnitTypes interface defines a commonly used set of constants
and is a base interface used by SVGGradientElement,
SVGPatternElement, SVGClipPathElement, SVGMaskElement
and SVGFilterElement.
[NoInterfaceObject]
interface SVGUnitTypes {
// Unit Types
const unsigned short SVG_UNIT_TYPE_UNKNOWN = 0;
const unsigned short SVG_UNIT_TYPE_USERSPACEONUSE = 1;
const unsigned short SVG_UNIT_TYPE_OBJECTBOUNDINGBOX = 2;
};
-
- SVG_UNIT_TYPE_UNKNOWN (unsigned short)
-
The type is not one of predefined types. It is invalid to attempt to
define a new value of this type or to attempt to switch an existing
value to this type.
- SVG_UNIT_TYPE_USERSPACEONUSE (unsigned short)
-
Corresponds to value 'userSpaceOnUse'.
- SVG_UNIT_TYPE_OBJECTBOUNDINGBOX (unsigned short)
-
Corresponds to value 'objectBoundingBox'.
3.3.19. Interface SVGGraphicsElement
Interface SVGGraphicsElement represents SVG elements whose primary purpose
is to directly render graphics into a group. The
‘transform
’ property applies to all SVGGraphicsElement. All SVGGraphicsElement
have a bounding box in current local coordinate system.
dictionary SVGBoundingBoxOptions {
boolean fill = true;
boolean stroke = false;
boolean markers = false;
boolean clipped = false;
};
interface SVGGraphicsElement : SVGElement {
readonly attribute SVGAnimatedTransformList transform;
DOMRect getBBox(optional SVGBoundingBoxOptions options);
DOMMatrix? getCTM();
DOMMatrix? getScreenCTM();
DOMMatrix getTransformToElement(SVGGraphicsElement element);
};
SVGGraphicsElement implements SVGTests;
-
- transform (readonly SVGAnimatedTransformList)
-
Corresponds to attribute ‘
transform
’ on the given element.
This needs to be updated to reflect the value of the ‘transform
’
property.
-
- DOMRect getBBox(optional SVGBoundingBoxOptions options)
-
Returns the result of invoking the bounding box algorithm
for the element, with fill, stroke, markers
and clipped members of the options dictionary argument
used to control which parts of the element are included in the bounding box,
using the element's local coordinate system as the coordinate system to return the
bounding box in.
-
An
DOMRect object that defines the bounding box.
- DOMMatrix? getCTM()
-
Returns the transformation matrix from current user units (i.e., after
application of the ‘
transform
’ property) to the viewport
coordinate system for the nearest viewport element (
CTM). Note that null
is returned if this element is not hooked into the document tree.
What is the expected result if you call getCTM on an ‘svg’ element?
See thread. Also see example.
(ACTION-3724 on Dirk.)
-
- DOMMatrix? getScreenCTM()
-
Returns the transformation matrix from current user units (i.e., after
application of the ‘
transform
’ property) to the parent
user agent's notion of a "pixel". For display devices, ideally this
represents a physical screen pixel. For other devices or environments
where physical pixel sizes are not known, then an algorithm similar to
the CSS 2.1 definition of a "pixel" can be used instead. 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.
Should this take into account the 'transform' on the ‘svg’ element itself?
See example. Chrome/Opera/IE: returns the identity matrix for this example,
Firefox: difference between transform style and attribute, and is not an identity matrix.
-
An
DOMMatrix object that defines the given
transformation matrix.
- DOMMatrix getTransformToElement(SVGGraphicsElement element)
-
-
-
The target element.
-
An
DOMMatrix object that defines the transformation.
-
- InvalidStateError
- Raised if the currently
defined transformation matrices make it impossible to compute the
given matrix (e.g., because one of the transformations is singular).
3.3.20. Interface SVGGeometryElement
Interface SVGGeometryElement represents SVG elements whose rendering
is defined by geometry and which can be filled and stroked. This includes
paths, text and the basic shapes.
interface SVGGeometryElement : SVGGraphicsElement {
boolean isPointInFill(DOMPoint point);
boolean isPointInStroke(DOMPoint point);
};
-
- boolean isPointInFill(DOMPoint point)
- Returns whether the specified point is within the fill of the element.
Normal hit testing rules apply; the value of the ‘
pointer-events
’
property on the element determines whether a point is considered to be
within the fill.
-
-
The point to check for intersection with the fill
of this element. The
DOMPoint is interpreted as a
as a point in the local coordinate system of this element.
- true if the point is within the fill of this shape,
or false otherwise.
- boolean isPointInStroke(DOMPoint point)
- Returns whether the specified point is within the stroke of the element.
Normal hit testing rules apply; the value of the ‘
pointer-events
’
property on the element determines whether a point is considered to be
within the stroke.
-
-
The point to check for intersection with the stroke
of this element. The
DOMPoint is interpreted as a
as a point in the local coordinate system of this element.
- true if the point is within the stroke of this shape,
or false otherwise.
3.3.21. Interface SVGTests
Interface SVGTests defines an interface which applies to all
elements which have attributes
‘requiredExtensions’ and ‘systemLanguage’.
[NoInterfaceObject]
interface SVGTests {
readonly attribute SVGStringList requiredExtensions;
readonly attribute SVGStringList systemLanguage;
};
-
- requiredExtensions (readonly SVGStringList)
-
- systemLanguage (readonly SVGStringList)
-
3.3.22. Interface SVGFitToViewBox
Interface SVGFitToViewBox defines DOM attributes that apply to
elements which have XML attributes ‘viewBox’ and
‘preserveAspectRatio’.
[NoInterfaceObject]
interface SVGFitToViewBox {
readonly attribute SVGAnimatedRect viewBox;
readonly attribute SVGAnimatedPreserveAspectRatio preserveAspectRatio;
};
-
- viewBox (readonly SVGAnimatedRect)
-
Corresponds to attribute
‘viewBox’ on the given element.
- preserveAspectRatio (readonly SVGAnimatedPreserveAspectRatio)
-
3.3.23. Interface SVGZoomAndPan
The SVGZoomAndPan interface defines attribute zoomAndPan and
associated constants.
[NoInterfaceObject]
interface SVGZoomAndPan {
// Zoom and Pan Types
const unsigned short SVG_ZOOMANDPAN_UNKNOWN = 0;
const unsigned short SVG_ZOOMANDPAN_DISABLE = 1;
const unsigned short SVG_ZOOMANDPAN_MAGNIFY = 2;
attribute unsigned short zoomAndPan;
};
-
- SVG_ZOOMANDPAN_UNKNOWN (unsigned short)
-
The enumeration was set to a value that is not one of predefined types.
It is invalid to attempt to define a new value of this type or to
attempt to switch an existing value to this type.
- SVG_ZOOMANDPAN_DISABLE (unsigned short)
-
Corresponds to value 'disable'.
- SVG_ZOOMANDPAN_MAGNIFY (unsigned short)
-
Corresponds to value 'magnify'.
-
- zoomAndPan (unsigned short)
-
Corresponds to attribute
‘zoomAndPan’ on the given element. The
value must be one of the SVG_ZOOMANDPAN_* constants defined on this
interface.
3.3.24. Interface SVGURIReference
Interface SVGURIReference defines an interface which applies to all
elements which have an ‘href’ attribute.
[NoInterfaceObject]
interface SVGURIReference {
readonly attribute SVGAnimatedString href;
};
-
- href (readonly SVGAnimatedString)
-
Corresponds to the ‘href’
attribute.
If the element also supports the deprecated ‘xlink:href’
attribute, the resulting SVGAnimatedString object will
correspond to the ‘xlink:href’ attribute in the XLink namespace
if, and only if, all of the following conditions are true at
the time when the href IDL attribute is accessed:
- There is no ‘href’ attribute
without a namespace specified on the element, and
- There is no animation element whose target element is this
element and whose ‘attributeName’ is the string ‘href’ (that is, without an XMLNS
prefix), and
- There is an ‘href’ attribute in
the XLink namespace on the element, or there is an animation element whose target
element is this element and whose ‘attributeName’
references the ‘href’ attribute
in the XLink namespace.
If any of the above conditions does not hold at the time
when the the href IDL attribute is accessed, the returned
attribute will correspond to the ‘href’
attribute without a namespace.