SVG 2 – 03 December 2012 TopContentsPreviousNextElementsAttributesProperties

Chapter 5: Document Structure

Contents

5.1. Defining an SVG document fragment: the ‘svg’ element

5.1.1. Overview

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 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" version="1.1">
      <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.)

In all cases, 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 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].

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.

5.1.2. The ‘svg’ element

SVG 2 Requirement: Should support the playbackOrder attribute to inform UA to not display controls to seek backwards.
Resolution: Support the playbackOrder attribute.
Purpose: To inform UA to not display controls to seek backwards.
Owner: Cyril
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)
SVG 2 Requirement: Support a means for having SMIL animations start before their time container has fully loaded.
Resolution: Timeline control.
Purpose: To start animations before the SVG document is fully loaded (useful for large SVG documents).
Owner: Cyril
‘svg’
Categories:
Container element, structural element
Content model:
Any number of the following elements, in any order:a, altGlyphDef, clipPath, color-profile, cursor, filter, font, font-face, foreignObject, image, marker, mask, pattern, script, style, switch, text, view
Attributes:
DOM Interfaces:

Attribute definitions:

Name Value Lacuna value Animatable
version <number> (none) no

Indicates the SVG language version to which this document fragment conforms.

In SVG 1.0 [SVG10], this attribute was fixed to the value '1.0'. For SVG 1.1, the attribute should have the value '1.1'.

What are we doing with the version attribute? It's not clear whether it is useful to keep.

Name Value Lacuna value Animatable
baseProfile <anything> none no

Describes the minimum SVG language profile that the author believes is necessary to correctly render the content. The attribute does not specify any processing restrictions; It can be considered metadata. For example, the value of the attribute could be used by an authoring tool to warn the user when they are modifying the document beyond the scope of the specified base profile. Each SVG profile should define the text that is appropriate for this attribute.

It's unlikely SVG 2 will have profiles as 1.0 and 1.1 did. Do we keep the attribute in case others wish to profile SVG? (Or should we be discouraging that?)

Name Value Lacuna value Animatable
x, y <coordinate> 0 yes

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.

Name Value Lacuna value Animatable
width, height <length> | <percentage> 100% yes

For outermost svg elements, the width and height attributes specify the intrinsice 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.

A negative value is an error (see Error processing). A value of zero disables rendering of the element.

When zero is used on an outer svg element, does this disable rendering too? Or does it just affect the intrinsic size?

Name Value Lacuna value Animatable
preserveAspectRatio defer? <align> [ meet | slice ]? xMidYMid meet yes

Specifies the fitting behavior when the aspect ratio of the svg element does not match the aspect ratio of the rectangle it is placed in. See the definition of preserveAspectRatio for details.

Name Value Lacuna 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.

Name Value Lacuna value Animatable
playbackOrder forwardOnly | all all no

This attribute may be harmonized and/or replaced with the work done as part of the Web Animation specification.

Indicates whether it is possible to seek backwards in the document. In earlier versions of SVG there was no need to put restrictions on the direction of seeking but with the newly introduced facilities for long-running documents (e.g. the ‘discard’ element) there is sometimes a need to restrict this.

If ‘playbackOrder’ is set to 'forwardOnly', the content will probably contain discard elements or scripts that destroy resources, thus seeking back in the document's timeline may result in missing content. If ‘playbackOrder’ is 'forwardOnly', the content should not provide a way, through hyperlinking or script, of seeking backwards in the timeline. Similarly the UA should disable any controls it may provide in the user interface for seeking backwards. Content with playbackOrder="forwardOnly" that provides a mechanism for seeking backwards in time may result in undefined behavior or a document that is in error.

Can't we define this so that there is no undefined behavior?

Attribute values have the following meanings:

'forwardOnly'
This file is intended to be played only in the forward direction, sequentially, therefore seeking backwards should not be allowed.
'all'
Indicates that the document is authored appropriately for seeking in both directions.
Name Value Lacuna value Animatable
timelineBegin onLoad | onStart onLoad no

This attribute may be harmonized and/or replaced with the work done as part of the Web Animation specification.

Controls the initialization of the timeline for the document.

The svg element controls the document timeline, which is the timeline of the svg element's time container. For progressively loaded animations, the author would typically set this attribute to 'onStart', thus allowing the timeline to begin as the document loads, rather than waiting until the complete document is loaded.

Attribute values have the following meanings:

'onLoad'
The document's timeline starts the moment the load event for the rootmost ‘svg’ element is triggered.
'onStart'
The document's timeline starts at the moment the rootmost ‘svg’ element's start-tag as defined in XML 1.0 ([XML10], section 3.1) is fully parsed and processed.

What about when the SVG document fragment is within an XHTML document? Is there a single timeline for the whole document, and if so, does it start at the parse time for the first <svg> start tag? What about when using the HTML parser?

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.

This paragraph feels out of place just after the list of attributes specific to svg.

5.2. Grouping: the ‘g’ element

5.2.1. Overview

The g element is a container element for grouping together related graphics elements.

Grouping constructs, when used in conjunction with the desc and title elements, provide information about document structure and semantics. Documents that are rich in structure may be rendered graphically, as speech, or as braille, and thus promote accessibility.

That generously structured content with title and desc is more accessible isn't necessarily true. It also seems like a stretch to claim that documents "rich in structure" can be rendered as speech or braille, without specific references to how that can be achieved. More fundamental uses of grouping that should be mentioned are (a) for specifying common styling of inherited properties, and (b) for selecting elements to apply a group effect like filters and group opacity.

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>

View this example as SVG (SVG-enabled browsers only)

A g element can contain other g elements nested within it, to an arbitrary depth. Thus, the following is possible:

<?xml version="1.0" standalone="no"?>
<svg xmlns="http://www.w3.org/2000/svg"
     version="1.1" width="4in" height="3in">
  <desc>Groups can nest</desc>
  <g>
     <g>
       <g>
       </g>
     </g>
   </g>
</svg>

This is not a particularly useful example.

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)

Any element that is not contained within a g is treated (at least conceptually) as if it were in its own group.

It is unclear what this sentence actually means. Does it mean that all operations that apply to groups (such as group opacity, filter effects, etc.) can apply to single elements too? If so, then it should say that.

5.2.2. The ‘g’ element

‘g’
Categories:
Container element, structural element
Content model:
Any number of the following elements, in any order:a, altGlyphDef, clipPath, color-profile, cursor, filter, font, font-face, foreignObject, image, marker, mask, pattern, script, style, switch, text, view
Attributes:
DOM Interfaces:

5.3.1. Overview

SVG allows graphical objects to be defined for later reuse. To do this, it makes extensive use of IRI 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: altGlyphDef, clipPath, cursor, filter, linearGradient, marker, mask, pattern, radialGradient and symbol. Defining these elements inside of a defs element promotes understandability of the SVG content and thus promotes accessibility.

Again this claim about accessibility is dubious.

We should have a term for definition elements (since we now have a corresponding IDL interface) and reference it here.

5.3.2. The ‘defs’ element

‘defs’
Categories:
Container element, structural element
Content model:
Any number of the following elements, in any order:a, altGlyphDef, clipPath, color-profile, cursor, filter, font, font-face, foreignObject, image, marker, mask, pattern, script, style, switch, text, view
Attributes:
DOM Interfaces:

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.

To provide some SVG user agents with an opportunity to implement efficient implementations in streaming environments, creators of SVG content are encouraged to place all elements which are targets of local IRI references within a defs element which is a direct child of one of the ancestors of the referencing element. For example:

Is this really about efficiency of implementations? If anything, it looks like it is ensuring progressively rendered documents don't make forward references that would otherwise cause an incorrect rendering before the referenced element is loaded.

<?xml version="1.0" standalone="no"?>
<svg width="8cm" height="3cm"
     xmlns="http://www.w3.org/2000/svg" version="1.1">
  <desc>Local URI references within ancestor's 'defs' element.</desc>
  <defs>
    <linearGradient id="Gradient01">
      <stop offset="20%" stop-color="#39F" />
      <stop offset="90%" stop-color="#F3F" />
    </linearGradient>
  </defs>
  <rect x="1cm" y="1cm" width="6cm" height="1cm" 
        fill="url(#Gradient01)"  />

  <!-- Show outline of canvas using 'rect' element -->
  <rect x=".01cm" y=".01cm" width="7.98cm" height="2.98cm"
        fill="none" stroke="blue" stroke-width=".02cm" />

</svg>

View this example as SVG (SVG-enabled browsers only)

In the document above, the linear gradient is defined within a defs element which is the direct child of the svg element, which in turn is an ancestor of the rect element which references the linear gradient. Thus, the above document conforms to the guideline.

5.4. The ‘discard’ element

Would this element be better as part of the Animation chapter? It also needs to be a member of the element categories that other animation elements are, and an IDL interface needs to be written for it.

SVG 2 Requirement: Have the discard element to declaratively discard elements from the document tree.
Resolution: SVG 2 will support the discard element.
Purpose: To conserve memory while displaying long-running documents.
Owner: Cyril (ACTION-3319)
‘discard’
Categories:
Animation element
Content model:
Any number of the following elements, in any order:
Attributes:
DOM Interfaces:
  • @@ unknown interface "SVGDiscardElement"

The ‘discard’ element allows authors to specify the time at which particular elements are to be discarded, thereby reducing the resources required by an SVG user agent. This is particularly useful to help SVG viewers conserve memory while displaying long-running documents. This element will not be processed by static SVG viewers.

The ‘discard’ element may occur wherever the ‘animate’ element may.

Attribute definitions:

Name Value Lacuna value Animatable
href <iri> (none) no

An IRI reference that identifies the target element to discard. See the definition of ‘href’ on animation elements for details on identifying a target element.

Note that if the target element is not part of the current SVG document fragment then whether the target element will be removed or not is defined by the host language.

If the href attribute is not provided, then the target element will be the immediate parent element of the discard element.

Name Value Lacuna value Animatable
begin <begin-value-list> 0s no

Indicates when the target element will be discarded. See the definition of ‘begin’ on animation elements for details.

The ‘discard’ element has an implicit simple duration of "indefinite". As soon as the element's active duration starts, the SVG user agent discards the element identified by the ‘href’ attribute ([SMIL], section 5.4.5). The removal operation acts as if removeChild were called on the parent of the target element with the target element as parameter. [DOM4] The SVG user agent must remove the target node as well as all of its attributes and descendants.

After removal of the target element, the ‘discard’ element is no longer useful. It must also be discarded following the target element removal. If the ‘href’ attribute has an invalid IRI reference (the target element did not exist, for example), the ‘discard’ element itself must still be removed following activation.

Seeking backwards in the timeline ([SMIL], section 5.4.5) must not re-insert the discarded elements. Discarded elements are intended to be completely removed from memory. So, authors are encouraged to set the ‘playbackOrder’ attribute to "forwardOnly" when using the ‘discard’ element.

The ‘discard’ element itself can be discarded prior to its activation, in which case it will never trigger the removal of its own target element. SVG user agents must allow the ‘discard’ element to be the target of another ‘discard’ element.

The following example demonstrates a simple usage of the ‘discard’ element. The list below describes relevant behavior in the document timeline of this example:

At time = 0:
When the document timeline starts, the blue ellipse starts to move down the page.
At time = 1 second:
The red rectangle starts moving up the page.
At time = 2 seconds:
The ‘animateTransform’ on the ‘ellipse’ ends. The ‘ellipse’ and its children are also discarded, as it is the target element of a ‘discard’ with begin="2". The green ‘polygon’ starts to move across the page.
At time = 3 seconds:
The animation on the red rectangle ends. The rectangle and its children are discarded as it is the target of a ‘discard’ element with begin="3".
At time = 4 seconds:
The animation on the green triangle ends. The green ‘polygon’ and its children are discarded as it is the target of a ‘discard’ element with begin="4".
<svg xmlns="http://www.w3.org/2000/svg" width="352" height="240" playbackOrder="forwardOnly">
    
  <ellipse cx="98.5" cy="17.5" rx="20.5" ry="17.5" fill="blue" stroke="black" 
           transform="translate(9 252) translate(3 -296)">
    <animateTransform attributeName="transform" begin="0s" dur="2s" fill="remove"
                      calcMode="linear" type="translate" additive="sum"
                      from="0 0" to="-18 305"/>
    <discard begin="2s"/>
  </ellipse>
  
  <rect x="182" y="-39" width="39" height="30" fill="red" stroke="black"
        transform="translate(30 301)">
    <animateTransform attributeName="transform" begin="1s" dur="2s" fill="remove"
                      calcMode="linear" type="translate" additive="sum"
                      from="0 0" to="-26 -304"/>
    <discard begin="3s"/>
  </rect>
  
  <polygon points="-66,83.5814 -43,123.419 -89,123.419" fill="green" stroke="black" 
           transform="matrix(1 0 0 1.1798 0 -18.6096)">
    <animateTransform attributeName="transform" begin="2s" dur="2s"
                      fill="remove" calcMode="linear" type="translate" additive="sum"
                      from="0 0" to="460 63.5699"/>
    <discard begin="4s"/>
  </polygon>
</svg>

View this example as SVG (SVG-enabled browsers only)

5.5. The ‘desc’ and ‘title’ elements

‘desc’
Categories:
Descriptive element
Content model:
Any elements or character data.
Attributes:
DOM Interfaces:
‘title’
Categories:
Descriptive element
Content model:
Any elements or character data.
Attributes:
DOM Interfaces:

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. 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. This is readily achieved by using a different (perhaps user) style sheet. 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.

I don't think it is easy to use a style sheet to cause an element's title to be rendered in place of its graphics.

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.

'lang' should be defined here (rather than pointing to the glyph definition).

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"
     version="1.1" 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. Here is an example:

<?xml version="1.0" standalone="yes"?>
<svg xmlns="http://www.w3.org/2000/svg"
     version="1.1" width="4in" height="3in">
  <desc xmlns:mydoc="http://example.org/mydoc">
    <mydoc:title>This is an example SVG file</mydoc:title>
    <mydoc:para>The global description uses markup from the 
      <mydoc:emph>mydoc</mydoc:emph> namespace.</mydoc:para>
  </desc>
  <g>
    <!-- the picture goes here -->
  </g>
</svg>

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.

Authors should always provide a title child element to the outermost svg element within a stand-alone SVG document. The title child element to an svg element serves the purposes of identifying the content of the given SVG document fragment. 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).

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.

5.6. The ‘symbol’ element

‘symbol’
Categories:
Container element, structural element
Content model:
Any number of the following elements, in any order:a, altGlyphDef, clipPath, color-profile, cursor, filter, font, font-face, foreignObject, image, marker, mask, pattern, script, style, switch, text, view
Attributes:
DOM Interfaces:

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. Documents that are rich in structure may be rendered graphically, as speech, or as braille, and thus promote accessibility.

Again this mention of accessibility through the use of structure (this time with symbol elements). We should include an example here or in the Accessibility appendix that shows how this is the case and what the actual effects of structuring content with symbol are.

The key distinctions between a symbol and a g are:

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.

5.7. The ‘use’ element

‘use’
Categories:
Graphics element, graphics referencing element, structural element
Content model:
Any number of the following elements, in any order:mask
Attributes:
DOM Interfaces:

Any svg, symbol, g, graphics element or other use is potentially a template object that can be re-used (i.e., "instanced") in the SVG document via a use element. 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.

Unlike image, the use element cannot reference entire files.

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

We should define the behavior of use in terms of Web Components.

For user agents that support Styling with CSS, 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.

We should be requiring CSS styling in SVG 2. Also, hopefully, how styles can apply or not to elements in the shadow tree (and how event handling works, below) should be specified by how we define use to work in terms of Web Components.

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.

If event attributes are assigned to referenced elements, then the actual target for the event will be the SVGElementInstance object within the "instance tree" corresponding to the given referenced element.

Once we define use in terms of Web Components, will we drop instance trees?

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, except that events are dispatched to the SVGElementInstance objects. The event's target and currentTarget attributes are set to the SVGElementInstance 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.

An element and all its corresponding SVGElementInstance objects share an event listener list. The currentTarget attribute of the event can be used to determine through which object an event listener was invoked.

The behavior of the ‘visibility’ property conforms to this model of property inheritance. Thus, 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'.

Why is ‘visibility’ called out speciically? It might be better just to include an example that shows this.

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.

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" xmlns:xlink="http://www.w3.org/1999/xlink">
  <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" xlink:href="#MyRect" />
</svg>
Example Use01 — Simple case of 'use' on a 'rect'

Example Use01

View this example as SVG (SVG-enabled browsers only)

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>

View this example as SVG (SVG-enabled browsers only)

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" xmlns:xlink="http://www.w3.org/1999/xlink">
  <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" 
       xlink:href="#MySymbol" />
</svg>
Example Use02 — 'use' on a 'symbol'

Example Use02

View this example as SVG (SVG-enabled browsers only)

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>

View this example as SVG (SVG-enabled browsers only)

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" xmlns:xlink="http://www.w3.org/1999/xlink">
  <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 xlink:href="#MyRect"
       transform="translate(20,2.5) rotate(10)" />
</svg>
Example Use03 — 'use' with a 'transform' property

Example Use03

View this example as SVG (SVG-enabled browsers only)

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>

View this example as SVG (SVG-enabled browsers only)

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" version="1.1"
     xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
  <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" xlink:href="#MyPath" 
         class="MyUseClass"
         style="/* rule 12 */ stroke-dashoffset:50" />
  </g>
</svg>
Example Use04 — 'use' with CSS styling

Example Use04

View this example as SVG (SVG-enabled browsers only)

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>

View this example as SVG (SVG-enabled browsers only)

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 Lacuna value Animatable
x, y <coordinate> 0 yes
width, height <length> (see prose) yes

The x, y, width and height attributes specify the positioning of the referenced element. The width and height attributes have different lacuna values depending on the type of the referenced element:

svg
The lacuna values are the width and height values from the referenced svg element.
anything else
The lacuna values are '100%'.

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 Lacuna value Animatable
href <iri> (none) yes

An IRI reference to the element/fragment within an SVG document to be cloned for rendering.

5.8. The ‘image’ element

‘image’
Categories:
Graphics element, graphics referencing element
Content model:
Any number of the following elements, in any order:mask
Attributes:
DOM Interfaces:

The image element indicates that the contents of a complete file are to be rendered into a given rectangle within the current user coordinate system. The image element can refer to raster image files such as PNG or JPEG or to files with MIME type of "image/svg+xml". Conforming SVG viewers need to support at least PNG, JPEG and SVG format files.

The result of processing an image is always a four-channel RGBA result. When an image element references a raster image file such as PNG or JPEG files which only has three channels (RGB), then the effect is as if the object were converted into a 4-channel RGBA image with the alpha channel uniformly set to 1. For a single-channel raster image, the effect is as if the object were converted into a 4-channel RGBA image, where the single channel from the referenced object is used to compute the three color channels and the alpha channel is uniformly set to 1.

An image element establishes a new viewport for the referenced file as described in Establishing a new viewport. The bounds for the new viewport are defined by attributes x, y, width and height. The placement and scaling of the referenced image are controlled by the preserveAspectRatio attribute on the image element.

When an image element references an SVG image, the ‘clip’ and ‘overflow’ properties on the root element in the referenced SVG image are ignored (in the same manner as the x, y, width and height attributes are ignored). Unless the value of preserveAspectRatio on the image element starts with 'defer', the preserveAspectRatio attribute on the root element in the referenced SVG image is also ignored (see preserveAspectRatio for details). Instead, the preserveAspectRatio attribute on the referencing image element defines how the SVG image content is fitted into the viewport and the ‘clip’ and ‘overflow’ properties on the image element define how the SVG image content is clipped (or not) relative to the viewport.

Why does it make sense to override ‘clip’ but not ‘clip-path’?

The value of the viewBox attribute to use when evaluating the preserveAspectRatio attribute is defined by the referenced content. For content that clearly identifies a viewBox (e.g. an SVG file with the viewBox attribute on the outermost svg element) that value should be used. For most raster content (PNG, JPEG) the bounds of the image should be used (i.e. the image element has an implicit viewBox of '0 0 raster-image-width raster-image-height'). Where no value is readily available (e.g. an SVG file with no viewBox attribute on the outermost svg element) the preserveAspectRatio attribute is ignored, and only the translation due to the x & y attributes of the viewport is used to display the content.

We should say how the use of an #xywh media fragment interacts with the the above.

For example, if the image element referenced a PNG or JPEG and preserveAspectRatio="xMinYMin meet", then the aspect ratio of the raster would be preserved (which means that the scale factor from image's coordinates to current user space coordinates would be the same for both X and Y), the raster would be sized as large as possible while ensuring that the entire raster fits within the viewport, and the top/left of the raster would be aligned with the top/left of the viewport as defined by the attributes x, y, width and height on the image element. If the value of preserveAspectRatio was 'none' then aspect ratio of the image would not be preserved. The image would be fitted such that the top/left corner of the raster exactly aligns with coordinate (x, y) and the bottom/right corner of the raster exactly aligns with coordinate (x+width, y+height).

The resource referenced by the image element represents a separate document which generates its own parse tree and document object model (if the resource is XML). Thus, there is no inheritance of properties into the image.

Unlike use, the image element cannot reference elements within an SVG file.

SVG 2 Requirement: Support auto-sized images.
Resolution: We will allow auto-sized images in SVG 2.
Purpose: To allow raster images to use their own size without the need to set width and height.
Owner: Cameron (ACTION-3340)
SVG 2 Requirement: Support selecting part of an image for display.
Resolution: We will have a method for ‘image’ to select a part of an image to display, maybe by allowing ‘viewBox’ on it.
Purpose: To allow selection of part of an image without requiring the author to manually slice the image.
Owner: Nobody
SVG 2 Requirement: Support the ‘object-fit’ and ‘object-position’ properties from css3-images.
Resolution: SVG 2 will depend on CSS3 Image Values and CSS4 Image Values.
Purpose: To align with the CSS way of specifying image fitting that preserveAspectRatio provides.
Owner: Cameron or Erik (no action)

Attribute definitions:

Name Value Lacuna value Animatable
x, y <coordinate> 0 yes
width, height <length> 0 yes

The x, y, width and height attributes specify the rectangular region into which the referenced image is placed.

A negative value for width or height is invalid (see Error processing). A value of zero for either attribute disables rendering of the element.

Name Value Lacuna value Animatable
xlink:href <iri> (none) yes

An IRI reference identifying the image to render.

Name Value Lacuna value Animatable
preserveAspectRatio defer? <align> [ meet | slice ]? xMidYMid meet yes

Specifies the fitting behavior when the aspect ratio of the referenced image does not match the aspect ratio of the rectangle it is placed in. See the definition of preserveAspectRatio for details.

An example:

<?xml version="1.0" standalone="no"?>
<svg width="4in" height="3in" version="1.1"
     xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
  <desc>This graphic links to an external image
  </desc>
  <image x="200" y="200" width="100px" height="100px"
         xlink:href="myimage.png">
    <title>My image</title>
  </image>
</svg>

5.9. Conditional processing

5.9.1. Conditional processing overview

SVG contains a switch element along with attributes requiredFeatures, 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 requiredFeatures, requiredExtensions and systemLanguage act as tests and return either true or false results. 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.

It sounds strange to talk about attributes "returning" a value.

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:

5.9.2. The ‘switch’ element

‘switch’
Categories:
Container element
Content model:
Any number of the following elements, in any order:a, foreignObject, g, image, mask, svg, switch, text, use
Attributes:
DOM Interfaces:

The switch element evaluates the requiredFeatures, 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.

For more information and an example, see Embedding foreign object types.

5.9.3. The ‘requiredFeatures’ attribute

Name Value Lacuna value Animatable
requiredFeatures list-of-features (none) no

Need a grammar for list-of-features.

The value is a list of feature strings, with the individual values separated by white space. Determines whether all of the named features are supported by the user agent. Only feature strings defined in the Feature String appendix are allowed. If all of the given features are supported, then the attribute evaluates to true; otherwise, the current element and its children are skipped and thus will not be rendered.

If the attribute is not present, then its implicit return value is "true". If a null string or empty string value is given to attribute requiredFeatures, the attribute returns "false".

requiredFeatures is often used in conjunction with the switch element. If the requiredFeatures is used in other situations, then it represents a simple switch on the given element whether to render the element or not.

5.9.4. The ‘requiredExtensions’ attribute

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 IRI reference.

Name Value Lacuna value Animatable
requiredExtensions list-of-extensions (none) no

The value is a list of IRI 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 IRI reference contains white space within itself, that white space must be escaped.

If the attribute is not present, then its implicit return value is "true". If a null string or empty string value is given to attribute requiredExtensions, the attribute returns "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 IRI 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.

5.9.5. The ‘systemLanguage’ attribute

The attribute value is a comma-separated list of language names 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.

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.

For the systemLanguage attribute: Animatable: no.

If the attribute is not present, then its implicit return value is "true". If a null string or empty string value is given to attribute systemLanguage, the attribute returns "false".

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.

Should have an attribute definition table in this section.

5.9.6. Applicability of test attributes

The following list describes the applicability of the test attributes to the elements that do not directly produce rendering.

This was already mentioned in the "Conditional processing overview" section. We should just describe this once.

5.10. Common attributes

5.10.1. Attributes common to all elements: ‘id’ and ‘xml:base’

The id and xml:base attributes are available on all SVG elements:

Name Value Lacuna value Animatable
id name (none) no

Need a grammar for name.

Standard XML attribute for assigning a unique name to an element. Refer to the Extensible Markup Language (XML) 1.0 Recommendation [XML10].

Name Value Lacuna value Animatable
xml:base <iri> (none) no

Specifies a base IRI other than the base IRI of the document or external entity. Refer to the XML Base specification [XML-BASE].

Are we happy to keep promoting the use of ‘xml:base’? Is it a use case worth trying to include a more HTML-like syntax for – the ‘base’ element? We anyway need to define somewhere what effect the HTML ‘base’ element has on any SVG document fragments.

5.10.2. The ‘xml:lang’ and ‘xml:space’ attributes

Elements that might contain character data content have attributes xml:lang and xml:space.

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 and ACTION-3005, done)

Should we be moving ‘lang’ instead of ‘xlink:lang’?

Name Value Lacuna value Animatable
xml:lang languageID (none) no

Need a grammar for languageID.

Standard XML attribute to specify the language (e.g., English) used in the contents and attribute values of particular elements. Refer to the Extensible Markup Language (XML) 1.0 Recommendation [XML10].

Name Value Lacuna value Animatable
xml:space default | preserve default no

Deprecated XML attribute to specify whether white space is preserved in character data. The only possible values are 'default' and 'preserve'. 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.

5.11. DOM interfaces

5.11.1. Interface Document

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 ‘href’ 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.

HTML defines title, referrer and domain. We should remove them and file a bug on HTML to ensure that title does the right thing for SVG documents.

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 DOMString title;
  readonly attribute DOMString referrer;
  readonly attribute DOMString domain;
  readonly attribute SVGSVGElement rootElement;
};
Attributes:
title (readonly DOMString)
The title of a document as specified by the title sub-element of the svg root element (i.e., <svg><title>Here is the title</title>...</svg>)
referrer (readonly DOMString)
Returns the URI of the page that linked to this page. The value is an empty string if the user navigated to the page directly (not through a link, but, for example, via a bookmark).
domain (readonly DOMString)
The domain name of the server that served the document, or a null string if the server cannot be identified by a domain name.
rootElement (readonly SVGSVGElement)
The root svg in the document hierarchy.

5.11.2. Interface SVGSVGElement

A key interface definition is the SVGSVGElement interface, which is the interface that corresponds to the svg element. This interface contains various miscellaneous commonly-used utility methods, such as matrix operations and the ability to control the time of redraw on visual rendering devices.

SVGSVGElement implements ViewCSS and DocumentCSS to provide access to the computed values of properties and the override style sheet as described in DOM Level 2 Style [DOM2STYLE].

Does it make sense for SVGSVGElement to implement ViewCSS and DocumentCSS? Shouldn't the former be on Window and the latter on Document or SVGDocument?

interface SVGSVGElement : SVGGraphicsElement {

  readonly attribute SVGAnimatedLength x;
  readonly attribute SVGAnimatedLength y;
  readonly attribute SVGAnimatedLength width;
  readonly attribute SVGAnimatedLength height;
  readonly attribute SVGRect viewport;
  readonly attribute float pixelUnitToMillimeterX;
  readonly attribute float pixelUnitToMillimeterY;
  readonly attribute float screenPixelToMillimeterX;
  readonly attribute float screenPixelToMillimeterY;
  readonly attribute boolean useCurrentView;
  readonly attribute SVGViewSpec currentView;
           attribute float currentScale;
  readonly attribute SVGPoint currentTranslate;

  unsigned long suspendRedraw(unsigned long maxWaitMilliseconds);
  void unsuspendRedraw(unsigned long suspendHandleID);
  void unsuspendRedrawAll();
  void forceRedraw();
  void pauseAnimations();
  void unpauseAnimations();
  boolean animationsPaused();
  float getCurrentTime();
  void setCurrentTime(float seconds);
  NodeList getIntersectionList(SVGRect rect, SVGElement referenceElement);
  NodeList getEnclosureList(SVGRect rect, SVGElement referenceElement);
  boolean checkIntersection(SVGElement element, SVGRect rect);
  boolean checkEnclosure(SVGElement element, SVGRect rect);
  void deselectAll();
  SVGNumber createSVGNumber();
  SVGLength createSVGLength();
  SVGAngle createSVGAngle();
  SVGPoint createSVGPoint();
  SVGMatrix createSVGMatrix();
  SVGRect createSVGRect();
  SVGTransform createSVGTransform();
  SVGTransform createSVGTransformFromMatrix(SVGMatrix matrix);
  Element getElementById(DOMString elementId);
};

SVGSVGElement implements ViewCSS;
SVGSVGElement implements DocumentCSS;
SVGSVGElement implements SVGFitToViewBox;
SVGSVGElement implements SVGZoomAndPan;
Attributes:
x (readonly SVGAnimatedLength)
Corresponds to attribute x on the given svg element.
y (readonly SVGAnimatedLength)
Corresponds to attribute y on the given svg element.
width (readonly SVGAnimatedLength)
Corresponds to attribute width on the given svg element.
height (readonly SVGAnimatedLength)
Corresponds to attribute height on the given svg element.
viewport (readonly SVGRect)

The position and size of the viewport (implicit or explicit) that corresponds to this svg element. When the user agent is actually rendering the content, then the position and size values represent the actual values when rendering. The position and size values are unitless values in the coordinate system of the parent element. If no parent element exists (i.e., svg element represents the root of the document tree), if this SVG document is embedded as part of another document (e.g., via the HTML ‘object’ element), then the position and size are unitless values in the coordinate system of the parent document. (If the parent uses CSS or XSL layout, then unitless values represent pixel units for the current CSS or XSL viewport, as described in the CSS2 specification.) If the parent element does not have a coordinate system, then the user agent should provide reasonable default values for this attribute.

The SVGRect object is read only.

pixelUnitToMillimeterX (readonly float)
Size of a pixel units (as defined by CSS2) along the x-axis of the viewport, which represents a unit somewhere in the range of 70dpi to 120dpi, and, on systems that support this, might actually match the characteristics of the target medium. On systems where it is impossible to know the size of a pixel, a suitable default pixel size is provided.

Should this and the next three IDL attributes be removed? Are they implemented?

pixelUnitToMillimeterY (readonly float)
Corresponding size of a pixel unit along the y-axis of the viewport.
screenPixelToMillimeterX (readonly float)
User interface (UI) events in DOM Level 2 indicate the screen positions at which the given UI event occurred. When the user agent actually knows the physical size of a "screen unit", this attribute will express that information; otherwise, user agents will provide a suitable default value such as .28mm.
screenPixelToMillimeterY (readonly float)
Corresponding size of a screen pixel along the y-axis of the viewport.
useCurrentView (readonly boolean)
The initial view (i.e., before magnification and panning) of the current innermost SVG document fragment can be either the "standard" view (i.e., based on attributes on the svg element such as viewBox) or to a "custom" view (i.e., a hyperlink into a particular view or other element - see Linking into SVG content: IRI fragments and SVG views). If the initial view is the "standard" view, then this attribute is false. If the initial view is a "custom" view, then this attribute is true.
currentView (readonly SVGViewSpec)

The definition of the initial view (i.e., before magnification and panning) of the current innermost SVG document fragment. The meaning depends on the situation:

The object itself and its contents are both read only.

currentScale (float)
On an outermost svg element, this attribute indicates the current scale factor relative to the initial view to take into account user magnification and panning operations, as described under Magnification and panning. DOM attributes currentScale and currentTranslate are equivalent to the 2x3 matrix [a b c d e f] = [currentScale 0 0 currentScale currentTranslate.x currentTranslate.y]. If "magnification" is enabled (i.e., zoomAndPan="magnify"), then the effect is as if an extra transformation were placed at the outermost level on the SVG document fragment (i.e., outside the outermost svg element).

When accessed on an svg element that is not an outermost svg element, it is undefined what behavior this attribute has.

currentTranslate (readonly SVGPoint)
On an outermost svg element, the corresponding translation factor that takes into account user "magnification".

When accessed on an svg element that is not an outermost svg element, it is undefined what behavior this attribute has.

Operations:
unsigned long suspendRedraw(unsigned long maxWaitMilliseconds)
This method is deprecated, and is only kept due to compatibility with legacy content. Calling this method has no effect on redrawing.
Parameters
  1. unsigned long maxWaitMilliseconds
    This parameter is ignored.
Returns
The returned value is always 1.
void unsuspendRedraw(unsigned long suspendHandleID)
This method is deprecated, and is only kept due to compatibility with legacy content. Calling this method has no effect on redrawing.
Parameters
  1. unsigned long suspendHandleID
    This parameter is ignored.
void unsuspendRedrawAll()
This method is deprecated, and is only kept due to compatibility with legacy content. Calling this method has no effect on redrawing.
void forceRedraw()
In rendering environments supporting interactivity, forces the user agent to immediately redraw all regions of the viewport that require updating.

Should this method be neutered as suspendRedraw and friends have been? Do implementations actually support painting in the middle of a running script by calling this method?

void pauseAnimations()
Suspends (i.e., pauses) all currently running animations that are defined within the SVG document fragment corresponding to this svg element, causing the animation clock corresponding to this document fragment to stand still until it is unpaused.
void unpauseAnimations()
Unsuspends (i.e., unpauses) currently running animations that are defined within the SVG document fragment, causing the animation clock to continue from the time at which it was suspended.
boolean animationsPaused()
Returns true if this SVG document fragment is in a paused state.
Returns
Boolean indicating whether this SVG document fragment is in a paused state.
float getCurrentTime()
Returns the current time in seconds relative to the start time for the current SVG document fragment. If getCurrentTime is called before the document timeline has begun (for example, by script running in a script element before the document's SVGLoad event is dispatched), then 0 is returned.
Returns
The current time in seconds, or 0 if the document timeline has not yet begun.
void setCurrentTime(float seconds)
Adjusts the clock for this SVG document fragment, establishing a new current time. If setCurrentTime is called before the document timeline has begun (for example, by script running in a script element before the document's SVGLoad event is dispatched), then the value of seconds in the last invocation of the method gives the time that the document will seek to once the document timeline has begun.
Parameters
  1. float seconds
    The new current time in seconds relative to the start time for the current SVG document fragment.
NodeList getIntersectionList(SVGRect rect, SVGElement referenceElement)
Returns the list of graphics elements whose rendered content intersects the supplied rectangle. Each candidate graphics element is to be considered a match only if the same graphics element can be a target of pointer events as defined in ‘pointer-events’ processing.
Parameters
  1. SVGRect rect
    The test rectangle. The values are in the initial coordinate system for the current svg element.
  2. SVGElement referenceElement
    If not null, then any intersected element that doesn't have the referenceElement as ancestor must not be included in the returned NodeList.
Returns
A list of Elements whose content intersects the supplied rectangle. This NodeList must be implemented identically to the NodeList interface as defined in DOM4 ([DOM4], section 8.1) with the exception that the interface is not live.
NodeList getEnclosureList(SVGRect rect, SVGElement referenceElement)
Returns the list of graphics elements whose rendered content is entirely contained within the supplied rectangle. Each candidate graphics element is to be considered a match only if the same graphics element can be a target of pointer events as defined in ‘pointer-events’ processing.
Parameters
  1. SVGRect rect
    The test rectangle. The values are in the initial coordinate system for the current svg element.
  2. SVGElement referenceElement
    If not null, then any intersected element that doesn't have the referenceElement as ancestor must not be included in the returned NodeList.
Returns
A list of Elements whose content is enclosed by the supplied rectangle. This NodeList must be implemented identically to the NodeList interface as defined in DOM4 ([DOM4], section 8.1) with the exception that the interface is not live.
boolean checkIntersection(SVGElement element, SVGRect rect)
Returns true if the rendered content of the given element intersects the supplied rectangle. Each candidate graphics element is to be considered a match only if the same graphics element can be a target of pointer events as defined in ‘pointer-events’ processing.
Parameters
  1. SVGElement element
    The element on which to perform the given test.
  2. SVGRect rect
    The test rectangle. The values are in the initial coordinate system for the current svg element.
Returns
True or false, depending on whether the given element intersects the supplied rectangle.
boolean checkEnclosure(SVGElement element, SVGRect rect)
Returns true if the rendered content of the given element is entirely contained within the supplied rectangle. Each candidate graphics element is to be considered a match only if the same graphics element can be a target of pointer events as defined in ‘pointer-events’ processing.
Parameters
  1. SVGElement element
    The element on which to perform the given test.
  2. SVGRect rect
    The test rectangle. The values are in the initial coordinate system for the current svg element.
Returns
True or false, depending on whether the given element is enclosed by the supplied rectangle.
void deselectAll()
Unselects any selected objects, including any selections of text strings and type-in bars.

What is a type-in bar? Do we need deselectAll given we have DOM Selection?

SVGNumber createSVGNumber()
Creates an SVGNumber object outside of any document trees. The object is initialized to a value of zero.
Returns
An SVGNumber object.
SVGLength createSVGLength()
Creates an SVGLength object outside of any document trees. The object is initialized to the value of 0 user units.
Returns
An SVGLength object.
SVGAngle createSVGAngle()
Creates an SVGAngle object outside of any document trees. The object is initialized to the value 0 degrees (unitless).
Returns
An SVGAngle object.
SVGPoint createSVGPoint()
Creates an SVGPoint object outside of any document trees. The object is initialized to the point (0,0) in the user coordinate system.
Returns
An SVGPoint object.
SVGMatrix createSVGMatrix()
Creates an SVGMatrix object outside of any document trees. The object is initialized to the identity matrix.
Returns
An SVGMatrix object.
SVGRect createSVGRect()
Creates an SVGRect object outside of any document trees. The object is initialized such that all values are set to 0 user units.
Returns
An SVGRect object.
SVGTransform createSVGTransform()
Creates an SVGTransform object outside of any document trees. The object is initialized to an identity matrix transform (SVG_TRANSFORM_MATRIX).
Returns
An SVGTransform object.
SVGTransform createSVGTransformFromMatrix(SVGMatrix matrix)

Creates an SVGTransform object outside of any document trees. The object is initialized to the given matrix transform (i.e., SVG_TRANSFORM_MATRIX). The values from the parameter matrix are copied, the matrix parameter is not adopted as SVGTransform::matrix.

Parameters
  1. SVGMatrix matrix
    The transform matrix.
Returns
An SVGTransform object.
Element getElementById(DOMString elementId)
Searches this SVG document fragment (i.e., the search is restricted to a subset of the document tree) for an Element whose id is given by elementId. If an Element is found, that Element is returned. If no such element exists, returns null. Behavior is not defined if more than one element has this id.

Do we need this? If so, can we define it in terms of calling Document.getElementById and checking whether the returned element is within the subtree?

Parameters
  1. DOMString elementId
    The unique id value for an element.
Returns
The matching element.

5.11.3. Interface SVGGElement

The SVGSVGElement interface corresponds to the g element.
interface SVGGElement : SVGGraphicsElement {
};

5.11.4. Interface SVGDefsElement

The SVGDefsElement interface corresponds to the defs element.
interface SVGDefsElement : SVGGraphicsElement {
};

5.11.5. Interface SVGDescElement

The SVGDescElement interface corresponds to the desc element.
interface SVGDescElement : SVGElement {
};

5.11.6. Interface SVGTitleElement

The SVGTitleElement interface corresponds to the title element.
interface SVGTitleElement : SVGElement {
};

5.11.7. Interface SVGSymbolElement

The SVGSymbolElement interface corresponds to the symbol element.
interface SVGSymbolElement : SVGDefinitionElement {
};

SVGSymbolElement implements SVGFitToViewBox;

5.11.8. Interface SVGUseElement

The SVGUseElement interface corresponds to the use element.

interface SVGUseElement : SVGGraphicsElement {
  readonly attribute SVGAnimatedLength x;
  readonly attribute SVGAnimatedLength y;
  readonly attribute SVGAnimatedLength width;
  readonly attribute SVGAnimatedLength height;
  readonly attribute SVGElementInstance instanceRoot;
  readonly attribute SVGElementInstance animatedInstanceRoot;
};

SVGUseElement implements SVGURIReference;
Attributes:
x (readonly SVGAnimatedLength)
Corresponds to attribute x on the given use element.
y (readonly SVGAnimatedLength)
Corresponds to attribute y on the given use element.
width (readonly SVGAnimatedLength)
Corresponds to attribute width on the given use element.
height (readonly SVGAnimatedLength)
Corresponds to attribute height on the given use element.
instanceRoot (readonly SVGElementInstance)
The root of the "instance tree". See description of SVGElementInstance for a discussion on the instance tree.
animatedInstanceRoot (readonly SVGElementInstance)
If the xlink:href attribute is being animated, contains the current animated root of the "instance tree". If the xlink:href attribute is not currently being animated, contains the same value as instanceRoot. See description of SVGElementInstance for a discussion on the instance tree.

5.11.9. Interface SVGElementInstance

For each use element, the SVG DOM maintains a shadow tree (the "instance tree") of objects of type SVGElementInstance. An SVGElementInstance represents a single node in the instance tree. The root object in the instance tree is pointed to by the instanceRoot attribute on the SVGUseElement object for the corresponding use element.

If the use element references a simple graphics element such as a rect, then there is only a single SVGElementInstance object, and the correspondingElement attribute on this SVGElementInstance object is the SVGRectElement that corresponds to the referenced rect element.

If the use element references a g which contains two rect elements, then the instance tree contains three SVGElementInstance objects, a root SVGElementInstance object whose correspondingElement is the SVGGElement object for the g, and then two child SVGElementInstance objects, each of which has its correspondingElement that is an SVGRectElement object.

If the referenced object is itself a use, or if there are use subelements within the referenced object, the instance tree will contain recursive expansion of the indirect references to form a complete tree. For example, if a use element references a g, and the g itself contains a use, and that use references a rect, then the instance tree for the original (outermost) use will consist of a hierarchy of SVGElementInstance objects, as follows:

SVGElementInstance #1 (parentNode=null, firstChild=#2, correspondingElement is the 'g')
  SVGElementInstance #2 (parentNode=#1, firstChild=#3, correspondingElement is the other 'use')
    SVGElementInstance #3 (parentNode=#2, firstChild=null, correspondingElement is the 'rect')
interface SVGElementInstance : EventTarget {
  readonly attribute SVGElement correspondingElement;
  readonly attribute SVGUseElement correspondingUseElement;
  readonly attribute SVGElementInstance parentNode;
  readonly attribute SVGElementInstanceList childNodes;
  readonly attribute SVGElementInstance firstChild;
  readonly attribute SVGElementInstance lastChild;
  readonly attribute SVGElementInstance previousSibling;
  readonly attribute SVGElementInstance nextSibling;
};
Attributes:
correspondingElement (readonly SVGElement)
The corresponding element to which this object is an instance. For example, if a use element references a rect element, then an SVGElementInstance is created, with its correspondingElement being the SVGRectElement object for the rect element.
correspondingUseElement (readonly SVGUseElement)
The corresponding use element to which this SVGElementInstance object belongs. When use elements are nested (e.g., a use references another use which references a graphics element such as a rect), then the correspondingUseElement is the outermost use (i.e., the one which indirectly references the rect, not the one with the direct reference).
parentNode (readonly SVGElementInstance)
The parent of this SVGElementInstance within the instance tree. All SVGElementInstance objects have a parent except the SVGElementInstance which corresponds to the element which was directly referenced by the use element, in which case parentNode is null.
childNodes (readonly SVGElementInstanceList)
An SVGElementInstanceList that contains all children of this SVGElementInstance within the instance tree. If there are no children, this is an SVGElementInstanceList containing no entries (i.e., an empty list).
firstChild (readonly SVGElementInstance)
The first child of this SVGElementInstance within the instance tree. If there is no such SVGElementInstance, this returns null.
lastChild (readonly SVGElementInstance)
The last child of this SVGElementInstance within the instance tree. If there is no such SVGElementInstance, this returns null.
previousSibling (readonly SVGElementInstance)
The SVGElementInstance immediately preceding this SVGElementInstance. If there is no such SVGElementInstance, this returns null.
nextSibling (readonly SVGElementInstance)
The SVGElementInstance immediately following this SVGElementInstance. If there is no such SVGElementInstance, this returns null.

5.11.10. Interface SVGElementInstanceList

The SVGElementInstanceList interface provides the abstraction of an ordered collection of SVGElementInstance objects, without defining or constraining how this collection is implemented.
interface SVGElementInstanceList {

  readonly attribute unsigned long length;

  SVGElementInstance item(unsigned long index);
};
Attributes:
length (readonly unsigned long)
The number of SVGElementInstance objects in the list. The range of valid child indices is 0 to length-1 inclusive.
Operations:
SVGElementInstance item(unsigned long index)
Returns the indexth item in the collection. If index is greater than or equal to the number of nodes in the list, this returns null.
Parameters
  1. unsigned long index
    Index into the collection.
Returns
The SVGElementInstance object at the indexth position in the SVGElementInstanceList, or null if that is not a valid index.

5.11.11. Interface SVGImageElement

The SVGImageElement interface corresponds to the image element.

interface SVGImageElement : SVGGraphicsElement {
  readonly attribute SVGAnimatedLength x;
  readonly attribute SVGAnimatedLength y;
  readonly attribute SVGAnimatedLength width;
  readonly attribute SVGAnimatedLength height;
  readonly attribute SVGAnimatedPreserveAspectRatio preserveAspectRatio;
};

SVGImageElement implements SVGURIReference;
Attributes:
x (readonly SVGAnimatedLength)
Corresponds to attribute x on the given image element.
y (readonly SVGAnimatedLength)
Corresponds to attribute y on the given image element.
width (readonly SVGAnimatedLength)
Corresponds to attribute width on the given image element.
height (readonly SVGAnimatedLength)
Corresponds to attribute height on the given image element.
preserveAspectRatio (readonly SVGAnimatedPreserveAspectRatio)
Corresponds to attribute preserveAspectRatio on the given image element.

5.11.12. Interface SVGSwitchElement

The SVGSwitchElement interface corresponds to the switch element.
interface SVGSwitchElement : SVGGraphicsElement {
};

5.11.13. Interface GetSVGDocument

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, such as the DOM Element object that corresponds to an HTML ‘object’ element. Such DOM objects are often also required to implement the EmbeddingElement defined in the Window specification [WINDOW].

This interface is deprecated and may be dropped from future versions of the SVG specification. Authors are suggested to use the contentDocument attribute on the EmbeddingElement interface to obtain a referenced SVG document, if that interface is available.

interface GetSVGDocument {
  SVGDocument getSVGDocument();
};
Operations:
SVGDocument getSVGDocument()

This method must return the Document object embedded content in an embedding element, or null if there is no document.

Note that this is equivalent to fetching the value of the EmbeddingElement::contentDocument attribute of the embedding element, if the EmbeddingElement interface is also implemented. The author is advised to check that the document element of the returned Document is indeed an svg element instead of assuming that that will always be the case.

Returns
The Document object for the referenced document, or null if there is no document.
SVG 2 – 03 December 2012 TopContentsPreviousNextElementsAttributesProperties

5.12. WAI-ARIA Attributes

5.12.1 Role Attribute

Rendered SVG elements 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 [ARIA] Section 5.4 Definition of Roles. The WAI-ARIA role that an HTML 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.

5.12.2. State and property Attributes (all aria- attributes)

Every renderable SVG element may have WAI-ARIA state and property attributes specified. These attributes are defined by [ARIA] in Section 6.6, Definitions of States and Properties (all aria-* attributes). 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 [ARIA] Section 10.2 Mapping WAI-ARIA Value types to languages using the SVG mapping. 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 interrace, consequently state and property attributes are processed according to the [ARIA] and [ARIAIMPL] specifications.