The content model and set of allowed attributes, as listed in definitions.xml, needs to be reviewed for consistency across all elements.
An SVG document fragment consists of any number of SVG elements contained within an ‘svg’ element.
An SVG document fragment can range from an empty fragment (i.e., no content inside of the ‘svg’ element), to a very simple SVG document fragment containing a single SVG graphics element such as a ‘rect’, to a complex, deeply nested collection of container elements and graphics elements.
An SVG document fragment can stand by itself as a self-contained file or resource, in which case the SVG document fragment is an SVG document, or it can be embedded inline as a fragment within a parent HTML or XML document.
The following example shows simple SVG content embedded inline as a fragment within a parent XML document. Note the use of XML namespaces to indicate that the ‘svg’ and ‘ellipse’ elements belong to the SVG namespace:
<?xml version="1.0" standalone="yes"?> <parent xmlns="http://example.org" xmlns:svg="http://www.w3.org/2000/svg"> <!-- parent contents here --> <svg:svg width="4cm" height="8cm"> <svg:ellipse cx="2cm" cy="4cm" rx="2cm" ry="1cm" /> </svg:svg> <!-- ... --> </parent>
This example shows a slightly more complex (i.e., it contains multiple rectangles) stand-alone, self-contained SVG document:
<?xml version="1.0" standalone="no"?> <svg width="5cm" height="4cm" version="1.1" xmlns="http://www.w3.org/2000/svg"> <desc>Four separate rectangles </desc> <rect x="0.5cm" y="0.5cm" width="2cm" height="1cm"/> <rect x="0.5cm" y="2cm" width="1cm" height="1.5cm"/> <rect x="3cm" y="0.5cm" width="1.5cm" height="2cm"/> <rect x="3.5cm" y="3cm" width="1cm" height="0.5cm"/> <!-- Show outline of canvas using 'rect' element --> <rect x=".01cm" y=".01cm" width="4.98cm" height="3.98cm" fill="none" stroke="blue" stroke-width=".02cm" /> </svg>
‘svg’ elements can appear in the middle of SVG content. This is the mechanism by which SVG document fragments can be embedded within other SVG document fragments.
Another use for ‘svg’ elements within the middle of SVG content is to establish a new viewport. (See Establishing a new viewport.)
When SVG is parsed as a XML, for compliance with the Namespaces in XML Recommendation [XML-NS], an SVG namespace declaration must be provided so that all SVG elements are identified as belonging to the SVG namespace.
The SVG 2 namespace is http://www.w3.org/2000/svg
,
which is the same as for earlier versions of SVG.
The following are possible ways to provide a namespace declaration. An ‘xmlns’ attribute without a namespace prefix could be specified on an ‘svg’ element, which means that SVG is the default namespace for all elements within the scope of the element with the ‘xmlns’ attribute:
<svg xmlns="http://www.w3.org/2000/svg" …> <rect …/> </svg>
If a namespace prefix is specified on the ‘xmlns’
attribute (e.g., xmlns:svg="http://www.w3.org/2000/svg"
),
then the corresponding namespace is not the default namespace, so an
explicit namespace prefix must be assigned to the elements:
<svg:svg xmlns:svg="http://www.w3.org/2000/svg" …> <svg:rect …/> </svg:svg>
Namespace prefixes can be specified on ancestor elements (illustrated in the above example). For more information, refer to the Namespaces in XML Recommendation [XML-NS].
When using the HTML syntax, the namespace is provided automatically by the parser.
This section should talk about how a document's behavior is defined in terms of the DOM, and also explain how the HTML parser can create SVG fragments.
The general definition of a user agent is an application that retrieves and renders Web content, including text, graphics, sounds, video, images, and other content types. A user agent may require additional user agents that handle some types of content. For instance, a browser may run a separate program or plug-in to render sound or video. User agents include graphical desktop browsers, multimedia players, text browsers, voice browsers, and assistive technologies such as screen readers, screen magnifiers, speech synthesizers, onscreen keyboards, and voice input software.
A "user agent" may or may not have the ability to retrieve and render SVG content; however, an "SVG user agent" retrieves and renders SVG content.
SVG 2 Requirement: | Support transforming ‘svg’ elements. |
---|---|
Resolution: | We will allow ‘transform’ on ‘svg’ in SVG 2. |
Purpose: | To allow transforms on nested ‘svg’ elements, in line with author expectations. |
Owner: | Dirk (no action) |
The ‘x
’ and ‘y
’ attributes specify the
top-left corner of the rectangular region into which an
embedded ‘svg’ element is placed. On an outermost svg element,
these attributes have no effect.
For outermost svg elements,
the ‘width
’ and ‘height
’ attributes specify
the intrinsic size of the SVG document fragment.
For embedded ‘svg’ elements, they specify the size
of the rectangular region into which the ‘svg’ element
is placed.
Attribute definitions:
Name | Value | Initial value | Animatable |
---|---|---|---|
zoomAndPan | disable | magnify | magnify | no |
Specifies whether the user agent should supply a means to zoom and pan the SVG content. See the definition of ‘zoomAndPan’ for details.
If an SVG document is likely to be referenced as a component of another document, the author will often want to include a ‘viewBox’ attribute on the outermost svg element of the referenced document. This attribute provides a convenient way to design SVG documents to scale-to-fit into an arbitrary viewport.
The ‘svg’ element exposes as event handler content attributes a number of the event handlers of the Window object. It also mirrors their event handler IDL attributes.
The onblur, ‘onerror’, onfocus, ‘onload’, and ‘onscroll’ event handlers of the Window object, exposed on the ‘svg’ element, replace the generic event handlers with the same names normally supported by SVG elements.
The ‘g’ element is a container element for grouping together related graphics elements.
A group of elements, as well as individual objects, can be given a name using the ‘id’ attribute. Named groups are needed for several purposes such as animation and re-usable objects.
An example:
<?xml version="1.0" standalone="no"?> <svg xmlns="http://www.w3.org/2000/svg" version="1.1" width="5cm" height="5cm"> <desc>Two groups, each of two rectangles</desc> <g id="group1" fill="red"> <rect x="1cm" y="1cm" width="1cm" height="1cm"/> <rect x="3cm" y="1cm" width="1cm" height="1cm"/> </g> <g id="group2" fill="blue"> <rect x="1cm" y="3cm" width="1cm" height="1cm"/> <rect x="3cm" y="3cm" width="1cm" height="1cm"/> </g> <!-- Show outline of canvas using 'rect' element --> <rect x=".01cm" y=".01cm" width="4.98cm" height="4.98cm" fill="none" stroke="blue" stroke-width=".02cm"/> </svg>
A ‘g’ element can contain other ‘g’ elements nested within it, to an arbitrary depth.
SVG 2 Requirement: | Have unknown elements treated as ‘g’ for the purpose of rendering. |
---|---|
Resolution: | Accept having unknown elements treated as ‘g’ for the purpose of rendering. |
Purpose: | To allow fallbacks without the use of ‘switch’, and to align with the behavior of unknown elements in HTML. |
Owner: | Nobody (no action) |
The SVGUnknownElement interface must be used for elements in the SVG namespace that are not defined by this specification.
Known elements in the SVG namespace that occur in places where SVG's content model doesn't explicitly allow it must not render.
Unknown elements in the SVG namespace render as if the unknown element was a ‘g’ element.
Known and unknown elements in other namespaces that occur as a child of any SVG element except ‘foreignObject’, must not render unless explicitly stated otherwise in this specification.
Consequently, in the following example:
<?xml version="1.0" standalone="no"?> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 700 200"> <mysteryElement> <path d="M0 0h600v200h-600z"/> </mysteryElement> <hideElement xmlns="http://www.example.com/invisibleML"> nothing to see here <path d="M0 0h600v200h-600z"/> </hideElement> <text y="1em"><text>this text must not be visible</text></text> <linearGradient> <gradientExtension> <path d="M0 0h600v200h-600z"/> </gradientExtension> </linearGradient> <div xmlns="http://www.w3.org/1999/xhtml">this must not be visible</div> </svg>
Should it be possible to somehow force rendering of unknown elements in other namespaces?
Do we need to mention anything about attributes, properties and such on SVGUnknownElements?
Should SVGUnknownElement be a container element?
SVG allows graphical objects to be defined for later reuse. To do this, it makes extensive use of URL references [RFC3987] to these other objects. For example, to fill a rectangle with a linear gradient, you first define a ‘linearGradient’ element and give it an ID, as in:
<linearGradient id="MyGradient">...</linearGradient>
You then reference the linear gradient as the value of the
‘fill
’ property for the rectangle, as in:
<rect style="fill:url(#MyGradient)"/>
Some types of element, such as gradients, will not by themselves produce a graphical result. They can therefore be placed anywhere convenient. However, sometimes it is desired to define a graphical object and prevent it from being directly rendered. it is only there to be referenced elsewhere. To do this, and to allow convenient grouping defined content, SVG provides the ‘defs’ element.
It is recommended that, wherever possible, referenced elements be defined inside of a ‘defs’ element. Among the elements that are always referenced: ‘clipPath’, ‘cursor’, ‘filter’, ‘linearGradient’, ‘marker’, ‘mask’, ‘pattern’, ‘radialGradient’ and ‘symbol’.
The ‘defs’ element is a container element for referenced elements. For understandability and accessibility reasons, it is recommended that, whenever possible, referenced elements be defined inside of a ‘defs’.
The content model for ‘defs’ is the same as for the ‘g’ element; thus, any element that can be a child of a ‘g’ can also be a child of a ‘defs’, and vice versa.
Elements that are descendants of a ‘defs’ are not rendered directly;
they are prevented from becoming part of the rendering tree
just as if the ‘defs’ element were a ‘g’ element and the
‘display
’ property were set to none.
Note, however, that the descendants of a ‘defs’ are
always present in the source tree and thus can always be
referenced by other elements; thus, the value of the ‘display
’
property on the ‘defs’ element or any of its descendants does not
prevent those elements from being referenced by other elements.
The attribute ‘lang’ added to allow internationalization of the ‘desc’ and ‘title’ elements.
Adding 'lang' resolved at Rigi Kaltbad face-to-face. Removed text that limited number of 'desc' and 'title' elements.
Is there any updated wording from SVG Tiny 1.2 that we should be using wrt tooltips?
Each container element or graphics element in an SVG drawing can supply one or more ‘desc’ and/or one or more ‘title’ description strings where the description is text-only. When the current SVG document fragment is rendered as SVG on visual media, ‘desc’ and ‘title’ elements are not rendered as part of the graphics. The ‘title’ child element represents advisory information for the element, such as would be appropriate for a tooltip. On a link, this could be the title or a description of the target resource; on an image or drawing object, it could be the image credit or short description of the image; it could be further information about the source; on interactive content, it could be a label for, or instructions for, use of the element; and so forth. The value is text. The ‘desc’ element represents more detailed, textual information, for the element. This is typically exposed to assistive technologies to provide more detailed information, such as help information about the element. The value is text.
Authors are provided two vehicles for providing a visible label with a drawing element. The first way is to embed text within the drawing element. The second is to associate visible text with a drawing element through the use of ‘aria-labelledby’ on the element being labelled. Authors may provide a non-visible label to a drawing element by applying an ‘aria-label’ to it but also by providing a descendant ‘title’ element. An author may also expose a hidden label on an element to an assistive technologies through the use of ‘aria-labelledby’ when it points to content that is hidden and contains text. It is common for user agents to render the ‘title’ element as a tooltip. Tooltips are an important way to convey alternative text information for a drawing object where the text label is either not readily visible or could be rendered in a clearer way in response to passing over the drawing element with a pointing device. One benefit of using a descendant 'title' element can be seen when using SVG to to produce an image button or small drawing that has no visible text but it is important to be able to render a short textual equivalent label, or tooltip, when a pointing device passes over the button.
Authors should provide a ‘title’ child element to the outermost svg element within a stand-alone SVG document. Since users often consult documents out of context, authors should provide context-rich titles. Thus, instead of a title such as "Introduction", which doesn't provide much contextual background, authors should supply a title such as "Introduction to Medieval Bee-Keeping" instead. For reasons of accessibility, user agents should always make the content of the ‘title’ child element to the outermost svg element available to users. The mechanism for doing so depends on the user agent (e.g., as a caption, spoken).
If the SVG document is embedded in an HTML document, the outermost svg element may only serve to act as a container for SVG drawings and applying a ‘title’ child element may not be of value. Applying a ‘title’ element to the outermost SVG element in this may may result in a tooltip being generated.
Unlike the desc element, authors also have the ability to associate more detailed information with content that includes visible text. This can be achieved by applying ‘aria-describedby’ to the element, or container of elements being described and passing an ID reference to content that includes text that describes the element in question. However, if the text describing the object is hidden the text within the description would be exposed to assistive technologies as detailed text information, similar to a descendant ‘desc’ element. The ‘aria-describedby’ attribute takes precedence over the child ‘desc’ when providing a description, consequently authors should only use ‘aria-describedby’ when an element is described by visible text on the screen, otherwise the use of a child ‘desc’ is preferred.
User agents may, however, for example, display the ‘title’ element as a tooltip, as the pointing device moves over particular elements. Alternate presentations are possible, both visual and aural, which display the ‘desc’ and ‘title’ elements but do not display ‘path’ elements or other graphics elements. For deep hierarchies, and for following ‘use’ element references, it is sometimes desirable to allow the user to control how deep they drill down into descriptive text.
More than one ‘desc’ or ‘title’ may be present with different ‘lang’ attributes. The text displayed will be the text from the element where the ‘lang’ attribute best matches the language set by the user agent. If no match exists, the text from the first element is used (to allow default text to be given for legacy renderers). If multiple equally valid matches exist, the first match is used.
The following is an example. In typical operation, the SVG user agent would not render the ‘desc’ and ‘title’ elements but would render the remaining contents of the ‘g’ element.
<?xml version="1.0" standalone="no"?> <svg xmlns="http://www.w3.org/2000/svg" width="4in" height="3in"> <g> <title>Company sales by region</title> <title lang="fr">Chiffre d'affaires par région</title> <desc>Bar chart which shows company sales by region.</desc> <desc lang="fr">Graphique illustrant les ventes par région.</desc> <!-- Bar chart defined as vector data --> </g> </svg>
Description and title elements can contain marked-up text from other namespaces.
We should say what purpose including other-namespaced markup in ‘title’ and ‘desc’ has. If it is just that these are basically metadata extension points for other profiles or uses of SVG, then we should say that.
We have this sentence here about tooltips which is stronger than the earlier note that some implementations do this. We should look at how HTML describes the ‘title’ attribute and whether a tooltip is required, suggested, etc., and follow that.
Once we have said how ARIA attributes can be used in SVG, we might want to define ‘title’ and ‘desc’ in a manner consistent with them, so that it is clear what it means for example for an element to have both a ‘desc’ element child and an ‘aria-describedby’ attribute.
Metadata which is included with SVG content should be specified within ‘metadata’ elements. The contents of the ‘metadata’ should be elements from other XML namespaces, with these elements from these namespaces expressed in a manner conforming with the Namespaces in XML Recommendation [XML-NS].
Authors should provide a ‘metadata’ child element to the outermost svg element within a stand-alone SVG document. The ‘metadata’ child element to an ‘svg’ element serves the purposes of identifying document-level metadata.
The definitions of many of SVG's elements (particularly, container and text elements) place no restriction on the placement or number of the ‘metadata’ sub-elements. This flexibility is only present so that there will be a consistent content model for container elements, because some container elements in SVG allow for mixed content, and because the mixed content rules for XML ([XML10], section 3.2.2) do not permit the desired restrictions. Future versions of the SVG language might provide more restrictive mixed content rules. It is strongly recommended that at most one ‘metadata’ element appear as a child of any particular element, and that this element appear before any other child elements (except possibly ‘desc’ or ‘title’ elements) or character data content. If metadata-processing user agents need to choose among multiple ‘metadata’ elements for processing it should choose the first one.
Here is an example of how metadata can be included in an SVG document. The example uses the Dublin Core version 1.1 schema. (Other XML-compatible metadata languages, including ones not based on RDF, can be used also.)
<?xml version="1.0" standalone="yes"?> <svg width="4in" height="3in" xmlns = 'http://www.w3.org/2000/svg'> <desc xmlns:myfoo="http://example.org/myfoo"> <myfoo:title>This is a financial report</myfoo:title> <myfoo:descr>The global description uses markup from the <myfoo:emph>myfoo</myfoo:emph> namespace.</myfoo:descr> <myfoo:scene><myfoo:what>widget $growth</myfoo:what> <myfoo:contains>$three $graph-bar</myfoo:contains> <myfoo:when>1998 $through 2000</myfoo:when> </myfoo:scene> </desc> <metadata> <rdf:RDF xmlns:rdf = "http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:rdfs = "http://www.w3.org/2000/01/rdf-schema#" xmlns:dc = "http://purl.org/dc/elements/1.1/" > <rdf:Description about="http://example.org/myfoo" dc:title="MyFoo Financial Report" dc:description="$three $bar $thousands $dollars $from 1998 $through 2000" dc:publisher="Example Organization" dc:date="2000-04-11" dc:format="image/svg+xml" dc:language="en" > <dc:creator> <rdf:Bag> <rdf:li>Irving Bird</rdf:li> <rdf:li>Mary Lambert</rdf:li> </rdf:Bag> </dc:creator> </rdf:Description> </rdf:RDF> </metadata> </svg>
Name | Value | Initial value | Animatable |
---|---|---|---|
refX | <length> | left | center | right | 0 | yes |
refY | <length> | top | center | bottom | 0 | yes |
New in SVG 2. Added to make it easier to align symbols to a particular point, as is often done in maps. Similar to the matching attributes on ‘marker’.
Add refX/refY to symbol element. Resolved at Leipzig F2F.
We will add top/center/bottom, left/center/right keywords to refX/refY on marker/symbol. Resolved at London F2F. Values inspired by 'background-position'.
The ‘refX’ and ‘refY’ attributes define the reference point of the symbol which is to be placed exactly at the symbol's position as defined by the ‘use’ element. They are interpreted as being in the coordinate system of the symbol contents, after application of the ‘viewBox’ and ‘preserveAspectRatio’ attributes.
The ‘symbol’ element is used to define graphical template objects which can be instantiated by a ‘use’ element.
The use of ‘symbol’ elements for graphics that are used multiple times in the same document adds structure and semantics.
The key distinctions between a ‘symbol’ and a ‘g’ are:
The user agent style sheet sets
the ‘overflow
’ property for ‘symbol’ elements to
hidden, which causes a rectangular clipping
path to be created at the bounds of symbol's viewport. Unless the
‘overflow
’ property is overridden, any graphics within the symbol which
goes outside of the symbol's viewport will be clipped.
Closely related to the ‘symbol’ element are the ‘marker’ and ‘pattern’ elements.
‘symbol’ elements are never rendered directly; their only usage is
as something that can be referenced using the
‘use’ element. The ‘display
’ property does not apply
to the ‘symbol’ element; thus, ‘symbol’ elements are
not directly rendered even if the ‘display
’ property is set to a
value other than none, and ‘symbol’
elements are available for referencing even when the
‘display
’ property on the ‘symbol’ element or any of its
ancestors is set to none.
SVG 2 Requirement: | Allow ‘use’ to reference an external document's root element by omitting the fragment. |
---|---|
Resolution: | We will relax referencing requirements to particular elements to allow dropping fragments to mean referencing root element, where it makes sense, such as with use, in SVG 2. |
Purpose: | To avoid requiring authors to modify the referenced document to add an ID to the root element. |
Owner: | Cameron (ACTION-3417) |
The ‘use’ element references another element and indicates that the graphical contents of that element is included/drawn at that given point in the document.
‘use’ is described as referencing template objects, but the parameters of the template are limited – just different inherited property values.
The graphical contents are any ‘svg’, ‘symbol’, ‘g’, graphics element or other ‘use’ elements, that a ‘use’ element references.
The ‘use’ element can reference an entire SVG document by specifying an ‘href’ value without a fragment. Such references are taken to be referring to the root element of the referenced document.
This allows an entire SVG document to be referenced without having to ensure that it has an ID on its root element.
The ‘use’ element has optional attributes ‘x’, ‘y’, ‘width’ and ‘height’ which are used to map the graphical contents of the referenced element onto a rectangular region within the current coordinate system.
The effect of a ‘use’ element is as if the graphical contents of the referenced element were deeply cloned into a separate non-exposed DOM tree which had the ‘use’ element as its parent and all of the ‘use’ element's ancestors as its higher-level ancestors. Because the cloned DOM tree is non-exposed, the SVG Document Object Model (DOM) only contains the ‘use’ element and its attributes. The SVG DOM does not show the referenced element's contents as children of ‘use’ element.
The non-exposed DOM tree must be created even if 'display: none' is set on the ‘use’ element. Note that ‘script’ elements that get conceptually cloned into the non-exposed DOM tree do not execute again, and ‘audio’ and ‘video’ elements that may play audio must only do so if the ‘use’ element is rendered.
We should define the behavior of ‘use’ in terms of Web Components. See ACTION-3729 (Tab)
The conceptual deep cloning of the referenced element into a non-exposed DOM tree also copies any property values resulting from the CSS cascade ([CSS21], chapter 6) on the referenced element and its contents. CSS2 selectors can be applied to the original (i.e., referenced) elements because they are part of the formal document structure. CSS2 selectors cannot be applied to the (conceptually) cloned DOM tree because its contents are not part of the formal document structure.
Property inheritance, however, works as if the referenced element had been textually included as a deeply cloned child of the ‘use’ element. The referenced element inherits properties from the ‘use’ element and the ‘use’ element's ancestors. An instance of a referenced element does not inherit properties from the referenced element's original parents.
Note that specifying 'visibility:hidden' on a ‘use’ element does not guarantee that the referenced content will not be rendered. If the ‘use’ element specifies 'visibility:hidden' and the element it references specifies 'visibility:hidden' or 'visibility:inherit', then that one element will be hidden. However, if the referenced element instead specifies 'visibility:visible', then that element will be visible even if the ‘use’ element specifies 'visibility:hidden'.
If event attributes are assigned to referenced elements, then the actual target for the event will be the element within the "instance tree" corresponding to the given referenced element.
The event handling for the non-exposed tree works as if the referenced element had been textually included as a deeply cloned child of the ‘use’ element, and events are dispatched according to the shadow tree event dispatching algorithm [SHADOWDOM]. The event's target and currentTarget attributes are set to the instance tree element that corresponds to the target and current target elements in the referenced subtree. An event propagates through the exposed and non-exposed portions of the tree in the same manner as it would in the regular document tree: first going from the root element to the ‘use’ element and then through non-exposed tree elements in the capture phase, followed by the target phase at the target of the event, then bubbling back through non-exposed tree to the use element and then back through regular tree to the root element in bubbling phase. In order to maintain encapsulation events must use the event retargeting algorithm [SHADOWDOM] when crossing from a non-exposed tree to the regular tree.
The element referenced by ‘use’ may be in a separate document. However, this specification does not define how or if the user agent will process stylesheets in that document, or what viewport will be used for resolving percentages and media queries in such documents, if animations run in the separate document and which document controls the animation timeline. Script elements in the resource document must not be executed, and the corresponding conceptually cloned script elements must also not execute.
When re-using external assets, therefore, authors are advised not to include any scripts in the external file and to use inline styles or presentation attributes only. Percentage lengths should only be used if the re-used assets define their own viewport (i.e., if the re-used element is an ‘svg’ or ‘symbol’). Declarative animations in external assets should not be used.
User agents may restrict restrict external resource documents for security reasons. In particular, this specification does not allow cross-origin resource requests in ‘use’. A future version of this or another specification may provide a method of securely enabling cross-origin re-use of assets.
Animations on a referenced element will cause the instances to also be animated.
A ‘use’ element has the same visual effect as if the ‘use’ element were replaced by the following generated content:
Except that the replaced content shouldn't affect how styles are matched.
In the generated content, the ‘use’ will be replaced
by ‘g’, where all attributes from the ‘use’ element
except for ‘x’, ‘y’, ‘width’,
‘height’, ‘href’ and ‘xlink:href’ are transferred
to the generated ‘g’ element. An additional transformation
translate(x,y) is appended to the
end (i.e., right-side) of the ‘transform
’ property on the
generated ‘g’, where x
and y represent the values of
the ‘x’ and ‘y’ attributes on the ‘use’
element.
If the ‘use’ element references a ‘symbol’ element:
The referenced ‘symbol’ and its contents are deep-cloned into the generated tree, with the exception that the ‘symbol’ is replaced by an ‘svg’. This generated ‘svg’ will always have explicit values for its ‘width’ and ‘height’ presentation attributes. If attributes ‘width’ and/or ‘height’ are provided on the ‘use’ element, then these attributes will be transferred to the generated ‘svg’. If attributes ‘width’ and/or ‘height’ are not specified, the generated ‘svg’ element will use values of '100%' for these attributes.
If the ‘use’ element references an ‘svg’ element:
The referenced ‘svg’ and its contents are deep-cloned into the generated tree. If attributes ‘width’ and/or ‘height’ are provided on the ‘use’ element, then these values will override the corresponding attributes on the ‘svg’ in the generated tree.
Otherwise:
The referenced object and its contents are deep-cloned into the generated tree.
For user agents that support Styling with CSS, the generated ‘g’ element carries along with it the "cascaded" property values on the ‘use’ element which result from the CSS cascade ([CSS21], chapter 6). Additionally, the copy (deep clone) of the referenced resource carries along with it the "cascaded" property values resulting from the CSS cascade on the original (i.e., referenced) elements. Thus, the result of various CSS selectors in combination with the ‘class’ and ‘style’ attributes are, in effect, replaced by the functional equivalent of a ‘style’ attribute in the generated content which conveys the "cascaded" property values.
Example Use01 below has a simple ‘use’ on a ‘rect’.
<?xml version="1.0" standalone="no"?> <svg width="10cm" height="3cm" viewBox="0 0 100 30" version="1.1" xmlns="http://www.w3.org/2000/svg"> <desc>Example Use01 - Simple case of 'use' on a 'rect'</desc> <defs> <rect id="MyRect" width="60" height="10"/> </defs> <rect x=".1" y=".1" width="99.8" height="29.8" fill="none" stroke="blue" stroke-width=".2" /> <use x="20" y="10" href="#MyRect" /> </svg>
The visual effect would be equivalent to the following document:
<?xml version="1.0" standalone="no"?> <svg width="10cm" height="3cm" viewBox="0 0 100 30" xmlns="http://www.w3.org/2000/svg" version="1.1"> <desc>Example Use01-GeneratedContent - Simple case of 'use' on a 'rect'</desc> <!-- 'defs' section left out --> <rect x=".1" y=".1" width="99.8" height="29.8" fill="none" stroke="blue" stroke-width=".2" /> <!-- Start of generated content. Replaces 'use' --> <g transform="translate(20,10)"> <rect width="60" height="10"/> </g> <!-- End of generated content --> </svg>
Example Use02 below has a ‘use’ on a ‘symbol’.
<?xml version="1.0" standalone="no"?> <svg width="10cm" height="3cm" viewBox="0 0 100 30" version="1.1" xmlns="http://www.w3.org/2000/svg"> <desc>Example Use02 - 'use' on a 'symbol'</desc> <defs> <symbol id="MySymbol" viewBox="0 0 20 20"> <desc>MySymbol - four rectangles in a grid</desc> <rect x="1" y="1" width="8" height="8"/> <rect x="11" y="1" width="8" height="8"/> <rect x="1" y="11" width="8" height="8"/> <rect x="11" y="11" width="8" height="8"/> </symbol> </defs> <rect x=".1" y=".1" width="99.8" height="29.8" fill="none" stroke="blue" stroke-width=".2" /> <use x="45" y="10" width="10" height="10" href="#MySymbol" /> </svg>
The visual effect would be equivalent to the following document:
<?xml version="1.0" standalone="no"?> <svg width="10cm" height="3cm" viewBox="0 0 100 30" xmlns="http://www.w3.org/2000/svg" version="1.1"> <desc>Example Use02-GeneratedContent - 'use' on a 'symbol'</desc> <!-- 'defs' section left out --> <rect x=".1" y=".1" width="99.8" height="29.8" fill="none" stroke="blue" stroke-width=".2" /> <!-- Start of generated content. Replaces 'use' --> <g transform="translate(45, 10)" > <!-- Start of referenced 'symbol'. 'symbol' replaced by 'svg', with x,y,width,height=0,0,100%,100% --> <svg width="10" height="10" viewBox="0 0 20 20"> <rect x="1" y="1" width="8" height="8"/> <rect x="11" y="1" width="8" height="8"/> <rect x="1" y="11" width="8" height="8"/> <rect x="11" y="11" width="8" height="8"/> </svg> <!-- End of referenced symbol --> </g> <!-- End of generated content --> </svg>
Example Use03 illustrates
what happens when a ‘use’ has
a ‘transform
’ property.
<?xml version="1.0" standalone="no"?> <svg width="10cm" height="3cm" viewBox="0 0 100 30" version="1.1" xmlns="http://www.w3.org/2000/svg"> <desc>Example Use03 - 'use' with a 'transform' attribute</desc> <defs> <rect id="MyRect" x="0" y="0" width="60" height="10"/> </defs> <rect x=".1" y=".1" width="99.8" height="29.8" fill="none" stroke="blue" stroke-width=".2" /> <use href="#MyRect" transform="translate(20,2.5) rotate(10)" /> </svg>
The visual effect would be equivalent to the following document:
<?xml version="1.0" standalone="no"?> <svg width="10cm" height="3cm" viewBox="0 0 100 30" xmlns="http://www.w3.org/2000/svg" version="1.1"> <desc>Example Use03-GeneratedContent - 'use' with a 'transform' attribute</desc> <!-- 'defs' section left out --> <rect x=".1" y=".1" width="99.8" height="29.8" fill="none" stroke="blue" stroke-width=".2" /> <!-- Start of generated content. Replaces 'use' --> <g transform="translate(20,2.5) rotate(10)"> <rect x="0" y="0" width="60" height="10"/> </g> <!-- End of generated content --> </svg>
Example Use04 illustrates a ‘use’ element with various methods of applying CSS styling.
<?xml version="1.0" standalone="no"?> <svg width="12cm" height="3cm" viewBox="0 0 1200 300" xmlns="http://www.w3.org/2000/svg"> <desc>Example Use04 - 'use' with CSS styling</desc> <defs style=" /* rule 9 */ stroke-miterlimit: 10" > <path id="MyPath" d="M300 50 L900 50 L900 250 L300 250" class="MyPathClass" style=" /* rule 10 */ stroke-dasharray:300,100" /> </defs> <style type="text/css"> <![CDATA[ /* rule 1 */ #MyUse { fill: blue } /* rule 2 */ #MyPath { stroke: red } /* rule 3 */ use { fill-opacity: .5 } /* rule 4 */ path { stroke-opacity: .5 } /* rule 5 */ .MyUseClass { stroke-linecap: round } /* rule 6 */ .MyPathClass { stroke-linejoin: bevel } /* rule 7 */ use > path { shape-rendering: optimizeQuality } /* rule 8 */ g > path { visibility: hidden } ]]> </style> <rect x="0" y="0" width="1200" height="300" style="fill:none; stroke:blue; stroke-width:3"/> <g style=" /* rule 11 */ stroke-width:40"> <use id="MyUse" href="#MyPath" class="MyUseClass" style="/* rule 12 */ stroke-dashoffset:50" /> </g> </svg>
The visual effect would be equivalent to the following document. Observe that some of the style rules above apply to the generated content (i.e., rules 1-6, 10-12), whereas others do not (i.e., rules 7-9). The rules which do not affect the generated content are:
In the generated content below, the selectors that yield a match have been transferred into inline ‘style’ attributes for illustrative purposes.
<?xml version="1.0" standalone="no"?> <svg width="12cm" height="3cm" viewBox="0 0 1200 300" xmlns="http://www.w3.org/2000/svg" version="1.1"> <desc>Example Use04-GeneratedContent - 'use' with a 'transform' attribute</desc> <!-- 'style' and 'defs' sections left out --> <rect x="0" y="0" width="1200" height="300" style="fill:none; stroke:blue; stroke-width:3"/> <g style="/* rule 11 */ stroke-width:40"> <!-- Start of generated content. Replaces 'use' --> <g style="/* rule 1 */ fill:blue; /* rule 3 */ fill-opacity:.5; /* rule 5 */ stroke-linecap:round; /* rule 12 */ stroke-dashoffset:50" > <path d="M300 50 L900 50 L900 250 L300 250" style="/* rule 2 */ stroke:red; /* rule 4 */ stroke-opacity:.5; /* rule 6 */ stroke-linejoin: bevel; /* rule 10 */ stroke-dasharray:300,100" /> </g> <!-- End of generated content --> </g> </svg>
When a ‘use’ references another element which is another ‘use’ or whose content contains a ‘use’ element, then the deep cloning approach described above is recursive. However, a set of references that directly or indirectly reference a element to create a circular dependency is an error, as described in References and the ‘defs’ element.
Attribute definitions:
Name | Value | Initial value | Animatable |
---|---|---|---|
x, y | <length> | 0 | yes |
width, height | <length> | (see below) | yes |
The ‘x’, ‘y’, ‘width’ and ‘height’ attributes specify the positioning of the referenced element. The ‘width’ and ‘height’ attributes have different initial values depending on the type of the referenced element:
A negative value for ‘width’ or ‘height’ is an error (see Error processing). If ‘width’ or ‘height’ is zero then rendering of the ‘use’ element is disabled.
Name | Value | Initial value | Animatable |
---|---|---|---|
href | URL [URL] | (none) | yes |
An URL reference to the element/fragment within an SVG document to be cloned for rendering.
Refer to the common handling defined for URL reference attributes and deprecated XLink attributes.SVG contains a ‘switch’ element along with attributes ‘requiredExtensions’ and ‘systemLanguage’ to provide an ability to specify alternate viewing depending on the capabilities of a given user agent or the user's language.
Attributes ‘requiredExtensions’ and ‘systemLanguage’ act as tests and evaluate to either true or false. The ‘switch’ renders the first of its children for which all of these attributes test true. If the given attribute is not specified, then a true value is assumed.
Similar to the ‘display
’ property, conditional processing
attributes only affect the direct rendering of elements and do
not prevent elements from being successfully referenced by
other elements (such as via a ‘use’).
In consequence:
The ‘switch’ element evaluates the ‘requiredExtensions’ and ‘systemLanguage’ attributes on its direct child elements in order, and then processes and renders the first child for which these attributes evaluate to true. All others will be bypassed and therefore not rendered. If the child element is a container element such as a ‘g’, then the entire subtree is either processed/rendered or bypassed/not rendered.
Note that the values of properties ‘display
’ and
‘visibility
’ have no effect on ‘switch’ element
processing. In particular, setting ‘display
’ to
none on a child of a ‘switch’ element
has no effect on true/false testing associated with ‘switch’
element processing.
The ‘switch’ element does not affect the processing of ‘script’ and ‘style’ elements.
For more information and an example, see Embedding foreign object types.
The ‘requiredExtensions’ attribute defines a list of required language extensions. Language extensions are capabilities within a user agent that go beyond the feature set defined in this specification. Each extension is identified by an URL reference.
Name | Value | Initial value | Animatable |
---|---|---|---|
requiredExtensions | set of space-separated tokens [HTML] | (none) | no |
The value is a list of URL references which identify the required extensions, with the individual values separated by white space. Determines whether all of the named extensions are supported by the user agent. If all of the given extensions are supported, then the attribute evaluates to true; otherwise, the current element and its children are skipped and thus will not be rendered.
If a given URL reference contains white space within itself, that white space must be escaped.
If the attribute is not present, then it implicitly evaluates to "true". If a null string or empty string value is given to attribute ‘requiredExtensions’, the attribute evaluates to "false".
‘requiredExtensions’ is often used in conjunction with the ‘switch’ element. If the ‘requiredExtensions’ is used in other situations, then it represents a simple switch on the given element whether to render the element or not.
The URL names for the extension should include versioning information, such as "http://example.org/SVGExtensionXYZ/1.0", so that script writers can distinguish between different versions of a given extension.
Name | Value | Initial value | Animatable |
---|---|---|---|
systemLanguage | set of comma-separated tokens [HTML] | (none) | no |
The value is a set of comma-separated tokens, each of which must be a Language-Tag value, as defined in BCP 47 [BCP47].
Evaluates to "true" if one of the languages indicated by user preferences exactly equals one of the languages given in the value of this parameter, or if one of the languages indicated by user preferences exactly equals a prefix of one of the languages given in the value of this parameter such that the first tag character following the prefix is "-".
Evaluates to "false" otherwise.
If the attribute is not present, then it implicitly evaluates to "true". If a null string or empty string value is given to attribute ‘systemLanguage’, the attribute evaluates to "false".
Note: This use of a prefix matching rule does not imply that language tags are assigned to languages in such a way that it is always true that if a user understands a language with a certain tag, then this user will also understand all languages with tags for which this tag is a prefix.
The prefix rule simply allows the use of prefix tags if this is the case.
Implementation note: When making the choice of linguistic preference available to the user, implementers should take into account the fact that users are not familiar with the details of language matching as described above, and should provide appropriate guidance. As an example, users may assume that on selecting "en-gb", they will be served any kind of English document if British English is not available. The user interface for setting user preferences should guide the user to add "en" to get the best matching behavior.
Multiple languages may be listed for content that is intended for multiple audiences. For example, content that is presented simultaneously in the original Maori and English versions, would call for:
<text systemLanguage="mi, en"><!-- content goes here --></text>
However, just because multiple languages are present within the object on which the ‘systemLanguage’ test attribute is placed, this does not mean that it is intended for multiple linguistic audiences. An example would be a beginner's language primer, such as "A First Lesson in Latin," which is clearly intended to be used by an English-literate audience. In this case, the ‘systemLanguage’ test attribute should only include "en".
Authoring note: Authors should realize that if several alternative language objects are enclosed in a ‘switch’, and none of them matches, this may lead to situations where no content is displayed. It is thus recommended to include a "catch-all" choice at the end of such a ‘switch’ which is acceptable in all cases.
‘systemLanguage’ is often used in conjunction with the ‘switch’ element. If the ‘systemLanguage’ is used in other situations, then it represents a simple switch on the given element whether to render the element or not.
For user agents that support HTML, the following HTML elements (in the HTML namespace) must be supported in SVG documents:
Note that the base
element will affect all URL values in the document, including e.g paint server references.
The ‘id’ attribute is available on all SVG elements:
Name | Value | Initial value | Animatable |
---|---|---|---|
id | (see below) | (none) | no |
Reflects the element's ID [DOM4]. The ‘id’ attribute must be any value other than the empty string.
The ‘lang’ attribute (in no namespace) specifies the primary language for the element's contents and for any of the element's attributes that contain text.
The ‘lang’ attribute in the XML namespace is defined in XML [XML10].
If these attributes are omitted from an element, then the language of this element is the same as the language of its parent element, if any.
The ‘lang’ attribute in the XML namespace may be used on SVG elements in XML documents. If both the ‘lang’ attribute in no namespace and the ‘lang’ attribute in the XML namespace are specified on the same element, they must have exactly the same value when compared in an ASCII case-insensitive manner.
If both the ‘lang’ attribute in no namespace and the ‘lang’ attribute in the XML namespace are set on an element, user agents must use the ‘lang’ attribute in the XML namespace, and the ‘lang’ attribute in no namespace must be ignored for the purposes of determining the element's language.
SVG 2 Requirement: | Deprecate the use of ‘xml:space’ to affect text layout and use the ‘white-space’ property instead. |
---|---|
Resolution: | We drop xml:space from SVG 2 and remove the relating tests from the SVG 1.1. test suite. |
Purpose: | To align with CSS. |
Owner: | Chris (ACTION-3004, done; and ACTION-3005, done) |
Name | Value | Initial value | Animatable |
---|---|---|---|
lang | Language-Tag [ABNF] | (none) | no |
The ‘lang’ attribute specifies the primary language for the element's contents and for any of the element's attributes that contain text. Its value must be a valid BCP 47 language tag, or the empty string. Setting the attribute to the empty string indicates that the primary language is unknown. [BCP47].
Name | Value | Initial value | Animatable |
---|---|---|---|
xml:space | (see below) | default | no |
Deprecated XML attribute to specify whether white space is preserved in character data. The only possible values are the strings 'default' and 'preserve', without white space. Refer to the Extensible Markup Language (XML) 1.0 Recommendation [XML10] and to the discussion white space handling in SVG.
New content should use the ‘white-space
’ property instead.
Name | Value | Initial value | Animatable |
---|---|---|---|
tabindex | valid integer [HTML] | (none) | no |
This content attribute allows authors to control whether an element is focusable, whether it is supposed to be reachable using sequential focus navigation, and what is to be the relative order of the element for the purposes of sequential focus navigation.
The name "tab index" comes from the common use of the "tab" key to navigate through the focusable elements. The term "tabbing" refers to moving forward through the focusable elements that can be reached using sequential focus navigation.
SVG elements having native semantics that are not limited to presentation (having "no role"), may have an ARIA role attribute specified. The attribute, if specified, must have a value that is a set of space-separated tokens representing the various WAI-ARIA roles that the element belongs to. These tokens are role values defined in Definition of Roles ([ARIA], section 5.4).
The WAI-ARIA role that an SVG element has assigned to it is the first non-abstract role found in the list of values generated when the role attribute is split on spaces.
Name | Value | Initial value | Animatable |
---|---|---|---|
role | set of space-separated tokens [HTML] | (see below) | no |
The ‘role’ attribute must be a set of space-separated tokens having values defined in Definition of Roles ([ARIA], section 5.4).
The role value is a set of white-space separated machine-extractable semantic information used to define the purpose of the element.
The initial value for the ‘role’ attribute, for each SVG element, is the corresponding default implied ARIA semantic for SVG elements.
SVG elements having native semantics that are not limited to presentation (having "no role"), may have an may have WAI-ARIA state and property attributes specified. These attributes are defined by ARIA in Definitions of States and Properties (all aria-* attributes) ([ARIA], section 6.6).
These attributes, if specified, must have a value that is the WAI-ARIA value type in the "Value" field of the definition for the state or property, mapped to the appropriate SVG value type according to Mapping WAI-ARIA Value types to languages using the SVG mapping ([ARIA], section 10.2).
WAI-ARIA State and Property attributes can be used on any element. They are not always meaningful, however, and in such cases user agents might not perform any processing aside from including them in the DOM. Unlike some other host languages, SVG is not considered to have strong native host language semantics in terms of the user interface, consequently state and property attributes are processed according to the ARIA and SVG Accessibility API Mappings specification specifications. [ARIA] [SVG-AAM]
The following table defines the default implicit ARIA semantics that apply to SVG elements. Each language feature (element) in a cell in the first column implies the ARIA semantics (role, states, and/or properties) given in the cell in the second column of the same row. The third column defines restrictions as to what WAI-ARIA semantic (role, state, or property) may or may not apply.
Language feature | Default implied ARIA semantics | Restrictions |
---|---|---|
‘a’ | link role |
no restrictions |
‘audio’ | group role |
If specified, role must be application |
‘canvas’ | group role |
no restrictions |
‘circle’ | none role provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, ‘aria-describedby’ attribute; or ‘tabindex’ attribute; otherwise, group role |
no restrictions |
‘clipPath’ | none | no role may be applied |
‘cursor’ | none | no restrictions |
‘defs’ | none | no role may be applied |
‘desc’ | none | no role may be applied |
‘ellipse’ | none role provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, ‘aria-describedby’ attribute; or ‘tabindex’ attribute; otherwise, group role |
no restrictions |
‘feBlend’ | none | no role may be applied |
‘feColorMatrix’ | none | no role may be applied |
‘feComponentTransfer’ | none | no role may be applied |
‘feComposite’ | none | no role may be applied |
‘feConvolveMatrix’ | none | no role may be applied |
‘feDiffuseLighting’ | none | no role may be applied |
‘feDisplacementMap’ | none | no role may be applied |
‘feDistantLight’ | none | no role may be applied |
‘feDropShadow’ | none | no role may be applied |
‘feFlood’ | none | no role may be applied |
‘feFuncA’ | none | no role may be applied |
‘feFuncB’ | none | no role may be applied |
‘feFuncG’ | none | no role may be applied |
‘feFuncR’ | none | no role may be applied |
‘feGaussianBlur’ | none | no role may be applied |
‘feImage’ | none | no role may be applied |
‘feMerge’ | none | no role may be applied |
‘feMergeNode’ | none | no role may be applied |
‘feMorphology’ | none | no role may be applied |
‘feOffset’ | none | no role may be applied |
‘fePointLight’ | none | no role may be applied |
‘feSpecularLighting’ | none | no role may be applied |
‘feSpotLight’ | none | no role may be applied |
‘feTile’ | none | no role may be applied |
‘feTurbulence’ | none | no role may be applied |
‘filter’ | none | no role may be applied |
‘foreignObject’ | none role provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, ‘aria-describedby’ attribute; or ‘tabindex’ attribute; otherwise, group role |
no restrictions |
‘g’ | none role provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, ‘aria-describedby’ attribute; or ‘tabindex’ attribute; otherwise, group role |
no restrictions |
‘hatch’ | none | no role may be applied |
‘hatchpath’ | none | no role may be applied |
‘iframe’ | no role | If Specified, role must be either application , document , or img roles |
‘image’ | img role |
no restrictions |
‘line’ | none role provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, ‘aria-describedby’ attribute; or ‘tabindex’ attribute; otherwise, group role |
no restrictions |
‘linearGradient’ | none | no role may be applied |
‘marker’ | none | no role may be applied |
‘mask’ | none | no role may be applied |
‘mesh’ | none | no role may be applied |
‘meshpatch’ | none | no role may be applied |
‘meshrow’ | none | no role may be applied |
‘metadata’ | none | no role may be applied |
‘mpath’ | none | no role may be applied |
‘path’ | none role provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, ‘aria-describedby’ attribute; or ‘tabindex’ attribute; otherwise, group role |
no restrictions |
‘pattern’ | none | no role may be applied |
‘polygon’ | none role provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, ‘aria-describedby’ attribute; or ‘tabindex’ attribute; otherwise, group role |
no restrictions |
‘polyline’ | none role provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, ‘aria-describedby’ attribute; or ‘tabindex’ attribute; otherwise, group role |
no restrictions |
‘radialGradient’ | none | no role may be applied |
‘rect’ | none role provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, ‘aria-describedby’ attribute; or ‘tabindex’ attribute; otherwise, group role |
no restrictions |
‘script’ | none | no role may be applied |
‘solidcolor’ | none | no role may be applied |
‘stop’ | none | no role may be applied |
‘style’ | none | no role may be applied |
‘svg’ | group role |
no restrictions |
‘switch’ | none role provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, ‘aria-describedby’ attribute; or ‘tabindex’ attribute; otherwise, group role |
no restrictions |
‘symbol’ | none role provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, ‘aria-describedby’ attribute; or ‘tabindex’ attribute; otherwise, group role |
no restrictions |
‘text’ | group role |
no restrictions |
‘textPath’ | group role |
no restrictions |
‘title’ | none | no role may be applied |
‘tspan’ | group role |
no restrictions |
‘use’ | none role provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, ‘aria-describedby’ attribute; or ‘tabindex’ attribute; otherwise, img role |
no restrictions |
‘video’ | group role |
If specified, role must be application |
‘view’ | none role provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, ‘aria-describedby’ attribute; or ‘tabindex’ attribute; otherwise, group role |
no restrictions |
The DOM Core specification defines a Document interface, which this specification extends.
In the case where an SVG document is embedded by reference, such as when an HTML document has an ‘object’ element whose ‘data’ attribute references an SVG document (i.e., a document whose MIME type is "image/svg+xml" and whose root element is thus an ‘svg’ element), there will exist two distinct DOM hierarchies. The first DOM hierarchy will be for the referencing document (e.g., an XHTML document). The second DOM hierarchy will be for the referenced SVG document.
For historical reasons, Window objects must also have a writable, configurable, non-enumerable property named SVGDocument whose value is the Document interface object.
partial interface Document { readonly attribute SVGSVGElement rootElement; };
The rootElement IDL attribute represents the root ‘svg’ element. On getting rootElement, the root element of the document is returned, if it is an ‘svg’ element, or null otherwise.
This attribute is deprecated, and may be removed in a future SVG specification. Authors are encouraged to use the documentElement attribute on Document instead.
The following IDL fragment must be supported only if the SVG implementation is also a Web browser or other interactive user agent, and therefore implements HTML.
// must only be implemented in certain implementations partial interface Document { readonly attribute DOMString title; readonly attribute DOMString referrer; readonly attribute DOMString domain; readonly attribute Element? activeElement; };
This is because the interface members above are already defined in HTML, and in implementations that support SVG and HTML they cannot be duplicated.
The title, referrer, domain and activeElement IDL attributes must behave the same as the corresponding IDL attributes defined in HTML.
An SVGSVGElement object represents an ‘svg’ element in the DOM. The SVGSVGElement interface also contains miscellaneous utility methods, such as data type object factory methods.
An SVGSVGElement object maintains an internal DOMPoint object, called its current translate point object, which is the object returned from the currentTranslate IDL attribute.
interface SVGSVGElement : SVGGraphicsElement { [SameObject] readonly attribute SVGAnimatedLength x; [SameObject] readonly attribute SVGAnimatedLength y; [SameObject] readonly attribute SVGAnimatedLength width; [SameObject] readonly attribute SVGAnimatedLength height; attribute float currentScale; [SameObject] readonly attribute DOMPointReadOnly currentTranslate; NodeList getIntersectionList(DOMRectReadOnly rect, SVGElement? referenceElement); NodeList getEnclosureList(DOMRectReadOnly rect, SVGElement? referenceElement); boolean checkIntersection(SVGElement element, DOMRectReadOnly rect); boolean checkEnclosure(SVGElement element, DOMRectReadOnly rect); void deselectAll(); SVGNumber createSVGNumber(); SVGLength createSVGLength(); SVGAngle createSVGAngle(); DOMPoint createSVGPoint(); DOMMatrix createSVGMatrix(); DOMRect createSVGRect(); SVGTransform createSVGTransform(); SVGTransform createSVGTransformFromMatrix(DOMMatrixReadOnly matrix); // Deprecated methods that have no effect when called, // but which are kept for compatibility reasons. unsigned long suspendRedraw(unsigned long maxWaitMilliseconds); void unsuspendRedraw(unsigned long suspendHandleID); void unsuspendRedrawAll(); void forceRedraw(); }; SVGSVGElement implements SVGFitToViewBox; SVGSVGElement implements SVGZoomAndPan; SVGSVGElement implements WindowEventHandlers;
The
x,
y,
width and
height IDL attributes
reflect the computed values of the ‘x
’, ‘y
’, ‘width
’ and
‘height
’ properties and their corresponding
presentation attributes, respectively.
The currentScale and currentTranslate IDL attributes represent the transform applied to the document in response to user magnification and panning operations, as described under Magnification and panning.
The document's magnification and panning
transform is a 2x3 matrix of the form
[currentScale 0 0 currentScale currentTranslate.x currentTranslate.y].
The value of the ‘transform
’ property does not affect
currentScale or
currentTranslate.
On getting currentScale, the following steps are run:
On setting currentScale, the following steps are run:
On getting currentTranslate, the SVGSVGElement object's current translate point object is returned. This object represents the current translation for the ‘svg’ element. A current translate point object must be read only when its ‘svg’ element is not the outermost svg element, and writable otherwise.
See the rules for assigning to a DOMPoint for how modifying the current translate point object affects the document's magnification and panning transform.
Whenever the document's magnification and panning transform changes in response to user interaction or whenever the outermost svg element changes, the following steps are run:
Running these steps when the outermost svg element changes will ensure that if the document element is replaced with a different ‘svg’ element, that its currentTranslate will be immediately updated to reflect the translation component of the document's magnification and panning transform.
Whenever an ‘svg’ element is no longer outermost svg element, the x and y components of its current translate point object must be set to 0.
Note that the value of the ‘zoomAndPan’ attribute on the outermost svg element only controls whether the document's magnification and panning transform can be updated through user interaction. Regardless of the value of that attribute, the current scale and translation can be changed by modifying currentScale and currentTranslate.
The suspendRedraw, unsuspendRedraw, unsuspendRedrawAll and forceRedraw methods are all deprecated and defined to have no effect. When the suspendRedraw method is called, it must return 1.
The getIntersectionList, getEnclosureList, checkIntersection and checkEnclosure methods are used to perform geometry operations on graphics elements to find those whose (or check whether their) graphical content lies partially or completely within a given rectangle.
To find the intersecting or enclosed descendants of a given element element with a given rectangle rectangle using ancestor as the element in whose coordinate space rectangle is to be interpreted, the following steps are run:
display
’ value
of none or being in a subtree that has
failing conditional processing attributes or a failing branch
of a ‘switch’, then return result.This means that although we look at the specific content referenced by the ‘use’ element, we don't place the referencing content in the result list; only the ‘use’ element itself is returned.
pointer-events
’ value.To find the non-container graphics elements within a given element element, the following steps are run:
When getIntersectionList(rect, referenceElement) or getEnclosureList(rect, referenceElement) is called, the following steps are run:
When checkIntersection(element, rect) or checkEnclosure(element, rect) is called, the following steps are run:
The deselectAll method is used to remove any selections from the document. When deselectAll() is called, all ranges from the document's selection are removed and the selection's direction is set to forwards. [DOM4][EDITING] This method is deprecated, as it duplicates functionality from the Selection API.
This is equivalent to calling document.getSelection().removeAllRanges()
on the document that this ‘svg’ element is in.
The createSVGNumber, createSVGLength, createSVGAngle, createSVGPoint, createSVGMatrix, createSVGRect and createSVGTransform methods are all factory functions used to create a new datatype object of a particular type. When one of these methods is called, a new object is returned according to the following table:
Method | Object and details |
---|---|
createSVGNumber | A new, detached SVGNumber object whose value is 0. |
createSVGLength | A new, detached SVGLength object whose value is the unitless <number> 0. |
createSVGAngle | A new, detached SVGAngle object whose value is the unitless <number> 0. |
createSVGPoint | A new, detached DOMPoint object whose coordinates are all 0. |
createSVGMatrix | A new, detached DOMMatrix object representing the identity matrix. |
createSVGRect | A new, DOMRect object whose x, y, width and height are all 0. |
createSVGTransform | A new, detached SVGTransform object whose value is matrix(1, 0, 0, 1, 0, 0). |
The createSVGPoint, createSVGMatrix and createSVGRect methods are all deprecated and kept only for compatibility with legacy content. Authors are encouraged to use the DOMPoint, DOMMatrix and DOMRect constructors instead.
The createSVGTransformFromMatrix method is used to create a new SVGTransform object from a matrix object. Its behavior is the same as the createSVGTransformFromMatrix method on SVGTransformList.
An SVGGElement object represents a ‘g’ element in the DOM.
interface SVGGElement : SVGGraphicsElement { };
An SVGUnknownElement object represents an unknown element in the SVG namespace.
interface SVGUnknownElement : SVGGraphicsElement { };
An SVGDefsElement object represents a ‘defs’ element in the DOM.
interface SVGDefsElement : SVGGraphicsElement { };
An SVGDescElement object represents a ‘desc’ element in the DOM.
interface SVGDescElement : SVGElement { };
An SVGMetadataElement object represents a ‘metadata’ element in the DOM.
interface SVGMetadataElement : SVGElement { };
An SVGTitleElement object represents a ‘title’ element in the DOM.
interface SVGTitleElement : SVGElement { };
An SVGSymbolElement object represents a ‘symbol’ element in the DOM.
interface SVGSymbolElement : SVGElement { }; SVGSymbolElement implements SVGFitToViewBox;
An SVGUseElement object represents a ‘use’ element in the DOM.
interface SVGUseElement : SVGGraphicsElement { [SameObject] readonly attribute SVGAnimatedLength x; [SameObject] readonly attribute SVGAnimatedLength y; [SameObject] readonly attribute SVGAnimatedLength width; [SameObject] readonly attribute SVGAnimatedLength height; }; SVGUseElement implements SVGURIReference;
The x, y, width and height IDL attributes reflect the computed values of the ‘x’, ‘y’, ‘width’ and ‘height’ properties and their corresponding presentation attributes, respectively.
An SVGSwitchElement object represents a ‘switch’ element in the DOM.
interface SVGSwitchElement : SVGGraphicsElement { };
This interface provides access to an SVG document embedded by reference in another DOM-based language. The expectation is that the interface is implemented on DOM objects that allow such SVG document references.
This interface is deprecated and may be dropped from future versions of
the SVG specification. To access the SVG document inside an
‘iframe’ or
‘object’ element,
authors are suggested to use the contentDocument
attribute on the HTMLIFrameElement or HTMLObjectElement
interface, respectively.
The HTMLIFrameElement, HTMLEmbedElement and HTMLObjectElement interfaces all define their own getSVGDocument method, which provides access to the SVG document in the same way that the GetSVGDocument does. Those three interfaces therefore do not need to implement GetSVGDocument. Still, authors are strongly recommended to use contentDocument instead.
[NoInterfaceObject] interface GetSVGDocument { Document getSVGDocument(); };
The getSVGDocument method is used to return a referenced SVG document. When getSVGDocument() is called, it must return the Document object referenced by the embedding element that implements the GetSVGDocument interface; if there is no document, null is returned.
Note that this does no check to see whether the referenced document is indeed an SVG document. Instead, any document is returned.