Copyright © 2015 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply.
This specification defines the features and syntax for Scalable Vector Graphics (SVG) Version 2. SVG is a language based on XML for describing two-dimensional vector and mixed vector/raster graphics. SVG content is stylable, scalable to different display resolutions, and can be viewed stand-alone, mixed with HTML content, or embedded using XML namespaces within other XML languages. SVG also supports dynamic changes; script can be used to create interactive documents, and animations can be performed using declarative animation features or by using script.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This document is the 09 July 2015 Working Draft of SVG 2. This version of SVG builds upon SVG 1.1 Second Edition by improving the usability of the language and by adding new features commonly requested by authors. The Changes appendix lists all of the changes that have been made since SVG 1.1 Second Edition.
Comments on this Working Draft are welcome.
Comments can be sent to www-svg@w3.org,
the public email list for issues related to vector graphics on the Web. This list is
archived and
senders must agree to have their message publicly archived from their
first posting. To subscribe send an email to
www-svg-request@w3.org with
the word subscribe
in the subject line.
The specification includes a number of annotations that the Working Group is using to record links to meeting minutes and resolutions where specific decisions about SVG features have been made. Different coloring is also used to mark the maturity of different sections of the specification:
In this Working Draft, by default, the background colors indicating section maturity are hidden and only annotations that record specific requirements for SVG 2 as part of our requirements gathering exercise are visible. To view the section maturity background colors and any additional annotations, the "All annotations" alternate style sheet can be used.
This document has been produced by the W3C SVG Working Group as part of the Graphics Activity within the W3C Interaction Domain. The goals of the W3C SVG Working Group are discussed in the W3C SVG Charter. The W3C SVG Working Group maintains a public Web page, http://www.w3.org/Graphics/SVG/, that contains further background information. The authors of this document are the SVG Working Group participants.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
A list of current W3C Recommendations and other technical documents can be found at http://www.w3.org/TR/. W3C publications may be updated, replaced, or obsoleted by other documents at any time.
This document is governed by the 1 August 2014 W3C Process Document.
The SVG Working Group would like to thank the following people for contributing to this specification with patches or by participating in discussions that resulted in changes to the document: David Dailey, Eric Eastwood, Daniel Holbert, Paul LeBeau, Robert Longson, Henri Manson, Philip Rogers, David Zbarsky.
In addition, the SVG Working Group would like to acknowledge the contributions of the editors and authors of the previous versions of SVG – as much of the text in this document derives from these earlier specifications – including:
Finally, the SVG Working Group would like to acknowledge the great many people outside of the SVG Working Group who help with the process of developing the SVG specifications. These people are too numerous to list individually. They include but are not limited to the early implementers of the SVG 1.0 and 1.1 languages (including viewers, authoring tools, and server-side transcoders), developers of SVG content, people who have contributed on the www-svg@w3.org and svg-developers@yahoogroups.com email lists, other Working Groups at the W3C, and the W3C Team. SVG 1.1 is truly a cooperative effort between the SVG Working Group, the rest of the W3C, and the public and benefits greatly from the pioneering work of early implementers and content developers, feedback from the public, and help from the W3C team.
This specification defines the features and syntax for Scalable Vector Graphics (SVG).
SVG is a language for describing two-dimensional graphics. As a standalone format or when mixed with other XML, it uses the XML syntax [XML10]. When mixed with HTML5, it uses the HTML5 syntax [HTML]. SVG allows for three types of graphic objects: vector graphic shapes (e.g., paths consisting of straight lines and curves), images and text. Graphical objects can be grouped, styled, transformed and composited into previously rendered objects. The feature set includes nested transformations, clipping paths, alpha masks, filter effects and template objects.
SVG drawings can be interactive and dynamic. Animations can be defined and triggered either declaratively (i.e., by embedding SVG animation elements in SVG content) or via scripting.
Sophisticated applications of SVG are possible by use of a supplemental scripting language which accesses SVG Document Object Model (DOM), which provides complete access to all elements, attributes and properties. A rich set of event handlers such as ‘onmouseover’ and ‘onclick’ can be assigned to any SVG graphical object. Because of its compatibility and leveraging of other Web standards, features like scripting can be done on HTML and SVG elements simultaneously within the same Web page.
SVG is a language for rich graphical content. For accessibility reasons, if there is an original source document containing higher-level structure and semantics, it is recommended that the higher-level information be made available somehow, either by making the original source document available, or making an alternative version available in an alternative format which conveys the higher-level information, or by using SVG's facilities to include the higher-level information within the SVG content. For suggested techniques in achieving greater accessibility, see Accessibility.
The MIME type for SVG is "image/svg+xml
" (see
IANA Media Type Registry).
It is recommended that SVG files have the extension
".svg"
(all lowercase) on all platforms. It is
recommended that gzip-compressed
[RFC1952]
SVG files have the extension ".svgz"
(all
lowercase) on all platforms.
The SVG 2 namespace is http://www.w3.org/2000/svg
,
which is the same as for earlier versions of SVG.
When using the XML syntax, a namespace declaration is required. When using the HTML syntax, the namespace is provided automatically by the parser.
A DTD is not provided in this specification, as the use of DTDs for validating documents is known to be problematic. In particular, DTDs do not handle namespaces gracefully and the range of constraints they can express is limited. It is recommended that authors do not include a DOCTYPE declaration in SVG documents.
SVG leverages and integrates with other W3C specifications and standards efforts, as described in the following:
Clarify what DOM version is used and indicate that SVG/HTML can be scripted with a single API.
Within this specification, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in Key words for use in RFCs to Indicate Requirement Levels [RFC2119]. However, for readability, these words do not appear in all uppercase letters in this specification.
At times, this specification recommends good practice for authors and user agents. These recommendations are not normative and conformance with this specification does not depend on their realization. These recommendations contain the expression "We recommend ...", "This specification recommends ...", or some similar wording.
There should be a separate section that lists element and attribute categories and their members.
Either of the following:
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’.A initial value is a defined behavior used when an attribute or property is not specified, or when an attribute or property has an unsupported value. This value is to be used for the purposes of rendering, calculating animation values, and when accessing the attribute or property. As opposed to an XML default value, however, the attribute or property and its value are not visible in the DOM, and cannot be accessed with DOM methods. For properties, if the property is inherited and there is no inherited value (for example, on the root element), the initial value is the initial value as specified in the definition of that property. For non-inherited properties, the initial value is always the initial value.
"Unsupported value" should be a term that is linked to.
Note that a initial value is distinct from the XML term default value, which uses DTD lookup to determine whether an attribute is required and what its value is, and inserts required attributes and their values into the DOM ([XML10], section 3.3.2). At the XML parser level, SVG Tiny 1.2 does not have default values; initiale are part of the SVG application layer, and their values are derived from the UA.
Unify this with other specifiction defintions of URL. But see HTML5 refs section on URL which is complex.
The general definition of a user agent is an application that retrieves and renders Web content, including text, graphics, sounds, video, images, and other content types. A user agent may require additional user agents that handle some types of content. For instance, a browser may run a separate program or plug-in to render sound or video. User agents include graphical desktop browsers, multimedia players, text browsers, voice browsers, and assistive technologies such as screen readers, screen magnifiers, speech synthesizers, onscreen keyboards, and voice input software.
A "user agent" may or may not have the ability to retrieve and render SVG content; however, an "SVG user agent" retrieves and renders SVG content.
SVG 2 Requirement: Support the z-index.
Resolution: We will add Jonathan Watt's z-index proposal to SVG 2.
Purpose: Allow reordering (such as when a planet orbits the sun). Reordering without script support (e.g. CSS :hover).
Owner: Jonathan (Action 3002).
The SVG 2 rendering model will follow the rules defined by the Compositing and Blending specification.
Resolution: Seattle/Paris 2012 F2F day 3.
Owner: Nikos (Action 3332).
Implementations of SVG are expected to behave as though they implement a rendering (or imaging) model corresponding to the one described in this chapter. Real implementations may choose to implement the model in the way that they see fit, but the result on any device supported by the implementation must, in most cases, match this model.
The appendix on conformance requirements describes the extent to which an actual implementation may deviate from this description. In practice an actual implementation may deviate slightly because of limitations of the output device (e.g. only a limited range of colors might be supported) and because of practical limitations in implementing a precise mathematical model (e.g. for realistic performance curves are approximated by straight lines, the approximation need only be sufficiently precise to match the conformance requirements).
SVG uses a "painters model" of rendering. Paint is applied in successive operations to the output device such that each operation paints onto some area of the output device, possibly obscuring paint that has previously been layed down. After each object or group is painted, it becomes part of the background for the next painting operation. SVG 2 supports advanced blending modes and compositing operations that control how each painting operation interacts with the background. The rules governing these painting operations are outlined in the Compositing and Blending Specification.
Elements in SVG are positioned in three dimensions. In addition to their
position on the x and y axis of the SVG viewport, SVG elements are also
positioned on the z-axis. The position on the z-axis defines the order that
they are painted.
Along the z-axis, elements are grouped into 'stacking contexts', each stacking
context has an associated stack level.
A stack level may contain one or more child nodes - either child
stack levels, graphics elements, or ‘g’ elements.
graphics elements and ‘g’ elements within single
stack level are painted in document order - that is, they are painted
in the order that they are defined in the document.
Each stack level is assigned an integer value that defines it's
position on the z-axis relative to other stack levels within the same
stacking context. Lower values are painted first, and so
elements in a stack level with a higher value will paint over one
with a lower value.
By default, everything is placed in stack level zero.
See the CSS 2.1 specification for the definition
of ‘z-index
’. [CSS21]
The ‘z-index
’ property allows an element to be assigned to a
stack level.
The rules governing behaviour for SVG elements with the ‘z-index
’
property specified are outlined below:
CSS specifies a
property named ‘z-index
’. The CSS rules
that define the effect of the ‘z-index’ property
were written specifically for the CSS box model, and those rules do not make
sense as they stand for most SVG elements (most SVG elements do not participate
in or establish a CSS box model layout). This section specifies how
implementations must handle the ‘z-index
’ property on elements in the SVG
namespace.
Contrary to the rules in CSS 2.1, the ‘z-index
’ property applies to all SVG
elements regardless of the value of the ‘position
’ property, with one exception:
as for boxes in CSS 2.1, outer ‘svg’ elements must be positioned for ‘z-index
’
to apply to them.
The ‘z-index
’ property specifies:
Values have the following meanings:
Here is a simple example:
<svg xmlns="http://www.w3.org/2000/svg"> <rect x="0" width="100" height="100" fill="red" z-index="-1"/> <rect x="40" width="100" height="100" fill="lime"/> <rect x="80" width="100" height="100" fill="blue" z-index="1"/> <rect x="60" width="100" height="100" fill="aqua"/> <rect x="20" width="100" height="100" fill="yellow" z-index="-1"/> </svg>
In this example there are three stack levels: -1, 0 (the default) and 1. The red and yellow rects are in stack level -1, the lime and aqua rects are in stack level 0 (the default), and the blue rect is in stack level 1. Going from lowest stack level to highest, and painting the elements in each stack level in document order, the painting order is: red, yellow, lime, aqua, blue.
A new stacking context must be established at an SVG element for its descendants if:
z-index
’ property applies to the element and its computed
value is an integeroverflow
’ property is a value other than visibleopacity
’ property applies to the element and it has a
computed value other than 1mask
’ property applies to the element and it has a computed
value other than nonefilter
’ property applies to the element and it has a
computed value other than noneStacking contexts and stack levels are conceptual tools used to describe the order in which elements must be painted one on top of the other when the document is rendered, and for determining which element is highest when determining the target of a pointer event. Stacking contexts and stack levels do not affect the position of elements in the DOM tree, and their presence or absence does not affect an element's position, size or orientation in the canvas' X-Y plane - only the order in which it is painted.
Stacking contexts can contain further stacking contexts. A stacking context is atomic from the point of view of its parent stacking context; elements in ancestor stacking contexts may not come between any of its elements.
Each element belongs to one stacking context. Each element in a given stacking context has an integer stack level. Elements with a higher stack level must be placed in front of elements with lower stack levels in the same stacking context. Elements may have negative stack levels. Elements with the same stack level in a stacking context must be stacked according to document order.
With the exception of the ‘foreignObject’ element, the back to front stacking order for a stacking context created by an SVG element is:
Since the ‘foreignObject’ element creates a "fixed position containing block" in CSS terms, the normative rules for the stacking order of the stacking context created by ‘foreignObject’ elements are the rules in Appendix E of CSS 2.1.
In the following example, the ‘z-index
’ property on the ‘g’
element is set to zero. This creates a new stacking context to contain the
‘g’ element's children without moving the ‘g’ to a different
level in the document's root stacking context:
<svg xmlns="http://www.w3.org/2000/svg"> <g z-index="0"> <!-- this is a self contained graphic --> <rect x="40" width="100" height="100" fill="lime" z-index="1"/> <rect x="20" width="100" height="100" fill="yellow"/> </g> <rect x="60" width="100" height="100" fill="aqua"/> <rect x="0" width="100" height="100" fill="red" z-index="-1"/> </svg>
The example's root stacking context contains two stack levels: -1 and 0. The red
‘rect’ is in level -1, and the ‘g’ element and aqua ‘rect’ are in level 0. Inside
stack level 0, the ‘g’ element's ‘z-index
’ property creates a new nested stacking
context at the ‘g’ for the ‘g’ element's children. In this child stacking
context there are two stack levels: 0 and 1. The yellow ‘rect’ is in level 0 (the
default), and the lime ‘rect’ is in level 1.
Painting of this example starts with the stack levels of the root stacking context. First the red rect is painted in level -1, then in level 0 the ‘g’ element is painted followed by the aqua rect. When the ‘g’ element is painted, the child stacking context that its z-index created and all of that context's stack levels are also painted. In this child stacking context, first the yellow rect in level 0 is painted, followed by the lime rect in level 1. It's only after the ‘g’ and the stacking context that it creates has been painted that the aqua rect is painted. Note that this means that although the z-index of 1 for the lime rect is a higher value than the (implicit) z-index of 0 for the aqua rect, the containment provided by the ‘g’'s child stacking context results in the aqua rect painting over the lime rect. The painting order is therefore: red, yellow, lime, aqua.
Individual graphics elements are treated as if they are non isolated groups, the components (fill, stroke, etc) that make up a graphic element (See Painting shapes and text) being members of that group. See How groups are rendered.
Grouping elements, such as the ‘g’ element (see container elements
) create a compositing group. The Compositing and Blending
specification normatively describes how to render compositing groups.
In SVG, effects may be applied to a group. For example, opacity, Filter Effects
or masking. These effects are applied to the rendered result of the group
immediately before any transforms on the group are applied, which are applied
immediately before the group is blended and composited with the
group backdrop. Applying any such effects to a group makes that
group isolated.
When rendering an SVG group, unknown elements and their children are discarded
from the group.
Thus, rendering a compositing group follows the following steps:
If the group is isolated:
See the CSS Color Module Level 3 for the definition
of ‘opacity
’. [CSS3COLOR]
The ‘opacity
’ property specifies how opaque a given
graphical element or container element will be when it is
painted to the canvas. When applied to a container element,
this is known as group opacity, and when applied to
an individual rendering element, it is known as object
opacity. The principle for these two operations however
is the same.
There are several other opacity-related properties in SVG:
fill-opacity
’, which specifies the opacity of a fill
operation;stroke-opacity
’, which specifies the opacity of a stroking
operation;solid-opacity
’, which specifies the opacity of a solid color
paint server; andstop-opacity
’, which specifies the opacity of a gradient stop.These four opacity properties are involved in intermediate rendering operations.
Object and group opacity however can be thought of as a post-processing operation.
Conceptually, the object or group to which ‘opacity
’ applies
is rendered into an RGBA offscreen image. The offscreen image as whole is then blended
into the canvas with the specified ‘opacity
’ value used uniformly
across the offscreen image.
Thus, the presence of ‘opacity
’ causes the group to be
isolated.
The ‘opacity
’ property applies to the following SVG elements:
‘svg’, ‘g’, ‘symbol’, ‘marker’,
‘a’, ‘switch’, graphics elements and
text content child elements.
The following example illustrates various usage of the ‘opacity
’
property on objects and groups.
<svg xmlns="http://www.w3.org/2000/svg" width="600" height="175" viewBox="0 0 1200 350"> <!-- Background blue rectangle --> <rect x="100" y="100" width="1000" height="150" fill="blue"/> <!-- Red circles going from opaque to nearly transparent --> <circle cx="200" cy="100" r="50" fill="red" opacity="1"/> <circle cx="400" cy="100" r="50" fill="red" opacity=".8"/> <circle cx="600" cy="100" r="50" fill="red" opacity=".6"/> <circle cx="800" cy="100" r="50" fill="red" opacity=".4"/> <circle cx="1000" cy="100" r="50" fill="red" opacity=".2"/> <!-- Opaque group, opaque circles --> <g opacity="1"> <circle cx="182.5" cy="250" r="50" fill="red" opacity="1"/> <circle cx="217.5" cy="250" r="50" fill="green" opacity="1"/> </g> <!-- Group opacity: .5, opacity circles --> <g opacity=".5"> <circle cx="382.5" cy="250" r="50" fill="red" opacity="1"/> <circle cx="417.5" cy="250" r="50" fill="green" opacity="1"/> </g> <!-- Opaque group, semi-transparent green over red --> <g opacity="1"> <circle cx="582.5" cy="250" r="50" fill="red" opacity=".5"/> <circle cx="617.5" cy="250" r="50" fill="green" opacity=".5"/> </g> <!-- Opaque group, semi-transparent red over green --> <g opacity="1"> <circle cx="817.5" cy="250" r="50" fill="green" opacity=".5"/> <circle cx="782.5" cy="250" r="50" fill="red" opacity=".5"/> </g> <!-- Group opacity .5, semi-transparent green over red --> <g opacity=".5"> <circle cx="982.5" cy="250" r="50" fill="red" opacity=".5"/> <circle cx="1017.5" cy="250" r="50" fill="green" opacity=".5"/> </g> </svg>
In the example, the top row of circles have differing opacities, ranging from 1.0 to 0.2. The bottom row illustrates five ‘g’ elements, each of which contains overlapping red and green circles, as follows:
SVG supports three fundamental types of graphics elements that can be rendered onto the canvas:
Shapes and text can be filled (i.e., apply paint to the interior of the shape) and stroked (i.e., apply paint along the outline of the shape).
For certain types of shapes, marker symbols (which themselves can consist of any combination of shapes, text and images) can be drawn at positions along the shape boundary. Each marker symbol is painted as if its graphical content were expanded into the SVG document tree just after the shape object which is using the given marker symbol. The graphical contents of a marker symbol are rendered using the same methods as graphics elements. Marker symbols are not applicable to text.
The order in which fill, stroke and markers are painted is determined
by the ‘paint-order
’ property. The default is that
fill is painted first, then the stroke, and then the
marker symbols. The marker symbols are rendered in order along
the outline of the shape, from the start of the shape to the
end of the shape.
Each fill and stroke operation has its own opacity settings; thus, you can fill and/or stroke a shape with a semi-transparently drawn solid color, with different opacity values for the fill and stroke operations.
The fill and stroke operations are entirely independent painting operations; thus, any stroke applied to the shape will be painted on top of part of the fill.
SVG supports numerous built-in types of paint which can be used in fill and stroke operations. These are described in Paint Servers.
When a raster image is rendered, the original samples are "resampled" using standard algorithms to produce samples at the positions required on the output device. Resampling requirements are discussed under conformance requirements.
As in HTML [HTML, 10.4.2], all animated images with the same absolute URL and the same image data are expected to be rendered synchronised to the same timeline as a group, with the timeline starting at the time of the least recent addition to the group.
When a user agent is to restart the animation for an img element showing an animated image, all animated images with the same absolute URL and the same image data in that img element's node document are expected to restart their animation from the beginning.
SVG allows any painting operation to be filtered. (See Filter Effects.)
In this case the result must be as though the paint operations had been applied to an intermediate canvas initialized to transparent black, of a size determined by the rules given in Filter Effects then filtered by the processes defined in Filter Effects.
SVG supports the following clipping/masking features:
Both, clipping and masking, are specified in the module CSS Masking [CSS-MASKING].
SVG document fragments can be semi-opaque.
In accordance with the Compositing and Blending specification, the ‘svg’ element always creates an isolated group.
When the SVG document is a top-level document, the top level SVG element is considered to be the page group and is composited with a backdrop of white with 100% opacity. For all other referencing modes, there is no page group. The SVG document is composited into the parent document with opacity preserved.
See the Cascading Style Sheets Level 2 Revision 1 (CSS 2.1)
Specification [CSS21] for the definition of
‘overflow
’.
element | initial | ua styleshet | auto[6] | visible | hidden | scroll |
---|---|---|---|---|---|---|
standalone svg | visible[2] | hidden | hidden | visible | hidden | scroll |
inner svg | visible[2] | hidden | hidden | visible | hidden | scroll |
pattern[1] | visible | hidden[4] | hidden | visible | hidden | hidden |
hatches[1] | visible | hidden[5] | hidden | visible | hidden | hidden |
marker[1] | visible | hidden[3] | hidden | visible | hidden | hidden |
symbol | visible | n/a | hidden | visible | hidden | hidden |
image | visible | hidden | hidden | visible | hidden | hidden |
iframe | visible | hidden | hidden | visible | hidden | hidden |
foreignObject | visible^ | hidden | hidden | visible | hidden | hidden |
Table footnotes:
The ‘overflow
’ property has the same parameter values and has the
same meaning as defined in CSS 2.1
([CSS21], section 11.1.1);
however, the following additional points apply:
overflow
’ property can apply.
If the ‘overflow
’ property has the value
hidden or scroll, a clip,
the exact size of the viewport is applied.
overflow
’ property can apply, if
the ‘overflow
’ property has the value hidden or scroll,
the effect is that a new clipping path in the shape of a rectangle is created.
The result is equivalent to defining a ‘clipPath’ element whose
content is a ‘rect’ element which defines the equivalent rectangle,
and then specifying the <uri> of this ‘clipPath’ element on the
‘clip-path
’ property for the given element.overflow
’ property has a value other than
hidden or scroll,
the property has no effect (i.e., a clipping rectangle is not created).
This is needed still
CSS implies that 'auto' should be clipped rather than visible, do we want to follow that or not?
Check on resolution that we made for this - Can't find resolution, but see https://lists.w3.org/Archives/Public/www-svg/2012May/0096.html Browsers all seem to implement auto = hidden.overflow
’ property has the value hidden
or scroll, then the user agent will
establish an initial clipping path equal to the bounds of the initial
viewport; otherwise, the initial
clipping path is set according to the clipping rules as defined in CSS 2.1
([CSS21], section 11.1.1).
This seems superfluous given what is written in bullet point 1, but we might
need to say something special for the visible value - check the CSS text.
overflow
’ property on the outermost svg element is ignored
for the purposes of visual rendering and the initial clipping path is set to
the bounds of the initial viewport.
Note that the value hidden still means that
no scrolling user interface should be provided.overflow
’ as defined
in [CSS21-overflow]
is 'visible', and this applies also to the outermost svg element; however,
for child elements of an SVG document, SVG's user agent style sheet
overrides this initial value and sets the ‘overflow
’ property on the
‘svg’, ‘image’, ‘pattern’ and ‘iframe’ elements
to the value hidden.overflow
’ is auto. In the UA style sheet,
overflow is overriden for svg, image, pattern, and frame to be hidden by default.
Get rid of this
As a result of the above, the default behavior of SVG user agents is to
establish a clipping path to the bounds of the initial
viewport and to establish a new clipping
path for each element which
establishes a new viewport and each ‘pattern’ and
‘marker’ element.
When an ‘svg’ element is either the root element in the
document or is embedded within a document whose layout is determined
according to the layout rules of CSS, then the user agent must
establish an initial clipping path for the SVG document fragment. The
‘overflow
’ property along with additional SVG
user agent processing rules determine the initial clipping path which
the user agent establishes for the SVG document fragment:
In SVG 1.1 the ‘overflow
’ and ‘clip
’ property
defintions follow at this point.
In this specification, attributes are defined with an attribute definition table, which looks like this:
Name | Value | Initial value | Animatable |
---|---|---|---|
exampleattr | <length> | none | none | yes |
In the Value column is a description of the attribute's syntax. There are five methods for describing an attribute's syntax:
When a presentation attribute defined using the CSS Value Definition Syntax is parsed, this is done as follows:
The insertion of the <number> symbols allows for unitless length and angles to be used in presentation attribute while disallowing them in corresponding property values.
Note that all presentation attributes, since they are defined by reference to their corresponding CSS properties, are defined using the CSS Value Definition Syntax.
When any other attribute defined using the CSS Value Definition Syntax is parsed, this is done by parsing the attribute's value according to the grammar given in attribute definition table.
Note that this allows CSS comments and escapes to be used in such attributes. For example, a value of '10\px/**/' would successfully parse as '10px' in the ‘x’ presentation attribute of the ‘rect’ element.
When an attribute defined as a URL is parsed, this is done by invoking the URL parser with the attribute's value as input and the document's URL as base [URL].
The Initial value column gives the initial value for the attribute. When an attribute fails to parse according to the specified CSS Value Definition Syntax, EBNF or EBNF grammar, or if parsing according to the URL Standard or by the prose describing how to parse the attribute indicates failure, the attribute is assumed to have been specified as the given initial value.
The initial value of a presentation attribute is its corresponding property's initial value. Since the use of an invalid value in a presentation attribute will be treated as if the initial value was specified, this value can override values that come from lower priority style sheet rules, such as those from the user agent style sheet.
For example, although the user agent style sheet sets the value of the
‘overflow
’ property to hidden
for ‘svg’ elements, specifying an invalid presentation attribute such
as overflow="invalid" will result
in a rule setting ‘overflow
’ to visible,
overriding the user agent style sheet value.
The Animatable column indicates whether the attribute can be animated using animation elements; see the Animation chapter for details.
The following common definitions are used for attributes that are defined in terms of an EBNF grammar:
wsp ::= (#x9 | #x20 | #xA | #xC | #xD) comma-wsp ::= (wsp+ ","? wsp*) | ("," wsp*)
Unless stated otherwise, numeric values in SVG attributes and in properties that are defined to have an effect on SVG elements must support at least all finite IEEE 754 single-precision values.
It is recommended that higher precision floating point storage and computation be performed on operations such as coordinate system transformations to provide the best possible precision and to prevent round-off errors.
Conforming SVG Viewers are required to perform numerical computation in accordance with their conformance class, as described in Conformance Criteria.
SVG 2 Requirement: | Make the SVGList* interfaces a bit more like other lists/arrays. |
---|---|
Resolution: | Add array style indexing and .length and .item to svg list types. |
Purpose: | To align with other array types (e.g. NodeList). Already implemented in Opera and Firefox. |
Owner: | Erik (ACTION-2975) |
We need some explicit wording about attributes being "reflected" using these interfaces.
This should also describe how reflection works for attributes that were
promoted to properties, such as ‘transform
’.
(Some discussion.)
Consider combining the definitions of all the list interfaces; there is a lot of duplicated text currently.
All of the SVG DOM interfaces that correspond directly to elements in the SVG language (such as the SVGPathElement interface for the ‘path’ element) derive from the SVGElement interface.
The CSSOM specification augments SVGElement with a style IDL attribute, so that the ‘style’ attribute can be accessed in the same way as on HTML elements.
interface SVGElement : Element { readonly attribute SVGAnimatedString className; readonly attribute SVGSVGElement? ownerSVGElement; readonly attribute SVGElement? viewportElement; attribute long tabIndex; void focus(); void blur(); }; SVGElement implements GlobalEventHandlers;
This attribute is deprecated and may be removed in a future version of this specification. Authors are advised to use Element.classList intead.
Corresponds to attribute ‘class’ on the given element.
Link to a definition of what the UA has to do to "blur an element" (e.g reference https://html.spec.whatwg.org/multipage/interaction.html#dom-blur).
Do not use this method to hide the focus ring. Do not use any other method that hides the focus ring from keyboard users, in particular do not use a CSS rule to override the ‘outline
’ property.
Removal of the focus ring leads to serious accessibility issues for users who navigate and interact with interactive content using the keyboard.
Used for attributes of type boolean which can be animated.
interface SVGAnimatedBoolean { attribute boolean baseVal; readonly attribute boolean animVal; };
Used for attributes of type DOMString which can be animated.
interface SVGAnimatedString { attribute DOMString baseVal; readonly attribute DOMString animVal; };
This interface defines a list of DOMString values.
SVGStringList has the same attributes and methods as other SVGxxxList interfaces.
The supported property indices of an SVGStringList object is all non-negative integers less than the length of the list.
interface SVGStringList { readonly attribute unsigned long length; readonly attribute unsigned long numberOfItems; void clear(); DOMString initialize(DOMString newItem); getter DOMString getItem(unsigned long index); DOMString insertItemBefore(DOMString newItem, unsigned long index); DOMString replaceItem(DOMString newItem, unsigned long index); DOMString removeItem(unsigned long index); DOMString appendItem(DOMString newItem); setter void (unsigned long index, DOMString newItem); };
Used for attributes whose value must be a constant from a particular enumeration and which can be animated.
interface SVGAnimatedEnumeration { attribute unsigned short baseVal; readonly attribute unsigned short animVal; };
Used for attributes of basic type <integer> which can be animated.
interface SVGAnimatedInteger { attribute long baseVal; readonly attribute long animVal; };
Used for attributes of basic type <number>.
interface SVGNumber { attribute float value; };
Used for attributes of basic type <number> which can be animated.
interface SVGAnimatedNumber { attribute float baseVal; readonly attribute float animVal; };
This interface defines a list of SVGNumber objects.
SVGNumberList has the same attributes and methods as other SVGxxxList interfaces.
The supported property indices of an SVGNumberList object is all non-negative integers less than the length of the list.
An SVGNumberList object can be designated as read only, which means that attempts to modify the object will result in an exception being thrown, as described below.
interface SVGNumberList { readonly attribute unsigned long length; readonly attribute unsigned long numberOfItems; void clear(); SVGNumber initialize(SVGNumber newItem); getter SVGNumber getItem(unsigned long index); SVGNumber insertItemBefore(SVGNumber newItem, unsigned long index); SVGNumber replaceItem(SVGNumber newItem, unsigned long index); SVGNumber removeItem(unsigned long index); SVGNumber appendItem(SVGNumber newItem); setter void (unsigned long index, SVGNumber newItem); };
Used for attributes which take a list of numbers and which can be animated.
interface SVGAnimatedNumberList { readonly attribute SVGNumberList baseVal; readonly attribute SVGNumberList animVal; };
The SVGLength interface corresponds to the <length> and <percentage> basic data types, and represents a length or percentage that consists of a numerical factor and a unit, where the unit is one of the set of units described in Units (em, ex, px, pt, pc, cm, mm and in), a percentage, a unitless number (user units), or "unknown".
An SVGLength object can be designated as read only, which means that attempts to modify the object will result in an exception being thrown, as described below.
An SVGLength object can be associated with a particular element, as well as being designated with a directionality: horizontal, vertical or unspecified. The associated element and the directionality of the length are used to resolve percentage values to user units. Unless otherwise described, an SVGLength object is not associated with any element and has unspecified directionality.
We need to define the behavior of converting values from/to percentages when the viewport width/height/size is zero. (ACTION-3722 on Cameron.)
The use of numeric length unit type constants is an anti-pattern and new constant values will not be introduced for any other units or length types supported by SVGLength. If other types of lengths are supported and used, the SVGLength uses the SVG_LENGTHTYPE_UNKNOWN unit type. See below for details on how the other properties of an SVGLength operate with these types of lengths.
interface SVGLength { // Length Unit Types const unsigned short SVG_LENGTHTYPE_UNKNOWN = 0; const unsigned short SVG_LENGTHTYPE_NUMBER = 1; const unsigned short SVG_LENGTHTYPE_PERCENTAGE = 2; const unsigned short SVG_LENGTHTYPE_EMS = 3; const unsigned short SVG_LENGTHTYPE_EXS = 4; const unsigned short SVG_LENGTHTYPE_PX = 5; const unsigned short SVG_LENGTHTYPE_CM = 6; const unsigned short SVG_LENGTHTYPE_MM = 7; const unsigned short SVG_LENGTHTYPE_IN = 8; const unsigned short SVG_LENGTHTYPE_PT = 9; const unsigned short SVG_LENGTHTYPE_PC = 10; readonly attribute unsigned short unitType; attribute float value; attribute float valueInSpecifiedUnits; attribute DOMString valueAsString; void newValueSpecifiedUnits(unsigned short unitType, float valueInSpecifiedUnits); void convertToSpecifiedUnits(unsigned short unitType); };
The value of the length in user units.
On getting, returns the value converted to user units. If the length cannot be converted to user units, for example because it is a percentage with no basis against which to resolve the percentage, then the value of valueInSpecifiedUnits is returned.
For example, (new SVGLength("10%")).value
evalutes to 10, since the SVGLength is not associated with
an element and thus has no percentage basis to resolve against.
On setting, sets the numerical factor to the assigned value and the unit type to user units.
The numerical factor of the length value.
On getting, returns the numerical factor if the length is a scalar value (such as '20px' or '50%'), or returns 0 if the length is not a scalar value (such as a calc() value).
On setting, modifies the numerical factor of the length value using the same unit. If the length not a scalar value, then assigning to valueInSpecifiedUnits sets the length to be the specified number of user units.
The length value as a string. On getting, returns a string as follows:
What about serializing non-scalar values, such as calc() values?
On setting, updates the numeric factor and units type of the SVGLength object according to the result of parsing the assigned string as a <length> or <percentage>.
Sets the unit type of the length value to the type specified by unitType and sets the numeric factor value such that it represents the same absolute length. For example, if the original value were "0.5cm" and the method was invoked to convert to millimeters, then unitType would return SVG_LENGTHTYPE_MM and valueInSpecifiedUnits would return the numeric value 5.
If the old or new unit type is percentage and the SVGLength object has no associated element, then the percentages are considered to resolve against a length of 100 user units. For example, converting an SVGLength whose value is 20px to a percentage will result in the value being 20%.
Used for attributes of basic type <length> which can be animated.
interface SVGAnimatedLength { readonly attribute SVGLength baseVal; readonly attribute SVGLength animVal; };
This interface defines a list of SVGLength objects.
SVGLengthList has the same attributes and methods as other SVGxxxList interfaces.
The supported property indices of an SVGLengthList object is all non-negative integers less than the length of the list.
An SVGLengthList object can be designated as read only, which means that attempts to modify the object will result in an exception being thrown, as described below.
interface SVGLengthList { readonly attribute unsigned long length; readonly attribute unsigned long numberOfItems; void clear(); SVGLength initialize(SVGLength newItem); getter SVGLength getItem(unsigned long index); SVGLength insertItemBefore(SVGLength newItem, unsigned long index); SVGLength replaceItem(SVGLength newItem, unsigned long index); SVGLength removeItem(unsigned long index); SVGLength appendItem(SVGLength newItem); setter void (unsigned long index, SVGLength newItem); };
Used for attributes of type SVGLengthList which can be animated.
interface SVGAnimatedLengthList { readonly attribute SVGLengthList baseVal; readonly attribute SVGLengthList animVal; };
The SVGAngle interface corresponds to the <angle> basic data type, and represents an angle that consists of a numerical factor and a unit, where the unit is degrees, radians, grads, unitless numbers or "unknown".
An SVGAngle object can be designated as read only, which means that attempts to modify the object will result in an exception being thrown, as described below.
The use of numeric angle unit type constants is an anti-pattern and new constant values will not be introduced for any other units or angle types supported by SVGAngle. If other types of angles are supported and used, the SVGAngle uses the SVG_ANGLETYPE_UNKNOWN unit type. See below for details on how the other properties of an SVGAngle operate with these types of angles.
interface SVGAngle { // Angle Unit Types const unsigned short SVG_ANGLETYPE_UNKNOWN = 0; const unsigned short SVG_ANGLETYPE_UNSPECIFIED = 1; const unsigned short SVG_ANGLETYPE_DEG = 2; const unsigned short SVG_ANGLETYPE_RAD = 3; const unsigned short SVG_ANGLETYPE_GRAD = 4; readonly attribute unsigned short unitType; attribute float value; attribute float valueInSpecifiedUnits; attribute DOMString valueAsString; void newValueSpecifiedUnits(unsigned short unitType, float valueInSpecifiedUnits); void convertToSpecifiedUnits(unsigned short unitType); };
The angle value as a string. On getting, returns a string as follows:
On setting, updates the numeric factor and units type of the SVGAngle object according to the result of parsing the assigned string as an <angle>.
Sets the unit type of the angle value to the type specified by unitType and sets the numeric factor value such that it represents the same absolute angle. For example, if the original value were "180deg" and the method was invoked to convert to radians, then unitType would return SVG_ANGLETYPE_RAD and valueInSpecifiedUnits would return the numeric value π.
Used for attributes of basic data type <angle> that can be animated.
interface SVGAnimatedAngle { readonly attribute SVGAngle baseVal; readonly attribute SVGAngle animVal; };
Used for attributes of type DOMRect which can be animated.
interface SVGAnimatedRect { readonly attribute DOMRectReadOnly baseVal; readonly attribute DOMRectReadOnly animVal; };
The SVGUnitTypes interface defines a commonly used set of constants and is a base interface used by SVGGradientElement, SVGPatternElement, SVGClipPathElement, SVGMaskElement and SVGFilterElement.
[NoInterfaceObject] interface SVGUnitTypes { // Unit Types const unsigned short SVG_UNIT_TYPE_UNKNOWN = 0; const unsigned short SVG_UNIT_TYPE_USERSPACEONUSE = 1; const unsigned short SVG_UNIT_TYPE_OBJECTBOUNDINGBOX = 2; };
SVG 2 Requirement: | Detect if a mouse event is on the fill or stroke of a shape. |
---|---|
Resolution: | SVG 2 will make it easier to detect if an mouse event is on the stroke or fill of an element. |
Purpose: | To allow authors to discriminate between pointer events on the fill and stroke of an element without having to duplicate the element |
Owner: | Cameron (ACTION-3279) |
Interface SVGGraphicsElement represents SVG elements whose primary purpose
is to directly render graphics into a group. The
‘transform
’ property applies to all SVGGraphicsElement. All SVGGraphicsElement
have a bounding box in current local coordinate system.
dictionary SVGBoundingBoxOptions { boolean fill = true; boolean stroke = false; boolean markers = false; boolean clipped = false; }; interface SVGGraphicsElement : SVGElement { readonly attribute SVGAnimatedTransformList transform; DOMRect getBBox(optional SVGBoundingBoxOptions options); DOMMatrix? getCTM(); DOMMatrix? getScreenCTM(); DOMMatrix getTransformToElement(SVGGraphicsElement element); }; SVGGraphicsElement implements SVGTests;
transform
’ on the given element.This needs to be updated to reflect the value of the ‘transform
’
property.
Returns the result of invoking the bounding box algorithm for the element, with fill, stroke, markers and clipped members of the options dictionary argument used to control which parts of the element are included in the bounding box, using the element's local coordinate system as the coordinate system to return the bounding box in.
transform
’ property) to the viewport
coordinate system for the nearest viewport element (CTM). Note that null
is returned if this element is not hooked into the document tree.
What is the expected result if you call getCTM on an ‘svg’ element? See thread. Also see example. (ACTION-3724 on Dirk.)
transform
’ property) to the parent
user agent's notion of a "pixel". For display devices, ideally this
represents a physical screen pixel. For other devices or environments
where physical pixel sizes are not known, then an algorithm similar to
the CSS 2.1 definition of a "pixel" can be used instead. Note that null
is returned if this element is not hooked into the document tree. This
method would have been more aptly named as getClientCTM
,
but the name getScreenCTM
is kept for historical reasons.
Should this take into account the 'transform' on the ‘svg’ element itself? See example. Chrome/Opera/IE: returns the identity matrix for this example, Firefox: difference between transform style and attribute, and is not an identity matrix.
transform
’ property)
to the user coordinate system on parameter element
(after application of its ‘transform
’ property).
If the passed in element is in another document, what should happen? Measurements. Proposal to limit this to the same fragment if not removeable.
Interface SVGGeometryElement represents SVG elements whose rendering is defined by geometry and which can be filled and stroked. This includes paths, text and the basic shapes.
interface SVGGeometryElement : SVGGraphicsElement { boolean isPointInFill(DOMPoint point); boolean isPointInStroke(DOMPoint point); };
pointer-events
’
property on the element determines whether a point is considered to be
within the fill.
pointer-events
’
property on the element determines whether a point is considered to be
within the stroke.
Interface SVGTests defines an interface which applies to all elements which have attributes ‘requiredExtensions’ and ‘systemLanguage’.
[NoInterfaceObject] interface SVGTests { readonly attribute SVGStringList requiredExtensions; readonly attribute SVGStringList systemLanguage; };
Interface SVGFitToViewBox defines DOM attributes that apply to elements which have XML attributes ‘viewBox’ and ‘preserveAspectRatio’.
[NoInterfaceObject] interface SVGFitToViewBox { readonly attribute SVGAnimatedRect viewBox; readonly attribute SVGAnimatedPreserveAspectRatio preserveAspectRatio; };
The SVGZoomAndPan interface defines attribute zoomAndPan and associated constants.
[NoInterfaceObject] interface SVGZoomAndPan { // Zoom and Pan Types const unsigned short SVG_ZOOMANDPAN_UNKNOWN = 0; const unsigned short SVG_ZOOMANDPAN_DISABLE = 1; const unsigned short SVG_ZOOMANDPAN_MAGNIFY = 2; attribute unsigned short zoomAndPan; };
Interface SVGURIReference defines an interface which applies to all elements which have an ‘href’ attribute.
[NoInterfaceObject] interface SVGURIReference { readonly attribute SVGAnimatedString href; };
Corresponds to the ‘href’ attribute. If the element also supports the deprecated ‘xlink:href’ attribute, the resulting SVGAnimatedString object will correspond to the ‘xlink:href’ attribute in the XLink namespace if, and only if, all of the following conditions are true at the time when the href IDL attribute is accessed:
If any of the above conditions does not hold at the time when the the href IDL attribute is accessed, the returned attribute will correspond to the ‘href’ attribute without a namespace.
An SVG document fragment consists of any number of SVG elements contained within an ‘svg’ element.
An SVG document fragment can range from an empty fragment (i.e., no content inside of the ‘svg’ element), to a very simple SVG document fragment containing a single SVG graphics element such as a ‘rect’, to a complex, deeply nested collection of container elements and graphics elements.
An SVG document fragment can stand by itself as a self-contained file or resource, in which case the SVG document fragment is an SVG document, or it can be embedded inline as a fragment within a parent HTML or XML document.
The following example shows simple SVG content embedded inline as a fragment within a parent XML document. Note the use of XML namespaces to indicate that the ‘svg’ and ‘ellipse’ elements belong to the SVG namespace:
<?xml version="1.0" standalone="yes"?> <parent xmlns="http://example.org" xmlns:svg="http://www.w3.org/2000/svg"> <!-- parent contents here --> <svg:svg width="4cm" height="8cm"> <svg:ellipse cx="2cm" cy="4cm" rx="2cm" ry="1cm" /> </svg:svg> <!-- ... --> </parent>
This example shows a slightly more complex (i.e., it contains multiple rectangles) stand-alone, self-contained SVG document:
<?xml version="1.0" standalone="no"?> <svg width="5cm" height="4cm" version="1.1" xmlns="http://www.w3.org/2000/svg"> <desc>Four separate rectangles </desc> <rect x="0.5cm" y="0.5cm" width="2cm" height="1cm"/> <rect x="0.5cm" y="2cm" width="1cm" height="1.5cm"/> <rect x="3cm" y="0.5cm" width="1.5cm" height="2cm"/> <rect x="3.5cm" y="3cm" width="1cm" height="0.5cm"/> <!-- Show outline of canvas using 'rect' element --> <rect x=".01cm" y=".01cm" width="4.98cm" height="3.98cm" fill="none" stroke="blue" stroke-width=".02cm" /> </svg>
‘svg’ elements can appear in the middle of SVG content. This is the mechanism by which SVG document fragments can be embedded within other SVG document fragments.
Another use for ‘svg’ elements within the middle of SVG content is to establish a new viewport. (See Establishing a new viewport.)
When SVG is parsed as a XML, for compliance with the Namespaces in XML Recommendation [XML-NS], an SVG namespace declaration must be provided so that all SVG elements are identified as belonging to the SVG namespace. The following are possible ways to provide a namespace declaration. An ‘xmlns’ attribute without a namespace prefix could be specified on an ‘svg’ element, which means that SVG is the default namespace for all elements within the scope of the element with the ‘xmlns’ attribute:
<svg xmlns="http://www.w3.org/2000/svg" …> <rect …/> </svg>
If a namespace prefix is specified on the ‘xmlns’
attribute (e.g., xmlns:svg="http://www.w3.org/2000/svg"
),
then the corresponding namespace is not the default namespace, so an
explicit namespace prefix must be assigned to the elements:
<svg:svg xmlns:svg="http://www.w3.org/2000/svg" …> <svg:rect …/> </svg:svg>
Namespace prefixes can be specified on ancestor elements (illustrated in the above example). For more information, refer to the Namespaces in XML Recommendation [XML-NS].
This section should talk about how a document's behavior is defined in terms of the DOM, and also explain how the HTML parser can create SVG fragments.
SVG 2 Requirement: | Should support the playbackorder attribute to inform UA to not display controls to seek backwards. |
---|---|
Resolution: | Support the playbackorder attribute. |
Purpose: | To inform UA to not display controls to seek backwards. |
Owner: | Cyril |
SVG 2 Requirement: | Support transforming ‘svg’ elements. |
---|---|
Resolution: | We will allow ‘transform’ on ‘svg’ in SVG 2. |
Purpose: | To allow transforms on nested ‘svg’ elements, in line with author expectations. |
Owner: | Dirk (no action) |
SVG 2 Requirement: | Support a means for having SMIL animations start before their time container has fully loaded. |
---|---|
Resolution: | Timeline control. |
Purpose: | To start animations before the SVG document is fully loaded (useful for large SVG documents). |
Owner: | Cyril |
The ‘x
’ and ‘y
’ attributes specify the
top-left corner of the rectangular region into which an
embedded ‘svg’ element is placed. On an outermost svg element,
these attributes have no effect.
Note that ‘width
’ and ‘height
’ are presentation attributes.
The Value column does not match the new Attribute syntax description.
For outermost svg elements,
the ‘width
’ and ‘height
’ attributes specify
the intrinsic size of the SVG document fragment.
For embedded ‘svg’ elements, they specify the size
of the rectangular region into which the ‘svg’ element
is placed.
Attribute definitions:
Name | Value | Initial value | Animatable |
---|---|---|---|
preserveAspectRatio | defer? <align> [ meet | slice ]? | xMidYMid meet | yes |
Specifies the fitting behavior when the aspect ratio of the ‘svg’ element does not match the aspect ratio of the rectangle it is placed in. See the definition of ‘preserveAspectRatio’ for details.
Name | Value | Initial value | Animatable |
---|---|---|---|
zoomAndPan | disable | magnify | magnify | no |
Specifies whether the user agent should supply a means to zoom and pan the SVG content. See the definition of ‘zoomAndPan’ for details.
Name | Value | Initial value | Animatable |
---|---|---|---|
playbackorder | forwardonly | all | all | no |
This attribute may be harmonized and/or replaced with the work done as part of the Web Animation specification.
Indicates whether it is possible to seek backwards in the document. In earlier versions of SVG there was no need to put restrictions on the direction of seeking but with the newly introduced facilities for long-running documents (e.g. the ‘discard’ element) there is sometimes a need to restrict this.
If ‘playbackorder’ is set to 'forwardonly', the content will likely contain ‘discard’ elements or scripts that destroy resources, thus seeking back in the document fragment's timeline may result in missing content. If ‘playbackorder’ is 'forwardonly', the content should not provide a way, through hyperlinking or script, of seeking backwards in the timeline. Similarly the UA should disable any controls it may provide in the user interface for seeking backwards. Content with playbackorder="forwardonly" that provides a mechanism for seeking backwards in time may result in undefined behavior or a document that is in error.
Can't we define this so that there is no undefined behavior? Awaiting ACTION-3726 (Brian).
Attribute values have the following meanings:
Name | Value | Initial value | Animatable |
---|---|---|---|
timelinebegin | loadend | loadbegin | loadend | no |
Controls the initialization of the timeline for the SVG document fragment.
The outermost svg element of an SVG document fragment defines a timeline. Absolute times used by animation elements in an SVG document fragment are relative to the document fragment's timeline.
By default, the timeline is initialized when the document
fragment's load
event
is fired but for progressively loaded animations, the author may set this
attribute to 'loadend',
thus allowing the timeline to begin as the document loads, rather than
waiting until the complete document is loaded.
Attribute values have the following meanings:
load
event for the
outermost svg element is triggered.
If an SVG document is likely to be referenced as a component of another document, the author will often want to include a ‘viewBox’ attribute on the outermost svg element of the referenced document. This attribute provides a convenient way to design SVG documents to scale-to-fit into an arbitrary viewport.
The ‘svg’ element exposes as event handler content attributes a number of the event handlers of the Window object. It also mirrors their event handler IDL attributes.
The onblur, ‘onerror’, onfocus, ‘onload’, and ‘onscroll’ event handlers of the Window object, exposed on the ‘svg’ element, replace the generic event handlers with the same names normally supported by SVG elements.
The ‘g’ element is a container element for grouping together related graphics elements.
A group of elements, as well as individual objects, can be given a name using the ‘id’ attribute. Named groups are needed for several purposes such as animation and re-usable objects.
An example:
<?xml version="1.0" standalone="no"?> <svg xmlns="http://www.w3.org/2000/svg" version="1.1" width="5cm" height="5cm"> <desc>Two groups, each of two rectangles</desc> <g id="group1" fill="red"> <rect x="1cm" y="1cm" width="1cm" height="1cm"/> <rect x="3cm" y="1cm" width="1cm" height="1cm"/> </g> <g id="group2" fill="blue"> <rect x="1cm" y="3cm" width="1cm" height="1cm"/> <rect x="3cm" y="3cm" width="1cm" height="1cm"/> </g> <!-- Show outline of canvas using 'rect' element --> <rect x=".01cm" y=".01cm" width="4.98cm" height="4.98cm" fill="none" stroke="blue" stroke-width=".02cm"/> </svg>
A ‘g’ element can contain other ‘g’ elements nested within it, to an arbitrary depth.
SVG 2 Requirement: | Have unknown elements treated as ‘g’ for the purpose of rendering. |
---|---|
Resolution: | Accept having unknown elements treated as ‘g’ for the purpose of rendering. |
Purpose: | To allow fallbacks without the use of ‘switch’, and to align with the behavior of unknown elements in HTML. |
Owner: | Nobody (no action) |
SVG allows graphical objects to be defined for later reuse. To do this, it makes extensive use of URL references [RFC3987] to these other objects. For example, to fill a rectangle with a linear gradient, you first define a ‘linearGradient’ element and give it an ID, as in:
<linearGradient id="MyGradient">...</linearGradient>
You then reference the linear gradient as the value of the
‘fill
’ property for the rectangle, as in:
<rect style="fill:url(#MyGradient)"/>
Some types of element, such as gradients, will not by themselves produce a graphical result. They can therefore be placed anywhere convenient. However, sometimes it is desired to define a graphical object and prevent it from being directly rendered. it is only there to be referenced elsewhere. To do this, and to allow convenient grouping defined content, SVG provides the ‘defs’ element.
It is recommended that, wherever possible, referenced elements be defined inside of a ‘defs’ element. Among the elements that are always referenced: ‘clipPath’, ‘cursor’, ‘filter’, ‘linearGradient’, ‘marker’, ‘mask’, ‘pattern’, ‘radialGradient’ and ‘symbol’.
The ‘defs’ element is a container element for referenced elements. For understandability and accessibility reasons, it is recommended that, whenever possible, referenced elements be defined inside of a ‘defs’.
The content model for ‘defs’ is the same as for the ‘g’ element; thus, any element that can be a child of a ‘g’ can also be a child of a ‘defs’, and vice versa.
Elements that are descendants of a ‘defs’ are not rendered directly;
they are prevented from becoming part of the rendering tree
just as if the ‘defs’ element were a ‘g’ element and the
‘display
’ property were set to none.
Note, however, that the descendants of a ‘defs’ are
always present in the source tree and thus can always be
referenced by other elements; thus, the value of the ‘display
’
property on the ‘defs’ element or any of its descendants does not
prevent those elements from being referenced by other elements.
Would this element be better as part of the Animation chapter? It also needs to be a member of the element categories that other animation elements are, and an IDL interface needs to be written for it. Covered by ACTION-3727 (Cyril).
SVG 2 Requirement: | Have the ‘discard’ element to declaratively discard elements from the document tree. |
---|---|
Resolution: | SVG 2 will support the discard element. |
Purpose: | To conserve memory while displaying long-running documents. |
Owner: | Cyril (ACTION-3319) |
Need to define SVGDiscardElement DOM interface for ‘discard’ element. Covered by ACTION-3727 (Cyril).
The ‘discard’ element allows authors to specify the time at which particular elements are to be discarded, thereby reducing the resources required by an SVG user agent. This is particularly useful to help SVG viewers conserve memory while displaying long-running documents. This element will not be processed by static SVG viewers.
The ‘discard’ element may occur wherever the ‘animate’ element may.
Attribute definitions:
Name | Value | Initial value | Animatable |
---|---|---|---|
href | URL [URL] | (none) | no |
An URL reference that identifies the target element to discard. See the definition of ‘href’ on animation elements for details on identifying a target element. Note, however, that unlike other animation elements, the ‘discard’ element does not support the deprecated ‘xlink:href’ attribute.
Note that if the target element is not part of the current SVG document fragment then whether the target element will be removed or not is defined by the host language.
If the ‘href’ attribute is not provided, then the target element will be the immediate parent element of the discard element.
Name | Value | Initial value | Animatable |
---|---|---|---|
begin | <begin-value-list> | 0s | no |
Attribute syntax needs fixing.
Indicates when the target element will be discarded. See the definition of ‘begin’ on animation elements for details.
The ‘discard’
element has an implicit
simple duration
of "indefinite". As soon as the element's
active duration
starts, the SVG user agent
discards the element identified by the
‘href’
attribute ([SMIL], section 5.4.5).
The removal operation acts as if
removeChild
were called on the parent of the target element with the target element as
parameter. [DOM4] The SVG user agent
must remove the target node as well as all of its attributes and descendants.
After removal of the target element, the ‘discard’ element is no longer useful. It must also be discarded following the target element removal. If the ‘href’ attribute has an invalid URL reference (the target element did not exist, for example), the ‘discard’ element itself must still be removed following activation.
Seeking backwards in the timeline ([SMIL], section 5.4.5) must not re-insert the discarded elements. Discarded elements are intended to be completely removed from memory. So, authors are encouraged to set the ‘playbackorder’ attribute to "forwardonly" when using the ‘discard’ element.
The ‘discard’ element itself can be discarded prior to its activation, in which case it will never trigger the removal of its own target element. SVG user agents must allow the ‘discard’ element to be the target of another ‘discard’ element.
The following example demonstrates a simple usage of the ‘discard’ element. The list below describes relevant behavior in the document timeline of this example:
<svg xmlns="http://www.w3.org/2000/svg" width="352" height="240" playbackorder="forwardonly"> <ellipse cx="98.5" cy="17.5" rx="20.5" ry="17.5" fill="blue" stroke="black" transform="translate(9 252) translate(3 -296)"> <animateTransform attributeName="transform" begin="0s" dur="2s" fill="remove" calcMode="linear" type="translate" additive="sum" from="0 0" to="-18 305"/> <discard begin="2s"/> </ellipse> <rect x="182" y="-39" width="39" height="30" fill="red" stroke="black" transform="translate(30 301)"> <animateTransform attributeName="transform" begin="1s" dur="2s" fill="remove" calcMode="linear" type="translate" additive="sum" from="0 0" to="-26 -304"/> <discard begin="3s"/> </rect> <polygon points="-66,83.5814 -43,123.419 -89,123.419" fill="green" stroke="black" transform="matrix(1 0 0 1.1798 0 -18.6096)"> <animateTransform attributeName="transform" begin="2s" dur="2s" fill="remove" calcMode="linear" type="translate" additive="sum" from="0 0" to="460 63.5699"/> <discard begin="4s"/> </polygon> </svg>
The attribute ‘lang’ added to allow internationalization of the ‘desc’ and ‘title’ elements.
Adding 'lang' resolved at Rigi Kaltbad face-to-face. Removed text that limited number of 'desc' and 'title' elements.
Is there any updated wording from SVG Tiny 1.2 that we should be using wrt tooltips?
Each container element or graphics element in an SVG drawing can supply one or more ‘desc’ and/or one or more ‘title’ description strings where the description is text-only. When the current SVG document fragment is rendered as SVG on visual media, ‘desc’ and ‘title’ elements are not rendered as part of the graphics. The ‘title’ child element represents advisory information for the element, such as would be appropriate for a tooltip. On a link, this could be the title or a description of the target resource; on an image or drawing object, it could be the image credit or short description of the image; it could be further information about the source; on interactive content, it could be a label for, or instructions for, use of the element; and so forth. The value is text. The ‘desc’ element represents more detailed, textual information, for the element. This is typically exposed to assistive technologies to provide more detailed information, such as help information about the element. The value is text.
Authors are provided two vehicles for providing a visible label with a drawing element. The first way is to embed text within the drawing element. The second is to associate visible text with a drawing element through the use of ‘aria-labelledby’ on the element being labelled. Authors may provide a non-visible label to a drawing element by applying an ‘aria-label’ to it but also by providing a descendant ‘title’ element. An author may also expose a hidden label on an element to an assistive technologies through the use of ‘aria-labelledby’ when it points to content that is hidden and contains text. It is common for user agents to render the ‘title’ element as a tooltip. Tooltips are an important way to convey alternative text information for a drawing object where the text label is either not readily visible or could be rendered in a clearer way in response to passing over the drawing element with a pointing device. One benefit of using a descendant 'title' element can be seen when using SVG to to produce an image button or small drawing that has no visible text but it is important to be able to render a short textual equivalent label, or tooltip, when a pointing device passes over the button.
Authors should provide a ‘title’ child element to the outermost svg element within a stand-alone SVG document. Since users often consult documents out of context, authors should provide context-rich titles. Thus, instead of a title such as "Introduction", which doesn't provide much contextual background, authors should supply a title such as "Introduction to Medieval Bee-Keeping" instead. For reasons of accessibility, user agents should always make the content of the ‘title’ child element to the outermost svg element available to users. The mechanism for doing so depends on the user agent (e.g., as a caption, spoken).
If the SVG document is embedded in an HTML document, the outermost svg element may only serve to act as a container for SVG drawings and applying a ‘title’ child element may not be of value. Applying a ‘title’ element to the outermost SVG element in this may may result in a tooltip being generated.
Unlike the desc element, authors also have the ability to associate more detailed information with content that includes visible text. This can be achieved by applying ‘aria-describedby’ to the element, or container of elements being described and passing an ID reference to content that includes text that describes the element in question. However, if the text describing the object is hidden the text within the description would be exposed to assistive technologies as detailed text information, similar to a descendant ‘desc’ element. The ‘aria-describedby’ attribute takes precedence over the child ‘desc’ when providing a description, consequently authors should only use ‘aria-describedby’ when an element is described by visible text on the screen, otherwise the use of a child ‘desc’ is preferred.
User agents may, however, for example, display the ‘title’ element as a tooltip, as the pointing device moves over particular elements. Alternate presentations are possible, both visual and aural, which display the ‘desc’ and ‘title’ elements but do not display ‘path’ elements or other graphics elements. For deep hierarchies, and for following ‘use’ element references, it is sometimes desirable to allow the user to control how deep they drill down into descriptive text.
More than one ‘desc’ or ‘title’ may be present with different ‘lang’ attributes. The text displayed will be the text from the element where the ‘lang’ attribute best matches the language set by the user agent. If no match exists, the text from the first element is used (to allow default text to be given for legacy renderers). If multiple equally valid matches exist, the first match is used.
The following is an example. In typical operation, the SVG user agent would not render the ‘desc’ and ‘title’ elements but would render the remaining contents of the ‘g’ element.
<?xml version="1.0" standalone="no"?> <svg xmlns="http://www.w3.org/2000/svg" width="4in" height="3in"> <g> <title>Company sales by region</title> <title lang="fr">Chiffre d'affaires par région</title> <desc>Bar chart which shows company sales by region.</desc> <desc lang="fr">Graphique illustrant les ventes par région.</desc> <!-- Bar chart defined as vector data --> </g> </svg>
Description and title elements can contain marked-up text from other namespaces.
We should say what purpose including other-namespaced markup in ‘title’ and ‘desc’ has. If it is just that these are basically metadata extension points for other profiles or uses of SVG, then we should say that.
We have this sentence here about tooltips which is stronger than the earlier note that some implementations do this. We should look at how HTML describes the ‘title’ attribute and whether a tooltip is required, suggested, etc., and follow that.
Once we have said how ARIA attributes can be used in SVG, we might want to define ‘title’ and ‘desc’ in a manner consistent with them, so that it is clear what it means for example for an element to have both a ‘desc’ element child and an ‘aria-describedby’ attribute.
Metadata which is included with SVG content should be specified within ‘metadata’ elements. The contents of the ‘metadata’ should be elements from other XML namespaces, with these elements from these namespaces expressed in a manner conforming with the Namespaces in XML Recommendation [XML-NS].
Authors should provide a ‘metadata’ child element to the outermost svg element within a stand-alone SVG document. The ‘metadata’ child element to an ‘svg’ element serves the purposes of identifying document-level metadata.
The definitions of many of SVG's elements (particularly, container and text elements) place no restriction on the placement or number of the ‘metadata’ sub-elements. This flexibility is only present so that there will be a consistent content model for container elements, because some container elements in SVG allow for mixed content, and because the mixed content rules for XML ([XML10], section 3.2.2) do not permit the desired restrictions. Future versions of the SVG language might provide more restrictive mixed content rules. It is strongly recommended that at most one ‘metadata’ element appear as a child of any particular element, and that this element appear before any other child elements (except possibly ‘desc’ or ‘title’ elements) or character data content. If metadata-processing user agents need to choose among multiple ‘metadata’ elements for processing it should choose the first one.
Here is an example of how metadata can be included in an SVG document. The example uses the Dublin Core version 1.1 schema. (Other XML-compatible metadata languages, including ones not based on RDF, can be used also.)
<?xml version="1.0" standalone="yes"?> <svg width="4in" height="3in" xmlns = 'http://www.w3.org/2000/svg'> <desc xmlns:myfoo="http://example.org/myfoo"> <myfoo:title>This is a financial report</myfoo:title> <myfoo:descr>The global description uses markup from the <myfoo:emph>myfoo</myfoo:emph> namespace.</myfoo:descr> <myfoo:scene><myfoo:what>widget $growth</myfoo:what> <myfoo:contains>$three $graph-bar</myfoo:contains> <myfoo:when>1998 $through 2000</myfoo:when> </myfoo:scene> </desc> <metadata> <rdf:RDF xmlns:rdf = "http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:rdfs = "http://www.w3.org/2000/01/rdf-schema#" xmlns:dc = "http://purl.org/dc/elements/1.1/" > <rdf:Description about="http://example.org/myfoo" dc:title="MyFoo Financial Report" dc:description="$three $bar $thousands $dollars $from 1998 $through 2000" dc:publisher="Example Organization" dc:date="2000-04-11" dc:format="image/svg+xml" dc:language="en" > <dc:creator> <rdf:Bag> <rdf:li>Irving Bird</rdf:li> <rdf:li>Mary Lambert</rdf:li> </rdf:Bag> </dc:creator> </rdf:Description> </rdf:RDF> </metadata> </svg>
Name | Value | Initial value | Animatable |
---|---|---|---|
refX | <length> | left | center | right | 0 | yes |
refY | <length> | top | center | bottom | 0 | yes |
New in SVG 2. Added to make it easier to align symbols to a particular point, as is often done in maps. Similar to the matching attributes on ‘marker’.
Add refX/refY to symbol element. Resolved at Leipzig F2F.
We will add top/center/bottom, left/center/right keywords to refX/refY on marker/symbol. Resolved at London F2F. Values inspired by 'background-position'.
The ‘refX’ and ‘refY’ attributes define the reference point of the symbol which is to be placed exactly at the symbol's position as defined by the ‘use’ element. They are interpreted as being in the coordinate system of the symbol contents, after application of the ‘viewBox’ and ‘preserveAspectRatio’ attributes.
The ‘symbol’ element is used to define graphical template objects which can be instantiated by a ‘use’ element.
The use of ‘symbol’ elements for graphics that are used multiple times in the same document adds structure and semantics.
The key distinctions between a ‘symbol’ and a ‘g’ are:
Closely related to the ‘symbol’ element are the ‘marker’ and ‘pattern’ elements.
‘symbol’ elements are never rendered directly; their only usage is
as something that can be referenced using the
‘use’ element. The ‘display
’ property does not apply
to the ‘symbol’ element; thus, ‘symbol’ elements are
not directly rendered even if the ‘display
’ property is set to a
value other than none, and ‘symbol’
elements are available for referencing even when the
‘display
’ property on the ‘symbol’ element or any of its
ancestors is set to none.
SVG 2 Requirement: | Allow ‘use’ to reference an external document's root element by omitting the fragment. |
---|---|
Resolution: | We will relax referencing requirements to particular elements to allow dropping fragments to mean referencing root element, where it makes sense, such as with use, in SVG 2. |
Purpose: | To avoid requiring authors to modify the referenced document to add an ID to the root element. |
Owner: | Cameron (ACTION-3417) |
The ‘use’ element references another element and indicates that the graphical contents of that element is included/drawn at that given point in the document.
‘use’ is described as referencing template objects, but the parameters of the template are limited – just different inherited property values.
The graphical contents are any ‘svg’, ‘symbol’, ‘g’, graphics element or other ‘use’ elements, that a ‘use’ element references.
The ‘use’ element can reference an entire SVG document by specifying an ‘href’ value without a fragment. Such references are taken to be referring to the root element of the referenced document.
This allows an entire SVG document to be referenced without having to ensure that it has an ID on its root element.
The ‘use’ element has optional attributes ‘x’, ‘y’, ‘width’ and ‘height’ which are used to map the graphical contents of the referenced element onto a rectangular region within the current coordinate system.
The effect of a ‘use’ element is as if the graphical contents of the referenced element were deeply cloned into a separate non-exposed DOM tree which had the ‘use’ element as its parent and all of the ‘use’ element's ancestors as its higher-level ancestors. Because the cloned DOM tree is non-exposed, the SVG Document Object Model (DOM) only contains the ‘use’ element and its attributes. The SVG DOM does not show the referenced element's contents as children of ‘use’ element.
The non-exposed DOM tree must be created even if 'display: none' is set on the ‘use’ element. Note that ‘script’ elements that get conceptually cloned into the non-exposed DOM tree do not execute again, and ‘audio’ and ‘video’ elements that may play audio must only do so if the ‘use’ element is rendered.
We should define the behavior of ‘use’ in terms of Web Components. See ACTION-3729 (Tab)
The conceptual deep cloning of the referenced element into a non-exposed DOM tree also copies any property values resulting from the CSS cascade ([CSS21], chapter 6) on the referenced element and its contents. CSS2 selectors can be applied to the original (i.e., referenced) elements because they are part of the formal document structure. CSS2 selectors cannot be applied to the (conceptually) cloned DOM tree because its contents are not part of the formal document structure.
Property inheritance, however, works as if the referenced element had been textually included as a deeply cloned child of the ‘use’ element. The referenced element inherits properties from the ‘use’ element and the ‘use’ element's ancestors. An instance of a referenced element does not inherit properties from the referenced element's original parents.
If event attributes are assigned to referenced elements, then the actual target for the event will be the element within the "instance tree" corresponding to the given referenced element.
The event handling for the non-exposed tree works as if the referenced element had been textually included as a deeply cloned child of the ‘use’ element, and events are dispatched according to the shadow tree event dispatching algorithm [SHADOWDOM]. The event's target and currentTarget attributes are set to the instance tree element that corresponds to the target and current target elements in the referenced subtree. An event propagates through the exposed and non-exposed portions of the tree in the same manner as it would in the regular document tree: first going from the root element to the ‘use’ element and then through non-exposed tree elements in the capture phase, followed by the target phase at the target of the event, then bubbling back through non-exposed tree to the use element and then back through regular tree to the root element in bubbling phase. In order to maintain encapsulation events must use the event retargeting algorithm [SHADOWDOM] when crossing from a non-exposed tree to the regular tree.
The behavior of the ‘visibility
’ property conforms to
this model of property inheritance. Thus, specifying 'visibility:hidden' on a ‘use’ element does not guarantee
that the referenced content will not be rendered. If the ‘use’ element specifies 'visibility:hidden' and the element
it references specifies 'visibility:hidden' or 'visibility:inherit', then that one
element will be hidden. However, if the referenced element
instead specifies 'visibility:visible', then that
element will be visible even if the ‘use’ element specifies 'visibility:hidden'.
Why is ‘visibility
’ called out specially? It might
be better just to include an example that shows this.
The element referenced by ‘use’ may be in a separate document. However, this specification does not define how or if the user agent will process stylesheets in that document, or what viewport will be used for resolving percentages and media queries in such documents, if animations run in the separate document and which document controls the animation timeline. Script elements in the resource document must not be executed, and the corresponding conceptually cloned script elements must also not execute.
When re-using external assets, therefore, authors are advised not to include any scripts in the external file and to use inline styles or presentation attributes only. Percentage lengths should only be used if the re-used assets define their own viewport (i.e., if the re-used element is an ‘svg’ or ‘symbol’). Declarative animations in external assets should not be used.
User agents may restrict restrict external resource documents for security reasons. In particular, this specification does not allow cross-origin resource requests in ‘use’. A future version of this or another specification may provide a method of securely enabling cross-origin re-use of assets.
Animations on a referenced element will cause the instances to also be animated.
A ‘use’ element has the same visual effect as if the ‘use’ element were replaced by the following generated content:
Except that the replaced content shouldn't affect how styles are matched.
In the generated content, the ‘use’ will be replaced
by ‘g’, where all attributes from the ‘use’ element
except for ‘x’, ‘y’, ‘width’,
‘height’, ‘href’ and ‘xlink:href’ are transferred
to the generated ‘g’ element. An additional transformation
translate(x,y) is appended to the
end (i.e., right-side) of the ‘transform
’ property on the
generated ‘g’, where x
and y represent the values of
the ‘x’ and ‘y’ attributes on the ‘use’
element.
If the ‘use’ element references a ‘symbol’ element:
The referenced ‘symbol’ and its contents are deep-cloned into the generated tree, with the exception that the ‘symbol’ is replaced by an ‘svg’. This generated ‘svg’ will always have explicit values for its ‘width’ and ‘height’ presentation attributes. If attributes ‘width’ and/or ‘height’ are provided on the ‘use’ element, then these attributes will be transferred to the generated ‘svg’. If attributes ‘width’ and/or ‘height’ are not specified, the generated ‘svg’ element will use values of '100%' for these attributes.
If the ‘use’ element references an ‘svg’ element:
The referenced ‘svg’ and its contents are deep-cloned into the generated tree. If attributes ‘width’ and/or ‘height’ are provided on the ‘use’ element, then these values will override the corresponding attributes on the ‘svg’ in the generated tree.
Otherwise:
The referenced object and its contents are deep-cloned into the generated tree.
For user agents that support Styling with CSS, the generated ‘g’ element carries along with it the "cascaded" property values on the ‘use’ element which result from the CSS cascade ([CSS21], chapter 6). Additionally, the copy (deep clone) of the referenced resource carries along with it the "cascaded" property values resulting from the CSS cascade on the original (i.e., referenced) elements. Thus, the result of various CSS selectors in combination with the ‘class’ and ‘style’ attributes are, in effect, replaced by the functional equivalent of a ‘style’ attribute in the generated content which conveys the "cascaded" property values.
Example Use01 below has a simple ‘use’ on a ‘rect’.
<?xml version="1.0" standalone="no"?> <svg width="10cm" height="3cm" viewBox="0 0 100 30" version="1.1" xmlns="http://www.w3.org/2000/svg"> <desc>Example Use01 - Simple case of 'use' on a 'rect'</desc> <defs> <rect id="MyRect" width="60" height="10"/> </defs> <rect x=".1" y=".1" width="99.8" height="29.8" fill="none" stroke="blue" stroke-width=".2" /> <use x="20" y="10" href="#MyRect" /> </svg>
The visual effect would be equivalent to the following document:
<?xml version="1.0" standalone="no"?> <svg width="10cm" height="3cm" viewBox="0 0 100 30" xmlns="http://www.w3.org/2000/svg" version="1.1"> <desc>Example Use01-GeneratedContent - Simple case of 'use' on a 'rect'</desc> <!-- 'defs' section left out --> <rect x=".1" y=".1" width="99.8" height="29.8" fill="none" stroke="blue" stroke-width=".2" /> <!-- Start of generated content. Replaces 'use' --> <g transform="translate(20,10)"> <rect width="60" height="10"/> </g> <!-- End of generated content --> </svg>
Example Use02 below has a ‘use’ on a ‘symbol’.
<?xml version="1.0" standalone="no"?> <svg width="10cm" height="3cm" viewBox="0 0 100 30" version="1.1" xmlns="http://www.w3.org/2000/svg"> <desc>Example Use02 - 'use' on a 'symbol'</desc> <defs> <symbol id="MySymbol" viewBox="0 0 20 20"> <desc>MySymbol - four rectangles in a grid</desc> <rect x="1" y="1" width="8" height="8"/> <rect x="11" y="1" width="8" height="8"/> <rect x="1" y="11" width="8" height="8"/> <rect x="11" y="11" width="8" height="8"/> </symbol> </defs> <rect x=".1" y=".1" width="99.8" height="29.8" fill="none" stroke="blue" stroke-width=".2" /> <use x="45" y="10" width="10" height="10" href="#MySymbol" /> </svg>
The visual effect would be equivalent to the following document:
<?xml version="1.0" standalone="no"?> <svg width="10cm" height="3cm" viewBox="0 0 100 30" xmlns="http://www.w3.org/2000/svg" version="1.1"> <desc>Example Use02-GeneratedContent - 'use' on a 'symbol'</desc> <!-- 'defs' section left out --> <rect x=".1" y=".1" width="99.8" height="29.8" fill="none" stroke="blue" stroke-width=".2" /> <!-- Start of generated content. Replaces 'use' --> <g transform="translate(45, 10)" > <!-- Start of referenced 'symbol'. 'symbol' replaced by 'svg', with x,y,width,height=0,0,100%,100% --> <svg width="10" height="10" viewBox="0 0 20 20"> <rect x="1" y="1" width="8" height="8"/> <rect x="11" y="1" width="8" height="8"/> <rect x="1" y="11" width="8" height="8"/> <rect x="11" y="11" width="8" height="8"/> </svg> <!-- End of referenced symbol --> </g> <!-- End of generated content --> </svg>
Example Use03 illustrates
what happens when a ‘use’ has
a ‘transform
’ property.
<?xml version="1.0" standalone="no"?> <svg width="10cm" height="3cm" viewBox="0 0 100 30" version="1.1" xmlns="http://www.w3.org/2000/svg"> <desc>Example Use03 - 'use' with a 'transform' attribute</desc> <defs> <rect id="MyRect" x="0" y="0" width="60" height="10"/> </defs> <rect x=".1" y=".1" width="99.8" height="29.8" fill="none" stroke="blue" stroke-width=".2" /> <use href="#MyRect" transform="translate(20,2.5) rotate(10)" /> </svg>
The visual effect would be equivalent to the following document:
<?xml version="1.0" standalone="no"?> <svg width="10cm" height="3cm" viewBox="0 0 100 30" xmlns="http://www.w3.org/2000/svg" version="1.1"> <desc>Example Use03-GeneratedContent - 'use' with a 'transform' attribute</desc> <!-- 'defs' section left out --> <rect x=".1" y=".1" width="99.8" height="29.8" fill="none" stroke="blue" stroke-width=".2" /> <!-- Start of generated content. Replaces 'use' --> <g transform="translate(20,2.5) rotate(10)"> <rect x="0" y="0" width="60" height="10"/> </g> <!-- End of generated content --> </svg>
Example Use04 illustrates a ‘use’ element with various methods of applying CSS styling.
<?xml version="1.0" standalone="no"?> <svg width="12cm" height="3cm" viewBox="0 0 1200 300" xmlns="http://www.w3.org/2000/svg"> <desc>Example Use04 - 'use' with CSS styling</desc> <defs style=" /* rule 9 */ stroke-miterlimit: 10" > <path id="MyPath" d="M300 50 L900 50 L900 250 L300 250" class="MyPathClass" style=" /* rule 10 */ stroke-dasharray:300,100" /> </defs> <style type="text/css"> <![CDATA[ /* rule 1 */ #MyUse { fill: blue } /* rule 2 */ #MyPath { stroke: red } /* rule 3 */ use { fill-opacity: .5 } /* rule 4 */ path { stroke-opacity: .5 } /* rule 5 */ .MyUseClass { stroke-linecap: round } /* rule 6 */ .MyPathClass { stroke-linejoin: bevel } /* rule 7 */ use > path { shape-rendering: optimizeQuality } /* rule 8 */ g > path { visibility: hidden } ]]> </style> <rect x="0" y="0" width="1200" height="300" style="fill:none; stroke:blue; stroke-width:3"/> <g style=" /* rule 11 */ stroke-width:40"> <use id="MyUse" href="#MyPath" class="MyUseClass" style="/* rule 12 */ stroke-dashoffset:50" /> </g> </svg>
The visual effect would be equivalent to the following document. Observe that some of the style rules above apply to the generated content (i.e., rules 1-6, 10-12), whereas others do not (i.e., rules 7-9). The rules which do not affect the generated content are:
In the generated content below, the selectors that yield a match have been transferred into inline ‘style’ attributes for illustrative purposes.
<?xml version="1.0" standalone="no"?> <svg width="12cm" height="3cm" viewBox="0 0 1200 300" xmlns="http://www.w3.org/2000/svg" version="1.1"> <desc>Example Use04-GeneratedContent - 'use' with a 'transform' attribute</desc> <!-- 'style' and 'defs' sections left out --> <rect x="0" y="0" width="1200" height="300" style="fill:none; stroke:blue; stroke-width:3"/> <g style="/* rule 11 */ stroke-width:40"> <!-- Start of generated content. Replaces 'use' --> <g style="/* rule 1 */ fill:blue; /* rule 3 */ fill-opacity:.5; /* rule 5 */ stroke-linecap:round; /* rule 12 */ stroke-dashoffset:50" > <path d="M300 50 L900 50 L900 250 L300 250" style="/* rule 2 */ stroke:red; /* rule 4 */ stroke-opacity:.5; /* rule 6 */ stroke-linejoin: bevel; /* rule 10 */ stroke-dasharray:300,100" /> </g> <!-- End of generated content --> </g> </svg>
When a ‘use’ references another element which is another ‘use’ or whose content contains a ‘use’ element, then the deep cloning approach described above is recursive. However, a set of references that directly or indirectly reference a element to create a circular dependency is an error, as described in References and the ‘defs’ element.
Attribute definitions:
Name | Value | Initial value | Animatable |
---|---|---|---|
x, y | <length> | 0 | yes |
width, height | <length> | (see below) | yes |
The ‘x’, ‘y’, ‘width’ and ‘height’ attributes specify the positioning of the referenced element. The ‘width’ and ‘height’ attributes have different initial values depending on the type of the referenced element:
A negative value for ‘width’ or ‘height’ is an error (see Error processing). If ‘width’ or ‘height’ is zero then rendering of the ‘use’ element is disabled.
Name | Value | Initial value | Animatable |
---|---|---|---|
href | URL [URL] | (none) | yes |
An URL reference to the element/fragment within an SVG document to be cloned for rendering.
Refer to the common handling defined for URL reference attributes and deprecated XLink attributes.SVG contains a ‘switch’ element along with attributes ‘requiredExtensions’ and ‘systemLanguage’ to provide an ability to specify alternate viewing depending on the capabilities of a given user agent or the user's language.
Attributes ‘requiredExtensions’ and ‘systemLanguage’ act as tests and evaluate to either true or false. The ‘switch’ renders the first of its children for which all of these attributes test true. If the given attribute is not specified, then a true value is assumed.
Similar to the ‘display
’ property, conditional processing
attributes only affect the direct rendering of elements and do
not prevent elements from being successfully referenced by
other elements (such as via a ‘use’).
In consequence:
The ‘switch’ element evaluates the ‘requiredExtensions’ and ‘systemLanguage’ attributes on its direct child elements in order, and then processes and renders the first child for which these attributes evaluate to true. All others will be bypassed and therefore not rendered. If the child element is a container element such as a ‘g’, then the entire subtree is either processed/rendered or bypassed/not rendered.
Note that the values of properties ‘display
’ and
‘visibility
’ have no effect on ‘switch’ element
processing. In particular, setting ‘display
’ to
none on a child of a ‘switch’ element
has no effect on true/false testing associated with ‘switch’
element processing.
The ‘switch’ element does not affect the processing of ‘script’ and ‘style’ elements.
For more information and an example, see Embedding foreign object types.
The ‘requiredExtensions’ attribute defines a list of required language extensions. Language extensions are capabilities within a user agent that go beyond the feature set defined in this specification. Each extension is identified by an URL reference.
Name | Value | Initial value | Animatable |
---|---|---|---|
requiredExtensions | list-of-extensions | (none) | no |
Need a grammar for list-of-extensions.
The value is a list of URL references which identify the required extensions, with the individual values separated by white space. Determines whether all of the named extensions are supported by the user agent. If all of the given extensions are supported, then the attribute evaluates to true; otherwise, the current element and its children are skipped and thus will not be rendered.
If a given URL reference contains white space within itself, that white space must be escaped.
If the attribute is not present, then 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 URL names for the extension should include versioning information, such as "http://example.org/SVGExtensionXYZ/1.0", so that script writers can distinguish between different versions of a given extension.
Name | Value | Initial value | Animatable |
---|---|---|---|
systemLanguage | list-of-languages | (none) | no |
Need a grammar for list-of-languages.
The value is a comma-separated list of Language-Tag values, as defined in BCP 47 [BCP47].
Evaluates to "true" if one of the languages indicated by user preferences exactly equals one of the languages given in the value of this parameter, or if one of the languages indicated by user preferences exactly equals a prefix of one of the languages given in the value of this parameter such that the first tag character following the prefix is "-".
Evaluates to "false" otherwise.
Note: This use of a prefix matching rule does not imply that language tags are assigned to languages in such a way that it is always true that if a user understands a language with a certain tag, then this user will also understand all languages with tags for which this tag is a prefix.
The prefix rule simply allows the use of prefix tags if this is the case.
Implementation note: When making the choice of linguistic preference available to the user, implementers should take into account the fact that users are not familiar with the details of language matching as described above, and should provide appropriate guidance. As an example, users may assume that on selecting "en-gb", they will be served any kind of English document if British English is not available. The user interface for setting user preferences should guide the user to add "en" to get the best matching behavior.
Multiple languages MAY be listed for content that is intended for multiple audiences. For example, content that is presented simultaneously in the original Maori and English versions, would call for:
<text systemLanguage="mi, en"><!-- content goes here --></text>
However, just because multiple languages are present within the object on which the ‘systemLanguage’ test attribute is placed, this does not mean that it is intended for multiple linguistic audiences. An example would be a beginner's language primer, such as "A First Lesson in Latin," which is clearly intended to be used by an English-literate audience. In this case, the ‘systemLanguage’ test attribute should only include "en".
Authoring note: Authors should realize that if several alternative language objects are enclosed in a ‘switch’, and none of them matches, this may lead to situations where no content is displayed. It is thus recommended to include a "catch-all" choice at the end of such a ‘switch’ which is acceptable in all cases.
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.
The following list describes the applicability of the test attributes to the elements that do not directly produce rendering.
This was already mentioned in the "Conditional processing overview" section. We should just describe this once.
The ‘id’ and ‘xml:base’ attributes are available on all SVG elements:
Name | Value | Initial value | Animatable |
---|---|---|---|
id | (see below) | (none) | no |
Reflects the element's ID [DOM4]. The ‘id’ attribute must be any value other than the empty string.
Name | Value | Initial value | Animatable |
---|---|---|---|
xml:base | URL [URL] | (none) | no |
Specifies a base URL other than the base URL of the document or external entity. Refer to the XML Base specification [XML-BASE].
Are we happy to keep promoting the use of ‘xml:base’? Is it a use case worth trying to include a more HTML-like syntax for – the ‘base’ element? We anyway need to define somewhere what effect the HTML ‘base’ element has on any SVG document fragments. For some more context on making <base> apply to svg, see this AngularJS issue.
Elements that might contain character data content can have the attribute ‘xml:lang’.
SVG 2 Requirement: | Deprecate the use of ‘xml:space’ to affect text layout and use the ‘white-space’ property instead. |
---|---|
Resolution: | We drop xml:space from SVG 2 and remove the relating tests from the SVG 1.1. test suite. |
Purpose: | To align with CSS. |
Owner: | Chris (ACTION-3004, done; and ACTION-3005, done) |
Should we be moving 'lang'? instead of ‘xml:lang’? At minimum allow both lang and xml:lang (then needs a priority if both specified).
Name | Value | Initial value | Animatable |
---|---|---|---|
xml:lang | Language-Tag [ABNF] | (none) | no |
Standard XML attribute to specify the language (e.g., English) used in the contents and attribute values of particular elements. Refer to the Extensible Markup Language (XML) 1.0 Recommendation [XML10].
Name | Value | Initial value | Animatable |
---|---|---|---|
xml:space | (see below) | default | no |
Deprecated XML attribute to specify whether white space is preserved in character data. The only possible values are the strings 'default' and 'preserve'. White space is not allowed. Refer to the Extensible Markup Language (XML) 1.0 Recommendation [XML10] and to the discussion white space handling in SVG.
New content should use the ‘white-space
’ property instead.
Name | Value | Initial value | Animatable |
---|---|---|---|
tabindex | <number> | (none) | no |
We should explicit refer to the algorithm HTML uses to parse ‘tabindex’ numbers.
This content attribute allows authors to control whether an element is focusable, whether it is supposed to be reachable using sequential focus navigation, and what is to be the relative order of the element for the purposes of sequential focus navigation
The name "tab index" comes from the common use of the "tab" key to navigate through the focusable elements. The term "tabbing" refers to moving forward through the focusable elements that can be reached using sequential focus navigation.
SVG elements having native semantics that are not limited to presentation (having "no role"), may have an ARIA role attribute specified. The attribute, if specified, must have a value that is a set of space-separated tokens representing the various WAI-ARIA roles that the element belongs to. These tokens are role values defined in Definition of Roles ([ARIA], section 5.4).
The WAI-ARIA role that an SVG element has assigned to it is the first non-abstract role found in the list of values generated when the role attribute is split on spaces.
Name | Value | Initial value | Animatable |
---|---|---|---|
role | set of space-separated tokens | (see below) | no |
The ‘role’ attribute must be a set of space-separated tokens having values defined in Definition of Roles ([ARIA], section 5.4).
The role value is a set of white-space separated machine-extractable semantic information used to define the purpose of the element.
The initial value for the ‘role’ attribute, for each SVG element, is the corresponding default implied ARIA semantic for SVG elements.
SVG elements having native semantics that are not limited to presentation (having "no role"), may have an may have WAI-ARIA state and property attributes specified. These attributes are defined by ARIA in Definitions of States and Properties (all aria-* attributes) ([ARIA], section 6.6).
These attributes, if specified, must have a value that is the WAI-ARIA value type in the "Value" field of the definition for the state or property, mapped to the appropriate SVG value type according to Mapping WAI-ARIA Value types to languages using the SVG mapping ([ARIA], section 10.2).
WAI-ARIA State and Property attributes can be used on any element. They are not always meaningful, however, and in such cases user agents might not perform any processing aside from including them in the DOM. Unlike some other host languages, SVG is not considered to have strong native host language semantics in terms of the user interface, consequently state and property attributes are processed according to the ARIA and SVG Accessibility API Mappings specification specifications. [ARIA] [SVG-AAM]
The following table defines the implicit native semantics and corresponding default implicit ARIA semantics that apply to SVG elements. Each language feature (element) in a cell in the first column implies the ARIA semantics (role, states, and/or properties) given in the cell in the second column of the same row. The third column defines restrictions as to what WAI-ARIA semantic (role, state, or property) may or may not apply.
Language feature | Default implied ARIA semantics | Restrictions |
---|---|---|
‘a’ | link role |
no restrictions |
‘animate’ | none | no role may be applied |
‘animateMotion’ | none | no role may be applied |
‘animateTransform’ | none | no role may be appplied |
‘audio’ | group role |
If specified, role must be application |
‘canvas’ | group role |
no restrictions |
‘circle’ | none role provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, ‘aria-describedby’ attribute; or ‘tabindex’ attribute; otherwise, group role |
no restrictions |
‘clipPath’ | none | no role may be applied |
‘cursor’ | none | no restrictions |
‘defs’ | none | no role may be applied |
‘desc’ | none | no role may be applied |
‘discard’ | none | no role may be applied |
‘ellipse’ | none role provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, ‘aria-describedby’ attribute; or ‘tabindex’ attribute; otherwise, group role |
no restrictions |
‘feBlend’ | none | no role may be applied |
‘feColorMatrix’ | none | no role may be applied |
‘feComponentTransfer’ | none | no role may be applied |
‘feComposite’ | none | no role may be applied |
‘feConvolveMatrix’ | none | no role may be applied |
‘feDiffuseLighting’ | none | no role may be applied |
‘feDisplacementMap’ | none | no role may be applied |
‘feDistantLight’ | none | no role may be applied |
‘feDropShadow’ | none | no role may be applied |
‘feFlood’ | none | no role may be applied |
‘feFuncA’ | none | no role may be applied |
‘feFuncB’ | none | no role may be applied |
‘feFuncG’ | none | no role may be applied |
‘feFuncR’ | none | no role may be applied |
‘feGaussianBlur’ | none | no role may be applied |
‘feImage’ | none | no role may be applied |
‘feMerge’ | none | no role may be applied |
‘feMergeNode’ | none | no role may be applied |
‘feMorphology’ | none | no role may be applied |
‘feOffset’ | none | no role may be applied |
‘fePointLight’ | none | no role may be applied |
‘feSpecularLighting’ | none | no role may be applied |
‘feSpotLight’ | none | no role may be applied |
‘feTile’ | none | no role may be applied |
‘feTurbulence’ | none | no role may be applied |
‘filter’ | none | no role may be applied |
‘foreignObject’ | none role provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, ‘aria-describedby’ attribute; or ‘tabindex’ attribute; otherwise, group role |
no restrictions |
‘g’ | none role provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, ‘aria-describedby’ attribute; or ‘tabindex’ attribute; otherwise, group role |
no restrictions |
‘hatch’ | none | no role may be applied |
‘hatchpath’ | none | no role may be applied |
‘iframe’ | no role | If Specified, role must be either application , document , or img roles |
‘image’ | img role |
no restrictions |
‘line’ | none role provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, ‘aria-describedby’ attribute; or ‘tabindex’ attribute; otherwise, group role |
no restrictions |
‘linearGradient’ | none | no role may be applied |
‘marker’ | none | no role may be applied |
‘mask’ | none | no role may be applied |
‘mesh’ | none | no role may be applied |
‘meshpatch’ | none | no role may be applied |
‘meshrow’ | none | no role may be applied |
‘metadata’ | none | no role may be applied |
‘mpath’ | none | no role may be applied |
‘path’ | none role provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, ‘aria-describedby’ attribute; or ‘tabindex’ attribute; otherwise, group role |
no restrictions |
‘pattern’ | none | no role may be applied |
‘polygon’ | none role provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, ‘aria-describedby’ attribute; or ‘tabindex’ attribute; otherwise, group role |
no restrictions |
‘polyline’ | none role provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, ‘aria-describedby’ attribute; or ‘tabindex’ attribute; otherwise, group role |
no restrictions |
‘radialGradient’ | none | no role may be applied |
‘rect’ | none role provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, ‘aria-describedby’ attribute; or ‘tabindex’ attribute; otherwise, group role |
no restrictions |
‘script’ | none | no role may be applied |
‘set’ | none | no role may be applied |
‘solidcolor’ | none | no role may be applied |
‘source’ | none | no role may be applied |
‘stop’ | none | no role may be applied |
‘style’ | none | no role may be applied |
‘svg’ | group role |
no restrictions |
‘switch’ | none role provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, ‘aria-describedby’ attribute; or ‘tabindex’ attribute; otherwise, group role |
no restrictions |
‘symbol’ | none role provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, ‘aria-describedby’ attribute; or ‘tabindex’ attribute; otherwise, group role |
no restrictions |
‘text’ | group role |
no restrictions |
‘textPath’ | group role |
no restrictions |
‘title’ | none | no role may be applied |
‘track’ | none | no role may be applied |
‘tspan’ | group role |
no restrictions |
‘use’ | none role provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, ‘aria-describedby’ attribute; or ‘tabindex’ attribute; otherwise, img role |
no restrictions |
‘video’ | group role |
If specified, role must be application |
‘view’ | none role provided no associated ‘title’ element, ‘desc’ element, ‘aria-label’ attribute, ‘aria-labelledby’ attribute, ‘aria-describedby’ attribute; or ‘tabindex’ attribute; otherwise, group role |
no restrictions |
The DOM Core specification defines a Document interface, which this specification extends.
In the case where an SVG document is embedded by reference, such as when an HTML document has an ‘object’ element whose ‘data’ attribute references an SVG document (i.e., a document whose MIME type is "image/svg+xml" and whose root element is thus an ‘svg’ element), there will exist two distinct DOM hierarchies. The first DOM hierarchy will be for the referencing document (e.g., an XHTML document). The second DOM hierarchy will be for the referenced SVG document.
For historical reasons, Window objects must also have a writable, configurable, non-enumerable property named SVGDocument whose value is the Document interface object.
partial interface Document { readonly attribute SVGSVGElement rootElement; };
This attribute is deprecated, and may be removed in a future SVG specification. Authors are encouraged to use the documentElement attribute on Document instead.
The following IDL fragment must be supported only if the SVG implementation is also a Web browser or other interactive user agent, and therefore implements HTML.
// must only be implemented in certain implementations partial interface Document { readonly attribute DOMString title; readonly attribute DOMString referrer; readonly attribute DOMString domain; readonly attribute Element? activeElement; };
This is because the interface members above are already defined in HTML, and in implementations that support SVG and HTML they cannot be duplicated.
The title, referrer, domain and activeElement IDL attributes must behave the same as the corresponding IDL attributes defined in HTML.
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 : SVGGraphicsElement { readonly attribute SVGAnimatedLength x; readonly attribute SVGAnimatedLength y; readonly attribute SVGAnimatedLength width; readonly attribute SVGAnimatedLength height; readonly attribute DOMRectReadOnly viewport; attribute float currentScale; readonly attribute DOMPointReadOnly currentTranslate; unsigned long suspendRedraw(unsigned long maxWaitMilliseconds); void unsuspendRedraw(unsigned long suspendHandleID); void unsuspendRedrawAll(); void forceRedraw(); void pauseAnimations(); void unpauseAnimations(); boolean animationsPaused(); float getCurrentTime(); void setCurrentTime(float seconds); NodeList getIntersectionList(DOMRectReadOnly rect, SVGElement? referenceElement); NodeList getEnclosureList(DOMRectReadOnly rect, SVGElement? referenceElement); boolean checkIntersection(SVGElement element, DOMRectReadOnly rect); boolean checkEnclosure(SVGElement element, DOMRectReadOnly rect); void deselectAll(); SVGNumber createSVGNumber(); SVGLength createSVGLength(); SVGAngle createSVGAngle(); DOMPoint createSVGPoint(); DOMMatrix createSVGMatrix(); DOMRect createSVGRect(); SVGTransform createSVGTransform(); SVGTransform createSVGTransformFromMatrix(DOMMatrixReadOnly matrix); }; SVGSVGElement implements SVGFitToViewBox; SVGSVGElement implements SVGZoomAndPan; SVGSVGElement implements WindowEventHandlers;
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 DOMRectReadOnly object, as its name suggests, is read only.
The value of a transform property on the outermost svg element does not affect the value of this attribute.
When accessed on an ‘svg’ element that is not an outermost svg element, this attribute must return 1 as scaling factor.
The value of a transform property on the outermost svg element does not affect the value of this attribute.
When accessed on an ‘svg’ element that is not an outermost svg element, this attribute must return an DOMPointReadOnly at the coordinates (0, 0).
Suspends (i.e., pauses) all currently running SVG animations that are defined within the SVG document fragment corresponding to this ‘svg’ element, causing the current time of the timeline for this document fragment to stand still until it is unpaused. If this ‘svg’ element is not the outermost svg element this method has no effect.
This method only affects animations defined using SVG's animation elements. It does not affect CSS Animations [CSSANIMATIONS], CSS Transitions [CSS3TRANSITIONS] or animations created using script.
Unsuspends (i.e., unpauses) currently running animations that are defined within the SVG document fragment corresponding to this ‘svg’ element, causing the timeline for the document fragment to continue from its current time. If this ‘svg’ element is not the outermost svg element this method has no effect.
This method only affects animations defined using SVG's animation elements. It does not affect CSS Animations [CSSANIMATIONS], CSS Transitions [CSS3TRANSITIONS] or animations created using script.
Returns the current time in seconds relative to the start time for the timeline of the current SVG document fragment. If getCurrentTime is called before the current SVG document fragment's timeline has begun, then 0 is returned.
For example, if the outermost svg element of an SVG document fragment has a ‘timelinebegin’ value of loadend, any script running in a ‘script’ element that does not wait for the document fragment's load event to fire, will run before the timeline begins and any calls to this method will return 0.
Adjusts the clock for this SVG document fragment, establishing a new current time. If setCurrentTime is called before the document timeline has begun, the value of seconds in the last invocation of the method gives the time that the document will seek to once the document timeline has begun.
If this ‘svg’ element is not the outermost svg element this method has no effect.
pointer-events
’ processing.
Shadow tree elements must not be returned in the list, if such an element is matched then the corresponding ‘use’ element is to be returned.
pointer-events
’ processing.
Shadow tree elements must not be returned in the list, if such an element is matched then the corresponding ‘use’ element is to be returned.
pointer-events
’ processing.pointer-events
’ processing.Removes any selections from the document. The effect of this method is to remove all ranges from the document's selection and then to set the selection's direction to forwards. [DOM4][EDITING]
This is equivalent to calling document.getSelection().removeAllRanges()
on the document that this ‘svg’ element is in.
This method is deprecated, as it duplicates functionality from the Selection API.
This method is deprecated, and is only kept for compatibility with legacy content. Authors are encouraged to use the DOMPoint constructors instead.
This method is deprecated, and is only kept for compatibility with legacy content. Authors are encouraged to use the DOMMatrix constructors instead.
This method is deprecated, and is only kept for compatibility with legacy content. Authors are encouraged to use the DOMRect constructors instead.
Creates an SVGTransform object outside of any document trees. The object is initialized to the given matrix transform (i.e., SVG_TRANSFORM_MATRIX). The values from the parameter matrix are copied, the matrix parameter is not adopted as SVGTransform::matrix.
interface SVGGElement : SVGGraphicsElement { };
interface SVGDefsElement : SVGGraphicsElement { };
interface SVGDescElement : SVGElement { };
interface SVGMetadataElement : SVGElement { };
interface SVGTitleElement : SVGElement { };
interface SVGSymbolElement : SVGElement { }; SVGSymbolElement implements SVGFitToViewBox;
The SVGUseElement interface corresponds to the ‘use’ element.
interface SVGUseElement : SVGGraphicsElement { readonly attribute SVGAnimatedLength x; readonly attribute SVGAnimatedLength y; readonly attribute SVGAnimatedLength width; readonly attribute SVGAnimatedLength height; }; SVGUseElement implements SVGURIReference;
interface SVGSwitchElement : SVGGraphicsElement { };
This interface provides access to an SVG document embedded by reference in another DOM-based language. The expectation is that the interface is implemented on DOM objects that allow such SVG document references.
This interface is deprecated and may be dropped from future versions of
the SVG specification. To access the SVG document inside an
‘iframe’ or
‘object’ element,
authors are suggested to use the contentDocument
attribute on the HTMLIFrameElement or HTMLObjectElement
interface, respectively.
The HTMLIFrameElement, HTMLEmbedElement and HTMLObjectElement interfaces all define their own getSVGDocument method, which provides access to the SVG document in the same way that the GetSVGDocument does. Those three interfaces therefore do not need to implement GetSVGDocument. Still, authors are strongly recommended to use contentDocument instead.
[NoInterfaceObject] interface GetSVGDocument { SVGDocument getSVGDocument(); };
This method must return the Document object embedded content in an embedding element, or null if there is no document.
The author is advised to check that the document element of the returned Document is indeed an ‘svg’ element instead of assuming that that will always be the case.
SVG uses styling properties to describe many of its document parameters. Styling properties define how the graphics elements in the SVG content are to be rendered. SVG uses styling properties for the following:
SVG shares many of its styling properties with CSS [CSS21] and XSL [XSL]. Except for any additional SVG-specific rules explicitly mentioned in this specification, the normative definition of properties that are shared with CSS and XSL is the definition of the property from the CSS 2.1 specification [CSS21] or a later version of the relevant CSS module.
The following properties are shared between CSS 2.1 and SVG. Most of these properties are also defined in XSL:
This list needs to be updated. We should list all the properties we normative require support for, and which specification they are defined in. Come up with a definitive list of CSS specifications we normatively depend on.
Overall: we should not have to mention the version of CSS everywhere. We don't do that for XSL.
Remove mentions of XSL and XSLT from this chapter.
font
’font-family
’font-size
’font-size-adjust
’font-stretch
’font-style
’font-variant
’font-weight
’clip
’, only applicable to outermost svg element.color
’, used to provide a potential indirect value
(currentColor) for the
‘fill
’,
‘stroke
’,
‘stop-color
’,
‘flood-color
’ and
‘lighting-color
’
properties.
(The SVG properties which support color allow a color
specification which is extended from CSS 2.1 to accommodate
color definitions in arbitrary color spaces.)cursor
’display
’overflow
’, only applicable to
elements which establish a new viewport.visibility
’The following SVG properties are not defined in CSS 2.1. The complete normative definitions for these properties are found in this specification:
isolation
’filter
’flood-color
’flood-opacity
’lighting-color
’color-interpolation
’color-rendering
’fill
’fill-opacity
’fill-rule
’image-rendering
’marker
’marker-end
’marker-mid
’marker-start
’shape-rendering
’stroke
’stroke-dasharray
’stroke-dashoffset
’stroke-linecap
’stroke-linejoin
’stroke-miterlimit
’stroke-opacity
’stroke-width
’text-rendering
’A table that lists and summarizes the styling properties can be found in the Property Index.
Styling properties can be assigned to SVG elements in the following two ways:
This section doesn't add anything to the following two sections; consider removing it.
Presentation attributes
Styling properties can be assigned using SVG's presentation attributes. For each styling property defined in this specification, there is a corresponding XML presentation attribute available on all relevant SVG elements. Detailed information on the presentation attributes can be found in Specifying properties using the presentation attributes.
The presentation attributes are style sheet language independent and thus are applicable to usage scenario 1 above (i.e., tool interoperability). Because it is straightforward to assign values to XML attributes from XSLT, the presentation attributes are well-suited to usage scenario 2 above (i.e., SVG generation from XSLT).
Conforming SVG Interpreters and Conforming SVG Viewers are required to support SVG's presentation attributes.
CSS Stylesheets
To support usage scenario 3 above, SVG content can be styled with CSS. For more information, see Styling with CSS.
Conforming SVG Interpreters and Conforming SVG Viewers that support CSS styling of generic (i.e., text-based) XML content are required to also support CSS styling of SVG content.
We should require CSS styling support in all conformance classes. (ACTION-3709 on Cameron)
For each styling property defined in this specification (see
Property Index), there is a
corresponding XML attribute (the presentation attribute) with the same
name that is available on all relevant SVG elements. For
example, SVG has a ‘fill
’ property that defines how
to paint the interior of a shape. There is a corresponding
presentation attribute with the same name (i.e., ‘fill’) that can be used to specify a
value for the ‘fill
’ property on a given
element.
We should state which properties have a corresponding presentation attribute. Discussion. (ACTION-3732 on Cameron)
The following example shows how the ‘fill
’ and
‘stroke
’ properties can be specified on a ‘rect’ using the
‘fill’ and
‘stroke’ presentation attributes. The
rectangle will be filled with red and outlined with blue:
Make a more useful example. At least show the rendering.
<?xml version="1.0" standalone="no"?> <svg xmlns="http://www.w3.org/2000/svg" width="10cm" height="5cm" viewBox="0 0 1000 500"> <rect x="200" y="100" width="600" height="300" fill="red" stroke="blue" stroke-width="3"/> </svg>
Remove all of this advantages/limitations discussion.
The presentation attributes offer the following advantages:
In some situations, SVG content that uses the presentation attributes has potential limitations versus SVG content that is styled with a style sheet language such as CSS (see Styling with CSS). In other situations, such as when an XSLT style sheet generates SVG content from semantically rich XML source files, the limitations below may not apply. Depending on the situation, some of the following potential limitations may or may not apply to the presentation attributes:
For user agents that support CSS, the presentation attributes must be translated to corresponding CSS style rules according to rules described in Precedence of non-CSS presentational hints ([CSS21], section 6.4.4), with the additional clarification that the presentation attributes are conceptually inserted into a new author style sheet which is the first in the author style sheet collection. The presentation attributes thus will participate in the CSS 2.1 cascade as if they were replaced by corresponding CSS style rules placed at the start of the author style sheet with a specificity of zero. In general, this means that the presentation attributes have lower priority than other CSS style rules specified in author style sheets or ‘style’ attributes.
User agents that do not support CSS must ignore any CSS style rules defined in CSS style sheets and ‘style’ attributes. In this case, the CSS cascade does not apply. (Inheritance of properties, however, does apply. See Property inheritance.)
Make UAs that don't support CSS non-conforming instead, and drop the above paragraph?
An !important declaration ([CSS21], section 6.4.2) within a presentation attribute definition is an invalid value.
Referencing the discussion of presentation attribute parsing in the Types chapter.
Animation of presentation attributes is equivalent to animating the corresponding property.
SVG implementations that support CSS are required to support the following:
The following example shows the use of an external CSS style
sheet to set the ‘fill
’ and ‘stroke
’ properties on all
rectangles to red and blue, respectively:
Make a more useful example. At least show the rendering.
mystyle.css rect { fill: red; stroke: blue; stroke-width: 3 } SVG file referencing mystyle.css <?xml version="1.0" standalone="no"?> <?xml-stylesheet href="mystyle.css" type="text/css"?> <svg xmlns="http://www.w3.org/2000/svg" width="10cm" height="5cm" viewBox="0 0 1000 500"> <rect x="200" y="100" width="600" height="300"/> </svg>
View this
example as SVG (SVG-enabled browsers only)
CSS style sheets can be embedded within SVG content inside of a ‘style’ element. The following example uses an internal CSS style sheet to achieve the same result as the previous example:
<?xml version="1.0" standalone="no"?> <svg xmlns="http://www.w3.org/2000/svg" width="10cm" height="5cm" viewBox="0 0 1000 500"> <defs> <style type="text/css"><![CDATA[ rect { fill: red; stroke: blue; stroke-width: 3 } ]]></style> </defs> <rect x="200" y="100" width="600" height="300"/> </svg>
Note how the CSS style sheet is placed within a CDATA
construct (i.e., <![CDATA[ ... ]]>
). Placing
internal CSS style sheets within CDATA
blocks is
sometimes necessary since CSS style sheets can include
characters, such as ">", which conflict with XML parsers.
Even if a given style sheet does not use characters that
conflict with XML parsing, it is highly recommended that
internal style sheets be placed inside CDATA
blocks.
If we need to keep this, it should also mention best practice for HTML. In any case, ">" is fine in XML documents; it's "<" and "&" you need to escape.
Implementations that support CSS are also required to support CSS inline style. Similar to the ‘style’ attribute in HTML, CSS inline style can be declared within a ‘style’ attribute in SVG by specifying a semicolon-separated list of property declarations, where each property declaration has the form "name: value". Note that property declarations inside the ‘style’ attribute must follow CSS style rules, see The 'style' attribute.
Do we need a conformance class for svg UAs that don't support CSS?
The following example shows how the
‘fill
’ and ‘stroke
’ properties can be specified
on a ‘rect’ using the ‘style’ attribute. Just like the
previous example, the rectangle will be filled with red and
outlined with blue:
<?xml version="1.0" standalone="no"?> <svg xmlns="http://www.w3.org/2000/svg" width="10cm" height="5cm" viewBox="0 0 1000 500"> <rect x="200" y="100" width="600" height="300" style="fill: red; stroke: blue; stroke-width: 3"/> </svg>
In an SVG user agent that supports CSS style sheets, the following facilities from CSS 2.1 must be supported:
Why not support ::before/::after? We might have discussed this.
This is not a "facility from CSS 2.1". Can probably remove this list item.
Note the following about relative URIs and external CSS style sheets: The CSS 2.1 specification says ([CSS21], section 4.3.4) that relative URIs (as defined in Uniform Resource Identifiers (URI): Generic Syntax [RFC3986]) within style sheets are resolved such that the base URI is that of the style sheet, not that of the referencing document.
Should be talking about URLs instead, no?
Property declarations via presentation attributes are expressed in XML [XML10], which is case-sensitive. CSS property declarations specified either in CSS style sheets or in a ‘style’ attribute, on the other hand, are generally case-insensitive with some exceptions ([CSS21], section 4.1.3).
Because presentation attributes are expressed as XML
attributes, their names are case-sensitive and must be
given exactly as they are defined.
When using a presentation attribute to specify a value for the
‘fill
’ property, the presentation attribute must be
be specified as fill="…" and not
fill="…" or Fill="…". Keyword
values, such as italic in
font-style="italic",
are also case-sensitive and must be specified using the exact
case used in the specification which defines the given keyword.
For example, the keyword sRGB
must have lowercase "s" and uppercase "RGB".
Also we should not require the "correct" case to be used. (ACTION-3276 on Cameron)
Property declarations within CSS style sheets or in a ‘style’ attribute must only conform to CSS rules, which are generally more lenient with regard to case sensitivity. However, to promote consistency across the different ways for expressing styling properties, it is strongly recommended that authors use the exact property names (usually, lowercase letters and hyphens) as defined in the relevant specification and express all keywords using the same case as is required by presentation attributes and not take advantage of CSS's ability to ignore case.
The above paragraph doesn't add anything.
SVG 2 Requirement: | Consider relaxing case sensitivity of presentation attribute values. |
---|---|
Resolution: | We will make property values case insensitivity. |
Purpose: | To align presentation attribute syntax parsing with parsing of the corresponding CSS property. |
Owner: | Cameron (ACTION-3276) |
SVG shares various relevant properties and approaches common to CSS and XSL, plus the semantics of many of the processing rules.
This doesn't need a whole section. Remove it, and any interesting information can be moved earlier in the chapter.
SVG shares the following facilities with CSS and XSL:
External style sheets are referenced using the mechanism documented in Associating Style Sheets with XML documents Version 1.0 [XML-SS].
We should suggest @import
as a means for
referencing external CSS style sheets that will also work in an HTML5
document.
Where is it defined that an HTML ‘link’ element can cause a style sheet to be loaded and applied to SVG content? Should we allow (an SVG or HTML namespace) ‘link’ element in an SVG document fragment?
This section can be folded into the "Styling with CSS" one.
SVG 2 Requirement: | Add HTML5 ‘style’ element attributes to SVG's ‘style’ element. |
---|---|
Resolution: | SVG 2 ‘style’ element shall be aligned with the HTML5 ‘style’ element. |
Purpose: | To not surprise authors with different behavior for the ‘style’ element in HTML and SVG content. |
Owner: | Cameron (ACTION-3277) |
The ‘style’ element allows style sheets to be embedded directly within SVG content. SVG's ‘style’ element has the same attributes as the corresponding element in HTML (see HTML's ‘style’ element).
Attribute definitions:
Name | Value | Initial value | Animatable |
---|---|---|---|
type | content-type | text/css | no |
This attribute specifies the style sheet language of the element's contents. The style sheet language is specified as a content type (e.g., "text/css"), as per MIME Part Two: Media Types [RFC2046]. If the attribute is not specified, then the style sheet language is assumed to be CSS.
Name | Value | Initial value | Animatable |
---|---|---|---|
media | media | (none) | no |
This attribute specifies the intended destination medium for style information. It may be a single media descriptor or a comma-separated list. The default value for this attribute is "all". The set of recognized media-descriptors are the list of media types recognized by CSS 2.1 ([CSS21], section 7.3).
Don't we need to require that the style sheet is applied or not based on the value of this attribute?
Name | Value | Initial value | Animatable |
---|---|---|---|
title | advisory-title | (none) | no |
(For compatibility with HTML 4 [HTML4].) This attribute specifies an advisory title for the ‘style’ element.
The Value columns in the tables above need updating to the new attribute value syntax.
The syntax of style data depends on the style sheet language.
Some style sheet languages might allow a wider variety of rules in the ‘style’ element than in the ‘style’. For example, with CSS, rules can be declared within a ‘style’ element that cannot be declared within a ‘style’ attribute.
An example showing the ‘style’ element is provided above (see example).
Attribute definitions:
Should call into the HTML algorithm that parses a "set of space-separated tokens".
Should have an attribute definition table.
The ‘class’ attribute assigns one or more class names to an element. The element may be said to belong to these classes. A class name may be shared by several element instances. The ‘class’ attribute has several roles:
In the following example, the ‘text’ element is used in conjunction with the ‘class’ attribute to markup document messages. Messages appear in both English and French versions.
<!-- English messages --> <text class="info" lang="en">Variable declared twice</text> <text class="warning" lang="en">Undeclared variable</text> <text class="error" lang="en">Bad syntax for variable name</text> <!-- French messages --> <text class="info" lang="fr">Variable déclarée deux fois</text> <text class="warning" lang="fr">Variable indéfinie</text> <text class="error" lang="fr">Erreur de syntaxe pour variable</text>
In an SVG user agent that supports CSS styling, the following CSS style rules would tell visual user agents to display informational messages in green, warning messages in yellow, and error messages in red:
text.info { fill: green } text.warning { fill: yellow } text.error { fill: red }
The ‘style’ attribute allows per-element style rules to be specified directly on a given element. When CSS styling is used, CSS inline style is specified by including semicolon-separated property declarations of the form "name : value" within the ‘style’ attribute. Property declarations must follow CSS style rules thus CSS defined properties (e.g. 'font-size') when having a <length> value must include a unit (for non-zero values). See SVG's styling properties for a list of CSS defined properties.
Attribute definitions:
Should add an attribute definition table and refer to css-syntax's algorithm to parse a declarations.
The style attribute may be used to apply a particular style to an individual SVG element. If the style will be reused for several elements, authors should use the ‘style’ element to regroup that information. For optimal flexibility, authors should define styles in external style sheets.
An example showing the ‘style’ attribute is provided above (see example).
Need to ensure that all of the attributes you can put on HTML ‘style’ elements can be used here, such as ‘scope’.
Whether or not the user agent supports CSS, property inheritance in SVG follows the property inheritance rules defined in the CSS 2.1 specification. The normative definition for property inheritance is the Inheritance section of the CSS 2.1 specification ([CSS21], section 6.2).
How property inheritance works is defined completely by CSS. Probably most of this section can be removed, or at least condensed and turned into a note.
The definition of each property indicates whether the property can inherit the value of its parent.
In SVG, as in CSS 2.1, most elements inherit
computed values
([CSS21], section 6.1.2).
For cases where something other than
computed values are inherited, the property definition will
describe the inheritance rules. For specified values
([CSS21], section 6.1.1)
which are expressed in user units, in
pixels (e.g., 20px) or in absolute values,
the computed value equals the specified
value. For specified values which use certain relative units
(i.e., em, ex and percentages), the computed
value will have the same units as the value to which it is
relative. Thus, if the parent element has a ‘font-size
’ of
10pt and the current
element has a ‘font-size
’ of 120%,
then the computed value for ‘font-size
’ on the current element
will be 12pt. In cases where the referenced value for
relative units is not expressed in any of the standard SVG
units (i.e., CSS units or user units), such as when a
percentage is used relative to the current viewport or an
object bounding box, then the computed value will be in user
units.
Note that SVG has some facilities wherein a property which
is specified on an ancestor element might effect its descendant
element, even if the descendant element has a different
assigned value for that property. For example, if a ‘clip-path
’
property is specified on an ancestor element, and the current element has a
‘clip-path
’ of none, the
ancestor's clipping path
still applies to the current element because the semantics of
SVG state that the clipping path used on a given element is the
intersection of all clipping paths specified on itself and all
ancestor elements. The key concept is that property assignment
(with possible property inheritance) happens first. After
properties values have been assigned to the various elements,
then the user agent applies the semantics of each assigned
property, which might result in the property assignment of an
ancestor element affecting the rendering of its
descendants.
The following define the scope/range of style sheets:
Should mention SVG inline in HTML.
The content size properties specify the size of a CSS box.
These properties need more of a description. Why are they here?
These properties should be defined by reference to CSS, rather than repeating a bunch of information here.
Name: | width |
---|---|
Value: | <percentage> | <length> | auto |
Initial: | auto |
Applies to: | all elements but non-replaced inline elements, table rows, and row groups, in SVG: the ‘foreignObject’, ‘image’, ‘mask’, ‘rect’ and ‘svg’ elements |
Inherited: | no |
Percentages: | refer to width of containing block |
Media: | visual |
Computed value: | the percentage or 'auto' as specified or the absolute length |
Animatable: | yes |
Except for any additional information provided in this specification, the normative definition of the ‘width’ property is in CSS 2.1 ([CSS21], section 10.2).
Name: | height |
---|---|
Value: | <percentage> | <length> | auto |
Initial: | auto |
Applies to: | all elements but non-replaced inline elements, table columns, and column groups, in SVG: the ‘foreignObject’, ‘image’, ‘mask’, ‘rect’ and ‘svg’ elements |
Inherited: | no |
Percentages: | see prose |
Media: | visual |
Computed value: | the percentage or 'auto' (see prose under <percentage>) or the absolute length |
Animatable: | yes |
Except for any additional information provided in this specification, the normative definition of the ‘height’ property is in CSS 2.1 ([CSS21], section 10.5).
Is there a need to define 'auto' in more detail specifically for svg/foreignObject?
The user agent shall maintain a user agent style sheet ([CSS21], section 6.4) for elements in the SVG namespace for visual media ([CSS21], section 7.3.1). The user agent style sheet below is expressed using CSS syntax; however, user agents are required to support the behavior that corresponds to this default style sheet even if CSS style sheets are not supported in the user agent:
Why is visual media mentioned? The user agent style sheet
should just be applied as is, not effectively wrapped in a @media visual
rule.
svg, image, pattern { overflow: hidden }
Should this be for non-root svg elements only for web compat?
This needs to be reviewed. It should at least
use @namespace
to cause the rules to match only
SVG elements. attr(width)
won't do the right
thing if the ‘width’ attribute does
not use a unit. And what about when the attributes are being
animated? Presumably attr()
doesn't look at animated
values. Discussion.
(ACTION-3733 on Cameron)
The first line of the above user agent style sheet will
cause the initial
clipping path to be established at the bounds of the initial viewport.
Furthermore, it will cause new clipping paths to be established
at the bounds of the listed elements, all of which are elements that
establish a new viewport. (Refer to the description of
SVG's use of the ‘overflow
’ property for more
information.)
interface SVGStyleElement : SVGElement { attribute DOMString type; attribute DOMString media; attribute DOMString title; }; SVGStyleElement implements LinkStyle;
Beside SVG's styling properties, SVG also defines geometry properties. Geometry properties describe the position and dimension of the graphics elements ‘circle’, ‘ellipse’, ‘rect’, ‘image’, ‘foreignObject’ and the elements ‘mask’, ‘svg’.
Name: | cx |
---|---|
Value: | <length> | <percentage> |
Initial: | 0 |
Applies to: | ‘circle’ and ‘ellipse’ |
Inherited: | no |
Percentages: | refer to the size of the current viewport (see Units) |
Media: | visual |
Computed value: | absolute length or percentage |
Animatable: | yes |
The ‘cx
’ property describes the horizontal center coordinate
of the position of the element.
Name: | cy |
---|---|
Value: | <length> | <percentage> |
Initial: | 0 |
Applies to: | ‘circle’ and ‘ellipse’ |
Inherited: | no |
Percentages: | refer to the size of the current viewport (see Units) |
Media: | visual |
Computed value: | absolute length or percentage |
Animatable: | yes |
The ‘cy
’ property describes the vertical center coordinate
of the position of the element.
Name: | r |
---|---|
Value: | <length> | <percentage> |
Initial: | 0 |
Applies to: | ‘circle’ |
Inherited: | no |
Percentages: | refer to the size of the current viewport (see Units) |
Media: | visual |
Computed value: | absolute length or percentage |
Animatable: | yes |
The ‘r
’ property describes the radius of the ‘circle’
element.
Negative values for ‘r
’ are illegal.
Name: | rx |
---|---|
Value: | <length> | <percentage> |
Initial: | 0 |
Applies to: | ‘ellipse’, ‘rect’ |
Inherited: | no |
Percentages: | refer to the size of the current viewport (see Units) |
Media: | visual |
Computed value: | absolute length or percentage |
Animatable: | yes |
The ‘rx
’ property describes the horizontal radius of the
‘ellipse’ element and the curve radius of the ‘rect’
element.
Negative values for ‘rx
’ are illegal.
Name: | ry |
---|---|
Value: | <length> | <percentage> |
Initial: | 0 |
Applies to: | ‘ellipse’, ‘rect’ |
Inherited: | no |
Percentages: | refer to the size of the current viewport (see Units) |
Media: | visual |
Computed value: | absolute length or percentage |
Animatable: | yes |
The ‘ry
’ property describes the vertical radius of the
‘ellipse’ element and the curve radius of the ‘rect’
element.
Negative values for ‘ry
’ are illegal.
Name: | x |
---|---|
Value: | <length> | <percentage> |
Initial: | 0 |
Applies to: | ‘mask’, ‘svg’, ‘rect’, ‘image’, ‘foreignObject’ |
Inherited: | no |
Percentages: | refer to the size of the current viewport (see Units) |
Media: | visual |
Computed value: | absolute length or percentage |
Animatable: | yes |
The ‘x
’ property describes the horizontal coordinate of
the position of the element.
Name: | y |
---|---|
Value: | <length> | <percentage> |
Initial: | 0 |
Applies to: | ‘mask’, ‘svg’, ‘rect’, ‘image’, ‘foreignObject’ |
Inherited: | no |
Percentages: | refer to the size of the current viewport (see Units) |
Media: | visual |
Computed value: | absolute length or percentage |
Animatable: | yes |
The ‘y
’ property describes the vertical coordinate of
the position of the element.
For all media, the canvas describes "the space where the SVG content is rendered." The canvas is infinite for each dimension of the space, but rendering occurs relative to a finite rectangular region of the canvas. This finite rectangular region is called the SVG viewport. For visual media ([CSS21], section 7.3.1) the SVG viewport is the viewing area where the user sees the SVG content.
The above paragraph and definitions need to be merged.
The size of the SVG viewport (i.e., its width and height) is determined by a negotiation process (see Establishing the size of the initial viewport) between the SVG document fragment and its parent (real or implicit). Once that negotiation process is completed, the SVG user agent is provided the following information:
Using the above information, the SVG user agent determines the SVG viewport, an initial viewport coordinate system and an initial local coordinate system such that the two coordinates systems are identical. Both coordinates systems are established such that the origin matches the origin of the viewport (for the root viewport, the viewport origin is at the top/left corner), and one unit in the initial coordinate system equals one CSS pixel in the SVG viewport. (See Initial coordinate system.)
New SVG viewports can be established. By establishing a new viewport, you can redefine the meaning of percentages units and provide a new reference rectangle for "fitting" a graphic relative to a particular rectangular area.
SVG content can be
embedded (by reference or inline) within a containing document. This containing
document might include attributes, properties and/or other
parameters (explicit or implicit) which specify or provide
hints about the dimensions of the viewport for the SVG content.
SVG content itself optionally can provide information about the
appropriate viewport region for the content via the ‘width
’
and ‘height
’ presentation attributes on the outermost svg element.
If SVG is embedded within a containing element.
The ‘width
’ presentation attribute on the
outermost svg element
establishes the viewport's width, unless the following
conditions are met:
Under these conditions, the positioning properties establish the viewport's width.
Similarly, if there are
positioning properties
specified on the referencing element or on the
outermost svg element that are
sufficient to establish the height of the viewport, then these
positioning properties establish the viewport's height;
otherwise, the ‘height
’ presentation attribute
on the outermost svg element
establishes the viewport's height.
If the ‘width
’ or ‘height
’
presentation attributes on the outermost svg element
are in user units (i.e., no unit
identifier has been provided), then the value is assumed to be
equivalent to the same number of "px" units (see Units).
In the following example, an SVG graphic is embedded inline within a parent XML document which is formatted using CSS layout rules. Since CSS positioning properties are not provided on the outermost svg element, the width="100px" and height="200px" attributes determine the size of the initial viewport:
<?xml version="1.0" standalone="yes"?> <parent xmlns="http://some.url"> <!-- SVG graphic --> <svg xmlns='http://www.w3.org/2000/svg' width="100px" height="200px"> <path d="M100,100 Q200,400,300,100"/> <!-- rest of SVG graphic would go here --> </svg> </parent>
The initial clipping path for the SVG document fragment is established according to the rules described in The initial clipping path.
For the outermost svg element, the SVG user agent determines an initial viewport coordinate system and an initial local coordinate system such that the two coordinates systems are identical. The origin of both coordinate systems is at the origin of the viewport, and one unit in the initial coordinate system equals one "pixel" (i.e., a px unit as defined in CSS 2.1 ([CSS21], section 4.3.2) in the SVG viewport. In most cases, such as stand-alone SVG documents or SVG document fragments embedded (by reference or inline) within XML parent documents where the parent's layout is determined by CSS [CSS21] or XSL [XSL], the initial viewport coordinate system (and therefore the initial user coordinate system) has its origin at the top/left of the viewport, with the positive x-axis pointing towards the right, the positive y-axis pointing down, and text rendered with an "upright" orientation, which means glyphs are oriented such that Roman characters and full-size ideographic characters for Asian scripts have the top edge of the corresponding glyphs oriented upwards and the right edge of the corresponding glyphs oriented to the right.
If the SVG implementation is part of a user agent which supports styling XML documents using CSS 2.1 compatible px units, then the SVG user agent should get its initial value for the size of a px unit in real world units to match the value used for other XML styling operations; otherwise, if the user agent can determine the size of a px unit from its environment, it should use that value; otherwise, it should choose an appropriate size for one px unit. In all cases, the size of a px must be in conformance with the rules described in CSS 2.1 ([CSS21], section 4.3.2).
Example InitialCoords below shows that the initial coordinate system has the origin at the top/left with the x-axis pointing to the right and the y-axis pointing down. The initial user coordinate system has one user unit equal to the parent (implicit or explicit) user agent's "pixel".
<?xml version="1.0" standalone="no"?> <svg width="300px" height="100px" version="1.1" xmlns="http://www.w3.org/2000/svg"> <desc>Example InitialCoords - SVG's initial coordinate system</desc> <g fill="none" stroke="black" stroke-width="3" > <line x1="0" y1="1.5" x2="300" y2="1.5" /> <line x1="1.5" y1="0" x2="1.5" y2="100" /> </g> <g fill="red" stroke="none" > <rect x="0" y="0" width="3" height="3" /> <rect x="297" y="0" width="3" height="3" /> <rect x="0" y="97" width="3" height="3" /> </g> <g font-size="14" font-family="Verdana" > <text x="10" y="20">(0,0)</text> <text x="240" y="20">(300,0)</text> <text x="10" y="90">(0,100)</text> </g> </svg>
transform
’ property [CSS3TRANSFORMS].Name | Value | Initial value | Animatable |
---|---|---|---|
viewBox | [<min-x> <min-y> <width> <height>] | As if not specified. | yes |
<min-x>, <min-x>, <width>, <height> = <number>
Transform on the ‘svg’ element is a bit special due to the ‘viewBox’ attribute. The transform should be applied as if the ‘svg’ had a parent element with that transform set.
RESOLUTION: transform property applies conceptually to the outside of the 'svg' element and there is no difference between
presentation attribute and style property (in terms of the visual result).
It is often desirable to specify that a given set of graphics stretch to fit a particular container element. The ‘viewBox’ attribute provides this capability.
All elements that establish a new viewport (see elements that establish viewports), plus the ‘marker’, ‘pattern’ and ‘view’ elements have attribute ‘viewBox’. The value of the ‘viewBox’ attribute is a list of four numbers <min-x>, <min-y>, <width> and <height>, separated by whitespace and/or a comma, which specify a rectangle in user space which should be mapped to the bounds of the viewport established by the given element, taking into account attribute ‘preserveAspectRatio’. If specified, an additional transformation is applied to all descendants of the given element to achieve the specified effect.
A negative value for <width> or <height> is an error (see Error processing). A value of zero disables rendering of the element.
Example ViewBox illustrates the use of the ‘viewBox’ attribute on the outermost svg element to specify that the SVG content should stretch to fit bounds of the viewport.
<?xml version="1.0" standalone="no"?> <svg width="300px" height="200px" viewBox="0 0 1500 1000" preserveAspectRatio="none" xmlns="http://www.w3.org/2000/svg"> <desc>Example ViewBox - uses the viewBox attribute to automatically create an initial user coordinate system which causes the graphic to scale to fit into the viewport no matter what size the viewport is.</desc> <!-- This rectangle goes from (0,0) to (1500,1000) in local coordinate system. Because of the viewBox attribute above, the rectangle will end up filling the entire area reserved for the SVG content. --> <rect x="0" y="0" width="1500" height="1000" fill="yellow" stroke="blue" stroke-width="12" /> <!-- A large, red triangle --> <path fill="red" d="M 750,100 L 250,900 L 1250,900 z"/> <!-- A text string that spans most of the viewport --> <text x="100" y="600" font-size="200" font-family="Verdana" > Stretch to fit </text> </svg>
Rendered into viewport with width=300px, height=200px |
Rendered into viewport with width=150px, height=200px |
|
---|---|---|
View
this example as SVG (SVG-enabled browsers only)
The effect of the ‘viewBox’ attribute is that the user agent automatically supplies the appropriate transformation matrix to map the specified rectangle in local coordinate system to the bounds of a designated region (often, the viewport). To achieve the effect of the example on the left, with viewport dimensions of 300 by 200 pixels, the user agent needs to automatically insert a transformation which scales both X and Y by 0.2. The effect is equivalent to having a viewport of size 300px by 200px and the following supplemental transformation in the document, as follows:
<?xml version="1.0" standalone="no"?> <svg width="300px" height="200px" xmlns="http://www.w3.org/2000/svg"> <g transform="scale(0.2)"> <!-- Rest of document goes here --> </g> </svg>
To achieve the effect of the example on the right, with viewport dimensions of 150 by 200 pixels, the user agent needs to automatically insert a transformation which scales X by 0.1 and Y by 0.2. The effect is equivalent to having a viewport of size 150px by 200px and the following supplemental transformation in the document, as follows:
<?xml version="1.0" standalone="no"?> <svg width="150px" height="200px" xmlns="http://www.w3.org/2000/svg"> <g transform="scale(0.1 0.2)"> <!-- Rest of document goes here --> </g> </svg>
Note that in some cases the user agent will need to supply a translate transformation in addition to a scale transformation. For example, on an outermost svg element, a translate transformation will be needed if the ‘viewBox’ attributes specifies values other than zero for <min-x> or <min-y>.
If both ‘transform
’ (or ‘patternTransform’)
and ‘viewBox’ are applied to an element two new coordinate
systems are established. ‘transform
’ establishes the first new
coordinate system for the element. ‘viewBox’
establishes a second coordinate system for all descendants of
the element. The first coordinate system is post-multiplied by the
second coordinate system.
Unlike the
‘transform
’ property,
the automatic transformation that is created
due to a ‘viewBox’ does not affect
the ‘x’, ‘y’, ‘width’ and ‘height’ attributes (or in the case of
the ‘marker’ element, the
‘markerWidth’ and ‘markerHeight’ attributes) on the
element with the ‘viewBox’
attribute. Thus, in the example above which shows an
‘svg’ element which has
‘width
’ and ‘height
’ presentation attributes
and a ‘viewBox’ attribute,
the ‘width
’ and ‘height
’
represent values in the coordinate system that exists before the
‘viewBox’ transformation is applied. On
the other hand, like the ‘transform
’ property, it does
establish a new coordinate system for all other attributes and
for descendant elements.
Name | Value | Initial value | Animatable |
---|---|---|---|
preserveAspectRatio | <align> <meetOrSlice>? | xMidYMid meet | yes |
<align> = none | xMinYMin | xMidYMin | xMaxYMin | xMinYMid | xMidYMid | xMaxYMid | xMinYMax | xMidYMax | xMaxYMax
<meetOrSlice> = meet | slice
Indicates whether or not to force uniform scaling. Applies to all elements that establish a new viewport (see elements that establish viewports), plus the ‘image’, ‘marker’, ‘pattern’ and ‘view’ elements
In some cases, typically when using the ‘viewBox’ attribute, it is desirable that the graphics stretch to fit non-uniformly to take up the entire viewport. In other cases, it is desirable that uniform scaling be used for the purposes of preserving the aspect ratio of the graphics.
For elements that establish a new viewport (see elements that establish viewports), plus the ‘marker’, ‘pattern’ and ‘view’ elements, ‘preserveAspectRatio’ only applies when a value has been provided for ‘viewBox’ on the same element. For these elements, if attribute ‘viewBox’ is not provided, then ‘preserveAspectRatio’ is ignored.
For ‘image’ elements, ‘preserveAspectRatio’ indicates how referenced images should be fitted with respect to the reference rectangle and whether the aspect ratio of the referenced image should be preserved with respect to the current user coordinate system.
The <align> parameter indicates whether to force uniform scaling and, if so, the alignment method to use in case the aspect ratio of the ‘viewBox’ doesn't match the aspect ratio of the SVG viewport. The <align> parameter must be one of the following strings:
The <meetOrSlice> parameter is optional and, if provided, is separated from the <align> value by one or more spaces and then must be one of the following strings:
meet (the default) - Scale the graphic such that:
In this case, if the aspect ratio of the graphic does not match the viewport, some of the viewport will extend beyond the bounds of the ‘viewBox’ (i.e., the area into which the ‘viewBox’ will draw will be smaller than the viewport).
slice - Scale the graphic such that:
In this case, if the aspect ratio of the ‘viewBox’ does not match the viewport, some of the ‘viewBox’ will extend beyond the bounds of the viewport (i.e., the area into which the ‘viewBox’ will draw is larger than the viewport).
Example PreserveAspectRatio illustrates the various options on ‘preserveAspectRatio’. The example creates several new viewports by including ‘svg’ sub-elements embedded inside the outermost svg element (see Establishing a new viewport).
<svg width="450px" height="300px" xmlns="http://www.w3.org/2000/svg"> <desc>Example PreserveAspectRatio - illustrates preserveAspectRatio attribute</desc> <defs> <g id="smile"> <rect x='.5' y='.5' width='29' height='39' fill='black' stroke='red'/> <g transform='translate(0, 5)'> <circle cx='15' cy='15' r='10' fill='yellow'/> <circle cx='12' cy='12' r='1.5' fill='black'/> <circle cx='17' cy='12' r='1.5' fill='black'/> <path d='M 10 19 A 8 8 0 0 0 20 19' stroke='black' stroke-width='2'/> </g> </g> </defs> <rect x="1" y="1" width="448" height="298" fill="none" stroke="blue"/> <g font-size="9"> <text x="10" y="30">SVG to fit</text> <g transform="translate(20,40)"><use href="#smile" /></g> <text x="10" y="110">Viewport 1</text> <g transform="translate(10,120)"><rect x='.5' y='.5' width='49' height='29' fill='none' stroke='blue'/>;</g> <text x="10" y="180">Viewport 2</text> <g transform="translate(20,190)"><rect x='.5' y='.5' width='29' height='59' fill='none' stroke='blue'/>;</g> <g id="meet-group-1" transform="translate(100, 60)"> <text x="0" y="-30">--------------- meet ---------------</text> <g><text y="-10">xMin*</text><rect x='.5' y='.5' width='49' height='29' fill='none' stroke='blue'/>; <svg preserveAspectRatio="xMinYMin meet" viewBox="0 0 30 40" width="50" height="30"><use href="#smile" /></svg></g> <g transform="translate(70,0)"><text y="-10">xMid*</text><rect x='.5' y='.5' width='49' height='29' fill='none' stroke='blue'/>; <svg preserveAspectRatio="xMidYMid meet" viewBox="0 0 30 40" width="50" height="30"><use href="#smile" /></svg></g> <g transform="translate(0,70)"><text y="-10">xMax*</text><rect x='.5' y='.5' width='49' height='29' fill='none' stroke='blue'/>; <svg preserveAspectRatio="xMaxYMax meet" viewBox="0 0 30 40" width="50" height="30"><use href="#smile" /></svg></g> </g> <g id="meet-group-2" transform="translate(250, 60)"> <text x="0" y="-30">---------- meet ----------</text> <g><text y="-10">*YMin</text><rect x='.5' y='.5' width='29' height='59' fill='none' stroke='blue'/>; <svg preserveAspectRatio="xMinYMin meet" viewBox="0 0 30 40" width="30" height="60"><use href="#smile" /></svg></g> <g transform="translate(50, 0)"><text y="-10">*YMid</text><rect x='.5' y='.5' width='29' height='59' fill='none' stroke='blue'/>; <svg preserveAspectRatio="xMidYMid meet" viewBox="0 0 30 40" width="30" height="60"><use href="#smile" /></svg></g> <g transform="translate(100, 0)"><text y="-10">*YMax</text><rect x='.5' y='.5' width='29' height='59' fill='none' stroke='blue'/>; <svg preserveAspectRatio="xMaxYMax meet" viewBox="0 0 30 40" width="30" height="60"><use href="#smile" /></svg></g> </g> <g id="slice-group-1" transform="translate(100, 220)"> <text x="0" y="-30">---------- slice ----------</text> <g><text y="-10">xMin*</text><rect x='.5' y='.5' width='29' height='59' fill='none' stroke='blue'/>; <svg preserveAspectRatio="xMinYMin slice" viewBox="0 0 30 40" width="30" height="60"><use href="#smile" /></svg></g> <g transform="translate(50,0)"><text y="-10">xMid*</text><rect x='.5' y='.5' width='29' height='59' fill='none' stroke='blue'/>; <svg preserveAspectRatio="xMidYMid slice" viewBox="0 0 30 40" width="30" height="60"><use href="#smile" /></svg></g> <g transform="translate(100,0)"><text y="-10">xMax*</text><rect x='.5' y='.5' width='29' height='59' fill='none' stroke='blue'/>; <svg preserveAspectRatio="xMaxYMax slice" viewBox="0 0 30 40" width="30" height="60"><use href="#smile" /></svg></g> </g> <g id="slice-group-2" transform="translate(250, 220)"> <text x="0" y="-30">--------------- slice ---------------</text> <g><text y="-10">*YMin</text><rect x='.5' y='.5' width='49' height='29' fill='none' stroke='blue'/>; <svg preserveAspectRatio="xMinYMin slice" viewBox="0 0 30 40" width="50" height="30"><use href="#smile" /></svg></g> <g transform="translate(70,0)"><text y="-10">*YMid</text><rect x='.5' y='.5' width='49' height='29' fill='none' stroke='blue'/>; <svg preserveAspectRatio="xMidYMid slice" viewBox="0 0 30 40" width="50" height="30"><use href="#smile" /></svg></g> <g transform="translate(140,0)"><text y="-10">*YMax</text><rect x='.5' y='.5' width='49' height='29' fill='none' stroke='blue'/>; <svg preserveAspectRatio="xMaxYMax slice" viewBox="0 0 30 40" width="50" height="30"><use href="#smile" /></svg></g> </g> </g> </svg>
Note that this section handles the SVG viewport which is different from the term "viewport" in CSS.
At any point in an SVG drawing, you can establish a new SVG viewport into which all contained graphics is drawn by including an ‘svg’ element inside SVG content. By establishing a new SVG viewport, you also implicitly establish a new viewport coordinate system, a new user coordinate system. Additionally, there is a new meaning for percentage units defined to be relative to the current SVG viewport since a new SVG viewport has been established (see Units).
The bounds of the new SVG viewport are defined by the ‘x’, ‘y’, ‘width’ and ‘height’ attributes on the element establishing the new SVG viewport, such as an ‘svg’ element. Both the new viewport coordinate system and the new user coordinate system have their origins at (‘x’, ‘y’), where ‘x’ and ‘y’ represent the value of the corresponding attributes on the element establishing the SVG viewport. The orientation of the new viewport coordinate system and the new user coordinate system correspond to the orientation of the current user coordinate system for the element establishing the SVG viewport. A single unit in the new viewport coordinate system and the new user coordinate system are the same size as a single unit in the current user coordinate system for the element establishing the SVG viewport.
Here is an example:
<?xml version="1.0" standalone="no"?> <svg width="4in" height="3in" xmlns="http://www.w3.org/2000/svg"> <desc>This SVG drawing embeds another one, thus establishing a new SVG viewport </desc> <!-- The following statement establishing a new SVG viewport and renders SVG drawing B into that viewport --> <svg x="25%" y="25%" width="50%" height="50%"> <!-- drawing B goes here --> </svg> </svg>
For an extensive example of creating new SVG viewports, see Example PreserveAspectRatio.
The following elements establish new SVG viewports:
Whether a new SVG viewport also establishes a new additional
clipping path is determined by the value of the ‘overflow
’ property on the element
that establishes the new SVG viewport.
SVG follows the description and definition of common values and units from the CSS Values and Units Module [CSS3VALUES] for attributes, presentation attributes and CSS properties. Each attribute and property must specify the used component value type. Subsequent or extending specifications published by the CSS WG or SVG WG may extend basic data types or add new data types.
For <percentage> values that are defined to be relative to the size of viewport:
sqrt((actual-width)**2 +
(actual-height)**2)/sqrt(2)
.Example Units below illustrates some of the processing rules for different types of units.
<?xml version="1.0" standalone="no"?> <svg width="400px" height="200px" viewBox="0 0 4000 2000" xmlns="http://www.w3.org/2000/svg"> <title>Example Units</title> <desc>Illustrates various units options</desc> <!-- Frame the picture --> <rect x="5" y="5" width="3990" height="1990" fill="none" stroke="blue" stroke-width="10"/> <g fill="blue" stroke="red" font-family="Verdana" font-size="150"> <!-- Absolute unit specifiers --> <g transform="translate(400,0)"> <text x="-50" y="300" fill="black" stroke="none">Abs. units:</text> <rect x="0" y="400" width="4in" height="2in" stroke-width=".4in"/> <rect x="0" y="750" width="384" height="192" stroke-width="38.4"/> <g transform="scale(2)"> <rect x="0" y="600" width="4in" height="2in" stroke-width=".4in"/> </g> </g> <!-- Relative unit specifiers --> <g transform="translate(1600,0)"> <text x="-50" y="300" fill="black" stroke="none">Rel. units:</text> <rect x="0" y="400" width="2.5em" height="1.25em" stroke-width=".25em"/> <rect x="0" y="750" width="375" height="187.5" stroke-width="37.5"/> <g transform="scale(2)"> <rect x="0" y="600" width="2.5em" height="1.25em" stroke-width=".25em"/> </g> </g> <!-- Percentages --> <g transform="translate(2800,0)"> <text x="-50" y="300" fill="black" stroke="none">Percentages:</text> <rect x="0" y="400" width="10%" height="10%" stroke-width="1%"/> <rect x="0" y="750" width="400" height="200" stroke-width="31.62"/> <g transform="scale(2)"> <rect x="0" y="600" width="10%" height="10%" stroke-width="1%"/> </g> </g> </g> </svg>
The three rectangles on the left demonstrate the use of one of the absolute unit identifiers, the "in" unit (inch). CSS defines 1 inch to be equal to 96 pixels. Therefore, the topmost rectangle, which is specified in inches, is exactly the same size as the middle rectangle, which is specified in user units such that there are 96 user units for each corresponding inch in the topmost rectangle. The bottom rectangle of the group illustrates what happens when values specified in inches are scaled.
The three rectangles in the middle demonstrate the use of
one of the relative unit identifiers, the "em" unit. Because
the ‘font-size
’ property has been set
to 150 on the outermost ‘g’ element, each "em" unit is
equal to 150 user units. The topmost rectangle, which is
specified in "em" units, is exactly the same size as the middle
rectangle, which is specified in user units such that there are
150 user units for each corresponding "em" unit in the topmost
rectangle. The bottom rectangle of the group illustrates what
happens when values specified in "em" units are scaled.
The three rectangles on the right demonstrate the use of
percentages. Note that the width and height of the viewport in
the user coordinate system for the viewport element (in this
case, the outermost svg element) are 4000 and
2000, respectively, because processing the ‘viewBox’ attribute results in a
transformed user coordinate system. The topmost rectangle,
which is specified in percentage units, is exactly the same
size as the middle rectangle, which is specified in equivalent
user units. In particular, note that the ‘stroke-width
’ property in the
middle rectangle is set to 1% of the
sqrt((actual-width)**2 +
(actual-height)**2) / sqrt(2)
, which in this
case is .01*sqrt(4000*4000+2000*2000)/sqrt(2), or 31.62. The
bottom rectangle of the group illustrates what happens when
values specified in percentage units are scaled.
The bounding box (or "bbox") of an element is the tightest fitting rectangle aligned with the axes of that element's user coordinate system that entirely encloses it and its descendants.
Three kinds of bounding boxes can be computed for an element:
Note that the values of the ‘opacity
’, ‘visibility
’, ‘fill
’,
‘fill-opacity
’, ‘fill-rule
’, ‘stroke-dasharray
’
and ‘stroke-dashoffset
’ properties on an element have no effect on the
bounding box of an element.
For curved shapes, the bounding box must enclose all portions of the shape along the edge, not just end points. Note that control points for a curve which are not defined as lying along the line of the resulting curve (e.g., the second coordinate pair of a Cubic Bézier command) must not contribute to the dimensions of the bounding box (though those points may fall within the area of the bounding box, if they lie within the shape itself, or along or close to the curve). For example, control points of a curve that are at a further distance than the curve edge, from the non-enclosing side of the curve edge, must be excluded from the bounding box.
Even if an element is not in the rendering tree – due to it being 'display: none', within a ‘defs’ element, not usually rendered like a ‘symbol’ element or not currently present in the document tree – it still has a bounding box. A call to getBBox on the element will return the same rectangle as if the element were rendered. However, an element that is not in the rendering tree does not contribute to the bounding box of any ancestor element.
The following example defines a number of elements. The expected object bounding box for each element with an ID is shown below.
<svg xmlns="http://www.w3.org/2000/svg"> <title>Bounding Box Calculation</title> <desc>Examples of elements with different bounding box results based on context.</desc> <defs id="defs-1"> <rect id="rect-1" x="20" y="20" width="40" height="40" fill="blue" /> </defs> <g id="group-1"> <use id="use-1" href="#rect-1" x="10" y="10" /> <g id="group-2" display="none"> <rect id="rect-2" x="10" y="10" width="100" height="100" fill="red" /> </g> </g> </svg>
Element ID | Bounding Box Result |
---|---|
"defs-1 " |
{0, 0, 0, 0} |
"rect-1 " |
{20, 20, 40, 40} |
"group-1 " |
{30, 30, 40, 40} |
"use-1 " |
{30, 30, 40, 40} |
"group-2 " |
{10, 10, 100, 100} |
"rect-2 " |
{10, 10, 100, 100} |
For text content elements, for the purposes of the bounding box
calculation, each glyph must be treated as a separate graphics element.
he calculations must assume that all glyphs occupy the full glyph cell.
For example, for horizontal text, the calculations must assume that each glyph
extends vertically to the full ascent and descent values for the font.
An exception to this is when the ‘inline-size
’ presentation
attribute has been specified on the ‘text’ element, in which case the
element's content area is its bounding box.
Because declarative or scripted animation can change the shape, size, and position of an element, the bounding box is mutable. Thus, the bounding box for an element shall reflect the current values for the element at the snapshot in time at which the bounding box is requested, whether through a script call or as part of a declarative or linking syntax.
An element which has zero width, zero height, or both (such as a
vertical or horizontal line, or a ‘rect’ element with a zero
‘width
’ or ‘height
’) still has a bounding box, with a
positive value for the positive dimension, or with '0'
for both the width and height if no positive dimension is specified. Similarly,
subpaths segments of a ‘path’ element with zero width and height must be
included in that element's geometry for the sake of the bounding box.
An element with no position specified (such as a ‘path’ element with a value of (none) for the ‘d’ attribute) is positioned at the point (0,0) for the purposes of calculating a bounding box.
Note that elements whose DOM object does not derive from SVGGraphicsElement (such as gradient elements) do not have a bounding box, and thus have no interface to request a bounding box.
Elements in the rendering tree which reference unresolved resources shall
still have a bounding box, defined by the position and dimensions specified in
their attributes, or by the initial value for those attributes if no
values are supplied. For example, the element <use href="#bad" x="10" y="10"/>
would have a bounding box with an x and y of 10 and a width and height of 0.
The following algorithm defines how to compute a bounding box for a given element. The inputs to the algorithm are:
Need to define what the union of rectangles with no area means.
The algorithm to compute the bounding box is as follows, depending on the type of element:
Need to update this take into account ‘inline-size
’
on ‘text’.
The values of the ‘fill
’, ‘fill-opacity
’ and ‘fill-rule
’
properties do not affect fill-shape.
stroke
’ is anything other than
none, then set box to be the union of box and the
tightest rectangle in coordinate system space that contains the stroke shape of the
element, with the assumption that the element has no dash pattern.
The values of the ‘stroke-opacity
’, ‘stroke-dasharray
’
and ‘stroke-dashoffset
’ do not affect the calculation of the stroke shape.
Need to determine whether 'display: none' on the ‘marker’ element itself has any effect here.
clip-path
’ on element is not
none, then set box to be the tighest rectangle
in coordinate system space that contains the intersection of box and the clipping path.The fill, stroke and markers input arguments to this algorithm do not affect the bounding box returned for these elements.
The object bounding box, stroke bounding box or decorated bounding box of an element is the result of invoking the bounding box computation algorithm above with the following arguments: element is the element itself; space is the element's user coordinate system; fill is true; stroke is true if we are computing the stroke bounding box or decorated bounding box, and false othwerise; markers is true if we are computing the decorated bounding box, and false otherwise; and clipped is false.
The following elements offer the option of expressing coordinate values and lengths as fractions (and, in some cases, percentages) of the object bounding box, by setting a specified attribute to 'objectBoundingBox' on the given element:
Element | Attribute | Effect |
---|---|---|
‘linearGradient’ | ‘gradientUnits’ | Indicates that the attributes which specify the gradient vector (‘x1’, ‘y1’, ‘x2’, ‘y2’) represent fractions or percentages of the bounding box of the element to which the gradient is applied. |
‘radialGradient’ | ‘gradientUnits’ | Indicates that the attributes which specify the center (‘cx’, ‘cy’), the radius (‘r’) and focus (‘fx’, ‘fy’) represent fractions or percentages of the bounding box of the element to which the gradient is applied. |
‘mesh’ | ‘gradientUnits’ | Indicates that the attributes which specify the paint server mesh (‘x’, ‘y’) represent fractions or percentages of the bounding box of the element to which the mesh is applied. (Gets ignored if the mesh is a graphics object) |
‘pattern’ | ‘patternUnits’ | Indicates that the attributes which define how to tile the pattern (‘x’, ‘y’, ‘width’, ‘height’) are established using the bounding box of the element to which the pattern is applied. |
‘pattern’ | ‘patternContentUnits’ | Indicates that the user coordinate system for the contents of the pattern is established using the bounding box of the element to which the pattern is applied. |
‘clipPath’ | ‘clipPathUnits’ | Indicates that the user coordinate system for the contents of the ‘clipPath’ element is established using the bounding box of the element to which the clipping path is applied. |
‘mask’ | ‘maskUnits’ | Indicates that the attributes which define the masking region (‘x’, ‘y’, ‘width’, ‘height’) is established using the bounding box of the element to which the mask is applied. |
‘mask’ | ‘maskContentUnits’ | Indicates that the user coordinate system for the contents of the ‘mask’ element are established using the bounding box of the element to which the mask is applied. |
‘filter’ | ‘filterUnits’ | Indicates that the attributes which define the filter effects region (‘x’, ‘y’, ‘width’, ‘height’) represent fractions or percentages of the bounding box of the element to which the filter is applied. |
‘filter’ | ‘primitiveUnits’ | Indicates that the various length values within the filter primitives represent fractions or percentages of the bounding box of the element to which the filter is applied. |
In the discussion that follows, the term applicable element
is the element to which the given effect applies. For gradients and
patterns, the applicable element is the graphics element
which has its ‘fill
’ or ‘stroke
’ property referencing the
given gradient or pattern. (See Inheritance
of Painting Properties. For special rules concerning text elements, see the discussion of object
bounding box units and text elements.) For clipping paths,
masks and filters, the applicable element can be either a
container element or a graphics element.
When keyword objectBoundingBox is used, then the effect is as if a supplemental transformation matrix were inserted into the list of nested transformation matrices to create a new user coordinate system.
First, the (minx,miny) and (maxx,maxy) coordinates are determined by the extends of the object bounding box of the applicable element.
Then, coordinate (0,0) in the new user coordinate system is mapped to the (minx,miny) corner of the tight bounding box within the user coordinate system of the applicable element and coordinate (1,1) in the new user coordinate system is mapped to the (maxx,maxy) corner of the tight bounding box of the applicable element. In most situations, the following transformation matrix produces the correct effect:
[ (maxx-minx) 0 0 (maxy-miny) minx miny ]
When percentages are used with attributes that define the gradient vector, the pattern tile, the filter region or the masking region, a percentage represents the same value as the corresponding decimal value (e.g., 50% means the same as 0.5). If percentages are used within the content of a ‘pattern’, ‘clipPath’, ‘mask’ or ‘filter’ element, these values are treated according to the processing rules for percentages as defined in Units.
Any numeric value can be specified for values expressed as a fraction or percentage of object bounding box units. In particular, fractions less are zero or greater than one and percentages less than 0% or greater than 100% can be specified.
Keyword objectBoundingBox should not be used when the geometry of the applicable element has no width or no height, such as the case of a horizontal or vertical line, even when the line has actual thickness when viewed due to having a non-zero stroke width since stroke width is ignored for bounding box calculations. When the geometry of the applicable element has no width or height and objectBoundingBox is specified, then the given effect (e.g., a gradient or a filter) will be ignored.
SVG needs to specify how to calculate some intrinsic sizing properties to
enable inclusion within other host documents. The intrinsic width and height
of the SVG viewport of SVG content must be determined from the ‘width
’
and ‘height
’ properties. If either of these are not specified,
the used value is the initial value 'auto'.
Specifically, percentage values do not provide an intrinsic width or height.
We have the problem that either ‘width
’ and ‘height
’ are
Furthermore we can have a intrinsic ratio with ‘viewBox’. We need to describe all combinations and what happens in these cases in detail. The current text does not seem sufficient enough to describe all cases.
The outcome of this should be a intrinsic ratio for all cases.
The intrinsic aspect ratio of the SVG viewport of SVG content is necessary for example, when including SVG from an ‘object’ element in HTML styled with CSS. It is possible (indeed, common) for an SVG graphic to have an intrinsic aspect ratio but not to have an intrinsic width or height. The intrinsic aspect ratio must be calculated based upon the following rules:
width
’ and ‘height
’ properties
of the outermost svg element are both specified with
unit identifiers (in, mm, cm, pt, pc, px, em, ex) or in user units, then the aspect ratio is
calculated from the ‘width
’ and ‘height
’ properties after resolving both values to user units.
We should use the terms relative and absolute length here.width
’ and ‘height
’ of the outermost svg element are in
percentage units (or omitted) (used value is auto), the aspect ratio is calculated from the width and
height values of the ‘viewBox’ specified for the current SVG document fragment.
If the ‘viewBox’ is not correctly specified,
the intrinsic aspect ratio cannot be calculated and is considered unspecified.How is
the host document supposed to handle a "unspecified" ratio and dimension? Probably use the 300x150 size?Examples:
<svg xmlns="http://www.w3.org/2000/svg" width="10cm" height="5cm"> ... </svg>
In this example the intrinsic aspect ratio of the SVG viewport is 2:1. The intrinsic width is 10cm and the intrinsic height is 5cm.
<svg xmlns="http://www.w3.org/2000/svg" width="100%" height="50%" viewBox="0 0 200 200"> ... </svg>
In this example the intrinsic aspect ratio of the outermost SVG viewport is 1:1. An aspect ratio calculation in this case allows embedding in an object within a containing block that is only constrained in one direction.
<svg xmlns="http://www.w3.org/2000/svg" width="10cm" viewBox="0 0 200 200"> ... </svg>
In this case the intrinsic aspect ratio is 1:1.
<svg xmlns="http://www.w3.org/2000/svg" width="75%" height="10cm" viewBox="0 0 200 200"> ... </svg>
In this example, the intrinsic aspect ratio is 1:1.
Add more examples for the new auto value? E.g some of the examples provided by David Vest.
SVGTransform is the interface for one of the component
transformations within an SVGTransformList; thus, an
SVGTransform object corresponds to a single component (e.g.,
'scale(…)' or
'matrix(…)') within a ‘transform
’
attribute specification.
interface SVGTransform { // Transform Types const unsigned short SVG_TRANSFORM_UNKNOWN = 0; const unsigned short SVG_TRANSFORM_MATRIX = 1; const unsigned short SVG_TRANSFORM_TRANSLATE = 2; const unsigned short SVG_TRANSFORM_SCALE = 3; const unsigned short SVG_TRANSFORM_ROTATE = 4; const unsigned short SVG_TRANSFORM_SKEWX = 5; const unsigned short SVG_TRANSFORM_SKEWY = 6; readonly attribute unsigned short type; readonly attribute DOMMatrixReadOnly matrix; readonly attribute float angle; void setMatrix(DOMMatrixReadOnly matrix); void setTranslate(float tx, float ty); void setScale(float sx, float sy); void setRotate(float angle, float cx, float cy); void setSkewX(float angle); void setSkewY(float angle); };
The matrix that represents this transformation. The matrix object is live, meaning that any changes made to the SVGTransform object are immediately reflected in the matrix object and vice versa. In case the matrix object is changed directly (i.e., without using the methods on the SVGTransform interface itself) then the type of the SVGTransform changes to SVG_TRANSFORM_MATRIX.
A convenience attribute for SVG_TRANSFORM_ROTATE, SVG_TRANSFORM_SKEWX and SVG_TRANSFORM_SKEWY. It holds the angle that was specified.
For SVG_TRANSFORM_MATRIX, SVG_TRANSFORM_TRANSLATE and SVG_TRANSFORM_SCALE, angle will be zero.
Sets the transform type to SVG_TRANSFORM_MATRIX, with parameter matrix defining the new transformation. The values from the parameter matrix are copied, the matrix parameter does not replace SVGTransform::matrix.
This interface defines a list of SVGTransform objects.
The SVGTransformList and SVGTransform interfaces correspond
to the various attributes which specify a set of transformations, such as
the ‘transform
’ presentation attribute which is available for many of SVG's elements.
SVGTransformList has the same attributes and methods as other SVGxxxList interfaces. Implementers may consider using a single base class to implement the various SVGxxxList interfaces.
The supported property indices of an SVGTransformList object is all non-negative integers less than the length of the list.
An SVGTransformList object can be designated as read only, which means that attempts to modify the object will result in an exception being thrown, as described below.
interface SVGTransformList { readonly attribute unsigned long length; readonly attribute unsigned long numberOfItems; void clear(); SVGTransform initialize(SVGTransform newItem); getter SVGTransform getItem(unsigned long index); SVGTransform insertItemBefore(SVGTransform newItem, unsigned long index); SVGTransform replaceItem(SVGTransform newItem, unsigned long index); SVGTransform removeItem(unsigned long index); SVGTransform appendItem(SVGTransform newItem); SVGTransform createSVGTransformFromMatrix(DOMMatrixReadOnly matrix); SVGTransform? consolidate(); setter void (unsigned long index, SVGTransform newItem); };
Creates an SVGTransform object which is initialized to transform of type SVG_TRANSFORM_MATRIX and whose values are the given matrix. The values from the parameter matrix are copied, the matrix parameter is not adopted as SVGTransform::matrix.
Used for the various attributes which specify a set of transformations,
such as the ‘transform
’ presentation attribute which is available for many of
SVG's elements, and which can be animated.
The SVGAnimatedTransformList must only reflect the values of the corresponding
presentation attribute. E.g. the ‘transform
’ property set by a
‘style’ attribute or within a style block in a ‘style’
element is not represented by a SVGAnimatedTransformList.
interface SVGAnimatedTransformList { readonly attribute SVGTransformList baseVal; readonly attribute SVGTransformList animVal; };
An SVGPreserveAspectRatio object can be designated as read only, which means that attempts to modify the object will result in an exception being thrown, as described below.
interface SVGPreserveAspectRatio { // Alignment Types const unsigned short SVG_PRESERVEASPECTRATIO_UNKNOWN = 0; const unsigned short SVG_PRESERVEASPECTRATIO_NONE = 1; const unsigned short SVG_PRESERVEASPECTRATIO_XMINYMIN = 2; const unsigned short SVG_PRESERVEASPECTRATIO_XMIDYMIN = 3; const unsigned short SVG_PRESERVEASPECTRATIO_XMAXYMIN = 4; const unsigned short SVG_PRESERVEASPECTRATIO_XMINYMID = 5; const unsigned short SVG_PRESERVEASPECTRATIO_XMIDYMID = 6; const unsigned short SVG_PRESERVEASPECTRATIO_XMAXYMID = 7; const unsigned short SVG_PRESERVEASPECTRATIO_XMINYMAX = 8; const unsigned short SVG_PRESERVEASPECTRATIO_XMIDYMAX = 9; const unsigned short SVG_PRESERVEASPECTRATIO_XMAXYMAX = 10; // Meet-or-slice Types const unsigned short SVG_MEETORSLICE_UNKNOWN = 0; const unsigned short SVG_MEETORSLICE_MEET = 1; const unsigned short SVG_MEETORSLICE_SLICE = 2; attribute unsigned short align; attribute unsigned short meetOrSlice; };
interface SVGAnimatedPreserveAspectRatio { readonly attribute SVGPreserveAspectRatio baseVal; readonly attribute SVGPreserveAspectRatio animVal; };
A path represents the outline of a shape which can be filled or stroked. A path can also be used as a clipping path, to describe animation, or position text. A path can be used for more than one of these functions at the same time. (See Filling, Stroking and Paint Servers, Clipping and Masking, Animation ('animateMotion'), and Text on a Path.)
A path is described using the concept of a current point. In an analogy with drawing on paper, the current point can be thought of as the location of the pen. The position of the pen can be changed, and the outline of a shape (open or closed) can be traced by dragging the pen in either straight lines or curves.
Paths represent the geometry of the outline of an object, defined in terms of moveto (set a new current point), bearing (set a new orientation), lineto (draw a straight line), curveto (draw a curve using a cubic Bézier), arc (elliptical or circular arc) and closepath (close the current shape by connecting to the last moveto) commands. Compound paths (i.e., a path with multiple subpaths) are possible to allow effects such as "donut holes" in objects.
This chapter describes the syntax, behavior and DOM interfaces for SVG paths. Various implementation notes for SVG paths can be found in ‘path’ element implementation Notes and Elliptical arc implementation notes.
A path is defined in SVG using the ‘path’ element.
The basic shapes are all described in terms of what their equivalent path is, which is what their shape is as a path. (The equivalent path of a ‘path’ element is simply the path itself.)
Name | Value | Initial value | Animatable |
---|---|---|---|
d | svg-path [EBNF] | (none) | yes |
The definition of the outline of a shape. See Path data. Error processing for svg-path is done according to Path Data Error Handling.
Path data animation is only possible when each path data specification within an animation specification has exactly the same list of path data commands as the ‘d’ attribute. If an animation is specified and the list of path data commands is not the same, then the animation specification is in error (see Error Handling). The animation engine interpolates each parameter to each path data command separately based on the attributes to the given animation element. Flags and booleans are interpolated as fractions between zero and one, with any non-zero value considered to be a value of one/true.
The initial value, (none) indicates that the path element is valid but does not render.
Name | Value | Initial value | Animatable |
---|---|---|---|
pathLength | <number> | (none) | yes |
The author's computation of the total length of the path, in user units. This value is used to calibrate the user agent's own distance-along-a-path calculations with that of the author. The user agent will scale all distance-along-a-path computations by the ratio of ‘pathLength’ to the user agent's own computed value for total path length. ‘pathLength’ potentially affects calculations for text on a path, motion animation and various stroke operations.
A negative value is an error (see Error handling).
SVG 2 Requirement: | Support turtle-graphics-like current rotation in path syntax. |
---|---|
Resolution: | We will add a path rotation command. |
Purpose: | Make path rotations easier to animate and pie charts easier to draw. |
Owner: | Cameron (ACTION-3125) |
A path is defined by including a ‘path’ element which contains a d="(path data)" attribute, where the ‘d’ attribute contains the moveto, bearing, lineto, curveto (both cubic and quadratic Béziers), arc and closepath instructions.
Example triangle01 specifies a path in the shape of a triangle. (The M indicates a moveto, the Ls indicate linetos, and the z indicates a closepath).
<?xml version="1.0" standalone="no"?> <svg width="4cm" height="4cm" viewBox="0 0 400 400" xmlns="http://www.w3.org/2000/svg" version="1.1"> <title>Example triangle01- simple example of a 'path'</title> <desc>A path that draws a triangle</desc> <rect x="1" y="1" width="398" height="398" fill="none" stroke="blue" /> <path d="M 100 100 L 300 100 L 200 300 z" fill="red" stroke="blue" stroke-width="3" /> </svg>
Path data can contain newline characters and thus can be broken up into multiple lines to improve readability. Newlines inside attributes in markup will be normalized to space characters while parsing.
The syntax of path data is concise in order to allow for minimal file size and efficient downloads, since many SVG files will be dominated by their path data. Some of the ways that SVG attempts to minimize the size of path data are as follows:
The path data syntax is a prefix notation (i.e., commands followed by parameters). The only allowable decimal point is a Unicode U+0046 FULL STOP (".") character (also referred to in Unicode as PERIOD, dot and decimal point) and no other delimiter characters are allowed [UNICODE]. (For example, the following is an invalid numeric value in a path data stream: "13,000.56". Instead, say: "13000.56".)
For the relative versions of the commands, all coordinate values are relative to the current point at the start of the command.
Relative path commands are also influenced by the current bearing, which is an angle set by the bearing commands. This allows for paths to be specified using a style of "turtle graphics", where straight line and curved path segments are placed with their starting point at a tangent (or at some other angle) to the current bearing.
In the tables below, the following notation is used to describe the syntax of a given path command:
In the description of the path commands, cpx and cpy represent the coordinates of the current point, and cb represents the current bearing.
The following sections list the commands. Those that draw straight line segments include the lineto commands (L, l, H, h, V and v) and the close path commands (Z and z). These three groups of commands draw curves:
The "moveto" commands (M or m) establish a new current point. The effect is as if the "pen" were lifted and moved to a new location. A path data segment (if there is one) must begin with a "moveto" command. Subsequent "moveto" commands (i.e., when the "moveto" is not the first command) represent the start of a new subpath:
Command | Name | Parameters | Description |
---|---|---|---|
M (absolute) m (relative) |
moveto | (x y)+ | Start a new sub-path at the given (x,y) coordinates. M (uppercase) indicates that absolute coordinates will follow; m (lowercase) indicates that relative coordinates will follow. If a moveto is followed by multiple pairs of coordinates, the subsequent pairs are treated as implicit lineto commands. Hence, implicit lineto commands will be relative if the moveto is relative, and absolute if the moveto is absolute. If a relative moveto (m) appears as the first element of the path, then it is treated as a pair of absolute coordinates. In this case, subsequent pairs of coordinates are treated as relative even though the initial moveto is interpreted as an absolute moveto. |
When a relative m command is used, the position moved to is (cpx + x cos cb + y sin cb, cpy + x sin cb + y cos cb).
The "closepath" (Z or z) ends the current subpath by connecting it back to its initial point in either of two ways:
complete, that is that all the required coordinate data has been supplied, then an automatic straight line is drawn from the current point to the initial point of the current subpath. This path segment may be of zero length.
Examples:
SVG 2 adds the ability to fill in missing coordinate data with the Z or z command to avoid the need to add a zero length (or very short in the case of relative paths with rounding errors) path segment to close a subpath. This can effect the number of markers drawn and their orientation at the beginning/end of a closed subpath.
The use of Z or z to replace missing coordinate data with the coordinate of the initial point in a subpath was resolved at the Sydney (2015) meeting.
If a "closepath" is followed immediately by a "moveto", then the "moveto" identifies the start point of the next subpath. If a "closepath" is followed immediately by any other command, then the next subpath starts at the same initial point as the current subpath.
When a subpath ends in a "closepath," it differs in behavior
from what happens when "manually" closing a subpath via a
"lineto" command in how ‘stroke-linejoin
’
and ‘stroke-linecap
’ are implemented. With "closepath", the end of the final segment
of the subpath is "joined" with the start of the initial
segment of the subpath using the current value of ‘stroke-linejoin
’.
If you instead "manually" close the subpath via a "lineto"
command, the start of the first segment and the end of the last
segment are not joined but instead are each capped using the
current value of ‘stroke-linecap
’.
At the end of the command, the new current point is set to the
initial point of the current subpath.
The current bearing does not affect a z command.
Command | Name | Parameters | Description |
---|---|---|---|
Z or z |
closepath | (none) | Close the current subpath by connecting it back to the current subpath's initial point (see prose above). Since the Z and z commands take no parameters, they have an identical effect. |
The various "lineto" commands draw straight lines from the current point to a new point:
Command | Name | Parameters | Description |
---|---|---|---|
L (absolute) l (relative) |
lineto | (x y)+ | Draw a line from the current point to the given (x,y) coordinate which becomes the new current point. L (uppercase) indicates that absolute coordinates will follow; l (lowercase) indicates that relative coordinates will follow. A number of coordinates pairs may be specified to draw a polyline. At the end of the command, the new current point is set to the final set of coordinates provided. |
H (absolute) h (relative) |
horizontal lineto | x+ | Draws a horizontal line from the current point. H (uppercase) indicates that absolute coordinates will follow; h (lowercase) indicates that relative coordinates will follow. Multiple x values can be provided (although usually this doesn't make sense). An H or h command is equivalent to an L or l command with 0 specified for the y coordinate. At the end of the command, the new current point is taken from the final coordinate value. |
V (absolute) v (relative) |
vertical lineto | y+ | Draws a vertical line from the current point. V (uppercase) indicates that absolute coordinates will follow; v (lowercase) indicates that relative coordinates will follow. Multiple y values can be provided (although usually this doesn't make sense). A V or v command is equivalent to an L or l command with 0 specified for the x coordinate. At the end of the command, the new current point is taken from the final coordinate value. |
When a relative l command is used, the end point of the line is (cpx + x cos cb + y sin cb, cpy + x sin cb + y cos cb).
When a relative h command is used, the end point of the line is (cpx + x cos cb, cpy + x sin cb). This means that an h command with a positive x value draws a line in the direction of the current bearing. When the current bearing is 0, this is a horizontal line in the direction of the positive x-axis.
When there is a non-zero bearing, a mnemonic for the h command could be "head this distance at the current bearing", rather than "draw a horizontal line".
When a relative v command is used, the end point of the line is (cpx + y sin cb, cpy + y cos cb).
The cubic Bézier commands are as follows:
Command | Name | Parameters | Description |
---|---|---|---|
C (absolute) c (relative) |
curveto | (x1 y1 x2 y2 x y)+ | Draws a cubic Bézier curve from the current point to (x,y) using (x1,y1) as the control point at the beginning of the curve and (x2,y2) as the control point at the end of the curve. C (uppercase) indicates that absolute coordinates will follow; c (lowercase) indicates that relative coordinates will follow. Multiple sets of coordinates may be specified to draw a polybézier. At the end of the command, the new current point becomes the final (x,y) coordinate pair used in the polybézier. |
S (absolute) s (relative) |
shorthand/smooth curveto | (x2 y2 x y)+ | Draws a cubic Bézier curve from the current point to (x,y). The first control point is assumed to be the reflection of the second control point on the previous command relative to the current point. (If there is no previous command or if the previous command was not an C, c, S or s, assume the first control point is coincident with the current point.) (x2,y2) is the second control point (i.e., the control point at the end of the curve). S (uppercase) indicates that absolute coordinates will follow; s (lowercase) indicates that relative coordinates will follow. Multiple sets of coordinates may be specified to draw a polybézier. At the end of the command, the new current point becomes the final (x,y) coordinate pair used in the polybézier. |
When a relative c or s command is used, each of the relative coordinate pairs is computed as for those in an m command. For example, the final control point of the curve of both commands is (cpx + x cos cb + y sin cb, cpy + x sin cb + y cos cb).
Example cubic01 shows some simple uses of cubic Bézier commands within a path. The example uses an internal CSS style sheet to assign styling properties. Note that the control point for the "S" command is computed automatically as the reflection of the control point for the previous "C" command relative to the start point of the "S" command.
<?xml version="1.0" standalone="no"?> <svg width="5cm" height="4cm" viewBox="0 0 500 400" xmlns="http://www.w3.org/2000/svg" version="1.1"> <title>Example cubic01- cubic Bézier commands in path data</title> <desc>Picture showing a simple example of path data using both a "C" and an "S" command, along with annotations showing the control points and end points</desc> <style type="text/css"><![CDATA[ .Border { fill:none; stroke:blue; stroke-width:1 } .Connect { fill:none; stroke:#888888; stroke-width:2 } .SamplePath { fill:none; stroke:red; stroke-width:5 } .EndPoint { fill:none; stroke:#888888; stroke-width:2 } .CtlPoint { fill:#888888; stroke:none } .AutoCtlPoint { fill:none; stroke:blue; stroke-width:4 } .Label { font-size:22; font-family:Verdana } ]]></style> <rect class="Border" x="1" y="1" width="498" height="398" /> <polyline class="Connect" points="100,200 100,100" /> <polyline class="Connect" points="250,100 250,200" /> <polyline class="Connect" points="250,200 250,300" /> <polyline class="Connect" points="400,300 400,200" /> <path class="SamplePath" d="M100,200 C100,100 250,100 250,200 S400,300 400,200" /> <circle class="EndPoint" cx="100" cy="200" r="10" /> <circle class="EndPoint" cx="250" cy="200" r="10" /> <circle class="EndPoint" cx="400" cy="200" r="10" /> <circle class="CtlPoint" cx="100" cy="100" r="10" /> <circle class="CtlPoint" cx="250" cy="100" r="10" /> <circle class="CtlPoint" cx="400" cy="300" r="10" /> <circle class="AutoCtlPoint" cx="250" cy="300" r="9" /> <text class="Label" x="25" y="70">M100,200 C100,100 250,100 250,200</text> <text class="Label" x="325" y="350" style="text-anchor:middle">S400,300 400,200</text> </svg>
The following picture shows some how cubic Bézier curves change their shape depending on the position of the control points. The first five examples illustrate a single cubic Bézier path segment. The example at the lower right shows a "C" command followed by an "S" command.
View
this example as SVG (SVG-enabled browsers only)
The quadratic Bézier commands are as follows:
Command | Name | Parameters | Description |
---|---|---|---|
Q (absolute) q (relative) |
quadratic Bézier curveto | (x1 y1 x y)+ | Draws a quadratic Bézier curve from the current point to (x,y) using (x1,y1) as the control point. Q (uppercase) indicates that absolute coordinates will follow; q (lowercase) indicates that relative coordinates will follow. Multiple sets of coordinates may be specified to draw a polybézier. At the end of the command, the new current point becomes the final (x,y) coordinate pair used in the polybézier. |
T (absolute) t (relative) |
Shorthand/smooth quadratic Bézier curveto | (x y)+ | Draws a quadratic Bézier curve from the current point to (x,y). The control point is assumed to be the reflection of the control point on the previous command relative to the current point. (If there is no previous command or if the previous command was not a Q, q, T or t, assume the control point is coincident with the current point.) T (uppercase) indicates that absolute coordinates will follow; t (lowercase) indicates that relative coordinates will follow. At the end of the command, the new current point becomes the final (x,y) coordinate pair used in the polybézier. |
When a relative q or t command is used, each of the relative coordinate pairs is computed as for those in an m command. For example, the final control point of the curve of both commands is (cpx + x cos cb + y sin cb, cpy + x sin cb + y cos cb).
Example quad01 shows some simple uses of quadratic Bézier commands within a path. Note that the control point for the "T" command is computed automatically as the reflection of the control point for the previous "Q" command relative to the start point of the "T" command.
<?xml version="1.0" standalone="no"?> <svg width="12cm" height="6cm" viewBox="0 0 1200 600" xmlns="http://www.w3.org/2000/svg" version="1.1"> <title>Example quad01 - quadratic Bézier commands in path data</title> <desc>Picture showing a "Q" a "T" command, along with annotations showing the control points and end points</desc> <rect x="1" y="1" width="1198" height="598" fill="none" stroke="blue" stroke-width="1" /> <path d="M200,300 Q400,50 600,300 T1000,300" fill="none" stroke="red" stroke-width="5" /> <!-- End points --> <g fill="black" > <circle cx="200" cy="300" r="10"/> <circle cx="600" cy="300" r="10"/> <circle cx="1000" cy="300" r="10"/> </g> <!-- Control points and lines from end points to control points --> <g fill="#888888" > <circle cx="400" cy="50" r="10"/> <circle cx="800" cy="550" r="10"/> </g> <path d="M200,300 L400,50 L600,300 L800,550 L1000,300" fill="none" stroke="#888888" stroke-width="2" /> </svg>
SVG 2 Requirement: | Make it simpler to draw arcs in SVG path syntax. |
---|---|
Resolution: | Make arcs in paths easier. |
Purpose: | To make it easier for authors to write path data with arcs by hand. |
Owner: | Cameron (ACTION-3151) |
The elliptical arc commands are as follows:
Command | Name | Parameters | Description |
---|---|---|---|
A (absolute) a (relative) |
elliptical arc | (rx ry x-axis-rotation large-arc-flag sweep-flag x y)+ | Draws an elliptical arc from the current point to (x, y). The size and orientation of the ellipse are defined by two radii (rx, ry) and an x-axis-rotation, which indicates how the ellipse as a whole is rotated relative to the current coordinate system. The center (cx, cy) of the ellipse is calculated automatically to satisfy the constraints imposed by the other parameters. large-arc-flag and sweep-flag contribute to the automatic calculations and help determine how the arc is drawn. |
When a relative a command is used, the end point of the arc is (cpx + x cos cb + y sin cb, cpy + x sin cb + y cos cb). The effective value of the x-axis-rotation parameter is also affected by the current bearing: it is computed as x-axis-rotation + cb.
Example arcs01 shows some simple uses of arc commands within a path.
<?xml version="1.0" standalone="no"?> <svg width="12cm" height="5.25cm" viewBox="0 0 1200 400" xmlns="http://www.w3.org/2000/svg" version="1.1"> <title>Example arcs01 - arc commands in path data</title> <desc>Picture of a pie chart with two pie wedges and a picture of a line with arc blips</desc> <rect x="1" y="1" width="1198" height="398" fill="none" stroke="blue" stroke-width="1" /> <path d="M300,200 h-150 a150,150 0 1,0 150,-150 z" fill="red" stroke="blue" stroke-width="5" /> <path d="M275,175 v-150 a150,150 0 0,0 -150,150 z" fill="yellow" stroke="blue" stroke-width="5" /> <path d="M600,350 l 50,-25 a25,25 -30 0,1 50,-25 l 50,-25 a25,50 -30 0,1 50,-25 l 50,-25 a25,75 -30 0,1 50,-25 l 50,-25 a25,100 -30 0,1 50,-25 l 50,-25" fill="none" stroke="red" stroke-width="5" /> </svg>
The elliptical arc command draws a section of an ellipse which meets the following constraints:
For most situations, there are actually four different arcs (two different ellipses, each with two different arc sweeps) that satisfy these constraints. large-arc-flag and sweep-flag indicate which one of the four arcs are drawn, as follows:
The following illustrates the four combinations of large-arc-flag and sweep-flag and the four different arcs that will be drawn based on the values of these flags. For each case, the following path data command was used:
<path d="M 125,75 a100,50 0 ?,? 100,50" style="fill:none; stroke:red; stroke-width:6"/>
where "?,?" is replaced by "0,0" "0,1" "1,0" and "1,1" to generate the four possible cases.
View this example as SVG (SVG-enabled browsers only)
Refer to Elliptical arc implementation notes for detailed implementation notes for the path data elliptical arc commands.
Update for new 'Z'/'z' behavior.
SVG path data matches the following EBNF grammar.
svg-path: wsp* moveto-drawto-command-groups? wsp* moveto-drawto-command-groups: moveto-drawto-command-group | moveto-drawto-command-group wsp* moveto-drawto-command-groups moveto-drawto-command-group: moveto wsp* drawto-commands? drawto-commands: drawto-command | drawto-command wsp* drawto-commands drawto-command: closepath | lineto | horizontal-lineto | vertical-lineto | curveto | smooth-curveto | quadratic-bezier-curveto | smooth-quadratic-bezier-curveto | elliptical-arc | bearing moveto: ( "M" | "m" ) wsp* moveto-argument-sequence moveto-argument-sequence: coordinate-pair | coordinate-pair comma-wsp? lineto-argument-sequence closepath: ("Z" | "z") lineto: ( "L" | "l" ) wsp* lineto-argument-sequence lineto-argument-sequence: coordinate-pair | coordinate-pair comma-wsp? lineto-argument-sequence horizontal-lineto: ( "H" | "h" ) wsp* horizontal-lineto-argument-sequence horizontal-lineto-argument-sequence: coordinate | coordinate comma-wsp? horizontal-lineto-argument-sequence vertical-lineto: ( "V" | "v" ) wsp* vertical-lineto-argument-sequence vertical-lineto-argument-sequence: coordinate | coordinate comma-wsp? vertical-lineto-argument-sequence curveto: ( "C" | "c" ) wsp* curveto-argument-sequence curveto-argument-sequence: curveto-argument | curveto-argument comma-wsp? curveto-argument-sequence curveto-argument: coordinate-pair comma-wsp? coordinate-pair comma-wsp? coordinate-pair smooth-curveto: ( "S" | "s" ) wsp* smooth-curveto-argument-sequence smooth-curveto-argument-sequence: smooth-curveto-argument | smooth-curveto-argument comma-wsp? smooth-curveto-argument-sequence smooth-curveto-argument: coordinate-pair comma-wsp? coordinate-pair quadratic-bezier-curveto: ( "Q" | "q" ) wsp* quadratic-bezier-curveto-argument-sequence quadratic-bezier-curveto-argument-sequence: quadratic-bezier-curveto-argument | quadratic-bezier-curveto-argument comma-wsp? quadratic-bezier-curveto-argument-sequence quadratic-bezier-curveto-argument: coordinate-pair comma-wsp? coordinate-pair smooth-quadratic-bezier-curveto: ( "T" | "t" ) wsp* smooth-quadratic-bezier-curveto-argument-sequence smooth-quadratic-bezier-curveto-argument-sequence: coordinate-pair | coordinate-pair comma-wsp? smooth-quadratic-bezier-curveto-argument-sequence elliptical-arc: ( "A" | "a" ) wsp* elliptical-arc-argument-sequence elliptical-arc-argument-sequence: elliptical-arc-argument | elliptical-arc-argument comma-wsp? elliptical-arc-argument-sequence elliptical-arc-argument: number comma-wsp? number comma-wsp? number comma-wsp flag comma-wsp? flag comma-wsp? coordinate-pair bearing: ( "B" | "b" ) wsp* bearing-argument-sequence bearing-argument-sequence: number | number comma-wsp? bearing-argument-sequence coordinate-pair: coordinate comma-wsp? coordinate coordinate: number nonnegative-number: integer-constant | floating-point-constant number: sign? integer-constant | sign? floating-point-constant flag: "0" | "1" integer-constant: digit-sequence floating-point-constant: fractional-constant exponent? | digit-sequence exponent fractional-constant: digit-sequence? "." digit-sequence | digit-sequence "." exponent: ( "e" | "E" ) sign? digit-sequence sign: "+" | "-" digit-sequence: digit | digit digit-sequence digit: "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
The processing of the BNF must consume as much of a given BNF production as possible, stopping at the point when a character is encountered which no longer satisfies the production. Thus, in the string "M 100-200", the first coordinate for the "moveto" consumes the characters "100" and stops upon encountering the minus sign because the minus sign cannot follow a digit in the production of a "coordinate". The result is that the first coordinate will be "100" and the second coordinate will be "-200".
Similarly, for the string "M 0.6.5", the first coordinate of the "moveto" consumes the characters "0.6" and stops upon encountering the second decimal point because the production of a "coordinate" only allows one decimal point. The result is that the first coordinate will be "0.6" and the second coordinate will be ".5".
Note that the BNF allows the path ‘d’ attribute to be empty. This is not an error, instead it disables rendering of the path.
If path data not matching the grammar is encountered, then the path data is in error (see Error Handling).
A conforming SVG user agent must implement path rendering as follows:
stroke-linecap
’ has a value of
round or
square.(newx1, newy1) = (curx - (oldx2 - curx), cury - (oldy2 - cury)) = (2*curx - oldx2, 2*cury - oldy2)
Various operations, including text on a path and motion animation and various stroke operations, require that the user agent compute the distance along the geometry of a graphics element, such as a ‘path’.
Exact mathematics exist for computing distance along a path, but the formulas are highly complex and require substantial computation. It is recommended that authoring products and user agents employ algorithms that produce as precise results as possible; however, to accommodate implementation differences and to help distance calculations produce results that approximate author intent, the ‘pathLength’ attribute can be used to provide the author's computation of the total length of the path so that the user agent can scale distance-along-a-path computations by the ratio of ‘pathLength’ to the user agent's own computed value for total path length.
A "moveto" or "bearing" operation within a ‘path’ element is defined to have zero length. Only the various "lineto", "curveto" and "arcto" commands contribute to path length calculations.
interface SVGPathElement : SVGGeometryElement { readonly attribute SVGAnimatedNumber pathLength; float getTotalLength(); DOMPoint getPointAtLength(float distance); };
If no valid path data exists, returns (0,0).
SVG contains the following set of basic shape elements:
Mathematically, these shape elements are equivalent to a ‘path’ element that would construct the same shape. The basic shapes may be stroked, filled and used as clip paths. All of the properties available for ‘path’ elements also apply to the basic shapes.
The equivalent path and algorithm to compute the stroke for each shape are defined in the shape sections below.
The ‘rect’ element defines a rectangle which is axis-aligned
with the current local coordinate system. Rounded rectangles can be achieved by setting
appropriate values for attributes ‘rx
’ and ‘ry
’.
The ‘x
’ and ‘y
’ coordinates refer to the left and top edges of the rectangle,
in the current user coordinate system.
The ‘width
’ and ‘height
’ of the rectangle. A negative value for either
attribute is an error (see Error processing).
A value of zero for either attribute disables rendering of the element.
For rounded rectangles, the x- and y-axis radii of the ellipse used to round off the corners of the rectangle. A negative value for either attribute is an error (see Error processing).
The values used for the x- and y-axis rounded corner radii are
determined implicitly if the ‘rx
’ or ‘ry
’ attributes (or both)
are not specified, or are specified but with invalid values.
The values are also subject to clamping so that the lengths of
the straight segments of the rectangle are never negative. The
effective values for ‘rx
’ and ‘ry
’ are determined by following
these steps in order:
rx
’ nor ‘ry
’ are properly specified, then set both
rx and ry to 0. (This will result in square corners.)rx
’, but
not for ‘ry
’, then set both rx and ry to the value of ‘rx
’.ry
’, but
not for ‘rx
’, then set both rx and ry to the value of ‘ry
’.rx
’ and ‘ry
’ were specified properly. Set rx to
the value of ‘rx
’ and ry to the value of ‘ry
’.width
’, then set
rx to half of ‘width
’.height
’, then set
ry to half of ‘height
’.rx
’ and ‘ry
’ are rx and
ry, respectively.Mathematically, a ‘rect’ element is mapped to an equivalent ‘path’ element as follows: (Note: all coordinate and length values are first converted into local coordinate system coordinates according to Units.)
x
’ attribute converted to user
space, rx is the effective value of the ‘rx
’ attribute
converted to local coordinate system and y is the value of the ‘y
’
attribute converted to local coordinate systemwidth
’ attribute converted to user
spacerx
’ and ‘ry
’ attributes on the ‘rect’
element converted to local coordinate system are used as the rx and ry
attributes on the elliptical arc
command, respectively, the x-axis-rotation is set to zero, the
large-arc-flag is set to zero, and the sweep-flag is set
to oneheight
’ attribute converted to user
spacePath decomposition resolved during teleconference on June 3rd, 2013.
Example rect01 shows a rectangle with sharp corners. The ‘rect’ element is filled with yellow and stroked with navy.
<?xml version="1.0" standalone="no"?> <svg width="12cm" height="4cm" viewBox="0 0 1200 400" xmlns="http://www.w3.org/2000/svg" version="1.1"> <desc>Example rect01 - rectangle with sharp corners</desc> <!-- Show outline of canvas using 'rect' element --> <rect x="1" y="1" width="1198" height="398" fill="none" stroke="blue" stroke-width="2"/> <rect x="400" y="100" width="400" height="200" fill="yellow" stroke="navy" stroke-width="10" /> </svg>
Example rect02 shows
two rounded rectangles. The ‘rx
’ specifies how to round the corners of
the rectangles. Note that since no value has been specified for the ‘ry
’
attribute, it will be assigned the same value as the ‘rx
’ attribute.
<?xml version="1.0" standalone="no"?> <svg width="12cm" height="4cm" viewBox="0 0 1200 400" xmlns="http://www.w3.org/2000/svg" version="1.1"> <desc>Example rect02 - rounded rectangles</desc> <!-- Show outline of canvas using 'rect' element --> <rect x="1" y="1" width="1198" height="398" fill="none" stroke="blue" stroke-width="2"/> <rect x="100" y="100" width="400" height="200" rx="50" fill="green" /> <g transform="translate(700 210) rotate(-30)"> <rect x="0" y="0" width="400" height="200" rx="50" fill="none" stroke="purple" stroke-width="30" /> </g> </svg>
The ‘circle’ element defines a circle based on a center point and a radius.
The ‘cx
’ and ‘cy
’ attributes define the coordinates of the center of the circle.
The ‘r
’ attribute defines the radius of the circle. A negative value
is an error (see Error processing).
A value of zero disables rendering of the element.
Mathematically, a ‘circle’ element is mapped to an equivalent ‘path’ element that consists of four elliptical arc segments, each covering a quarter of the circle. The path begins at the "3 o'clock" point on the radius and proceeds in a clock-wise direction (before any transformations).
Path decomposition resolved during teleconference on June 3rd, 2013.
Example circle01 consists of a ‘circle’ element that is filled with red and stroked with blue.
<?xml version="1.0" standalone="no"?> <svg width="12cm" height="4cm" viewBox="0 0 1200 400" xmlns="http://www.w3.org/2000/svg" version="1.1"> <desc>Example circle01 - circle filled with red and stroked with blue</desc> <!-- Show outline of canvas using 'rect' element --> <rect x="1" y="1" width="1198" height="398" fill="none" stroke="blue" stroke-width="2"/> <circle cx="600" cy="200" r="100" fill="red" stroke="blue" stroke-width="10" /> </svg>
The ‘ellipse’ element defines an ellipse which is axis-aligned with the current local coordinate system based on a center point and two radii.
The ‘cx
’ and ‘cy
’ coordinates define the center of the ellipse.
The ‘cx
’ and ‘cy
’ attributes define the x- and y-axis radii of the
ellipse. A negative value for either attribute is an error (see
Error processing).
A value of zero disables rendering of the element.
Mathematically, an ‘ellipse’ element is mapped to an equivalent ‘path’ element that consists of four elliptical arc segments, each covering a quarter of the ellipse. The path begins at the "3 o'clock" point on the radius and proceeds in a clock-wise direction (before any transformation).
Path decomposition resolved during teleconference on June 3rd, 2013.
Example ellipse01 below specifies
the coordinates of the two ellipses in the user coordinate system
established by the ‘viewBox’ attribute on the ‘svg’
element and the ‘transform
’ property on the ‘g’ and
‘ellipse’ elements. Both ellipses use the default values of
zero for the ‘cx
’ and ‘cy
’ attributes (the center of the
ellipse). The second ellipse is rotated.
<?xml version="1.0" standalone="no"?> <svg width="12cm" height="4cm" viewBox="0 0 1200 400" xmlns="http://www.w3.org/2000/svg" version="1.1"> <desc>Example ellipse01 - examples of ellipses</desc> <!-- Show outline of canvas using 'rect' element --> <rect x="1" y="1" width="1198" height="398" fill="none" stroke="blue" stroke-width="2" /> <g transform="translate(300 200)"> <ellipse rx="250" ry="100" fill="red" /> </g> <ellipse transform="translate(900 200) rotate(-30)" rx="250" ry="100" fill="none" stroke="blue" stroke-width="20" /> </svg>
The ‘line’ element defines a line segment that starts at one point and ends at another.
Attribute definitions:
Name | Value | Initial value | Animatable |
---|---|---|---|
x1, y1 | <length> | <percentage> | <number> | 0 | yes |
Name | Value | Initial value | Animatable |
---|---|---|---|
x2, y2 | <length> | <percentage> | <number> | 0 | yes |
Mathematically, a ‘line’ element can be mapped to an equivalent ‘path’ element as follows: (Note: all coordinate and length values are first converted into local coordinate system coordinates according to Units.)
Because ‘line’ elements are single lines and thus are geometrically
one-dimensional, they have no interior; thus, ‘line’ elements are never
filled (see the ‘fill
’ property).
Example line01 below specifies the coordinates of the five lines in the user coordinate system established by the ‘viewBox’ attribute on the ‘svg’ element. The lines have different thicknesses.
<?xml version="1.0" standalone="no"?> <svg width="12cm" height="4cm" viewBox="0 0 1200 400" xmlns="http://www.w3.org/2000/svg" version="1.1"> <desc>Example line01 - lines expressed in user coordinates</desc> <!-- Show outline of canvas using 'rect' element --> <rect x="1" y="1" width="1198" height="398" fill="none" stroke="blue" stroke-width="2" /> <g stroke="green" > <line x1="100" y1="300" x2="300" y2="100" stroke-width="5" /> <line x1="300" y1="300" x2="500" y2="100" stroke-width="10" /> <line x1="500" y1="300" x2="700" y2="100" stroke-width="15" /> <line x1="700" y1="300" x2="900" y2="100" stroke-width="20" /> <line x1="900" y1="300" x2="1100" y2="100" stroke-width="25" /> </g> </svg>
The ‘polyline’ element defines a set of connected straight line segments. Typically, ‘polyline’ elements define open shapes.
Attribute definitions:
Name | Value | Initial value | Animatable |
---|---|---|---|
points | <points> | (none) | yes |
where:
The points that make up the polyline. All coordinate values are in the user coordinate system.
If an odd number of coordinates is provided, then the element is in error, with the same user agent behavior as occurs with an incorrectly specified ‘path’ element. In such error cases the user agent will drop the last, odd coordinate and otherwise render the shape.
The initial value, (none), indicates that the polyline element is valid but does not render.
Mathematically, a ‘polyline’ element can be mapped to an equivalent ‘path’ element as follows:
Example polyline01 below specifies a polyline in the user coordinate system established by the ‘viewBox’ attribute on the ‘svg’ element.
<?xml version="1.0" standalone="no"?> <svg width="12cm" height="4cm" viewBox="0 0 1200 400" xmlns="http://www.w3.org/2000/svg" version="1.1"> <desc>Example polyline01 - increasingly larger bars</desc> <!-- Show outline of canvas using 'rect' element --> <rect x="1" y="1" width="1198" height="398" fill="none" stroke="blue" stroke-width="2" /> <polyline fill="none" stroke="blue" stroke-width="10" points="50,375 150,375 150,325 250,325 250,375 350,375 350,250 450,250 450,375 550,375 550,175 650,175 650,375 750,375 750,100 850,100 850,375 950,375 950,25 1050,25 1050,375 1150,375" /> </svg>
The ‘polygon’ element defines a closed shape consisting of a set of connected straight line segments.
Attribute definitions:
Name | Value | Initial value | Animatable |
---|---|---|---|
points | <points> | (none) | yes |
The points that make up the polygon. All coordinate values are in the user coordinate system.
If an odd number of coordinates is provided, then the element is in error, with the same user agent behavior as occurs with an incorrectly specified ‘path’ element.
The initial value, (none), indicates that the polygon element is valid, but does not render.
Mathematically, a ‘polygon’ element can be mapped to an equivalent ‘path’ element as follows:
Example polygon01 below specifies two polygons (a star and a hexagon) in the user coordinate system established by the ‘viewBox’ attribute on the ‘svg’ element.
<?xml version="1.0" standalone="no"?> <svg width="12cm" height="4cm" viewBox="0 0 1200 400" xmlns="http://www.w3.org/2000/svg" version="1.1"> <desc>Example polygon01 - star and hexagon</desc> <!-- Show outline of canvas using 'rect' element --> <rect x="1" y="1" width="1198" height="398" fill="none" stroke="blue" stroke-width="2" /> <polygon fill="red" stroke="blue" stroke-width="10" points="350,75 379,161 469,161 397,215 423,301 350,250 277,301 303,215 231,161 321,161" /> <polygon fill="lime" stroke="blue" stroke-width="10" points="850,75 958,137.5 958,262.5 850,325 742,262.6 742,137.5" /> </svg>
interface SVGRectElement : SVGGeometryElement { readonly attribute SVGAnimatedLength x; readonly attribute SVGAnimatedLength y; readonly attribute SVGAnimatedLength width; readonly attribute SVGAnimatedLength height; readonly attribute SVGAnimatedLength rx; readonly attribute SVGAnimatedLength ry; };
interface SVGCircleElement : SVGGeometryElement { readonly attribute SVGAnimatedLength cx; readonly attribute SVGAnimatedLength cy; readonly attribute SVGAnimatedLength r; };
interface SVGEllipseElement : SVGGeometryElement { readonly attribute SVGAnimatedLength cx; readonly attribute SVGAnimatedLength cy; readonly attribute SVGAnimatedLength rx; readonly attribute SVGAnimatedLength ry; };
interface SVGLineElement : SVGGeometryElement { readonly attribute SVGAnimatedLength x1; readonly attribute SVGAnimatedLength y1; readonly attribute SVGAnimatedLength x2; readonly attribute SVGAnimatedLength y2; };
The SVGAnimatedPoints interface supports elements which have a ‘points’ attribute which holds a list of coordinate values and which support the ability to animate that attribute.
Additionally, the ‘points’ attribute on
the original element accessed via the XML DOM (e.g., using the
getAttribute()
method call) will reflect any changes made to
points.
[NoInterfaceObject] interface SVGAnimatedPoints { readonly attribute SVGPointList points; readonly attribute SVGPointList animatedPoints; };
This interface defines a list of DOMPoint objects.
SVGPointList has the same attributes and methods as other SVGxxxList interfaces. Implementers may consider using a single base class to implement the various SVGxxxList interfaces.
The supported property indices of an SVGPointList object is all non-negative integers less than the length of the list.
interface SVGPointList { readonly attribute unsigned long length; readonly attribute unsigned long numberOfItems; void clear(); DOMPoint initialize(DOMPoint newItem); getter DOMPoint getItem(unsigned long index); DOMPoint insertItemBefore(DOMPoint newItem, unsigned long index); DOMPoint replaceItem(DOMPoint newItem, unsigned long index); DOMPoint removeItem(unsigned long index); DOMPoint appendItem(DOMPoint newItem); setter void (unsigned long index, DOMPoint newItem); };
The SVGPolylineElement interface corresponds to the ‘polyline’ element.
interface SVGPolylineElement : SVGGeometryElement { }; SVGPolylineElement implements SVGAnimatedPoints;
The SVGPolygonElement interface corresponds to the ‘polygon’ element.
interface SVGPolygonElement : SVGGeometryElement { }; SVGPolygonElement implements SVGAnimatedPoints;
Text that is to be rendered as part of an SVG document fragment is specified using the ‘text’ element. The characters to be drawn are expressed as XML character data ([XML10], section 2.4) inside the ‘text’ element.
Each ‘text’ element causes a section of text to be rendered. The text can be rendered:
The section Text layout gives an introduction to text layout. It is followed by sections covering content areas, writing directions and general glyph positioning. The specialized layout rules corresponding to text that is pre-formatted, auto-wrapped, and on a path are then addressed in individual sections.
Rules for text layout in SVG 1.1 are mostly defined within the SVG 1.1 specification. The rules mirror to a large extent those found in CSS. In SVG 2, the dependence on CSS is more explicit. In practice the end layout is the same. The change to directly relying on CSS specifications simplifies the SVG specification while making it more obvious that rendering agents can use the same code to both render text in HTML and in SVG. In particular, SVG 2 auto-wrapped text is based on CSS text layout.
SVG's ‘text’ elements are rendered like other graphics elements. Thus, coordinate system transformations, painting, clipping and masking features apply to ‘text’ elements in the same way as they apply to shapes such as paths and rectangles.
SVG text supports advanced typographic features including:
SVG text supports international text processing needs such as:
Multi-language SVG content is possible by substituting different text strings based on the user's preferred language.
Because SVG text is packaged as XML character data:
For accessibility reasons, it is recommended that text which is included in a document have appropriate semantic markup to indicate its function. See SVG accessibility guidelines for more information.
A font consists of a collection of glyphs together with other information (collectively, the font tables) necessary to use those glyphs to present characters on some visual medium. The combination of the collection of glyphs and the font tables is called the font data. The font tables include the information necessary to map characters to glyphs, to determine the size of glyph areas and to position the glyph area. Each font table consists of one or more font characteristics, such as the font-weight and font-style.
SVG 2 Requirement: | Include explicit support for Web Open Font Format (WOFF). |
---|---|
Resolution: | We will mandate WOFF support in SVG 2. |
Purpose: | To allow access to full OpenType features for internationalisation and advanced typography. |
Owner: | Chris (no action) |
SVG requires support for downloadable fonts as defined in the Font Resources section of the CSS Fonts Module. In particular, support for the Web Open Font Format [WOFF] is required.
New in SVG 2. WOFF allows authors to provide the fonts needed to properly render their content. This includes ensuring that the fonts have the proper OpenType tables to support complex scripts, discretionary ligatures, swashes, old-style numbers, and so on. WOFF also allows the fonts to be compressed, subsetted, and include licensing information.
The geometric font characteristics are expressed in a coordinate system based on the EM box. (The EM is a relative measure of the height of the glyphs in the font.) The box 1 EM high and 1 EM wide is called the design space. This space is given a geometric coordinates by sub-dividing the EM into a number of units per em.
Units per em is a font characteristic. A typical value for units per em is 1000 or 2048.
The coordinate space of the EM box is called the design space coordinate system. For scalable fonts, the curves and lines that are used to draw a glyph are represented using this coordinate system.
Most often, the (0,0) point in this coordinate system is positioned on the left edge of the EM box, but not at the bottom left corner. The Y coordinate of the bottom of a roman capital letter is usually zero. And the descenders on lowercase roman letters have negative coordinate values.
SVG assumes that the font tables will provide at least three font characteristics: an ascent, a descent and a set of baseline-tables. The ascent is the distance to the top of the EM box from the (0,0) point of the font; the descent is the distance to the bottom of the EM box from the (0.0) point of the font. The baseline-table is explained below.
Within an OpenType font, for horizontal writing-modes, the ascent and descent are given by the sTypoAscender and sTypoDescender entries in the OS/2 table. For vertical writing-modes, the descent (the distance, in this case from the (0,0) point to the left edge of the glyph) is normally zero because the (0,0) point is on the left edge. The ascent for vertical writing-modes is either 1 em or is specified by the ideographic top baseline value in the OpenType Base table for vertical writing-modes.
SVG 2 Requirement: | Support text aligned to different baselines. |
---|---|
Resolution: | SVG 2 will support glyphs being aligned to different baselines, perhaps by using existing or improved CSS properties. |
Purpose: | To allow glyphs in horizontal text to have different vertical alignments for stylistic effects. |
Owner: | Chris (no action) |
In horizontal writing-modes, the glyphs of a given script are positioned so that a particular point on each glyph, the alignment-point, is aligned with the alignment-points of the other glyphs in that script. The glyphs of different scripts, for example, Western, Northern Indic and Far-Eastern scripts, are typically aligned at different points on the glyph. For example, Western glyphs are aligned on the bottoms of the capital letters, northern indic glyphs are aligned at the top of a horizontal stroke near the top of the glyphs and far-eastern glyphs are aligned either at the bottom or center of the glyph. Within a script and within a line of text having a single font-size, the sequence of alignment-points defines, in the inline- progression-direction, a geometric line called a baseline. Western and most other alphabetic and syllabic glyphs are aligned to an "alphabetic" baseline, the northern indic glyphs are aligned to a "hanging" baseline and the far-eastern glyphs are aligned to an "ideographic" baseline.
A baseline-table specifies the position of one or more baselines in the design space coordinate system. The function of the baseline table is to facilitate the alignment of different scripts with respect to each other when they are mixed on the same text line. Because the desired relative alignments may depend on which script is dominant in a line (or block), there may be a different baseline table for each script. In addition, different alignment positions are needed for horizontal and vertical writing modes. Therefore, the font may have a set of baseline tables: typically, one or more for horizontal writing-modes and zero or more for vertical writing-modes.
Some fonts may not have values for the baseline tables. Heuristics are suggested for approximating the baseline tables when a given font does not supply baseline tables.
SVG further assumes that for each glyph in the font data for a font, there are two width values, two alignment-baselines and two alignment-points, one each for horizontal writing-modes and the other for vertical writing-modes. (Even though it is specified as a width, for vertical writing-modes the width is used in the vertical direction.) The script to which a glyph belongs determines an alignment-baseline to which the glyph is to be aligned. The inline-progression-direction position of the alignment-point is on the start-edge of the glyph.
Properties related to baselines are described below under Baseline alignment properties. Additional information on baselines can be found in the CSS Inline Layout Module Level 3 specification. Update to www.w3.org/TR when available. [CSS3INLINE] (Also see: CSS Writing Modes Level 3 specification. [CSSWRITINGMODES3])
In addition to the font characteristics required above, a font may also supply substitution and positioning tables that can be used by a formatter to re-order, combine and position a sequence of glyphs to make one or more composite glyphs. The combination may be as simple as a ligature, or as complex as an indic syllable which combines, usually with some re-ordering, multiple consonants and vowel glyphs.
The ‘text’ element defines a graphics element consisting of text. The ‘tspan’ element within a ‘text’ or another ‘tspan’ element, allows one to switch the style and/or adjust the position of the rendered text inside the ‘tspan’ element relative to the parent element.
The XML character data within the ‘text’ and ‘tspan’ elements, along with relevant attributes and properties, and character-to-glyph mapping tables within the font itself, define the glyphs to be rendered. The attributes and properties on the ‘text’ and ‘tspan’ elements indicate such things as the writing direction, font specification, and painting attributes which describe how exactly to render the characters. Subsequent sections of this chapter describe the relevant text-specific attributes and properties, particular text layout and bidirectionality.
Since ‘text’ and ‘tspan’ elements are rendered using the same rendering methods as other graphics elements, all of the same coordinate system transformations, and painting features that apply to shapes such as paths and rectangles also apply to ‘text’ and ‘tspan’ elements. In addition, clipping, and masking can be applied to the ‘text’ element as a whole.
It is possible to apply a gradient, pattern, clipping path, mask or filter to text. When one of these facilities is applied to text and keyword 'objectBoundingBox' is used (see Object bounding box units) to specify a graphical effect relative to the "object bounding box", then the object bounding box units are computed relative to the entire ‘text’ element in all cases, even when different effects are applied to different ‘tspan’ elements within the same ‘text’ element.
The ‘text’ element renders its first glyph (after
bidirectionality
reordering) at the initial current text position (with
possible adjustments due to the value of the
‘text-anchor
’ property or the ‘text-align
’ property).
For pre-formatted text and for auto-wrapped text where the
content area is determined by the ‘inline-size
’
property, the initial current text position is determined by the ‘x’ and
‘y’ values of the ‘text’ or ‘tspan’
element which contains the first rendered character.
For auto-wrapped text in a shape or text on a path see
the Auto-wrapped text or
Text on a path sections,
respectively, to determine the initial current text position.
After the glyph(s) corresponding to the given character is (are)
rendered, the current text position is updated for the next
character. In the simplest case, the new current text position is
the previous current text position plus the glyphs' advance value
(horizontal or vertical). See
text layout for a description
of glyph placement and glyph advance.
The text string Hello, out there!
is rendered onto the
canvas using the Verdana font family with the glyphs filled
with the color blue.
<?xml version="1.0" standalone="no"?> <svg width="10cm" height="3cm" viewBox="0 0 1000 300" xmlns="http://www.w3.org/2000/svg" version="1.1"> <text x="250" y="180" font-family="Verdana" font-size="64" fill="blue" > Hello, out there! </text> </svg>
A ‘tspan’ is used to change the styling of the word not
.
<?xml version="1.0" standalone="no"?> <svg width="10cm" height="3cm" viewBox="0 0 1000 300" xmlns="http://www.w3.org/2000/svg" version="1.1"> <g font-family="Verdana" font-size="64" > <text x="160" y="180" fill="blue" > You are <tspan font-weight="bold" fill="red" >not</tspan> a banana. </text> </g> </svg>
Two ‘tspan’ elements are repositioned horizontally and vertically using the ‘x’ and ‘y’ attributes. Because all the text is within a single ‘text’ element, a user will be able to select through all the text and copy it to the system clipboard in user agents that support text selection and clipboard operations.
<?xml version="1.0" standalone="no"?> <svg width="10cm" height="3cm" viewBox="0 0 1000 300" xmlns="http://www.w3.org/2000/svg" version="1.1"> <g font-family="Verdana" font-size="64" > <text x="100" y="180" fill="blue" > But you <tspan dx="2em" dy="-50" font-weight="bold" fill="red" > are </tspan> <tspan dy="100"> a peach! </tspan> </text> </g> </svg>
SVG 2 Requirement: | Allow transforms on ‘tspan’. |
---|---|
Resolution: | SVG 2 will allow transforms on ‘tspan’. |
Purpose: | Align with other elements such as ‘a’ which already allow transforms. |
Owner: | Cameron (no action) |
Name | Value | Initial value | Animatable |
---|---|---|---|
x, y | [<length> | <percentage> | <number>]#+ ,? | 0 | yes |
If a single <length> is provided, then the value represents the new absolute X (Y) coordinate for the current text position for rendering the glyphs that correspond to the first character within this element or any of its descendants.
If a comma- or space-separated list of n <length>s is provided, then the values represent new absolute X (Y) coordinates for the current text position for rendering the glyphs corresponding to each of the first n characters within this element or any of its descendants.
If more <length>s are provided than characters, then the extra <length>s will have no effect on glyph positioning.
If more characters exist than <length>s, then for each of these extra characters: (a) if an ancestor ‘text’ or ‘tspan’ element specifies an absolute X (Y) coordinate for the given character via an ‘x’ (‘y’) attribute, then that absolute X (Y) coordinate is used as the starting X (Y) coordinate for that character (nearest ancestor has precedence), else (b) the starting X (Y) coordinate for rendering the glyphs corresponding to the given character is the X (Y) coordinate of the resulting current text position from the most recently rendered glyph for the current ‘text’ element.
If the attribute is not specified: (a) if an ancestor ‘text’ or ‘tspan’ element specifies an absolute X (Y) coordinate for a given character via an ‘x’ (‘y’) attribute, then that absolute X (Y) coordinate is used (nearest ancestor has precedence), else (b) the starting X (Y) coordinate for rendering the glyphs corresponding to a given character is the X (Y) coordinate of the resulting current text position from the most recently rendered glyph for the current ‘text’ element.
In SVG 2, the ‘text’ and ‘tspan’ ‘x’ and ‘y’ attributes are not presentation attributes and cannot be set via CSS. This may change in a future version of SVG.
Name | Value | Initial value | Animatable |
---|---|---|---|
dx, dy | [<length> | <percentage> | <number>]#+ ,? | See below | yes |
If a single <length> is provided, this value represents the new relative X (Y) coordinate for the current text position for rendering the glyphs corresponding to the first character within this element or any of its descendants. The current text position is shifted along the x-axis (y-axis) of the current user coordinate system by <length> before the first character's glyphs are rendered.
If a comma- or space-separated list of n <length>s is provided, then the values represent incremental shifts along the x-axis (y-axis) for the current text position before rendering the glyphs corresponding to the first n characters within this element or any of its descendants. Thus, before the glyphs are rendered corresponding to each character, the current text position resulting from drawing the glyphs for the previous character within the current ‘text’ element is shifted along the x-axis (y-axis) of the current user coordinate system by <length>.
If more <length>s are provided than characters, then any extra <length>s will have no effect on glyph positioning.
If more characters exist than <length>s, then for each of these extra characters: (a) if an ancestor ‘text’ or ‘tspan’ element specifies a relative X (Y) coordinate for the given character via a ‘dx’ (‘dy’) attribute, then the current text position is shifted along the x-axis (y-axis) of the current user coordinate system by that amount (nearest ancestor has precedence), else (b) no extra shift along the x-axis (y-axis) occurs.
If the attribute is not specified: (a) if an ancestor ‘text’ or ‘tspan’ element specifies a relative X (Y) coordinate for a given character via a ‘dx’ (‘dy’) attribute, then the current text position is shifted along the x-axis (y-axis) of the current user coordinate system by that amount (nearest ancestor has precedence), else (b) no extra shift along the x-axis (y-axis) occurs.
Name | Value | Initial value | Animatable |
---|---|---|---|
rotate | <number>#+ ,? | See below | yes (non-additive). |
The supplemental rotation about the current text position that will be applied to all of the glyphs corresponding to each character within this element.
If a comma- or space-separated list of <number>s is provided, then the first <number> represents the supplemental rotation for the glyphs corresponding to the first character within this element or any of its descendants, the second <number> represents the supplemental rotation for the glyphs that correspond to the second character, and so on.
If more <number>s are provided than there are characters, then the extra <number>s will be ignored.
If more characters are provided than <number>s, then for each of these extra characters the rotation value specified by the last number must be used.
If the attribute is not specified and if an ancestor of a ‘tspan’ element specifies a supplemental rotation for a given character via a ‘rotate’ attribute, then the given supplemental rotation is applied to the given character (nearest ancestor has precedence). If there are more characters than <number>s specified in the ancestor's ‘rotate’ attribute, then for each of these extra characters the rotation value specified by the last number must be used.
This supplemental rotation has no impact on the rules by
which current text position is modified as glyphs get
rendered and is supplemental to any rotation due to
text on a path and
to ‘glyph-orientation-horizontal
’
or ‘glyph-orientation-vertical
’.
Name | Value | Initial value | Animatable |
---|---|---|---|
textLength | <length> | <percentage> | <number> | See below | yes |
The author's computation of the total sum of all of the
advance values that correspond to character data within this
element, including the advance value on the glyph (horizontal
or vertical), the effect of properties ‘letter-spacing
’
and ‘word-spacing
’ and adjustments due to attributes
‘dx’ and ‘dy’ on this ‘text’
or ‘tspan’ element or any descendants. This value is
used to calibrate the user agent's own calculations with that
of the author.
The purpose of this attribute is to allow the author to achieve exact alignment, in visual rendering order after any bidirectional reordering, for the first and last rendered glyphs that correspond to this element; thus, for the last rendered character (in visual rendering order after any bidirectional reordering), any supplemental inter-character spacing beyond normal glyph advances are ignored (in most cases) when the user agent determines the appropriate amount to expand/compress the text string to fit within a length of ‘textLength’.
If attribute ‘textLength’ is specified on a given element and also specified on an ancestor, the adjustments on all character data within this element are controlled by the value of ‘textLength’ on this element exclusively, with the possible side-effect that the adjustment ratio for the contents of this element might be different than the adjustment ratio used for other content that shares the same ancestor. The user agent must assume that the total advance values for the other content within that ancestor is the difference between the advance value on that ancestor and the advance value for this element.
This attribute is not intended for use to obtain effects such as shrinking or expanding text.
A negative value is an error (see Error processing).
If the attribute is not specified anywhere within a ‘text’ element, the effect is as if the author's computation exactly matched the value calculated by the user agent; thus, no advance adjustments are made.
Name | Value | Initial value | Animatable |
---|---|---|---|
lengthAdjust | spacing | spacingAndGlyphs | spacing | yes |
The user agent is required to achieve correct start and end positions for the text strings, but the locations of intermediate glyphs are not predictable because user agents might employ advanced algorithms to stretch or compress text strings in order to balance correct start and end positioning with optimal typography.
Note that, for a text string that contains n characters, the adjustments to the advance values often occur only for n−1 characters (see description of attribute ‘textLength’), whereas stretching or compressing of the glyphs will be applied to all n characters.
The ‘x’, ‘y’, ‘dx’, ‘dy’, and
‘rotate’ on the ‘tspan’ element are useful in
high-end typography scenarios where individual glyphs require
exact placement. These attributes are useful for minor positioning
adjustments between characters or for major positioning
adjustments, such as moving a section of text to a new location to
achieve the visual effect of a new line of text (compatable with
SVG 1.1). Note that the ‘x’, ‘y’, ‘dx’,
‘dy’, and ‘rotate’ attributes are
ignored for auto-wrapped text (except for the initial current text position when the content area is specified by
the ‘inline-size
’ property).
It was decided at the 2015 Sydney F2F that 'dx', 'dy', and 'rotate' would be ignored for auto-wrapped text. (Technically, it is not difficult to apply them but it was not seen as being really useful.)
In situations where micro-level positioning adjustment are necessary for advanced typographic control, the SVG content designer needs to ensure that the necessary font will be available for all viewers of the document (e.g., package up the necessary font data in the form of an SVG font or an alternative WebFont format which is stored at the same Web site as the SVG content) and that the viewing software will process the font in the expected way (the capabilities, characteristics and font layout mechanisms vary greatly from system to system). If the SVG content contains ‘x’, ‘y’, ‘dx’, or ‘dy’ attribute values which are meant to correspond to a particular font processed by a particular set of viewing software and either of these requirements is not met, then the text might display with poor quality.
The following additional rules apply to attributes ‘x’, ‘y’, ‘dx’, ‘dy’, and ‘rotate’ when they contain a list of numbers:
<tspan dx="11 12 13 14 15 0 21 22 23 0 31 32 33 34 35 36">Latin and Hebrew</tspan>and that the word "Hebrew" will be drawn right-to-left. First, the character data and the corresponding values in the ‘dx’ list will be reordered, such that the text string will be "Latin and werbeH" and the list of values for the ‘dx’ attribute will be "11 12 13 14 15 0 21 22 23 0 36 35 34 33 32 31". After this re-ordering, the glyphs corresponding to the characters will be positioned using standard left-to-right layout rules.
Example tspan04 uses the ‘rotate’ attribute on the ‘tspan’ element to rotate the glyphs to be rendered. This example shows a single text string in a ‘tspan’ element that contains more characters than the number of values specified in the ‘rotate’ attribute. In this case the last value specified in the ‘rotate’ attribute of the ‘tspan’ must be applied to the remaining characters in the string.
<?xml version="1.0" standalone="no"?> <svg width="10cm" height="3cm" viewBox="0 0 1000 300" xmlns="http://www.w3.org/2000/svg" version="1.1"> <desc> Example tspan04 - The number of rotate values is less than the number of characters in the string. </desc> <text font-family="Verdana" font-size="55" fill="blue" > <tspan x="250" y="150" rotate="-30,0,30"> Hello, out there </tspan> </text> <!-- Show outline of canvas using 'rect' element --> <rect x="1" y="1" width="998" height="298" fill="none" stroke="blue" stroke-width="2" /> </svg>
Example tspan05 specifies the ‘rotate’ attribute on the ‘text’ element and on all but one of the child ‘tspan’ elements to rotate the glyphs to be rendered. The example demonstrates the propagation of the ‘rotate’ attribute.
<?xml version="1.0" standalone="no"?> <svg width="100%" height="100%" viewBox="0 0 500 120" xmlns="http://www.w3.org/2000/svg" version="1.1"> <desc> Example tspan05 - propagation of rotation values to nested tspan elements. </desc> <text id="parent" font-family="Arial, sans-serif" font-size="32" fill="red" x="40" y="40" rotate="5,15,25,35,45,55"> Not <tspan id="child1" rotate="-10,-20,-30,-40" fill="orange"> all characters <tspan id="child2" rotate="70,60,50,40,30,20,10" fill="yellow"> in <tspan id="child3"> the </tspan> </tspan> <tspan id="child4" fill="orange" x="40" y="90"> text </tspan> have a </tspan> <tspan id="child5" rotate="-10" fill="blue"> specified </tspan> rotation </text> <!-- Show outline of canvas using 'rect' element --> <rect x="1" y="1" width="498" height="118" fill="none" stroke="blue" stroke-width="2" /> </svg>
Rotation of red text inside the ‘text’ element:
Rotation of the orange text inside the "child1" ‘tspan’element:
Rotation of the yellow text inside the "child2" ‘tspan’element:
Rotation of the blue text inside the "child5" ‘tspan’ element:
The following diagram illustrates how the rotation values propagate to ‘tspan’ elements nested withing a ‘text’ element:
SVG 2 Requirement: | Include text layout improvements from SVG Tiny 1.2. |
---|---|
Resolution: | SVG 2 will include the improved text from SVG Tiny 1.2 on characters and glyphs, text layout, text selection, text search. |
Purpose: | To include clearer descriptions of text layout; no functional change. |
Owner: | Chris (ACTION-3236) |
SVG 2 Requirement: | Support text in shapes. |
---|---|
Resolution: | SVG 2 will require automatic text wrapping compatible with CSS. |
Purpose: | Text in flow charts, etc. |
Owner: | Tav (no action) |
This section gives a short overview of SVG text layout. It is followed by sections that cover different aspects of text layout in more detail.
Text layout in SVG is a multi-stage process that takes as input a ‘text’ element subtree and its property values and produces a sequence of glyphs to render and their positions in each text content element's coordinate system.
First, a ‘text’ element and its descendants are laid out
inside a content area or wrapping area according to
CSS, as if the ‘text’ were a block element and
any ‘tspan’ and ‘textPath’ descendants were inline
elements.
The content area may be explictly declared by setting the
‘inline-size
’ property, or by setting
the ‘shape-inside
’ property that defines or references an
SVG shape. If a content area is not declared, it
defaults to a rectangle of infinite width and height. The rules
for text layout within the content area are the same as for
text layout in a
CSS
content area except as noted in this chapter.
Second, any positioning given by ‘x’, ‘y’, ‘dx’ and ‘dy’ attributes are applied to the resulting glyph positions from the CSS layout process. The rules for which transforms are allowed depend on if the content area was explictly declared or not. If not explicitly declared, the rules define the layout of pre-formatted text. If declared, the rules define the layout of auto-wrapped text.
Third, the effect of the ‘text-anchor
’ property is applied
for pre-formatted text.
Finally, layout of glyphs for any ‘textPath’ elements is performed, converting pre-formatted text to text-on-a-path.
Examples if the different types of text layout follow:
An example of multi-line pre-formatted text.
<svg xmlns="http://www.w3.org/2000/svg"> width="300" height="100" viewBox="0 0 300 100" <text x="20" y="45" font-family="sans-serif" font-size="24" > Example of multi-line, <tspan x="20" y="75">pre-formatted text.</tspan> </text> </svg>
An example of auto-wrapped text.
<svg xmlns="http://www.w3.org/2000/svg"> width="300" height="100" viewBox="0 0 300 100" <text x="20" y="45" font-family="sans-serif" font-size="24" width="250"> Example of text auto-wrapped.</text> </svg>
An example of text on a path.
<svg xmlns="http://www.w3.org/2000/svg"> width="300" height="100" viewBox="0 0 300 100" <path id="MyPath" stroke="lightblue" fill="none" d="M 50,50 C 100,0 200,100 250,50"/> <text font-family="sans-serif" font-size="24"> <textPath href="#MyPath">Text on a path.</textPath> </text> </svg>
SVG 2 introduces the ability to automatically wrap text inside a
rectangle or other shape by specifying a content area. The
design of SVG wrapped text is motivated by the desire that SVG
text wrapping be as compatible as possible with text wrapping in
CSS inorder that renderers that support CSS text wrapping can
implement SVG text wrapping easily (but without requiring non-HTML
compatable SVG renderers to implement HTML). There are several
differences between SVG and CSS text wrapping. The most important
is that in SVG, a content area must be explicitly provided
as SVG does not have an automatic finite (or semi-finite)
content area (provided in CSS by the box model). Another
difference is that SVG does not have the <p></p> and
<br/> elements which create line breaks. Instead, SVG relies
on the pre and
pre-line values of
‘white-space
’ to provide line breaks. SVG wrapped text also
allows a content-creation tool to provide a natural fallback for
SVG 1.1 renderers that do not support wrapped text (by use of
‘x’ and ‘y’ attributes in the ‘text’ and
‘tspan’ elements, which are ignored by SVG 2 renderers for
auto-wrapped text).
SVG's text layout options are designed to cover most general use cases. If more complex layout is required (bulleted lists, tables, etc.), text can be rendered in another XML namespace such as XHTML [XHTML] embedded inline within a ‘foreignObject’ element.
A content area is defined by specifying in
a ‘text’ element a ‘inline-size
’ property,
or a ‘shape-inside
’ property that defines
or references an SVG shape. If no content area is
provided, the content area defaults to a rectangle of
infinite width and height (see the
pre-formatted text section).
If both an ‘inline-size
’ property and a
‘shape-inside
’ property with value other than 'none' are
given, the ‘shape-inside
’ property is used.
Wrapped text is laid out in a wrapping area. The
wrapping area is normally the same as the content area. When the content area is defined using
the ‘shape-inside
’ property, the wrapping area
may be smaller due to the presence of a ‘shape-outside
’
property and/or a ‘shape-padding
’ property. The
‘shape-outside
’ property (along with the
‘shape-margin
’ property) defines a wrapping
context. The wrapping area then is found by
subtracting the wrapping context from the content area. A non-zero value for the ‘shape-padding
’ property
causes an additional inset to the wrapping area.
'extent' added by resolution from February 12th, 2015. 'extent' replaces the 'width' and 'height' attributes, added by resolution from June 27th, 2013. Replaced by 'inline-size' presentation attribute per resolution from Linkoping F2F, June 11, 2015.
The ‘inline-size
’ property allows one to set the
content area to a rectangluar shape. The computed value of
the property sets the width of the rectangle for horizontal text
and the height of the rectangle for vertical text. The other
dimension (height for horizontal text, width for vertical text) is
of infinite length.
The initial current text position is taken from the ‘x’ and ‘y’ attributes of the ‘text’ element (or first child ‘tspan’ element if the attributes are not given on the ‘text’ element). For left-to-right text, the initial current text position is at the left of the rectangle. For right-to-left text it is at the right of the rectangle. For vertical text, the initial current text position is at the top of the rectangle.
Name: | inline-size |
---|---|
Value: | <length> | <percentage> | <number> |
Initial: | As if not specified. |
Applies to: | ‘text’ elements |
Inherited: | no |
Percentages: | Refer to the width (for horizontal text) or height (for vertical text) of the current viewport (see Units) |
Media: | visual |
Computed value: | absolute length or percentage |
Animatable: | yes |
An example of using ‘inline-size
’ for wrapping horizontal text.
<svg xmlns="http://www.w3.org/2000/svg" width="300" height="100" viewBox="0 0 300 100"> <text x="50" y="30" inline-size="200" font-family="sans-serif" font-size="20px" >This text wraps at 200 pixels.</text> </svg>
An example of using ‘inline-size
’ for wrapping right to left horizontal text.
<svg xmlns="http://www.w3.org/2000/svg" width="300" height="100" viewBox="0 0 300 100"> <text x="250" y="30" inline-size="200" writing-mode="rl-tb" font-family="PakType Naqsh" font-size="20px" >هذا النص يلتف في 200 بكسل.</text> </svg>
Some browser may not render this SVG 1.1 figure correctly. Batik and Firefox seems to get it right.
An example of using ‘inline-size
’ for wrapping vertical text.
<svg xmlns="http://www.w3.org/2000/svg" width="100" height="300" viewBox="0 0 100 300"> <text x="62.5" y="25" inline-size="200" writing-mode="tb-rl" font-family="IPAMincho" font-size="25px" >テキストは10文字後に折り返されます。</text> </svg>
This SVG 1.1 image doesn't work in Firefox, even nightly. The "period" is in the incorrect place in Chrome (should be at upper-right of cell). It appears that horizontal to vertical glyph substitution is not being done. librsvg does do the correct glyph substitution.
The ‘shape-inside
’ property allows one to set the
content area to a CSS basic shape or to an
SVG shape.
In CSS/HTML ‘shape-inside
’ applies to block-level elements
and absolute and percentage values are defined relative to the
block-level element.
In SVG absolute and percentage values are defined relative to the
current local coordinate system and the ‘viewBox’.
The values 'outside-shape' and 'auto' are probably not useful in SVG. A new value of 'none' is probably needed for SVG. This would indicate that the text should be rendered using a 'width' and/or 'height' attribute, or absent those attributes, as pre-formatted text.
Name: | shape-inside |
---|---|
Value: | none | <basic-shape> | <uri> |
Initial: | none |
Applies to: | ‘text’ elements |
Inherited: | no |
Percentages: | N/A |
Media: | visual |
Computed value: | computed lengths for <shape>, the absolute URI for <uri>, otherwise as specified |
Animatable: | yes, see Interpolation of Basic Shapes |
An example of using a CSS basic-shape for wrapping horizontal text.
<svg xmlns="http://www.w3.org/2000/svg" width="300" height="100" viewBox="0 0 300 100"> <text shape-inside="circle(100 at 100 100)" font-family="sans-serif" font-size="20px">Lorem ipsum dolor sit amet, consec-tetuer adipiscing elit...</text> </svg>
Check if we allow referencing an image. There are security issues. If we allow it, then the 'shape-image-threshold' property is also required.
An example of using a reference to an SVG shape for wrapping horizontal text.
<svg xmlns="http://www.w3.org/2000/svg" width="300" height="100" viewBox="0 0 300 100"> <defs> <rect id="wrap" x="50" y="10" width="200" height="80"/> </defs> <text shape-inside="url(#wrap)" font-family="sans-serif" font-size="20px" >This text wraps in a rectangle.</text> </svg>
Except as noted, see the CSS Shapes Module Level 2 for the definition of 'shape-inside'. [CSSSHAPES2]
'shape-inside' was removed when the CSS Exclusions and Shapes Module was split into separate Exclusions and Shapes modules. At the Tokyo joint SVG/CSS F2F meeting, it was agreed that it would reappear in CSS Shapes Module Level 2.
The ‘shape-outside
’ property allows one to exclude part of
the content area from the wrapping area. The
exclusion can be a CSS basic shape or to an
SVG shape.
In CSS/HTML ‘shape-outside
’ applies to floats and
absolute and percentage values are defined relative to the
float.
In SVG absolute and percentage values are defined relative to the
current local coordinate system and the ‘viewBox’.
We could use the content area.
The value 'auto' is probably not useful in SVG. A new value of 'none' is probably needed in which case the property is ignored.
Name: | shape-outside |
---|---|
Value: | none | <basic-shape> | <uri> |
Initial: | none |
Applies to: | ‘text’ elements |
Inherited: | no |
Percentages: | N/A |
Media: | visual |
Computed value: | computed lengths for <basic-shape>, the absolute URI for <uri>, otherwise as specified |
Animatable: | yes, see Interpolation of Basic Shapes |
Check if we allow referencing an image. There are security issues. If we allow it, then the 'shape-image-threshold' property is also required.
An example of using ‘shape-outside
’.
<svg xmlns="http://www.w3.org/2000/svg" width="450" height="300" viewBox="0 0 450 300"> <rect id="rect1" x="25" y="25" width="225" height="175" fill="white" stroke="black"/> <rect id="rect2" x="200" y="125" width="225" height="150" fill="white" stroke="black"/> <text shape-inside="url(#rect1)" shape-outside="url(#rect2)" shape-padding="25" shape-margin="25" font-family="DejaVu Sans" font-size="12px" text-align="justified" line-height="110%">Lorem ipsum ...</text> <text shape-inside="url(#rect2)" shape-padding="25" font-family="DejaVu Sans" font-size="12px" text-align="justified" line-height="110%">Lorem ipsum ...</text> </svg>
Except as noted, see the CSS Shapes Module Level 1 for the definition of 'shape-outside'. [CSSXX]
The ‘shape-margin
’ property adds a margin to a
‘shape-outside
’. This defines a new shape where every
point is the specified distance from the shape-outside. This
property takes on positive values only.
Name: | shape-margin |
---|---|
Value: | <length> | <percentage> |
Initial: | 0 |
Applies to: | ‘text’ elements |
Inherited: | no |
Percentages: | N/A |
Media: | visual |
Computed value: | the absolute length |
Animatable: | yes |
Except as noted, see the CSS Shapes Module Level 1 for the definition of See 'shape-margin'. [CSSXX]
The ‘shape-padding
’ property can be used to offset the
inline flow content wrapping on the inside of elements. Offsets
created by the ‘wrap-padding’ property are offset from the content
area of the element. This property takes on positive values only.
An example of using ‘shape-padding
’
<svg xmlns="http://www.w3.org/2000/svg" width="300" height="300" viewBox="0 0 300 300"> <circle id="circle" cx="150" cy="150" r="125" fill="none" stroke="black"/> <text shape-inside="url(#circle)" shape-padding="25" font-family="DejaVu Sans" font-size="18px" text-align="justified" line-height="110%">This is an example of wrapped text in SVG 2! There should be 25 pixel pixel around the text. The text is justified on both sides. It looks good!</text> </svg>
Except as noted, see the CSS Shapes Module Level 2 for the definition of 'shape-padding' (wrap-padding renamed to shape-padding).
Once a content area has been defined, the following algorithm is used to determine the glyphs to render for a given ‘text’ element and their positions:
inline-size
’
attribute, then lay out root with its block size set to the ‘inline-size
’ attribute's value and
with an unconstrained inline size.
This means that root is laid out with its
width set to the ‘inline-size
’ value, if ‘writing-mode
’
is horizontal-tb, and its height otherwise.
inline-size
’ was not specified. Lay
out root with an unconstrained width and height.
This option corresponds to basic SVG 1.1 text layout.
This is the default text layout method and is used in the absence of an explicitly defined content area. It is also used as a first step in laying out text on a path (with slightly modified rules). In this layout method, no automatic line breaking or word wrapping is done. Nominally, the text is rendered as a single line inside a rectangular content area of infinite width and height. Multiple lines of text can be obtained by precomputing line breaks and using one of the following methods:
white-space
’ set
to pre
or pre-line. Line spacing is set
by ‘line-height
’.
New in SVG 2.
The following properties do not apply to pre-formatted text:
‘text-align
’, ‘text-align-last
’, ‘line-break
’,
‘word-break
’, ‘hyphens
’, ‘word-wrap
’,
and ‘overflow-wrap
’.
Multi-line pre-formatted text may be created by using the
‘white-space
’ values pre
or pre-line. In these cases, a
line-feed or carriage return is preserved as a forced line break. When a renderer encounters a forced line break,
the current text position is set as follows:
line-height
’
property.
line-height
’.
SVG 1.1 only has right-to-left vertical text but CSS Writing Modes Module Level 3 also has left-to-right. This is required for Mongolian.
After text is laid out according to the basic CSS text layout
rules, glyphs can be repositioned using SVG specific rules. Two
types of adjustments can be made. The first uses the
‘x’, ‘y’, ‘dx’,
‘dy’, ‘rotate’ attributes to reposition
glyphs with in a ‘tspan’ element. The second uses the
‘text-anchor
’ property to realign lines of text.
Expand on how 'x' and 'y' effect characters.
The ‘text-anchor
’ property is used to align (start-,
middle- or end-alignment) a string of pre-formatted text
relative to a given point. It is not applicable to
auto-wrapped text, see instead ‘text-align
’. For
multi-line text, the alignment takes place for each line.
This is confusing, perhaps a figure would help:
The ‘text-anchor
’ property is applied to each individual
text chunk within a
given ‘text’ element. Each text chunk has an initial
current text position, which represents the point in the user
coordinate system resulting from (depending on context)
application of the ‘x’ and ‘y’ attributes
on the ‘text’ element, any ‘x’
or ‘y’ attribute values on a ‘tspan’
element assigned explicitly to
the first rendered character in a text chunk, or determination of
the initial current text position for a ‘textPath’ element.
Name: | text-anchor |
---|---|
Value: | start | middle | end |
Initial: | start |
Applies to: | text content elements |
Inherited: | yes |
Percentages: | N/A |
Media: | visual |
Computed value: | as specified |
Animatable: | yes |
Values have the following meanings:
direction
’ property value
of "ltr" (typical for most
European languages), the left side of the text is rendered at
the initial text position. For an element with a
‘direction
’ property value of
"rtl" (typical for Arabic and
Hebrew), the right side of the text is rendered at the initial
text position. For an element with a vertical primary text
direction (often typical for Asian text), the top side of the
text is rendered at the initial text position.
direction
’ property value
of "ltr" (typical for most
European languages), the right side of the text is rendered at
the initial text position. For an element with
a ‘direction
’ property value
of "rtl" (typical for Arabic and
Hebrew), the left side of the text is rendered at the initial
text position. For an element with a vertical primary text
direction (often typical for Asian text), the bottom of the text
is rendered at the initial text position.
An example of using ‘text-anchor
’ on multi-line text.
<svg xmlns="http://www.w3.org/2000/svg" width="300" height="100" viewBox="0 0 300 100"> <text x="150" y="30" font-family="sans-serif" font-size="20px" white-space="pre-line" text-anchor="middle">This multi-line text is anchored to the middle.</text> </svg>
Text is automatically wrapped when a content area is
specified in the ‘text’ element. The content area
defines the outermost container for wrapping text. A wrapping context (set of exclusion areas) may also be given. The
actual wrapping area is defined by subtracting the
wrapping context from the content area. The
wrapping context may also be reduced by the value of the
‘shape-padding
’ property. The effective area of an
exclusion may be enlarged by the value of the
‘shape-margin
’ property.
In the case where the content area is defined by the by
the ‘inline-size
’ attribute,
the ‘x’ and ‘y’ attributes
corresponding to the first rendered glyph define the
initial current text position. When the content area is inside a shape, the initial current text position is determined by FIX ME, FIND
WHERE IN CSS THIS IS SPECED..
Except when used to determine the initial current text position, all values ‘x’ and ‘y’ are ignored on ‘text’, and ‘tspan’ elements.
The attributes ‘x’ and ‘y’ can provide a natural fallback mechanism for SVG1.1 renderers for wrapped text. Most of the text wrapping examples in this section rely on this mechanism to render text in browsers that have not implemented text wrapping.
See the CSS Text Module Level 3 specification for the definition of 'text-align'. [CSSXX]
See the CSS Text Module Level 3 specification for the definition of 'text-align-last'. [CSSXX]
See the CSS Text Module Level 3 specification for the definition of 'line-break'. [CSSXX]
See the CSS Text Module Level 3 specification for the definition of 'word-break'. [CSSXX]
See the CSS Text Module Level 3 specification for the definition of 'hyphens'. [CSSXX]
See the CSS Text Module Level 3 specification for the definition of 'word-wrap'. [CSSXX]
See the CSS Text Module Level 3 specification for the definition of 'overflow-wrap'. [CSSXX]
See the CSS Text Module Level 3 specification for the definition of 'text-indent'. [CSSXX]
This property might also be useful for preformatted text.
See the CSS Text Module Level 3 specification for the definition of 'hanging-punctuation'. [CSSXX]
This property might also be useful for preformatted text. It is marked in the CSS spec as at risk.
SVG can place text along a path defined either by a ‘path’ element or the path equivalent of a basic shape. This is specified by including text within a ‘textPath’ element that has either an ‘href’ attribute with an URL reference pointing to a ‘path’ element or basic shape, or by including a ‘d’ attribute that specifies path data directly.
The ability to place text along a basic shape is new in SVG 2.
Placing text along a basic shape was resolved at the Sydney (2015) meeting.
Text on a path is conceptional like a single line of pre-formatted text text that is then transformed to follow the path. Except as indicated, all the properties that apply to pre-formatted text apply to text on a path.
SVG 2 Requirement: | Have a more precise explanation of text path stretch methods. |
---|---|
Resolution: | We will clarify method="stretch" on >'textPath' elements. |
Purpose: | Improve interoperability of the feature. |
Owner: | Cameron (no action) |
An offset from the start of the path for the initial current text position, calculated using the user agent's distance along the path algorithm.
If a <length>
other than a percentage is given, then the
‘startOffset’ represents a distance along the path
measured in the current user coordinate system.
If a
percentage is given, then the ‘startOffset’ represents
a percentage distance along the entire path. Thus,
startOffset="0%" indicates the
start point of the path and
startOffset="100%" indicates
the end point of the path.
For an open path, glyphs with mid-points that are not on the path are not rendered.
For a closed path (including an equivalent path for a basic shape), the path is considered to wrap around in both directions. All glyphs are rendered.
Rendering all glyphs was agreed to for basic shapes at the Sydney (2015) meeting (but missing in minutes).
Indicates the method by which text should be rendered along the path.
A value of align indicates that the glyphs should be rendered using simple 2x3 transformations such that there is no stretching/warping of the glyphs. Typically, supplemental rotation, scaling and translation transformations are done for each glyph to be rendered. As a result, with align, fonts where the glyphs are designed to be connected (e.g., cursive fonts), the connections may not align properly when text is rendered along a path.
A value of stretch indicates that the glyph outlines will be converted into paths, and then all end points and control points will be adjusted to be along the perpendicular vectors from the path, thereby stretching and possibly warping the glyphs. With this approach, connected glyphs, such as in cursive scripts, will maintain their connections.
Indicates how the user agent should determine the spacing between glyphs that are to be rendered along a path.
A value of exact indicates that the glyphs should be rendered exactly according to the spacing rules as specified in Text on a path layout rules.
A value of auto indicates that the user agent should use text-on-a-path layout algorithms to adjust the spacing between glyphs in order to achieve visually appealing results.
The definition of the path onto which the glyphs will be rendered. The handling of erroneous path data follows the behavior specified in the ‘path’ element implementation notes.
If both the ‘d’ attribute and ‘href’ attributes are specified, it is as if the ‘href’ attribute were not specified for the purposes of rendering.
Determines the side of the path the text is placed on (relative to the path direction). Specifying a value of right effectively reverses the path.
Added in SVG 2 to allow text either inside or outside closed paths and basic shapes (e.g. rectangles, circles, and ellipses).
Adding 'side' was resolved at the Sydney (2015) meeting.
An URL reference to the ‘path’ or basic shape element onto which the glyphs will be rendered. If <url> is an invalid reference (e.g., no such element exists, or the referenced element is not a ‘path’) or basic shape, then the ‘textPath’ element is in error and its entire contents shall not be rendered by the user agent.
Refer to the common handling defined for URL reference attributes and deprecated XLink attributes.
The path data coordinates within the referenced ‘path’
or basic shape
element are assumed to be in the same coordinate system as the
current ‘text’ element, not in the coordinate system where
the ‘path’ element is defined. The ‘transform
’
attribute on the referenced ‘path’ or basic shape
element represents a
supplemental transformation relative to the current user
coordinate system for the current ‘text’ element, including
any adjustments to the current user coordinate system due to a
possible ‘transform
’ property on the current ‘text’
element. For example, the following fragment of SVG content:
<svg xmlns="http://www.w3.org/2000/svg"> <g transform="translate(25,25)"> <defs> <path id="path1" transform="scale(2)" d="..." fill="none" stroke="red"/> </defs> </g> <text transform="rotate(45)"> <textPath href="#path1">Text on a path1</textPath> </text> </svg>
should have the same effect as the following:
<svg xmlns="http://www.w3.org/2000/svg"> <g transform="rotate(45)"> <defs> <path id="path1" transform="scale(2)" d="..." fill="none" stroke="red"/> </defs> <text> <textPath href="#path1">Text on a path1</textPath> </text> </g> </svg>
Note that the transform="translate(25,25)"
has no effect on
the ‘textPath’ element, whereas the
transform="rotate(45)"
applies to both
the ‘text’ and the use of the ‘path’ element as the
referenced shape for text on a path.
Example toap01 provides a simple example of text on a path:
<?xml version="1.0" standalone="no"?> <svg width="12cm" height="3.6cm" viewBox="0 0 1000 300" version="1.1" xmlns="http://www.w3.org/2000/svg"> <defs> <path id="MyPath" d="M 100 200 C 200 100 300 0 400 100 C 500 200 600 300 700 200 C 800 100 900 100 900 100" /> </defs> <desc>Example toap01 - simple text on a path</desc> <use href="#MyPath" fill="none" stroke="red" /> <text font-family="Verdana" font-size="42.5" fill="blue" > <textPath href="#MyPath"> We go up, then we go down, then up again </textPath> </text> <!-- Show outline of canvas using 'rect' element --> <rect x="1" y="1" width="998" height="298" fill="none" stroke="blue" stroke-width="2" /> </svg>
Example toap02 shows how ‘tspan’ elements can be included within ‘textPath’ elements to adjust styling attributes and adjust the current text position before rendering a particular glyph. The first occurrence of the word "up" is filled with the color red. Attribute ‘dy’ is used to lift the word "up" from the baseline.
<?xml version="1.0" standalone="no"?> <svg width="12cm" height="3.6cm" viewBox="0 0 1000 300" version="1.1" xmlns="http://www.w3.org/2000/svg"> <defs> <path id="MyPath" d="M 100 200 C 200 100 300 0 400 100 C 500 200 600 300 700 200 C 800 100 900 100 900 100" /> </defs> <desc>Example toap02 - tspan within textPath</desc> <use href="#MyPath" fill="none" stroke="red" /> <text font-family="Verdana" font-size="42.5" fill="blue" > <textPath href="#MyPath"> We go <tspan dy="-30" fill="red" > up </tspan> <tspan dy="30"> , </tspan> then we go down, then up again </textPath> </text> <!-- Show outline of canvas using 'rect' element --> <rect x="1" y="1" width="998" height="298" fill="none" stroke="blue" stroke-width="2" /> </svg>
Example toap03 demonstrates the use of the ‘startOffset’ attribute on the ‘textPath’ element to specify the start position of the text string as a particular position along the path. Notice that glyphs that fall off the end of the path are not rendered (see text on a path layout rules).
<?xml version="1.0" standalone="no"?> <svg width="12cm" height="3.6cm" viewBox="0 0 1000 300" version="1.1" xmlns="http://www.w3.org/2000/svg"> <defs> <path id="MyPath" d="M 100 200 C 200 100 300 0 400 100 C 500 200 600 300 700 200 C 800 100 900 100 900 100" /> </defs> <desc>Example toap03 - text on a path with startOffset attribute</desc> <use href="#MyPath" fill="none" stroke="red" /> <text font-family="Verdana" font-size="42.5" fill="blue" > <textPath href="#MyPath" startOffset="80%"> We go up, then we go down, then up again </textPath> </text> <!-- Show outline of canvas using 'rect' element --> <rect x="1" y="1" width="998" height="298" fill="none" stroke="blue" stroke-width="2" /> </svg>
Conceptually, for text on a path the target path is stretched out into either a horizontal or vertical straight line segment. For horizontal text layout flows, the path is stretched out into a hypothetical horizontal line segment such that the start of the path is mapped to the left of the line segment. For vertical text layout flows, the path is stretched out into a hypothetical vertical line segment such that the start of the path is mapped to the top of the line segment. The standard text layout rules are applied to the hypothetical straight line segment and the result is mapped back onto the target path. Vertical and bidirectional text layout rules also apply to text on a path.
The reference orientation is determined individually for each glyph that is rendered along the path. For horizontal text layout flows, the reference orientation for a given glyph is the vector that starts at the intersection point on the path to which the glyph is attached and which points in the direction 90 degrees counter-clockwise from the angle of the curve at the intersection point. For vertical text layout flows, the reference orientation for a given glyph is the vector that starts at the intersection point on the path to which the glyph is attached and which points in the direction 180 degrees from the angle of the curve at the intersection point.
Example toap04 will be used to illustrate the particular layout rules for text on a path that supplement the basic text layout rules for straight line horizontal or vertical text.
<?xml version="1.0" standalone="no"?> <svg width="12cm" height="3.6cm" viewBox="0 0 1000 300" version="1.1" xmlns="http://www.w3.org/2000/svg"> <defs> <path id="MyPath" d="M 100 125 C 150 125 250 175 300 175 C 350 175 450 125 500 125 C 550 125 650 175 700 175 C 750 175 850 125 900 125" /> </defs> <desc>Example toap04 - text on a path layout rules</desc> <use href="#MyPath" fill="none" stroke="red" /> <text font-family="Verdana" font-size="60" fill="blue" letter-spacing="2" > <textPath href="#MyPath"> Choose shame or get war </textPath> </text> <!-- Show outline of canvas using 'rect' element --> <rect x="1" y="1" width="998" height="298" fill="none" stroke="blue" stroke-width="2" /> </svg>
The following picture does an initial zoom in on the first glyph in the ‘text’ element.
The small dot above shows the point at which the glyph is attached to the path. The box around the glyph shows the glyph is rotated such that its horizontal axis is parallel to the tangent of the curve at the point at which the glyph is attached to the path. The box also shows the glyph's charwidth (i.e., the amount which the current text position advances horizontally when the glyph is drawn using horizontal text layout).
The next picture zooms in further to demonstrate the detailed layout rules.
For left-to-right horizontal text layout along a path (i.e., when the glyph orientation is perpendicular to the inline-progression-direction), the layout rules are as follows:
text-anchor
’. For text-anchor:start,
startpoint-on-the-path is the point on the path which represents
the point on the path which is ‘startOffset’ distance
along the path from the start of the path, calculated using the
user agent's distance
along the path algorithm.
For text-anchor:middle,
startpoint-on-the-path is the point on the path which represents
the point on the path which is [ ‘startOffset’ minus half
of the total advance values for all of the glyphs in
the ‘textPath’ element ] distance along the path from the
start of the path, calculated using the user
agent's distance along
the path algorithm.
For text-anchor:end,
startpoint-on-the-path is the point on the path which represents
the point on the path which is [ ‘startOffset’ minus the
total advance values for all of the glyphs in
the ‘textPath’ element ]. Before rendering the first
glyph, the horizontal component of the startpoint-on-the-path is
adjusted to take into account various horizontal alignment text
properties and attributes, such as a ‘dx’ attribute
value on a ‘tspan’ element. (In the picture above, the
startpoint-on-the-path is the leftmost dot on the path.)
alignment-baseline
’ and any specified
values for attribute ‘dy’ on a ‘tspan’
element. In the example above, the ‘alignment-baseline
’
property is unspecified, so the initial value
of alignment-baseline:baseline
will be used. There are no ‘tspan’ elements; thus, the
baseline of the glyph is aligned to the
midpoint-on-the-path.
Comparable rules are used for top-to-bottom vertical text layout along a path (i.e., when the glyph orientation is parallel with the inline-progression-direction), the layout rules are as follows:
alignment-baseline
’ and any specified values
for attribute ‘dx’ on a ‘tspan’ element.
In the calculations above, if either the startpoint-on-the-path or the endpoint-on-the-path is off the end of the path, then extend the path beyond its end points with a straight line that is parallel to the tangent at the path at its end point so that the midpoint-on-the-path can still be calculated.
When the inline-progression-direction is horizontal, then any ‘x’ attributes on ‘text’ or ‘tspan’ elements represent new absolute offsets along the path, thus providing explicit new values for startpoint-on-the-path. Any ‘y’ attributes on ‘text’ or ‘tspan’ elements are ignored. When the inline-progression-direction is vertical, then any ‘y’ attributes on ‘text’ or ‘tspan’ elements represent new absolute offsets along the path, thus providing explicit new values for startpoint-on-the-path. Any ‘x’ attributes on ‘text’ or ‘tspan’ elements are ignored.
A ‘text’ element is rendered in one or more chunks. Each chunk (as produced by the text layout algorithm) is rendered, one after the other, in document order. Each rendered chunk, which consists of one or more glyphs, is filled and stroked as if it were a single path.
For the purposes of painting, a ‘text’ has zero, one, or more equivalent paths, one for each chunk. Each equivalent path consists of one subpath per glyph within that chunk.
Since the ‘fill-rule
’ property does not apply
to SVG text elements, the specific order of the subpaths within
the equivalent path does not matter.
The specific position of the start of each subpath, and the direction that the path progresses around glyph shape, is not defined.
This means that dashed strokes on text may not place the dash pattern at the same positions across different implementations.
Make sure these chunks are not confused with the text anchoring chunks.
SVG 2 Requirement: | Add ‘text-overflow ’ functionality. |
---|---|
Resolution: | We will add text-overflow in SVG 2. |
Purpose: | To align with CSS, allow indicating that not all text is shown. |
Owner: | Erik (ACTION-3003) |
New in SVG 2. Added to allow user agents to handle text strings that overflow a predefined region in a more useful way. Aligns SVG and HTML/CSS text processing.
See the CSS3 UI specification for the definition of of 'text-overflow'. [CSS3UI]
SVG uses the ‘text-overflow
’ property to control
how text content block elements render when the text
overflows a specified region. In the case of wrapped text, the
region is the wrapping area. In the case of text on a path,
a region is determined by the path length. Pre-formatted text does
not create a region.
When applied to a text content block element
setting ‘text-overflow
’ to
ellipsis then if the text that is
to be rendered overflows the specified region an ellipsis is
rendered such that it fits within the given region. For the
purposes of rendering, the ellipsis is treated as if it replaced
the characters at the point where it is inserted.
In SVG ‘text-overflow
’ has an effect if there is a validly
specified region, regardless of the computed value of
the ‘overflow
’ property on the text content block element.
Any other value for ‘text-overflow
’ is treated as if it
wasn't specified.
SVG could allow the keyword 'clip' to work too. It's already possible to do clipping with clip-path, but it's unconditional, where this would theoretically only clip if the text overflowed. It's mostly a convenient shorthand.
Note that the effect of ‘text-overflow
’ is purely visual,
the ellipsis itself does not become part of the DOM. For all the
DOM methods it's as if ‘text-overflow
’ wasn't applied, and
as if ‘inline-size
’ didn't constrain the text.
The following example shows the use of ‘text-overflow
’.
The top line shows text as it would normally be rendered, without any width restriction.
The middle line shows text with text-overflow=clip specified, and the bottom line shows
text with text-overflow=ellipsis.
<svg xmlns="http://www.w3.org/2000/svg" width="180" height="120" viewBox="0 0 180 120"> <style> text { font: 16px sans-serif; } rect { fill: none; stroke: black; vector-effect: non-scaling-stroke; stroke-width: 1; } </style> <g> <rect x="19.5" y="16.5" width="100" height="20"/> <text x="20" y="2em" width="100">SVG is awesome</text> </g> <g transform="translate(0,30)"> <rect x="19.5" y="16.5" width="100" height="20"/> <text x="20" y="2em" width="100" text-overflow="clip">SVG is awesome</text> </g> <g transform="translate(0,60)"> <rect x="19.5" y="16.5" width="100" height="20"/> <text x="20" y="2em" width="100" text-overflow="ellipsis">SVG is awesome</text> </g> </svg>
It has been argued that this property is useless. It would be of more use if coupled with a mechanism that would expose the hidden text (tool-tip on hovering over ellipses?).
CSS offers a multitude of properties for styling text. In
general, only two sets of properties are applicable to SVG: those
that determine which glyphs are to be rendered
(‘font-family
’, ‘font-style
’, etc.) and those that
apply at the paragraph level (‘direction
’,
‘writing-mode
’, ‘line-height
’, ‘letter-spacing
’,
etc.).
The following CSS properties must be supported on SVG text elements:
font
’font-family
’font-style
’font-variant
’font-weight
’font-stretch
’font-size
’font-size-adjust
’writing-mode
’direction
’unicode-bidi
’glyph-orientation-vertical
’ (deprecated?)glyph-orientation-horizontal
’ (deprecated?)text-anchor
’dominant-baseline
’alignment-baseline
’baseline-shift
’letter-spacing
’word-spacing
’text-decoration
’line-height
’text-align
’*Need to decide and fill in that list of the minimum set of properties that must be supported on text.
Is the @font-face rule required?
Additionally, the ::first-line and ::first-letter pseudo-elements must be supported on ‘text’ elements.
Other CSS properties that affect text layout and rendering may also be supported by an SVG user agent; their effect should be taken into account as part of the CSS text layout step of the overall SVG text layout process.
For example, while SVG 2 does not require support for
the ‘text-transform
’ property, its behavior in an SVG
context should be obvious.
A number of CSS properties must not have any effect on SVG text elements:
border-top-style
’). Boxes
generated by the CSS layout process must not be sized as if they
had any borders. The used value for all of
the ‘border-style
’ component longhand properties on SVG
text elements is none.
display
’ on an SVG text element
other than none is handled just
as if it were inline. Thus it
is not possible for a single ‘text’ element to have any
block children.
float
’ property, whose used value on SVG text
elements is none.
position
’ property, whose used value on SVG text
elements is static.
margin-top
’), whose used
values on SVG text elements are
0.
text-align
’ property, whose used value on SVG text
elements is start.
content
’ property, whose used value on SVG text
elements is none.
Additionally, the ::before and ::after generated content pseudo-elements must not apply to SVG text elements.
SVG 2 Requirement: | Align with CSS for text layout functionality. |
---|---|
Resolution: | SVG 2 Will use CSS3 definitions for text layout (white space, bidi, etc.) that is not specific to SVG. |
Purpose: | To facilitate shared specification and implementation of text layout in HTML and SVG. |
Owner: | Cameron and Chris (ACTION-3004, ACTION-3005) |
This section describes the text layout rules that govern direction of text flow inside a content area in order to support various international writing directions, such as left-to-right (e.g., Latin scripts) and bidirectional (e.g., Hebrew or Arabic), and vertical (e.g., Asian scripts).
We cannot simply reference CSS 2 as it doesn't include the
‘writing-mode
’ property. The
CSS Writing
Modes Module Level 3 spec does include ‘writing-mode
’
but its definition is a bit different from SVG 1.1. The spec also
has a different structure, putting 'direction' and 'unicode-bidi'
before 'writing-mode'.
For each ‘text’ element, the SVG user agent determines the current reference orientation. For standard horizontal or vertical text (i.e., not text-on-a-path), the reference orientation is the vector pointing towards negative infinity in Y within the current user coordinate system. (Note: in the initial coordinate system, the reference orientation is up.) For text on a path, the reference orientation is determined at each character's position along the path. It is 90 degrees counter-clockwise relative to the path direction for horizontal text and 180 degrees relative to the path direction for vertical text.
In the model that text-on-a-path is text that is first layed out according to CSS and then warped along a path, we can get rid of the distinction made above.
Based on the reference orientation and the value for
property ‘writing-mode
’, the SVG user agent determines the
current inline-progression-direction. For left-to-right
text, the inline-progression-direction points 90 degrees clockwise
from the reference orientation vector. For right-to-left text, the
inline progression points 90 degrees counter-clockwise from the
reference orientation vector. For top-to-bottom text, the
inline-progression-direction points 180 degrees from the reference
orientation vector.
Based on the reference orientation and the value for
property ‘writing-mode
’, the SVG user agent determines the
current block-progression-direction. For left-to-right
and right-to-left text, the block-progression-direction points 180
degrees from the reference orientation vector because the only
available horizontal ‘writing-mode
’s
are lr-tb
and rl-tb. For top-to-bottom text,
the block-progression-direction always points 90 degrees
counter-clockwise from the reference orientation vector because
the only available top-to-bottom ‘writing-mode
’
is tb-rl.
The shift direction is the
direction towards which the
baseline table moves due
to positive values for property ‘baseline-shift
’. The shift
direction is such that a positive value shifts the baseline table
towards the topmost entry in the parent's
baseline table.
Do we align with CSS Writing Modes Module Level 3? In CSS3, inline progression direction is separated from block progression direction. The CSS Writing Modes Module redefines 'writing-mode'. Note: SVG does not have tb-lr required for Mongolian.
See: CSS Issue-183
The ‘writing-mode
’ property specifies whether the initial
inline-progression-direction for a ‘text’ element shall be
left-to-right, right-to-left, or top-to-bottom. The
‘writing-mode
’ property applies only to ‘text’
elements; the property is ignored for ‘tspan’,
and ‘textPath’ sub-elements. (Note that
the inline-progression-direction can change within a ‘text’
element due to the Unicode bidirectional algorithm and
properties ‘direction
’ and ‘unicode-bidi
’. For more on
bidirectional text, see
Relationship
with bidirectionality.)
Name: | writing-mode |
---|---|
Value: | lr-tb | rl-tb | tb-rl | lr | rl | tb |
Initial: | lr-tb |
Applies to: | ‘text’ elements |
Inherited: | yes |
Percentages: | N/A |
Media: | visual |
Computed value: | |
Animatable: | no |
The characters in certain scripts are written from right to left. In some documents, in particular those written with the Arabic or Hebrew script, and in some mixed-language contexts, text in a single line may appear with mixed directionality. This phenomenon is called bidirectionality, or "bidi" for short.
The Unicode standard ([UNICODE], specifically [UAX9]) defines a complex algorithm for determining the proper directionality of text. The algorithm consists of an implicit part based on character properties, as well as explicit controls for embeddings and overrides. The SVG user agent applies this bidirectional algorithm when determining the layout of characters within a text content block element.
The ‘direction
’ and ‘unicode-bidi
’ properties allow
authors to override the inherent directionality of the content
characters and thus explicitly control how the elements and
attributes of a document language map to this algorithm. These two
properties are applicable to all characters whose glyphs are
perpendicular to the inline-progression-direction.
In many cases, the bidirectional algorithm from Unicode
[UNICODE] produces the desired
result automatically, and in such cases the author does not need
to use these properties. For other cases, such as when using
right-to-left languages, it may be sufficient to add the
‘direction
’ property to the outermost svg element,
and allow that direction to inherit to all text elements, as in the
following example (which may be used as a template):
<svg xmlns="http://www.w3.org/2000/svg" width="100%" height="100%" viewBox="0 0 400 400" direction="rtl" xml:lang="fa"> <title direction="ltr" xml:lang="en">Right-to-left Text</title> <desc direction="ltr" xml:lang="en"> A simple example for using the 'direction' property in documents that predominantly use right-to-left languages. </desc> <text x="200" y="200" font-size="20">داستان SVG 1.1 SE طولا ني است.</text> </svg>
Is the PNG image above correct? Shouldn't the period be on the other side?
Below is another example, where where implicit bidi reordering is not sufficient:
<?xml version="1.0" encoding="utf-8"?> <svg xmlns="http://www.w3.org/2000/svg" width="100%" height="100%" viewBox="0 0 400 400" direction="rtl" xml:lang="he"> <title direction="ltr" xml:lang="en">Right-to-left Text</title> <desc direction="ltr" xml:lang="en"> An example for using the 'direction' and 'unicode-bidi' properties in documents that predominantly use right-to-left languages. </desc> <text x="200" y="200" font-size="20"> כתובת MAC:‏ <tspan direction="ltr" unicode-bidi="embed">00-24-AF-2A-55-FC</tspan> </text> </svg>
Within text content elements, the alignment of text with
regards to the ‘text-anchor
’ property is determined by the
value of the ‘direction
’ property. For example, given
a ‘text’ element with a ‘text-anchor
’ value
of "end", for a ‘direction
’
value of "ltr", the text will
extend to the left of the position of the ‘text’
element's ‘x’ attribute value, while for
‘direction
’ value of "rtl",
the text will extend to the right of the position of the
‘text’ element's ‘x’ attribute value.
A more complete discussion of bidirectionality can be found in the Text direction section of CSS 2.1 ([CSS21], section 9.10).
The processing model for bidirectional text is as follows. The
user agent processes the characters which are provided in
logical order (i.e., the order the characters appear in
the original document). The user agent determines
the set of independent blocks within each of which it should apply
the Unicode bidirectional algorithm. Each
text chunk represents an
independent block of text. Additionally, any change in glyph
orientation due to processing of properties
‘glyph-orientation-horizontal
’ or
‘glyph-orientation-vertical
’ will subdivide the independent
blocks of text further. After processing the Unicode bidirectional
algorithm and properties ‘direction
’ and
‘unicode-bidi
’ on each of the independent text blocks, the
user agent will have a potentially re-ordered list of characters
which are now in left-to-right rendering order. Simultaneous with
re-ordering of the characters, the ‘dx’,
‘dy’, and ‘rotate’ attributes on the
‘tspan’ elements are also re-ordered to
maintain the original correspondence between characters and
attribute values. While kerning or ligature processing might be
font-specific, the preferred model is that kerning and ligature
processing occurs between combinations of characters or glyphs
after the characters have been re-ordered.
Name: | direction |
---|---|
Value: | ltr | rtl |
Initial: | ltr |
Applies to: | text content elements |
Inherited: | yes |
Percentages: | N/A |
Media: | visual |
Computed value: | |
Animatable: | no |
This property specifies the base writing direction of text and the
direction of embeddings and overrides (see ‘unicode-bidi
’)
for the Unicode bidirectional algorithm. For
the ‘direction
’ property to have any effect on an element
that does not by itself establish a
new text chunk (such as
a ‘tspan’ element without absolute position adjustments due
to ‘x’ or ‘y’ attributes),
the ‘unicode-bidi
’ property's value must
be embed
or bidi-override.
Except for any additional information provided in this
specification, the
normative
definition of the ‘direction
’ property is in CSS 2.1
([CSS21], section 9.10).
The ‘direction
’ property applies only to glyphs oriented
perpendicular to the
inline-progression-direction,
which includes the usual case of horizontally-oriented Latin or
Arabic text and the case of narrow-cell Latin or Arabic characters
rotated 90 degrees clockwise relative to a top-to-bottom
inline-progression-direction.
Name: | unicode-bidi |
---|---|
Value: | normal | embed | bidi-override |
Initial: | normal |
Applies to: | text content elements |
Inherited: | no |
Percentages: | N/A |
Media: | visual |
Computed value: | |
Animatable: | no |
Except for any additional information provided in this
specification, the
normative
definition of the ‘unicode-bidi
’ property is in CSS 2.1
([CSS21], section 9.10).
CSS Writing Modes Module Level 3 replaces 'glyph-orientation-vertical' with 'text-orientation' but does not provide a replacement for 'glyph-orientation horizontal'. There is, however, a value 'use-glyph-orientation', only valid for SVG, which directs an implementation to use the values of 'glyph-orientation-veritical' and 'glyph-orientation-horizontal'. Note that this value is marked as at risk.
In some cases, it is required to alter the orientation of a sequence of characters relative to the inline-progression-direction. The requirement is particularly applicable to vertical layouts of East Asian documents, where sometimes narrow-cell Latin text is to be displayed horizontally and other times vertically.
Two properties control the glyph orientation relative to the
reference orientation for each of the two possible
inline-progression-directions. ‘glyph-orientation-vertical
’
controls glyph orientation when the inline-progression-direction
is vertical. ‘glyph-orientation-horizontal
’ controls glyph
orientation when the inline-progression-direction is horizontal.
Reference CSS3 text? CSS3 has additional values: upright, inline.
Name: | glyph-orientation-vertical |
---|---|
Value: | auto | <angle> | <number> |
Initial: | auto |
Applies to: | text content elements |
Inherited: | yes |
Percentages: | N/A |
Media: | visual |
Computed value: | |
Animatable: | no |
Fullwidth ideographic and fullwidth Latin text will be set with a glyph-orientation of 0-degrees.
Ideographic punctuation and other ideographic characters having alternate horizontal and vertical forms will use the vertical form of the glyph.
Text which is not fullwidth will be set with a glyph-orientation of 90-degrees.
This reorientation rule applies only to the first-level non-ideographic text. All further embedding of writing-modes or bidi processing will be based on the first-level rotation.
This is equivalent to having set the non-ideographic text string horizontally honoring the bidi-rule, then rotating the resultant sequence of inline-areas (one area for each change of glyph direction) 90-degrees clockwise.
It should be noted that text set in this "rotated" manner may contain ligatures or other glyph combining and reordering common to the language and script. (This "rotated" presentation form does not disable auto-ligature formation or similar context-driven variations.)
The glyph orientation angle. A value specified as a <number> is interpreted as an angle in degrees. The value of the angle is restricted to 0, 90, 180, and 270 degrees. The user agent shall round the value of the angle to the closest of the permitted values.
A value of 0deg indicates that all glyphs are set with the top of the glyphs oriented towards the reference orientation. A value of 90deg indicates an orientation of 90 degrees clockwise from the reference orientation.
This property is applied only to text written in a vertical
‘writing-mode
’.
The glyph orientation affects the amount that the current text
position advances as each glyph is rendered. When the
inline-progression-direction is vertical and the
‘glyph-orientation-vertical
’ results in an orientation
angle that is a multiple of 180 degrees, then the current text
position is incremented according to the vertical metrics of the
glyph. Otherwise, if the ‘glyph-orientation-vertical
’
results in an orientation angle that is not a multiple of 180
degrees, then the current text position is incremented according
to the horizontal metrics of the glyph.
The text layout diagrams in this section use the following symbols:
wide-cell glyph (e.g. Han) which is the n-th glyph in the text run | |
narrow-cell glyph (e.g. Latin) which is the n-th glyph in the text run |
The orientation which the above symbols assume in the diagrams corresponds to the orientation that the Unicode characters they represent are intended to assume when rendered in the user agent. Spacing between the glyphs in the diagrams is usually symbolic, unless intentionally changed to make a point.
The diagrams below illustrate different uses of
‘glyph-orientation-vertical
’. The diagram on the left shows
the result of the mixing of full-width ideographic glyphs with
narrow-cell Latin glyphs when ‘glyph-orientation-vertical
’
for the Latin characters is either
auto or
90. The diagram on the right show
the result of mixing full-width ideographic glyphs with
narrow-cell Latin glyphs when Latin glyphs are specified to have
a ‘glyph-orientation-vertical
’ of
0.
Reference CSS3 text? CSS3 has additional values: auto, inline.
Name: | glyph-orientation-horizontal |
---|---|
Value: | <angle> | <number> |
Initial: | 0deg |
Applies to: | text content elements |
Inherited: | yes |
Percentages: | N/A |
Media: | visual |
Computed value: | |
Animatable: | no |
This property is applied only to text written in a
horizontal ‘writing-mode
’.
The glyph orientation affects the amount that the current text
position advances as each glyph is rendered. When the reference
orientation direction is horizontal and the
‘glyph-orientation-horizontal
’ results in an orientation
angle that is a multiple of 180 degrees, then the current text
position is incremented according to the horizontal metrics of the
glyph. Otherwise, if the ‘glyph-orientation-horizontal
’
results in an orientation angle that is not a multiple of 180
degrees, then the current text position is incremented according
to the vertical metrics of the glyph.
Current text position is referred to throughout the document (almost 100 times!). The idea of current text position needs to be reconciled with CSS inline boxes. See: CSS-Inline as well as with the idea that text is laid out first using CSS rules and then tranformed, if necessary, with SVG rules.
The section covers the general rules for positiong glyphs. In SVG, the first step in positioning a glyph is to find its inline position which is determined by the current text position. Next, the glyph is aligned relative to a particular baseline. Once a glyph is positioned, the current text position is advanced and the next glyph is placed.
In processing a given ‘text’ element, the SVG user agent keeps track of the current text position. The initial current text position is established by the ‘x’ and ‘y’ attributes on the ‘text’ element for pre-formatted and in some cases for auto-wrapped text. FIX FOR AUTO-WRAPPED TEXT IN SHAPE
The current text position is adjusted after each glyph to establish a new current text position at which the next glyph shall be rendered. The adjustment to the current text position is based on:
If a glyph does not provide explicit advance values corresponding to the current glyph orientation, then an appropriate approximation should be used. For vertical text, a suggested approximation is the sum of the ascent and descent values for the glyph. Another suggested approximation for an advance value for both horizontal and vertical text is the size of an em.
For each glyph to be rendered, the SVG user agent determines an appropriate alignment-point on the glyph which will be placed exactly at the current text position. The alignment-point is determined based on glyph cell metrics in the glyph itself, the current inline-progression-direction and the glyph orientation relative to the inline-progression-direction. For example, in most uses of pre-formatted Latin text (i.e., writing-mode:lr, text-anchor:start, and alignment-baseline:baseline) the alignment-point in the glyph will be the intersection of left edge of the glyph cell (or some other glyph-specific x-axis coordinate indicating a left-side origin point) with the Latin baseline of the glyph. For many cases with top-to-bottom vertical text layout, the reference point will be either a glyph-specific origin point based on the set of vertical baselines for the font or the intersection of the center of the glyph with its top line (see Text Baselines in [CSSWRITINGMODES3]). If a glyph does not provide explicit origin points corresponding to the current glyph orientation, then an appropriate approximation should be used, such as the intersection of the left edge of the glyph with the appropriate horizontal baseline for the glyph or intersection of the top edge of the glyph with the appropriate vertical baseline. If baseline tables are not available, user agents should establish baseline tables that reflect common practice.
The distinction between absolute and relative position adjustments seems mostly made to define text chunks. 'x' and 'y' attributes are ignored for wrapped text and partially ignored for text on a path. Does this impact text chunks? How are new lines (either manual or auto) handled?
Once all the glyphs in a ‘text’ element are laid out according to the above rules, the position of the glyphs maybe adjusted according to SVG specific rules. Adjustments to the current text position are either absolute position adjustments or relative position adjustments. An absolute position adjustment occurs in the following circumstances:
All other position adjustments to the current text position are relative position adjustments.
Each absolute position adjustment defines a new text chunk. Absolute position adjustments impact text layout in the following ways:
text-anchor
’ property values.
The following additional rules apply to ligature formation:
letter-spacing
’, the user agent should not use
ligatures.
New in SVG 2. Added ‘white-space
’ to allow a more useful
way to control whitespace handling. Aligns SVG and HTML/CSS text
processing. ‘xml:space’ deprecated in new content, retained
for backwards compatibility.
Rendering of white space in SVG 2 is controlled by the ‘white-space
’
property. This specifies two things:
Name: | white-space |
---|---|
Value: | normal | pre | nowrap | pre-wrap | pre-line |
Initial: | not defined for shorthand properties |
Applies to: | text content elements |
Inherited: | yes |
Percentages: | N/A |
Media: | visual |
Computed value: | see individual properties |
Animatable: | yes |
Values and their meanings are defined in [CSS3 Text].
An example of using the ‘white-space
’
value pre-line.
<svg xmlns="http://www.w3.org/2000/svg"> width="200" height="200" viewBox="0 0 200 200"> <text x="150" y="30" font-family="IPAMincho" font-size="20px" writing-mode="tb-rl" white-space="pre-line">千利奴流乎和加 餘多連曽津祢那 良牟有為能於久 耶万計不己衣天 阿佐伎喩女美之 恵比毛勢須</text> </svg>
For compatibility, SVG 2 also supports the XML attribute
‘xml:space’ to specify the handling of white space
characters within a given ‘text’ element's character
data. New content should not use ‘xml:space’ but
instead, use the ‘white-space
’ property.
I think we should limit the discussion of xml:space
and just define it in the user agent style sheet to a value
of ‘white-space
’.
fantasai
agreed to add an appropriate value for ‘white-space
’ to match
SVG 1.1's odd xml:space="preserve" behaviur.
Note that any child element of a ‘text’ element may also have an ‘xml:space’ attribute which will apply to that child element's text content. The SVG user agent has special processing rules associated with this attribute as described below. These are behaviors that occur subsequent to XML parsing [XML10] and any construction of a DOM.
‘xml:space’ is an inheritable attribute which can have one of two values:
"a b"
(three spaces between "a"
and "b") will produce a larger separation between "a" and "b"
than "a b"
(one space between "a" and "b").
The following example illustrates that line indentation can be important when using xml:space="default". The fragment below show two pairs of similar ‘text’ elements, with both ‘text’ elements using xml:space="default". For these examples, there is no extra white space at the end of any of the lines (i.e., the line break occurs immediately after the last visible character).
[01] <text xml:space='default'> [02] WS example [03] indented lines [04] </text> [05] <text xml:space='preserve'>WS example indented lines</text> [06] [07] <text xml:space='default'> [08]WS example [09]non-indented lines [10] </text> [11] <text xml:space='preserve'>WS examplenon-indented lines</text>
The first pair of ‘text’ elements above show the effect of indented character data. The attribute xml:space="default" in the first ‘text’ element instructs the user agent to:
The second pair of ‘text’ elements above show the effect of non-indented character data. The attribute xml:space="default" in the third ‘text’ element instructs the user agent to:
Note that XML parsers are required to convert the standard representations for a newline indicator (e.g., the literal two-character sequence "#xD#xA" or the stand-alone literals #xD or #xA) into the single character #xA before passing character data to the application. Thus, each newline in SVG will be represented by the single character #xA, no matter what representation for newlines might have been used in the original resource. (See XML end-of-line handling.)
Any features in the SVG language or the SVG DOM that are based on character position number, such as the ‘x’, ‘y’, ‘dx’, ‘dy’ and ‘rotate’ attributes on the ‘text’ and ‘tspan’ elements, are based on character position after applying the white space handling rules described here. In particular, if xml:space="default", it is often the case that white space characters are removed as part of processing. Character position numbers index into the text string after the white space characters have been removed per the rules in this section.
Note that a glyph corresponding to a whitespace character should only be displayed as a visible but blank space, even if the glyph itself happens to be non-blank. See display of unsupported characters [UNICODE].
The ‘xml:space’ attribute is:
Animatable: no.
Older, SVG 1.1 content will use ‘xml:space’. New content,
and older content that is being reworked, will use
‘white-space
’ and remove any existing
‘xml:space’. However, user agents may come across content
which uses both methods on the same element. If
the ‘white-space
’ property is set on any element, then the
value of ‘xml:space’ is ignored.
See the CSS Text Module Level 3 specification for the definition of 'tab-size'. [CSSXX]
New in SVG 2. Added for multi-line pre-formatted and auto-wrapped text. Aligns SVG and HTML/CSS text processing.
SVG uses the ‘line-height
’ property to determine the amount
of leading space which is added between lines in multi-line text
(both for horizontal and vertical text). It is not applicable to
text on a path.
Name: | line-height |
---|---|
Value: | normal | <number> | <length> | <percentage> |
Initial: | normal |
Applies to: | text content elements |
Inherited: | yes |
Percentages: | refer to the font size of the element itself |
Media: | visual |
Computed value: | see individual properties |
Animatable: | yes |
See the CSS2.1 specification for the definition of 'line-height'. [CSS21]
See the CSS Line Layout Module 3 specification for the definition of 'line-height'. [CSS3LINEBOX] CSS 3 adds the value 'none'.
Two properties affect the space between characters and words:
letter-spacing
’ indicates an amount of space that is
to be added between text characters.
word-spacing
’ indicates the spacing behavior between words.
Note that the ‘kerning’ property
from SVG 1.1 has been removed in favor of using
‘letter-spacing
’ to add or remove spacing between glyphs
and the ‘font-kerning’ property to
disable kerning based on information from the font.
We need to require ‘font-kerning’.
Name: | 'letter-spacing' |
---|---|
Value: | normal | <length> |
Initial: | normal |
Applies to: | text content elements |
Inherited: | yes |
Percentages: | N/A |
Media: | visual |
Computed value: | 'normal' or absolute length |
Animatable: | yes |
This property specifies spacing behavior between text characters.
For SVG, if a <length> is provided without a unit identifier (e.g., an unqualified number such as 128), the SVG user agent processes the <length> as a width value in the current user coordinate system.
If a <length> is provided with one of the unit identifiers (e.g., .25em or 1%), then the SVG user agent converts the <length> into a corresponding value in the current user coordinate system by applying the rules described in Units.
Except for any additional information provided in this specification, the normative definition of the property is in CSS 2.1 ([CSS21], section 16.4).
Name: | word-spacing |
---|---|
Value: | normal | <length> |
Initial: | normal |
Applies to: | text content elements |
Inherited: | yes |
Percentages: | N/A |
Media: | visual |
Computed value: | for 'normal' the value '0'; otherwise the absolute length |
Animatable: | yes |
This property specifies spacing behavior between words. For SVG, if a <length> is provided without a unit identifier (e.g., an unqualified number such as 128), the SVG user agent processes the <length> as a width value in the current user coordinate system.
If a <length> is provided with one of the unit identifiers (e.g., .25em or 1%), then the SVG user agent converts the <length> into a corresponding value in the current user coordinate system by applying the rules described in Units.
Except for any additional information provided in this specification, the normative definition of the property is in CSS 2.1 ([CSS21], section 16.4).
SVG 2 Requirement: | Align with CSS for baseline alignment functionality. |
---|---|
Resolution: | SVG 2 will deprecate ‘baseline-shift’ and use ‘vertical-align’ instead. |
Purpose: | To align with CSS. |
Owner: | Cameron (ACTION-3281) |
'baseline-shift' is still in CSS Line Layout Module 3. It is important for aligning subscripts and superscripts (Inkscape relies on it for this purpose). 'vertical-align' is a shorthand for changing multiple properties at once, including 'baseline-shift'.
An overview of baseline alignment and baseline tables can be found above in Fonts, font tables and baselines.
One of the characteristics of international text is that there are different baselines (different alignment points) for glyphs in different scripts. For example, in horizontal writing, ideographic scripts, such as Han Ideographs, Katakana, Hiragana, and Hangul, alignment occurs with a baseline near the bottoms of the glyphs; alphabetic based scripts, such as Latin, Cyrillic, Hebrew, Arabic, align a point that is the bottom of most glyphs, but some glyphs descend below the baseline; and Indic based scripts are aligned at a point that is near the top of the glyphs.
When different scripts are mixed on a line of text, an adjustment must be made to ensure that the glyphs in the different scripts are aligned correctly with one another. OpenType [OPENTYPE] fonts have a Baseline table (BASE) [OPENTYPE-BASETABLE] that specifies the offsets of the alternative baselines from the current baseline.
SVG uses a similar baseline table model that assumes one script (at one font-size) is the "dominant run" during processing of a ‘text’ element; that is, all other baselines are defined in relation to this dominant run. The baseline of the script with the dominant run is called the dominant baseline. So, for example, if the dominant baseline is the alphabetic baseline, there will be offsets in the baseline table for the alternate baselines, such as the ideographic baseline and the Indic baseline. There will also be an offset for the math baseline which is used for some math fonts. Note that there are separate baseline tables for horizontal and vertical writing-modes. The offsets in these tables may be different for horizontal and vertical writing.
The baseline table established at the start of processing of a ‘text’ element is called the dominant baseline table.
Because the value of the ‘font-family
’ property is a list
of fonts, to insure a consistent choice of baseline table we
define the nominal font in a font list as the first font
in the list for which a glyph is available. This is the first font
that could contain a glyph for each character encountered. (For
this definition, glyph data is assumed to be present if a font
substitution is made or if the font is synthesized.) This
definition insures a content independent determination of the font
and baseline table that is to be used.
The value of the ‘font-size
’ property on the ‘text’
element establishes the dominant baseline table font size.
The model assumes that each glyph has a 'alignment-baseline' value
which specifies the baseline with which the glyph is to be
aligned. (The 'alignment-baseline' is called the "Baseline Tag" in
the OpenType baseline table description.) The initial value of
the ‘alignment-baseline
’ property uses the baseline
identifier associated with the given glyph. Alternate values
for ‘alignment-baseline
’ can be useful for glyphs such as a
"*" which are ambiguous with respect to script membership.
The model assumes that the font from which the glyph is drawn also has a baseline table, the font baseline table. This baseline table has offsets in units-per-em from the (0,0) point to each of the baselines the font knows about. In particular, it has the offset from the glyph's (0,0) point to the baseline identified by the 'alignment-baseline'.
The offset values in the baseline table are in "design units"
which means fractional units of the EM. Thus, the
current ‘font-size
’ is used to determine the actual offset
from the dominant baseline to the alternate baselines.
The glyph is aligned so that its baseline identified by its 'alignment-baseline' is aligned with the baseline with the same name from the dominant baseline table.
The offset from the dominant baseline of the parent to the baseline identified by the 'alignment-baseline' is computed using the dominant baseline table and dominant baseline table font size. The font baseline table and font size applicable to the glyph are used to compute the offset from the identified baseline to the (0,0) point of the glyph. This second offset is subtracted from the first offset to get the position of the (0,0) point in the shift direction. Both offsets are computed by multiplying the baseline value from the baseline table times the appropriate font size value.
If the 'alignment-baseline' identifies the dominant baseline, then the first offset is zero and the glyph is aligned with the dominant baseline; otherwise, the glyph is aligned with the chosen alternate baseline.
The baseline-identifiers below are used in this specification. Some of these are determined by baseline-tables contained in a font as described in XSL ([XSL], section 7.9.1). Others are computed from other font characteristics as described below.
For ideographic fonts, this baseline is often used to align the glyphs; it is an alternative to the ideographic baseline.
The position of this baseline is normally around or at the top of the ascenders, but it may not encompass all accents that can appear above a glyph. For these fonts the value of the "ascent" font characteristic is used. For ideographic fonts, the position of this baseline is normally 1 EM in the shift-direction from the "ideographic" baseline. However, some ideographic fonts have a reduced width in the inline-progression-direction to allow tighter setting. When such a font, designed only for vertical writing-modes, is used in a horizontal writing-mode, the "text-before-edge" baseline may be less than 1 EM from the text-after-edge.
For fonts with descenders, the position of this baseline is normally around or at the bottom of the descenders. For these fonts the value of the "descent" font characteristic is used. For ideographic fonts, the position of this baseline is normally at the "ideographic" baseline.
There are, in addition, two computed baselines that are only defined for line areas. Since SVG does not support the notion of computations based on line areas, the two computed baselines are mapped as follows:
There are also four baselines that are defined only for horizontal writing-modes.
See the CSS Line Layout Module 3 specification for the definition of 'dominant-baseline'. [CSSXX]
Name: | dominant-baseline |
---|---|
Value: | auto | use-script | no-change | reset-size | ideographic | alphabetic | hanging | mathematical | central | middle | text-after-edge | text-before-edge |
Initial: | auto |
Applies to: | text content elements |
Inherited: | no |
Percentages: | N/A |
Media: | visual |
Computed value: | |
Animatable: | yes |
The "dominant-baseline" property is used to determine or re-determine a scaled-baseline-table. A scaled-baseline-table is a compound value with three components: a baseline-identifier for the dominant-baseline, a baseline-table and a baseline-table font-size. Some values of the property re-determine all three values; other only re-establish the baseline-table font-size. When the initial value, auto, would give an undesired result, this property can be used to explicitly set the desire scaled-baseline-table.
Values for the property have the following meaning:
If this property occurs on a ‘text’ element, then the
computed value depends on the value of the
‘writing-mode
’ property. If the 'writing-mode' is
horizontal, then the value of the dominant-baseline component
is 'alphabetic', else if the 'writing-mode' is vertical, then
the value of the dominant-baseline component is 'central'.
If this property occurs on a ‘tspan’
or ‘textPath’ element, then the
dominant-baseline and the baseline-table components remain the
same as those of the parent text content element. If
the computed ‘baseline-shift
’ value actually shifts the
baseline, then the baseline-table font-size component is set
to the value of the ‘font-size
’ property on the element
on which the ‘dominant-baseline
’ property occurs,
otherwise the baseline-table font-size remains the same as
that of the element. If there is no parent text content element, the scaled-baseline-table value is constructed as
above for ‘text’ elements.
writing-mode
’, whether horizontal or
vertical, is used to select the appropriate set of
baseline-tables and the dominant baseline is used to select the
baseline-table that corresponds to that baseline. The
baseline-table font-size component is set to the value of
the ‘font-size
’ property on the element on which
the ‘dominant-baseline
’ property occurs.
font-size
’ property on this element. This re-scales
the baseline-table for the current ‘font-size
’.
font-size
’ property on this element.
font-size
’ property on this element.
font-size
’ property on this element.
font-size
’ property on this element.
font-size
’ property on this element.
font-size
’ property on this
element.
font-size
’ property on this
element.
Using the following priority order of baseline-table names: 'alphabetic', 'ideographic', 'hanging', 'mathematical' is probably a reasonable strategy for determining which font baseline-table to use.
font-size
’ property on this
element.
Using the following priority order of baseline-table names: 'alphabetic', 'ideographic', 'hanging', 'mathematical' is probably a reasonable strategy for determining which font baseline-table to use.
If there is no baseline table in the nominal font or if the baseline table lacks an entry for the desired baseline, then the user agent may use heuristics to determine the position of the desired baseline.
See the CSS Line Layout Module 3 specification for the definition of 'alignment-baseline'. [CSSXX]
Name: | alignment-baseline |
---|---|
Value: | auto | baseline | before-edge | text-before-edge | middle | central | after-edge | text-after-edge | ideographic | alphabetic | hanging | mathematical |
Initial: | auto |
Applies to: | ‘tspan’, ‘textPath’ elements |
Inherited: | no |
Percentages: | N/A |
Media: | visual |
Computed value: | |
Animatable: | yes |
This property specifies how an object is aligned with respect to its parent. This property specifies which baseline of this element is to be aligned with the corresponding baseline of the parent. For example, this allows alphabetic baselines in Roman text to stay aligned across font size changes. It defaults to the baseline with the same name as the computed value of the alignment-baseline property. That is, the position of "ideographic" alignment-point in the block-progression-direction is the position of the "ideographic" baseline in the baseline-table of the object being aligned.
Values have the following meanings:
See the CSS Line Layout Module 3 specification for the definition of 'baseline-shift'. [CSSXX]
Name: | baseline-shift |
---|---|
Value: | baseline | sub | super | <percentage> | <length> |
Initial: | baseline |
Applies to: | ‘tspan’, ‘textPath’ elements |
Inherited: | no |
Percentages: | refers to the "line-height" of the ‘text’ element, which
in the case of SVG is defined to be equal to the ‘font-size ’ |
Media: | visual |
Computed value: | absolute length, percentage, or keyword specified |
Animatable: | yes |
The ‘baseline-shift
’ property allows repositioning of the
dominant-baseline relative to the dominant-baseline of the
parent text content element. The shifted object might be a
sub- or superscript. Within the shifted object, the whole
baseline-table is offset; not just a single baseline. The amount
of the shift is determined from information from the
parent text content element, the sub- or superscript offset
from the nominal font of the parent text content element,
percent of the "line-height" of the parent text content element or an absolute value.
In SVG, the ‘baseline-shift
’ property represents a
supplemental adjustment to the baseline tables. The
‘baseline-shift
’ property shifts the baseline tables for
each glyph to temporary new positions, for example to lift the
glyph into superscript or subscript position, but it does not
affect the current text position. When the current text position
is adjusted after rendering a glyph to take into account glyph
advance values, the adjustment happens as if there were no
baseline shift.
‘baseline-shift
’ properties can nest. Each nested
‘baseline-shift
’ is added to previous baseline shift
values.
Values for the property have the following meaning:
SVG 2 Requirement: | Reference CSS3 Fonts. |
---|---|
Resolution: | SVG 2 will depend on CSS3 Fonts. |
Purpose: | Alignment with CSS 2.1 and CSS3 for Web font functionality, and to provide access to advanced typographic features of fonts. |
Owner: | Chris (ACTION-3123) |
SVG relies on the CSS font selection mechanism as described in CSS Font Module Level 3 ([CSS3FONTS]), except as noted below.
CSS Font Module Level 3 changes the meaning of the 'font-variant' property from that defined by CSS 2.1. It has been repurposed (and function greatly expanded) as a shorthand for selecting font variants from within a single font.
Name: | font-family |
---|---|
Value: | [[ <family-name> | <generic-family> ],]* [<family-name> | <generic-family>] |
Initial: | depends on user agent |
Applies to: | text content elements |
Inherited: | yes |
Percentages: | N/A |
Media: | visual |
Computed value: | |
Animatable: | yes |
This property indicates which font family is to be used to render the text, specified as a prioritized list of font family names and/or generic family names. Unless the family name corresponds to a CSS IDENT, it must be quoted. Except for any additional information provided in this specification, the normative definition of the property is in CSS 2.1 ([CSS21], section 15.3).
Name: | font-style |
---|---|
Value: | normal | italic | oblique |
Initial: | normal |
Applies to: | text content elements |
Inherited: | yes |
Percentages: | N/A |
Media: | visual |
Computed value: | |
Animatable: | yes |
This property specifies whether the text is to be rendered using a normal, italic or oblique face. Except for any additional information provided in this specification, the normative definition of the property is in CSS 2.1 ([CSS21], section 15.4).
Name: | font-variant |
---|---|
Value: | normal | small-caps |
Initial: | normal |
Applies to: | text content elements |
Inherited: | yes |
Percentages: | N/A |
Media: | visual |
Computed value: | |
Animatable: | yes |
This property indicates whether the text is to be rendered using the normal glyphs for lowercase characters or using small-caps glyphs for lowercase characters. Except for any additional information provided in this specification, the normative definition of the property is in CSS 2.1 ([CSS21], section 15.5).
Name: | font-weight |
---|---|
Value: | normal | bold | bolder | lighter | 100 | 200 |
300 | 400 | 500 | 600 | 700 | 800 | 900 |
Initial: | normal |
Applies to: | text content elements |
Inherited: | yes |
Percentages: | N/A |
Media: | visual |
Computed value: | |
Animatable: | yes |
This property refers to the boldness or lightness of the glyphs used to render the text, relative to other fonts in the same font family. Except for any additional information provided in this specification, the normative definition of the property is in CSS 2.1 ([CSS21], section 15.6).
Name: | font-stretch |
---|---|
Value: | normal | wider | narrower | ultra-condensed | extra-condensed | condensed | semi-condensed | semi-expanded | expanded | extra-expanded | ultra-expanded |
Initial: | normal |
Applies to: | text content elements |
Inherited: | yes |
Percentages: | N/A |
Media: | visual |
Computed value: | |
Animatable: | yes |
This property indicates the desired amount of condensing or expansion in the glyphs used to render the text. Except for any additional information provided in this specification, the normative definition of the property is in CSS3 Fonts ([CSS3FONTS], section 3.3).
Name: | font-size |
---|---|
Value: | <absolute-size> | <relative-size>
| <length> | <percentage> |
Initial: | medium |
Applies to: | text content elements |
Inherited: | yes, the computed value is inherited |
Percentages: | refer to parent element's font size |
Media: | visual |
Computed value: | |
Animatable: | yes |
This property refers to the size of the font from baseline to baseline when multiple lines of text are set solid in a multi-line layout environment. For SVG, if a <length> is provided without a unit identifier (e.g., an unqualified number such as 128), the SVG user agent processes the <length> as a height value in the current user coordinate system.
If a <length> is provided with one of the unit identifiers (e.g., 12pt or 10%), then the SVG user agent converts the <length> into a corresponding value in the current user coordinate system by applying the rules described in Units.
Except for any additional information provided in this specification, the normative definition of the property is in CSS 2.1 ([CSS21], section 15.7).
Name: | font-size-adjust |
---|---|
Value: | <number> | none |
Initial: | none |
Applies to: | text content elements |
Inherited: | yes |
Percentages: | N/A |
Media: | visual |
Computed value: | |
Animatable: | yes |
This property allows authors to specify an aspect value for an element that will preserve the x-height of the first choice font in a substitute font. Except for any additional information provided in this specification, the normative definition of the property is in CSS3 Fonts ([CSS3FONTS], section 3.6).
Name: | font |
---|---|
Value: | [ [ <'font-style'>
|| <'font-variant'>
|| <'font-weight'>
]? <'font-size'> [ / <'line-height'> ]? <'font-family'> ] | caption | icon | menu | message-box | small-caption | status-bar |
Initial: | see individual properties |
Applies to: | text content elements |
Inherited: | yes |
Percentages: | allowed on 'font-size' and 'line-height' (Note:
for the purposes of processing the ‘font ’ property in
SVG, 'line-height' is assumed to be equal the value
for property ‘font-size ’) |
Media: | visual |
Computed value: | |
Animatable: | yes (non-additive) |
Shorthand property for setting ‘font-style
’,
‘font-variant
’, ‘font-weight
’, ‘font-size
’,
‘line-height’ and
‘font-family
’. The ‘line-height’
property has no effect on text layout in SVG. For the purposes of
the ‘font
’ property,
‘line-height’ is assumed to be equal
to the value of the ‘font-size
’ property.
Conforming SVG
Viewers are not required to support the various system font
options (caption, icon, menu, message-box, small-caption and
status-bar) and can use a system font or one of the generic fonts
instead.
Except for any additional information provided in this specification, the normative definition of the property is in CSS 2.1 ([CSS21], section 15.8).
Text in SVG can be decorated with an underline, overline,
and/or strike-through. The position and style of the decoration is
determined respectively by the ‘text-decoration-line
’ and
‘text-decoration-style
’ properties, or by
the ‘text-decoration
’ shorthand property as defined in the
Line
Decoration section of the
CSS Text
Decoration Module Level 3
[(CSS3TEXTDECOR)]
specification. The fill and stroke of the decoration are given by
the ‘text-decoration-fill
’ and
‘text-decoration-stroke
’ properties. If a color value is
specified either by the ‘text-decoration-color
’ property or
by the ‘text-decoration
’ shorthand, and no
‘text-decoration-fill
’ property is specified, it is
interpreted as if the ‘text-decoration-fill
’ property were
specified with that color value.
If the fill or stroke of the text decoration are not explicitly
specified (via ‘text-decoration
’, ‘text-decoration-color
’,
‘text-decoration-fill
’, or ‘text-decoration-stroke
’),
they are given by the fill and stroke of the text at the point
where the text decoration is declared (see example below).
The ‘text-decoration-line
’ and
‘text-decoration-style
’ properties are new in SVG 2. The
SVG 1.1/CSS 2.1 ‘text-decoration
’ property is transformed
in a backwards compatible way to a short hand for these
properties. ‘text-decoration-fill
’ and
‘text-decoration-stroke
’ are SVG specific properties which
may added to a future level of the CSS Text Decoration
specification.
The order in which the text and decorations are drawn is defined
by the
Painting
Order of Text Decorations section of
CSS Text
Decoration Module Level 3. The paint order of the text
decoration itself (fill/stroke) is determined by the value of the
‘paint-order
’ property at the point where the text
decoration is declared.
Example textdecoration01 provides
examples for ‘text-decoration
’. The first line of text has
no value for ‘text-decoration
’, so the initial value
of text-decoration:none is
used. The second line shows
text-decoration:line-through. The
third line shows
text-decoration:underline. The
fourth line illustrates the rule whereby decorations are rendered
using the same fill and stroke properties as are present on the
element for which the ‘text-decoration
’ is specified. Since
‘text-decoration
’ is specified on the ‘text’
element, all text within the ‘text’ element has its
underline rendered with the same fill and stroke properties as
exist on the ‘text’ element (i.e., blue fill, red stroke),
even though the various words have different fill and stroke
property values. However, the word "different" explicitly
specifies a value for ‘text-decoration
’; thus, its
underline is rendered using the fill and stroke properties as
the ‘tspan’ element that surrounds the word "different"
(i.e., yellow fill, darkgreen stroke):
<?xml version="1.0" standalone="no"?> <svg width="12cm" height="4cm" viewBox="0 0 1200 400" xmlns="http://www.w3.org/2000/svg" version="1.1"> <desc>Example textdecoration01 - behavior of 'text-decoration' property</desc> <rect x="1" y="1" width="1198" height="398" fill="none" stroke="blue" stroke-width="2" /> <g font-size="60" fill="blue" stroke="red" stroke-width="1" > <text x="100" y="75">Normal text</text> <text x="100" y="165" text-decoration="line-through" >Text with line-through</text> <text x="100" y="255" text-decoration="underline" >Underlined text</text> <text x="100" y="345" text-decoration="underline" > <tspan>One </tspan> <tspan fill="yellow" stroke="purple" >word </tspan> <tspan fill="yellow" stroke="black" >has </tspan> <tspan fill="yellow" stroke="darkgreen" text-decoration="underline" >different </tspan> <tspan fill="yellow" stroke="blue" >underlining</tspan> </text> </g> </svg>
The CSS working group agreed to the SVG specification of the 'text-decoration-fill' and 'text-decoration-stroke' properties at the joint CSS/SVG 2014 TPAC meeting. They again endorsed the use of these properties at the joint 2015 Sydney meeting. They expressed their intention to extend CSS text decoration to include these properties at the same time they allow 'fill' and 'stroke' properties on text.
Name: | text-decoration-fill |
---|---|
Value: | <paint> |
Initial: | See prose. |
Applies to: | text content elements |
Inherited: | See prose. |
Percentages: | N/A |
Media: | visual |
Computed value: | as specified, but with <color> values computed and <url> values made absolute. |
Animatable: | yes |
Name: | text-decoration-stroke |
---|---|
Value: | <paint> |
Initial: | See prose. |
Applies to: | text content elements |
Inherited: | See prose. |
Percentages: | N/A |
Media: | visual |
Computed value: | as specified, but with <color> values computed and <url> values made absolute. |
Animatable: | yes |
Conforming SVG viewers on systems which have the capacity for text selection (e.g., systems which are equipped with a pointer device such as a mouse) and which have system clipboards for copy/paste operations are required to support:
A text selection operation starts when all of the following occur:
As the text selection operation proceeds (e.g., the user continues to press the given mouse button), all associated events with other graphics elements are ignored (i.e., the text selection operation is modal) and the SVG user agent shall dynamically indicate which characters are selected by an appropriate highlighting technique, such as redrawing the selected glyphs with inverse colors. As the pointer is moved during the text selection process, the end glyph for the text selection operation is the glyph within the same ‘text’ element whose glyph cell is closest to the pointer. All characters within the ‘text’ element whose position within the ‘text’ element is between the start of selection and end of selection shall be highlighted, regardless of position on the canvas and regardless of any graphics elements that might be above the end of selection point.
Once the text selection operation ends (e.g., the user releases the given mouse button), the selected text will stay highlighted until an event occurs which cancels text selection, such as a pointer device activation event (e.g., pressing a mouse button).
Detailed rules for determining which characters to highlight during a text selection operation are provided in Text selection implementation notes.
For systems which have system clipboards, the SVG user agent is required to provide a user interface for initiating a copy of the currently selected text to the system clipboard. It is sufficient for the SVG user agent to post the selected text string in the system's appropriate clipboard format for plain text, but it is preferable if the SVG user agent also posts a rich text alternative which captures the various font properties associated with the given text string.
For bidirectional text, the user agent must support text selection in logical order, which will result in discontinuous highlighting of glyphs due to the bidirectional reordering of characters. User agents can provide an alternative ability to select bidirectional text in visual rendering order (i.e., after bidirectional text layout algorithms have been applied), with the result that selected character data might be discontinuous logically. In this case, if the user requests that bidirectional text be copied to the clipboard, then the user agent is required to make appropriate adjustments to copy only the visually selected characters to the clipboard.
When feasible, it is recommended that generators of SVG attempt to order their text strings to facilitate properly ordered text selection within SVG viewing applications such as Web browsers.
SVG 2 Requirement: | Have a DOM method to convert a ‘text’ element to outline path data. |
---|---|
Resolution: | We will add a DOM method to convert a ‘text’ element to outline path data, possibly moving the functionality to the FXTF. |
Purpose: | To allow manipualtion of text as a path. |
Owner: | Cameron (ACTION-3076) |
The SVGTextContentElement is inherited by various text-related interfaces, such as SVGTextElement, SVGTSpanElement, and SVGTextPathElement.
For the methods on this interface that refer to an index to a character or a number of characters, these references are to be interpreted as an index to a UTF-16 code unit or a number of UTF-16 code units, respectively. This is for consistency with DOM Level 2 Core, where methods on the CharacterData interface use UTF-16 code units as indexes and counts within the character data. Thus for example, if the text content of a ‘text’ element is a single non-BMP character, such as U+10000, then invoking getNumberOfChars on that element will return 2 since there are two UTF-16 code units (the surrogate pair) used to represent that one character.
interface SVGTextContentElement : SVGGraphicsElement { // lengthAdjust Types const unsigned short LENGTHADJUST_UNKNOWN = 0; const unsigned short LENGTHADJUST_SPACING = 1; const unsigned short LENGTHADJUST_SPACINGANDGLYPHS = 2; readonly attribute SVGAnimatedLength textLength; readonly attribute SVGAnimatedEnumeration lengthAdjust; long getNumberOfChars(); float getComputedTextLength(); float getSubStringLength(unsigned long charnum, unsigned long nchars); DOMPoint getStartPositionOfChar(unsigned long charnum); DOMPoint getEndPositionOfChar(unsigned long charnum); DOMRect getExtentOfChar(unsigned long charnum); float getRotationOfChar(unsigned long charnum); long getCharNumAtPosition(DOMPoint point); void selectSubString(unsigned long charnum, unsigned long nchars); };
letter-spacing
’ and ‘word-spacing
’ and
adjustments due to attributes ‘dx’ and ‘dy’ on
‘tspan’ elements. For non-rendering environments, the user agent
shall make reasonable assumptions about glyph metrics.letter-spacing
’ and ‘word-spacing
’ and adjustments due to
attributes ‘dx’ and ‘dy’ on ‘tspan’ elements. For
non-rendering environments, the user agent shall make reasonable
assumptions about glyph metrics. If multiple consecutive characters are
rendered inseparably (e.g., as a single glyph or a sequence of glyphs,
or because the range encompasses half of a surrogate pair), and nchars
is greater than 0 then the measured range shall be expanded so that each
of the inseparable characters are included.letter-spacing
’ and
‘word-spacing
’ and adjustments due to attributes
‘x’, ‘y’,
‘dx’ and
‘dy’. If multiple consecutive characters
are rendered inseparably (e.g., as a single glyph or a sequence of
glyphs), then each of the inseparable characters will return the start
position for the first glyph.letter-spacing
’ and ‘word-spacing
’ and adjustments due to
attributes ‘x’,
‘y’, ‘dx’
and ‘dy’. If multiple consecutive
characters are rendered inseparably (e.g., as a single glyph or a
sequence of glyphs), then each of the inseparable characters will
return the end position for the last glyph.glyph-orientation-horizontal
’ and
‘glyph-orientation-vertical
’; thus, any glyph rotations due to
these properties are not included into the returned rotation value. If
multiple consecutive characters are rendered inseparably (e.g., as a
single glyph or a sequence of glyphs), then each of the inseparable
characters will return the same rotation value.Selects a substring of the text in this element, beginning at character index charnum and extending forwards nchars characters. The following steps must be followed when this method is called:
Ignoring the argument checking and exception throwing, this is equivalent to performing the following:
var selection = document.getSelection(); selection.removeAllRanges(); var range = new Range(); range.setStart(textContentElement, charnum); range.setEnd(textContentElement, charnum + nchars); selection.addRange(range);
This method is deprecated, as it duplicates functionality from the Selection API.
interface SVGTextPositioningElement : SVGTextContentElement { readonly attribute SVGAnimatedLengthList x; readonly attribute SVGAnimatedLengthList y; readonly attribute SVGAnimatedLengthList dx; readonly attribute SVGAnimatedLengthList dy; readonly attribute SVGAnimatedNumberList rotate; };
interface SVGTextElement : SVGTextPositioningElement { };
interface SVGTSpanElement : SVGTextPositioningElement { };
interface SVGTextPathElement : SVGTextContentElement { // textPath Method Types const unsigned short TEXTPATH_METHODTYPE_UNKNOWN = 0; const unsigned short TEXTPATH_METHODTYPE_ALIGN = 1; const unsigned short TEXTPATH_METHODTYPE_STRETCH = 2; // textPath Spacing Types const unsigned short TEXTPATH_SPACINGTYPE_UNKNOWN = 0; const unsigned short TEXTPATH_SPACINGTYPE_AUTO = 1; const unsigned short TEXTPATH_SPACINGTYPE_EXACT = 2; readonly attribute SVGAnimatedLength startOffset; readonly attribute SVGAnimatedEnumeration method; readonly attribute SVGAnimatedEnumeration spacing; }; SVGTextPathElement implements SVGURIReference;
Graphical elements that define a shape – ‘path’ elements, basic shapes, and text content elements – are rendered by being filled, which is painting the interior of the object, and stroked, which is painting along the outline of the object. Filling and stroking are both painting operations. SVG 2 supports a number of different paints that the fill and stroke of a graphical element can be painted with:
The paint to use for filling and stroking an element is specified using the
‘fill
’ and ‘stroke
’ properties. The following section describes
the different values that can be used for these properties.
Other properties, such as ‘fill-opacity
’ and ‘stroke-width
’,
also have an effect on the way fill and stroke paint is applied to the
canvas. The Fill properties and Stroke properties
sections below describe these properties.
Some graphics elements – ‘path’ elements and basic shapes – can also have marker symbols drawn at their vertices or at other positions along the path that they describe. The Markers section below describes how markers can be defined and used.
SVG 2 adds markers on shapes. Resolved at Tokyo F2F.
SVG 2 Requirement: | Add new paint values for referencing current fill paint, stroke paint, etc. |
---|---|
Resolution: | We will add new paint values currentFillPaint, currentStrokePaint etc. to SVG 2 |
Purpose: | Among other things, to provide an easy way to match marker color to stroke color. |
Owner: | Chris (ACTION-3094) |
SVG 2 Addition: | Allow multiple paints in fill and stroke. |
---|---|
Resolution: | We will allow multiple paints in the fill and stroke properties in SVG 2. |
Purpose: | Useful for creating cross hatchings, putting a partially transparent pattern on top of a solid fill, etc. |
Owner: | Tav (ACTION-3500) |
Properties ‘fill
’ and ‘stroke
’ take on a comma separated list of values of type <paint>. Each paint is applied to an element in reverse order. Note, only a paint server in the last position may take an optional fallback color.
The ability to apply more than one paint to an element is new in SVG 2.
The paint order follows that of CSS backgrounds.
<rect width="100" height="100" fill="url(#MyHatch1), url(#MyHatch2), powderblue">
The type <paint> is defined as:
<paint> = [ <paint-layer> , ]* <final-paint-layer>
<paint-layer> = <paint-source>|| <position> [ / <paint-size> ]? || <repeat-style> || [ <shape-box> | fill | stroke | view-box ] || [ <shape-box> | fill | stroke | view-box ]
<final-paint-layer> = <paint-source> || <position> [ / <paint-size> ]? || <repeat-style> || [ <shape-box> | fill | stroke | view-box ] || [ <shape-box> | fill | stroke | view-box ] || <color>
<paint-source> = none | <image> | <url> | context-fill | context-stroke
Values have the following meaning:
color
’ property.Changed from SVG 1.1 behavior where document is in error if paint server missing or invalid.
<rect width="100" height="100" fill="url(#MyHatch1), url(#MyHatch2) powderblue">
How should 'child' behave with allowing multiple paints?
This section needs additional examples, especially one with 'child'.
fill
’ or ‘stroke
’
property, respectively, of the context element. If there
is no context element, then no paint is applied. If the referenced paint
is a gradient or a pattern, then the coordinate space to use and the
object used for any 'objectBoundingBox'-relative
values are the same as those of the context element.Should gradient elements also be context elements?
See the CSS Color Module Level 3 specification for the
definition of ‘color
’.
[CSS3COLOR]
The ‘color
’ property is used to provide a potential indirect value,
currentColor, for the ‘fill
’,
‘stroke
’, ‘solid-color
’, ‘stop-color
’, ‘flood-color
’ and
‘lighting-color
’ properties. The property has no other effect
on SVG elements.
The following example shows how the inherited value of the
‘color
’ property from an HTML document can be used to
set the color of SVG text in an inline SVG fragment.
<!DOCTYPE html> <style> body { color: #468; font: 16px sans-serif } svg { border: 1px solid #888; background-color: #eee } </style> <p>Please see the diagram below:</p> <svg width="200" height="100"> <g fill="currentColor"> <text x="70" y="55" text-anchor="end">START</text> <text x="130" y="55">STOP</text> <path d="M 85,45 h 25 v -5 l 10,10 -10,10 v -5 h -25 z"/> </g> </svg>
Please see the diagram below:
Name: | fill |
---|---|
Value: | <paint> |
Initial: | black |
Applies to: | shapes and text content elements |
Inherited: | yes |
Percentages: | N/A |
Media: | visual |
Computed value: | as specified, but with <color> values computed and <url> values made absolute |
Animatable: | yes |
The ‘fill
’ property paints the interior of the given graphical
element. The area to be painted consists of any areas inside the outline
of the shape. To determine the inside of the shape, all subpaths are
considered, and the interior is determined according to the rules
associated with the current value of the ‘fill-rule
’ property.
The zero-width geometric outline of a shape is included in the area to
be painted.
The fill operation fills open subpaths by performing the fill operation as if an additional "closepath" command were added to the path to connect the last point of the subpath with the first point of the subpath. Thus, fill operations apply to both open subpaths within ‘path’ elements (i.e., subpaths without a closepath command) and ‘polyline’ elements.
Name: | fill-rule |
---|---|
Value: | nonzero | evenodd |
Initial: | nonzero |
Applies to: | shapes and text content elements |
Inherited: | yes |
Percentages: | N/A |
Media: | visual |
Computed value: | as specified |
Animatable: | yes |
The ‘fill-rule
’ property indicates the algorithm (or
winding rule) which is to
be used to determine what parts of the canvas are included inside the
shape. For a simple, non-intersecting path, it is intuitively clear
what region lies "inside"; however, for a more complex path, such as a
path that intersects itself or where one subpath encloses another, the
interpretation of "inside" is not so obvious.
The ‘fill-rule
’ property provides two options for how the
inside of a shape is determined:
This rule determines the "insideness" of a point on the canvas by drawing a ray from that point to infinity in any direction and then examining the places where a segment of the shape crosses the ray. Starting with a count of zero, add one each time a path segment crosses the ray from left to right and subtract one each time a path segment crosses the ray from right to left. After counting the crossings, if the result is zero then the point is outside the path. Otherwise, it is inside. The following drawing illustrates the nonzero rule:
This rule determines the "insideness" of a point on the canvas by drawing a ray from that point to infinity in any direction and counting the number of path segments from the given shape that the ray crosses. If this number is odd, the point is inside; if even, the point is outside. The following drawing illustrates the evenodd rule:
The above descriptions do not specify what to do if a path segment coincides with or is tangent to the ray. Since any ray will do, one may simply choose a different ray that does not have such problem intersections.
Name: | fill-opacity |
---|---|
Value: | <number> |
Initial: | 1 |
Applies to: | shapes and text content elements |
Inherited: | yes |
Percentages: | N/A |
Media: | visual |
Computed value: | as specified, but clamped to the range [0, 1] |
Animatable: | yes |
‘fill-opacity
’ specifies the
opacity of the painting operation used to paint the interior
the current object. (See Painting shapes and
text.) A value of 0 means fully transparent, and a
value of 1 means fully opaque.
See also the ‘opacity
’ property, which
specifies group opacity.
SVG 2 Requirement: | Support non-scaling stroke. |
---|---|
Resolutions: | SVG 2 will include non-scaling stroke. SVG 2 will have the ‘vector-effect’ property. |
Purpose: | To support strokes whose width does not change when zooming a page, as common for example in maps. |
Owner: | Chris or Erik (no action) |
Note: | Note that this could be part of more generic non-scaling features. |
In this section, we define a number of properties that allow the author to control different aspects of a stroke, including its paint, thickness, use of dashing, and joining and capping of path segments.
In all cases, all stroking properties which are affected by directionality, such as those having to do with dash patterns, must be rendered such that the stroke operation starts at the same point at which the graphics element starts. In particular, for ‘path’ elements, the start of the path is the first point of the initial "moveto" command.
For stroking properties such as dash patterns whose computations are dependent on progress along the outline of the graphics element, distance calculations are required to utilize the SVG user agent's standard Distance along a path algorithms.
When stroking is performed using a complex paint server, such as a gradient or a pattern, the stroke operation must be identical to the result that would have occurred if the geometric shape defined by the geometry of the current graphics element and its associated stroking properties were converted to an equivalent ‘path’ element and then filled using the given paint server.
Name: | stroke |
---|---|
Value: | <paint> |
Initial: | none |
Applies to: | shapes and text content elements |
Inherited: | yes |
Percentages: | N/A |
Media: | visual |
Computed value: | as specified, but with <color> values computed and <url> values made absolute |
Animatable: | yes |
The ‘stroke
’ property paints along the outline of the given
graphical element.
Note that when stroking a ‘path’ element,
any subpath consisting of a moveto
but no following line drawing command will not be stroked.
Any other type of zero-length subpath, such as
'M 10,10 L 10,10'
or 'M 30,30 Z'
will also not be stroked if the ‘stroke-linecap
’ property has a value of
butt. See the definition of
the stroke shape below for the details of computing
the stroke of a path.
SVG 2 Requirement: | Include a way to specify stroke position. |
---|---|
Resolution: | SVG 2 shall include a way to specify stroke position. |
Purpose: | To allow a stroke to be inside or outside the path. |
Owner: | Cameron (ACTION-3162) |
Note: | See proposal page. |
Name: | stroke-opacity |
---|---|
Value: | <number> |
Initial: | 1 |
Applies to: | shapes and text content elements |
Inherited: | yes |
Percentages: | N/A |
Media: | visual |
Computed value: | as specified, but clamped to the range [0, 1] |
Animatable: | yes |
The ‘stroke-opacity
’ property specifies the opacity of the
painting operation used to stroke the current object. (See
Painting shapes and text.)
As with ‘fill-opacity
’, a value of 0 means fully transparent, and a value of 1
means fully opaque.
See also the ‘opacity
’ property, which specifies
group opacity.
Name: | stroke-width |
---|---|
Value: | <percentage> | <length> |
Initial: | 1 |
Applies to: | shapes and text content elements |
Inherited: | yes |
Percentages: | refer to the size of the current viewport (see Units) |
Media: | visual |
Computed value: | absolute length or percentage |
Animatable: | yes |
This property specifies the width of the stroke on the current object. A zero value causes no stroke to be painted. A negative value is invalid.
Name: | stroke-linecap |
---|---|
Value: | butt | round | square |
Initial: | butt |
Applies to: | shapes and text content elements |
Inherited: | yes |
Percentages: | N/A |
Media: | visual |
Computed value: | as specified |
Animatable: | yes |
‘stroke-linecap
’ specifies the shape to be used at the end of
open subpaths when they are stroked. The possible values are:
This value indicates that at each end of each subpath, the shape representing the stroke will be extended by a half circle with a radius equal to the stroke width. If a subpath has zero length, then the resulting effect is that the stroke for that subpath consists solely of a full circle centered at the subpath's point.
This value indicates that at the end of each subpath, the shape representing the stroke will be extended by a rectangle with the same width as the stroke width and whose length is half of the stroke width. If a subpath has zero length, then the resulting effect is that the stroke for that subpath consists solely of a square with side length equal to the stroke width, centered at the subpath's point, and oriented such that two of its sides are parallel to the effective tangent at that subpath's point. See ‘path’ element implementation notes for details on how to determine the tangent at a zero-length subpath.
See the definition of the cap shape below for a more precise description of the shape a line cap will have.
Name: | stroke-linejoin |
---|---|
Value: | miter | miter-clip | round | bevel | arcs |
Initial: | miter |
Applies to: | shapes and text content elements |
Inherited: | yes |
Percentages: | N/A |
Media: | visual |
Computed value: | as specified |
Animatable: | yes |
‘stroke-linejoin
’ specifies the shape to be used at the
corners of paths or basic shapes when they are stroked. For further details see
the path implementation notes.
stroke-miterlimit
’
is exceeded, the line join falls back to bevel
(see below).stroke-miterlimit
’ is exceeded, the miter is clipped at a
miter length equal to the ‘stroke-miterlimit
’ value multiplied
by the stroke width (see below).The miter-clip and arcs values are new in SVG 2. The miter-clip value offers a more consistent presentation for a path with multiple joins as well as better behavior when a path is animated. The arcs value provides a better looking join when the path segments at the join are curved.
Adding 'arcs' line join was resolved at the Rigi Kaltbad group meeting.
Adding 'miter-clip' line join was resolved at the Sydney (2015) group meeting.
Name: | stroke-miterlimit |
---|---|
Value: | <number> |
Initial: | 4 |
Applies to: | shapes and text content elements |
Inherited: | yes |
Percentages: | N/A |
Media: | visual |
Computed value: | as specified |
Animatable: | yes |
When two line segments meet at a sharp angle and a value of
miter,
miter-clip, or
arcs has been specified for
‘stroke-linejoin
’, it is possible for the join to extend
far beyond the thickness of the line stroking the path. The
‘stroke-miterlimit
’ imposes a limit on the extent of the
line join.
stroke-width
’ value. The value of
‘stroke-miterlimit
’ must be a <number> greater
than or equal to 1. Any other value is an error (see
Error processing).
For the miter or the miter-clip values, given the angle θ between the segments in local coordinate system, the miter length is calculated by:
miter length = stroke-width / sin(theta / 2)
If the miter length divided by the stroke width exceeds the
‘stroke-miterlimit
’ then for the value:
For the arcs value, the
miter length is calculated along a circular arc that is
tangent to the line bisecting the angle between the two segments at
the point the two segments intersect and passes through the end
point of the join. The line join is clipped, if necessary, by a line
perpendicular to this arc at a miter length equal to the
value of the ‘stroke-miterlimit
’ value multiplied by the
stroke width.
The effect of 'stroke-miterlimit' on an 'arcs' line join was resolved at Sydney (2015) group meeting.
See the definition of the line join shape below for a more precise description of the shape a line join will have.
Name: | stroke-dasharray |
---|---|
Value: | none | <dasharray> |
Initial: | none |
Applies to: | shapes and text content elements |
Inherited: | yes |
Percentages: | refer to the size of the current viewport (see Units) |
Media: | visual |
Computed value: | absolute lengths or percentages for <dasharray>, or keyword specified |
Animatable: | yes (non-additive) |
where:
<dasharray> = [ <length> | <percentage> | <number> ]#*
The ‘stroke-dasharray
’ property controls
the pattern of dashes and gaps used to form the shape of
a path's stroke.
Specifies a dashing pattern to use. A <dasharray> is a list of comma and/or white space separated lengths or percentages. Each value specifies a length along the path for which the stroke is to be painted (a dash) and not painted (a gap). The first value and every second value in the list after it specifies the length of a dash, and every other value specifies the length of a gap between the dashes. If the list has an odd number of values, then it is repeated to yield an even number of values. (Thus, the rendering behavior of stroke-dasharray: 5,3,2 is equivalent to stroke-dasharray: 5,3,2,5,3,2.)
The resulting even-length dashing pattern is repeated along each subpath. The dashing pattern is reset and begins again at the start of each subpath.
If any value in the list is negative, the <dasharray> value is invalid. If all of the values in the list are zero, then the stroke is rendered as a solid line without any dashing.
Name: | stroke-dashoffset |
---|---|
Value: | <length> | <percentage> |
Initial: | 0 |
Applies to: | shapes and text content elements |
Inherited: | yes |
Percentages: | refer to the size of the current viewport (see Units) |
Media: | visual |
Computed value: | absolute length or percentage |
Animatable: | yes |
The ‘stroke-dashoffset
’ property specifies the distance into the repeated
dash pattern to start the stroke dashing at the beginning of the path. If the
value is negative, then the effect is the same as dash offset d:
d = s - (abs(stroke-dashoffset) mod s)
where s is the sum of the dash array values.
See the definition of dash positions below for a more precise description of positions along a path that dashes will be placed.
SVG 2 Requirement: | Specify stroke dashing more precisely. |
---|---|
Resolution: | SVG 2 shall specify stroke dashing more precisely. |
Purpose: | To define dash starting point on basic shapes and path segments. |
Owner: | Cameron (no action) |
Something in this section needs to reference ‘pathLength’ so that dash lengths are in the author's path length space.
The stroke shape of an element is the
shape that is filled by the ‘stroke
’ property. Since ‘text’
elements can be rendered in multiple chunks, each chunk has its own
stroke shape. The following algorithm describes what the stroke shape
of a ‘path’, basic shape or individual ‘text’ chunk is,
taking into account the stroking properties above:
stroke-width
’ of
the point on the subpath at that position.It does not matter whether any zero length segments are included when choosing index and last.
The dash positions for a given subpath of the equivalent path of a ‘path’ or basic shape is a sequence of pairs of values, which represent the starting and ending distance along the subpath for each of the dashes that form the subpath's stroke. It is determined as follows:
stroke-dasharray
’
on the element, converted to user units, repeated if necessary so that it has
an even number of elements; if the property has the value
none, then the list has a single value 0.stroke-dashoffset
’
property on the element.The starting and ending cap shapes at a given position along a subpath are determined as follows:
stroke-linecap
’ is butt, then return an empty shape.stroke-linecap
’ is round, then:
stroke-width
’ positioned such that:
stroke-width
’ positioned such that:
stroke-linecap
’ is square:
stroke-width
’ and ‘stroke-width
’ / 2 positioned such that:
stroke-width
’ and ‘stroke-width
’ / 2 positioned such that:
The line join shape for a given segment of a subpath is determined as follows:
stroke-width
’ / 2 to the
left and to the right of A relative to the subpath direction, respectively.stroke-width
’ / 2 to the
left and to the right of B, relative to the subpath direction, respectively.stroke-linejoin
’ is round, then
return the union of bevel and a circular sector of radius
‘stroke-width
’, centered on P, and which has
P1 and P2 as the two endpoints of
the arc.stroke-linejoin
’ is arcs,
then find the circles that are tangent to the stroke edges at
P1 and P2 with the
same curvature as the edges at those points (see below). If both
curvatures are zero fall through to miter-clip.
Extend the stroke edges using these circles (or a line, in the case
of zero curvature). If the two circles (or circle and line) do not
intersect, fall through to miter-clip.
If the two circles (or circle and line) intersect, the line join
region is defined by the lines that connect P
with P1 and P2 and the
arcs defined by the circles (or arc and line) between the closest
intersection point to P, and P1
and P2.
Next calculate the miter limit as defined in
the ‘stroke-miterlimit
’ section. Clip any part of the line
join region that extends past the miter limit. Return the
resulting region.
Note that the curvatures are calculated in user-space before any
transforms are applied.stroke-linejoin
’ is miter or
miter-clip then the line join
region is the union of bevel and the triangle formed
from the three points P1,
P2 and P3.
stroke-miterlimit
’, then return
the line join region.
stroke-linejoin
’ is miter-clip,
then clip any part of the line join region that extends past the
miter limit and return this region.
The arcs ‘stroke-linejoin
’
requires finding circles that are both tangent to and have the same
curvatures as the outer stroke edges at the ends of path
segments. To find one of these circles, first calculate the
curvature κ of the path segment at its end (see
below). Next, find the radius of a circle corresponding to this
curvature: r = 1/κ. Increase or
decrease the radius by one half of the stroke width to account for
the stroke: rc = r ± ½
stroke-width. The center of the circle will be on a line normal to
the path end a distance of rc away from the
outer stroke edge at the end.
For a line: the curvature is infinite. Extend the outer stroke edge by a line.
For an elliptical arc:
$$\kappa(t) = {{r_x r_y}\over{(r_x^2 \sin^2 t + r_y^2 \cos^2 t)^{3/2}}}$$
where:
$$t = \arctan ( {r_y \over r_x} \tan \theta )$$
The parameter θ at the beginning or end of an arc segment can be found by using the formulas in the Elliptical arc implementation notes. (Note, some renderers convert elliptical arcs to cubic Béziers prior to rendering so the equations here may not be needed.)
For a quadratic Bézier:
$$\kappa(0) = {2\over3}{(P_1-P_0)\times((P_0-P_1)+(P_2-P_1))\over|P_1-P_0|^3}$$
$$\kappa(0) = {2\over3}{(P_1-P_0)\times((P_0-P_1)+(P_2-P_1))\over|P_1-P_0|^3}$$
Where κ(0) and κ(1) are the signed curvatures at the start and end of the path segment respectively, and the P's are the three points that define the quadratic Bézier.
For a cubic Bézier:
$$\kappa(0) = {2\over3}{(P_1-P_0)\times((P_0-P_1)+(P_2-P_1))\over|P_1-P_0|^3}$$
$$\kappa(1) = {2\over3}{(P_3-P_2)\times((P_1-P_2)+(P_3-P_2))\over|P_3-P_2|^3}$$
Where κ(0) and κ(1) are the signed curvatures at the start and end of the path segment respectively, and the P's are the four points that define the cubic Bézier. Note, if P0 and P1, or P2 and P3 are degenerate, the curvature will be infinite and a line should be used in constructing the join.
See the CSS 2.1 specification for the definitions
of ‘display
’ and ‘visibility
’.
[CSS21]
SVG uses two properties to control the visibility of
container elements, graphics elements
and text content elements:
‘display
’ and ‘visibility
’.
When applied to certain container elements, graphics elements
or text content elements, setting ‘display
’ to
none results in the element not becoming part of
the rendering tree. Such elements and all of their descendants (regardless of
their own ‘display
’ property value):
Elements that have any other ‘display
’ value than
none behave normally with
respect to all of the above.
The ‘display
’ property only applies to the following SVG elements:
‘svg’, ‘g’, ‘switch’, ‘a’,
‘foreignObject’, graphics elements and
text content elements. Note that ‘display
’
is not an inherited property.
The ‘display
’ property affects the direct processing
of a given element, but it does not prevent it from
being referenced by other elements. For example, setting
display: none on a ‘path’ element
will prevent that element from getting rendered directly onto the
canvas, but the ‘path’ element can still be referenced by a
‘textPath’ element; furthermore, its geometry will be used
in text-on-a-path processing even if the ‘path’ has
display: none.
When applied to a graphics element or text content element,
setting ‘visibility
’ to hidden
or collapse
results in the element not being painted. It is, however,
still part of the rendering tree, is sensitive
to pointer events (depending on the value of ‘pointer-events
’),
contributes to bounding box calculations and clipping paths,
and does affect text layout.
The ‘visibility
’ property only applies to
graphics elements and text content elements.
Note that since ‘visibility
’ is an inherited property,
although it has no effect on a container element itself,
its inherited value can affect descendant elements.
SVG 2 Requirement: | SVG 2 will have constrained transformations based on SVG 1.2 Tiny. |
---|---|
Resolution: | Add vector effects extension proposal to SVG 2 specification. |
Purpose: | To include non-scaling features (non-scaling part of the object, and non-scaling entire object |
Owner: | Satoru Takagi (ACTION-3619) |
Sometimes it is of interest to let the outline of an object keep its original width or to let the position of an object fix no matter which transforms are applied to it. For example, in a map with a 2px wide line representing roads it is of interest to keep the roads 2px wide even when the user zooms into the map, or introductory notes on the graphic chart in which panning is possible.
To offer such effects regarding special coordinate transformations and graphic drawings, SVG Tiny 1.2 introduces the ‘vector-effect
’ property. Although SVG Tiny 1.2 introduced only non-scaling stroke behavior, this version introduces a number of additional effects. Furthermore, since these effects can be specified in combination, they show more various effects. And, future versions of the SVG language will allow for more powerful vector effects through this property.
Name: | vector-effect |
---|---|
Value: | none | [non-scaling-stroke | non-scaling-size | non-rotation | fixed-position]+ [ viewport | screen ]? |
Initial: | none (When values except none are set, viewport becomes the another initial value.) |
Applies to: | graphics elements |
Inherited: | no |
Percentages: | N/A |
Media: | visual |
Computed value: | as specified |
Animatable: | yes |
transform
’ property, that property is consumed for this effect. The shift conponents e and f of matrix of ‘transform
’ property are used to transfer the origin of fixed local coordinate system. The transformation formula and the example behavior are indicated to the following chapter. These values can be enumerated. Thereby, the effect which has these characteristics simultaneously can be specified.
The following two values assists the above-mentioned values. They show the host coordinate space of constrained transformations. Especially it has effective for the element belonging to nested viewport coordinate system such as nested contents or nested ‘svg’ elements. An initial value in case it is not specified is viewport.
Note: Future versions of SVG may allow ways to specify the device coordinate system.
This section shows the list of transformation formulas regarding combinations of the values for clarification of the behavior of vector effects excluding non-scaling-stroke which has clear implications.
The normal coordinate transformation formula from local coordinate system to viewport coordinate system is as follows.
The code assumes a 2D rendering context. Width CSS Transforms we get a 3D rendering context as well? How does that work on perspective or 3D transformations?
CSS Transforms Level 1 mentions about 3D rendering context and non scaling stroke with the purport that the functionality becomes no affect. Is it appropriate to extend it to all the vector effects?
<circle vector-effect="veValue" transform="translate(xo yo)" cx="xf" cy="yf" r=".."/>
When the ‘vector-effect
’ is added to an element like the above, the transformation formula for user coordinate to the device coordinate changes as follows. Here, xf and yf are user coordinate of the corresponding element and its descendant. And, xo and yo are matrix element e and f of the transform attribute which the corresponding element has. In addition, |det(CTM)| is absolute value of the determinants of CTM. When this value becomes 0 and non-scaling-size is appointed, ‘vector-effect
’ becomes invalidity namely none.
veValue | Formula |
---|---|
non-scaling-size |
|
non-rotation |
|
non-scaling-size non-rotation |
|
fixed-position |
|
fixed-position non-scaling-size |
|
fixed-position non-rotation |
|
fixed-position non-scaling-size non-rotation |
|
Below is normal coordinate transformation formula for nested viewport coordinate systems without vector effects. xviewport(UA) and yviewport(UA) are coordinates which under the immediate control of user agent. CTMthis is CTM for the transformation matrix from local coordinate system of an target graphic to viewport coordinate system to which it belongs. CTMparent is CTM for the transformation matrix from aforementioned viewport coordinate system to viewport coordinate system of the parent of that. And, CTMroot is CTM for rootmost viewport coordinate system (UA).
When applying seven formulas of the preceding section to nested viewport coordinate systems, the application way of those formulas changes as follows by whether viewport or screen is specified as the additional value of ‘vector-effect
’.
When viewport value is specified, user agent computes coordinates combining either of seven formulas of the preceding chapter, and the following formulas.
When screen value is specified, user agent computes coordinates combining either of seven formulas of the preceding chapter, and the following formulas.
Below is an example of the non-scaling-stroke ‘vector-effect
’.
<?xml version="1.0"?> <svg xmlns="http://www.w3.org/2000/svg" width="6cm" height="4cm" viewBox="0 0 600 400" viewport-fill="rgb(255,150,200)"> <desc>Example non-scaling stroke</desc> <rect x="1" y="1" width="598" height="398" fill="none" stroke="black"/> <g transform="scale(9,1)"> <line stroke="black" stroke-width="5" x1="10" y1="50" x2="10" y2="350"/> <line vector-effect="non-scaling-stroke" stroke="black" stroke-width="5" x1="32" y1="50" x2="32" y2="350"/> <line vector-effect="none" stroke="black" stroke-width="5" x1="55" y1="50" x2="55" y2="350"/> </g> </svg>
Below is an example of the none ‘vector-effect
’ (no vector effect).
Before changing CTM | After changing CTM |
Source code
<svg xmlns="http://www.w3.org/2000/svg" viewBox="-50,-50,500,500" height="500" width="500"> <rect x="-50" y="-50" width="500" height="500" stroke="orange" stroke-width="3" fill="none"></rect> <!-- Nested local coordinate system is transformed by this transform attribute --> <g id="base" transform="matrix(2.1169438081370817,0.3576047954311102,-0.3576047954311102,1.4700998667618626,0,0) translate(-50,-50)"> <svg viewBox="-50,-50,500,500" height="500" width="500"> <!-- Graph paper on the this svg's base local coordinate system --> <g stroke="green" stroke-width="1" fill="none"> <circle cx="0" cy="0" r="10"></circle> <circle cx="150" cy="150" r="7"></circle> <path fill="green" stroke="none" d="M0,-3 L30,-3 25,-10 50,0 25,10 30,3 0,3z"></path> <line x1="-100" y1="-100" x2="600" y2="-100" stroke-dasharray="5,5"></line> <line x1="-100" y1="000" x2="600" y2="000"></line> <line x1="-100" y1="100" x2="600" y2="100" stroke-dasharray="5,5"></line> <line x1="-100" y1="200" x2="600" y2="200" stroke-dasharray="5,5"></line> <line x1="-100" y1="300" x2="600" y2="300" stroke-dasharray="5,5"></line> <line x1="-100" y1="400" x2="600" y2="400" stroke-dasharray="5,5"></line> <line x1="-100" y1="500" x2="600" y2="500" stroke-dasharray="5,5"></line> <line y1="-100" x1="-100" y2="600" x2="-100" stroke-dasharray="5,5"></line> <line y1="-100" x1="000" y2="600" x2="000"></line> <line y1="-100" x1="100" y2="600" x2="100" stroke-dasharray="5,5"></line> <line y1="-100" x1="200" y2="600" x2="200" stroke-dasharray="5,5"></line> <line y1="-100" x1="300" y2="600" x2="300" stroke-dasharray="5,5"></line> <line y1="-100" x1="400" y2="600" x2="400" stroke-dasharray="5,5"></line> <line y1="-100" x1="500" y2="600" x2="500" stroke-dasharray="5,5"></line> </g> <!-- Figure having vector effect --> <!-- An thick red right arrow and small rectangle on this figure's nested local coordinate system origin --> <path id="ve" vector-effect="none" stroke="red" stroke-width="3" fill="none" transform="matrix(1,0,0,1,150,150)" d="M-50,-50 L50,-50 50,-100 150,0 50,100 50,50 -50,50 -50,-50z M5 0 L0 -5 -5 0 0 5z"></path> </svg> </g> </svg>
Below is an example of the non-scaling-size.
Before changing CTM | After changing CTM |
<path id="ve" vector-effect="non-scaling-size" stroke="red" stroke-width="3" fill="none" transform="matrix(1,0,0,1,150,150)" d="M-50,-50 L50,-50 50,-100 150,0 50,100 50,50 -50,50 -50,-50z M5 0 L0 -5 -5 0 0 5z"/>
Below is an example of the non-rotation.
Before changing CTM | After changing CTM |
<path id="ve" vector-effect="non-rotation" stroke="red" stroke-width="3" fill="none" transform="matrix(1,0,0,1,150,150)" d="M-50,-50 L50,-50 50,-100 150,0 50,100 50,50 -50,50 -50,-50z M5 0 L0 -5 -5 0 0 5z"/>
Below is an example of the non-scaling-size non-rotation.
Before changing CTM | After changing CTM |
<path id="ve" vector-effect="non-scaling-size non-rotation" stroke="red" stroke-width="3" fill="none" transform="matrix(1,0,0,1,150,150)" d="M-50,-50 L50,-50 50,-100 150,0 50,100 50,50 -50,50 -50,-50z M5 0 L0 -5 -5 0 0 5z"/>
Below is an example of the fixed-position.
Before changing CTM | After changing CTM |
<path id="ve" vector-effect="fixed-position" stroke="red" stroke-width="3" fill="none" transform="matrix(1,0,0,1,150,150)" d="M-50,-50 L50,-50 50,-100 150,0 50,100 50,50 -50,50 -50,-50z M5 0 L0 -5 -5 0 0 5z"/>
Below is an example of the non-scaling-size fixed-position.
Before changing CTM | After changing CTM |
<path id="ve" vector-effect="non-scaling-size fixed-position" stroke="red" stroke-width="3" fill="none" transform="matrix(1,0,0,1,150,150)" d="M-50,-50 L50,-50 50,-100 150,0 50,100 50,50 -50,50 -50,-50z M5 0 L0 -5 -5 0 0 5z"/>
Below is an example of the non-rotation fixed-position.
Before changing CTM | After changing CTM |
<path id="ve" vector-effect="non-rotation fixed-position" stroke="red" stroke-width="3" fill="none" transform="matrix(1,0,0,1,150,150)" d="M-50,-50 L50,-50 50,-100 150,0 50,100 50,50 -50,50 -50,-50z M5 0 L0 -5 -5 0 0 5z"/>
Below is an example of the non-scaling-size non-rotation fixed-position.
Before changing CTM | After changing CTM |
<path id="ve" vector-effect="non-scaling-size non-rotation fixed-position" stroke="red" stroke-width="3" fill="none" transform="matrix(1,0,0,1,150,150)" d="M-50,-50 L50,-50 50,-100 150,0 50,100 50,50 -50,50 -50,-50z M5 0 L0 -5 -5 0 0 5z"/>
SVG 2 Requirement: | Improve markers. |
---|---|
Resolution: | We will improve markers for SVG 2. |
Purpose: | To solve the common problems authors have with SVG markers. |
Owner: | Cameron (ACTION-3286) |
A marker is a graphical object that is painted at particular positions along a ‘path’, ‘line’, ‘polyline’ or ‘polygon’ element, together known as the markable elements.
The ‘marker-start
’ and ‘marker-end
’ properties
can be used to place markers at the first and last vertex, and the
‘marker-mid
’ property can be used to place markers at every
other vertex (aside from the first and last). The ‘marker-start
’ and
‘marker-end
’ can be used for example to add arrowheads to paths.
Markers placed using these properties are known as
vertex markers.
In SVG 2, vertex markers are the only kind of markers available. Other specifications will add new types of markers.
The graphics for a marker are defined by a ‘marker’ element.
The ‘marker-start
’, ‘marker-end
’ and ‘marker-mid
’ properties,
together known as the marker properties, reference
‘marker’ elements.
Markers can be animated, and as with ‘use’ elements, the animated effects will show on all current uses of the markers within the document.
Markers on a given element are painted in the following order, from bottom to top:
marker-start
’marker-mid
’ markers, in order of their position along the pathmarker-end
’The ‘marker’ element defines the graphics that are to be used for drawing markers on a markable element.
Attribute definitions:
Name | Value | Initial value | Animatable |
---|---|---|---|
markerUnits | strokeWidth | userSpaceOnUse | strokeWidth | yes |
The ‘markerUnits’ attribute defines the coordinate system for attributes ‘markerWidth’, ‘markerHeight’ and the contents of the ‘marker’. Values have the following meanings:
stroke-width
’ property) in
place for the graphic object referencing the marker.Name | Value | Initial value | Animatable |
---|---|---|---|
markerWidth, markerHeight | <length> | <percentage> | <number> | 3 | yes |
The ‘markerWidth’ and ‘markerHeight’ attributes represent the size of the viewport into which the marker is to be fitted according to the ‘viewBox’ and ‘preserveAspectRatio’ attributes. A value of zero for either attribute results in nothing being rendered for the marker. A negative value for either attribute is an error (see Error processing).
Name | Value | Initial value | Animatable |
---|---|---|---|
refX | <length> | <percentage> | <number> | left | center | right | 0 | yes |
refY | <length> | <percentage> | <number> | top | center | bottom | 0 | yes |
New in SVG 2: geometric keywords (matches use in ‘symbol’).
We will add top/center/bottom, left/center/right keywords to refX/refY on marker/symbol. Resolved at London F2F. Values inspired by 'background-position'.
The ‘refX’ and ‘refY’ attributes define the reference point of the marker which is to be placed exactly at the marker's position on the markable element. They are interpreted as being in the coordinate system of the marker contents, after application of the ‘viewBox’ and ‘preserveAspectRatio’ attributes.
Name | Value | Initial value | Animatable |
---|---|---|---|
orient | auto | auto-start-reverse | <angle> | <number> | 0 | yes (non-additive) |
The ‘orient’ attribute indicates how the marker is rotated when it is placed at its position on the markable element. Values have the following meaning:
A value of 'auto' indicates that the marker is oriented such that its positive x-axis is pointing in the direction of the path at the point it is placed.
This needs to reference a definition for how
directionality of a given start/mid/end vertex is calculated.
Part of that (which should be moved somewhere more appropriate) is in
the path element implementation notes.
Some wording from SVG 1.1 appears to have been lost, compare with this.
Here's an example that is a bit unclear currently:
<svg>
<marker id="m" orient="auto" overflow="visible">
<rect x="-1" y="-0.5" width="1" height="1" fill="green"/>
</marker>
<path d="M50,0C50,50 50,100 50,100" marker-end="url(#m)" stroke-width="100" stroke="red"/>
</svg>
The second control point and the endpoint coincide, should this mean that the direction of the endpoint is a) unknown [aka default to 0 degrees] or
b) that you have to look at the previous segment(s)/command(s) until a direction can be established?
If the marker is on the first or last vertex of a closed subpath, then the incoming direction taken from the final path segment and the outgoing direction is taken from:
A value of 'auto-start-reverse'
means the same as 'auto' except that
for a marker placed by ‘marker-start
’, the orientation is 180°
different from the orientation as determined by 'auto'.
This allows a single arrowhead marker to be defined that can be used for both the start and end of a path, point in the right directions.
An <angle> value represents the angle the marker's positive x-axis makes with the positive x-axis in the local coordinate system of the markable element, and a <number> value with no unit represents an angle in degrees. For example, if a value of '0' is given, then the marker will be drawn such that its x-axis will align with the x-axis of the user space of the graphic object referencing the marker. A value of '90deg' will result in the marker being drawn with its positive x-axis in the direction of the positive y-axis of the markable element's local coordinate system.
The orientation occurs after the marker has been fitted into its viewport. See the Details on how markers are rendered section below for an illustrative example.
The contents of the ‘marker’ are relative to a new coordinate system. The ‘markerUnits’ attribute determines an initial scale factor for transforming the graphics in the marker into the user coordinate system for the referencing element. An additional set of transformations might occur if there is a ‘viewBox’ attribute, in which case the coordinate system for the contents of the ‘marker’ will be transformed due to the processing of attributes ‘viewBox’ and ‘preserveAspectRatio’. If there is no ‘viewBox’ attribute, then the assumed default value for the the ‘viewBox’ attribute has the origin of the viewBox coincident with the origin of the viewport and the width/height of the viewBox the same as the width/height of the viewport.
The user agent style sheet sets
the ‘overflow
’ property for ‘marker’ elements to
hidden, which causes a rectangular clipping
path to be created at the bounds of marker's viewport. Unless the
‘overflow
’ property is overridden, any graphics within the marker which
goes outside of the marker's viewport will be clipped.
Properties inherit into the
‘marker’ element from its ancestors; properties do not
inherit from the element referencing the ‘marker’ element.
Note however that by using the context-stroke
value for the ‘fill
’ or ‘stroke
’ on elements in its definition,
a single marker can be designed to match the style of the element referencing
the marker.
‘marker’ elements are not rendered directly
and must be referenced by one of the marker properties
to be rendered. The ‘display
’ property does not apply to the
‘marker’ element; thus, ‘marker’ elements are not
directly rendered even if the ‘display
’ property is
set to a value other than none, and
‘marker’ elements are available for referencing even when the
‘display
’ property on the ‘marker’ element or any of its
ancestors is set to none.
Event attributes and event listeners attached to the contents of a ‘marker’ element are not processed; only the rendering aspects of ‘marker’ elements are processed.
A number of marker properties allow specifying a ‘marker’ using a <marker-ref> value.
where:
Values have the following meaning
Name: | marker-start, marker-mid, marker-end |
---|---|
Value: | none | <marker-ref> |
Initial: | none |
Applies to: | markable elements |
Inherited: | yes |
Percentages: | N/A |
Media: | visual |
Computed value: | as specified, but with <url> values (that are part of a <marker-ref>) made absolute |
Animatable: | yes |
The ‘marker-start
’ and ‘marker-end
’ properties are used
to specify the marker that will be drawn at the first and last vertices
of the given markable element, respectively. ‘marker-mid
’
is used to specify the marker that will be drawn at all other vertices
(i.e., every vertex except the first and last).
Possible values for ‘marker-start
’, ‘marker-mid
’ and
‘marker-end
’ are:
For ‘polygon’ elements, the last vertex is the same as the first
vertex, and for ‘path’ elements that end with a closed subpath, the last
vertex is the same as the first vertex of that final subpath.
In this case, if the value of ‘marker-end
’ is not
none, then it is possible that two markers
will be rendered on that final vertex.
Note that ‘marker-start
’ and ‘marker-end
’
refer to the first and last vertex of the entire path, not each subpath.
The following example shows a triangular marker symbol used as a vertex marker to form an arrowhead at the end of two paths.
<svg xmlns="http://www.w3.org/2000/svg" width="275" height="200" viewBox="0 0 275 200"> <defs> <marker id="Triangle" viewBox="0 0 10 10" refX="1" refY="5" markerUnits="strokeWidth" markerWidth="4" markerHeight="3" orient="auto"> <path d="M 0 0 L 10 5 L 0 10 z" fill="context-stroke"/> </marker> </defs> <g fill="none" stroke-width="10" marker-end="url(#Triangle)"> <path stroke="crimson" d="M 100,75 C 125,50 150,50 175,75"/> <path stroke="olivedrab" d="M 175,125 C 150,150 125,150 100,125"/> </g> </svg>
Name: | marker |
---|---|
Value: | none | <marker-ref> |
Initial: | not defined for shorthand properties |
Applies to: | markable elements |
Inherited: | yes |
Percentages: | N/A |
Media: | visual |
Computed value: | see individual properties |
Animatable: | yes |
The ‘marker
’ property sets values for the
‘marker-start
’, ‘marker-mid
’ and ‘marker-end
’
properties. The value of the ‘marker
’ is used
directly for all three of the corresponding longhand properties.
For each marker that is drawn, a temporary new user coordinate system is established so that the marker will be positioned and sized correctly, as follows:
stroke-width
’. If ‘markerUnits’ equals
'userSpaceOnUse', then no extra scale
transformation is applied.overflow
’ property on the ‘marker’ element
indicates that the marker needs to be clipped to its viewport, then an
implicit clipping path is established at the bounds of the viewport.The rendering effect of a marker is as if the contents of the referenced ‘marker’ element were deeply cloned into a separate non-exposed DOM tree for each instance of the marker. Because the cloned DOM tree is non-exposed, the SVG DOM does not show the cloned instance of the marker.
For user agents that support Styling with CSS, the conceptual deep cloning of the referenced ‘marker’ element into a non-exposed DOM tree also copies any property values resulting from the CSS cascade ([CSS21], chapter 6) and property inheritance on the referenced element and its contents. CSS 2.1 selectors can be applied to the original (i.e., referenced) elements because they are part of the formal document structure. CSS 2.1 selectors cannot be applied to the (conceptually) cloned DOM tree because its contents are not part of the formal document structure.
For illustrative purposes, we'll repeat the marker example shown earlier:
<?xml version="1.0" standalone="no"?> <svg width="4in" height="2in" viewBox="0 0 4000 2000" xmlns="http://www.w3.org/2000/svg"> <defs> <marker id="Triangle" viewBox="0 0 10 10" refX="0" refY="5" markerUnits="strokeWidth" markerWidth="4" markerHeight="3" orient="auto"> <path d="M 0 0 L 10 5 L 0 10 z" /> </marker> </defs> <rect x="10" y="10" width="3980" height="1980" fill="none" stroke="blue" stroke-width="10" /> <desc>Placing an arrowhead at the end of a path. </desc> <path d="M 1000 750 L 2000 750 L 2500 1250" fill="none" stroke="black" stroke-width="100" marker-end="url(#Triangle)" /> </svg>
The rendering effect of the above file will be visually identical to the following:
<?xml version="1.0" standalone="no"?> <svg width="4in" height="2in" viewBox="0 0 4000 2000" xmlns="http://www.w3.org/2000/svg"> <desc>File which produces the same effect as the marker example file, but without using markers. </desc> <rect x="10" y="10" width="3980" height="1980" fill="none" stroke="blue" stroke-width="10" /> <!-- The path draws as before, but without the marker properties --> <path d="M 1000 750 L 2000 750 L 2500 1250" fill="none" stroke="black" stroke-width="100" /> <!-- The following logic simulates drawing a marker at final vertex of the path. --> <!-- First off, move the origin of the user coordinate system so that the origin is now aligned with the end point of the path. --> <g transform="translate(2500,1250)" > <!-- Rotate the coordinate system 45 degrees because the marker specified orient="auto" and the final segment of the path is going in the direction of 45 degrees. --> <g transform="rotate(45)" > <!-- Scale the coordinate system to match the coordinate system indicated by the 'markerUnits' attributes, which in this case has a value of 'strokeWidth'. Therefore, scale the coordinate system by the current value of the 'stroke-width' property, which is 100. --> <g transform="scale(100)" > <!-- Translate the coordinate system by (-refX*viewBoxToMarkerUnitsScaleX, -refY*viewBoxToMarkerUnitsScaleY) in order that (refX,refY) within the marker will align with the vertex. In this case, we use the default value for preserveAspectRatio ('xMidYMid meet'), which means find a uniform scale factor (i.e., viewBoxToMarkerUnitsScaleX=viewBoxToMarkerUnitsScaleY) such that the viewBox fits entirely within the viewport ('meet') and is center-aligned ('xMidYMid'). In this case, the uniform scale factor is markerHeight/viewBoxHeight=3/10=.3. Therefore, translate by (-refX*.3,-refY*.3)=(0*.3,-5*.3)=(0,-1.5). --> <g transform="translate(0,-1.5)" > <!-- There is an implicit clipping path because the user agent style sheet says that the 'overflow' property for markers has the value 'hidden'. To achieve this, create a clipping path at the bounds of the viewport. Note that in this case the viewport extends 0.5 units to the left and right of the viewBox due to a uniform scale factor, different ratios for markerWidth/viewBoxWidth and markerHeight/viewBoxHeight, and 'xMidYMid' alignment --> <clipPath id="cp1" > <rect x="-0.5" y="0" width="4" height="3" /> </clipPath> <g clip-path="url(#cp1)" > <!-- Scale the coordinate system by the uniform scale factor markerHeight/viewBoxHeight=3/10=.3 to set the coordinate system to viewBox units. --> <g transform="scale(.3)" > <!-- This 'g' element carries all property values that result from cascading and inheritance of properties on the original 'marker' element. In this example, neither fill nor stroke was specified on the 'marker' element or any ancestors of the 'marker', so the initial values of "black" and "none" are used, respectively. --> <g fill="black" stroke="none" > <!-- Expand out the contents of the 'marker' element. --> <path d="M 0 0 L 10 5 L 0 10 z" /> </g> </g> </g> </g> </g> </g> </g> </svg>
View this example as SVG (SVG-enabled browsers only)
SVG 2 Requirement: | Support control of the order of filling, stroke and painting markers on shapes. |
---|---|
Resolution: | SVG 2 will adopt the ‘paint-order’ property proposal, though possibly with a different name. The property name is now resolved, see 15 Nov 2013 minutes. |
Purpose: | To address the common desire to paint strokes below fills without having to duplicate an element. |
Owner: | Cameron (ACTION-3285) |
Name: | paint-order |
---|---|
Value: | normal | [ fill || stroke || markers ] |
Initial: | normal |
Applies to: | graphics elements and text content elements |
Inherited: | yes |
Percentages: | N/A |
Media: | visual |
Computed value: | as specified |
Animatable: | yes |
New in SVG 2. Added primarily to allow painting the stroke of text below its fill without needing to duplicate the ‘text’ element.
The ‘paint-order
’ property controls the order that the three
paint operations that shapes and text are rendered with:
their fill, their stroke and any markers they might have.
When the value of this property is normal, the element is painted with the standard order of painting operations: the fill is painted first, then its stroke and finally its markers.
When any of the other keywords are used, the order of the paint operations for painting the element is as given, from left to right. If any of the three keywords are omitted, they are painted last, in the order they would be painted with paint-order: normal.
This mean that, for example, paint-order: stroke has the same rendering behavior as paint-order: stroke fill markers.
This does not affect interaction, but once the
marker children proposal
is added to the spec, it will be possible for ‘marker’ elements to
receive mouse events or not depending on the value of ‘paint-order
’.
Should there be a way of addressing the individual types of markers – vertex & segment, repeating, positioned – given they are currently specified to render in that order?
The following example shows how the ‘paint-order
’ property can
be used to render stroked text in a more aesthetically pleasing manner.
<svg xmlns="http://www.w3.org/2000/svg" width="600" height="150" viewBox="0 0 600 150"> <style> text { font: 80px bold sans-serif; stroke-linejoin: round; text-anchor: middle; fill: peachpuff; stroke: crimson; } </style> <text x="150" y="100" stroke-width="6px">pizazz</text> <text x="450" y="100" stroke-width="12px" paint-order="stroke">pizazz</text> </svg>
Name: | color-interpolation |
---|---|
Value: | auto | sRGB | linearRGB |
Initial: | sRGB |
Applies to: | container elements, graphics elements, gradient elements and ‘animate’ |
Inherited: | yes |
Percentages: | N/A |
Media: | visual |
Computed value: | as specified |
Animatable: | yes |
The SVG user agent performs color interpolations and compositing
at various points as it processes SVG content. The ‘color-interpolation
’
property controls which color space is used for the following graphics operations:
For filter effects, the
‘color-interpolation-filters
’ property controls which color space is used.
[FILTERS]
The ‘color-interpolation
’ property chooses between color operations
occurring in the sRGB color space or in a (light energy linear) linearized RGB
color space. Having chosen the appropriate color space, component-wise linear
interpolation is used. Possible values for ‘color-interpolation
’ are:
The conversion formulas between the sRGB color space (i.e., nonlinear with 2.2 gamma curve) and the linearized RGB color space (i.e., color values expressed as sRGB tristimulus values without a gamma curve) can be found in the sRGB specification [SRGB]. For illustrative purposes, the following formula shows the conversion from sRGB to linearized RGB, where Csrgb is one of the three sRGB color components, Clinear is the corresponding linearized RGB color component, and all color values are between 0 and 1:
if C_srgb <= 0.04045 C_linear = C_srgb / 12.92 else if c_srgb > 0.04045 C_linear = ((C_srgb + 0.055) / 1.055) ^ 2.4
Out-of-range color values, if supported by the user agent, also are converted using the above formulas. (See Clamping values which are restricted to a particular range.)
When a child element is blended into a background, the value of the
‘color-interpolation
’ property on the child determines the type of
blending, not the value of the ‘color-interpolation
’ on the parent.
For gradients which make use of the
‘href’ attribute to reference another
gradient, the gradient uses the ‘color-interpolation
’ property value
from the gradient element which is directly referenced by the ‘fill
’ or
‘stroke
’ property. When animating colors, color interpolation is
performed according to the value of the ‘color-interpolation
’ property
on the element being animated.
Name: | color-rendering |
---|---|
Value: | auto | optimizeSpeed | optimizeQuality |
Initial: | auto |
Applies to: | container elements, graphics elements, gradient elements and ‘animate’ |
Inherited: | yes |
Percentages: | N/A |
Media: | visual |
Computed value: | as specified |
Animatable: | yes |
The creator of SVG content might want to provide a hint
to the implementation about how to make speed vs. quality
tradeoffs as it performs color interpolation and compositing. The
‘color-rendering
’ property provides a hint to the SVG user
agent about how to optimize its color interpolation and compositing
operations. Possible values are:
‘color-rendering
’ takes precedence over
‘color-interpolation-filters
’. For example, assume
color-rendering: optimizeSpeed and
color-interpolation-filters: linearRGB.
In this case, the SVG user agent should perform color operations in a way that
optimizes performance, which might mean sacrificing the color interpolation
precision as specified by color-interpolation-filters: linearRGB.
Name: | shape-rendering |
---|---|
Value: | auto | optimizeSpeed | crispEdges | geometricPrecision |
Initial: | auto |
Applies to: | shapes |
Inherited: | yes |
Percentages: | N/A |
Media: | visual |
Computed value: | as specified |
Animatable: | yes |
The creator of SVG content might want to provide a hint to the
implementation about what tradeoffs to make as it renders vector graphics
elements such as ‘path’ elements and basic shapes
such as circles and rectangles. The ‘shape-rendering
’ property provides
these hints. Possible values are:
Name: | text-rendering |
---|---|
Value: | auto | optimizeSpeed | optimizeLegibility | geometricPrecision |
Initial: | auto |
Applies to: | ‘text’ |
Inherited: | yes |
Percentages: | N/A |
Media: | visual |
Computed value: | as specified |
Animatable: | yes |
The creator of SVG content might want to provide a hint to the
implementation about what tradeoffs to make as it renders text. The
‘text-rendering
’ property provides these hints. Possible
values are:
The CSS Image Values and Replacement Conent Module Level 4 may in the future redefine this property. In particular it should allow the choice between smoothing and keeping a pixelated look when upscaling.
Name: | image-rendering |
---|---|
Value: | auto | optimizeQuality | optimizeSpeed |
Initial: | auto |
Applies to: | shapes |
Inherited: | yes |
Percentages: | N/A |
Media: | visual |
Computed value: | as specified |
Animatable: | yes |
The creator of SVG content might want to provide a hint to the
implementation about how to make speed vs. quality tradeoffs as it performs
image processing. The ‘image-rendering
’ property provides a hint to the
SVG user agent about how to optimize its image rendering. Possible values are:
In all cases, resampling must be done in a truecolor (e.g., 24-bit) color space even if the original data and/or the target device is indexed color. High quality SVG viewers should perform image resampling using a linear color space.
SVG 2 Requirement: | Support a hint to indicate that an element's rendering should be cached. |
---|---|
Resolution: | SVG 2 will add ‘buffered-rendering’, as implementor feedback indicates that it is needed. |
Purpose: | For caching rendered results for faster display. |
Owner: | Erik (no action) |
The creator of SVG content might want to provide a hint to the implementation about how often an element is modified to make speed vs. memory tradeoffs as it performs rendering. The ‘buffered-rendering
’ property provides a hint to the SVG user agent about how to buffer the rendering of elements:
Name: | buffered-rendering |
---|---|
Value: | auto | dynamic | static |
Initial: | auto |
Applies to: | container elements and graphics elements |
Inherited: | no |
Percentages: | N/A |
Media: | visual |
Computed value: | as specified |
Animatable: | yes |
The values of any of the painting properties defined in this chapter can be inherited from a given object's parent. Painting, however, is always done on each graphics element individually, never at the container element (e.g., a ‘g’) level. Thus, for the following SVG, even though the gradient fill is specified on the ‘g’, the gradient is simply inherited through the ‘g’ element down into each rectangle, each of which is rendered such that its interior is painted with the gradient.
Any painting properties defined in terms of the object's bounding box use the bounding box of the graphics element to which the operation applies. Note that text elements are defined such that any painting operations defined in terms of the object's bounding box use the bounding box of the entire ‘text’ element. (See the discussion of object bounding box units and text elements.)
The following example shows how painting properties are inherited from a ‘g’ element to its child ‘rect’ elements.
<svg xmlns="http://www.w3.org/2000/svg" width="350" height="100" viewBox="0 0 350 100"> <defs> <linearGradient id="OrangeYellow" gradientUnits="objectBoundingBox"> <stop offset="0%" stop-color="#F60"/> <stop offset="100%" stop-color="#FF6"/> </linearGradient> </defs> <g stroke="black" stroke-width="2px" fill="url(#OrangeYellow)"> <rect x="50" y="25" width="100" height="50"/> <rect x="200" y="25" width="100" height="50"/> </g> </svg>
interface SVGMarkerElement : SVGElement { // Marker Unit Types const unsigned short SVG_MARKERUNITS_UNKNOWN = 0; const unsigned short SVG_MARKERUNITS_USERSPACEONUSE = 1; const unsigned short SVG_MARKERUNITS_STROKEWIDTH = 2; // Marker Orientation Types const unsigned short SVG_MARKER_ORIENT_UNKNOWN = 0; const unsigned short SVG_MARKER_ORIENT_AUTO = 1; const unsigned short SVG_MARKER_ORIENT_ANGLE = 2; readonly attribute SVGAnimatedLength refX; readonly attribute SVGAnimatedLength refY; readonly attribute SVGAnimatedEnumeration markerUnits; readonly attribute SVGAnimatedLength markerWidth; readonly attribute SVGAnimatedLength markerHeight; readonly attribute SVGAnimatedEnumeration orientType; readonly attribute SVGAnimatedAngle orientAngle; attribute DOMString orient; void setOrientToAuto(); void setOrientToAngle(SVGAngle angle); }; SVGMarkerElement implements SVGFitToViewBox;
This section covers Paint Servers, a method which
allows the ‘fill
’ or ‘stroke
’ of an object to be defined
by a resource found elsewhere. It allows resources to be reused
throughout a document. See the section
Painting: Filling and Stroking for a
general discussion of filling and stroking objects.
SVG defines several types of paint servers:
SVG1.1 refers to "built-in" paint servers. Is there any other kind?
SVG 2 Requirement: | Arbitrary fills for shapes. |
---|---|
Resolution: | SVG 2 shall support filling and stroking from arbitrary elements. |
Purpose: | To allow for example videos or images to be used as a fill source. |
Owner: | Alex? (no action) |
Paint servers are used by including a URL reference in
a ‘fill
’ or ‘stroke
’ property (i.e. fill="url(#MyLightPurple)").
Properties inherit into a paintserver element from its ancestors; properties do not inherit from the element referencing the paintserver element.
Paintserver elements are never rendered directly (with the exception
of ‘mesh’ which may be rendered in a non-paintserver
mode); their only usage is as something that can be referenced using
the ‘fill
’ and ‘stroke
’ properties. The
‘display
’ property does not apply to a paintserver element;
thus, paintserver elements are not directly rendered even if
the ‘display
’ property is set to a value other
than none, and paintserver elements
are available for referencing even when the ‘display
’
property on the paintserver element or any of its ancestors is set
to none.
Solid Colors are new in SVG 2 (ported from SVG 1.2 Tiny).
SVG 2 Requirement: | Support named colors. |
---|---|
Resolution: | Will add ‘solidColor’ element to SVG 2. |
Purpose: | To provide an easy mechanism for creating named colors and palettes. Also useful for animation. |
Owner: | Tav (no action) |
The 'solidcolor' element is a paint server that provides a single color with opacity. It can be referenced any place a single color can be used. The 'solidcolor' element allows a palette to be defined and used consistently throughout a document. It is also useful as away of animating a palette colors. (See CSS3 Color for a more general discussion of color [CSS3COLOR].)
Solid colors are defined by a ‘solidcolor’ element.
The ‘solid-color
’ property specifies the color of
the ‘solidcolor’. The keyword
currentColor and ICC colors
can be specified in the same manner as within a
<paint>
specification for the ‘fill
’ and ‘stroke
’
properties.
solid-color
’ elements
The ‘solid-opacity
’ property defines the opacity of
the ‘solidcolor’.
solid-color
’ elements<?xml version="1.0" standalone="no"?> <svg xmlns="http://www.w3.org/2000/svg" version="2.0" viewBox="0 0 300 100" > <title>Example solidColor</title> <desc>Fill objects using a solidColor paint server.</desc> <defs> <solidColor id="MyLightPurple" solid-color="#a080ff" solid-opacity="0.5"/> </defs> <!-- The shapes are filled using a solidColor paint server --> <circle fill="url(#MyLightPurple)" cx="50" cy="50" r="40"/> <rect fill="url(#MyLightPurple)" x="110" y="10" width="80" height="80"/> <path fill="url(#MyLightPurple)" d="m 250 10 l 40 80 -80 0 z"/> </svg>
Gradients consist of smooth color transitions between points on a drawing surface. SVG provides for three types of gradients:
The above text and definition may need to be merged
Once a gradient is defined, a graphics element can be
filled or stroked with the gradient by setting the ‘fill
’
or ‘stroke
’ properties to reference the gradient.
Color transitions for linear and radial gradients are defined by a series of color stops along a gradient vector. A gradient normal defines how the colors in a vector are painted to the surface. For a linear gradient, the normal corresponds to lines with the same color. It is perpendicular to the vector in an untransformed gradient. When a graphics element references a gradient, conceptually the graphics element should take a copy of the gradient vector and gradient normal and treat it as part of its own geometry. Any transformations applied to the graphics element geometry also apply to the copied gradient vector and gradient normal. Any gradient transforms that are specified on the reference gradient are applied before any graphics element transformations are applied to the gradient.
Would it be better to just refer to the normal as the line where color is constant. In this case, it would be a circle for an untransformed radial gradient.
Alternative figure:
Color transitions for mesh gradients are defined by an array of color stops. The mapping of colors to the drawing surface in this case is done by geometric data located in the stops. This is discussed in detail in the mesh gradients section.
Linear gradients are defined by a ‘linearGradient’ element.
Defines the coordinate system for attributes ‘x1’, ‘y1’, ‘x2’ and ‘y2’.
If gradientUnits="userSpaceOnUse",
‘x1’, ‘y1’, ‘x2’, and ‘y2’
represent values in the coordinate system that results
from taking the current user coordinate system in place at
the time when the gradient element is referenced (i.e.,
the user coordinate system for the element referencing the
gradient element via a ‘fill
’ or ‘stroke
’
property) and then applying the transform specified by
attribute ‘gradientTransform’. Percentages
represent values relative to the current viewport.
If gradientUnits="objectBoundingBox", the user coordinate system for attributes ‘x1’, ‘y1’, ‘x2’ and ‘y2’ is established using the bounding box of the element to which the gradient is applied (see Object bounding box units) and then applying the transform specified by attribute ‘gradientTransform’. Percentages represent values relative to the bounding box for the object.
When gradientUnits="objectBoundingBox" and ‘gradientTransform’ is the identity matrix, the normal of the linear gradient is perpendicular to the gradient vector in object bounding box space (i.e., the abstract coordinate system where (0,0) is at the top/left of the object bounding box and (1,1) is at the bottom/right of the object bounding box). When the object's bounding box is not square, the gradient normal which is initially perpendicular to the gradient vector within object bounding box space may render non-perpendicular relative to the gradient vector in user space. If the gradient vector is parallel to one of the axes of the bounding box, the gradient normal will remain perpendicular. This transformation is due to application of the non-uniform scaling transformation from bounding box space to local coordinate system.
Contains the definition of an optional additional transformation from the gradient coordinate system onto the target coordinate system (i.e., 'userSpaceOnUse' or 'objectBoundingBox'). This allows for things such as skewing the gradient. This additional transformation matrix is post-multiplied to (i.e., inserted to the right of) any previously defined transformations, including the implicit transformation necessary to convert from object bounding box units to local coordinate system.
‘x1’, ‘y1’, ‘x2’ and ‘y2’ define a gradient vector for the linear gradient. This gradient vector provides starting and ending points onto which the gradient stops are mapped. The values of ‘x1’, ‘y1’, ‘x2’ and ‘y2’ can be either numbers or percentages.
See ‘x1’.
See ‘x1’.
See ‘x1’.
Indicates what happens if the gradient starts or ends inside the bounds of the target rectangle.
A URL reference to a different ‘linearGradient’ or ‘radialGradient’ element within the current SVG document fragment. Any ‘linearGradient’ attributes which are defined on the referenced element which are not defined on this element are inherited by this element. If this element has no defined gradient stops, and the referenced element does (possibly due to its own ‘href’ attribute), then this element inherits the gradient stop from the referenced element. Inheritance can be indirect to an arbitrary level; thus, if the referenced element inherits attribute or gradient stops due to its own ‘href’ attribute, then the current element can inherit those attributes or gradient stops.
Refer to the common handling defined for URL reference attributes and deprecated XLink attributes.
If ‘x1’ = ‘x2’ and ‘y1’ = ‘y2’, then the area to be painted will be painted as a single color using the color and opacity of the last gradient stop.
Example lingrad01 shows how to fill a rectangle by referencing a linear gradient paint server.
<?xml version="1.0" standalone="no"?> <svg xmlns="http://www.w3.org/2000/svg" version="1.1" viewBox="0 0 300 200" > <title>Example lingrag01</title> <desc>Fill a rectangle using a linear-gradient paint server.</desc> <defs> <linearGradient id="MyGradient"> <stop offset="5%" stop-color="#A8F" /> <stop offset="95%" stop-color="#FDC" /> </linearGradient> </defs> <!-- The rectangle is filled using a linear-gradient paint server --> <rect fill="url(#MyGradient)" stroke="black" stroke-width="2" x="25" y="25" width="250" height="150"/> </svg>
Radial gradients are defined by a ‘radialGradient’ element.
Defines the coordinate system for attributes ‘cx’, ‘cy’, ‘r’, ‘fx’, ‘fy’, and ‘fr’.
If gradientUnits="userSpaceOnUse",
‘cx’, ‘cy’, ‘r’, ‘fx’, ‘fy’,
and ‘fr’
represent values in the coordinate system that results
from taking the current user coordinate system in place at
the time when the gradient element is referenced (i.e.,
the user coordinate system for the element referencing the
gradient element via a ‘fill
’ or ‘stroke
’
property) and then applying the transform specified by
attribute ‘gradientTransform’. Percentages
represent values relative to the current viewport.
If gradientUnits="objectBoundingBox", the user coordinate system for attributes ‘cx’, ‘cy’, ‘r’, ‘fx’, ‘fr’, and ‘fr’ is established using the bounding box of the element to which the gradient is applied (see Object bounding box units) and then applying the transform specified by attribute ‘gradientTransform’. Percentages represent values relative to the bounding box for the object.
When gradientUnits="objectBoundingBox" and ‘gradientTransform’ is the identity matrix, then the rings of the radial gradient are circular with respect to the object bounding box space (i.e., the abstract coordinate system where (0,0) is at the top/left of the object bounding box and (1,1) is at the bottom/right of the object bounding box). When the object's bounding box is not square, the rings that are conceptually circular within object bounding box space will render as elliptical due to application of the non-uniform scaling transformation from bounding box space to local coordinate system.
Contains the definition of an optional additional transformation from the gradient coordinate system onto the target coordinate system (i.e., 'userSpaceOnUse' or 'objectBoundingBox'). This allows for things such as skewing the gradient. This additional transformation matrix is post-multiplied to (i.e., inserted to the right of) any previously defined transformations, including the implicit transformation necessary to convert from object bounding box units to local coordinate system.
‘cx’, ‘cy’ and ‘r’ define the end circle for the radial gradient. The gradient will be drawn such that the 100% gradient stop is mapped to the perimeter of this end circle.
See ‘cx’.
See ‘cx’.
A negative value is an error (see Error processing).
‘fx’, ‘fy’, and ‘fr’ define the start circle for the radial gradient. The gradient will be drawn such that the 0% gradient stop is mapped to the perimeter of this start circle.
If attribute ‘fx’ is not specified, ‘fx’ will coincide with the presentational value of ‘cx’ for the element whether the value for 'cx' was inherited or not. If the element references an element that specifies a value for 'fx', then the value of 'fx' is inherited from the referenced element.
See ‘fx’.
If attribute ‘fy’ is not specified, ‘fy’ will coincide with the presentational value of ‘cy’ for the element whether the value for 'cy' was inherited or not. If the element references an element that specifies a value for 'fy', then the value of 'fy' is inherited from the referenced element.
New in SVG 2. Added to align with Canvas.
‘fr’ is the radius of the focal circle. See ‘fx’.
A negative value is an error (see Error processing).
If the attribute is not specified, the effect is as if a value of '0%' were specified. If the element references an element that specifies a value for 'fr', then the value of 'fr' is inherited from the referenced element.
SVG 2 Requirement: | Allow specifying focal circle radius in radial gradients. |
---|---|
Resolution: | Add an ‘fr’ attribute to ‘radialGradient’> for SVG 2. |
Purpose: | To align with Canvas. The zero-offset stop would be along the circle defined by the ‘fx’, ‘fy’ and ‘fr’ attributes. |
Owner: | Erik (ACTION-3098) |
Indicates what happens if the gradient starts or ends inside the bounds of the object(s) being painted by the gradient. Has the same values and meanings as the ‘spreadMethod’ attribute on ‘linearGradient’ element.
A URL reference to a different ‘linearGradient’ or ‘radialGradient’ element within the current SVG document fragment. Any ‘radialGradient’ attributes which are defined on the referenced element which are not defined on this element are inherited by this element. If this element has no defined gradient stops, and the referenced element does (possibly due to its own ‘href’ attribute), then this element inherits the gradient stop from the referenced element. Inheritance can be indirect to an arbitrary level; thus, if the referenced element inherits attribute or gradient stops due to its own ‘href’ attribute, then the current element can inherit those attributes or gradient stops.
Refer to the common handling defined for URL reference attributes and deprecated XLink attributes.
SVG 2 Requirement: | Clarify radial gradients with focal point on the circle. |
---|---|
Resolution: | When the focal point is on the circle edge, with repeat, then the distance between the first and last stop for the repeating colors is 0 and the paint should generate a color that is the average of all the gradient stops. |
Purpose: | To improve interoperability of radial gradients. |
Owner: | Erik (ACTION-3097) |
Note: | SVG 1.1 does not define what to do when the focal point is on the circle edge, with 'repeat'. The distance between the first and last stop for the repeating colors is 0. It was resolved that the paint should generate a color that is the weighted average (by offset) of all the gradient stops. |
Changed in SVG 2. SVG 1.1 required that the focal point, if outside the end circle, be moved to be on the end circle. The change was made to align with Canvas.
Allowing the focal point to lie outside the end circle was resolved at the Rigi Kaltbad working group meeting.
If the start circle defined by ‘fx’, ‘fy’ and ‘fr’ lies outside the end circle defined by ‘cx’, ‘cy’, and ‘r’, effectively a cone is created, touched by the two circles. Areas outside the cone stay untouched by the gradient (transparent black).
If the start circle fully overlaps with the end circle, no gradient is drawn. The area stays untouched (transparent black).
The treatment of the area to the right of the gradient in the right-hand side of the above figure is different from that of Canvas where the area would be transparent black. The difference is to maintain compatibility with SVG 1.1.
The color space for the weighted average is the same as in which the gradient is interpolated. See Rigi Kaltbad working group meeting.
Example radgrad01 shows how to fill a rectangle by referencing a radial gradient paint server.
<?xml version="1.0" standalone="no"?> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 300 200" > <title>Example radgrad01</title> <desc>Fill a rectangle by referencing a radial gradient paint server.</desc> <defs> <radialGradient id="MyGradient" gradientUnits="userSpaceOnUse" cx="150" cy="100" r="100"> <stop offset="0%" stop-color="#A8F" /> <stop offset="50%" stop-color="#FDC" /> <stop offset="100%" stop-color="#A8F" /> </radialGradient> </defs> <!-- The rectangle is filled using a radial gradient paint server --> <rect fill="url(#MyGradient)" stroke="black" stroke-width="2" x="25" y="25" width="250" height="150"/> </svg>
SVG 2 Requirement: | Support photorealistic gradients. |
---|---|
Resolution: | Mesh gradients are accepted by the WG for SVG 2. |
Purpose: | To allow more complex gradients such as those found in nature. |
Owner: | Tav (ACTION-3121) |
Resolution: Rename stop-path to 'd' or 'path' (Coons patch syntax).
Resolution: We will allow just C/c/L/l in mesh path data. We will leave out tensor control points. We will not allow multiple colors at mesh intersections, just use zero size patches instead.
Resolution: We will have a type="smooth-bicubic" or similar on <mesh>. (Note: In the resolution, the attribute is incorrectly placed on <patch>; see the minutes.)
New in SVG 2. Added to allow complex shadings. This is needed, for example, in creating life-like drawings or in interpolating data points on a two-dimensional grid.
The mesh gradients in SVG are based on an array of Coons Patches. A Coons Patch is a shading defined by colors place at the corners of an area enclosed by four Bézier curves. The interpolation of the corner colors into the patch can either be bilinear or bicubic.
A Coons Patch is equivalent to a bi-cubic Ferguson patch where the distance between a cubic Bézier end point and its nearest control point is one-third the length of the corresponding Ferguson tangent line.
Unlike other paint servers, a mesh defined outside of a ‘defs’ section is rendered. In this the case, the mesh has a bounding box determined by its maximum extent, taking into account all of its patches.
A mesh consists of patches placed in an array. There are two reasons for using an array. The first is that an array of meshes is a natural result for most content creation processes (start with a path and then subdivide its area into rows and columns of patches). The second is that the data can be compacted by sharing sides and corners. The array structure is conceptual only. The actual mesh can be distorted in any way possible. The mesh gradient syntax is designed so that it is easy to simulate other types of gradients such as conical gradients or triangle meshes as shown in the examples below.
The structure of a mesh gradient:
<mesh x="100" y="100"> <meshrow> <meshpatch> <stop .../> Up to four stops in first patch. See details below. </meshpatch> <meshpatch> Any number of meshpatches in row. </meshpatch> </meshrow> <meshrow> Any number of meshrows, each with the same number of meshpatches as in the first row. </meshrow> </mesh>
The first ‘meshpatch’ in the first ‘meshrow’ contains four ‘stop’ elements. These elements correspond conceptually, in order, to the top, right, bottom, and left edges of the first patch. The following patches in the first row contains three ‘stop’ elements, corresponding to the top, right, and bottom edges of the patch. The left edge of one of these patches is taken from the (reversed) right edge of the previous patch. The first patch of following rows contains three ‘stop’ elements, corresponding to the right, bottom, and left edges. The top edge is taken from the (reversed) bottom edge of the first patch in the row above. The remaining patches contain two ‘stop’ elements, corresponding to the right and bottom edges of the patch. The top edge is taken from the patch directly above in the array of patches while the left edge is taken from the previous patch in the same row.
Each ‘stop’ element contains a ‘path’ attribute which consists of a single 'c', 'C', 'l', or 'L' path command. The initial point for the path command is taken from the last point of the previous edge of the patch (which for the first ‘stop’ in a patch is defined in the patch to the left or top), except for the first patch in the first row where the initial point is given by the ‘x’ and ‘y’ attributes in the ‘mesh’ element. The path command in the last ‘stop’ element of a ‘meshpatch’ has one less point than normal as this "missing" point necessary to close the path is already defined.
For each ‘stop’ element there is a color and opacity
that correspond to the patch corner at the initial point of
the stop's edge. This color and opacity are defined inside
the ‘stop’ by the ‘stop-color
’
and ‘stop-opacity
’ properties except for the first
stop in all patches other than the first patch in the first
row where the stop color and opacity are already defined by a
previous patch.
Here is an annotated example of a two by two mesh:
<mesh x="50" y="50" id="example"> <!-- x, y used for initial point in first patch. --> <meshrow> <!-- No attributes, used only to define begin/end of row. --> <meshpatch> <stop path="c 25,-25 75, 25 100,0" stop-color="lightblue" /> <stop path="c 25, 25 -25, 75 0,100" stop-color="purple" /> <stop path="c -25, 25 -75,-25 -100,0" stop-color="red" /> <stop path="c -25,-25, 25,-75" stop-color="purple" /> <!-- Last point not needed (closed path). --> </meshpatch> <meshpatch> <stop path="c 25,-25 75, 25 100,0" /> <!-- stop-color from previous patch. --> <stop path="c 25, 25 -25, 75 0,100" stop-color="lightblue" /> <stop path="c -25, 25 -75,-25" stop-color="purple" /> <!-- Last point not needed (closed path). --> <!-- Last path (left side) taken from right side of previous path (with points reversed). --> </meshpatch> </meshrow> <meshrow> <!-- New row. --> <meshpatch> <!-- First path (top side) taken from bottom path of patch above. --> <stop path="c 25, 25 -25, 75 0,100" /> <!-- stop-color from patch above. --> <stop path="c -25, 25 -75,-25 -100,0" stop-color="purple" /> <stop path="c -25,-25, 25,-75" stop-color="lightblue" /> <!-- Last point not needed (closed path). --> </meshpatch> <meshpatch> <!-- First path (top side) taken from bottom path of patch above (with points reversed). --> <stop path="c 25, 25 -25, 75 0,100" /> <!-- stop-color from patch above. --> <stop path="c -25, 25 -75,-25" stop-color="lightblue" /> <!-- Last point not needed (closed path). --> <!-- Last path (left side) taken from right side of previous path (with points reversed). --> </meshpatch> </meshrow> </mesh>
The above mesh is rendered as:
Coons patch meshes can simulate other types of gradients. Here is an example of a conic gradient:
The corner colors are mapped to the patch area with a two step process. First the colors are placed at the corners of a unit square and the area inside the square is then colored using either bilinear interpolation or bicubic interpolation. Second, the points inside the square are mapped to points inside the patch using the following formula:
$S = S_C + S_D - S_B$
where
$$ \begin{align} S_C(u,v) &= (1-v)×C_1(u) + v×C_2(u),\\ S_D(u,v) &= (1-u)×D_1(v) + u×D_2(v),\\ S_B(u,v) &= (1-v)×[(1-u)×C_1(0) + u×C_1(1)]\\ &\qquad {}+ v×[(1-u)×C_2(0) + u×C_2(1)]. \end{align} $$
, , , and are the curves at the top, bottom, left, and right of the patch, respectively; and are the coordinates inside the unit square. The subtraction term ensures that the boundary conditions are met.
Come up with better explanation of the mapping with diagram.
One method of rendering a patch is to "divide and conquer." Check if the four corner colors of the patch are the same within a specified tolerance. If so, paint the patch with the average color using the normal path filling routine. If not, divide the patch into four smaller patches and repeat the color tolerance check. Repeat the process as many times as necessary.
Another way to render a patch is to first divide the patch vertically or horizontally into a series of smaller patches that are each less than one pixel high or wide. Then each resulting patch can be rendered as a path.
Bilinear interpolation of the corner colors depends only on the values of the corner colors. The color profile along two opposite edges is first computed and then corresponding points along those edges are interpolated to fill in the interior. The color profile across a patch boundary may not be smooth, leading to an optical phenomena known as Mach banding.
Bicubic interpolation requires knowing not only the value of the corner colors but also their derivatives. The derivatives are chosen to ensure a smooth transition across patch boundaries and that there are no color value minima or maxima in the patch interior (i.e. a monotone cubic interpolation). Only the derivatives in x and y (where the x and y are the directions along the rows and columns of the conceptual mesh grid) are used (the cross derivatives are set to zero).
To calculate the derivatives: Let be the color value at the point , where .
\Delta_k = {{c_{k+1}-c_k}\over{\lvert p_{k+1}-p_k\rvert}}
$ \delta_k = {\Delta_{k-1} + \Delta_k\over 2} $
$ \delta_1 = 2\times\Delta_1 - \delta_2 $
$ \delta_n = 2\times\Delta_{n-1} - \delta_{n-1} $
The typical method for dealing with the start or end of a bicubic interpolation is to add an extra point before and an extra point after the given points. The value of the point before (after) is assigned either the value of the first (last) point or a value so that the secant before (after) is the same as the secant after (before) the first (last) point. The method described here does not rely on the addition of points but instead fits a quadratic curve to the color values and the already determined derivative at the other edge of the patch. This produces an interpolation that does not have an inflection point inside the patch.
Bicubic interpolation will produce smooth patch boundaries when a mesh is laid out on a rectangular grid and where the patch edges are linear. If the grid is distorted or the patch edges are not lines (i.e. they are Bézier curves), it is still possible to produce non-smooth transitions across patch boundaries.
Mesh gradients are defined by a ‘mesh’ element.
Defines the coordinate system for attributes ‘x’ and ‘y’.
If gradientUnits="userSpaceOnUse",
‘x’ and ‘y’
represent values in the coordinate system that results
from taking the current user coordinate system in place at
the time when the gradient element is referenced (i.e.,
the user coordinate system for the element referencing the
gradient element via a ‘fill
’ or ‘stroke
’
property) or when the mesh is rendered on its own
(i.e. not as a paint server) and then applying the
transform specified by attribute
‘transform’. Percentages represent values
relative to the current viewport.
If gradientUnits="objectBoundingBox", the user coordinate system for attributes ‘x’ and ‘y’, is established using the bounding box of the element to which the gradient is applied (see Object bounding box units) and then applying the transform specified by attribute ‘transform’. Percentages represent values relative to the bounding box for the object.
When a mesh is rendered on its own (i.e. not as a paint server) this value is not valid and the current user coordinate system is used.
Contains the definition of an optional additional transformation from the mesh coordinate system onto the target coordinate system (i.e., 'userSpaceOnUse'). This allows for things such as skewing the gradient. This additional transformation matrix is post-multiplied to (i.e., inserted to the right of) any previously defined transformations.
‘x’ and ‘y’ define the starting point of the mesh grid.
See ‘x’.
A URL reference to a different ‘mesh’ element within the current SVG document fragment. Any ‘mesh’ attributes which are defined on the referenced element which are not defined on this element are inherited by this element. Inheritance can be indirect to an arbitrary level; thus, if the referenced element inherits attribute due to its own ‘href’ attribute, then the current element can inherit those attributes.
Refer to the common handling defined for URL reference attributes and deprecated XLink attributes.
Determines the type of interpolation to use when painting a patch.
Mesh rows are defined by a ‘meshrow’ element.
Mesh patches are defined by a ‘meshpatch’ element.
The vector (linear and radial gradients) or array (mesh gradients) of colors to use in a gradient is defined by the ‘stop’ elements that are child elements to a ‘linearGradient’, ‘radialGradient’, or ‘meshpatch’ element.
In SVG 1.1, the above read: "The ramp of colors..." but "ramp" is used nowhere else in this section.
Indicates were the gradient stop is placed. For linear gradients, the ‘offset’ attribute represents a location along the gradient vector. For radial gradients, it represents a fractional distance from the edge of the innermost/smallest circle to the edge of the outermost/largest circle. This attribute does not apply to mesh gradients.
Gives the path for one side of a mesh gradient patch. This attribute applies only to mesh gradients.
Mesh path data consists of a single 'l', 'L', 'c', or 'C' path command (as defined for the Path ‘d’ attribute). See the ‘mesh’ section above for how the path data is interpreted.
The ‘stop-color
’ property indicates what color to use
at that gradient stop. The keyword
currentColor and ICC colors
can be specified in the same manner as within a
<paint>
specification for the ‘fill
’ and ‘stroke
’
properties.
The ‘stop-opacity
’ property defines the opacity of
a given gradient stop.
If two gradient stops have the same offset value, then the latter gradient stop controls the color value at the overlap point. In particular:
<stop offset="0" stop-color="white"/> <stop offset=".2" stop-color="red"/> <stop offset=".2" stop-color="blue"/> <stop offset="1" stop-color="black"/>
will have approximately the same effect as:
<stop offset="0" stop-color="white"/> <stop offset=".1999999999" stop-color="red"/> <stop offset=".2" stop-color="blue"/> <stop offset="1" stop-color="black"/>
which is a gradient that goes smoothly from white to red, then abruptly shifts from red to blue, and then goes smoothly from blue to black.
A pattern is used to ‘fill
’ or ‘stroke
’
an object using a pre-defined graphic object which can be replicated
("tiled") at fixed intervals in x and y to cover the
areas to be painted. Patterns are defined using a ‘pattern’
element and then referenced by properties ‘fill
’ and
‘stroke
’ on a given graphics element to indicate that the
given element shall be filled or stroked with the pattern.
Attributes ‘x’, ‘y’, ‘width’, ‘height’ and ‘patternUnits’ define a reference rectangle somewhere on the infinite canvas. The reference rectangle has its top/left at (x, y) and its bottom/right at (x + width, y + height). The tiling theoretically extends a series of such rectangles to infinity in X and Y (positive and negative), with rectangles starting at (x + m*width, y + n* height) for each possible integer value for m and n.
Defines the coordinate system for attributes ‘x’, ‘y’, ‘width’ and ‘height’.
If patternUnits="userSpaceOnUse",
‘x’, ‘y’, ‘width’ and ‘height’
represent values in the coordinate system that results
from taking the current user coordinate system in place at
the time when the ‘pattern’ element is referenced
(i.e., the user coordinate system for the element
referencing the ‘pattern’ element via a
‘fill
’ or ‘stroke
’ property) and then
applying the transform specified by attribute
‘patternTransform’. Percentages
represent values relative to the current viewport.
If patternUnits="objectBoundingBox", the user coordinate system for attributes ‘x’, ‘y’, ‘width’ and ‘height’ is established using the bounding box of the element to which the pattern is applied (see Object bounding box units) and then applying the transform specified by attribute ‘patternTransform’. Percentages represent values relative to the bounding box for the object.
Defines the coordinate system for the contents of the ‘pattern’. Note that this attribute has no effect if attribute ‘viewBox’ is specified.
If patternContentUnits="userSpaceOnUse",
the user coordinate system for the contents of the ‘pattern’
element is the coordinate system that results from taking
the current user coordinate system in place at the time
when the ‘pattern’ element is referenced (i.e., the
user coordinate system for the element referencing the
‘pattern’ element via a ‘fill
’ or ‘stroke
’
property) and then applying the transform specified by attribute
‘patternTransform’.
If patternContentUnits="objectBoundingBox", the user coordinate system for the contents of the ‘pattern’ element is established using the bounding box of the element to which the pattern is applied (see Object bounding box units) and then applying the transform specified by attribute ‘patternTransform’.
Contains the definition of an optional additional transformation from the pattern coordinate system onto the target coordinate system (i.e., 'userSpaceOnUse' or 'objectBoundingBox'). This allows for things such as skewing the pattern tiles. This additional transformation matrix is post-multiplied to (i.e., inserted to the right of) any previously defined transformations, including the implicit transformation necessary to convert from object bounding box units to local coordinate system.
‘x’, ‘y’, ‘width’ and ‘height’ indicate how the pattern tiles are placed and spaced. These attributes represent coordinates and values in the coordinate space specified by the combination of attributes ‘patternUnits’ and ‘patternTransform’.
See ‘x’.
See ‘x’.
A negative value is an error (see Error processing). A value of zero disables rendering of the element (i.e., no paint is applied).
See ‘x’.
A negative value is an error (see Error processing). A value of zero disables rendering of the element (i.e., no paint is applied).
A URL reference to a different ‘pattern’ element within the current SVG document fragment. Any attributes which are defined on the referenced element which are not defined on this element are inherited by this element. If this element has no children, and the referenced element does (possibly due to its own ‘href’ attribute), then this element inherits the children from the referenced element. Inheritance can be indirect to an arbitrary level; thus, if the referenced element inherits attributes or children due to its own ‘href’ attribute, then the current element can inherit those attributes or children.
Refer to the common handling defined for URL reference attributes and deprecated XLink attributes.
See ‘preserveAspectRatio’.
SVG's user agent style sheet sets
the ‘overflow
’ property for ‘pattern’ elements to
hidden, which causes a rectangular clipping
path to be created at the bounds of the pattern tile. Unless the
‘overflow
’ property is overridden, any graphics within the pattern
which goes outside of the pattern rectangle will be clipped. Note that if
the ‘overflow
’ property is set to visible
the rendering behavior for the pattern is undefined.
Example pattern01 below shows the
effect of clipping to the pattern tile.
The contents of the ‘pattern’ are relative to a new coordinate system. If there is a ‘viewBox’ attribute, then the new coordinate system is fitted into the region defined by the ‘x’, ‘y’, ‘width’, ‘height’ and ‘patternUnits’ attributes on the ‘pattern’ element using the standard rules for ‘viewBox’ and ‘preserveAspectRatio’. If there is no ‘viewBox’ attribute, then the new coordinate system has its origin at (x, y), where x is established by the ‘x’ attribute on the ‘pattern’ element, and y is established by the ‘y’ attribute on the ‘pattern’ element. Thus, in the following example:
<pattern x="10" y="10" width="20" height="20"> <rect x="5" y="5" width="10" height="10"/> </pattern>
the rectangle has its top/left located 5 units to the right and 5 units down from the origin of the pattern tile.
The ‘viewBox’ attribute introduces a supplemental transformation which is applied on top of any transformations necessary to create a new pattern coordinate system due to attributes ‘x’, ‘y’, ‘width’, ‘height’ and ‘patternUnits’.
Event attributes and event listeners attached to the contents of a ‘pattern’ element are not processed; only the rendering aspects of ‘pattern’ elements are processed.
Example pattern01
shows how to fill a rectangle by referencing a pattern paint
server. Note how the blue stroke of each triangle has been
slightly clipped at the top and the left. This is due to SVG's
user agent style sheet setting
the ‘overflow
’ property for ‘pattern’ elements to
hidden, which causes the pattern to be clipped
to the bounds of the pattern tile.
<?xml version="1.0" standalone="no"?> <svg xmlns="http://www.w3.org/2000/svg" version="1.1" viewBox="0 0 300 200" > <title>Example pattern01</title> <desc>Fill an ellipse using a pattern paint server.</desc> <defs> <pattern id="TrianglePattern" patternUnits="userSpaceOnUse" x="0" y="0" width="50" height="50" viewBox="0 0 10 10" > <path d="M 0 0 L 7 0 L 3.5 7 z" fill="plum" stroke="blue" /> </pattern> </defs> <!-- The ellipse is filled using a triangle pattern paint server --> <ellipse fill="url(#TrianglePattern)" stroke="black" stroke-width="2" cx="150" cy="100" rx="125" ry="75" /> </svg>
Hatches are new in SVG 2. They were added to allow the kinds of patterns required for mapping, engraving, etc. where continuous lines are needed.
SVG 2 Requirement: | Support hatches. |
---|---|
Resolution: | SVG 2 should support hatchings without the artifacts that patterns currently impose. |
Purpose: | To allow the kinds of patterns required for mapping, engraving, etc. where continuous lines are required. |
Owner: | Tav (no action) |
A hatch is used to ‘fill
’ or ‘stroke
’
an object using one or more pre-defined paths that are repeated
at fixed intervals in a specified direction to cover the
areas to be painted. Hatches are defined using a ‘hatch’
element and then referenced by properties ‘fill
’ and
‘stroke
’ on a given graphics element to indicate that the
given element shall be filled or stroked with the hatch.
Paths are defined by ‘hatchpath’ elements.
Attributes ‘x’, ‘y’, ‘pitch’, ‘rotate’, and ‘hatchUnits’ define an infinitely long reference strip on the infinite canvas. The strip has one edge at (x, y) and its other edge at a distance of pitch in the direction defined by rotate. This one-dimension tiling theoretically extends a series of such strips in the direction of 'rotate' to infinity (positive and negative), with strips starting at (x + m*pitch*cos(rotate), y + m*pitch*sin(rotate) for each possible integer value of m.
Defines the coordinate system for attributes ‘x’, ‘y’, ‘pitch’ and ‘rotate’.
If hatchUnits="userSpaceOnUse",
‘x’, ‘y’, ‘pitch’, and ‘rotate’
represent values in the coordinate system that results
from taking the current user coordinate system in place at
the time when the ‘hatch’ element is referenced
(i.e., the user coordinate system for the element
referencing the ‘hatch’ element via a
‘fill
’ or ‘stroke
’ property) and then
applying the transform specified by attribute
‘transform’. Percentages
represent values relative to the current viewport.
If hatchUnits="objectBoundingBox", the user coordinate system for attributes ‘x’, ‘y’, ‘pitch’, and ‘rotate’ is established using the bounding box of the element to which the hatch is applied (see Object bounding box units) and then applying the transform specified by attribute ‘transform’. Percentages represent values relative to the bounding box for the object.
Defines the coordinate system for the contents of the ‘hatch’.
If hatchContentUnits="userSpaceOnUse",
the user coordinate system for the contents of the ‘hatch’
element is the coordinate system that results from taking
the current user coordinate system in place at the time
when the ‘hatch’ element is referenced (i.e., the
user coordinate system for the element referencing the
‘hatch’ element via a ‘fill
’ or ‘stroke
’
property) and then applying the transform specified by attribute
‘transform’.
If hatchContentUnits="objectBoundingBox", the user coordinate system for the contents of the ‘hatch’ element is established using the bounding box of the element to which the hatch is applied (see Object bounding box units) and then applying the transform specified by attribute ‘transform’.
Contains the definition of an optional additional transformation from the hatch coordinate system onto the target coordinate system (i.e., 'userSpaceOnUse' or 'objectBoundingBox'). This allows for things such as skewing the hatch strips. This additional transformation matrix is post-multiplied to (i.e., inserted to the right of) any previously defined transformations, including the implicit transformation necessary to convert from object bounding box units to local coordinate system.
‘x’, ‘y’, ‘pitch’ and ‘rotate’ indicate how the hatch strips are placed and spaced. These attributes represent coordinates and values in the coordinate space specified by the combination of attributes ‘hatchUnits’ and ‘transform’.
See ‘x’.
See ‘x’.
A negative value is an error (see Error processing). A value of zero disables rendering of the element (i.e., no paint is applied).
See ‘x’.
Changed name from 'angle' to 'rotate' at Tokyo F2F.
A URL reference to a different ‘hatch’ element within the current SVG document fragment. Any attributes which are defined on the referenced element which are not defined on this element are inherited by this element. If this element has no children, and the referenced element does (possibly due to its own ‘href’ attribute), then this element inherits the children from the referenced element. Inheritance can be indirect to an arbitrary level; thus, if the referenced element inherits attributes or children due to its own ‘href’ attribute, then the current element can inherit those attributes or children.
Refer to the common handling defined for URL reference attributes.
SVG's user agent style sheet sets
the ‘overflow
’ property for ‘hatch’ elements to
hidden, which causes an infinite strip clipping
path to be created at the bounds of the hatch strip. Unless the
‘overflow
’ property is overridden, any graphics within the
hatch which goes outside of the hatch strip will be clipped. Note that
if the ‘overflow
’ property is set
to visible the area outside must be
rendered (NB this is different from a ‘pattern’
element). Strips with higher x (larger m) values
must be rendered after strips with lower x
(lower m) values.
The contents of the ‘hatch’ are relative to a new coordinate system. The new coordinate system has its origin at (x, y), where x is established by the ‘x’ attribute on the ‘hatch’ element, and y is established by the ‘y’ attribute on the ‘hatch’ element. The coordinate system is rotated around the origin by the angle given by the ‘rotate’ attribute.
The viewBox and preserveAspectRatio attributes are not useful and have been removed (as compared to the pattern element).
Event listeners attached to the contents of a ‘hatch’ element are not processed; only the rendering aspects of ‘hatch’ elements are processed.
The following illustrates a very simple ‘hatch’ fill:
<hatch pitch="5" rotate="135"> <hatchpath stroke="#a080ff" stroke-width="2"/> </hatch>
Proper examples with links to the SVG need to be given.
Hatch paths are defined by a ‘hatchpath’ element.
Defines a single path in the ‘hatch’.
Defines the point along the reference line where a path begins.
Hatch paths are defined with the same Path data used in the ‘d’ attribute of the ‘path’ element. The path is defined relative to the origin of each strip translated in the x direction by the ‘offset’ (the y direction is aligned along the infinite axis of the strip).
If a ‘d’ attribute is not provided, the path defaults to an infinitely long line aligned with the y-axis of the reference strip and passing through a point ‘offset’ distance in the x direction from the strip origin (see above).
If a ‘d’ attribute is given, the hatch path is constructed
by repeating the ‘d’ data, each time with an offset along the
y-axis determined by the y value of the last
path data point. (The offset must be positive, a negative or zero
offset value results in the hatch path not being rendered.) A hatch
path need not start with a "moveto" path instruction. If missing, the
first path instruction uses for its current point a value of
(x,0) where x is the x
value of the last data point given in the path. If the first path
command is not a "moveto" and the last not a "closepath", the last
point of each repeating section is joined to the first point of the
next repeating section with the current value
of ‘stroke-linejoin
’.
A hatch path can have any of the stroke style properties applied to it, however only
solid color paint servers are allowed for the ‘stroke
’ property.
Limiting 'stroke' to solid paint servers was resolved at the Tokyo F2F.
<hatch hatchUnits="userSpaceOnUse" pitch="6"> <hatchpath stroke-width="1" d="c 0,4 8,6 8,10 8,14 0,16 0,20"/> </hatch>
<hatch hatchUnits="userSpaceOnUse" pitch="20"> <hatchpath stroke-width="2" d="L 0,0 10,50"/> </hatch>
<hatch hatchUnits="userSpaceOnUse" pitch="20"> <hatchpath stroke-width="2" d="M 0,0 10,50"/> </hatch>
<hatch hatchUnits="userSpaceOnUse" pitch="20"> <hatchpath stroke-width="2"/> <hatchpath stroke-width="2" offset="5" stroke-dasharray="10 4 2 4"/> </hatch>
IDL needs to be added for SVGSolidcolorElement.
interface SVGGradientElement : SVGElement { // Spread Method Types const unsigned short SVG_SPREADMETHOD_UNKNOWN = 0; const unsigned short SVG_SPREADMETHOD_PAD = 1; const unsigned short SVG_SPREADMETHOD_REFLECT = 2; const unsigned short SVG_SPREADMETHOD_REPEAT = 3; readonly attribute SVGAnimatedEnumeration gradientUnits; readonly attribute SVGAnimatedTransformList gradientTransform; readonly attribute SVGAnimatedEnumeration spreadMethod; }; SVGGradientElement implements SVGURIReference; SVGGradientElement implements SVGUnitTypes;
interface SVGLinearGradientElement : SVGGradientElement { readonly attribute SVGAnimatedLength x1; readonly attribute SVGAnimatedLength y1; readonly attribute SVGAnimatedLength x2; readonly attribute SVGAnimatedLength y2; };
interface SVGRadialGradientElement : SVGGradientElement { readonly attribute SVGAnimatedLength cx; readonly attribute SVGAnimatedLength cy; readonly attribute SVGAnimatedLength r; readonly attribute SVGAnimatedLength fx; readonly attribute SVGAnimatedLength fy; readonly attribute SVGAnimatedLength fr; };
interface SVGMeshElement : SVGGradientElement { readonly attribute SVGAnimatedLength x; readonly attribute SVGAnimatedLength y; };
interface SVGMeshrowElement : SVGElement { };
interface SVGMeshpatchElement : SVGElement { };
interface SVGStopElement : SVGElement { readonly attribute SVGAnimatedNumber offset; };
interface SVGPatternElement : SVGElement { readonly attribute SVGAnimatedEnumeration patternUnits; readonly attribute SVGAnimatedEnumeration patternContentUnits; readonly attribute SVGAnimatedTransformList patternTransform; readonly attribute SVGAnimatedLength x; readonly attribute SVGAnimatedLength y; readonly attribute SVGAnimatedLength width; readonly attribute SVGAnimatedLength height; }; SVGPatternElement implements SVGFitToViewBox; SVGPatternElement implements SVGURIReference; SVGPatternElement implements SVGUnitTypes;
IDL needs to be added for SVGHatchElement.
SVG content can be interactive (i.e., responsive to user-initiated events) by utilizing the following features in the SVG language:
This chapter describes:
Related information can be found in other chapters:
SVG 2 Requirement: | Support anchor change events. |
---|---|
Resolution: | SVG 2 will consider adding HTML document wide events (including hashchange) apply to SVG documents where they make sense. |
Purpose: | To allow authors to use the same set of event listener attributes on a root SVG element that they can on an HTML body or root element. |
Owner: | Cameron (ACTION-3278) |
SVG 2 Requirement: | Have event listener attributes on an appropriate interface. |
---|---|
Resolution: | SVG 2 will move all events listener attributes to Element, in accordance with the similar move in HTML. |
Purpose: | To align with HTML. |
Owner: | Cameron (ACTION-3283) |
SVG 2 Requirement: | Introduce evt as an alias to event in event handlers. |
---|---|
Resolution: | We decide to resolve ISSUE-2176 by introducing evt as an alias to event in event handlers. |
Purpose: | To align with HTML. |
Owner: | Cameron (ACTION-3093) |
SVG 2 Requirement: | Support drag & drop functionality. |
---|---|
Resolution: | SVG 2 may require drag & drop functionality, and we'll investigate HTML5's functionality for that. |
Purpose: | To allow easier drag & drop in SVG, and to align with HTML. |
Owner: | Erik (ACTION-3328) |
The following aspects of SVG are affected by events:
There should be a note here saying we have changed some of the event names since SVG 1.1. Don't repeat events that are already in DOM Events or HTML, instead just reference those specs for the list of events to support.
The following table lists all of the events which are recognized and supported in SVG. The Event name in the first column is the name to use within SVG's animation elements to define the events which can start or end animations. The DOM3 Event name in the second column is the name to use when defining DOM 3 event listeners ([DOM3EVENTS], section 4.3).
Requirements in the table on whether an event of a given type
bubbles or is cancelable apply only to events that are created and
dispatched by the user agent. Events of those types created from script
using the createEvent
method on the Document interface can be made to bubble
or be cancelable with the
initEvent
method.
Event name and description | DOM3 Event name | Event category | Event attribute name |
---|---|---|---|
focus Occurs when an element receives focus. The focus must be given to the element before the dispatch of this event type. |
(same) | FocusEvent | onfocus |
focusin Occurs when an element is about to receive focus. |
(same) | FocusEvent | onfocusin |
focusout Occurs when an element is about to lose focus. The event must be dispatched to before the element loses focus. The element must be the element which is about to lose focus |
(same) | FocusEvent | onfocusout |
blur Occurs when an element loses focus. The focus must be taken from the element before the dispatch of this event type. |
(same) | FocusEvent | onblur |
keydown Occurs when a key is pressed down. The keydown event type is device dependent and relies on the capabilities of the input devices and how they are mapped in the operating system. |
(same) | KeyboardEvent | onkeydown |
keyup A user agent must dispatch this event when a key is released. The keyup event type is device dependent and relies on the capabilities of the input devices and how they are mapped in the operating system. |
(same) | KeyboardEvent | onkeyup |
click Occurs when the pointing device button is clicked over
an element or when the pointer is otherwise activated in a manner that simulates such an action. A click is defined as a mousedown and mouseup
over the same screen location. The sequence of these events
is: |
(same) | MouseEvent | onclick |
mousedown Occurs when the pointing device button is pressed over an element. |
(same) | MouseEvent | onmousedown |
mouseup Occurs when the pointing device button is released over an element. |
(same) | MouseEvent | onmouseup |
mouseover Occurs when the pointing device is moved onto an element. |
(same) | MouseEvent | onmouseover |
mousemove Occurs when the pointing device is moved while it is over an element. |
(same) | MouseEvent | onmousemove |
mouseout Occurs when the pointing device is moved away from an element. |
(same) | MouseEvent | onmouseout |
load The load event is dispatched only to structurally external elements and to the Window, when the corresponding external resources have finished loading. Note that due to it's relationship with Window the load event on ‘svg’ elements is only dispatched when all resources in the document have been completely loaded. The load event and the error event on structurally external elements are mutually exclusive, only one of these events must be dispatched when processing the element in question. load events do not bubble and are not cancelable. In previous SVG specifications the load event was called SVGLoad and could be dispatched immediately after parsing an element but before the related resource(s) were fully loaded. |
(same) | none | onload |
unload Only applicable to outermost svg elements. The unload event occurs when the DOM implementation removes a document from a window or frame. unload events do not bubble and are not cancelable. |
(same) | none | onunload |
abort The abort event occurs when page loading is stopped before an element has been allowed to load completely. abort events bubble but are not cancelable. |
(same) | none | onabort |
error The error event occurs when a structurally external element does not load properly or when an error occurs during script execution. error events bubble but are not cancelable. |
(same) | none | onerror |
resize Occurs when a document view is being resized. This event is only applicable to outermost svg elements and is dispatched after the resize operation has taken place. The target of the event is the ‘svg’ element. resize events do not bubble and are not cancelable. The term 'document view' is not defined, raised in this www-svg thread. Should probably be linked to CSSOM View, and/or be clarified that it is mostly intended for standalone svg documents. The issue applies to the 'scroll' and 'SVGZoom' events as well. |
(same) | none | onresize |
scroll Occurs when a document view is being shifted along the X or Y or both axis, either through a direct user interaction or any change on the currentTranslate property available on SVGSVGElement interface. This event is only applicable to outermost svg elements and is dispatched after the shift modification has taken place. The target of the event is the ‘svg’ element. scroll events bubble only when dispatched to the document, and are not cancelable. |
(same) | none | onscroll |
SVGZoom Occurs when the zoom level of a document view is being changed, either through a direct user interaction or any change to the currentScale property available on SVGSVGElement interface. This event is only applicable to outermost svg elements and is dispatched after the zoom level modification has taken place. The target of the event is the ‘svg’ element. SVGZoom events bubble but are not cancelable. |
none | none | onzoom |
beginEvent Occurs when an animation element begins. For details, see the description of Interface TimeEvent in the SMIL Animation specification. |
none | none | onbegin |
endEvent Occurs when an animation element ends. For details, see the description of Interface TimeEvent in the SMIL Animation specification. |
none | none | onend |
repeatEvent Occurs when an animation element repeats. It is raised each time the element repeats, after the first iteration. For details, see the description of Interface TimeEvent in the SMIL Animation specification. |
none | none | onrepeat |
Details on the parameters passed to event listeners for the event types for UI Events can be found in the ([ DOM3EVENTS]) and ([UIEVENTS]) specifications where the keybard event definition in UIEVENTS takes precedence over that in DOM3EVENTS. For other event types, the parameters passed to event listeners are described elsewhere in this specification.
Likewise, event-value timing specifiers used in animation element ‘begin’ and ‘end’ attributes are resolved to concrete times only in response to "bubbling" and "at target" phase events dispatched to the relevant element.
On user agents which support interactivity, it is common for authors to define SVG documents such that they are responsive to user interface events. Among the set of possible user events are pointer events, keyboard events, and document events.
In response to user interface (UI) events, the author might start an animation, perform a hyperlink to another Web page, highlight part of the document (e.g., change the color of the graphics elements which are under the pointer), initiate a "roll-over" (e.g., cause some previously hidden graphics elements to appear near the pointer) or launch a script which communicates with a remote database.
User interface events that occur because of user actions performed on a pointer device are called pointer events.
Many systems support pointer devices such as a mouse or trackball. On systems which use a mouse, pointer events consist of actions such as mouse movements and mouse clicks. On systems with a different pointer device, the pointing device often emulates the behavior of the mouse by providing a mechanism for equivalent user actions, such as a button to press which is equivalent to a mouse click.
For each pointer event, the SVG user agent determines the
target element of a given pointer event. The target
element is the topmost graphics element whose relevant
graphical content is under the pointer at the time of the
event. (See property ‘pointer-events
’ for a description
of how to determine whether an element's relevant graphical
content is under the pointer, and thus in which circumstances
that graphic element can be the target element for a pointer
event.) When an element is not displayed (i.e., when the
‘display
’ property on that element
or one of its ancestors has a value of none), that element cannot be the
target of pointer events.
If a target element for the pointer event exists, then the event is dispatched to that element according to the normal event flow ([DOM3EVENTS], section 1.2). For shadow trees created by the ‘use’ element or via script, the event must follow the Shadow DOM event dispatching algorithm [SHADOWDOM]
If a target element for the pointer event does not exist, then the event is ignored.
pointer-events
’ property.There are two distinct aspects of pointer-device interaction with an element or area:
Determining whether a pointer event results in a positive hit-test
depends upon the position of the pointer, the size and shape of the
graphics element, and the computed value of the ‘pointer-events
’
property on the element. The definition of the ‘pointer-events
’
property below describes the exact region that is sensitive to pointer
events for a given type of graphics element.
Note that the ‘svg’ element is not a graphics element, and in a Conforming SVG Stand-Alone File a outermost svg element will never be the target of pointer events, though events can bubble to this element. If a pointer event does not result in a positive hit-test on a graphics element, then it should evoke any user-agent-specific window behavior, such as a presenting a context menu or controls to allow zooming and panning of an SVG document fragment.
This specification does not define the behavior of pointer events on the outermost svg element for SVG images which are embedded by reference or inclusion within another document, e.g., whether the outermost svg element embedded in an HTML document intercepts mouse click events; future specifications may define this behavior, but for the purpose of this specification, the behavior is implementation-specific.
An element which is the target of a user interface event may have particular interaction behaviors, depending upon the type of element and whether it has explicit associated interactions, such as scripted event listeners, CSS pseudo-classes matches, or declarative animations with event-based timing. The algorithm and order for processing user interface events for a given target element, after dispatching the DOM event, is as follows:
preventDefault()
DOM method, then no further processing for this element is performed, and the
event follows the event dispatch and DOM event flow processing
as described in DOM Level 3 Events
[DOM3EVENTS] (or its successor);:hover
,
:active
, or :focus
as described in
[CSS21], section 5.11, then the relevant class
properties are applied;In different circumstances, authors may want to control under what conditions particular graphic elements can become the target of pointer events. For example, the author might want a given element to receive pointer events only when the pointer is over the stroked perimeter of a given shape. In other cases, the author might want a given element to ignore pointer events under all circumstances so that graphical elements underneath the given element will become the target of pointer events.
The effects of masking and clipping differ with respect to pointer events. A clip path is a geometric boundary, and a given point is clearly either inside or outside that boundary; thus, pointer events must be captured normally over the rendered areas of a clipped element, but must not be captured over the clipped areas, as described in the definition of clipping paths. By contrast, a mask is not a binary transition, but a pixel operation, and different behavior for fully transparent and almost-but-not-fully-transparent may be confusingly arbitrary; as a consequence, for elements with a mask applied, pointer events must still be captured even in areas where the mask goes to zero opacity. If an author wishes to achieve an effect where the transparent parts of a mask allow pointer events to pass to an element below, a combination of masking and clipping may be used.
The ‘filter
’ property has no effect on pointer events
processing, and must in this context be treated as if the ‘filter
’
wasn't specified.
For example, suppose a circle with a ‘stroke
’ of
red (i.e., the outline is solid red) and a
‘fill
’ of none (i.e., the interior is not
painted) is rendered directly on top of a rectangle with a ‘fill
’ of
blue. The author might want the circle to be
the target of pointer events only when the pointer is over the perimeter of
the circle. When the pointer is over the interior of the circle, the author
might want the underlying rectangle to be the target element of pointer
events.
The ‘pointer-events
’ property specifies under what circumstances a
given element can be the target element for a pointer event. It affects
the circumstances under which the following are processed:
Name: | pointer-events |
---|---|
Value: | bounding-box | visiblePainted | visibleFill | visibleStroke | visible | painted | fill | stroke | all | none |
Initial: | visiblePainted |
Applies to: | container elements, graphics elements and text content child elements |
Inherited: | yes |
Percentages: | N/A |
Media: | visual |
Computed value: | as specified |
Animatable: | yes |
visibility
’ property is set to
visible and when the pointer is over a
"painted" area. The pointer is over a painted area if it is over the
interior (i.e., fill) of the element and the ‘fill
’ property has
an actual value other than none or it
is over the perimeter (i.e., stroke) of the element and the ‘stroke
’
property is set to a value other than none.visibility
’
property is set to visible and when the
pointer is over the interior (i.e., fill) of the element. The value of
the ‘fill
’ property does not affect event processing.visibility
’ property is set to visible
and when the pointer is over the perimeter (i.e., stroke) of the element.
The value of the ‘stroke
’ property does not affect event processing.visibility
’ property is set to visible
and the pointer is over either the interior (i.e., fill) or the perimeter
(i.e., stroke) of the element. The values of the ‘fill
’ and
‘stroke
’ do not affect event processing.fill
’
property has an actual value other than
none or it is over the perimeter (i.e.,
stroke) of the element and the ‘stroke
’ property has an actual
value other than none. The value of the
‘visibility
’ property does not affect event processing.fill
’ and ‘visibility
’ properties do not affect event
processing.stroke
’ and ‘visibility
’ properties do not affect
event processing.fill
’, ‘stroke
’
and ‘visibility
’ properties do not affect event processing.For text elements, hit-testing is performed on a character cell basis:
fill
’ property is set to a value other than
none or the ‘stroke
’ property is set
to a value other than none, with the
additional requirement that the ‘visibility
’ property is set to
visible.visibility
’ property is set to visible.
The values of the ‘fill
’ and ‘stroke
’ properties do not affect
event processing.fill
’ property is set to a value other than
none or the ‘stroke
’ property is set to
a value other than none. The value of the
‘visibility
’ property does not affect event processing.fill
’, ‘stroke
’
and ‘visibility
’ properties do not affect event processing.For raster images, hit-testing is either performed on a whole-image basis (i.e., the rectangular area for the image is one of the determinants for whether the image receives the event) or on a per-pixel basis (i.e., the alpha values for pixels under the pointer help determine whether the image receives the event):
visibility
’
property is set to visible.visibility
’ property is set to
visible.visibility
’ property does not affect
event processing.visibility
’
property does not affect event processing.Note that for raster images, the values of properties ‘opacity
’,
‘fill-opacity
’, ‘stroke-opacity
’, ‘fill
’ and
‘stroke
’ do not affect event processing.
SVG 2 Requirement: | Support level of detail control. |
---|---|
Resolution: | We will support Level of Detail control in SVG 2. |
Purpose: | Control visibility of elements based on zoom level (useful, for example, in mapping). |
Owner: | Doug (no action) |
Note: | See Tiling and Layering Module for SVG 1.2 Tiny. |
Magnification represents a complete, uniform transformation on an SVG document fragment, where the magnify operation scales all graphical elements by the same amount. A magnify operation has the effect of a supplemental scale and translate transformation placed at the outermost level on the SVG document fragment (i.e., outside the outermost svg element).
Panning represents a translation (i.e., a shift) transformation on an SVG document fragment in response to a user interface action.
SVG user agents that operate in interaction-capable user environments are required to support the ability to magnify and pan.
The outermost svg element in an SVG document fragment has attribute ‘zoomAndPan’, which takes the possible values of disable and magnify, with the default being magnify.
If disable, the user agent shall disable any magnification and panning controls and not allow the user to magnify or pan on the given document fragment.
If magnify, in environments that support user interactivity, the user agent shall provide controls to allow the user to perform a "magnify" operation on the document fragment.
If a ‘zoomAndPan’ attribute is assigned to an inner ‘svg’ element, the ‘zoomAndPan’ setting on the inner ‘svg’ element will have no effect on the SVG user agent.
Animatable: no.
Some interactive display environments provide the ability to modify the appearance of the pointer, which is also known as the cursor. Three types of cursors are available:
The ‘cursor
’ property is used to
specify which cursor to use. The ‘cursor
’ property can be used to
reference standard built-in cursors by specifying a keyword
such as crosshair or a custom cursor. Custom cursors
are referenced via a <url> and can point to either an
external resource such as a platform-specific cursor file or to
a ‘cursor’ element, which can be
used to define a platform-independent cursor.
See the CSS Basic User Interface Module Level 3 specification
for the definition of ‘cursor
’. [CSS3UI]
SVG uses the ‘cursor
’ property to specify the type of cursor to
be displayed for the pointing device when it is over a region of an
element that is sensitive to pointer events, according to the value of
the ‘pointer-events
’ property. SVG extends the definition of
‘cursor
’ from the CSS Basic User Interface Module Level 3
specification as follows:
The ‘cursor’ element can be used to define a platform-independent custom cursor. A recommended approach for defining a platform-independent custom cursor is to create a PNG image [PNG] and define a ‘cursor’ element that references the PNG image and identifies the exact position within the image which is the pointer position (i.e., the hot spot).
The PNG format is recommended because it supports the ability to define a transparency mask via an alpha channel. If a different image format is used, this format should support the definition of a transparency mask (two options: provide an explicit alpha channel or use a particular pixel color to indicate transparency). If the transparency mask can be determined, the mask defines the shape of the cursor; otherwise, the cursor is an opaque rectangle. Typically, the other pixel information (e.g., the R, G and B channels) defines the colors for those parts of the cursor which are not masked out. Note that cursors usually contain at least two colors so that the cursor can be visible over most backgrounds.
Attribute definitions:
Name | Value | Initial value | Animatable |
---|---|---|---|
x, y | <length> | 0 | yes |
Name | Value | Initial value | Animatable |
---|---|---|---|
href | URL [URL] | (none) | yes |
SVG user agents are required to support PNG format images as targets of the ‘href’ attribute.
<!doctype html> <body> <style> body,html { cursor: auto; } circle { pointer-events: all; stroke: black; fill: yellow; stroke-width: 4px; } circle:hover { fill: blue; } svg { width: 200px; height: 200px; } text { font: 32px sans-serif; text-anchor: middle; } #test1 { cursor: url(cursor.svg) 8 1, auto; } #test2 { cursor: url(#cursor), auto; } </style> <svg id="test1" viewBox="0 0 200 200"> <circle cx="100" cy="100" r="75"/> <text x="100" y="100">SVG<tspan x="100" dy="1em">cursor</tspan></text> </svg> <svg id="test2" viewBox="0 0 200 200"> <cursor id="cursor" xlink:href="cursor.png" x="4" y="0"/> <circle cx="100" cy="100" r="75" /> <text x="100" y="100">PNG<tspan x="100" dy="1em">cursor</tspan></text> </svg> </body>
This section needs to defer to HTML more rather than duplicate the wording from that spec.
When an element is focused, key events received by the
document must be targeted at that element. There may be no element
focused; when no element is focused, key events received by the
document must be targeted at the Document
's root svg
element, if
there is one. If there is no root element, key events must not be
fired.
User agents may track focus for each browsing
context or Document
individually, or may support
only one focused element per top-level browsing context
— user agents should follow platform conventions in this
regard.
Which elements within a top-level browsing context currently have focus must be independent of whether or not the top-level browsing context itself has the system focus.
When a child browsing context is focused, its browsing conrtext container must also have focus.
When an element is focused, the element matches the
CSS :focus
pseudo-class.
The ‘tabindex’ attribute allows the author to control whether and element is focusable. Each element can have a tabindex focus flag set, as defined below. This flag is a factor that contributes towards determining whether an element is focusable, as described in the next section.
The user agent should follow platform conventions to determine if the element's tabindex focus flag is set and, if so, whether the element can be reached using sequential focus navigation, and if so, what its relative order should be.
An ‘a’ element that has an ‘href’ attribute must have the tabindex focus flag set.
The user agent must set the element's tabindex focus flag, but should not allow the element to be reached using sequential focus navigation.
One valid reason to ignore the requirement that sequential focus navigation not allow the author to lead to the element would be if the user's only mechanism for moving the focus is sequential focus navigation. For instance, a keyboard-only user would be unable to click on a text field with a negative ‘tabindex’, so that user's user agent would be well justified in allowing the user to tab to the control regardless.
The user agent must set the element's tabindex focus flag, should allow the element to be reached using sequential focus navigation, and should follow platform conventions to determine the element's relative order.
The user agent must set the element's tabindex focus flag, should allow the element to be reached using sequential focus navigation, and should place the element in the sequential focus navigation order so that it is:
An element that has its tabindex focus flag set but does not otherwise have an activation behavior defined has an activation behavior that does nothing.
This means that an element that is only focusable
because of its ‘tabindex’ attribute
will fire a click
event in response
to a non-mouse activation (e.g. hitting the "enter" key while the
element is focused).
The tabIndex
IDL
attribute must reflect the value of the ‘tabindex’ content attribute.
Need to decide how will replace some of the links pertainig to "in a document", "Document", and "being rendered". This is dependent on Document work that needs to be added wrt. tabindex. Do we define our own definitions vs. what is in HTML5?
An element is focusable if the user agent's default behavior allows it to be focusable or if the element has its tabindex focus flag set, but only if the element is either being rendered and only if neither the element nor any of its ancestors are inert.
User agents should make the a element focusable as part of their default behavior, unless platform conventions dictate otherwise:
Notwithstanding the above, user agents may make any element or part of an element focusable, especially to aid with accessibility or to better match platform conventions.
The focusing steps for an element are as follows:
If the element is not in a
Document
, or if the element's
Document
has no browsing context, or if
the element's Document
's browsing context
has no top-level browsing context, or if the element
is not focusable, then abort these steps.
If focusing the element will remove the focus from another element, then run the unfocusing steps for that element.
Make the element the currently focused element in its top-level browsing context.
Fire a simple event named focus
at the element.
User agents must synchronously run the focusing steps for an element whenever the user moves the focus to a focusable element.
The unfocusing steps for an element are as follows:
Unfocus the element.
Fire a simple event named focusout
at the element.
When an element that is focused stops being a focusable element, or stops being focused without another element being explicitly focused in its stead, the user agent should synchronously run the unfocusing steps for the affected element only.
For example, this might happen because the
element is removed from its Document
.
An element is being rendered if it is in a
Document
, either its parent node is itself
being rendered or it is the Document
node,
and it is not explicitly excluded from the rendering using either:
Just being off-screen does not mean the element is not being rendered.
The complete list of events that are part of the SVG language and SVG DOM and descriptions of those events is provided in Complete list of supported events.
The contents of event attributes are always interpreted as ECMAScript, as if processed with the media type 'application/ecmascript'. [RFC2046][RFC4329]
Attribute definitions:
Name | Value | Initial value | Animatable |
---|---|---|---|
onload | (see below) | (none) | no |
Below are the definitions for the graphical event attributes. These can be specified on most graphics elements and container elements. (See the definition for each element to determine whether it can have a graphical event attribute specified on it.)
Note that ‘onload’, defined above, is also classified as a graphical event attribute.
Attribute definitions:
Name | Value | Initial value | Animatable |
---|---|---|---|
onfocusin, onfocusout, onfocus, onblur, onclick, onkeydown, onkeyup, onmousedown, onmouseup, onmouseover, onmousemove, onmouseout | (see below) | (none) | no |
Below are the definitions for the document event attributes. These can be specified only on ‘svg’ elements.
The conformance class for the 'only-on-<svg> elements' criteria needs to be clarified here (this is for document validation presumably, so perhaps Conforming SVG Document Fragments would be appropriate to mention), the document event attributes should be fine to specify on any element, they just don't do much in all such cases, and it makes sense to not encourage uses where it doesn't have any real meaning. For Conforming Dynamic SVG Viewers: what the document event attributes should do is register an event listener for the event in question.
'onerror' should be available on image, script and elements that load external resources. This is related to issue 2254.
Attribute definitions:
Name | Value | Initial value | Animatable |
---|---|---|---|
onunload, onabort, onerror, onresize, onscroll, onzoom | (see below) | (none) | no |
Below are the definitions for the animation event attributes. These can be specified on the animation elements.
Attribute definitions:
Name | Value | Initial value | Animatable |
---|---|---|---|
onbegin, onend, onrepeat | (see below) | (none) | no |
SVG 2 Requirement: | Consider allowing async/defer on ‘script’. |
---|---|
Resolution: | SVG 2 will allow async/defer on ‘script’. |
Purpose: | To align with HTML. |
Owner: | Cameron (ACTION-3280) |
SVG 2 Requirement: | Incorporate SVG Tiny 1.2 script processing model. |
---|---|
Resolution: | SVG 2 will define how inline scriptable content will be processed, in a compatible way to HTML5 |
Purpose: | To have consistent script running behavior across HTML and SVG. |
Owner: | Cameron (ACTION-3282) |
A ‘script’ element is equivalent to the ‘script’ element in HTML and thus is the place for scripts (e.g., ECMAScript). Any functions defined within any ‘script’ element have a "global" scope across the entire current document.
Example script01
defines a function circle_click
which is called by the
‘onclick’ event attribute on the ‘circle’ element. The drawing
below on the left is the initial image. The drawing below on the right shows
the result after clicking on the circle.
Before attempting to execute the ‘script’ element the resolved media type value for ‘type’ must be inspected. If the SVG user agent does not support the scripting language then the ‘script’ element must not be executed.
<?xml version="1.0" standalone="no"?> <svg width="6cm" height="5cm" viewBox="0 0 600 500" xmlns="http://www.w3.org/2000/svg"> <desc>Example script01 - invoke an ECMAScript function from an onclick event </desc> <!-- ECMAScript to change the radius with each click --> <script type="application/ecmascript"> <![CDATA[ function circle_click(evt) { var circle = evt.target; var currentRadius = circle.getAttribute("r"); if (currentRadius == 100) circle.setAttribute("r", currentRadius*2); else circle.setAttribute("r", currentRadius*0.5); } ]]> </script> <!-- Outline the drawing area with a blue line --> <rect x="1" y="1" width="598" height="498" fill="none" stroke="blue"/> <!-- Act on each click event --> <circle onclick="circle_click(evt)" cx="300" cy="225" r="100" fill="red"/> <text x="300" y="480" font-family="Verdana" font-size="35" text-anchor="middle"> Click on circle to change its size </text> </svg>
View this example as SVG (SVG-enabled browsers only)
Attribute definitions:
Name | Value | Initial value | Animatable |
---|---|---|---|
crossorigin | [ anonymous | use-credentials ] | anonymous | yes |
The crossorigin attribute is a CORS settings attribute, and unless otherwise specified follows the same processing rules as in html [HTML].
Name | Value | Initial value | Animatable |
---|---|---|---|
type | (see below) | application/ecmascript | no |
Name | Value | Initial value | Animatable |
---|---|---|---|
href | URL [URL] | (none) | no |
To get the referenced resource, do a potentially CORS-enabled fetch of the absolute URL that resulted from the earlier step, with the mode being the current state of the element's ‘crossorigin’ attribute, the origin being the origin of the ‘script’ element's Document, and the default origin behaviour set to taint. For origin, the rules defined for the html 'script' element apply the same way to the svg ‘script’ element.
interface SVGCursorElement : SVGElement { readonly attribute SVGAnimatedLength x; readonly attribute SVGAnimatedLength y; }; SVGCursorElement implements SVGURIReference;
The SVGScriptElement interface corresponds to the ‘script’ element.
interface SVGScriptElement : SVGElement { attribute DOMString type; attribute DOMString crossOrigin; }; SVGScriptElement implements SVGURIReference;
A DOM consumer can use the hasFeature of the DOMImplementation interface to determine whether the SVG zoom event set has been implemented by a DOM implementation. The feature string for this event set is "SVGZoomEvents". This string is also used with the createEvent method.
The zoom event handler occurs before the zoom event is processed. The remainder of the DOM represents the previous state of the document. The document will be updated upon normal return from the event handler.
The UI event type for a zoom event is:
interface SVGZoomEvent : UIEvent { readonly attribute DOMRectReadOnly zoomRectScreen; readonly attribute float previousScale; readonly attribute DOMPointReadOnly previousTranslate; readonly attribute float newScale; readonly attribute DOMPointReadOnly newTranslate; };
The specified zoom rectangle in screen units.
The DOMRectReadOnly object is read only.
The translation values from previous zoom operations that were in place before the zoom operation occurred.
The DOMPointReadOnly object is read only.
The translation values that will be in place after the zoom operation has been processed.
The DOMPointReadOnly object is read only.
On the Internet, resources are identified using URLs (Internationalized Resource Identifiers). For example, an SVG file called someDrawing.svg located at http://example.com might have the following URL:
http://example.com/someDrawing.svg
An URL can also address a particular element within an XML document by including an URL fragment identifier as part of the URL. An URL which includes an URL fragment identifier consists of an optional base URL, followed by a "#" character, followed by the URL fragment identifier. For example, the following URL can be used to specify the element whose ID is "Lamppost" within file someDrawing.svg:
http://example.com/someDrawing.svg#Lamppost
Internationalized Resource Identifiers (URLs) are a more generalized complement to Uniform Resource Identifiers (URIs). An URL is a sequence of characters from the Universal Character Set [UNICODE]. A URI is constructed from a much more restricted set of characters. All URIs are already conformant URLs. A mapping from URLs to URIs is defined by the URL specification, which means that URLs can be used instead of URIs in XML documents, to identify resources. URLs can be converted to URIs for resolution on a network, if the protocol does not support URLs directly.
Previous versions of SVG, following XLink, defined an URL reference type as a URI or as a sequence of characters which must result in an URL after a particular escaping procedure was applied. The escaping procedure was repeated in the XLink 1.0 specification [XLINK], and in the W3C XML Schema Part 2: Datatypes specification [SCHEMA2]. This copying introduced the possibility of error and divergence, but was done because the URL specification was not yet standardized.
In this specification, the correct term URL is used for this "URI or sequence of characters plus an algorithm" and the escaping method, which turns URLs into URIs, is defined by reference to the URL specification [RFC3987], which has since become an IETF Proposed Standard. Other W3C specifications are expected to be revised over time to remove these duplicate descriptions of the escaping procedure and to refer to URL directly.
In most cases, URLs are specified using an ‘href’ attribute. However, some attributes allow both URLs and text strings as content. To disambiguate a text string from a relative URL, the <url> production is used [CSS3VALUES]. This is simply a URL delimited with a functional notation. This form is used in presentation attributes.
SVG makes extensive use of URL references, both absolute and relative, 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 the following example:
<rect fill="url(#MyGradient)"/>
SVG supports two types of URL references:
The following list describes the elements and properties that allow URL references and the valid target types for those references:
cursor
’ property must reference a resource that can provide an image for the cursor graphicfill
’ property (see Specifying paint for reference rules)marker
’, ‘marker-start
’, ‘marker-mid
’ and ‘marker-end
’ properties must reference a ‘marker’ element.stroke
’ property (see Specifying paint for reference rules)The following rules apply to the processing of invalid URL references:
fill
’ and ‘stroke
’).URL references are normally specified with an ‘href’ attribute. The value of this attribute forms a reference for the desired resource (or secondary resource, if there is a fragment identifier). The value of the ‘href’ attribute must be a URL.
Because it is impractical for any application to check that a value is an URL reference, this specification follows the lead of the URL Specification in this matter and imposes no such conformance testing requirement on SVG applications.
If the URL reference is relative, its absolute version must be computed by the method described in XML Base before use [XML-BASE].
If the protocol, such as HTTP, does not support URLs directly, the URL is converted to a URI by the SVG implementation, as described in section 3.1 of the URL specification [RFC3987].
In previous versions of SVG, the ‘href’ attribute was specified in the XLink namespace [XLINK] namespace. This usage is now deprecated and instead URL references should be specified using the ‘href’ attribute without a namespace.
For backwards compatibility, the deprecated ‘xlink:href’ attribute is defined below along with the ‘xlink:title’ attribute which has also been deprecated.
Attribute definitions:
Name | Value | Initial value | Animatable |
---|---|---|---|
xlink:href | URL [URL] | (none) | (see below) |
For backwards compatibility, elements with an ‘href’ attribute also recognize an ‘href’ attribute in the XLink namespace [XLINK].
When the ‘href’ attribute is present in both the the XLink namespace and without a namespace, the value of the attribute without a namespace shall be used. The attribute in the XLink namespace shall be ignored.
A Conforming SVG Generator must generate ‘href’ attributes without a namespace. However, it may also generate ‘href’ attributes in the XLink namespace to provide backwards compatibility.
This attribute is Animatable if and only if the corresponding ‘href’ attribute is defined to be animatable.
Name | Value | Initial value | Animatable |
---|---|---|---|
xlink:title | <anything> | (none) | no |
Deprecated attribute to describe the meaning of a link or resource in a human-readable fashion. New content should use a ‘title’ child element rather than a ‘xlink:title’ attribute.
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.
The ‘title’ attribute, if used, must be in the XLink namespace. Refer to the XML Linking Language (XLink) [XLINK].
When using the deprecated XLink attributes ‘xlink:href’ or ‘xlink:title’ an explicit XLink namespace declaration must be provided [XML-NS], One simple way to provide such an XLink namespace declaration is to include an ‘xmlns’ attribute for the XLink namespace on the ‘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>
SVG provides an ‘a’ element, to indicate links (also known as hyperlinks or Web links). The ‘a’ element may contain any element that its parent may contain, except itself.
SVG uses XLink ([XLink]) for all link definitions. SVG 1.1 only requires that user agents support XLink's notion of simple links. Each simple link associates exactly two resources, one local and one remote, with an arc going from the former to the latter.
A simple link is defined for each separate rendered element contained within the ‘a’ element; thus, if the ‘a’ element contains three ‘circle’ elements, a link is created for each circle. For each rendered element within an ‘a’ element, the given rendered element is the local resource (the source anchor for the link).
The remote resource (the destination for the link) is defined by an URL specified by the ‘href’ attribute on the ‘a’ element. The remote resource may be any Web resource (e.g., an image, a video clip, a sound bite, a program, another SVG document, an HTML document, an element within the current document, an element within a different document, etc.). By activating these links (by clicking with the mouse, through keyboard input, voice commands, etc.), users may visit these resources.
Example link01 assigns a link to an ellipse.
<?xml version="1.0" standalone="no"?> <svg width="5cm" height="3cm" viewBox="0 0 5 3" version="1.1" xmlns="http://www.w3.org/2000/svg"> <desc>Example link01 - a link on an ellipse </desc> <rect x=".01" y=".01" width="4.98" height="2.98" fill="none" stroke="blue" stroke-width=".03"/> <a href="http://www.w3.org"> <ellipse cx="2.5" cy="1.5" rx="2" ry="1" fill="red" /> </a> </svg>
If the above SVG file is viewed by a user agent that supports both SVG and HTML, then clicking on the ellipse will cause the current window or frame to be replaced by the W3C home page.
Attribute definitions:
Name | Value | Initial value | Animatable |
---|---|---|---|
href | URL [URL] | (none) | yes |
Name | Value | Initial value | Animatable |
---|---|---|---|
target | _self | _parent | _top | _blank | <XML-Name> | _self | yes |
Should the remaining differences with the "valid browsing context name or keyword" definition from HTML be harmonized? Specifically: HTML keywords are case-insensitive; HTML allows any string that doesn't start with "_" as a custom name, (requiring an XML name is more restrictive).
This attribute should be used when there are multiple possible targets for the ending resource, such as when the parent document is embedded within an HTML or XHTML document, or is viewed with a tabbed browser. This attribute specifies the name of the browsing context (e.g., a browser tab or an SVG, HTML, or XHTML iframe or object element) into which a document is to be opened when the link is activated:
The normative definitions for browsing contexts and security restrictions on navigation actions between browsing contexts is HTML 5 [HTML], specifically the chapter on loading web pages.
Previous versions of SVG defined the special target value '_replace'. It was never well implemented, and the distinction between '_replace' and '_self' has been made redundant by changes in the HTML definition of browsing contexts. Use '_self' to replace the current SVG document.
The value '_new' is not a legal value for target. Use '_blank' to open a document in a new tab/window.
Because SVG content often represents a picture or drawing of something, a common need is to link into a particular view of the document, where a view indicates the initial transformations so as to present a closeup of a particular section of the document.
SVG 2 Requirement: | Merge the SVG 1.1 SE text and the SVG Tiny 1.2 text on fragment identifiers link traversal and add media fragments. |
---|---|
Resolution: | SVG 2 will have media fragment identifiers. |
Purpose: | To align with Media Fragments URI. |
Owner: | Cyril (ACTION-3442) |
To link into a particular view of an SVG document, the URL fragment identifier needs to be a correctly formed SVG fragment identifier. An SVG fragment identifier defines the meaning of the "selector" or "fragment identifier" portion of URLs that locate resources of MIME media type "image/svg+xml".
An SVG fragment identifier can come in the following forms:
An SVG fragment identifier is defined as follows:
SVGFragmentIdentifier ::= BareName *( "&" timesegment ) | SVGViewSpec *( "&" timesegment ) | spacesegment *( "&" timesegment ) | timesegment *( "&" spacesegment ) BareName ::= XML_Name SVGViewSpec ::= 'svgView(' SVGViewAttributes ')' SVGViewAttributes ::= SVGViewAttribute | SVGViewAttribute ';' SVGViewAttributes SVGViewAttribute ::= viewBoxSpec | preserveAspectRatioSpec | transformSpec | zoomAndPanSpec | viewTargetSpec viewBoxSpec ::= 'viewBox(' ViewBoxParams ')' preserveAspectRatioSpec = 'preserveAspectRatio(' AspectParams ')' transformSpec ::= 'transform(' TransformParams ')' zoomAndPanSpec ::= 'zoomAndPan(' ZoomAndPanParams ')' viewTargetSpec ::= 'viewTarget(' ViewTargetParams ')'
where:
transform
’ property that is available on
many elements. For example, transform(scale(5)).
Spaces are not allowed in fragment specifications; thus, commas are used to separate numeric values within an SVG view specification (e.g., #svgView(viewBox(0,0,200,200))) and semicolons are used to separate attributes (e.g., #svgView(viewBox(0,0,200,200);preserveAspectRatio(none))).
Semicolons used to separate 'SVGViewAttribute' in SVG fragments may be url-escaped (as %3B); this is useful when animating a (semi-colon separated) list of URLs because otherwise the semicolon would be interpreted as a list separator.
The previous two paragraphs do not reflect actual browser support (spaces are usually supported, commas and URL escaping not always).
The five types of SVGViewAttribute may occur in any order, but each type may only occur at most one time in a correctly formed SVGViewSpec.
When a source document performs a link into an SVG document, for example via an HTML anchor element ([HTML4], section 12.2; i.e., <a href=...> element in HTML) or an XLink specification [XLINK], then the SVG fragment identifier specifies the initial view into the SVG document, as follows:
Do we allow the "pixel:" or "percent:" part of the spatial identifier? If yes, how do they map onto SVG user units?
The ‘view’ element is defined as follows:
Attribute definitions:
Name | Value | Initial value | Animatable |
---|---|---|---|
viewTarget | (see below) | (none) | no |
It is helpful to users if the target element(s) are highlighted. The visual styling of this highlight should be decided by the document author, because the SVG user agent has no way to determine what changes would make the elements more visible.
The CSS :target selector ([SELECTORS], section 6.2.2) may be used in a stylesheet to provide alternate styling for elements which are the target of links. For example:
<style type="text/css"> #foo:target {filter: url(#glow)} /* when the element with id foo is linked to, use a glow filter */ .bar :target {stroke: green; fill-opacity: 0.5} /* when any descendants of elements with class bar are linked to, make the fill partly transparent and use a green stroke */ :target {stroke: red } /* for everything else, just use a red stroke */ </style>
The SVGAElement interface corresponds to the ‘a’ element.
interface SVGAElement : SVGGraphicsElement { readonly attribute SVGAnimatedString target; }; SVGAElement implements SVGURIReference;
The SVGViewElement interface corresponds to the ‘view’ element.
interface SVGViewElement : SVGElement { readonly attribute SVGStringList viewTarget; }; SVGViewElement implements SVGFitToViewBox; SVGViewElement implements SVGZoomAndPan;
SVG supports the ability to change vector graphics over time. SVG content can be animated in the following ways:
SVG's animation elements were developed in collaboration with the W3C Synchronized Multimedia (SYMM) Working Group, developers of the Synchronized Multimedia Integration Language (SMIL) 3.0 Specification [SMIL].
The SYMM Working Group, in collaboration with the SVG Working Group, has authored the SMIL Animation specification [SMILANIM], which represents a general-purpose XML animation feature set. SVG incorporates the animation features defined in the SMIL Animation specification and provides some SVG-specific extensions.
For an introduction to the approach and features available in any language that supports SMIL Animation, see SMIL Animation overview and SMIL Animation animation model ([SMILANIM], sections 2 and 3). For the list of animation features which go beyond SMIL Animation, see SVG extensions to SMIL Animation.
SVG is a host language in terms of SMIL Animation and therefore introduces additional constraints and features as permitted by that specification. Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for SVG's animation elements and attributes is the SMIL Animation specification [SMILANIM].
SVG supports the following three animation elements which are defined in the SMIL Animation specification:
‘animate’ | allows attributes and properties to be assigned different values over time |
‘set’ | a convenient shorthand for ‘animate’, which produces a
discrete change to an animated attribute or property.
It is most commonly used with values which do not support
linear interpolation, such as the ‘visibility ’ property |
‘animateMotion’ | moves an element along a motion path |
Additionally, SVG includes the following compatible extensions to SMIL Animation:
‘animateTransform’ | modifies one of SVG's transformation values over
time, such as the ‘transform ’ property or the
‘patternTransform’ attribute. |
‘path’ attribute | SVG allows any feature from SVG's path data syntax to be specified in a ‘path’ attribute to the ‘animateMotion’ element (SMIL Animation only allows a subset of SVG's path data syntax within a ‘path’ attribute) |
‘mpath’ element | SVG allows an ‘animateMotion’ element to contain a child ‘mpath’ element which references an SVG ‘path’ element or shape element as the definition of the motion path |
‘keyPoints’ attribute | SVG adds a ‘keyPoints’ attribute to the ‘animateMotion’ to provide precise control of the velocity of motion path animations |
‘rotate’ attribute | SVG adds a ‘rotate’ attribute to the ‘animateMotion’ to control whether an object is automatically rotated so that its x-axis points in the same direction (or opposite direction) as the directional tangent vector of the motion path |
For compatibility with other aspects of the language, SVG uses URL references via an ‘href’ attribute to identify the elements which are to be targets of the animations, as allowed in SMIL 3.0.
SMIL Animation requires that the host language define the meaning for document begin and the document end. Since an ‘svg’ is sometimes the root of the XML document tree and other times can be a component of a parent XML grammar, the document begin for a given SVG document fragment is defined to be the exact time at which the ‘svg’ element's load event is triggered. The document end of an SVG document fragment is the point at which the document fragment has been released and is no longer being processed by the user agent. However, nested ‘svg’ elements within an SVG document do not constitute document fragments in this sense, and do not define a separate document begin; all times within the nested SVG fragment are relative to the document time defined for the root ‘svg’ element.
For SVG, the term presentation time indicates the position in the timeline relative to the document begin of a given document fragment.
Example anim01 below demonstrates each of SVG's four animation elements.
<?xml version="1.0" standalone="no"?> <svg width="8cm" height="3cm" viewBox="0 0 800 300" xmlns="http://www.w3.org/2000/svg"> <desc>Example anim01 - demonstrate animation elements</desc> <rect x="1" y="1" width="798" height="298" fill="none" stroke="blue" stroke-width="2" /> <!-- The following illustrates the use of the 'animate' element to animate a rectangles x, y, and width attributes so that the rectangle grows to ultimately fill the viewport. --> <rect id="RectElement" x="300" y="100" width="300" height="100" fill="rgb(255,255,0)" > <animate attributeName="x" begin="0s" dur="9s" fill="freeze" from="300" to="0" /> <animate attributeName="y" begin="0s" dur="9s" fill="freeze" from="100" to="0" /> <animate attributeName="width" begin="0s" dur="9s" fill="freeze" from="300" to="800" /> <animate attributeName="height" begin="0s" dur="9s" fill="freeze" from="100" to="300" /> </rect> <!-- Set up a new user coordinate system so that the text string's origin is at (0,0), allowing rotation and scale relative to the new origin --> <g transform="translate(100,100)" > <!-- The following illustrates the use of the 'set', 'animateMotion', 'animate' and 'animateTransform' elements. The 'text' element below starts off hidden (i.e., invisible). At 3 seconds, it: * becomes visible * continuously moves diagonally across the viewport * changes color from blue to dark red * rotates from -30 to zero degrees * scales by a factor of three. --> <text id="TextElement" x="0" y="0" font-family="Verdana" font-size="35.27" visibility="hidden" > It's alive! <set attributeName="visibility" to="visible" begin="3s" dur="6s" fill="freeze" /> <animateMotion path="M 0 0 L 100 100" begin="3s" dur="6s" fill="freeze" /> <animate attributeName="fill" from="rgb(0,0,255)" to="rgb(128,0,0)" begin="3s" dur="6s" fill="freeze" /> <animateTransform attributeName="transform" type="rotate" from="-30" to="0" begin="3s" dur="6s" fill="freeze" /> <animateTransform attributeName="transform" type="scale" from="1" to="3" additive="sum" begin="3s" dur="6s" fill="freeze" /> </text> </g> </svg>
At zero seconds | At three seconds | |
At six seconds | At nine seconds |
The sections below describe the various animation attributes and elements.
The following attribute is common to all animation elements and identifies the target element for the animation.
Attribute definitions:
Name | Value | Initial value | Animatable |
---|---|---|---|
href | URL [URL] | (none) | no |
A URL reference to the element which is the target of this animation element and which therefore will be modified over time.
The URL must point to exactly one target element which is capable of being the target of the given animation element. If the URL points to multiple target elements, if the given target element is not capable of being a target of the given animation element, or if the given target element is not part of the current document, then the animation element will not affect any target element. However, the animation element will still operate normally with regard to its timing properties. Specifically, TimeEvents are dispatched and the animation element can be used as syncbase in an identical fashion to when the URL refers to a valid target element.
If the ‘href’ attribute or the deprecated ‘xlink:href’ attribute is not provided, then the target element will be the immediate parent element of the current animation element. The behavior when both ‘href’ and ‘xlink:href’ are specified is defined by the common handling for deprecated XLink attributes.
Refer to the descriptions of the individual animation elements for any restrictions on what types of elements can be targets of particular types of animations.
Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for this attribute is the SMIL Animation specification. In particular, see SMIL Animation: Specifying the animation target ([SMILANIM], section 3.1).
The following attribute identifies the target attribute or property for the given target element whose value changes over time.
Attribute definitions:
Name | Value | Initial value | Animatable |
---|---|---|---|
attributeName | Name [EBNF] | (none) | no |
Specifies the name of the target property or attribute.
Unlike SMIL Animation, the attributeType attribute is not supported by SVG. SVG's animation elements follow the behavior defined for the auto value of attributeType. That is, when determining if ‘attributeName’ corresponds to an attribute name or a CSS property name, the implementation must first search through the list of CSS properties for a matching property name. If no matching property is found, the implementation must search for a matching attribute on the target element.
When referencing an attribute, an XMLNS prefix may be used to indicate the XML namespace for the attribute. The prefix will be interpreted in the scope of the current (i.e., the referencing) animation element. Otherwise the implementation must use the default XML namespace for the target element.
Note that, as a result of the behavior, it is not possible to animate the list of coordinates specified by the ‘x’ and ‘y’ attributes on ‘text’ and ‘tspan’ elements. This is because ‘x’ and ‘y’ are also CSS properties where they only accept a single length as a value.
Due to the complex mapping between characters and glyphs, using the list-based syntax for ‘x’ and ‘y’ to specify glyph positions does not scale well to anything beyond very simple Latin text and its use is discouraged. Authors who nevertheless wish to animate this list of coordinates may be able to achieve a comparable effect using the ‘dx’ and ‘dy’ attributes instead since these names to not overlap with CSS properties.
Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for this attribute is the SMIL Animation specification. In particular, see SMIL Animation: Specifying the animation target ([SMILANIM], section 3.1).
Example animns01 below shows a namespace prefix being resolved to a namespace name in the scope of the referencing element, and that namespace name being used (regardless of the prefix which happens to be used in the target scope) to identify the attribute being animated.
<?xml version="1.0" encoding="UTF-8"?> <svg version="1.1" xmlns="http://www.w3.org/2000/svg"> <title>Demonstration of the resolution of namespaces for animation</title> <!-- at the point of definition, the QName a:href resolves to the namespace name "http://www.w3.org/1999/xlink" and the local name "href" --> <g xmlns:a="http://www.w3.org/1999/xlink"> <animate attributeName="a:href" href="#foo" dur="2s" to="two.png" fill="freeze"/> </g> <!-- at the point of use, the namespace name "http://www.w3.org/1999/xlink" happens to be bound to the namespace prefix 'b' --> <g xmlns:b="http://www.w3.org/1999/xlink"> <image id="foo" b:href="one.png" x="35" y="50" width="410" height="160"/> </g> </svg>
Paced animations assume a notion of distance between the various animation values defined by the ‘to’, ‘from’, ‘by’ and ‘values’ attributes. Distance is defined only for scalar types (such as <length>), colors and the subset of transformation types that are supported by ‘animateTransform’. In the list of distance functions below, Va and Vb represent the two values the distance between which is being calculated.
Since paced animation is intended to produce an animation with an even pace of change, it does not make sense to define distance functions for all data types. Distance can be usefully defined for types whose values are n-dimensional vectors (including scalars, which are 1-dimensional vectors). For example, a <length> value is a scalar value, and a <color> value is a 3-dimensional vector. Thus attributes of these types can have paced animation applied to them. On the other hand, a <dasharray> (as used by ‘stroke-dasharray’) is a list of scalars (1-dimensional vectors), and <points> (as used by the ‘points’ attribute on a ‘polygon’) is a list of 2-dimensional vectors. Therefore, these types do not have a distance function defined and cannot have paced animation applied to them.
The distance functions for types that support paced animation are as follows:
distance(Va, Vb) = |Va − Vb|
Examples: animating the
‘x’ attribute on a
‘text’, or the
‘stroke-width
’
property on a ‘circle’.
distance(Va, Vb) = sqrt((Va.red − Vb.red)2 + (Va.green − Vb.green)2 + (Va.blue − Vb.blue)2), where:
Each of the color component values is usually in the range [0, 1], where 0 represents none of that color component, and 1 represents the maximum amount of that color component, in the sRGB gamut [SRGB]. Since <color> values may specify colors outside of the sRGB gamut, these component values may lie outside the range [0, 1].
distance(Va, Vb) = sqrt((Va.tx − Vb.tx)2 + (Va.ty − Vb.ty)2), where:
Example (for all transform definition types): animating the ‘transform
’
attribute on a ‘g’ using ‘animateTransform’.
distance(Va, Vb) = sqrt((Va.sx − Vb.sx)2 + (Va.sy − Vb.sy)2), where:
Note that, as when specifying scale transformations in a <transform-list>, if the y component of the scale is omitted it is implicitly equal to the x component.
distance(Va, Vb) = sqrt((Va.angle − Vb.angle)2), where:
Since the distance function for rotations is not in terms of the rotation center point components, a paced animation that changes the rotation center point may not appear to have a paced movement when the animation is applied.
Distance functions for all other data types are not defined. If calcMode="paced" is used on an animation of an attribute or property whose type is not one of those listed above, the animation effect is undefined. SVG user agents may choose to perform the animation as if calcMode="linear", but this is not required. Authors are recommended not to specify paced animation on types not listed above.
The following attributes are the animation timing attributes. They are common to all animation elements and control the timing of the animation, including what causes the animation to start and end, whether the animation runs repeatedly, and whether to retain the end state the animation once the animation ends.
In the syntax specifications that follow, optional white space is indicated as "S", defined as follows:
S ::= (#x20 | #x9 | #xD | #xA)*
Align with whitespace used in CSS and SVG, adding #xC to S.
Attribute definitions:
Name | Value | Initial value | Animatable |
---|---|---|---|
begin | begin-value-list | 0s | no |
Attribute syntax needs fixing.
Defines when the element should begin (i.e. become active).
The attribute value is a semicolon separated list of values.
begin
or end
to
identify whether to synchronize with the beginning or
active end of the referenced animation element.The begin of the animation will be determined by a "beginElement()" method call or a hyperlink targeted to the element.
The animation DOM methods are described in DOM interfaces.
Hyperlink-based timing is described in SMIL Animation: Hyperlinks and timing.
Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for this attribute is the SMIL Animation specification. In particular, see SMIL Animation: 'begin' attribute ([SMILANIM], section 3.2.1).
Name | Value | Initial value | Animatable |
---|---|---|---|
dur | Clock-value | "media" | "indefinite" | indefinite | no |
Attribute syntax needs fixing.
Specifies the simple duration.
The attribute value can be one of the following:
If the animation does not have a ‘dur’ attribute, the simple duration is indefinite. Note that interpolation will not work if the simple duration is indefinite (although this may still be useful for ‘set’ elements). Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for this attribute is the SMIL Animation specification. In particular, see SMIL Animation: 'dur' attribute ([SMILANIM], section 3.2.1).
Name | Value | Initial value | Animatable |
---|---|---|---|
end | end-value-list | (none) | no |
Attribute syntax needs fixing.
Defines an end value for the animation that can constrain the active duration. The attribute value is a semicolon separated list of values.
A value of 'indefinite' specifies that the end of the animation will be determined by an endElement method call (the animation DOM methods are described in DOM interfaces).
Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for this attribute is the SMIL Animation specification. In particular, see SMIL Animation: 'end' attribute ([SMILANIM], section 3.3.2).
Name | Value | Initial value | Animatable |
---|---|---|---|
min | Clock-value | "media" | 0s | no |
max | Clock-value | "media" | (none) | no |
Attribute syntax needs fixing.
The ‘min’ and ‘max’ attributes specify the minimum and maximum value of the active duration, respectively.
The attribute values can be either of the following:
Specifies the length of the minimum or maximum value of the active duration, measured in local time.
Value must be greater than 0.
The initial value for ‘min’ is '0' and there is no initial value for ‘max’. In both cases, this does not constrain the active duration at all.
Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for these attributes is the SMIL Animation specification. In particular, see SMIL Animation: The min and max attributes ([SMILANIM], section 3.3.3).
Name | Value | Initial value | Animatable |
---|---|---|---|
restart | always | whenNotActive | never | always | no |
Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for this attribute is the SMIL Animation specification. In particular, see SMIL Animation: 'restart' attribute ([SMILANIM], section 3.3.7).
Name | Value | Initial value | Animatable |
---|---|---|---|
repeatCount | <number> | indefinite | (none) | no |
Specifies the number of iterations of the animation function. It can have the following attribute values:
Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for this attribute is the SMIL Animation specification. In particular, see SMIL Animation: 'repeatCount' attribute ([SMILANIM], section 3.3.1).
Name | Value | Initial value | Animatable |
---|---|---|---|
repeatDur | Clock-value | "indefinite" | (none) | no |
Attribute syntax needs fixing.
Specifies the total duration for repeat. It can have the following attribute values:
f(t)
.Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for this attribute is the SMIL Animation specification. In particular, see SMIL Animation: 'repeatDur' attribute ([SMILANIM], section 3.3.1).
Name | Value | Initial value | Animatable |
---|---|---|---|
fill | freeze | remove | remove | no |
This attribute can have the following values:
The animation effect is removed (no longer applied) when the active duration of the animation is over. After the active end of the animation, the animation no longer affects the target (unless the animation is restarted - see SMIL Animation: Restarting animation).
Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for this attribute is the SMIL Animation specification. In particular, see SMIL Animation: 'fill' attribute ([SMILANIM], section 3.3.5).
The SMIL Animation specification [SMILANIM] defines the detailed processing rules associated with the above attributes. Except for any SVG-specific rules explicitly mentioned in this specification, the SMIL Animation specification is the normative definition of the processing rules for the above attributes.
Clock values have the same syntax as in SMIL Animation specification [SMILANIM]. The grammar for clock values is repeated here:
Clock-val ::= Full-clock-val | Partial-clock-val | Timecount-val Full-clock-val ::= Hours ":" Minutes ":" Seconds ("." Fraction)? Partial-clock-val ::= Minutes ":" Seconds ("." Fraction)? Timecount-val ::= Timecount ("." Fraction)? (Metric)? Metric ::= "h" | "min" | "s" | "ms" Hours ::= DIGIT+; any positive number Minutes ::= 2DIGIT; range from 00 to 59 Seconds ::= 2DIGIT; range from 00 to 59 Fraction ::= DIGIT+ Timecount ::= DIGIT+ 2DIGIT ::= DIGIT DIGIT DIGIT ::= [0-9]
For Timecount values, the default metric suffix is "s" (for seconds). No embedded white space is allowed in clock values, although leading and trailing white space characters will be ignored.
Clock values describe presentation time.
The following are examples of legal clock values:
02:30:03
= 2 hours, 30 minutes and 3 seconds 50:00:10.25
= 50 hours, 10 seconds and 250 milliseconds
02:33
= 2 minutes and 33 seconds 00:10.5
= 10.5 seconds = 10 seconds and 500 milliseconds 3.2h
= 3.2 hours = 3 hours and 12 minutes 45min
= 45 minutes 30s
= 30 seconds 5ms
= 5 milliseconds 12.467
= 12 seconds and 467 millisecondsFractional values are just (base 10) floating point definitions of seconds. Thus:
00.5s
= 500 milliseconds
00:00.005
= 5 milliseconds
The following attributes are the animation value attributes. They are common to elements ‘animate’, ‘animateMotion’ and ‘animateTransform’. These attributes define the values that are assigned to the target attribute or property over time. The attributes below provide control over the relative timing of keyframes and the interpolation method between discrete values.
Attribute definitions:
Name | Value | Initial value | Animatable |
---|---|---|---|
calcMode | discrete | linear | paced | spline | (none) | no |
Specifies the interpolation mode for the animation. This can take any of the following values. The default mode is 'linear', however if the attribute does not support linear interpolation (e.g. for strings), the ‘calcMode’ attribute is ignored and discrete interpolation is used.
Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for this attribute is the SMIL Animation specification. In particular, see SMIL Animation: 'calcMode' attribute ([SMILANIM], section 3.2.3).
Name | Value | Initial value | Animatable |
---|---|---|---|
values | (see below) | (none) | no |
The ‘values’ attribute specifies a sequence of values to use over the course of the animation.
The attribute is parsed as follows:
Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for this attribute is the SMIL Animation specification. In particular, see SMIL Animation: 'values' attribute ([SMILANIM], section 3.2.2).
Name | Value | Initial value | Animatable |
---|---|---|---|
keyTimes | <number> [; <number>]* ;? | (none) | no |
A semicolon-separated list of time values used to control the pacing of the animation. Each time in the list corresponds to a value in the ‘values’ attribute list, and defines when the value is used in the animation function.
Each time value in the ‘keyTimes’ list is specified as a floating point value between 0 and 1 (inclusive), representing a proportional offset into the simple duration of the animation element.
If the last semicolon separator is followed by either just white space or no more characters, ignore both the separator and the trailing white space.
For animations specified with a ‘values’ list, the ‘keyTimes’ attribute if specified must have exactly as many values as there are in the ‘values’ attribute. For from/to/by animations, the ‘keyTimes’ attribute if specified must have two values.
Each successive time value must be greater than or equal to the preceding time value.
The ‘keyTimes’ list semantics depends upon the interpolation mode:
If the interpolation mode is 'paced', the ‘keyTimes’ attribute is ignored.
If there are any errors in the ‘keyTimes’ specification (bad values, too many or too few values), the document fragment is in error (see error processing).
If the simple duration is indefinite, any ‘keyTimes’ specification will be ignored.
Because paced animation interpolation is unspecified for some value types, authors are encouraged to use 'linear' animation interpolation with calculated ‘keyTimes’ to achieve particular interpolation behavior for these types.
Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for this attribute is the SMIL Animation specification. In particular, see SMIL Animation: 'keyTimes' attribute ([SMILANIM], section 3.2.3).
Name | Value | Initial value | Animatable |
---|---|---|---|
keySplines | <control-point> [; <control-point>]* ;? | (none) | no |
where:
<control-point> = <number> ,? <number> ,? <number> ,? <number>
A set of Bézier control points associated with the ‘keyTimes’ list, defining a cubic Bézier function that controls interval pacing. The attribute value is a semicolon-separated list of control point descriptions.
If the last semicolon separator is followed by either just white space or no more characters, ignore both the separator and the trailing white space.
Each control point description is a set
of four values: x1 y1 x2 y2
, describing the
Bézier control points for one time segment. Note:
SMIL
allows these values to be separated either by commas with
optional whitespace, or by whitespace alone. The
‘keyTimes’ values that define the associated
segment are the Bézier "anchor points", and the
‘keySplines’ values are the control points.
Thus, there must be one fewer sets of control points than
there are ‘keyTimes’.
The values must all be in the range 0 to 1.
This attribute is ignored unless the ‘calcMode’ is set to 'spline'.
If there are any errors in the ‘keySplines’ specification (bad values, too many or too few values), the document fragment is in error (see error processing).
Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for this attribute is the SMIL Animation specification. In particular, see SMIL Animation: 'keySplines' attribute ([SMILANIM], section 3.2.3).
Name | Value | Initial value | Animatable |
---|---|---|---|
from, to, by | (see below) | (none) | no |
The ‘from’ and ‘to’ attributes specify the starting and ending value of the animation, while the ‘by’ attribute specifies a relative offset value for the animation.
All three attributes must be parsed using the rules for parsing the attribute identified by the ‘href’ and ‘attributeName’ attributes.
For example, if ‘href’ identified a ‘circle’ element and ‘attributeName’ is 'stroke-width', then the ‘from’, ‘to’ or ‘by’ attribute is parsed as a [<percentage> | <length>].
Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for these attributes is the SMIL Animation specification. In particular, see SMIL Animation: Animation function values ([SMILANIM], section 3.2.2).
The SMIL Animation specification [SMILANIM] defines the detailed processing rules associated with the above attributes. Except for any SVG-specific rules explicitly mentioned in this specification, the SMIL Animation specification is the normative definition of the processing rules for the above attributes.
The animation values specified in the animation element must be legal values for the specified attribute. Leading and trailing white space, and white space before and after semicolon separators, will be ignored.
All values specified must be legal values for the specified attribute (as defined in the associated namespace). If any values are not legal, the document fragment is in error (see error processing).
If a list of values is used, the animation will apply the values in order over the course of the animation. If a list of ‘values’ is specified, any ‘from’, ‘to’ and ‘by’ attribute values are ignored.
The processing rules for the variants of from/by/to animations are described in Animation function values with the following exception.
In order to provide behavior that is intuitive and consistent between discrete animations with an explicitly specified ‘from’ attribute (e.g. "from-to animation") and those where the underlying value is used (e.g. "to animation"), the behavior of discrete to-animation in SVG deviates from the definition in SMIL Animation. As with a discrete from-to animation, a discrete to animation will set the underlying value for the first half of the simple duration (or, if a ‘keyTimes’ list is provided, until the simple duration specified by the second value in the ‘keyTimes’ list) and the ‘to’ value for the remainder of the simple duration.
The following figure illustrates the interpretation of the ‘keySplines’ attribute. Each diagram illustrates the effect of ‘keySplines’ settings for a single interval (i.e. between the associated pairs of values in the ‘keyTimes’ and ‘values’ lists.). The horizontal axis can be thought of as the input value for the unit progress of interpolation within the interval - i.e. the pace with which interpolation proceeds along the given interval. The vertical axis is the resulting value for the unit progress, yielded by the function that the ‘keySplines’ attribute defines. Another way of describing this is that the horizontal axis is the input unit time for the interval, and the vertical axis is the output unit time. See also the section Timing and real-world clock times.
keySplines="0 0 1 1" (the default) | keySplines=".5 0 .5 1" |
keySplines="0 .75 .25 1" | keySplines="1 0 .25 .25" |
To illustrate the calculations, consider the simple example:
<animate dur="4s" values="10; 20" keyTimes="0; 1" calcMode="spline" keySplines={as in table} />
Using the ‘keySplines’ values for each of the four cases above, the approximate interpolated values as the animation proceeds are:
Value of ‘keySplines’ | Initial value | After 1s | After 2s | After 3s | Final value |
---|---|---|---|---|---|
0 0 1 1 | 10.0 | 12.5 | 15.0 | 17.5 | 20.0 |
.5 0 .5 1 | 10.0 | 11.0 | 15.0 | 19.0 | 20.0 |
0 .75 .25 1 | 10.0 | 18.0 | 19.3 | 19.8 | 20.0 |
1 0 .25 .25 | 10.0 | 10.1 | 10.6 | 16.9 | 20.0 |
For a formal definition of Bézier spline calculation, see [FOLEY-VANDAM], pp. 488-491.
It is frequently useful to define animation as an offset or delta to an attribute's value, rather than as absolute values.
A simple "grow" animation can increase the width of an object by 10 pixels:
<rect width="20px" ...> <animate attributeName="width" from="0px" to="10px" dur="10s" additive="sum"/> </rect>
It is frequently useful for repeated animations to build upon the previous results, accumulating with each iteration.
The following example causes the rectangle to continue to grow with each repeat of the animation:
<rect width="20px" ...> <animate attributeName="width" from="0px" to="10px" dur="10s" additive="sum" accumulate="sum" repeatCount="5"/> </rect>
At the end of the first repetition, the rectangle has a width of 30 pixels. At the end of the second repetition, the rectangle has a width of 40 pixels. At the end of the fifth repetition, the rectangle has a width of 70 pixels.
For more information about additive animations, see SMIL Animation: Additive animation. For more information on cumulative animations, see SMIL Animation: Controlling behavior of repeating animation - Cumulative animation.
The following attributes are the animation addition attributes, which are common to elements ‘animate’, ‘animateMotion’ and ‘animateTransform’.
Attribute definitions:
Name | Value | Initial value | Animatable |
---|---|---|---|
additive | replace | sum | replace | no |
Controls whether or not the animation is additive.
Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for this attribute is the SMIL Animation specification. In particular, see SMIL Animation: 'additive' attribute ([SMILANIM], section 3.3.6).
Name | Value | Initial value | Animatable |
---|---|---|---|
accumulate | none | sum | none | no |
Controls whether or not the animation is cumulative.
This attribute is ignored if the target attribute value does not support addition, or if the animation element does not repeat.
Cumulative animation is not defined for "to animation".
This attribute will be ignored if the animation function is specified with only the ‘to’ attribute.
Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for this attribute is the SMIL Animation specification. In particular, see SMIL Animation: 'accumulate' attribute ([SMILANIM], section 3.3.1).
SVG allows both attributes and properties to be animated. If a given attribute or property is inheritable by descendants, then animations on a parent element such as a ‘g’ element has the effect of propagating the attribute or property animation values to descendant elements as the animation proceeds; thus, descendant elements can inherit animated attributes and properties from their ancestors.
The ‘animate’ element is used to animate a single attribute or property over time.
This example makes a rectangle repeatedly fade away over 5 seconds:
<rect> <animate attributeName="opacity" from="1" to="0" dur="5s" repeatCount="indefinite" /> </rect>
Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for this element is the SMIL Animation specification. In particular, see SMIL Animation: 'animate' element ([SMILANIM], section 4.1).
The ‘color-interpolation
’ property applies to color interpolations
that result from animations using the ‘animate’ element.
For a list of attributes and properties that can be animated using the ‘animate’ element, see Elements, attributes and properties that can be animated.
The ‘set’ element provides a simple means of just setting the value of an attribute for a specified duration. It supports all attribute types, including those that cannot reasonably be interpolated, such as string and boolean values. The ‘set’ element is non-additive. The additive and accumulate attributes are not allowed, and will be ignored if specified.
Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for this element is the SMIL Animation specification. In particular, see SMIL Animation: 'set' element ([SMILANIM], section 4.2).
Attribute definitions:
Name | Value | Initial value | Animatable |
---|---|---|---|
to | <value> | (none) | no |
For a list of attributes and properties that can be animated using the ‘set’ element, see Elements, attributes and properties that can be animated.
The ‘animateMotion’ element causes a referenced element to move along a motion path.
Except for any SVG-specific rules explicitly mentioned in this specification, the normative definition for this element is the SMIL Animation specification. In particular, see SMIL Animation: 'animateMotion' element ([SMILANIM], section 4.3).
Attribute definitions:
Name | Value | Initial value | Animatable |
---|---|---|---|
calcMode | discrete | linear | paced | spline | paced | no |
Specifies the interpolation mode for the animation. Refer to general description of the ‘calcMode’ attribute above. The only difference is that the default value for the ‘calcMode’ for ‘animateMotion’ is 'paced'. See SMIL Animation: 'calcMode' attribute for 'animateMotion'.
Name | Value | Initial value | Animatable |
---|---|---|---|
path | svg-path [EBNF] | (none) | no |
The motion path, expressed in the same format and interpreted the same way as the ‘d’ attribute on the ‘path’ element. The effect of a motion path animation is to add a supplemental transformation matrix onto the CTM for the referenced object which causes a translation along the x- and y-axes of the current user coordinate system by the computed X and Y values computed over time.
Name | Value | Initial value | Animatable |
---|---|---|---|
keyPoints | <number> [; <number>]* ;? | (none) | no |
‘keyPoints’ takes a semicolon-separated list of floating point values between 0 and 1 and indicates how far along the motion path the object shall move at the moment in time specified by corresponding ‘keyTimes’ value. Distance calculations use the user agent's distance along the path algorithm. Each progress value in the list corresponds to a value in the ‘keyTimes’ attribute list.
If a list of ‘keyPoints’ is specified, there must be exactly as many values in the ‘keyPoints’ list as in the ‘keyTimes’ list.
If the last semicolon separator is followed by either just white space or no more characters, ignore both the separator and the trailing white space.
If there are any errors in the ‘keyPoints’ specification (bad values, too many or too few values), then the document is in error (see Error processing).
Name | Value | Initial value | Animatable |
---|---|---|---|
rotate | <number> | auto | auto-reverse | 0 | no |
The ‘rotate’ attribute post-multiplies a supplemental transformation matrix onto the CTM of the target element to apply a rotation transformation about the origin of the current user coordinate system. The rotation transformation is applied after the supplemental translation transformation that is computed due to the ‘path’ attribute.
Name | Value | Initial value | Animatable |
---|---|---|---|
origin | default | default | no |
The ‘origin’ attribute is defined in the SMIL Animation specification ([SMILANIM], section 4.3). It has no effect in SVG.
Attribute definitions:
Name | Value | Initial value | Animatable |
---|---|---|---|
href | URL [URL] | (none) | no |
A URL reference to the ‘path’ element or shape element which defines the motion path. Refer to the common handling defined for URL reference attributes and deprecated XLink attributes.
For ‘animateMotion’, the specified values for ‘from’, ‘by’, ‘to’ and ‘values’ consists of x, y coordinate pairs, with a single comma and/or white space separating the x coordinate from the y coordinate. For example, from="33,15" specifies an x coordinate value of 33 and a y coordinate value of 15.
If provided, the ‘values’ attribute must consists of a list of x, y coordinate pairs. Coordinate values are separated by at least one white space character or a comma. Additional white space around the separator is allowed. For example, values="10,20;30,20;30,40" or values="10mm,20mm;30mm,20mm;30mm,40mm". Each coordinate represents a <length>. Attributes ‘from’, ‘by’, ‘to’ and ‘values’ specify a shape on the current canvas which represents the motion path.
Two options are available which allow definition of a motion path using any of SVG's path data commands:
Note that SVG's path data commands can only contain values in local coordinate system, whereas ‘from’, ‘by’, ‘to’ and ‘values’ can specify coordinates in local coordinate system or using unit identifiers. See Units.
The various (x,y) points of the shape provide a supplemental
transformation matrix onto the CTM for the referenced object
which causes a translation along the x- and y-axes of the current
user coordinate system by the (x,y) values of the shape computed
over time. Thus, the referenced object is translated over time
by the offset of the motion path relative to the origin of the
current user coordinate system. The supplemental transformation is
applied on top of any transformations due to the target element's
‘transform
’ property or any animations on that attribute due
to ‘animateTransform’ elements on the target element.
The ‘additive’ and ‘accumulate’ attributes apply
to ‘animateMotion’ elements. Multiple ‘animateMotion’
elements all simultaneously referencing the same target element can
be additive with respect to each other; however, the transformations
which result from the ‘animateMotion’ elements are always
supplemental to any transformations due to the target element's
‘transform
’ property or any ‘animateTransform’
elements.
The default calculation mode (‘calcMode’) for ‘animateMotion’ is "paced". This will produce constant velocity motion along the specified path. Note that while animateMotion elements can be additive, it is important to observe that the addition of two or more "paced" (constant velocity) animations might not result in a combined motion animation with constant velocity.
When a path is combined with "discrete", "linear" or "spline" ‘calcMode’ settings, and if attribute ‘keyPoints’ is not provided, the number of values is defined to be the number of points defined by the path, unless there are "move to" commands within the path. A "move to" command within the path (i.e. other than at the beginning of the path description) A "move to" command does not count as an additional point when dividing up the duration, or when associating ‘keyTimes’, ‘keySplines’ and ‘keyPoints’ values. When a path is combined with a "paced" ‘calcMode’ setting, all "move to" commands are considered to have 0 length (i.e. they always happen instantaneously), and is not considered in computing the pacing.
For more flexibility in controlling the velocity along the motion path, the ‘keyPoints’ attribute provides the ability to specify the progress along the motion path for each of the ‘keyTimes’ specified values. If specified, ‘keyPoints’ causes ‘keyTimes’ to apply to the values in ‘keyPoints’ rather than the points specified in the ‘values’ attribute array or the points on the ‘path’ attribute.
The override rules for ‘animateMotion’ are as follows. Regarding the definition of the motion path, the ‘mpath’ element overrides the the ‘path’ attribute, which overrides ‘values’, which overrides ‘from’, ‘by’ and ‘to’. Regarding determining the points which correspond to the ‘keyTimes’ attributes, the ‘keyPoints’ attribute overrides ‘path’, which overrides ‘values’, which overrides ‘from’, ‘by’ and ‘to’.
At any time t within a motion path animation of duration dur, the computed coordinate (x,y) along the motion path is determined by finding the point (x,y) which is t/dur distance along the motion path using the user agent's distance along the path algorithm.
The following example demonstrates the supplemental transformation matrices that are computed during a motion path animation.
Example animMotion01 shows a triangle moving along a motion path.
<?xml version="1.0" standalone="no"?> <svg width="5cm" height="3cm" viewBox="0 0 500 300" xmlns="http://www.w3.org/2000/svg"> <desc>Example animMotion01 - demonstrate motion animation computations</desc> <rect x="1" y="1" width="498" height="298" fill="none" stroke="blue" stroke-width="2" /> <!-- Draw the outline of the motion path in blue, along with three small circles at the start, middle and end. --> <path id="path1" d="M100,250 C 100,50 400,50 400,250" fill="none" stroke="blue" stroke-width="7.06" /> <circle cx="100" cy="250" r="17.64" fill="blue" /> <circle cx="250" cy="100" r="17.64" fill="blue" /> <circle cx="400" cy="250" r="17.64" fill="blue" /> <!-- Here is a triangle which will be moved about the motion path. It is defined with an upright orientation with the base of the triangle centered horizontally just above the origin. --> <path d="M-25,-12.5 L25,-12.5 L 0,-87.5 z" fill="yellow" stroke="red" stroke-width="7.06" > <!-- Define the motion path animation --> <animateMotion dur="6s" repeatCount="indefinite" rotate="auto" > <mpath href="#path1"/> </animateMotion> </path> </svg>
At zero seconds |
At three seconds |
At six seconds |
View this example as SVG (SVG-enabled browsers only)
The following table shows the supplemental transformation matrices that are applied to achieve the effect of the motion path animation.
After 0s | After 3s | After 6s | |
---|---|---|---|
Supplemental transform due to movement along motion path | translate(100,250) | translate(250,100) | translate(400,250) |
Supplemental transform due to rotate="auto" | rotate(-90) | rotate(0) | rotate(90) |
For a list of elements that can be animated using the ‘animateMotion’ element, see Elements, attributes and properties that can be animated.
The ‘animateTransform’ element animates a transformation attribute on a target element, thereby allowing animations to control translation, scaling, rotation and/or skewing.
This section should talk about the ‘transform
’ property.
Attribute definitions:
Name | Value | Initial value | Animatable |
---|---|---|---|
type | translate | scale | rotate | skewX | skewY | translate | no |
Indicates the type of transformation which is to have its values change over time.
The ‘from’, ‘by’ and ‘to’ attributes take a value expressed using the same syntax that is available for the given transformation type:
(See The ‘transform’ property.)
The ‘values’ attribute for the ‘animateTransform’ element consists of a semicolon-separated list of values, where each individual value is expressed as described above for ‘from’, ‘by’ and ‘to’.
The animation effect for ‘animateTransform’ is post-multiplied to the underlying value for additive ‘animateTransform’ animations (see below) instead of added to the underlying value, due to the specific behavior of ‘animateTransform’.
From-to, from-by and by animations are defined in SMIL to be equivalent to a corresponding values animation. See the Animation function values section of SMIL Animation ([SMILANIM], section 3.2.2). However, to animations are a mixture of additive and non-additive behavior, as described in the How from, to and by attributes affect additive behavior section of SMIL Animation ([SMILANIM], section 3.3.6). To animations provide specific functionality to get a smooth change from the underlying value to the ‘to’ attribute value, which conflicts mathematically with the requirement for additive transform animations to be post-multiplied. As a consequence, in SVG 1.1 the behavior of to animations for ‘animateTransform’ is undefined. Authors are suggested to use from-to, from-by, by or values animations to achieve any desired transform animation.
If ‘calcMode’ has the value 'paced', then the "distance" for the transformation is calculated as further described in Paced animations and complex types.
When an animation is active, the effect of non-additive ‘animateTransform’ (i.e., additive="replace") is to replace the given attribute's value with the transformation defined by the ‘animateTransform’. The effect of additive (i.e., additive="sum") is to post-multiply the transformation matrix corresponding to the transformation defined by this ‘animateTransform’.
To illustrate:
<rect transform="skewX(30)"...> <animateTransform attributeName="transform" type="rotate" from="0" to="90" dur="5s" additive="replace" fill="freeze"/> <animateTransform attributeName="transform" type="scale" from="1" to="2" dur="5s" additive="replace" fill="freeze"/> </rect>
In the code snippet above, because the both animations have additive="replace", the first animation overrides the transformation on the rectangle itself and the second animation overrides the transformation from the first animation; therefore, at time 5 seconds, the visual result of the above two animations would be equivalent to the following static rectangle:
<rect transform="scale(2)" ... />
<rect transform="skewX(30)"...> <animateTransform attributeName="transform" type="rotate" from="0" to="90" dur="5s" additive="sum" fill="freeze"/> <animateTransform attributeName="transform" type="scale" from="1" to="2" dur="5s" additive="sum" fill="freeze"/> </rect>
In this code snippet, because the both animations have additive="sum", the first animation post-multiplies its transformation to any transformations on the rectangle itself and the second animation post-multiplies its transformation to any transformation from the first animation; therefore, at time 5 seconds, the visual result of the above two animations would be equivalent to the following static rectangle:
<rect transform="skewX(30) rotate(90) scale(2)" ... />
The zero value used when performing a by animation with type="scale" is indeed 0. Thus, performing the following animation causes the rectangle to be invisible at time 0s (since the animated transform list value is 'scale(0)'), and be scaled back to its original size at time 5s (since the animated transform list value is 'scale(1)'):
<rect width="100" height="100"> <animateTransform attributeName="transform" type="scale" by="1" dur="5s" fill="freeze"/> </rect>
When a transform animation has accumulate='sum', the accumulation that occurs for each completed repetition of the animation is computed on the values specified in the ‘animateTransform’ element's animation value attributes (i.e., ‘values’, ‘from’, ‘to’ and ‘by’) and not on the transformation matrix that these values represent.
For example, in the following code snippet, 3 is added to the scale value at the start of each repetition:
<rect width="100" height="100"> <animateTransform attributeName="transform" type="scale" from="2" to="3" repeatCount="3" dur="4s" fill="freeze"/> </rect>
The following graph and table shows the animated ‘transform
’ value on
the ‘rect’ over the course of the animation:
|
Transform item types that can have multiple values – 'translate', 'scale' and 'rotate' – are treated as vectors and accumulation is performed with vector addition. Optional values that are omitted are taken to have their usual implied value: 1 for the <sy> component of a 'scale' and 0 for the <tx> component of a 'translate' and the <cx cy> components of a 'rotate'.
For example, consider the following code snippet, which has a cumulative transform animation of type 'rotate':
<rect width="100" height="100"> <animateTransform attributeName="transform" type="rotate" from="0 30 40" to="10 30 40" repeatCount="2" dur="1s" fill="freeze"/> </rect>
At time 1 second, the animated value of ‘transform
’ on the ‘rect’
will jump from 'rotate(10 30 40)' to 'rotate(10 60 80)',
because the effect of the accumulation is to take the value at the end of the first repetition,
'10 30 40', and add to it the value at simple duration t = 0s, which
is '0 30 40'.
For a list of attributes and properties that can be animated using the ‘animateTransform’ element, see Elements, attributes and properties that can be animated.
The following lists all of the elements which can be animated by an ‘animateMotion’ element:
Each attribute or property within this specification indicates whether or not it can be animated by SVG's animation elements. Animatable attributes and properties are designated as follows:
Animatable: yes.
whereas attributes and properties that cannot be animated are designated:
Animatable: no.
Some properties are defined as being animatable but only for non-additive animations:
Animatable: yes (non-additive).
SVG has a number of different data types used for its various supported attributes and properties. For those attributes and properties that can be animated, the following table indicates which animation elements can be used to animate each of the basic data types. If a given attribute or property can take values of keywords (which are not additive) or numeric values (which are additive), then additive animations are possible if the subsequent animation uses a numeric value even if the base animation uses a keyword value; however, if the subsequent animation uses a keyword value, additive animation is not possible.
Data type | Additive? | ‘animate’ | ‘set’ | ‘animateTransform’ | Notes |
---|---|---|---|---|---|
<angle> | yes | yes | yes | no | |
<color> | yes | yes | yes | no | Only additive if each value can be converted to an RGB color. |
<frequency> | no | no | no | no | |
<integer> | yes | yes | yes | no | |
<length> | yes | yes | yes | no | |
<number> | yes | yes | yes | no | |
<paint> | yes | yes | yes | no | Only additive if each value can be converted to an RGB color. |
<percentage> | yes | yes | yes | no | |
<time> | no | no | no | no | |
URL | no | yes | yes | no | |
All other data types used in animatable attributes and properties | no | yes | yes | no |
Any deviation from the above table or other special note about the animation capabilities of a particular attribute or property is included in the section of the specification where the given attribute or property is defined.
Example dom01 shows a simple animation using the DOM.
<?xml version="1.0" standalone="no"?> <svg width="4cm" height="2cm" viewBox="0 0 400 200" xmlns="http://www.w3.org/2000/svg" onload="StartAnimation(evt)"> <script type="application/ecmascript"><![CDATA[ var timevalue = 0; var timer_increment = 50; var max_time = 5000; var text_element; function StartAnimation(evt) { text_element = evt.target.ownerDocument.getElementById("TextElement"); ShowAndGrowElement(); } function ShowAndGrowElement() { timevalue = timevalue + timer_increment; if (timevalue > max_time) return; // Scale the text string gradually until it is 20 times larger scalefactor = (timevalue * 20.) / max_time; text_element.setAttribute("transform", "scale(" + scalefactor + ")"); // Make the string more opaque opacityfactor = timevalue / max_time; text_element.setAttribute("opacity", opacityfactor); // Call ShowAndGrowElement again <timer_increment> milliseconds later. setTimeout("ShowAndGrowElement()", timer_increment) } window.ShowAndGrowElement = ShowAndGrowElement ]]></script> <rect x="1" y="1" width="398" height="198" fill="none" stroke="blue" stroke-width="2"/> <g transform="translate(50,150)" fill="red" font-size="7"> <text id="TextElement">SVG</text> </g> </svg>
At zero seconds |
At 2.5 seconds |
At five seconds |
View this example as SVG (SVG-enabled browsers only)
The above SVG file contains a single graphics element, a text string that says "SVG". The animation loops for 5 seconds. The text string starts out small and transparent and grows to be large and opaque. Here is an explanation of how this example works:
StartAnimation
.StartAnimation()
function is only called once to give a value to global
variable text_element
and to make the initial
call to ShowAndGrowElement()
.
ShowAndGrowElement()
is called every 50
milliseconds and resets the ‘transform
’ and
‘style’ attributes on the text element to new
values each time it is called. At the end of
ShowAndGrowElement
, the function tells the
ECMAScript engine to call itself again after 50 more
milliseconds.If scripts are modifying the same attributes or properties that are being animated by SVG's animation elements, the scripts modify the base value for the animation. If a base value is modified while an animation element is animating the corresponding attribute or property, the animations are required to adjust dynamically to the new base value.
If a script is modifying a property on the override style sheet at the same time that an animation element is animating that property, the result is implementation-dependent; thus, it is recommended that this be avoided.
Below are the DOM interfaces for the elements defined in this chapter. In addition, TimeEvent, which is from SMIL Animation, is included here for easy reference.
The TimeEvent interface, defined in SMIL Animation: Supported interfaces, provides specific contextual information associated with Time events.
The different types of events that can occur are:
interface TimeEvent : Event { readonly attribute AbstractView view; readonly attribute long detail; void initTimeEvent(DOMString typeArg, AbstractView viewArg, long detailArg); };
document.createEvent()
. This
method may only be called before the TimeEvent has been dispatched
via the dispatchEvent method, though it may be called multiple times
during that phase if necessary. If called multiple times, the final
invocation takes precedence.The SVGAnimationElement interface is the base interface for all of the animation element interfaces: SVGAnimateElement, SVGSetElement, SVGAnimateMotionElement and SVGAnimateTransformElement.
Unlike other SVG DOM interfaces, the SVG DOM does not specify
convenience DOM properties corresponding to the various language
attributes on SVG's animation elements. Specification of these
convenience properties in a way that will be compatible with future
versions of SMIL Animation is expected in a future version of SVG. The
current method for accessing and modifying the attributes on the
animation elements is to use the standard getAttribute
,
setAttribute
, getAttributeNS
and
setAttributeNS
defined in
DOM4
[DOM4].
SMIL Animation supports several methods for controlling the behavior of
animation: beginElement()
, beginElementAt()
,
endElement()
and endElementAt()
. These methods
are used to begin and end the active duration of an element. Authors can
(but are not required to) declare the timing to respond to the DOM using
the following syntax:
<animate begin="indefinite" end="indefinite" .../>
If a DOM method call is made to begin or end the element (using
beginElement()
, beginElementAt()
,
endElement()
or endElementAt()
), each method call
creates a single instance time (in the appropriate instance times list).
These times are then interpreted as part of the semantics of lists of
times, as described in
Evaluation of begin and end time lists.
beginElement()
or
endElement()
call is the current presentation time at the
time of the DOM method call.beginElementAt()
or
endElementAt()
call is the current presentation time at the
time of the DOM method call, plus or minus the specified offset.beginElement()
is subject to the ‘restart’
attribute in the same manner that event-based begin timing is. Refer
also to SMIL Animation: Restarting animation
([SMILANIM], section 3.3.7).interface SVGAnimationElement : SVGElement { readonly attribute SVGElement? targetElement; attribute EventHandler onbegin; attribute EventHandler onend; attribute EventHandler onrepeat; float getStartTime(); float getCurrentTime(); float getSimpleDuration(); void beginElement(); void beginElementAt(float offset); void endElement(); void endElementAt(float offset); }; SVGAnimationElement implements SVGTests;
beginElementAt(0)
.endElementAt(0)
.The SVGAnimateElement interface corresponds to the ‘animate’ element.
Object-oriented access to the attributes of the ‘animate’ element via the SVG DOM is not available.
interface SVGAnimateElement : SVGAnimationElement { };
The SVGSetElement interface corresponds to the ‘set’ element.
Object-oriented access to the attributes of the ‘set’ element via the SVG DOM is not available.
interface SVGSetElement : SVGAnimationElement { };
The SVGAnimateMotionElement interface corresponds to the ‘animateMotion’ element.
Object-oriented access to the attributes of the ‘animateMotion’ element via the SVG DOM is not available.
interface SVGAnimateMotionElement : SVGAnimationElement { };
The SVGMPathElement interface corresponds to the ‘mpath’ element.
interface SVGMPathElement : SVGElement { }; SVGMPathElement implements SVGURIReference;
The SVGAnimateTransformElement interface corresponds to the ‘animateTransform’ element.
Object-oriented access to the attributes of the ‘animateTransform’ element via the SVG DOM is not available.
interface SVGAnimateTransformElement : SVGAnimationElement { };
This appendix is normative.
SVG 2 Requirement: | Improve the DOM. |
---|---|
Resolution: | We will generally improve the SVG DOM for SVG 2. |
Purpose: | Help authors use the SVG DOM by making it less Java-oriented. |
Owner: | Cameron (ACTION-3273) |
Note: | See SVG 2 DOM Wiki page. |
SVG 2 Requirement: | Improve the SVG path DOM APIs. |
---|---|
Resolution: | We will improve the SVG path DOM APIs in SVG 2. |
Purpose: | Clean up SVGPathSegList interface, and possibly share an API with Canvas. |
Owner: | Cameron (no action) |
The SVG DOM is defined in terms of Web IDL interfaces. All IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [WEBIDL]
The SVG DOM builds upon a number of DOM specifications. In particular:
All SVG DOM objects that directly correspond to an attribute, e.g. the SVGAnimatedLength ry in an SVGRectElement, are live. This means that any changes made to the attribute are immediately reflected in the corresponding SVG DOM object.
The SVG DOM allows attributes to be accessed even though they haven't been specified explicitly in the document markup. When this happens an appropriate object is created, initialized and returned. This newly constructed object does not affect rendering until it is modified for the first time. Modifications made to the corresponding attribute are immediately reflected in the object.
For example, if rectElement.x.baseVal
is accessed
and the ‘x’ attribute was not specified in the document, the
returned SVG DOM object would represent the value 0 user units.
Needs updating for x now being a property.
For cases where an attribute has a default value the returned SVG DOM object that must reflect that value, and for all other cases the object is initialized as described below. If a particular SVG DOM interface is not listed below that means that the object initialization shall be done using the values for the objects that the interface contains, e.g DOMString in the case of SVGAnimatedString.
Every Element object that corresponds to an SVG element (that is, an element with namespace URI "http://www.w3.org/2000/svg" and a local name that is one of the elements defined in this specification) must also implement the DOM interface identified in element definition. For example, in The ‘rect’ element, the SVGRectElement interface is identified. This means that every Element object whose namespace URI is "http://www.w3.org/2000/svg" and whose local name is "rect" must also implement SVGRectElement.
The SVG DOM follows similar naming conventions to the Document Object Model HTML ([DOM1], chapter 2).
All names are defined as one or more English words concatenated together to form a single string. Property or method names start with the initial keyword in lowercase, and each subsequent word starts with a capital letter. For example, a property that returns document meta information such as the date the file was created might be named "fileDateCreated". In the ECMAScript binding, properties are exposed as properties of a given object.
For attributes with the CDATA data type, the case of the return value is that given in the source document.
The SVG DOM supports select all interfaces defined in, and the following event types from, DOM Level 3 Events [DOM3EVENTS]:
While event listeners can be registered using an
addEventListener
call on any element in the DOM,
the use of event attributes
on elements where those attributes are disallowed will not result in their
being invoked if the relevant event is dispatched to the element.
For example, if the ‘onclick’ attribute were specified on
a ‘title’ element, its contents would never be run in
response to a click event:
<svg xmlns="http://www.w3.org/2000/svg"> <title onclick="alert('Hello')">Invalid event attribute</title> <script> // Find the 'title' element. var title = document.getElementsByTagNameNS("http://www.w3.org/2000/svg", "title")[0]; // Create and initialize a 'click' event. var event = document.createEvent("MouseEvent"); event.initMouseEvent("click", true, false, this, 1, 0, 0, 0, 0, false, false, false, false, 0, null); // Dispatch the event to the 'title' element. Since onclick="" is not // allowed on 'title', the alert will not show. title.dispatchEvent(event); </script> </svg>
See the Attribute Index for details on which elements a given event attribute is allowed to be specified on.
Implementors may view the setting of event attributes as the
creation and registration of an EventListener on the
EventTarget. Such event listeners are invoked only for
the "bubbling" and "at target" phases, as if false were specified
for the useCapture
argument to addEventListener
.
This EventListener behaves in the same manner as any other
which may be registered on the EventTarget.
If the attribute representing the event listener is changed, this may be viewed as the removal of the previously registered EventListener and the registration of a new one. Futhermore, no specification is made as to the order in which event attributes will receive the event with regards to the other EventListeners on the EventTarget.
In ECMAScript, one way to establish an event listener is to
define a function and pass that function to the addEventListener
method:
function myAction1(evt) { // process the event } // ... later ... myElement.addEventListener("click", myAction1, false)
In ECMAScript, the character data content of an event attribute becomes the definition of the ECMAScript function which gets invoked in response to the event. As with all registered ECMAScript event listener functions, this function receives an Event object as a parameter, and the name of the Event object is evt. For example, it is possible to write:
<rect onclick="MyClickHandler(evt)" .../>
which will pass the Event object evt into
function MyClickHandler
.
The section describes the facilities from DOM Level 2 CSS ([DOM2STYLE], chapter 2) that are part of the SVG DOM.
For visual media ([CSS21], section 7.3.1), user agents must support all of the required interfaces defined in DOM Level 2 CSS. All of the interfaces that are optional for DOM Level 2 CSS are also optional for user agents implementing the SVG DOM.
If a script sets a DOM attribute to an invalid value (e.g., a negative number for an attribute that requires a non-negative number or an out-of-range value for an enumeration), unless this specification indicates otherwise, no exception shall be raised on setting, but the given document fragment shall become technically in error as described in Error processing.
This appendix is normative.
This appendix contains the complete Web IDL for the SVG Document Object Model definitions.
interface SVGElement : Element { readonly attribute SVGAnimatedString className; readonly attribute SVGSVGElement? ownerSVGElement; readonly attribute SVGElement? viewportElement; attribute long tabIndex; void focus(); void blur(); }; SVGElement implements GlobalEventHandlers; interface SVGAnimatedBoolean { attribute boolean baseVal; readonly attribute boolean animVal; }; interface SVGAnimatedString { attribute DOMString baseVal; readonly attribute DOMString animVal; }; interface SVGStringList { readonly attribute unsigned long length; readonly attribute unsigned long numberOfItems; void clear(); DOMString initialize(DOMString newItem); getter DOMString getItem(unsigned long index); DOMString insertItemBefore(DOMString newItem, unsigned long index); DOMString replaceItem(DOMString newItem, unsigned long index); DOMString removeItem(unsigned long index); DOMString appendItem(DOMString newItem); setter void (unsigned long index, DOMString newItem); }; interface SVGAnimatedEnumeration { attribute unsigned short baseVal; readonly attribute unsigned short animVal; }; interface SVGAnimatedInteger { attribute long baseVal; readonly attribute long animVal; }; interface SVGNumber { attribute float value; }; interface SVGAnimatedNumber { attribute float baseVal; readonly attribute float animVal; }; interface SVGNumberList { readonly attribute unsigned long length; readonly attribute unsigned long numberOfItems; void clear(); SVGNumber initialize(SVGNumber newItem); getter SVGNumber getItem(unsigned long index); SVGNumber insertItemBefore(SVGNumber newItem, unsigned long index); SVGNumber replaceItem(SVGNumber newItem, unsigned long index); SVGNumber removeItem(unsigned long index); SVGNumber appendItem(SVGNumber newItem); setter void (unsigned long index, SVGNumber newItem); }; interface SVGAnimatedNumberList { readonly attribute SVGNumberList baseVal; readonly attribute SVGNumberList animVal; }; interface SVGLength { // Length Unit Types const unsigned short SVG_LENGTHTYPE_UNKNOWN = 0; const unsigned short SVG_LENGTHTYPE_NUMBER = 1; const unsigned short SVG_LENGTHTYPE_PERCENTAGE = 2; const unsigned short SVG_LENGTHTYPE_EMS = 3; const unsigned short SVG_LENGTHTYPE_EXS = 4; const unsigned short SVG_LENGTHTYPE_PX = 5; const unsigned short SVG_LENGTHTYPE_CM = 6; const unsigned short SVG_LENGTHTYPE_MM = 7; const unsigned short SVG_LENGTHTYPE_IN = 8; const unsigned short SVG_LENGTHTYPE_PT = 9; const unsigned short SVG_LENGTHTYPE_PC = 10; readonly attribute unsigned short unitType; attribute float value; attribute float valueInSpecifiedUnits; attribute DOMString valueAsString; void newValueSpecifiedUnits(unsigned short unitType, float valueInSpecifiedUnits); void convertToSpecifiedUnits(unsigned short unitType); }; interface SVGAnimatedLength { readonly attribute SVGLength baseVal; readonly attribute SVGLength animVal; }; interface SVGLengthList { readonly attribute unsigned long length; readonly attribute unsigned long numberOfItems; void clear(); SVGLength initialize(SVGLength newItem); getter SVGLength getItem(unsigned long index); SVGLength insertItemBefore(SVGLength newItem, unsigned long index); SVGLength replaceItem(SVGLength newItem, unsigned long index); SVGLength removeItem(unsigned long index); SVGLength appendItem(SVGLength newItem); setter void (unsigned long index, SVGLength newItem); }; interface SVGAnimatedLengthList { readonly attribute SVGLengthList baseVal; readonly attribute SVGLengthList animVal; }; interface SVGAngle { // Angle Unit Types const unsigned short SVG_ANGLETYPE_UNKNOWN = 0; const unsigned short SVG_ANGLETYPE_UNSPECIFIED = 1; const unsigned short SVG_ANGLETYPE_DEG = 2; const unsigned short SVG_ANGLETYPE_RAD = 3; const unsigned short SVG_ANGLETYPE_GRAD = 4; readonly attribute unsigned short unitType; attribute float value; attribute float valueInSpecifiedUnits; attribute DOMString valueAsString; void newValueSpecifiedUnits(unsigned short unitType, float valueInSpecifiedUnits); void convertToSpecifiedUnits(unsigned short unitType); }; interface SVGAnimatedAngle { readonly attribute SVGAngle baseVal; readonly attribute SVGAngle animVal; }; interface SVGAnimatedRect { readonly attribute DOMRectReadOnly baseVal; readonly attribute DOMRectReadOnly animVal; }; [NoInterfaceObject] interface SVGUnitTypes { // Unit Types const unsigned short SVG_UNIT_TYPE_UNKNOWN = 0; const unsigned short SVG_UNIT_TYPE_USERSPACEONUSE = 1; const unsigned short SVG_UNIT_TYPE_OBJECTBOUNDINGBOX = 2; }; dictionary SVGBoundingBoxOptions { boolean fill = true; boolean stroke = false; boolean markers = false; boolean clipped = false; }; interface SVGGraphicsElement : SVGElement { readonly attribute SVGAnimatedTransformList transform; DOMRect getBBox(optional SVGBoundingBoxOptions options); DOMMatrix? getCTM(); DOMMatrix? getScreenCTM(); DOMMatrix getTransformToElement(SVGGraphicsElement element); }; SVGGraphicsElement implements SVGTests; interface SVGGeometryElement : SVGGraphicsElement { boolean isPointInFill(DOMPoint point); boolean isPointInStroke(DOMPoint point); }; [NoInterfaceObject] interface SVGTests { readonly attribute SVGStringList requiredExtensions; readonly attribute SVGStringList systemLanguage; }; [NoInterfaceObject] interface SVGFitToViewBox { readonly attribute SVGAnimatedRect viewBox; readonly attribute SVGAnimatedPreserveAspectRatio preserveAspectRatio; }; [NoInterfaceObject] interface SVGZoomAndPan { // Zoom and Pan Types const unsigned short SVG_ZOOMANDPAN_UNKNOWN = 0; const unsigned short SVG_ZOOMANDPAN_DISABLE = 1; const unsigned short SVG_ZOOMANDPAN_MAGNIFY = 2; attribute unsigned short zoomAndPan; }; [NoInterfaceObject] interface SVGURIReference { readonly attribute SVGAnimatedString href; }; partial interface Document { readonly attribute SVGSVGElement rootElement; }; // must only be implemented in certain implementations partial interface Document { readonly attribute DOMString title; readonly attribute DOMString referrer; readonly attribute DOMString domain; readonly attribute Element? activeElement; }; interface SVGSVGElement : SVGGraphicsElement { readonly attribute SVGAnimatedLength x; readonly attribute SVGAnimatedLength y; readonly attribute SVGAnimatedLength width; readonly attribute SVGAnimatedLength height; readonly attribute DOMRectReadOnly viewport; attribute float currentScale; readonly attribute DOMPointReadOnly currentTranslate; unsigned long suspendRedraw(unsigned long maxWaitMilliseconds); void unsuspendRedraw(unsigned long suspendHandleID); void unsuspendRedrawAll(); void forceRedraw(); void pauseAnimations(); void unpauseAnimations(); boolean animationsPaused(); float getCurrentTime(); void setCurrentTime(float seconds); NodeList getIntersectionList(DOMRectReadOnly rect, SVGElement? referenceElement); NodeList getEnclosureList(DOMRectReadOnly rect, SVGElement? referenceElement); boolean checkIntersection(SVGElement element, DOMRectReadOnly rect); boolean checkEnclosure(SVGElement element, DOMRectReadOnly rect); void deselectAll(); SVGNumber createSVGNumber(); SVGLength createSVGLength(); SVGAngle createSVGAngle(); DOMPoint createSVGPoint(); DOMMatrix createSVGMatrix(); DOMRect createSVGRect(); SVGTransform createSVGTransform(); SVGTransform createSVGTransformFromMatrix(DOMMatrixReadOnly matrix); }; SVGSVGElement implements SVGFitToViewBox; SVGSVGElement implements SVGZoomAndPan; SVGSVGElement implements WindowEventHandlers; interface SVGGElement : SVGGraphicsElement { }; interface SVGDefsElement : SVGGraphicsElement { }; interface SVGDescElement : SVGElement { }; interface SVGMetadataElement : SVGElement { }; interface SVGTitleElement : SVGElement { }; interface SVGSymbolElement : SVGElement { }; SVGSymbolElement implements SVGFitToViewBox; interface SVGUseElement : SVGGraphicsElement { readonly attribute SVGAnimatedLength x; readonly attribute SVGAnimatedLength y; readonly attribute SVGAnimatedLength width; readonly attribute SVGAnimatedLength height; }; SVGUseElement implements SVGURIReference; interface SVGSwitchElement : SVGGraphicsElement { }; [NoInterfaceObject] interface GetSVGDocument { SVGDocument getSVGDocument(); }; interface SVGStyleElement : SVGElement { attribute DOMString type; attribute DOMString media; attribute DOMString title; }; SVGStyleElement implements LinkStyle; interface SVGTransform { // Transform Types const unsigned short SVG_TRANSFORM_UNKNOWN = 0; const unsigned short SVG_TRANSFORM_MATRIX = 1; const unsigned short SVG_TRANSFORM_TRANSLATE = 2; const unsigned short SVG_TRANSFORM_SCALE = 3; const unsigned short SVG_TRANSFORM_ROTATE = 4; const unsigned short SVG_TRANSFORM_SKEWX = 5; const unsigned short SVG_TRANSFORM_SKEWY = 6; readonly attribute unsigned short type; readonly attribute DOMMatrixReadOnly matrix; readonly attribute float angle; void setMatrix(DOMMatrixReadOnly matrix); void setTranslate(float tx, float ty); void setScale(float sx, float sy); void setRotate(float angle, float cx, float cy); void setSkewX(float angle); void setSkewY(float angle); }; interface SVGTransformList { readonly attribute unsigned long length; readonly attribute unsigned long numberOfItems; void clear(); SVGTransform initialize(SVGTransform newItem); getter SVGTransform getItem(unsigned long index); SVGTransform insertItemBefore(SVGTransform newItem, unsigned long index); SVGTransform replaceItem(SVGTransform newItem, unsigned long index); SVGTransform removeItem(unsigned long index); SVGTransform appendItem(SVGTransform newItem); SVGTransform createSVGTransformFromMatrix(DOMMatrixReadOnly matrix); SVGTransform? consolidate(); setter void (unsigned long index, SVGTransform newItem); }; interface SVGAnimatedTransformList { readonly attribute SVGTransformList baseVal; readonly attribute SVGTransformList animVal; }; interface SVGPreserveAspectRatio { // Alignment Types const unsigned short SVG_PRESERVEASPECTRATIO_UNKNOWN = 0; const unsigned short SVG_PRESERVEASPECTRATIO_NONE = 1; const unsigned short SVG_PRESERVEASPECTRATIO_XMINYMIN = 2; const unsigned short SVG_PRESERVEASPECTRATIO_XMIDYMIN = 3; const unsigned short SVG_PRESERVEASPECTRATIO_XMAXYMIN = 4; const unsigned short SVG_PRESERVEASPECTRATIO_XMINYMID = 5; const unsigned short SVG_PRESERVEASPECTRATIO_XMIDYMID = 6; const unsigned short SVG_PRESERVEASPECTRATIO_XMAXYMID = 7; const unsigned short SVG_PRESERVEASPECTRATIO_XMINYMAX = 8; const unsigned short SVG_PRESERVEASPECTRATIO_XMIDYMAX = 9; const unsigned short SVG_PRESERVEASPECTRATIO_XMAXYMAX = 10; // Meet-or-slice Types const unsigned short SVG_MEETORSLICE_UNKNOWN = 0; const unsigned short SVG_MEETORSLICE_MEET = 1; const unsigned short SVG_MEETORSLICE_SLICE = 2; attribute unsigned short align; attribute unsigned short meetOrSlice; }; interface SVGAnimatedPreserveAspectRatio { readonly attribute SVGPreserveAspectRatio baseVal; readonly attribute SVGPreserveAspectRatio animVal; }; interface SVGPathElement : SVGGeometryElement { readonly attribute SVGAnimatedNumber pathLength; float getTotalLength(); DOMPoint getPointAtLength(float distance); }; interface SVGRectElement : SVGGeometryElement { readonly attribute SVGAnimatedLength x; readonly attribute SVGAnimatedLength y; readonly attribute SVGAnimatedLength width; readonly attribute SVGAnimatedLength height; readonly attribute SVGAnimatedLength rx; readonly attribute SVGAnimatedLength ry; }; interface SVGCircleElement : SVGGeometryElement { readonly attribute SVGAnimatedLength cx; readonly attribute SVGAnimatedLength cy; readonly attribute SVGAnimatedLength r; }; interface SVGEllipseElement : SVGGeometryElement { readonly attribute SVGAnimatedLength cx; readonly attribute SVGAnimatedLength cy; readonly attribute SVGAnimatedLength rx; readonly attribute SVGAnimatedLength ry; }; interface SVGLineElement : SVGGeometryElement { readonly attribute SVGAnimatedLength x1; readonly attribute SVGAnimatedLength y1; readonly attribute SVGAnimatedLength x2; readonly attribute SVGAnimatedLength y2; }; [NoInterfaceObject] interface SVGAnimatedPoints { readonly attribute SVGPointList points; readonly attribute SVGPointList animatedPoints; }; interface SVGPointList { readonly attribute unsigned long length; readonly attribute unsigned long numberOfItems; void clear(); DOMPoint initialize(DOMPoint newItem); getter DOMPoint getItem(unsigned long index); DOMPoint insertItemBefore(DOMPoint newItem, unsigned long index); DOMPoint replaceItem(DOMPoint newItem, unsigned long index); DOMPoint removeItem(unsigned long index); DOMPoint appendItem(DOMPoint newItem); setter void (unsigned long index, DOMPoint newItem); }; interface SVGPolylineElement : SVGGeometryElement { }; SVGPolylineElement implements SVGAnimatedPoints; interface SVGPolygonElement : SVGGeometryElement { }; SVGPolygonElement implements SVGAnimatedPoints; interface SVGTextContentElement : SVGGraphicsElement { // lengthAdjust Types const unsigned short LENGTHADJUST_UNKNOWN = 0; const unsigned short LENGTHADJUST_SPACING = 1; const unsigned short LENGTHADJUST_SPACINGANDGLYPHS = 2; readonly attribute SVGAnimatedLength textLength; readonly attribute SVGAnimatedEnumeration lengthAdjust; long getNumberOfChars(); float getComputedTextLength(); float getSubStringLength(unsigned long charnum, unsigned long nchars); DOMPoint getStartPositionOfChar(unsigned long charnum); DOMPoint getEndPositionOfChar(unsigned long charnum); DOMRect getExtentOfChar(unsigned long charnum); float getRotationOfChar(unsigned long charnum); long getCharNumAtPosition(DOMPoint point); void selectSubString(unsigned long charnum, unsigned long nchars); }; interface SVGTextPositioningElement : SVGTextContentElement { readonly attribute SVGAnimatedLengthList x; readonly attribute SVGAnimatedLengthList y; readonly attribute SVGAnimatedLengthList dx; readonly attribute SVGAnimatedLengthList dy; readonly attribute SVGAnimatedNumberList rotate; }; interface SVGTextElement : SVGTextPositioningElement { }; interface SVGTSpanElement : SVGTextPositioningElement { }; interface SVGTextPathElement : SVGTextContentElement { // textPath Method Types const unsigned short TEXTPATH_METHODTYPE_UNKNOWN = 0; const unsigned short TEXTPATH_METHODTYPE_ALIGN = 1; const unsigned short TEXTPATH_METHODTYPE_STRETCH = 2; // textPath Spacing Types const unsigned short TEXTPATH_SPACINGTYPE_UNKNOWN = 0; const unsigned short TEXTPATH_SPACINGTYPE_AUTO = 1; const unsigned short TEXTPATH_SPACINGTYPE_EXACT = 2; readonly attribute SVGAnimatedLength startOffset; readonly attribute SVGAnimatedEnumeration method; readonly attribute SVGAnimatedEnumeration spacing; }; SVGTextPathElement implements SVGURIReference; interface SVGImageElement : SVGGraphicsElement { readonly attribute SVGAnimatedLength x; readonly attribute SVGAnimatedLength y; readonly attribute SVGAnimatedLength width; readonly attribute SVGAnimatedLength height; readonly attribute SVGAnimatedPreserveAspectRatio preserveAspectRatio; attribute DOMString crossOrigin; }; SVGImageElement implements SVGURIReference; interface SVGVideoElement : SVGGraphicsElement { readonly attribute SVGAnimatedLength x; readonly attribute SVGAnimatedLength y; readonly attribute SVGAnimatedLength width; readonly attribute SVGAnimatedLength height; readonly attribute SVGAnimatedPreserveAspectRatio preserveAspectRatio; }; SVGVideoElement implements HTMLVideoElement; interface SVGAudioElement : SVGGraphicsElement { readonly attribute SVGAnimatedLength x; readonly attribute SVGAnimatedLength y; }; SVGAudioElement implements HTMLAudioElement; interface SVGIframeElement : SVGGraphicsElement { readonly attribute SVGAnimatedLength x; readonly attribute SVGAnimatedLength y; readonly attribute SVGAnimatedLength width; readonly attribute SVGAnimatedLength height; readonly attribute SVGAnimatedPreserveAspectRatio preserveAspectRatio; readonly attribute SVGAnimatedLength frameWidth; readonly attribute SVGAnimatedLength frameHeight; }; SVGIframeElement implements HTMLIframeElement; interface SVGCanvasElement : SVGGraphicsElement { readonly attribute SVGAnimatedLength x; readonly attribute SVGAnimatedLength y; readonly attribute SVGAnimatedLength width; readonly attribute SVGAnimatedLength height; readonly attribute SVGAnimatedPreserveAspectRatio preserveAspectRatio; readonly attribute SVGAnimatedLength canvasWidth; readonly attribute SVGAnimatedLength canvasHeight; }; SVGCanvasElement implements HTMLCanvasElement; interface SVGForeignObjectElement : SVGGraphicsElement { readonly attribute SVGAnimatedLength x; readonly attribute SVGAnimatedLength y; readonly attribute SVGAnimatedLength width; readonly attribute SVGAnimatedLength height; }; interface SVGSourceElement : SVGElement { }; SVGSourceElement implements HTMLSourceElement; interface SVGTrackElement : SVGElement { }; SVGTrackElement implements HTMLTrackElement; interface SVGMarkerElement : SVGElement { // Marker Unit Types const unsigned short SVG_MARKERUNITS_UNKNOWN = 0; const unsigned short SVG_MARKERUNITS_USERSPACEONUSE = 1; const unsigned short SVG_MARKERUNITS_STROKEWIDTH = 2; // Marker Orientation Types const unsigned short SVG_MARKER_ORIENT_UNKNOWN = 0; const unsigned short SVG_MARKER_ORIENT_AUTO = 1; const unsigned short SVG_MARKER_ORIENT_ANGLE = 2; readonly attribute SVGAnimatedLength refX; readonly attribute SVGAnimatedLength refY; readonly attribute SVGAnimatedEnumeration markerUnits; readonly attribute SVGAnimatedLength markerWidth; readonly attribute SVGAnimatedLength markerHeight; readonly attribute SVGAnimatedEnumeration orientType; readonly attribute SVGAnimatedAngle orientAngle; attribute DOMString orient; void setOrientToAuto(); void setOrientToAngle(SVGAngle angle); }; SVGMarkerElement implements SVGFitToViewBox; interface SVGGradientElement : SVGElement { // Spread Method Types const unsigned short SVG_SPREADMETHOD_UNKNOWN = 0; const unsigned short SVG_SPREADMETHOD_PAD = 1; const unsigned short SVG_SPREADMETHOD_REFLECT = 2; const unsigned short SVG_SPREADMETHOD_REPEAT = 3; readonly attribute SVGAnimatedEnumeration gradientUnits; readonly attribute SVGAnimatedTransformList gradientTransform; readonly attribute SVGAnimatedEnumeration spreadMethod; }; SVGGradientElement implements SVGURIReference; SVGGradientElement implements SVGUnitTypes; interface SVGLinearGradientElement : SVGGradientElement { readonly attribute SVGAnimatedLength x1; readonly attribute SVGAnimatedLength y1; readonly attribute SVGAnimatedLength x2; readonly attribute SVGAnimatedLength y2; }; interface SVGRadialGradientElement : SVGGradientElement { readonly attribute SVGAnimatedLength cx; readonly attribute SVGAnimatedLength cy; readonly attribute SVGAnimatedLength r; readonly attribute SVGAnimatedLength fx; readonly attribute SVGAnimatedLength fy; readonly attribute SVGAnimatedLength fr; }; interface SVGMeshElement : SVGGradientElement { readonly attribute SVGAnimatedLength x; readonly attribute SVGAnimatedLength y; }; interface SVGMeshrowElement : SVGElement { }; interface SVGMeshpatchElement : SVGElement { }; interface SVGStopElement : SVGElement { readonly attribute SVGAnimatedNumber offset; }; interface SVGPatternElement : SVGElement { readonly attribute SVGAnimatedEnumeration patternUnits; readonly attribute SVGAnimatedEnumeration patternContentUnits; readonly attribute SVGAnimatedTransformList patternTransform; readonly attribute SVGAnimatedLength x; readonly attribute SVGAnimatedLength y; readonly attribute SVGAnimatedLength width; readonly attribute SVGAnimatedLength height; }; SVGPatternElement implements SVGFitToViewBox; SVGPatternElement implements SVGURIReference; SVGPatternElement implements SVGUnitTypes; interface SVGCursorElement : SVGElement { readonly attribute SVGAnimatedLength x; readonly attribute SVGAnimatedLength y; }; SVGCursorElement implements SVGURIReference; interface SVGScriptElement : SVGElement { attribute DOMString type; attribute DOMString crossOrigin; }; SVGScriptElement implements SVGURIReference; interface SVGZoomEvent : UIEvent { readonly attribute DOMRectReadOnly zoomRectScreen; readonly attribute float previousScale; readonly attribute DOMPointReadOnly previousTranslate; readonly attribute float newScale; readonly attribute DOMPointReadOnly newTranslate; }; interface SVGAElement : SVGGraphicsElement { readonly attribute SVGAnimatedString target; }; SVGAElement implements SVGURIReference; interface SVGViewElement : SVGElement { readonly attribute SVGStringList viewTarget; }; SVGViewElement implements SVGFitToViewBox; SVGViewElement implements SVGZoomAndPan; interface TimeEvent : Event { readonly attribute AbstractView view; readonly attribute long detail; void initTimeEvent(DOMString typeArg, AbstractView viewArg, long detailArg); }; interface SVGAnimationElement : SVGElement { readonly attribute SVGElement? targetElement; attribute EventHandler onbegin; attribute EventHandler onend; attribute EventHandler onrepeat; float getStartTime(); float getCurrentTime(); float getSimpleDuration(); void beginElement(); void beginElementAt(float offset); void endElement(); void endElementAt(float offset); }; SVGAnimationElement implements SVGTests; interface SVGAnimateElement : SVGAnimationElement { }; interface SVGSetElement : SVGAnimationElement { }; interface SVGAnimateMotionElement : SVGAnimationElement { }; interface SVGMPathElement : SVGElement { }; SVGMPathElement implements SVGURIReference; interface SVGAnimateTransformElement : SVGAnimationElement { };
This appendix is normative.
The following are notes about implementation requirements corresponding to various features in the SVG language.
There are various scenarios where an SVG document fragment is technically in error:
A document can go in and out of error over time. For example, document changes from the SVG DOM or from animation can cause a document to become in error and a further change can cause the document to become correct again.
The following error processing shall occur when a document is in error:
Because of situations where a block of scripting changes might cause a given SVG document fragment to go into and out of error, error processing shall occur only at times when document presentation (e.g., rendering to the display device) is updated.
Some numeric attribute and property values have restricted ranges, such as color component values. When out-of-range values are provided, the user agent shall defer any error checking until after presentation time, as composited actions might produce intermediate values which are out-of-range but final values which are within range.
Color values are not in error if they are out-of-range, even if final computations produce an out-of-range color value at presentation time. It is recommended that user agents clamp color values to the nearest color value (possibly determined by simple clipping) which the system can process as late as possible (e.g., presentation time), although it is acceptable for user agents to clamp color values as early as parse time. Thus, implementation dependencies might preclude consistent behavior across different systems when out-of-range color values are used.
Opacity values out-of-range are not in error and should be clamped to the range 0 to 1 at the time which opacity values have to be processed (e.g., at presentation time or when it is necessary to perform intermediate filter effect calculations).
An elliptical arc is a particular path command. As such, it is described by the following parameters in order:
(x1, y1) are the absolute coordinates of the current point on the path, obtained from the last two parameters of the previous path command.
rx and ry are the radii of the ellipse (also known as its semi-major and semi-minor axes).
φ is the angle from the x-axis of the current coordinate system to the x-axis of the ellipse.
fA is the large arc flag, and is 0 if an arc spanning less than or equal to 180 degrees is chosen, or 1 if an arc spanning greater than 180 degrees is chosen.
fS is the sweep flag, and is 0 if the line joining center to arc sweeps through decreasing angles, or 1 if it sweeps through increasing angles.
(x2, y2) are the absolute coordinates of the final point of the arc.
This parameterization of elliptical arcs will be referred to as endpoint parameterization. One of the advantages of endpoint parameterization is that it permits a consistent path syntax in which all path commands end in the coordinates of the new "current point". The following notes give rules and formulas to help implementers deal with endpoint parameterization.
Arbitrary numerical values are permitted for all elliptical arc parameters, but where these values are invalid or out-of-range, an implementation must make sense of them as follows:
If the endpoints (x1, y1) and (x2, y2) are identical, then this is equivalent to omitting the elliptical arc segment entirely.
If rx = 0 or ry = 0 then this arc is treated as a straight line segment (a "lineto") joining the endpoints.
If rx or ry have negative signs, these are dropped; the absolute value is used instead.
If rx, ry and φ are such that there is no solution (basically, the ellipse is not big enough to reach from (x1, y1) to (x2, y2)) then the ellipse is scaled up uniformly until there is exactly one solution (until the ellipse is just big enough).
φ is taken mod 360 degrees.
Any nonzero value for either of the flags fA or fS is taken to mean the value 1.
This forgiving yet consistent treatment of out-of-range values ensures that:
An arbitrary point (x, y) on the elliptical arc can be described by the 2-dimensional matrix equation:
(F.6.3.1)x = rx*cos(θ)*cos(φ) - ry*sin(θ)*sin(φ) + cx y = rx*cos(θ)*sin(φ) + ry*sin(θ)*cos(φ) + cy
(cx, cy) are the coordinates of the center of the ellipse.
rx and ry are the radii of the ellipse (also known as its semi-major and semi-minor axes).
θ is the angle from the x-axis of the current coordinate system to the x-axis of the ellipse.
θ ranges from:
If one thinks of an ellipse as a circle that has been stretched and then rotated, then θ1, θ2 and Δθ are the start angle, end angle and sweep angle, respectively of the arc prior to the stretch and rotate operations. This leads to an alternate parameterization which is common among graphics APIs, which will be referred to as center parameterization. In the next sections, formulas are given for mapping in both directions between center parameterization and endpoint parameterization.
Given the following variables:
cx cy rx ry φ θ1 Δθ
the task is to find:
x1 y1 x2 y2 fA fS
This can be achieved using the following formulas:
|
(F.6.4.1) |
|
(F.6.4.2) |
|
(F.6.4.3) |
|
(F.6.4.4) |
Given the following variables:
x1 y1 x2 y2 fA fS rx ry φ
the task is to find:
cx cy θ1 Δθ
The equations simplify after a translation which places the origin at the midpoint of the line joining (x1, y1) to (x2, y2), followed by a rotation to line up the coordinate axes with the axes of the ellipse. All transformed coordinates will be written with primes. They are computed as intermediate values on the way toward finding the required center parameterization variables. This procedure consists of the following steps:
Step 1: Compute (x1′, y1′)
|
(F.6.5.1) |
Step 2: Compute (cx′, cy′)
|
(F.6.5.2) |
where the + sign is chosen if fA ≠ fS, and the − sign is chosen if fA = fS.
Step 3: Compute (cx, cy) from (cx′, cy′)
|
(F.6.5.3) |
Step 4: Compute θ1 and Δθ
In general, the angle between two vectors (ux, uy) and (vx, vy) can be computed as
|
(F.6.5.4) |
where the ± sign appearing here is the sign of ux vy − uy vx.
This angle function can be used to express θ1 and Δθ as follows:
|
(F.6.5.5) |
|
(F.6.5.6) |
where θ1 is fixed in the range −360° < Δθ < 360° such that:
if fS = 0, then Δθ < 0,
else if fS = 1, then Δθ > 0.
In other words, if fS = 0 and the right side of (F.6.5.6) is greater than 0, then subtract 360°, whereas if fS = 1 and the right side of (F.6.5.6) is less than 0, then add 360°. In all other cases leave it as is.
This section formalizes the adjustments to out-of-range rx and ry mentioned in F.6.2. Algorithmically these adjustments consist of the following steps:
Step 1: Ensure radii are non-zero
If rx = 0 or ry = 0, then treat this as a straight line from (x1, y1) to (x2, y2) and stop. Otherwise,
Step 2: Ensure radii are positive
Take the absolute value of rx and ry:
|
(F.6.6.1) |
Step 3: Ensure radii are large enough
Using the primed coordinate values of equation (F.6.5.1), compute
|
(F.6.6.2) |
If the result of the above equation is less than or equal to 1, then no further change need be made to rx and ry. If the result of the above equation is greater than 1, then make the replacements
|
(F.6.6.3) |
Step 4: Proceed with computations
Proceed with the remaining elliptical arc computations, such as those in section F.6.5. Note: As a consequence of the radii corrections in this section, equation (F.6.5.2) for the center of the ellipse always has at least one solution (i.e. the radicand is never negative). In the case that the radii are scaled up using equation (F.6.6.3), the radicand of (F.6.5.2) is zero and there is exactly one solution for the center of the ellipse.
The following implementation notes describe the algorithm for deciding which characters are selected during a text selection operation.
As the text selection operation occurs (e.g., while the user clicks and drags the mouse to identify the selection), the user agent determines a start selection position and an end selection position, each of which represents a position in the text string between two characters. After determining start selection position and end selection position, the user agent selects the appropriate characters, where the resulting text selection consists of either:
On systems with pointer devices, to determine the start selection position, the SVG user agent determines which boundary between characters corresponding to rendered glyphs is the best target (e.g., closest) based on the current pointer location at the time of the event that initiates the selection operation (e.g., the mouse down event). The user agent then tracks the completion of the selection operation (e.g., the mouse drag, followed ultimately by the mouse up). At the end of the selection operation, the user agent determines which boundary between characters is the best target (e.g., closest) for the end selection position.
If no character reordering has occurred due to bidirectionality, then the selection consists of all characters between the start selection position and end selection position. For example, if a ‘text’ element contains the string "abcdef" and the start selection position and end selection positions are 0 and 3 respectively (assuming the left side of the "a" is position zero), then the selection will consist of "abc".
When the user agent is implementing selection of bidirectional text, and when the selection starts (or ends) between characters which are not contiguous in logical order, then there might be multiple potential combinations of characters that can be considered part of the selection. The algorithms to choose among the combinations of potential selection options shall choose the selection option which most closely matches the text string's visual rendering order.
When multiple characters map inseparably to a given set of one or more glyphs, the user agent can either disallow the selection to start in the middle of the glyph set or can attempt to allocate portions of the area taken up by the glyph set to the characters that correspond to the glyph.
For systems which support pointer devices such as a mouse, the user agent is required to provide a mechanism for selecting text even when the given text has associated event handlers or links, which might block text selection due to event processing precedence rules (see Pointer events). One implementation option: For platforms which support a pointer device such as a mouse, the user agent may provide for a small additional region around character cells which initiates text selection operations but does not initiate event handlers or links.
For user agents which support both zooming on display devices and printing, it is recommended that the default printing option produce printed output that reflects the display device's current view of the current SVG document fragment (assuming there is no media-specific styling), taking into account any zooming and panning done by the user, the current state of animation, and any document changes due to DOM and scripting. Thus, if the user zooms into a particular area of a map on the display device and then requests a hardcopy, the hardcopy should show the same view of the map as appears on the display device. If a user pauses an animation and prints, the hardcopy should show the same graphics as the currently paused picture on the display device. If scripting has added or removed elements from the document, then the hardcopy should reflect the same changes that would be reflected on the display.
When an SVG document is rendered on a static-only device such as a printer which does not support SVG's animation and scripting and facilities, then the user agent shall ignore any animation and scripting elements in the document and render the remaining graphics elements according to the rules in this specification.
This appendix is normative.
In order to ensure that SVG-family documents are maximally portable among SVG-family user agents, this specification rigidly defines conformance requirements for both, as well as for SVG-family document types. While the conformance definitions can be found in this appendix, they necessarily reference normative text within this document and within other related specifications. It is only possible to fully comprehend the conformance requirements of SVG through a complete reading of all normative references.
An SVG document fragment is a Conforming SVG Document Fragment if it adheres to the specification described in this document (Scalable Vector Graphics (SVG) Specification) and also:
<?xml-stylesheet?>
processing instruction conforms to
Associating stylesheets with XML documents
[XML-SS],SVG document fragments can be included within parent XML documents using the XML namespace facilities described in Namespaces in XML [XML-XS]. Note, however, that since a Conforming SVG Document Fragment must have an ‘svg’ element as its root, the use of an individual non-‘svg’ element from the SVG namespace is disallowed. Thus, the SVG part of the following document is not conforming:
<?xml version="1.0" standalone="no"?> <!DOCTYPE SomeParentXMLGrammar PUBLIC "-//SomeParent" "http://SomeParentXMLGrammar.dtd"> <ParentXML> <!-- Elements from ParentXML go here --> <!-- The following is not conforming --> <z:rect xmlns:z="http://www.w3.org/2000/svg" x="0" y="0" width="10" height="10" /> <!-- More elements from ParentXML go here --> </ParentXML>
Instead, for the SVG part to become a Conforming SVG Document Fragment, the file could be modified as follows:
<?xml version="1.0" standalone="no"?> <!DOCTYPE SomeParentXMLGrammar PUBLIC "-//SomeParent" "http://SomeParentXMLGrammar.dtd"> <ParentXML> <!-- Elements from ParentXML go here --> <!-- The following is conforming --> <z:svg xmlns:z="http://www.w3.org/2000/svg" width="100px" height="100px"> <z:rect x="0" y="0" width="10" height="10"/> </z:svg> <!-- More elements from ParentXML go here --> </ParentXML>
The SVG language or these conformance criteria provide no designated size limits on any aspect of SVG content. There are no maximum values on the number of elements, the amount of character data, or the number of characters in attribute values.
A file is a Conforming SVG Stand-Alone File if:
A Conforming SVG Generator is a program which:
Additionally, an authoring tool which is a Conforming SVG Generator conforms to all of the Priority 1 accessibility guidelines from the document Authoring Tool Accessibility Guidelines 1.0 [ATAG] that are relevant to generators of SVG content. (Priorities 2 and 3 are encouraged but not required for conformance.)
SVG generators are encouraged to follow W3C developments in the area of internationalization. Of particular interest is the W3C Character Model and the concept of Webwide Early Uniform Normalization, which promises to enhance the interchangability of Unicode character data across users and applications. Future versions of the SVG specification are likely to require support of the W3C Character Model in Conforming SVG Generators.
Conforming SVG Servers must meet all the requirements of a Conforming SVG
Generator. In addition, Conforming SVG Servers using HTTP or other protocols
that use Internet Media types must serve SVG stand-alone files with the media
type "image/svg+xml"
.
Also, if the SVG file is compressed with gzip or deflate, Conforming SVG Servers must indicate this with the appropriate header, according to what the protocol supports. Specifically, for content compressed by the server immediately prior to transfer, the server must use the "Transfer-Encoding: gzip" or "Transfer-Encoding: deflate" headers as appropriate, and for content stored in a compressed format on the server (e.g. with the file extension "svgz"), the server must use the "Content-Encoding: gzip" or "Content-Encoding: deflate" headers as appropriate.
Note: Compression of stored content (the "entity," in HTTP terms) is distinct from automatic compression of the message body, as defined in HTTP/1.1 TE/ Transfer Encoding ([RFC2616], sections 14.39 and 14.41).
A DOM subtree rooted at a given element is a Conforming SVG DOM Subtree if, once serialized to XML, is a Conforming SVG Document Fragment. If the DOM subtree cannot be serialized to XML, such as when a Comment node's data contains the substring "--", then the subtree is not a Conforming SVG DOM Subtree.
An SVG interpreter is a program which can parse and process SVG document fragments. Examples of SVG interpreters are server-side transcoding tools (e.g., a tool which converts SVG content into modified SVG content) or analysis tools (e.g., a tool which extracts the text content from SVG content). An SVG viewer also satisfies the requirements of an SVG interpreter in that it can parse and process SVG document fragments, where processing consists of rendering the SVG content to the target medium.
In a Conforming SVG Interpreter, the XML parser must be able to parse and process all XML constructs defined within XML 1.0 [XML10] and Namespaces in XML [XML-NS].
There are two sub-categories of Conforming SVG Interpreters:
Now that feature strings have been removed, the above conformance classes need to be defined without reference to them.
A Conforming SVG Interpreter must parse any SVG document correctly. It is not required to interpret the semantics of all features correctly.
Note: A transcoder from SVG into another graphics representation, such as an SVG-to-raster transcoder, represents a viewer, and thus viewer conformance criteria apply. (See Conforming SVG Viewers.)
Action: | Look at the performance class requirements and decide whether to remove points or move them into general requirements. (heycam)
Spec that calculation of CTMs should use double precision. (stakagi) |
---|---|
Resolution: | Remove performance class requirements from SVG 2. ( ConformingHighQualitySVGViewers ) |
Purpose: | To modulate the tradeoff of a numerical precision in use cases of the technical drawing and mapping, and the performance of user agent. |
Owner: | heycam, stakagi |
An SVG viewer is a program which can parse and process an SVG document fragment and render the contents of the document onto some sort of output medium such as a display or printer; thus, an SVG Viewer is also an SVG Interpreter.
There are two sub-categories of Conforming SVG Viewers:
Now that feature strings have been removed, the above conformance classes need to be defined without reference to them.
Specific criteria that apply to both Conforming Static SVG Viewers and Conforming Dynamic SVG Viewers:
image-rendering
’.Although anti-aliasing support is not a strict requirement for a Conforming SVG Viewer, it is highly recommended for display devices. Lack of anti-aliasing support will generally result in poor results on display devices.
Specific criteria that apply to only Conforming Dynamic SVG Viewers:
The Web Accessibility Initiative is defining User Agent Accessibility Guidelines 1.0 [UAAG]. Viewers are encouraged to conform to the Priority 1 accessibility guidelines defined in this document, and preferably also Priorities 2 and 3. Once the guidelines are completed, a future version of this specification is likely to require conformance to the Priority 1 guidelines in Conforming SVG Viewers.
A higher order concept is that of a Conforming High-Quality SVG Viewer, with sub-categories Conforming High-Quality Static SVG Viewer and Conforming High-Quality Dynamic SVG Viewer.
Both a Conforming High-Quality Static SVG Viewer and a Conforming High-Quality Dynamic SVG Viewer must support the following additional features:
image-rendering
’.A Conforming High-Quality Dynamic SVG Viewer must support the following additional features:
A Conforming SVG Viewer must be able to apply styling properties to SVG content using presentation attributes.
If the user agent supports Cascading Style Sheets, level 2 revision 1 [CSS21], a Conforming SVG Viewer must support CSS styling of SVG content and must support all features from CSS 2.1 that are described in this specification as applying to SVG (see properties shared with CSS and XSL, Styling with CSS and Facilities from CSS and XSL used by SVG). The supported features from CSS 2.1 must be implemented in accordance with the conformance definitions from the CSS 2.1 specification ([CSS21], section 3.2).
If the user agent includes an HTML or XHTML viewing capability or can apply CSS/XSL styling properties to XML documents, then a Conforming SVG Viewer must support resources of MIME type "image/svg+xml" wherever raster image external resources can be used, such as in the HTML or XHTML ‘img’ element and in CSS/XSL properties that can refer to raster image resources (e.g., ‘background-image’).
This appendix is informative, not normative.
This appendix highlights the accessibility features of SVG and accessibility related specifications used to support SVG and the associated W3C Web Content Accessibility Guidelines (WCAG) 2.0 [WCAG2] requirements they are designed to support.
This section enumerates the SVG accessibility-related specifications and authoring guidelines.
We need to normatively reference html 5.1 for SVG Document title and activeElement, as well as for getSVGDocument on HTMLIframeElement etc..
This appendix is informative, not normative.
The following are the elements in the SVG language:
This appendix is informative, not normative.
The following table lists all of the attributes defined in the SVG language, except for the presentation attributes, which are treated in the Presentation attributes section below. For each attribute, the elements on which the attribute may be specified is also given.
As described in the Styling chapter, for each property there exists a corresponding presentation attribute. The table below lists the presentation attributes and the elements on which they may be specified.
Since the plan is to allow all SVG elements to be stylable, we will likely allow all presentation attributes on all SVG elements, and this table can then be removed.
This appendix is informative, not normative.
This table should not list properties defined in other specifications.
The table lacks a column for the 'computed value'.
Name | Values | Initial value | Applies to | Inh. | Percentages | Media | Anim. |
---|---|---|---|---|---|---|---|
alignment-baseline |
auto | baseline | before-edge | text-before-edge | middle | central | after-edge | text-after-edge | ideographic | alphabetic | hanging | mathematical | see property description | ‘tspan’, ‘textPath’ elements | no | N/A | visual | yes |
baseline-shift |
baseline | sub | super | <percentage> | <length> | baseline | ‘tspan’, ‘textPath’ elements | no | refer to the "line height" of the ‘text’ element, which in the case of SVG is defined to be equal to the font size | visual | yes |
buffered-rendering |
auto | dynamic | static | auto | container elements and graphics elements | no | N/A | visual | yes |
clip |
<shape> | auto | auto | elements which establish a new viewport, ‘pattern’ elements and ‘marker’ elements | no | N/A | visual | yes |
clip-path |
<basic-shape> | <url> | none | none | container elements and graphics elements | no | N/A | visual | yes |
clip-rule |
nonzero | evenodd | nonzero | graphics elements within a ‘clipPath’ element | yes | N/A | visual | yes |
color |
<color> | depends on user agent | elements to which properties ‘fill ’, ‘stroke ’, ‘stop-color ’, ‘flood-color ’, ‘lighting-color ’ apply |
yes | N/A | visual | yes |
color-interpolation |
auto | sRGB | linearRGB | sRGB | container elements, graphics elements and ‘animate’ | yes | N/A | visual | yes |
color-rendering |
auto | optimizeSpeed | optimizeQuality | auto | container elements, graphics elements and ‘animate’ | yes | N/A | visual | yes |
cursor |
[ [<url> ,]* [ auto | crosshair | default | pointer | move | e-resize | ne-resize | nw-resize | n-resize | se-resize | sw-resize | s-resize | w-resize| text | wait | help ] ] | auto | container elements and graphics elements | yes | N/A | visual, interactive | yes |
direction |
ltr | rtl | ltr | text content elements | yes | N/A | visual | no |
display |
inline | block | list-item | run-in | compact | marker | table | inline-table | table-row-group | table-header-group | table-footer-group | table-row | table-column-group | table-column | table-cell | table-caption | none | inline | ‘svg’, ‘g’, ‘switch’, ‘a’, ‘foreignObject’, graphics elements (including the ‘text’ element) and text sub-elements (i.e., ‘tspan’, ‘textPath’) | no | N/A | all | yes |
dominant-baseline |
auto | use-script | no-change | reset-size | ideographic | alphabetic | hanging | mathematical | central | middle | text-after-edge | text-before-edge | auto | text content elements | no | N/A | visual | yes |
fill |
<paint> (See Specifying paint) | black | shapes and text content elements | yes | N/A | visual | yes |
fill-opacity |
<opacity-value> | 1 | shapes and text content elements | yes | N/A | visual | yes |
fill-rule |
nonzero | evenodd | nonzero | shapes and text content elements | yes | N/A | visual | yes |
filter |
<filter-function-list> | none | none | container elements and graphics elements | no | N/A | visual | yes |
flood-color |
currentColor | <color> [<icccolor>] |
black | ‘feFlood’ elements | no | N/A | visual | yes |
flood-opacity |
<opacity-value> | 1 | ‘feFlood’ elements | no | N/A | visual | yes |
font |
[ [ ‘font-style ’
|| ‘font-variant ’
|| ‘font-weight ’
]? ‘font-size ’
[ / 'line-height'
]? ‘font-family ’
] | caption | icon | menu | message-box | small-caption |
status-bar |
see individual properties | text content elements | yes | see individual properties | visual | yes [1] |
font-family |
[[ <family-name> | <generic-family> ],]* [ <family-name> | <generic-family>] | depends on user agent | text content elements | yes | N/A | visual | yes |
font-size |
<absolute-size> | <relative-size> | <length> | <percentage> | medium | text content elements | yes, the computed value is inherited | refer to parent element's font size | visual | yes |
font-size-adjust |
<number> | none | none | text content elements | yes | N/A | visual | yes [1] |
font-stretch |
normal | wider | narrower | ultra-condensed | extra-condensed | condensed | semi-condensed | semi-expanded | expanded | extra-expanded | ultra-expanded | normal | text content elements | yes | N/A | visual | yes |
font-style |
normal | italic | oblique | normal | text content elements | yes | N/A | visual | yes |
font-variant |
normal | small-caps | normal | text content elements | yes | N/A | visual | yes |
font-weight |
normal | bold | bolder | lighter | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | normal | text content elements | yes | N/A | visual | yes |
glyph-orientation-horizontal |
<angle> | <number> | 0deg | text content elements | yes | N/A | visual | no |
glyph-orientation-vertical |
auto | <angle> | <number> | auto | text content elements | yes | N/A | visual | no |
image-rendering |
auto | optimizeSpeed | optimizeQuality | auto | images | yes | N/A | visual | yes |
letter-spacing |
normal | <length> | normal | text content elements | yes | N/A | visual | yes |
lighting-color |
currentColor | <color> [<icccolor>] |
white | ‘feDiffuseLighting’ and ‘feSpecularLighting’ elements | no | N/A | visual | yes |
line-height |
normal | <number> | <length> | <percentage> | normal | ‘text’ elements | yes | refer to font size of element itself | visual | yes |
marker |
see individual properties | see individual properties | ‘path’, ‘line’, ‘polyline’ and ‘polygon’ elements | yes | N/A | visual | yes |
marker-end marker-mid marker-start |
none | <url> | none | ‘path’, ‘line’, ‘polyline’ and ‘polygon’ elements | yes | N/A | visual | yes |
mask |
<url> | none | none | container elements and graphics elements | no | N/A | visual | yes |
opacity |
<opacity-value> | 1 | container elements and graphics elements | no | N/A | visual | yes |
overflow |
visible | hidden | scroll | auto | see prose | elements which establish a new viewport, ‘pattern’ elements and ‘marker’ elements | no | N/A | visual | yes |
paint-order |
normal | [ fill || stroke || markers ] | normal | graphics elements and text content elements | no | N/A | visual | yes |
pointer-events |
bounding-box | visiblePainted | visibleFill | visibleStroke |
visible | painted | fill | stroke | all | none |
visiblePainted | container elements, graphics elements and text content child elements | yes | N/A | visual | yes |
shape-rendering |
auto | optimizeSpeed | crispEdges | geometricPrecision |
auto | shapes | yes | N/A | visual | yes |
stop-color |
currentColor | <color> [<icccolor>] |
black | ‘stop’ elements | no | N/A | visual | yes |
stop-opacity |
<opacity-value> | 1 | ‘stop’ elements | no | N/A | visual | yes |
stroke |
<paint> (See Specifying paint) | none | shapes and text content elements | yes | N/A | visual | yes |
stroke-dasharray |
none | <dasharray> | none | shapes and text content elements | yes | N/A | visual | yes [1] |
stroke-dashoffset |
<percentage> | <length> | 0 | shapes and text content elements | yes | refer to the size of the current viewport | visual | yes |
stroke-linecap |
butt | round | square | butt | shapes and text content elements | yes | N/A | visual | yes |
stroke-linejoin |
miter | round | bevel | miter | shapes and text content elements | yes | N/A | visual | yes |
stroke-miterlimit |
<miterlimit> | 4 | shapes and text content elements | yes | N/A | visual | yes |
stroke-opacity |
<opacity-value> | 1 | shapes and text content elements | yes | N/A | visual | yes |
stroke-width |
<percentage> | <length> | 1 | shapes and text content elements | yes | refer to the size of the current viewport | visual | yes |
text-anchor |
start | middle | end | start | text content elements | yes | N/A | visual | yes |
text-decoration |
none | [ underline || overline || line-through || blink ] | none | text content elements | no (see prose) | N/A | visual | yes |
text-rendering |
auto | optimizeSpeed | optimizeLegibility | geometricPrecision |
auto | ‘text’ elements | yes | N/A | visual | yes |
unicode-bidi |
normal | embed | bidi-override | normal | text content elements | no | N/A | visual | no |
vector-effect |
non-scaling-stroke | none | none | graphics elements | no | N/A | visual | yes |
visibility |
visible | hidden | collapse | visible | graphics elements (including the ‘text’ element) and text sub-elements (i.e., ‘tspan’, ‘textPath’ and ‘a’) | yes | N/A | visual | yes |
word-spacing |
normal | <length> | normal | text content elements | yes | N/A | visual | yes |
white-space |
normal | pre | nowrap | pre-wrap | pre-line | normal | text content elements | yes | N/A | visual | yes |
writing-mode |
lr-tb | rl-tb | tb-rl | lr | rl | tb | lr-tb | ‘text’ elements | yes | N/A | visual | no |
font
’, ‘font-size-adjust
’ and ‘stroke-dasharray
’
properties are animatable but do not support additive animation.This appendix is informative, not normative.
The following is a list of all IDL interfaces defined in this specification:
This appendix is normative.
This appendix registers a new MIME media type, "image/svg+xml" in conformance with BCP 13 and W3CRegMedia.
image
svg+xml
None.
charset
Same as application/xml media type, as specified in [RFC3023] or its successors.
Same as for application/xml. See [RFC3023], section 3.2 or its successors.
As with other XML types and as noted in [RFC3023] section 10, repeated expansion of maliciously constructed XML entities can be used to consume large amounts of memory, which may cause XML processors in constrained environments to fail.
Several SVG elements may cause arbitrary URIs to be referenced. In this case, the security issues of [RFC3986], section 7, should be considered.
In common with HTML, SVG documents may reference external media such as images, audio, video, style sheets, and scripting languages. Scripting languages are executable content. In this case, the security considerations in the Media Type registrations for those formats shall apply.
In addition, because of the extensibility features for SVG and of XML in general, it is possible that "image/svg+xml" may describe content that has security implications beyond those described here. However, if the processor follows only the normative semantics of the published specification, this content will be outside the SVG namespace and shall be ignored. Only in the case where the processor recognizes and processes the additional content, or where further processing of that content is dispatched to other processors, would security issues potentially arise. And in that case, they would fall outside the domain of this registration document.
The published specification describes processing semantics that dictate behavior that must be followed when dealing with, among other things, unrecognized elements and attributes, both in the SVG namespace and in other namespaces.
Because SVG is extensible, conformant "image/svg+xml" processors must expect that content received is well-formed XML, but it cannot be guaranteed that the content is valid to a particular DTD or Schema or that the processor will recognize all of the elements and attributes in the document.
SVG has a published Test Suite and associated implementation report showing which implementations passed which tests at the time of the report. This information is periodically updated as new tests are added or as implementations improve.
This media type registration is extracted from Appendix P of the SVG 1.1 specification.
SVG is used by Web browsers, often in conjunction with HTML; by mobile phones and digital cameras, as a format for interchange of graphical assets in desk top publishing, for industrial process visualization, display signage, and many other applications which require scalable static or interactive graphical capability.
Note that the extension 'svgz' is used as an alias for 'svg.gz' [RFC1952], i.e. octet streams of type image/svg+xml, subsequently compressed with gzip.
Note that the Macintosh file type code 'svgz' (all lowercase) is used as an alias for GZIP [RFC1952] compressed "svg ", i.e. octet streams of type image/svg+xml, subsequently compressed with gzip.
org.w3c.svg
conforms to public.image
and to public.xml
Chris Lilley, Doug Schepers (member-svg-media-type@w3.org).
COMMON
None
The SVG specification is a work product of the World Wide Web Consortium's SVG Working Group.
The W3C has change control over this specification.
This appendix is informative, not normative.
This appendix summarizes the changes that have been made since the SVG 1.1 Second Edition Recommendation. Changes made since the last SVG 2 Working Draft are highlighted.
A number of stylistic changes have been made to the specification to make it more readable. These include the following:
In additional to the editorial changes listed above, the following substantial additions, changes and removals have been made.
suspendRedraw
, unsuspendRedraw
and unsuspendRedrawAll
methods on the SVGSVGElement interface.body
.SVGElementInstance
and SVGElementInstanceList
interfaces, and the corresponding attributes on the SVGUseElement interface.SVGPathSeg*
and SVGAnimatedPathData
interfaces and the related methods on SVGPathElement.inline-size
’ presentation attribute to ‘text’, and a
section about ‘text-overflow
’ processing.white-space
’ property and deprecated ‘xml:space’ attribute.paint-order
’ property.buffered-rendering
’ property.vector-effect
’ property to support non-scaling stroke.stroke-linejoin
’.fill
’ and
‘stroke
’ <paint> so that they can take multiple paints.z-index
’ property.solid-color
’
and ‘solid-opacity
’, ported over from SVG Tiny 1.2. (Renamed 'solidColor' to
'solidcolor'.)overflow
’ property should be respected on the outermost svg elements inline in html.pointer-events
’.