previous next contents elements attributes properties index

04 September 2001

# 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">
          <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"?>
    <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20010904//EN"
      "http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd">
    <svg width="5cm" height="4cm"
         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>

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

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

### 5.1.2 The 'svg' element

    <!ENTITY % svgExt "" >
    <!ELEMENT svg (desc|title|metadata|defs|
                       path|text|rect|circle|ellipse|line|polyline|polygon|
                       use|image|svg|g|view|switch|a|altGlyphDef|
                       script|style|symbol|marker|clipPath|mask|
                       linearGradient|radialGradient|pattern|filter|cursor|font|
                       animate|set|animateMotion|animateColor|animateTransform|
                       color-profile|font-face
                       %ceExt;%svgExt;)* >
    <!ATTLIST svg
      xmlns CDATA #FIXED "http://www.w3.org/2000/svg"
      %stdAttrs;
      %testAttrs;
      %langSpaceAttrs;
      externalResourcesRequired %Boolean; #IMPLIED
      class %ClassList; #IMPLIED
      style %StyleSheet; #IMPLIED
      %PresentationAttributes-All;
      viewBox %ViewBoxSpec; #IMPLIED
      preserveAspectRatio %PreserveAspectRatioSpec; 'xMidYMid meet'
      zoomAndPan (disable | magnify) 'magnify'
      %graphicsElementEvents;
      %documentEvents;
      version %Number; #FIXED "1.0"
      x %Coordinate; #IMPLIED
      y %Coordinate; #IMPLIED
      width %Length; #IMPLIED
      height %Length; #IMPLIED
      contentScriptType %ContentType; "text/ecmascript"
      contentStyleType %ContentType; "text/css" >

Attribute definitions:

xmlns [:prefix] = "resource-name"
  Standard XML attribute for identifying an XML namespace. Refer to the "Namespaces in XML" Recommendation [XML-NS].
  Animatable: no.
version = "<number>"
  Indicates the SVG language version to which this document fragment conforms.
  For SVG 1.0, this attribute is fixed to the value "1.0". For document fragments corresponding to future versions of the specification, this attribute will be required.
  Animatable: no.
x = "<coordinate>"
  (Has no meaning or effect on outermost 'svg' elements.)
  The x-axis coordinate of one corner of the rectangular region into which an embedded 'svg' element is placed.
  If the attribute is not specified, the effect is as if a value of "0" were specified.
  Animatable: yes.
y = "<coordinate>"
  (Has no meaning or effect on outermost 'svg' elements.)
  The y-axis coordinate of one corner of the rectangular region into which an embedded 'svg' element is placed.
  If the attribute is not specified, the effect is as if a value of "0" were specified.
  Animatable: yes.
width = "<length>"
  For outermost 'svg' elements, the intrinsic width of the SVG document fragment. For embedded 'svg' elements, the width 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.
  If the attribute is not specified, the effect is as if a value of "100%" were specified.
  Animatable: yes.
height = "<length>"
  For outermost 'svg' elements, the intrinsic height of the SVG document fragment. For embedded 'svg' elements, the height 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.
  If the attribute is not specified, the effect is as if a value of "100%" were specified.
  Animatable: yes.

Attributes defined elsewhere:
  %stdAttrs;, %langSpaceAttrs;, class, %graphicsElementEvents;, %documentEvents;, %testAttrs;, externalResourcesRequired, viewBox, preserveAspectRatio, zoomAndPan, contentScriptType, contentStyleType, style, %PresentationAttributes-All;.

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.

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

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"?>
    <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20010904//EN"
      "http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd">
    <svg width="5cm" height="5cm"
         xmlns="http://www.w3.org/2000/svg">
      <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"?>
    <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20010904//EN"
      "http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd">
    <svg width="4in" height="3in"
         xmlns="http://www.w3.org/2000/svg">
      <desc>Groups can nest
      </desc>
      <g>
         <g>
           <g>
           </g>
         </g>
       </g>
    </svg>

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

### 5.2.2 The 'g' element

    <!ENTITY % gExt "" >
    <!ELEMENT g (desc|title|metadata|defs|
                       path|text|rect|circle|ellipse|line|polyline|polygon|
                       use|image|svg|g|view|switch|a|altGlyphDef|
                       script|style|symbol|marker|clipPath|mask|
                       linearGradient|radialGradient|pattern|filter|cursor|font|
                       animate|set|animateMotion|animateColor|animateTransform|
                       color-profile|font-face
                       %ceExt;%gExt;)* >
    <!ATTLIST g
      %stdAttrs;
      %testAttrs;
      %langSpaceAttrs;
      externalResourcesRequired %Boolean; #IMPLIED
      class %ClassList; #IMPLIED
      style %StyleSheet; #IMPLIED
      %PresentationAttributes-All;
      transform %TransformList; #IMPLIED
      %graphicsElementEvents;  >

Attributes defined elsewhere:
  %stdAttrs;, %langSpaceAttrs;, class, transform, %graphicsElementEvents;, %testAttrs;, externalResourcesRequired, style, %PresentationAttributes-All;.

## 5.3 References and the 'defs' element

### 5.3.1 Overview

SVG makes extensive use of URI references [URI] to 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)"/>

In SVG, the following facilities allow URI references:

- the 'a' element
- the 'altGlyph' element
- the 'animate' element
- the 'animateColor' element
- the 'animateMotion' element
- the 'animateTransform' element
- the 'clip-path' property
- the 'color-profile' element, the 'color-profile' property and the 'src' descriptor on an @color-profile definition
- the 'cursor' element and 'cursor' property
- the 'feImage' element
- the 'fill' property
- the 'filter' element and 'filter' property
- the 'image' element
- the 'linearGradient' element
- the 'marker','marker-start','marker-mid' and 'marker-end' properties
- the 'mask' property
- the 'pattern' element
- the 'radialGradient' element
- the 'script' element
- the 'stroke' property
- the 'textpath' element
- the 'tref' element
- the 'set' element
- the 'use' element

URI references are defined in either of the following forms:

    <URI-reference> = [ <absoluteURI> | <relativeURI> ] [ "#" <elementID> ]    -or-
    <URI-reference> = [ <absoluteURI> | <relativeURI> ] [ "#xpointer(id(" <elementID> "))" ]

where <elementID> is the ID of the referenced element.

(Note that the two forms above (i.e., #<elementID> and #xpointer(id(<elementID>))) are formulated in syntaxes compatible with "XML Pointer Language (XPointer)" [XPTR]. These two formulations of URI references are the only XPointer formulations that are required in SVG 1.0 user agents.)

SVG supports two types of URI references:

- local URI references, where the URI reference does not contain an <absoluteURI> or <relativeURI> and thus only contains a fragment identifier (i.e., #<elementID> or #xpointer(id<elementID>))
- non-local URI references, where the URI reference does contain an <absoluteURI> or <relativeURI>

The following rules apply to the processing of URI references:

- URI references to nodes that do not exist shall be treated as invalid references.
- URI references to elements which are inappropriate targets for the given reference shall be treated as invalid references. For example, the 'clip-path' property can only refer to 'clipPath' elements. The property setting clip-path:url(#MyElement) is an invalid reference if the referenced element is not a 'clipPath'.

Except for the xlink:href attribute on the 'a' element and for some properties will allow for backup values in case a URI reference is invalid (see 'fill' and 'stroke'):

- An invalid local URI reference (i.e., an invalid references to a node within the current document) represents an error (see Error processing).
- When attribute externalResourcesRequired has been set to true on the referencing element or one of its ancestors, then an unresolved external URI reference (i.e., a resource that cannot be located) represents an error (see Error processing).

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.

### 5.3.2 URI reference attributes

A URI reference is specified within an href attribute in the XLink [XLINK] namespace. If the default prefix of 'xlink:' is used for attributes in the XLink namespace, then the attribute will be specified as xlink:href. The value of this attribute is a URI reference for the desired resource (or resource fragment).

The value of the href attribute must be a URI reference as defined in [RFC2396], or must result in a URI reference after the escaping procedure described below is applied. The procedure is applied when passing the URI reference to a URI resolver.

Some characters are disallowed in URI references, even if they are allowed in XML; the disallowed characters include all non-ASCII characters, plus the excluded characters listed in Section 2.4 of [RFC2396], except for the number sign (#) and percent sign (%) and the square bracket characters re-allowed in [RFC2732]. Disallowed characters must be escaped as follows:

1. Each disallowed character is converted to UTF-8 [RFC2279] as one or more bytes.

2. Any bytes corresponding to a disallowed character are escaped with the URI escaping mechanism (that is, converted to `%`HH, where HH is the hexadecimal notation of the byte value).

3. The original character is replaced by the resulting character sequence.

Because it is impractical for any application to check that a value is a URI reference, this specification follows the lead of [RFC2396] in this matter and imposes no such conformance testing requirement on SVG applications.

If the URI reference is relative, its absolute version must be computed by the method of [XML-Base] before use.

For locators into XML resources, the format of the fragment identifier (if any) used within the URI reference is specified by the XPointer specification [XPTR].

Additional XLink attributes can be specified that provide supplemental information regarding the referenced resource. These additional attributes are included in the DTD in the following entities. The two entity definitions differ only in the value of xlink:show, which has the value other in the first entity and the value embed in the second. The first entity definition is used in most element definitions which reference resources. The second entity definition is used by elements 'use', 'image' and 'feImage'.

    <!ENTITY % xlinkRefAttrs
     "xmlns:xlink CDATA #FIXED 'http://www.w3.org/1999/xlink'
      xlink:type (simple) #FIXED 'simple'
      xlink:role %URI; #IMPLIED
      xlink:arcrole %URI; #IMPLIED
      xlink:title CDATA #IMPLIED
      xlink:show (other) 'other'
      xlink:actuate (onLoad) #FIXED 'onLoad'" >

    <!ENTITY % xlinkRefAttrsEmbed
     "xmlns:xlink CDATA #FIXED 'http://www.w3.org/1999/xlink'
      xlink:type (simple) #FIXED 'simple'
      xlink:role %URI; #IMPLIED
      xlink:arcrole %URI; #IMPLIED
      xlink:title CDATA #IMPLIED
      xlink:show (embed) 'embed'
      xlink:actuate (onLoad) #FIXED 'onLoad'" >

xmlns [:prefix] = "resource-name"
  Standard XML attribute for identifying an XML namespace. This attribute makes the XLink [XLink] namespace available to the current element. Refer to the "Namespaces in XML" Recommendation [XML-NS].
  Animatable: no.
xlink:type = 'simple'
  Identifies the type of XLink being used. In SVG, only simple links are available. Refer to the "XML Linking Language (XLink)" [XLink].
  Animatable: no.
xlink:role = '<uri>'
  A URI reference that identifies some resource that describes the intended property. The value must be a URI reference as defined in [RFC2396], except that if the URI scheme used is allowed to have absolute and relative forms, the URI portion must be absolute. When no value is supplied, no particular role value is to be inferred. Disallowed URI reference characters in these attribute values must be specially encoded as described earlier in this section. Refer to the "XML Linking Language (XLink)" [XLink].
  Animatable: no.
xlink:arcrole = '<uri>'
  A URI reference that identifies some resource that describes the intended property. The value must be a URI reference as defined in [RFC2396], except that if the URI scheme used is allowed to have absolute and relative forms, the URI portion must be absolute. When no value is supplied, no particular role value is to be inferred. Disallowed URI reference characters in these attribute values must be specially encoded as described earlier in this section. The arcrole attribute corresponds to the [RDF] notion of a property, where the role can be interpreted as stating that "starting-resource HAS arc-role ending-resource." This contextual role can differ from the meaning of an ending resource when taken outside the context of this particular arc. For example, a resource might generically represent a "person," but in the context of a particular arc it might have the role of "mother" and in the context of a different arc it might have the role of "daughter." Refer to the "XML Linking Language (XLink)" [XLink].
  Animatable: no.
xlink:title = '<string>'
  The title attribute is used to describe the meaning of a link or resource in a human-readable fashion, along the same lines as the role or arcrole attribute. A value is optional; if a value is supplied, it should contain a string that describes the resource. The use of this information is highly dependent on the type of processing being done. It may be used, for example, to make titles available to applications used by visually impaired users, or to create a table of links, or to present help text that appears when a user lets a mouse pointer hover over a starting resource. Refer to the "XML Linking Language (XLink)" [XLink].
  Animatable: no.
xlink:show = 'embed'
  An application traversing to the ending resource should load its presentation in place of the presentation of the starting resource. Refer to the "XML Linking Language (XLink)" [XLink].
  Animatable: no.
xlink:actuate = 'onLoad'
  Indicates that the application should traverse to the ending resource immediately on loading the starting resource. Refer to the "XML Linking Language (XLink)" [XLink].
  Animatable: no.

In all cases, for compliance with the "Namespaces in XML" Recommendation [XML-NS], an explicit XLink namespace declaration must be provided whenever one of the above XLink attributes is used within SVG content. One simple way to provide such an XLink namespace declaration is to include an xmlns attribute for the XLink namespace on the outermost 'svg' element for content that uses XLink attributes. For example:

    <svg xmlns:xlink="http://www.w3.org/1999/xlink"...>
      <image xlink:href="foo.png" .../>
    </svg>

### 5.3.3 The 'defs' element

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.

    <!ENTITY % defsExt "" >
    <!ELEMENT defs (desc|title|metadata|defs|
                       path|text|rect|circle|ellipse|line|polyline|polygon|
                       use|image|svg|g|view|switch|a|altGlyphDef|
                       script|style|symbol|marker|clipPath|mask|
                       linearGradient|radialGradient|pattern|filter|cursor|font|
                       animate|set|animateMotion|animateColor|animateTransform|
                       color-profile|font-face
                       %ceExt;%defsExt;)* >
    <!ATTLIST defs
      %stdAttrs;
      %testAttrs;
      %langSpaceAttrs;
      externalResourcesRequired %Boolean; #IMPLIED
      class %ClassList; #IMPLIED
      style %StyleSheet; #IMPLIED
      %PresentationAttributes-All;
      transform %TransformList; #IMPLIED
      %graphicsElementEvents;  >

Attributes defined elsewhere:
  %stdAttrs;, %langSpaceAttrs;, class, transform, %testAttrs;, externalResourcesRequired, style, %PresentationAttributes-All;, %graphicsElementEvents;.

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 URI references within a 'defs' element which is a direct child of one of the ancestors of the referencing element. For example:

    <?xml version="1.0" standalone="no"?>
    <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20010904//EN" "http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd">
    <svg width="8cm" height="3cm"
         xmlns="http://www.w3.org/2000/svg">
      <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 'desc' and 'title' elements

Each container element or graphics element in an SVG drawing can supply a 'desc' and/or a 'title' description string 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.

    <!ENTITY % descExt "" >
    <!ELEMENT desc (#PCDATA %descExt;)* >
    <!ATTLIST desc
      %stdAttrs;
      %langSpaceAttrs;
      class %ClassList; #IMPLIED
      style %StyleSheet; #IMPLIED
      %StructuredText; >

Attributes defined elsewhere:
  %stdAttrs;, %langSpaceAttrs;, class, style.

    <!ENTITY % titleExt "" >
    <!ELEMENT title (#PCDATA %titleExt;)* >
    <!ATTLIST title
      %stdAttrs;
      %langSpaceAttrs;
      class %ClassList; #IMPLIED
      style %StyleSheet; #IMPLIED
      %StructuredText; >

Attributes defined elsewhere:
  %stdAttrs;, %langSpaceAttrs;, class, style.

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"?>
    <!DOCTYPE svg SYSTEM "http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd">
    <svg width="4in" height="3in"
         xmlns="http://www.w3.org/2000/svg">
    <g>
      <title>
        Company sales by region
      </title>
      <desc>
        This is a bar chart which shows
        company sales by region.
      </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 width="4in" height="3in"
     xmlns="http://www.w3.org/2000/svg">
       <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>

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

The DTD definitions of many of SVG's elements (particularly, container and text elements) place no restriction on the placement or number of the 'desc' and 'title' 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 [XML-MIXED] do not permit the desired restrictions. Representations of future versions of the SVG language might use more expressive representations than DTDs which allow for more restrictive mixed content rules. It is strongly recommended that at most one 'desc' and at most one 'title' element appear as a child of any particular element, and that these elements appear before any other child elements (except possibly 'metadata' elements) or character data content. If user agents need to choose among multiple 'desc' or 'title' elements for processing (e.g., to decide which string to use for a tooltip), the user agent shall choose the first one.

## 5.5 The 'symbol' element

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.

The key distinctions between a 'symbol' and a 'g' are:

- A 'symbol' element itself is not rendered. Only instances of a 'symbol' element (i.e., a reference to a 'symbol' by a 'use' element) are rendered.
- A 'symbol' element has attributes viewBox and preserveAspectRatio which allow a 'symbol' to scale-to-fit within a rectangular viewport defined by the referencing 'use' element.

Closely related to the 'symbol' element are the 'marker' and 'pattern' elements.

    <!ENTITY % symbolExt "" >
    <!ELEMENT symbol (desc|title|metadata|defs|
                       path|text|rect|circle|ellipse|line|polyline|polygon|
                       use|image|svg|g|view|switch|a|altGlyphDef|
                       script|style|symbol|marker|clipPath|mask|
                       linearGradient|radialGradient|pattern|filter|cursor|font|
                       animate|set|animateMotion|animateColor|animateTransform|
                       color-profile|font-face
                       %ceExt;%symbolExt;)* >
    <!ATTLIST symbol
      %stdAttrs;
      %langSpaceAttrs;
      externalResourcesRequired %Boolean; #IMPLIED
      class %ClassList; #IMPLIED
      style %StyleSheet; #IMPLIED
      %PresentationAttributes-All;
      viewBox %ViewBoxSpec; #IMPLIED
      preserveAspectRatio %PreserveAspectRatioSpec; 'xMidYMid meet'
      %graphicsElementEvents; >

Attributes defined elsewhere:
  %stdAttrs;, %langSpaceAttrs;, class, externalResourcesRequired, viewBox, preserveAspectRatio, style, %PresentationAttributes-All;, %graphicsElementEvents;.

'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.6 The 'use' element

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.

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.

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 [CSS2-CASCADE] 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.

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.

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

Animations on a referenced element will cause the instance to also be animated.

A 'use' element has the same visual effect as if the 'use' element were replaced by the following generated content:

- If the 'use' element references a 'symbol' element:
  In the generated content, the 'use' will be replaced by 'g', where all attributes from the 'use' element except for x, y, width, height 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 attribute on the generated 'g', where x and y represent the values of the x and y attributes on the 'use' 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 attributes width and height. 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:
  In the generated content, the 'use' will be replaced by 'g', where all attributes from the 'use' element except for x, y, width, height 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 attribute on the generated 'g', where x and y represent the values of the x and y attributes on the 'use' 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:
  In the generated content, the 'use' will be replaced by 'g', where all attributes from the 'use' element except for x, y, width, height 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 attribute on the generated 'g', where x and y represent the values of the x and y attributes on the 'use' element. 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 [CSS2-CASCADE]. 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"?>
    <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20010904//EN"
      "http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd">
    <svg width="10cm" height="3cm" viewBox="0 0 100 30"
         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

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"?>
    <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20010904//EN"
      "http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd">
    <svg width="10cm" height="3cm" viewBox="0 0 100 30"
         xmlns="http://www.w3.org/2000/svg">
      <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"?>
    <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20010904//EN"
      "http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd">
    <svg width="10cm" height="3cm" viewBox="0 0 100 30"
         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

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"?>
    <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20010904//EN"
      "http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd">
    <svg width="10cm" height="3cm" viewBox="0 0 100 30"
         xmlns="http://www.w3.org/2000/svg">
      <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 attribute.

    <?xml version="1.0" standalone="no"?>
    <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20010904//EN"
      "http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd">
    <svg width="10cm" height="3cm" viewBox="0 0 100 30"
         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

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"?>
    <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20010904//EN"
      "http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd">
    <svg width="10cm" height="3cm" viewBox="0 0 100 30"
         xmlns="http://www.w3.org/2000/svg">
      <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"?>
    <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20010904//EN"
      "http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd">
    <svg width="12cm" height="3cm" viewBox="0 0 1200 300"
         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

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:

- Rules 7 and 8: CSS selectors only apply to the formal document tree, not on the generated tree; thus, these selectors will not yield a match.
- Rule 9: The generated tree only inherits from the ancestors of the 'use' element and does not inherit from the ancestors of the referenced element; thus, this rule does not affect the generated content.

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"?>
    <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20010904//EN"
      "http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd">
    <svg width="12cm" height="3cm" viewBox="0 0 1200 300"
         xmlns="http://www.w3.org/2000/svg">
      <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.

    <!ENTITY % useExt "" >
    <!ELEMENT use (%descTitleMetadata;,(animate|set|animateMotion|animateColor|animateTransform
                       %geExt;%useExt;)*) >
    <!ATTLIST use
      %stdAttrs;
      %xlinkRefAttrsEmbed;
      xlink:href %URI; #REQUIRED
      %testAttrs;
      %langSpaceAttrs;
      externalResourcesRequired %Boolean; #IMPLIED
      class %ClassList; #IMPLIED
      style %StyleSheet; #IMPLIED
      %PresentationAttributes-All;
      transform %TransformList; #IMPLIED
      %graphicsElementEvents;
      x %Coordinate; #IMPLIED
      y %Coordinate; #IMPLIED
      width %Length; #IMPLIED
      height %Length; #IMPLIED >

Attribute definitions:

x = "<coordinate>"
  The x-axis coordinate of one corner of the rectangular region into which the referenced element is placed.
  If the attribute is not specified, the effect is as if a value of "0" were specified.
  Animatable: yes.
y = "<coordinate>"
  The y-axis coordinate of one corner of the rectangular region into which the referenced element is placed.
  If the attribute is not specified, the effect is as if a value of "0" were specified.
  Animatable: yes.
width = "<length>"
  The width of the rectangular region into which the referenced element is placed.
  Animatable: yes.
height = "<length>"
  The height of the rectangular region into which the referenced element is placed.
  Animatable: yes.
xlink:href = "<uri>"
  A URI reference to an element/fragment within an SVG document.
  Animatable: yes.

Attributes defined elsewhere:
  %stdAttrs;, %xlinkRefAttrsEmbed;, %testAttrs;, %langSpaceAttrs;, externalResourcesRequired, class, style, %PresentationAttributes-All;, transform, %graphicsElementEvents;.

## 5.7 The 'image' element

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.

When an 'image' element references a raster image file such as PNG or JPEG files, then the raster image is fitted into the region specified by the x, y, width and height attribute. Attribute preserveAspectRatio determines both the size and aspect ratio of the raster when fitted into the region specified by x, y, width and height. For example, if 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. If preserveAspectRatio="none", then the aspect ratio of the raster 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).

When an 'image' element references an SVG file, then the 'image' element establishes a new viewport for the SVG file as described in Establishing a new viewport. The bounds for the new viewport are defined by attributes x, y, width and height. Except for the implicit coordinate system translation that may occur due to the processing of the x and y attributes (see establishing a new viewport), the 'image' element itself does not cause any coordinate system transformations. Thus, the initial coordinate system for the referenced SVG file will be identical to the coordinate system for the new viewport. If it is necessary for the referenced SVG file to be scaled to fit into the viewport established by the 'image' element, then that outermost 'svg' element on the referenced SVG file will need to have a viewBox attribute or the referencing file will need to include appropriate transformations, perhaps by including an appropriate transform attribute on the 'image' element or one of its ancestors or by placing the 'image' element within an 'svg' element which has an appropriate viewBox attribute.

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.

    <!ENTITY % imageExt "" >
    <!ELEMENT image (%descTitleMetadata;,(animate|set|animateMotion|animateColor|animateTransform
                       %geExt;%imageExt;)*) >
    <!ATTLIST image
      %stdAttrs;
      %xlinkRefAttrsEmbed;
      xlink:href %URI; #REQUIRED
      %testAttrs;
      %langSpaceAttrs;
      externalResourcesRequired %Boolean; #IMPLIED
      class %ClassList; #IMPLIED
      style %StyleSheet; #IMPLIED
      %PresentationAttributes-Color;
      %PresentationAttributes-Graphics;
      %PresentationAttributes-Images;
      %PresentationAttributes-Viewports;
      transform %TransformList; #IMPLIED
      preserveAspectRatio %PreserveAspectRatioSpec; 'xMidYMid meet'
      %graphicsElementEvents;
      x %Coordinate; #IMPLIED
      y %Coordinate; #IMPLIED
      width %Length; #REQUIRED
      height %Length; #REQUIRED >

Attribute definitions:

x = "<coordinate>"
  The x-axis coordinate of one corner of the rectangular region into which the referenced document is placed.
  If the attribute is not specified, the effect is as if a value of "0" were specified.
  Animatable: yes.
y = "<coordinate>"
  The y-axis coordinate of one corner of the rectangular region into which the referenced document is placed.
  If the attribute is not specified, the effect is as if a value of "0" were specified.
  Animatable: yes.
width = "<length>"
  The width of the rectangular region into which the referenced document is placed.
  A negative value is an error (see Error processing). A value of zero disables rendering of the element.
  Animatable: yes.
height = "<length>"
  The height of the rectangular region into which the referenced document is placed.
  A negative value is an error (see Error processing). A value of zero disables rendering of the element.
  Animatable: yes.
xlink:href = "<uri>"
  A URI reference.
  Animatable: yes.

Attributes defined elsewhere:
  %stdAttrs;, %xlinkRefAttrsEmbed;, %testAttrs;, %langSpaceAttrs;, externalResourcesRequired, class, style, %PresentationAttributes-Color;, %PresentationAttributes-Graphics;, %PresentationAttributes-Images;, %PresentationAttributes-Viewports;, transform, preserveAspectRatio, %graphicsElementEvents;.

An example:

    <?xml version="1.0" standalone="no"?>
    <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20010904//EN"
      "http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd">
    <svg width="4in" height="3in"
         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.8 Conditional processing

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

    <!ENTITY % testAttrs
     "requiredFeatures %FeatureList; #IMPLIED
      requiredExtensions %ExtensionList; #IMPLIED
      systemLanguage %LanguageCodes; #IMPLIED" >

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.

### 5.8.2 The 'switch' element

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.

    <!ENTITY % switchExt "" >
    <!ELEMENT switch (%descTitleMetadata;,
                      (path|text|rect|circle|ellipse|line|polyline|polygon|
                       use|image|svg|g|switch|a|foreignObject|
                       animate|set|animateMotion|animateColor|animateTransform
                       %ceExt;%switchExt;)*) >
    <!ATTLIST switch
      %stdAttrs;
      %testAttrs;
      %langSpaceAttrs;
      externalResourcesRequired %Boolean; #IMPLIED
      class %ClassList; #IMPLIED
      style %StyleSheet; #IMPLIED
      %PresentationAttributes-All;
      transform %TransformList; #IMPLIED
      %graphicsElementEvents; >

Attributes defined elsewhere:
  %stdAttrs;, %langSpaceAttrs;, class, transform, %graphicsElementEvents;, %testAttrs;, externalResourcesRequired, style, %PresentationAttributes-All;.

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

### 5.8.3 The requiredFeatures attribute

Definition of requiredFeatures:

requiredFeatures = 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 this section (see below) 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.
  Animatable: no.

All feature strings referring to language capabilities begin with "org.w3c.svg". All feature strings referring to SVG DOM capabilities begin with "org.w3c.dom.svg".

The following are the feature strings for the requiredFeatures attribute. These same feature strings apply to the hasFeature method call that is part of the SVG DOM's support for the DOMImplementation interface defined in [DOM2-CORE] (see Feature strings for the hasFeature method call).

- The feature string "org.w3c.svg" indicates that the user agent supports at least one of the following (all of which are described subsequently): "org.w3c.svg.static", "org.w3c.svg.animation", "org.w3c.svg.dynamic" or "org.w3c.dom.svg". (Because the feature string "org.w3c.svg" can be ambiguous in some circumstances, it is recommended that more specific feature strings be used.)
- The feature string "org.w3c.dom.svg" indicates that the user agent supports at least one of the following (all of which are described subsequently): "org.w3c.dom.svg.static", "org.w3c.dom.svg.animation" or "org.w3c.dom.svg.dynamic". (Because the feature string "org.w3c.dom.svg" can be ambiguous in some circumstances, it is recommended that more specific feature strings be used.)
- The feature string "org.w3c.svg.static" indicates the availability of all of the language capabilities defined in:
  - Basic Data Types and Interfaces
  - Document Structure
  - Styling
  - Coordinate Systems, Transformations and Units
  - Paths
  - Basic Shapes
  - Text
  - Painting: Filling, Stroking and Marker Symbols
  - Color
  - Gradients and Patterns
  - Clipping, Masking and Compositing
  - Filter Effects
  - Fonts
  - The 'switch' element
  - The requiredFeatures attribute
  - The requiredExtensions attribute
  - The systemLanguage attribute
  For SVG viewers, "org.w3c.svg.static" indicates that the viewer can process and render successfully all of the language features listed above.
- The feature string "org.w3c.dom.svg.static" indicates the availability of all of the DOM interfaces and methods that correspond to the language features for "org.w3c.svg.static".
- The feature string "org.w3c.svg.animation" includes all of the language capabilities defined for "org.w3c.svg.static" plus the availability of all of the language capabilities defined in Animation. For SVG viewers running on media capable of rendering time-based material, such as displays, "org.w3c.svg.animation" indicates that the viewer can process and render successfully all of the corresponding language features.
- The feature string "org.w3c.dom.svg.animation" corresponds to the availability of DOM interfaces and methods that correspond to the language features for "org.w3c.svg.animation".
- The feature string "org.w3c.svg.dynamic" includes all of the language capabilities defined for "org.w3c.svg.animation" plus the availability of all of the language capabilities defined in Relationship with DOM2 events, Linking and Interactivity and Scripting. For SVG viewers running on media capable of rendering time-based material, such as displays, "org.w3c.svg.dynamic" indicates that the viewer can process and render successfully all of the corresponding language features.
- The feature string "org.w3c.dom.svg.dynamic" corresponds to the availability of DOM interfaces and methods that correspond to the language features for "org.w3c.svg.dynamic".
- The feature string "org.w3c.svg.all" corresponds to the availability of all of the language capabilities defined in this specification.
- The feature string "org.w3c.dom.svg.all" corresponds to the availability of all of the DOM interfaces defined in this specification.

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.8.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 a URI reference.

Definition of requiredExtensions:

requiredExtensions = list-of-extensions
  The value is a list of URI 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.
  Animatable: no.

If a given URI 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 URI 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.8.5 The systemLanguage attribute

The attribute value is a comma-separated list of language names as defined in [RFC3066].

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.

## 5.9 Specifying whether external resources are required for proper rendering

Documents often reference and use the contents of other files (and other Web resources) as part of their rendering. In some cases, authors want to specify that particular resources are required for a document to be considered correct.

Attribute externalResourcesRequired is available on all container elements and to all elements which potentially can reference external resources. It specifies whether referenced resources that are not part of the current document are required for proper rendering of the given container element or graphics element.

Attribute definition:

externalResourcesRequired = "false | true"
  false
    (The default value.) Indicates that resources external to the current document are optional. Document rendering can proceed even if external resources are unavailable to the current element and its descendants.
  true
    Indicates that resources external to the current document are required. If an external resource is not available, progressive rendering is suspended until that resource and all other required resources become available, have been parsed and are ready to be rendered. If a timeout event occurs on a required resource, then the document goes into an error state (see Error processing). The document remains in an error state until all required resources become available.

This attribute applies to all types of resource references, including style sheets, color profiles (see Color profile descriptions) and fonts specified by a URI reference using a 'font-face' element or a CSS @font-face specification. In particular, if an element sets externalResourcesRequired="true", then all style sheets must be available since any style sheet might affect the rendering of that element.

Attribute externalResourcesRequired is not inheritable (from a sense of attribute value inheritance), but if set on a container element, its value will apply to all elements within the container.

Because setting externalResourcesRequired="true" on a container element can have the effect of disabling progressive display of the contents of that container, tools that generate SVG content are cautioned against using simply setting externalResourcesRequired="true" on the outermost 'svg' element on a universal basis. Instead, it is better to specify externalResourcesRequired="true" on those particular graphics elements or container elements which specify need the availability of external resources in order to render properly.

For externalResourcesRequired: Animatable: no.

## 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:

    <!ENTITY % stdAttrs
     "id ID #IMPLIED
      xml:base %URI; #IMPLIED" >

Attribute definitions:

id = "name"
  Standard XML attribute for assigning a unique name to an element. Refer to the "Extensible Markup Language (XML) 1.0" Recommendation [XML10].
  Animatable: no.
xml:base = "<uri>"
  Specifies a base URI other than the base URI of the document or external entity. Refer to the "XML Base" specification [XML-BASE].
  Animatable: no.

### 5.10.2 The xml:lang and xml:space attributes

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

    <!ENTITY % langSpaceAttrs
     "xml:lang NMTOKEN #IMPLIED
      xml:space (default|preserve) #IMPLIED" >

Attribute definitions:

xml:lang = "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].
  Animatable: no.
xml:space = "{default | preserve}"
  Standard 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.
  Animatable: no.

## 5.11 DOM interfaces

The following interfaces are defined below: SVGDocument, SVGSVGElement, SVGGElement, SVGDefsElement, SVGDescElement, SVGTitleElement, SVGSymbolElement, SVGUseElement, SVGElementInstance, SVGElementInstanceList, SVGImageElement, SVGSwitchElement, GetSVGDocument.

### Interface SVGDocument

When an 'svg' element is embedded inline as a component of a document from another namespace, such as when an 'svg' element is embedded inline within an XHTML document [XHTML], then an SVGDocument object will not exist; instead, the root object in the document object hierarchy will be a Document object of a different type, such as an HTMLDocument object.

However, an SVGDocument object will indeed exist when the root element of the XML document hierarchy is an 'svg' element, such as when viewing a stand-alone SVG file (i.e., a file with MIME type "image/svg+xml"). In this case, the SVGDocument object will be the root object of the document object model hierarchy.

In the case where an SVG document is embedded by reference, such as when an XHTML 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. In this second DOM hierarchy, the root object of the document object model hierarchy is an SVGDocument object.

The SVGDocument interface contains a similar list of attributes and methods to the HTMLDocument interface described in the Document Object Model (HTML) Level 1 chapter of the [DOM1] specification.

IDL Definition

      interface SVGDocument :
                      Document,
                      events::DocumentEvent {

        readonly attribute DOMString    title;
        readonly attribute DOMString     referrer;
        readonly attribute DOMString      domain;
        readonly attribute DOMString      URL;
        readonly attribute SVGSVGElement rootElement;
      };

Attributes
  readonly DOMString title
    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>)
  readonly DOMString referrer
    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).
  readonly DOMString domain
    The domain name of the server that served the document, or a null string if the server cannot be identified by a domain name.
  readonly DOMString URL
    The complete URI of the document.
  readonly SVGSVGElement rootElement
    The root 'svg' element in the document hierarchy.

### 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 extends ViewCSS and DocumentCSS to provide access to the computed values of properties and the override style sheet as described in DOM2.

IDL Definition

      interface SVGSVGElement :
                      SVGElement,
                      SVGTests,
                      SVGLangSpace,
                      SVGExternalResourcesRequired,
                      SVGStylable,
                      SVGLocatable,
                      SVGFitToViewBox,
                      SVGZoomAndPan,
                      events::EventTarget,
                      events::DocumentEvent,
                      css::ViewCSS,
                      css::DocumentCSS {

        readonly attribute SVGAnimatedLength x;
        readonly attribute SVGAnimatedLength y;
        readonly attribute SVGAnimatedLength width;
        readonly attribute SVGAnimatedLength height;
                 attribute DOMString         contentScriptType;
                             // raises DOMException on setting
                 attribute DOMString         contentStyleType;
                             // raises DOMException on setting
        readonly attribute SVGRect           viewport;
        readonly attribute float pixelUnitToMillimeterX;
        readonly attribute float pixelUnitToMillimeterY;
        readonly attribute float screenPixelToMillimeterX;
        readonly attribute float screenPixelToMillimeterY;
                 attribute boolean useCurrentView;
                             // raises DOMException on setting
        readonly attribute SVGViewSpec currentView;
                 attribute float currentScale;
                             // raises DOMException on setting
        readonly attribute SVGPoint currentTranslate;

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

Attributes
  readonly SVGAnimatedLength x
    Corresponds to attribute x on the given 'svg' element.
  readonly SVGAnimatedLength y
    Corresponds to attribute y on the given 'svg' element.
  readonly SVGAnimatedLength width
    Corresponds to attribute width on the given 'svg' element.
  readonly SVGAnimatedLength height
    Corresponds to attribute height on the given 'svg' element.
  DOMString contentScriptType
    Corresponds to attribute contentScriptType on the given 'svg' element.
    Exceptions on setting

      DOMException |  | NO_MODIFICATION_ALLOWED_ERR: Raised on an attempt to change the value of a readonly attribute.

  DOMString contentStyleType
    Corresponds to attribute contentStyleType on the given 'svg' element.
    Exceptions on setting

      DOMException |  | NO_MODIFICATION_ALLOWED_ERR: Raised on an attempt to change the value of a readonly attribute.

  readonly SVGRect viewport

    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 object itself and its contents are both readonly.

  readonly float pixelUnitToMillimeterX
    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.
  readonly float pixelUnitToMillimeterY
    Corresponding size of a pixel unit along the y-axis of the viewport.
  readonly float screenPixelToMillimeterX
    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.
  readonly float screenPixelToMillimeterY
    Corresponding size of a screen pixel along the y-axis of the viewport.
  boolean useCurrentView
    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 fitBoxToViewport) or to a "custom" view (i.e., a hyperlink into a particular 'view' or other element - see Linking into SVG content: URI 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.
    Exceptions on setting

      DOMException |  | NO_MODIFICATION_ALLOWED_ERR: Raised on an attempt to change the value of a readonly attribute.

  readonly SVGViewSpec currentView
    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:
    - If the initial view was a "standard" view, then:
      - the values for viewBox, preserveAspectRatio and zoomAndPan within currentView will match the values for the corresponding DOM attributes that are on SVGSVGElement directly
      - the values for transform and viewTarget within currentView will be null
    - If the initial view was a link into a 'view' element, then:
      - the values for viewBox, preserveAspectRatio and zoomAndPan within currentView will correspond to the corresponding attributes for the given 'view' element
      - the values for transform and viewTarget within currentView will be null
    - If the initial view was a link into another element (i.e., other than a 'view'), then:
      - the values for viewBox, preserveAspectRatio and zoomAndPan within currentView will match the values for the corresponding DOM attributes that are on SVGSVGElement directly for the closest ancestor 'svg' element
      - the values for transform within currentView will be null
      - the viewTarget within currentView will represent the target of the link
    - If the initial view was a link into the SVG document fragment using an SVG view specification fragment identifier (i.e., #svgView(...)), then:
      - the values for viewBox, preserveAspectRatio, zoomAndPan, transform and viewTarget within currentView will correspond to the values from the SVG view specification fragment identifier

    The object itself and its contents are both readonly.

  float currentScale
    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).
    Exceptions on setting

      DOMException |  | NO_MODIFICATION_ALLOWED_ERR: Raised on an attempt to change the value of a readonly attribute.

  readonly SVGPoint currentTranslate
    The corresponding translation factor that takes into account user "magnification".
Methods
  suspendRedraw
    Takes a time-out value which indicates that redraw shall not occur until: (a) the corresponding unsuspendRedraw(suspend_handle_id) call has been made, (b) an unsuspendRedrawAll() call has been made, or (c) its timer has timed out. In environments that do not support interactivity (e.g., print media), then redraw shall not be suspended. suspend_handle_id = suspendRedraw(max_wait_milliseconds) and unsuspendRedraw(suspend_handle_id) must be packaged as balanced pairs. When you want to suspend redraw actions as a collection of SVG DOM changes occur, then precede the changes to the SVG DOM with a method call similar to suspend_handle_id = suspendRedraw(max_wait_milliseconds) and follow the changes with a method call similar to unsuspendRedraw(suspend_handle_id). Note that multiple suspendRedraw calls can be used at once and that each such method call is treated independently of the other suspendRedraw method calls.
    Parameters

      in unsigned long max_wait_milliseconds |  | The amount of time in milliseconds to hold off before redrawing the device. Values greater than 60 seconds will be truncated down to 60 seconds.

    Return value

      unsigned long |  | A number which acts as a unique identifier for the given suspendRedraw() call. This value must be passed as the parameter to the corresponding unsuspendRedraw() method call.

    No Exceptions
  unsuspendRedraw
    Cancels a specified suspendRedraw() by providing a unique suspend_handle_id.
    Parameters

      in unsigned long suspend_handle_id |  | A number which acts as a unique identifier for the desired suspendRedraw() call. The number supplied must be a value returned from a previous call to suspendRedraw()

    No Return Value
    Exceptions

      DOMException |  | This method will raise a DOMException with value NOT_FOUND_ERR if an invalid value (i.e., no such suspend_handle_id is active) for suspend_handle_id is provided.

  unsuspendRedrawAll
    Cancels all currently active suspendRedraw() method calls. This method is most useful at the very end of a set of SVG DOM calls to ensure that all pending suspendRedraw() method calls have been cancelled.
    No Parameters
    No Return Value
    No Exceptions
  forceRedraw
    In rendering environments supporting interactivity, forces the user agent to immediately redraw all regions of the viewport that require updating.
    No Parameters
    No Return Value
    No Exceptions
  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.
    No Parameters
    No Return Value
    No Exceptions
  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.
    No Parameters
    No Return Value
    No Exceptions
  animationsPaused
    Returns true if this SVG document fragment is in a paused state.
    No Parameters
    Return value

      boolean |  | Boolean indicating whether this SVG document fragment is in a paused state.

    No Exceptions
  getCurrentTime
    Returns the current time in seconds relative to the start time for the current SVG document fragment.
    No Parameters
    Return value

      float |  | The current time in seconds.

    No Exceptions
  setCurrentTime
    Adjusts the clock for this SVG document fragment, establishing a new current time.
    Parameters

      in float seconds |  | The new current time in seconds relative to the start time for the current SVG document fragment.

    No Return Value
    No Exceptions
  getIntersectionList
    Returns the list of graphics elements whose rendered content intersects the supplied rectangle, honoring the 'pointer-events' property value on each candidate graphics element.
    Parameters

      in SVGRect rect |  | The test rectangle. The values are in the initial coordinate system for the current 'svg' element.
      in SVGElement referenceElement |  | If not null, then only return elements whose drawing order has them below the given reference element.

    Return value

      NodeList |  | A list of Elements whose content intersects the supplied rectangle.

    No Exceptions
  getEnclosureList
    Returns the list of graphics elements whose rendered content is entirely contained within the supplied rectangle, honoring the 'pointer-events' property value on each candidate graphics element.
    Parameters

      in SVGRect rect |  | The test rectangle. The values are in the initial coordinate system for the current 'svg' element.
      in SVGElement referenceElement |  | If not null, then only return elements whose drawing order has them below the given reference element.

    Return value

      NodeList |  | A list of Elements whose content is enclosed by the supplied rectangle.

    No Exceptions
  checkIntersection
    Returns true if the rendered content of the given element intersects the supplied rectangle, honoring the 'pointer-events' property value on each candidate graphics element.
    Parameters

      in SVGElement element |  | The element on which to perform the given test.
      in SVGRect rect |  | The test rectangle. The values are in the initial coordinate system for the current 'svg' element.

    Return value

      boolean |  | True or false, depending on whether the given element intersects the supplied rectangle.

    No Exceptions
  checkEnclosure
    Returns true if the rendered content of the given element is entirely contained within the supplied rectangle, honoring the 'pointer-events' property value on each candidate graphics element.
    Parameters

      in SVGElement element |  | The element on which to perform the given test.
      in SVGRect rect |  | The test rectangle. The values are in the initial coordinate system for the current 'svg' element.

    Return value

      boolean |  | True or false, depending on whether the given element is enclosed by the supplied rectangle.

    No Exceptions
  deselectAll
    Unselects any selected objects, including any selections of text strings and type-in bars.
    No Parameters
    No Return Value
    No Exceptions
  createSVGNumber
    Creates an SVGNumber object outside of any document trees. The object is initialized to a value of zero.
    No Parameters
    Return value

      SVGNumber |  | An SVGNumber object.

    No Exceptions
  createSVGLength
    Creates an SVGLength object outside of any document trees. The object is initialized to the value of 0 user units.
    No Parameters
    Return value

      SVGLength |  | An SVGLength object.

    No Exceptions
  createSVGAngle
    Creates an SVGAngle object outside of any document trees. The object is initialized to the value 0 degrees (unitless).
    No Parameters
    Return value

      SVGAngle |  | An SVGAngle object.

    No Exceptions
  createSVGPoint
    Creates an SVGPoint object outside of any document trees. The object is initialized to the point (0,0) in the user coordinate system.
    No Parameters
    Return value

      SVGPoint |  | An SVGPoint object.

    No Exceptions
  createSVGMatrix
    Creates an SVGMatrix object outside of any document trees. The object is initialized to the identity matrix.
    No Parameters
    Return value

      SVGMatrix |  | An SVGMatrix object.

    No Exceptions
  createSVGRect
    Creates an SVGRect object outside of any document trees. The object is initialized such that all values are set to 0 user units.
    No Parameters
    Return value

      SVGRect |  | An SVGRect object.

    No Exceptions
  createSVGTransform
    Creates an SVGTransform object outside of any document trees. The object is initialized to an identity matrix transform (SVG_TRANSFORM_MATRIX).
    No Parameters
    Return value

      SVGTransform |  | An SVGTransform object.

    No Exceptions
  createSVGTransformFromMatrix
    Creates an SVGTransform object outside of any document trees. The object is initialized to the given matrix transform (i.e., SVG_TRANSFORM_MATRIX).
    Parameters

      in SVGMatrix matrix |  | The transform matrix.

    Return value

      SVGTransform |  | An SVGTransform object.

    No Exceptions
  getElementById
    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.
    Parameters

      in DOMString elementId |  | The unique id value for an element.

    Return value

      Element |  | The matching element.

    No Exceptions

### Interface SVGGElement

The SVGGElement interface corresponds to the 'g' element.

IDL Definition

      interface SVGGElement :
                      SVGElement,
                      SVGTests,
                      SVGLangSpace,
                      SVGExternalResourcesRequired,
                      SVGStylable,
                      SVGTransformable,
                      events::EventTarget {};

### Interface SVGDefsElement

The SVGDefsElement interface corresponds to the 'defs' element.

IDL Definition

      interface SVGDefsElement :
                      SVGElement,
                      SVGTests,
                      SVGLangSpace,
                      SVGExternalResourcesRequired,
                      SVGStylable,
                      SVGTransformable,
                      events::EventTarget {};

### Interface SVGDescElement

The SVGDescElement interface corresponds to the 'desc' element.

IDL Definition

      interface SVGDescElement :
                      SVGElement,
                      SVGLangSpace,
                      SVGStylable {};

### Interface SVGTitleElement

The SVGTitleElement interface corresponds to the 'title' element.

IDL Definition

      interface SVGTitleElement :
                      SVGElement,
                      SVGLangSpace,
                      SVGStylable {};

### Interface SVGSymbolElement

The SVGSymbolElement interface corresponds to the 'symbol' element.

IDL Definition

      interface SVGSymbolElement :
                      SVGElement,
                      SVGLangSpace,
                      SVGExternalResourcesRequired,
                      SVGStylable,
                      SVGFitToViewBox,
                      events::EventTarget {};

### Interface SVGUseElement

The SVGUseElement interface corresponds to the 'use' element.

IDL Definition

      interface SVGUseElement :
                      SVGElement,
                      SVGURIReference,
                      SVGTests,
                      SVGLangSpace,
                      SVGExternalResourcesRequired,
                      SVGStylable,
                      SVGTransformable,
                      events::EventTarget {

        readonly attribute SVGAnimatedLength   x;
        readonly attribute SVGAnimatedLength   y;
        readonly attribute SVGAnimatedLength   width;
        readonly attribute SVGAnimatedLength   height;
        readonly attribute SVGElementInstance instanceRoot;
        readonly attribute SVGElementInstance animatedInstanceRoot;
      };

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

### Interface SVGElementInstance

For each 'use' element, the SVG DOM maintains a shadow tree (the "instance tree") of objects of type SVGElementInstance. A 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, corresponding Element is the 'rect')

IDL Definition

      interface SVGElementInstance : events::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
  readonly SVGElement correspondingElement
    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 SVGElementInstance object for the 'rect' element.
  readonly SVGUseElement correspondingUseElement
    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).
  readonly SVGElementInstance parentNode
    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.
  readonly SVGElementInstanceList childNodes
    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).
  readonly SVGElementInstance firstChild
    The first child of this SVGElementInstance within the instance tree. If there is no such SVGElementInstance, this returns null.
  readonly SVGElementInstance lastChild
    The last child of this SVGElementInstance within the instance tree. If there is no such SVGElementInstance, this returns null.
  readonly SVGElementInstance previousSibling
    The SVGElementInstance immediately preceding this SVGElementInstance. If there is no such SVGElementInstance, this returns null.
  readonly SVGElementInstance nextSibling
    The SVGElementInstance immediately following this SVGElementInstance. If there is no such SVGElementInstance, this returns null.

### Interface SVGElementInstanceList

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

IDL Definition

      interface SVGElementInstanceList {

        readonly attribute unsigned long length;

        SVGElementInstance item ( in unsigned long index );
      };

Attributes
  readonly unsigned long length
    The number of SVGElementInstance objects in the list. The range of valid child indices is 0 to length-1 inclusive.
Methods
  item

    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

      in unsigned long index |  | Index into the collection.

    Return value

      SVGElementInstance |  | The SVGElementInstance object at the indexth position in the SVGElementInstanceList, or null if that is not a valid index.

    No Exceptions

### Interface SVGImageElement

The SVGImageElement interface corresponds to the 'image' element.

IDL Definition

      interface SVGImageElement :
                      SVGElement,
                      SVGURIReference,
                      SVGTests,
                      SVGLangSpace,
                      SVGExternalResourcesRequired,
                      SVGStylable,
                      SVGTransformable,
                      events::EventTarget {

        readonly attribute SVGAnimatedLength x;
        readonly attribute SVGAnimatedLength y;
        readonly attribute SVGAnimatedLength width;
        readonly attribute SVGAnimatedLength height;
        readonly attribute SVGAnimatedPreserveAspectRatio preserveAspectRatio;
      };

Attributes
  readonly SVGAnimatedLength x
    Corresponds to attribute x on the given 'image' element.
  readonly SVGAnimatedLength y
    Corresponds to attribute y on the given 'image' element.
  readonly SVGAnimatedLength width
    Corresponds to attribute width on the given 'image' element.
  readonly SVGAnimatedLength height
    Corresponds to attribute height on the given 'image' element.
  readonly SVGAnimatedPreserveAspectRatio preserveAspectRatio
    Corresponds to attribute preserveAspectRatio on the given element.

### Interface SVGSwitchElement

The SVGSwitchElement interface corresponds to the 'switch' element.

IDL Definition

      interface SVGSwitchElement :
                      SVGElement,
                      SVGTests,
                      SVGLangSpace,
                      SVGExternalResourcesRequired,
                      SVGStylable,
                      SVGTransformable,
                      events::EventTarget {};

### Interface GetSVGDocument

In the case where an SVG document is embedded by reference, such as when an XHTML document has an 'object' element whose href (or equivalent) 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), the SVG user agent is required to implement the GetSVGDocument interface for the element which references the SVG document (e.g., the HTML 'object' or comparable referencing elements).

IDL Definition

      interface GetSVGDocument {

        SVGDocument getSVGDocument (  )
                        raises( DOMException );
      };

Methods
  getSVGDocument

    Returns the SVGDocument object for the referenced SVG document.

    No Parameters
    Return value

      SVGDocument |  | The SVGDocument object for the referenced SVG document.

    Exceptions

      DOMException |  | NOT_SUPPORTED_ERR: No SVGDocument object is available.

previous next contents elements attributes properties index