<!ENTITY % useExt "" > <!ELEMENT use (%descTitleMetadata;,(animate|set|animateMotion|animateColor|animateTransform %geExt;%useExt;)*) > <!ATTLIST use %stdAttrs; %xlinkRefAttrs; 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:
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". Conforming SVG viewers need to support at least PNG, JPEG and SVG format files.
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 such that the top/left corner of the raster image exactly aligns with coordinate (x,y), and the bottom/right corner of the raster image 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.
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; %xlinkRefAttrs; xlink:href %URI; #REQUIRED %testAttrs; %langSpaceAttrs; externalResourcesRequired %Boolean; #IMPLIED class %ClassList; #IMPLIED style %StyleSheet; #IMPLIED %PresentationAttributes-Graphics; %PresentationAttributes-Viewports; transform %TransformList; #IMPLIED %graphicsElementEvents; x %Coordinate; #IMPLIED y %Coordinate; #IMPLIED width %Length; #REQUIRED height %Length; #REQUIRED > |
Attribute definitions:
An example:
<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20000629//EN"
"http://www.w3.org/TR/2000/WD-SVG-20000629/DTD/svg-20000629.dtd">
<svg width="4in" height="3in">
<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>
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.
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.
<!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; > |
For more information and an example, see Embedding foreign object types.
Definition of requiredFeatures:
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).
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.
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:
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://www.foo.org/SVGExtensionXYZ/1.0", so that script writers can distinguish between different versions of a given extension.
The attribute value is a comma-separated list of language names as defined in [RFC1766].
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.
The id attribute is available on all SVG elements:
<!ENTITY % stdAttrs "id ID #IMPLIED" > |
Attribute definitions:
<!ENTITY % langSpaceAttrs "xml:lang NMTOKEN #IMPLIED xml:space (default|preserve) #IMPLIED" > |
Attribute definitions:
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 elements which potentially can reference external resources. It specifies whether referenced resources that are not part of the current document are required.
Attribute definition:
This attribute applies to all types of resource references, including style sheets, color prorfiles (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 inheritable; thus,if set on a container element, its value will apply to the elements within the container which don't specify a value for this attribute.
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: yes.
The following interfaces are defined below: SVGDocument, SVGSVGElement, SVGGElement, SVGDefsElement, SVGDescElement, SVGTitleElement, SVGSymbolElement, SVGUseElement, SVGElementInstance, SVGElementInstanceList, SVGImageElement, SVGSwitchElement, GetSVGDocument.
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 standalone SVG file (i.e., a file with MIME type "image/svg"). In this case, the SVGDocument object will be the 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" 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 Document Object Model (HTML) Level 1 chapter of the [DOM1] specification.
interface SVGDocument :
Document,
events::DocumentEvent {
attribute DOMString title;
// raises DOMException on setting
readonly attribute DOMString referrer;
readonly attribute DOMString domain;
readonly attribute DOMString URL;
readonly attribute SVGSVGElement rootElement;
};
| DOMException |
NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
|
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.
interface SVGSVGElement :
SVGElement,
SVGTests,
SVGLangSpace,
SVGExternalResourcesRequired,
SVGStylable,
SVGFitToViewBox,
SVGZoomAndPan,
events::EventTarget,
events::DocumentEvent {
attribute SVGAnimatedLength x;
// raises DOMException on setting
attribute SVGAnimatedLength y;
// raises DOMException on setting
attribute SVGAnimatedLength width;
// raises DOMException on setting
attribute SVGAnimatedLength height;
// raises DOMException on setting
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
attribute SVGPoint currentTranslate;
// raises DOMException on setting
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 ( );
SVGLength createSVGLength ( );
SVGAngle createSVGAngle ( );
SVGPoint createSVGPoint ( );
SVGMatrix createSVGMatrix ( );
SVGRect createSVGRect ( );
SVGTransform createSVGTransform ( );
SVGTransform createSVGTransformFromMatrix ( in SVGMatrix matrix );
SVGICCColor createSVGICCColor ( );
SVGColor createSVGColor ( );
SVGPaint createSVGPaint ( );
Element getElementById ( in DOMString elementId );
};
| DOMException |
NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
|
| DOMException |
NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
|
| DOMException |
NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
|
| DOMException |
NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
|
| DOMException |
NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
|
| DOMException |
NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
|
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 unit-less 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.
| DOMException |
NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
|
| DOMException |
NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
|
| DOMException |
NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
|
| 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. |
| 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. |
| 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() |
| 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.
|
| boolean | Boolean indicating whether this SVG document fragment is in a paused state. |
| float | The current time in seconds. |
| in float seconds | The new current time in seconds relative to the start time for the current SVG document fragment. |
| 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. |
| 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. |
| 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. |
| 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. |
| SVGLength | An SVGLength object. |
| SVGAngle | An SVGAngle object. |
| SVGPoint | An SVGPoint object. |
| SVGMatrix | An SVGMatrix object. |
| SVGRect | An SVGRect object. |
| SVGTransform | An SVGTransform object. |
| in SVGMatrix matrix | The transform matrix. |
| SVGTransform | An SVGTransform object. |
| SVGICCColor | An SVGICCColor object. |
| SVGColor | An SVGColor object. |
| SVGPaint | An SVGPaint object. |
| in DOMString elementId |
The unique id value for an element. |
| Element | The matching element. |
The SVGGElement interface corresponds to the 'g' element.
interface SVGGElement :
SVGElement,
SVGTests,
SVGLangSpace,
SVGExternalResourcesRequired,
SVGStylable,
SVGTransformable,
events::EventTarget {};
The SVGDefsElement interface corresponds to the 'defs' element.
interface SVGDefsElement :
SVGElement,
SVGTests,
SVGLangSpace,
SVGExternalResourcesRequired,
SVGStylable,
SVGTransformable,
events::EventTarget {};
The SVGDescElement interface corresponds to the 'desc' element.
interface SVGDescElement :
SVGElement,
SVGLangSpace,
SVGStylable {};
The SVGTitleElement interface corresponds to the 'title' element.
interface SVGTitleElement :
SVGElement,
SVGLangSpace,
SVGStylable {};
The SVGSymbolElement interface corresponds to the 'symbol' element.
interface SVGSymbolElement :
SVGElement,
SVGLangSpace,
SVGExternalResourcesRequired,
SVGStylable,
SVGFitToViewBox,
events::EventTarget {};
The SVGUseElement interface corresponds to the 'use' element.
interface SVGUseElement :
SVGElement,
SVGURIReference,
SVGTests,
SVGLangSpace,
SVGExternalResourcesRequired,
SVGStylable,
SVGTransformable,
events::EventTarget {
attribute SVGAnimatedLength x;
// raises DOMException on setting
attribute SVGAnimatedLength y;
// raises DOMException on setting
attribute SVGAnimatedLength width;
// raises DOMException on setting
attribute SVGAnimatedLength height;
// raises DOMException on setting
readonly attribute SVGElementInstance instanceRoot;
readonly attribute SVGElementInstance animatedInstanceRoot;
};
| DOMException |
NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
|
| DOMException |
NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
|
| DOMException |
NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
|
| DOMException |
NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
|
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/topmost 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')
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;
};
The SVGElementInstanceList interface provides the abstraction of an ordered collection of SVGElementInstance objects, without defining or constraining how this collection is implemented.
interface SVGElementInstanceList {
readonly attribute SVGElementInstance length;
SVGElementInstance item ( in unsigned long index );
};
Returns the indexth item in the collection. If index is greater than or equal to the number of nodes in the list, this returns null.
| in unsigned long index | Index into the collection. |
| SVGElementInstance | The SVGElementInstance object at the indexth position in the SVGElementInstanceList, or null if that is not a valid index. |
The SVGImageElement interface corresponds to the 'image' element.
interface SVGImageElement :
SVGElement,
SVGURIReference,
SVGTests,
SVGLangSpace,
SVGExternalResourcesRequired,
SVGStylable,
SVGTransformable,
events::EventTarget {
attribute SVGAnimatedLength x;
// raises DOMException on setting
attribute SVGAnimatedLength y;
// raises DOMException on setting
attribute SVGAnimatedLength width;
// raises DOMException on setting
attribute SVGAnimatedLength height;
// raises DOMException on setting
};
| DOMException |
NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
|
| DOMException |
NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
|
| DOMException |
NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
|
| DOMException |
NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
|
The SVGSwitchElement interface corresponds to the 'switch' element.
interface SVGSwitchElement :
SVGElement,
SVGTests,
SVGLangSpace,
SVGExternalResourcesRequired,
SVGStylable,
SVGTransformable,
events::EventTarget {};
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" 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).
interface GetSVGDocument {
SVGDocument getSVGDocument ( )
raises( DOMException );
};
Returns the SVGDocument object for the referenced SVG document.
| SVGDocument | The SVGDocument object for the referenced SVG document. |
| DOMException |
NOT_SUPPORTED_ERR: No SVGDocument object is available.
|