W3C home > Mailing lists > Public > public-svg-wg@w3.org > July to September 2014

[svgwg] Add z-index.

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
Message-Id: <20140826094510.6CA511550243@ps58493.dreamhostps.com>
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>&lt;svg xmlns="http://www.w3.org/2000/svg"&gt;
+  &lt;rect x="0"  width="100" height="100" fill="red"    z-index="-1"/&gt;
+  &lt;rect x="40" width="100" height="100" fill="lime"/&gt;
+  &lt;rect x="80" width="100" height="100" fill="blue"   z-index="1"/&gt;
+  &lt;rect x="60" width="100" height="100" fill="aqua"/&gt;
+  &lt;rect x="20" width="100" height="100" fill="yellow" z-index="-1"/&gt;
+&lt;/svg&gt;</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>&lt;svg xmlns="http://www.w3.org/2000/svg"&gt;
+  &lt;g z-index="0"&gt;
+    &lt;!-- this is a self contained graphic --&gt;
+    &lt;rect x="40" width="100" height="100" fill="lime" z-index="1"/&gt;
+    &lt;rect x="20" width="100" height="100" fill="yellow"/&gt;
+  &lt;/g&gt;
+  &lt;rect x="60" width="100" height="100" fill="aqua"/&gt;
+  &lt;rect x="0" width="100" height="100" fill="red" z-index="-1"/&gt;
+&lt;/svg&gt;</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>&lt;integer&gt;</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

This archive was generated by hypermail 2.4.0 : Friday, 17 January 2020 17:29:56 UTC