- From: SVG Working Group repository <cam+svgwgrepo@mcc.id.au>
- Date: Tue, 26 Aug 2014 02:45:10 -0700 (PDT)
- To: public-svg-wg@w3.org
https://github.com/w3c/svgwg/commit/f1c3db9365f80ef9cb34397e8bb6baf33ed504df
commit f1c3db9365f80ef9cb34397e8bb6baf33ed504df
Author: Cameron McCormack <cam@mcc.id.au>
Date: Tue Aug 26 19:41:58 2014 +1000
Add z-index.
diff --git a/master/changes.html b/master/changes.html
index e5a28b0..b484830 100644
--- a/master/changes.html
+++ b/master/changes.html
@@ -256,6 +256,8 @@ have been made.</p>
<li class="added-since-last-wd">Added the <a>'stroke-dashcorner'</a> and
<a>'stroke-dashadjust'</a> properties.</li>
+
+ <li class="added-since-last-wd">Added the <a>'z-index'</a> property.</li>
</ul>
<h3 id="color">Color chapter</h3>
diff --git a/master/definitions.xml b/master/definitions.xml
index c36f789..8a17c06 100644
--- a/master/definitions.xml
+++ b/master/definitions.xml
@@ -1034,6 +1034,7 @@
<property name='visibility' href='painting.html#VisibilityControl'/>
<property name='height' href='styling.html#HeightProperty'/>
<property name='width' href='styling.html#WidthProperty'/>
+ <property name='z-index' href='painting.html#ZIndexProperty'/>
<!-- ... text properties defined elsewhere -->
<property name='hyphens' href='text.html#HyphensProperty'/>
@@ -1431,4 +1432,5 @@
<symbol name='identifier' href='http://www.w3.org/TR/2012/WD-css3-values-20120308/#identifier'/>
<symbol name='transform-function' href='http://dev.w3.org/csswg/css3-transforms/#transform-functions'/>
+ <property name='position' href='http://www.w3.org/TR/CSS21/visuren.html#propdef-position'/>
</definitions>
diff --git a/master/painting.html b/master/painting.html
index a8c9d4f..5b6fc89 100644
--- a/master/painting.html
+++ b/master/painting.html
@@ -3606,6 +3606,222 @@ specified to render in that order?</p>
<p class="caption">Text painted with its stroke below the fill.</p>
</div>
</div>
+</div>
+
+<h2 id="ZIndexProperty">Controlling element rendering order: the effect of the <span class='property'>'z-index'</span> property</h2>
+
+<p class="note">See the CSS 2.1 specification for the definition
+of <a>'z-index'</a>. [<a href="refs.html#ref-CSS21">CSS21</a>]</p>
+
+<p><i>The following text is non-normative.</i></p>
+
+<p>SVG elements are normally painted in document order using the painters model
+(elements that come later in the document paint over the top of elements that
+came earlier in the document). However, sometimes it is desirable to be able to
+force an element to a higher or lower position visually without changing its
+position in the DOM tree. This functionality is provided by the <a>'z-index'</a> property.</p>
+
+<p>Understanding the <a>'z-index'</a> property involves understanding the terms "stack
+level" and "stacking context". Let's consider each in turn:</p>
+
+<p>The <a>'z-index'</a> property moves an element up or down a conceptual z-axis into
+layers called "stack levels". By default all the elements in a document are in
+stack level 0. By setting <a>'z-index'</a> on an element to an integer other than 0, an
+author can force an element into a higher or lower stack level, thereby pushing
+that element above or below the elements in other stack levels. Documents are
+rendered by painting each stack level in turn, from lowest to highest, and
+painting the elements in each stack level in document order (i.e. using the
+painters model).</p>
+
+<div class="example">
+ <p>Here is a simple example:</p>
+ <pre><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></pre>
+ <p>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.</p>
+</div>
+
+<p>In addition to putting an element into a stack level, setting an element's
+<a>'z-index'</a> property to an integer value also creates something called a "stacking
+context". A stacking context is a stack level container that groups together an
+entirely new set of stack levels for that element's descendants. A <a>'z-index'</a>
+property on any descendant will then place that descendant into one of the stack
+level in this new stacking context (descendants go into its level 0 by default),
+not into the stack levels of the parent or any other stacking context. When an
+element that creates a new stacking context is painted, so is the new stacking
+context that it created, along with all of that stacking context's stack levels
+and the elements that they contain.</p>
+
+<p>Stacking contexts allow self contained document fragments to use <a>'z-index'</a> without
+needing to worry about their children interleaving badly with other elements
+(z-indexed or otherwise) in other parts of the document.</p>
+
+<div class="example">
+ <p>In the following example, the <a>'z-index'</a> property on the <a>'g'</a>
+ element is set to zero. This creates a new stacking context to contain the
+ <a>'g'</a> element's children without moving the <a>'g'</a> to a different
+ level in the document's root stacking context:</p>
+ <pre><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></pre>
+
+ <p>The example's root stacking context contains two stack levels: -1 and 0. The red
+ <a>'rect'</a> is in level -1, and the <a>'g'</a> element and aqua <a>'rect'</a> are in level 0. Inside
+ stack level 0, the <a>'g'</a> element's <a>'z-index'</a> property creates a new nested stacking
+ context at the <a>'g'</a> for the <a>'g'</a> element's children. In this child stacking
+ context there are two stack levels: 0 and 1. The yellow <a>'rect'</a> is in level 0 (the
+ default), and the lime <a>'rect'</a> is in level 1.</p>
+
+ <p>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 <a>'g'</a>
+ element is painted followed by the aqua rect. When the <a>'g'</a> 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 <a>'g'</a> 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 <a>'g'</a>'s child stacking context results in the
+ aqua rect painting over the lime rect. The painting order is therefore: red,
+ yellow, lime, aqua.</p>
+</div>
+
+<p>Note that setting <a>'z-index'</a> to an integer value is not the only way that a new
+stacking contexts is triggered for an element's descendants. See the normative
+text below for a full list.</p>
+
+<p><i>The following text is normative.</i></p>
+
+<p>CSS <a href="http://www.w3.org/TR/CSS2/visuren.html#propdef-z-index">specifies</a> a
+property named <a>'z-index'</a>. The <a href="http://www.w3.org/TR/CSS2/zindex.html">CSS rules
+that define the effect of the <span class='property'>'z-index'</span> property</a>
+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 <a>'z-index'</a> property on elements in the SVG
+namespace.</p>
+
+<p>Contrary to the rules in CSS 2.1, the <a>'z-index'</a> property applies to all SVG
+elements regardless of the value of the <a>'position'</a> property, with one exception:
+as for boxes in CSS 2.1, outer <a>'svg'</a> elements must be positioned for <a>'z-index'</a>
+to apply to them.</p>
+
+<p>The <a>'z-index'</a> property specifies:</p>
+
+<ol>
+ <li>The stack level of the element in the current stacking context.</li>
+ <li>Whether the element establishes a new local stacking context.</li>
+</ol>
+
+<p>Values have the following meanings:</p>
+
+<dl>
+ <dt><integer></dt>
+ <dd>This integer is the stack level of the element in the current
+ stacking context. The element also establishes a new local
+ stacking context for its descendants.</dd>
+
+ <dt>auto</dt>
+ <dd>The stack level of the element in the current stacking context
+ is the same as its parent element, unless its parent established
+ a new stacking context, in which case its stack level is 0. The
+ element does not establish a new local stacking context.</dd>
+</dl>
+
+<p>A new stacking context must be established at an SVG element for its descendants if:</p>
+
+<ul>
+ <li>it is the root element</li>
+
+ <li>the <a>'z-index'</a> property applies to the element and its computed
+ value is an integer</li>
+
+ <li>the element is an <a>outermost svg element</a>, or a <a>'foreignObject'</a>,
+ <a>'image'</a>, <a>'marker element'</a>, <a>'mask element'</a>, <a>'pattern'</a>,
+ <a>'symbol'</a> or <a>'use'</a> element</li>
+
+ <li>the element is an inner <a>'svg'</a> element and the computed value of its
+ <a>'overflow'</a> property is a value other than <span class='prop-value'>visible</span></li>
+
+ <li>the element is subject to explicit clipping:
+ <ul>
+ <li>the <a>'clip'</a> property applies to the element and it has a
+ computed value other than <span class='prop-value'>auto</span></li>
+
+ <li>the <a>'clip-path'</a> property applies to the element and it has a
+ computed value other than <span class='prop-value'>none</span></li>
+ </ul>
+ </li>
+
+ <li>the <a>'opacity'</a> property applies to the element and it has a
+ computed value other than <span class='prop-value'>1</span></li>
+
+ <li>the <a>'mask property'</a> property applies to the element and it has a computed
+ value other than <span class='prop-value'>none</span></li>
+
+ <li>the <a>'filter property'</a> property applies to the element and it has a
+ computed value other than <span class='prop-value'>none</span></li>
+</ul>
+
+<!--
+<p>For a user friendly explanation of the terms "stack level" and "stacking
+context", see the z-index primer document. For the normative rules regarding how
+stacking contexts and stack levels affect SVG elements, see below.</p>
+-->
+
+<p>Stacking contexts and stack levels are conceptual tools used to describing 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.</p>
+
+<p>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.</p>
+
+<p>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 back-to-front according to document
+tree order.</p>
+
+<p>With the exception of the <a>'foreignObject'</a> element, the back to front stacking
+order for a stacking context created by an SVG element is:</p>
+
+<ol>
+ <li>the background and borders of the element forming the stacking
+ context, if any</li>
+
+ <li>child stacking contexts created by descendants with negative stack
+ levels, primarily ordered by most negative first, then by tree order</li>
+
+ <li>descendants with <span class='prop-value'>'z-index: auto'</span> or
+ <span class='prop-value'>'z-index: 0'</span>, in tree order</li>
+
+ <li>child stacking contexts created by descendants with positive stack levels,
+ primarily ordered by lowest index first, then by tree order</li>
+</ol>
+
+<p>Since the <a>'foreignObject'</a> element creates a "fixed position containing block" in
+CSS terms, the normative rules for the stacking order of the stacking context
+created by <a>'foreignObject'</a> elements are the rules in Appendix E of CSS 2.1.</p>
<div class="ready-for-wider-review">
<h2 id="ColorInterpolation">Color space for interpolation: the
@@ -4204,7 +4420,6 @@ bounding box of the entire <a>'text'</a> element. (See the discussion of
gradient.</p>
</div>
</div>
-</div>
<h2 id="DOMInterfaces">DOM interfaces</h2>
diff --git a/master/render.html b/master/render.html
index 2345e67..9d93a10 100644
--- a/master/render.html
+++ b/master/render.html
@@ -90,6 +90,8 @@ drawing order, with the first elements in the SVG document
fragment getting "painted" first. Subsequent elements are
painted on top of previously painted elements.</p>
+<p class="issue">Should mention here how <a>'z-index'</a> can affect this.</p>
+
<h2 id="Grouping">How groups are rendered</h2>
<div class="ready-for-wider-review">
<p>
Received on Tuesday, 26 August 2014 09:45:33 UTC