Mon, 21 Jan 2013 17:02:00 -0800
[css-exclusions] start/end consistency (bug 16437)
1 <!DOCTYPE html public '-//W3C//DTD HTML 4.01//EN' 'http://www.w3.org/TR/html4/strict.dtd'>
2 <html lang="en">
3 <head profile="http://www.w3.org/2006/03/hcard">
4 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5 <title>CSS Exclusions and Shapes Module Level 3</title>
6 <link rel="stylesheet" type="text/css" href="../shared/style/default.css" />
7 <script src='http://test.csswg.org/harness/annotate.js#CSS3-EXCLUSIONS_DEV' type='text/javascript' defer></script>
10 <style type="text/css">
11 .singleImgExample {
12 display: block;
13 margin: auto;
14 }
16 .example-table {
17 table-layout: fixed;
18 width: 100%;
19 }
21 .example-table tr td img {
22 width: 90%;
23 }
24 </style>
26 <link rel="stylesheet" type="text/css"
27 href="http://www.w3.org/StyleSheets/TR/W3C-ED.css">
29 <link rel="stylesheet" type="text/css"
30 href="../shared/style/issues.css">
32 <link id="st" href="../shared/style/alternate-spec-style.css" rel="stylesheet"
33 type="text/css" title="alternate spec style">
36 </head>
37 <body>
38 <div id="div-head" class="head">
39 <p><a href="http://www.w3.org/"><img id="mobile-logo" alt="W3C" height="53" src=
40 "http://www.w3.org/2008/site/images/logo-w3c-mobile-lg" width="90"></a>
43 <!--begin-logo-->
45 <p><a href="http://www.w3.org/"><img id="logo" alt="W3C" height="48" src=
46 "http://www.w3.org/Icons/w3c_home" width="72"></a> <!--end-logo--></p>
47 <h1 id="css-exclusions-module">CSS Exclusions and Shapes Module Level 3</h1>
48 <h2 class="no-num no-toc">[LONGSTATUS] [DATE]</h2>
49 <dl>
50 <dt>This version:</dt>
51 <dd><a href="http://dev.w3.org/csswg/css3-exclusions/">http://dev.w3.org/csswg/css3-exclusions/</a></dd>
52 <!--<dd><a href="[VERSION]">http://www.w3.org/TR/[YEAR]/WD-css3-exclusions-[CDATE]/</a></dd>-->
54 <dt>Latest version:</dt>
55 <dd><a href="http://www.w3.org/TR/[SHORTNAME]/">http://www.w3.org/TR/[SHORTNAME]/</a></dd>
57 <dt>Editor's Draft:</dt>
58 <dd><a href="http://dev.w3.org/csswg/[SHORTNAME]/">http://dev.w3.org/csswg/[SHORTNAME]/</a>
60 <dt>Previous version:</dt>
61 <dd>None</dd>
63 <dt>Editors:</dt>
64 <dd class="vcard"><span class="fn">Vincent Hardy</span>, <span class="org">Adobe Systems, Inc.</span>, <span class="email">vhardy@adobe.com</span></dd>
65 <dd class="vcard"><span class="fn">Rossen Atanassov</span>, <span class="org">Microsoft Corporation</span>, <span class="email">ratan@microsoft.com</span></dd>
66 <dd class="vcard"><span class="fn">Alan Stearns</span>, <span class="org">Adobe Systems, Inc.</span>, <span class="email">stearns@adobe.com</span></dd>
68 <dt>Issues List:</dt>
69 <dd><a href="https://www.w3.org/Bugs/Public/buglist.cgi?query_format=advanced&product=CSS&component=Exclusions&resolution=---&cmdtype=doit">in Bugzilla</a></dd>
71 <dt>Discussion:</dt>
72 <dd><a href="http://lists.w3.org/Archives/Public/www-style/">www-style@w3.org</a> with subject line "<code>[css3-exclusions] message topic</code>"
74 </dl>
75 <!--copyright-->
76 <hr title="Separator for header">
77 </div>
79 <h2 class="no-num no-toc" id="abstract">Abstract</h2>
82 <p>
83 CSS Exclusions define arbitrary areas around which <a href="http://www.w3.org/TR/CSS2/visuren.html#inline-boxes">inline content</a> ([[!CSS21]]) content can flow.
84 CSS Exclusions can be defined on any CSS block-level elements. CSS
85 Exclusions extend the notion of content wrapping previously limited to
86 floats.</p>
88 <p>CSS Shapes control the geometric shapes used for wrapping inline flow
89 content outside or inside an element. CSS Shapes can be applied to any
90 element. A circle shape on a float will cause inline content to wrap around
91 the circle shape instead of the float's bounding box.</p>
93 <p>Combining CSS Exclusions and CSS Shapes allows sophisticated layouts,
94 allowing interactions between shapes in complex positioning schemes.</p>
96 <h2 class="no-num no-toc" id="status">Status of this document</h2>
97 <!--status-->
99 <h2 class="no-num no-toc" id="contents">Table of contents</h2>
100 <!--toc-->
102 <h2 id="intro">Introduction</h2>
103 <p><em>This section is not normative.</em></p>
104 <p>
105 The exclusions section of this specification defines features that allow inline flow
106 content to wrap around outside the <span>exclusion area</span> of elements.
107 </p>
108 <p>
109 The shapes section of the specification defines properties to control the geometry of
110 an element's <span>exclusion area</span> as well as the geometry used for wrapping
111 an element's inline flow content.
112 </p>
114 <h2 id="definitions">Definitions</h2>
116 <dfn>Exclusion box</dfn>
118 <p>
119 A <a href="http://www.w3.org/TR/css3-box/">box</a> ([[!CSS3BOX]]) that defines an <span>exclusion area</span> for other boxes. The 'wrap-flow'
120 property is used to make an element's generated box an exclusion box. An exclusion box contributes
121 its <span>exclusion area</span> to its <a href="http://www.w3.org/TR/CSS2/visudet.html#containing-block-details">
122 containing block's</a> <span>wrapping context</span>. An element with a 'float'
123 computed value other than 'none' does not become an exclusion.
124 </p>
126 <dfn>Exclusion area</dfn>
128 <p>
129 The area used for excluding inline flow content around an exclusion box. The
130 <span>exclusion area</span> is equivalent to the <a href="http://www.w3.org/TR/CSS2/box.html#box-dimensions">
131 border box</a>.
132 This specification's
133 'shape-outside' property
134 can be used to define arbitrary,
135 non-rectangular <span>exclusion areas</span>.
136 </p>
138 <dfn>Float area</dfn>
140 <p>
141 The area used for excluding inline flow content around a float element. By default, the
142 float area is the float element's
143 <a href="http://www.w3.org/TR/CSS2/box.html#box-dimensions">margin box</a>.
144 This specification's
145 'shape-outside' property can be used to define arbitrary, non-rectangular float
146 areas.
147 </p>
149 <dfn>Exclusion element</dfn>
151 <p>An block-level element which is not a float and generates an <span>exclusion box</span>.
152 An element generates an exclusion box when its 'wrap-flow' property's computed value is not 'auto'.
153 </p>
156 <dfn>Wrapping context</dfn>
157 <div class="issue-marker" data-bug_id="15086" data-bug_status="NEW">
158 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15086">Issue-15086</a>
159 <div class="issue-details">
160 <p class="short-desc">should the wrapping context be generic and include floats?</p>
161 </div>
162 </div>
164 <p>
165 The <span>wrapping context</span> of a box is a collection of <span>exclusion areas</span>
166 contributed by its associated <span>exclusion boxes</span>. During layout,
167 a box wraps its inline flow content in the area that corresponds to the subtraction of
168 its <span>wrapping context</span> from its own <span>content area</span>.
169 </p>
171 <p>
172 A box inherits its
173 <a href="http://www.w3.org/TR/CSS2/visudet.html#containing-block-details">containing block's</a>
174 <span>wrapping context</span> unless it specifically
175 resets it using the 'wrap-through' property.
176 </p>
178 <dfn>Content area</dfn>
179 <p>
180 The area used for layout of the inline flow content of a box. By default the
181 area is equivalent to the <a href="http://www.w3.org/TR/CSS2/box.html#box-dimensions">content box</a>.
182 This specification's 'shape-inside' property can define arbitrary, non-rectangular content areas.
183 </p>
185 <div class="issue-marker" data-bug_id="15089" data-bug_status="NEW">
186 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15089">Issue-15089</a>
187 <div class="issue-details">
188 <p class="short-desc">shrink-to-fit circle / shape</p>
189 </div>
190 </div>
192 <dfn title="outside-inside">Outside and inside</dfn>
194 <p>
195 In this specification, 'outside' refers to DOM content that is not a descendant of an element
196 while 'inside' refers to the element's descendants.
197 </p>
199 <h2 id="exclusions">Exclusions</h2>
200 <p>
201 Exclusion elements define <span>exclusion areas</span> that contribute to their containing block's
202 <span>wrapping context</span>. As a consequence, exclusions impact the layout of their
203 containing block's descendants.
204 <p>
206 <p>
207 Elements layout their inline content in their <span>content area</span> and wrap around the
208 <span>exclusion areas</span> in their associated <span>wrapping context</span>. If the element is itself an exclusion, it
209 does not wrap around its own exclusion shape and the impact of other exclusions on other
210 exclusions is controlled by the 'z-index' property as explained in the
211 <a href="#exclusions-order">exclusions order</a> section.
212 </p>
213 The <a href="#shapes">shape properties</a> can be used to change the shape of
214 <span>exclusion areas</span>.
215 </p>
217 <h3 id="declaring-exclusions">Declaring exclusions</h3>
218 <p>
219 An element becomes an exclusion when its 'wrap-flow' property has a computed value other than
220 'auto'.
221 </p>
223 <h4 id="wrap-flow-property">The 'wrap-flow' property</h4>
224 <table class="propdef">
225 <tr>
226 <th>Name:</th>
227 <td><dfn title="'wrap-flow'">wrap-flow</dfn></td>
228 </tr>
229 <tr>
230 <th>Value:</th>
231 <td><var>auto</var> | <var>both</var> | <var>start</var> | <var>end</var> | <var>minimum</var> | <var>maximum</var> | <var>clear</var></td>
232 </tr>
233 <tr>
234 <th>Initial:</th>
235 <td>auto</td>
236 </tr>
237 <tr>
238 <th>Applies to:</th>
239 <td>block-level elements.</td>
240 </tr>
241 <tr>
242 <th>Inherited:</th>
243 <td>no</td>
244 </tr>
245 <tr>
246 <th>Percentages:</th>
247 <td>N/A</td>
248 </tr>
249 <tr>
250 <th>Media:</th>
251 <td>visual</td>
252 </tr>
253 <tr>
254 <th>Computed value:</th>
255 <td>as specified except for element's whose 'float' computed value is not
256 <code class="css">none</code>, in which case the computed value is 'auto'.</td>
257 </tr>
258 </table>
260 <p>The values of this property have the following meanings:</p>
261 <dl>
262 <dt><dfn title="'wrap-flow'!!'auto'">auto</dfn></dt>
263 <dd>
264 No exclusion is created. Inline flow content interacts with the element as usual.
265 In particular, if the element is a
266 <a href="http://www.w3.org/TR/CSS2/visuren.html#floats">float</a> (see [[CSS21]]), the
267 behavior is unchanged.
268 </dd>
269 <dt><dfn title="'wrap-flow'!!'both'">both</dfn></dt>
270 <dd>
271 Inline flow content can flow on all sides of the exclusion.
272 </dd>
273 <dt><dfn title="'wrap-flow'!!'start'">start</dfn></dt>
274 <dd>
275 Inline flow content can flow
276 around the start edge
277 of the <span>exclusion area</span>
278 but must leave the area
279 next to the end edge
280 of the exclusion empty.
281 </dd>
282 <dt><dfn title="'wrap-flow'!!'end'">end</dfn></dt>
283 <dd>
284 Inline flow content can flow
285 around the end edge
286 of the <span>exclusion area</span>
287 but must leave the area
288 next to the start edge
289 of the exclusion empty.
290 </dd>
291 <dt><dfn title="'wrap-flow'!!'minimum'">minimum</dfn></dt>
292 <dd>
293 Inline flow content can flow
294 around the edge of the exclusion
295 with the smallest available space
296 within the flow content's containing block,
297 and must leave the other edge
298 of the exclusion empty.
299 </dd>
300 <dt><dfn title="'wrap-flow'!!'maximum'">maximum</dfn></dt>
301 <dd>
302 Inline flow content can flow
303 around the edge of the exclusion
304 with the largest available space
305 within the flow content's containing block,
306 and must leave the other edge
307 of the exclusion empty.
308 </dd>
309 <dt><dfn title="'wrap-flow'!!'clear'">clear</dfn></dt>
310 <dd>
311 Inline flow content can only flow
312 before and after the exclusion
313 in the flow content's block direction
314 and must leave the areas
315 next to the start and end edges
316 of the exclusion empty.
317 </dd>
318 </dl>
320 <p>
321 If the property's computed value is 'auto', the element does not become an
322 <span>exclusion</span>.
323 </p>
324 <p>
325 Otherwise, a computed 'wrap-flow' property value of 'both', 'start', 'end', 'minimum',
326 'maximum' or 'clear' on an element makes that element an <span>exclusion element</a>.
327 It's <span>exclusion shape</span> is contributed to its containing block's
328 <span>wrapping context</span>, causing the containing block's descendants to wrap around
329 its <span>exclusion area</span>.
330 </p>
332 <div class="figure">
333 <img alt="LTR text wrapping on left edge, RTL text wrapping on right edge, and vertical text wrapping on top edge." src="images/exclusion-writing-modes.png" width="70%" />
334 <p class="caption">Exclusion with 'wrap-flow: start' interacting with various writing modes.</p>
335 </div>
337 <p>Determining the relevant edges of the exclusion depends on the <a href="http://www.w3.org/TR/css3-writing-modes/#text-flow">writing mode</a> [[!CSS3-WRITING-MODES]] of the content wrapping around the <span>exclusion area</span>.
339 <p>An <span>exclusion element</span> establishes a
340 new <a href="">block formatting context</a> (see [[!CSS21]]) for its content.</p>
342 <div class="figure">
343 <img alt="General illustration showing how exclusions combine" src="images/exclusions-illustration.png" width="70%" />
344 <p class="caption">Combining exclusions</p>
345 </div>
347 <p>
348 The above figure illustrates how exclusions are combined.
349 The outermost box represents an element's content box.
350 The A, B, C and D darker gray boxes represent exclusions
351 in the element's <span>wrapping context</span>.
352 A, B, C and D have their respective 'wrap-flow'
353 computed to 'both', 'start', 'end' and 'clear' respectively.
354 The lighter gray areas show the additional areas
355 that are excluded for inline layout
356 as a result of the 'wrap-flow'value.
357 For example, the area to the right of 'B'
358 cannot be used for inline layout
359 of left-to-right writing mode content
360 because the 'wrap-flow' for 'B' is 'start'.
361 </p>
362 <p>
363 The background 'blue' area shows what areas are available
364 for a left-to-right writing mode element's inline content layout.
365 All areas represented with a light or dark shade of gray
366 are not available for (left-to-right writing mode) inline content layout.
367 </p>
369 <div class="issue-marker wrapper">
370 <div class="issue-marker" data-bug_id="15084" data-bug_status="NEW">
371 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15084">Issue-15084</a>
372 <div class="issue-details">
373 <p class="short-desc">Fluidity of the layout with respect to different amounts of content</p>
374 </div>
375 </div>
376 </div>
378 <div class="example">
379 <p>
380 The 'wrap-flow' property values applied to exclusions as grid items.
381 </p>
382 <code class="html"><pre>
384 <div id="grid">
385 <div id="top-right" class="exclusion"></div>
386 <div id="bottom-left" class="exclusion"></div>
387 <div id="content">Lorem ipsum…</div>
388 </div>
390 <style type="text/css">
391 #grid {
392 width: 30em;
393 height: 30em;
394 display: grid;
395 grid-columns: 25% 25% 25% 25%;
396 grid-rows: 25% 25% 25% 25%;
398 #top-right {
399 grid-column: 3;
400 grid-row: 2;
401 }
403 #bottom-left {
404 grid-column: 2;
405 grid-row: 3;
406 }
408 .exclusion {
409 wrap-flow: <see below>
410 }
412 #content {
413 grid-row: 1;
414 grid-row-span: 4;
415 grid-column: 1;
416 grid-column-span: 4;
417 }
418 </style>
419 </pre></code>
420 <p>The following figures illustrate the visual rendering for different values
421 of the 'wrap-flow' property. The gray grid lines are marking the grid cells. and the
422 blue area is the exclusion box (positioned by the grid).</p>
423 <table class="example-table">
424 <tr>
425 <td><code class="html">.exclusion{ wrap-flow: auto; }</code></td>
426 <td><code class="html">.exclusion{ wrap-flow: both; }</code></td>
427 </tr>
428 <tr>
429 <td><img src="images/exclusion_wrap_side_auto.png" alt="Example rendering for wrap-side: auto" /></td>
430 <td><img src="images/exclusion_wrap_side_both.png" alt="Example rendering for wrap-side: both" /></td>
431 </tr>
432 <tr>
433 <td><code class="html">.exclusion{ wrap-flow: start; }</code></td>
434 <td><code class="html">.exclusion{ wrap-flow: end; }</code></td>
435 </tr>
436 <tr>
437 <td><img src="images/exclusion_wrap_side_left.png" alt="Example rendering for wrap-side: start" /></td>
438 <td><img src="images/exclusion_wrap_side_right.png" alt="Example rendering for wrap-side: end" /></td>
439 </tr>
440 <tr>
441 <td><code class="html">.exclusion{ wrap-flow: minimum; }</code></td>
442 <td><code class="html">.exclusion{ wrap-flow: maximum; }</code></td>
443 </tr>
444 <tr>
445 <td><img src="images/exclusion_wrap_side_minimum.png" alt="Example rendering for wrap-side: minimum" /></td>
446 <td><img src="images/exclusion_wrap_side_maximum.png" alt="Example rendering for wrap-side: maximum" /></td>
447 </tr>
448 <tr>
449 <td><code class="html">.exclusion{ wrap-flow: clear; }</code></td>
450 <td></td>
451 </tr>
452 <tr>
453 <td><img src="images/exclusion_wrap_side_clear.png" alt="Example rendering for wrap-side: clear" /></td>
454 <td></td>
455 </tr>
456 </table>
457 </div>
459 <!-- End section "wrap-flow Property" -->
460 <!-- End section "Declaring Exclusions" -->
462 <h3 id="scope-and-effect-of-exclusions">Scope and effect of exclusions</h3>
463 <p>
464 An <span>exclusion</span> affects
465 the inline flow content descended
466 from the exclusion's containing block
467 (defined in <a href="http://www.w3.org/TR/CSS2/visudet.html#containing-block-details">
468 CSS 2.1 10.1</a>)
469 and that of all descendant elements
470 of the same containing block.
471 All inline flow content
472 inside the containing block
473 of the exclusions is affected.
474 To stop the effect of exclusions
475 defined outside an element,
476 the 'wrap-through' property can be used
477 (see the <a href="#propagation-of-exclusions">propagation of exclusions</a>
478 section below).
479 </p>
481 <p>
482 As a reminder,
483 for exclusions with 'position:fixed',
484 the containing block is that
485 of the root element.
486 </p>
488 <!-- End section "Scope and Effect of Exclusions" -->
490 <h3 id="propagation-of-exclusions">Propagation of Exclusions</h3>
491 <p>
492 By default, an element inherits its parent <span>wrapping context</span>. In other words
493 it is subject to the exclusions defined <span title="outside-inside">outside</sapn> the element.
494 </p>
495 <p>Setting the 'wrap-through' property to 'none' prevents an element from inheriting its parent
496 <span>wrapping context</span>. In other words, exclusions defined 'outside' the element, have not effect
497 on the element's children layout.
498 </p>
499 <div class="note">
500 Exclusions defined by an element's descendants still contribute to their containing block's
501 <span>wrapping context</span>. If that containing block is a child of an element with 'wrap-through'
502 computes to none, or the element itself, then exclusion still have an effect on the children of that
503 containing block element.
504 </div>
506 <h4 id="wrap-through-property">The 'wrap-through' Property</h4>
508 <table class="propdef">
509 <tr>
510 <th>Name:</th>
511 <td><dfn title="'wrap-through'">wrap-through</dfn></td>
512 </tr>
513 <tr>
514 <th>Value:</th>
515 <td><var>wrap</var> | <var>none</var></td>
516 </tr>
517 <tr>
518 <th>Initial:</th>
519 <td>wrap</td>
520 </tr>
521 <tr>
522 <th>Applies to:</th>
523 <td>block-level elements</td>
524 </tr>
525 <tr>
526 <th>Inherited:</th>
527 <td>no</td>
528 </tr>
529 <tr>
530 <th>Percentages:</th>
531 <td>N/A</td>
532 </tr>
533 <tr>
534 <th>Media:</th>
535 <td>visual</td>
536 </tr>
537 <tr>
538 <th>Computed value:</th>
539 <td>as specified</td>
540 </tr>
541 </table>
543 <p>The values of this property have the following meanings:</p>
544 <dl>
545 <dt><dfn title="'wrap-through'!!'wrap'">wrap</dfn></dt>
546 <dd>
547 The element inherits its parent node's <span>wrapping context</span>. Its descendant
548 inline content wraps around exclusions defined <span title="outside-inside">outside</span>
549 the element.
550 </dd>
551 </dl>
552 <dl>
553 <dt><dfn title="'wrap-through'!!'none'">none</dfn></dt>
554 <dd>
555 The element does not inherit its parent node's <span>wrapping context</span>. Its
556 descendants are only subject to exclusion shapes defined <span title="outside-inside">inside</span>
557 the element.
558 </dd>
559 </dl>
560 <div class="example">
561 <p>
562 Using the 'wrap-through' property to control the effect of exclusions.
563 </p>
564 <pre><code class="html">
566 <style type="text/css">
567 #grid {
568 display: grid;
569 grid-columns: 25% 50% 25%;
570 grid-rows: 25% 25% 25% 25%;
571 }
573 #exclusion {
574 grid-row: 2;
575 grid-row-span: 2;
576 grid-column: 2;
577 wrap-flow: <see below>
578 }
580 #rowA, #rowB {
581 grid-row-span: 2;
582 grid-column: 1;
583 grid-column-span: 3;
584 }
586 #rowA {
587 grid-row: 1;
588 }
590 #rowB {
591 grid-row: 3;
592 }
593 </style>
595 <style type="text/css">
596 .exclusion {
597 wrap-flow: both;
598 position: absolute;
599 left: 20%;
600 top: 20%;
601 width: 50%;
602 height: 50%;
603 background-color: rgba(220, 230, 242, 0.5);
604 }
605 </style>
607 <div id="grid">
608 <div class=”exclusion”></div>
609 <div id="rowA" style=”wrap-through: wrap;”> Lorem ipsum dolor sit amet...</div>
610 <div id="rowB" style=”wrap-through: none;”> Lorem ipsum dolor sit amet...</div>
611 </div>
612 </code></pre>
614 <img class="singleImgExample" src="images/exclusion_wrap_through.png" alt="Example rendering of wrap-through: wrap | none" style="max-width:40%"/>
615 </div>
616 <!-- End section "wrap-through property" -->
618 <!-- removed as wrap-margin and wrap-padding changed to shape-margin and shape-padding
620 <h4 id="wrap-shorthand-property">The 'wrap' Shorthand Property</h4>
621 <table class="propdef">
622 <tr>
623 <th>Name:</th>
624 <td><dfn title="'wrap'">wrap</dfn></td>
625 </tr>
626 <tr>
627 <th>Value:</th>
628 <td><var><wrap-flow></var> || <var><wrap-margin></var> [ / <var><wrap-padding></var>]</td>
629 </tr>
630 <tr>
631 <th>Initial:</th>
632 <td>see individual properties</td>
633 </tr>
634 <tr>
635 <th>Applies to:</th>
636 <td>block-level elements</td>
637 </tr>
638 <tr>
639 <th>Inherited:</th>
640 <td>no</td>
641 </tr>
642 <tr>
643 <th>Percentages:</th>
644 <td>N/A</td>
645 </tr>
646 <tr>
647 <th>Media:</th>
648 <td>visual</td>
649 </tr>
650 <tr>
651 <th>Computed value:</th>
652 <td>see individual properties</td>
653 </tr>
654 </table>
655 <p>
656 The 'wrap' property is a shorthand property for setting the exclusions properties
657 at the same place in the style sheet.
658 </p>
659 -->
660 <!-- End section "wrap shorthand property" -->
661 <!-- End section "Propagation of Exclusions" -->
663 <h3 id="exclusions-order">Exclusions order</h3>
664 <p>
665 Exclusions follow the painting order (See [[!CSS21]] Appendix E). Exclusions are
666 applied in reverse to the document order in which they are defined. The last exclusion
667 appears on top of all other exclusion, thus it affects the inline flow content of
668 all other preceding exclusions or elements descendant of the same containing block.
669 The 'z-index' property can be used to change the ordering of
670 <a href="http://www.w3.org/TR/CSS2/visuren.html#choose-position">positioned</a> exclusion
671 boxes (see [[!CSS21]]). Statically positioned exclusions are not affected by the
672 'z-index' property and thus follow the painting order.
673 </p>
675 <div class="issue-marker" data-bug_id="16474" data-bug_status="NEW">
676 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=16474">Issue-16474</a>
677 <div class="issue-details">
678 <p class="short-desc">Improve Example 3 about exclusion order</p>
679 </div>
680 </div>
682 <div class="example">
683 <p>Ordering of exclusions.</p>
684 <pre><code class="html">
685 <style type="text/css">
686 .exclusion {
687 wrap-flow: both;
688 position: absolute;
689 width: 50%;
690 height: auto;
691 }
692 </style>
694 <div class=”exclusion” style=”top: 0px; left: 0px;”>
695 Lorem ipsum dolor sit amet...
696 </div>
697 <div id="orderedExclusion" class=”exclusion” style=”top: 25%; left: 25%;”>
698 Lorem ipsum dolor sit amet...
699 </div>
700 <div class=”exclusion” style=”top: 50%; left: 50%;”>
701 Lorem ipsum dolor sit amet...
702 </div>
703 </code></pre>
705 <table class="example-table">
706 <tr>
707 <td style="width:50%"><code class="html">#orderedExclusion{ z-index: auto; }</code></td>
708 <td style="width:50%"><code class="html">#orderedExclusion{ z-index: 1; }</code></td>
709 </tr>
710 <tr>
711 <td><img class="singleImgExample" src="images/exclusion_ordering.png" alt="Example rendering of default exclusion ordering." /></td>
712 <td><img class="singleImgExample" src="images/exclusion_ordering_z_order.png" alt="Example rendering of default exclusion ordering." /></td>
713 </tr>
714 </table>
716 </div>
717 <!-- End section "Order of Exclusions" -->
719 <div class="issue-marker wrapper">
720 <div class="issue-marker" data-bug_id="15183" data-bug_status="NEW">
721 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15183">Issue-15183</a>
722 <div class="issue-details">
723 <p class="short-desc">Is the CSS exclusions processing model incorrect?</p>
724 </div>
725 </div>
726 </div>
728 <div class="issue">
730 <p>The current draft provides a model for exclusions
731 without a collision-avoidance model.
732 The existing exclusion model in CSS uses floats,
733 which have both exclusion and collision-avoidance behavior.
734 Concerns have been raised that allowing exclusions
735 without collision avoidance could be harmful,
736 particularly with absolutely-positioned elements.
737 Three options should be considered:<p>
738 <ol>
739 <li>Allow exclusions in positioning schemes
740 with no collision avoidance.</li>
741 <li>Disallow exclusions in positioning schemes
742 with no collision avoidance.</li>
743 <li>Define collision-avoidance behavior
744 for positioning schemes without it,
745 and use this behavior by default with exclusions.</li>
746 <ol>
747 </div>
749 <h3 id="exclusions-processing-model">Processing model</h3>
751 <h4 id="exclusions-processing-model-description">Description</h4>
753 <p>Applying exclusions is a two-step process:</p>
755 <ul>
756 <li><strong>Step 1</strong>: resolve exclusion boxes belonging to each <span>wrapping context</span></li>
757 <li><strong>Step 2</strong>: resolve <span>wrapping context</span>s and lay out each containing block in turn:
758 <ul>
759 <li><strong>Step 2-A</strong>: resolve the position and size of exclusion boxes</li>
760 <li><strong>Step 2-B</strong>: lay out containing block, wrapping around <span>exclusion areas</span></li>
761 </ul>
762 </li>
763 </ul>
765 <h4 id="step-1-resolve-exclusion-boxes-belonging-to-each-wrapping-context">Step 1: resolve exclusion boxes belonging to each <span>wrapping context</span></h4>
767 <p>In this step, the user agent determines which <a href="http://www.w3.org/TR/CSS2/visudet.html#containing-block-details">containing block</a> each
768 <span>exclusion area</span> belongs to. This is a simple step, based on the
769 definition of containing blocks and elements with a computed value for 'wrap-flow'
770 that is not <code class="css">auto</code>.</p>
772 <h4 id="step-2-resolve-wrapping-contexts-layout-containing-blocks">Step 2: resolve wrapping contexts and lay out containing blocks</h4>
774 <p>In this step, starting from the
775 top of the <a href="http://www.w3.org/TR/CSS2/visuren.html#z-index">rendering tree</a> (see [[!CSS21]]),
776 the the agent processes each containing block in two sub-steps.</p>
778 <h4 id="step-2-A-resolve-exclusions-position-and-size">Step 2-A: resolve the position and size of exclusion boxes</h4>
780 <p>Resolving the position and size
781 of <span>exclusion boxes</span>
782 in the <span>wrapping context</span>
783 may or may not require a layout.
784 For example,
785 if an <span>exclusion box</span>
786 is absolutely positioned and sized,
787 a layout may not be needed
788 to resolve its position and size.
789 In other situations,
790 laying out the containing block's content is required.</p>
792 <p>When a layout is required,
793 it is carried out
794 without applying any <span>exclusion area</span>.
795 In other words,
796 the containing block is laid out
797 without a <span>wrapping context</span>. </p>
799 <p>Step 2-A yields a position and size
800 for all <span>exclusion boxes</span>
801 in the <span>wrapping context</span>.
802 Each exclusion box is processed in turn,
803 starting from the top-most,
804 and each <span>exclusion area</span>
805 is computed and contributed
806 to the <a href="http://www.w3.org/TR/CSS2/visudet.html#containing-block-details">containing block's</a>
807 <span>wrapping context</span>. </p>
809 <p>Scrolling is ignored in this step
810 when resolving the position and size
811 of 'position:fixed' <span>exclusion boxes</span>.</p>
813 <p>Once the <a href="http://www.w3.org/TR/CSS2/visudet.html#containing-block-details">containing block's</a>
814 <span>wrapping context</span> is computed,
815 all <span>exclusion boxes</span>
816 in that <span>wrapping context</span>
817 are removed from the normal flow.</p>
819 <h4 id="step-2-B-layout-containing-block-applying-wrapping">Step 2-B: lay out containing block applying wrapping</h4>
821 <p>Finally, the content
822 of the containing block is laid out,
823 with the inline content wrapping around
824 the <span>wrapping content</span>'s
825 <span>exclusion areas</span>
826 (which may be different
827 from the <span>exclusion box</span>
828 because of the 'shape-outside' property).</p>
830 <p>When the containing block itself is an <span>exclusion box</span>, then
831 rules on <a href="#exclusions-order">exclusions order</a> define which exclusions
832 affect the inline and descendant content of the box.</p>
834 <h4 id="exclusions-processing-model-example">Example</h4>
836 <p>This section illustrates the exclusions processing model with an example. It is meant
837 to be simple. Yet, it contains enough complexity to address the issues of
838 layout dependencies and re-layout.</p>
841 <p>The code snippet in the following example has two exclusions affecting
842 the document's inline content.</p>
844 <div class="example">
845 <pre class="html"><html>
846 <style>
847 #d1 {
848 position:relative;
849 height: auto;
850 color: #46A4E9;
851 border: 1px solid gray;
852 }
854 #e1 {
855 wrap-flow: both;
856 position: absolute;
857 left: 50%;
858 top: 50%;
859 width: 40%;
860 height: 40%;
861 border: 1px solid red;
862 margin-left: -20%;
863 margin-top: -20%;
864 }
866 #d2 {
867 position: static;
868 width: 100%;
869 height: auto;
870 color: #808080;
871 }
873 #e2 {
874 wrap-flow: both;
875 position: absolute;
876 right: 5ex;
877 top: 1em;
878 width: 12ex;
879 height: 10em;
880 border: 1px solid lime;
881 }
882 </style>
883 <body>
884 <div id="d1">
885 Lorem ipsusm ...
886 <p id="e1"></p>
887 </div>
888 <div id="d2">
889 Lorem ipsusm ...
890 <p id="e2" ></p>
891 </div>
892 </body>
893 </html></pre>
894 </div>
895 <p>The following figures illustrate:</p>
897 <ul>
898 <li>the document's DOM tree</li>
899 <li>the layout tree of generated block boxes</p>
900 </ul>
902 <div class="figure">
903 <img src="images/processing-model-example-dom.svg" width="200"
904 alt="DOM tree nodes"/>
905 <p class="caption">DOM tree</p>
906 </div>
908 <div class="figure">
909 <img src="images/processing-model-example-layout-tree.svg" width="350"
910 alt="Layout tree boxes"/>
911 <p class="caption">Layout tree of generated block boxes</p>
912 </div>
914 <h5>Step 1: resolve exclusion boxes belonging to each <span>wrapping context</span></h5>
916 <p>The figures illustrate how the boxes corresponding to the element sometimes
917 have a different containment hierarchy in the layout tree than in the DOM tree.
918 For example, the box generated by <code class="idl">e1</code> is positioned in
919 its containing block's box, which is the <code class="idl">d1-box</code>, because
920 <code class="idl">e1</code> is absolutely positioned and <code class="idl">d1</code>
921 is relatively positioned. However, while <code class="idl">e2</code> is also absolutely
922 positioned, its containing block is the initial containing block (ICB). See the
923 section 10.1 of the CSS 2.1 specification ([[!CSS21]]) for details.</p>
925 <p>As a result of the computation of containing blocks for the tree, the boxes belonging
926 to the <span>wrapping context</span>s of all the elements can be determined:</p>
928 <ul>
929 <li>The <span>wrapping context</span> for the html element contains the <code class="idl">e2</code> box: WC-1 (Wrapping Context 1)</li>
930 <li>The <span>wrapping context</span> for the body element inherits the html element's <span>wrapping context</span>: WC-1</li>
931 <li>The <span>wrapping context</span> for <code class="idl">d1</code> inherits the body element's
932 <span>wrapping context</span> and adds the <code class="idl">e1-box</code> to it. So the wrapping
933 context is made of both the <code class="idl">e1-box</code> and the
934 <code class="idl">e2-box</code>: WC-2</li>
935 <li>The <span>wrapping context</span> for <code class="idl">d2</code> inherits the body element's
936 <span>wrapping context</span>: WC-1</li>
937 </ul>
939 <h5>Step 2: resolve wrapping contexts and lay out containing blocks</h5>
941 <p>In this step, each containing block is processed in turn. For each containing block,
942 we (conceptually) go through two phases:</p>
943 <ol>
944 <li>resolve the <span>wrapping context</span>: resolve the position and size of its exclusions</li>
945 <li>lay out the containing block</li>
946 </ol>
948 <p>In our example, this breaks down to:</p>
949 <ol>
950 <li>resolve the position and size of the exclusions belonging to WC-1: RWC-1 (Resolved Wrapping Context 1).</li>
951 <li>lay out the initial containing block (i.e., lay out its content):
952 <ol>
953 <li>resolve the html element's <span>wrapping context</span>: RWC-1</li>
954 <li>lay out the html element:
955 <ol>
956 <li>resolve the body element's <span>wrapping context</span>: RWC-1</li>
957 <li>lay out the body element:
958 <ol>
959 <li>resolve the <code class="idl">d1</code> element's <span>wrapping context</span>: RWC-2</li>
960 <li>lay out the <code class="idl">d1</code> element</li>
961 <li>resolve the <code class="idl">d2</code> element's <span>wrapping context</span>: RWC-1</li>
962 <li>lay out the <code class="idl">d2</code> element</li>
963 </ol>
964 </li>
965 </ol>
966 </li>
967 </ol>
968 </li>
969 </ol>
971 <h6>Resolving RWC-1</h6>
973 <p>The top-most <span>wrapping context</span> in the layout tree contains the <code class="idl">e2</code>
974 exclusion. Its position and size needs to be resolved. In general, computing an
975 exclusion's position and size may or may not require laying out other content.
976 In our example, no content needs to be laid out to resolve the <code class="idl">e2</code>
977 exclusion's position because it is absolutely positioned and its size can be resolved
978 without layout either. At this point, RWC-1 is resolved and can be used when
979 laying inline content out.</p>
981 <h6>Resolving RWC-2</h6>
983 <p>The process is similar: the position of the
984 <code class="idl">e1</code> exclusion needs to be resolved. Again, resolving the exclusion's
985 position and size may require processing the containing block (d1 here).
986 It is the case here because the size and position of
987 <code class="idl">e1</code> depend on resolving the percentage lengths. The percentages are relative
988 to the size of
989 <code class="idl">d1</code>'s box. As a result, in order to resolve
990 a size for <code class="idl">d1</code>'s box, a first layout of <code class="idl">d1</code>
991 is done without any <span>wrapping context</span> (i.e., no exclusions applied). The layout yields a
992 position and size for <code class="idl">e1</code>'s box.
993 </p>
994 <p>At this point, RWC-2 is resolved because the position and size of both
995 e1 and e2 are resolved.</p>
997 <p class="note">The important aspect of the above processing example is that once an element's <span>wrapping context</span>
998 is resolved (by resolving its exclusions' position and size), the position and size of the
999 exclusions are not re-processed if the element's size changes between the layout that may be done
1000 without considering any <span>wrapping context</span> (as for RWC-2) and the layout done with the resolved <span>wrapping context</span>.
1001 This is what breaks the possible circular dependency between the resolution of <span>wrapping context</span>s
1002 and the layout of containing blocks.</p>
1004 <h3 id="floats-and-exclusions">Floats and exclusions</h3>
1006 <h4 id="floats-and-exclusions-similarities">Similarities</h4>
1008 <p>There are similarities between floats an exclusions in that inline content wraps around floats
1009 and also wraps around <span>exclusion areas</span>. However, there are very significant differences.</p>
1011 <h4 id="floats-and-exclusions-differences">Differences</h4>
1013 <ul>
1014 <li><strong>scope</strong>. While floats apply to content that follows in the
1015 document, exclusions apply to content in their containing block.</li>
1016 <li><strong>positioning</strong>. Floats are part of the inline flow and 'float' on the
1017 line box. Authors can control how the floats move on the line box, to the right or to the
1018 left. By contrast, exclusions can be positioned using any positioning scheme such
1019 as grid layout ([[CSS3-GRID-LAYOUT]]), flexible box ([[CSS3-FLEXBOX]]) or any other
1020 CSS positioning scheme.</li>
1021 <li><strong>separation of concerns</strong>. Making an element a float determines both
1022 its positioning scheme and its effect on inline content. Making an element an
1023 exclusion only determines its impact on inline content and does not impose constraints
1024 on its positioning method.</li>
1025 </ul>
1027 <h4 id="floats-and-exclusions-interoperability">Interoperability</h4>
1029 <h5 id="effect-of-floats-on-exclusions">Effect of floats on exclusions</h5>
1031 <p>Floats have an effect on the positioning of exclusions and the layout of their inline content. For
1032 example, if an exclusion is an inline-box which happens to be on the same line as a float,
1033 its' position, as computed in <a href="#step-2-A-resolve-exclusions-position-and-size">Step 2-A</a> will be impacted by the float, as
1034 is any other inline content.</p>
1036 <h5 id="effect-of-exclusions-on-floats">Effect of exclusions on floats</h5>
1038 <p>Exclusions have an effect on the positioning of floats as they have an effect on inline content.
1039 Therefore, in <a href="#step-2-B-layout-containing-block-applying-wrapping">Step 2-B</a>, floats will avoid <span>exclusion areas</span>.</p>
1041 <!-- End section "Exclusions" -->
1043 <h2 id="shapes">Shapes</h2>
1045 <div class="issue-marker wrapper">
1046 <div class="issue-marker" data-bug_id="15091" data-bug_status="NEW">
1047 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15091">Issue-15091</a><br />
1048 <div class="issue-details">
1049 <p class="short-desc">Simplify the syntax for shapes</p>
1050 </div>
1051 </div>
1053 <div class="issue-marker" data-bug_id="16716" data-bug_status="NEW">
1054 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=16716">Issue-16716</a>
1055 <div class="issue-details">
1056 <p class="short-desc">Handling visible content as a shape for Exclusions</p>
1057 </div>
1058 </div>
1059 </div>
1061 <p>
1062 Shapes define arbitrary geometric contours around which or into which inline flow
1063 content flows. There are two different types of shapes – 'outside' and 'inside'.
1064 The outside shape defines the <span>exclusion area</span> for an <span>exclusion element</span>
1065 or the <span>float area</span> for a float.
1066 The inside shape defines an element's <span>content shape</span> and the element's inline
1067 content will flow within that shape.
1068 </p>
1070 <p class="note">It is important to note that while outside shapes only apply to
1071 <span>exclusions</span> and floats, inside shapes apply to all block-level elements.</p>
1073 <h3 id="relation-to-box-model-and-float-behavior">Relation to the box model and float behavior</h3>
1075 <p>
1076 While the boundaries used for wrapping inline flow content outside and inside
1077 an element can be defined using shapes, the actual box model does not change. If
1078 the element has specified margins, borders or paddings they will be computed and
1079 rendered according to the [[!CSS3BOX]] module.
1080 </p>
1082 <p>
1083 However, floats are an exception. If a float has an outside shape, its positioning
1084 is resolved as
1085 <a href="http://www.w3.org/TR/CSS2/visuren.html#float-position">defined</a> in
1086 [[!CSS21]] but using the
1087 outside shape's bounding box is used in lieu of the float's margin box.
1088 </p>
1090 <div class="example">
1091 <p>CSS 'shape-outside' and CSS box model relation: the red box illustrates the exclusion element's
1092 content box, which is unmodified and subject to normal CSS positioning (here absolute positioning).</p>
1093 <pre><code class="html">
1094 <style type="text/css">
1095 .exclusion {
1096 wrap-flow: both;
1097 position: absolute;
1098 top: 25%;
1099 left: 25%;
1100 width: 50%;
1101 height: 50%;
1102 shape-outside: circle(50%, 50%, 50%);
1103 border: 1px solid red;
1104 }
1105 </style>
1107 <div style=”position: relative;”>
1108 <div class=”exclusion”></div>
1109 Lorem ipsum dolor sit amet...
1110 </div>
1111 </code></pre>
1112 <img class="singleImgExample" src="images/shapes_CSS2.1_MBP.png" alt="Example rendering of circle shape and box model." style="max-width:40%"/>
1113 </div>
1115 <div class="example">
1116 <p>In the following example the left and right floating <code class="html">div</code> elements
1117 specify a triangular shape using the 'shape-outside' property.</p>
1119 <pre><code class="html">
1120 <div style="text-align:center;">
1121 <div id="float-left"></div>
1122 <div id="float-right"></div>
1123 <div>
1124 Sometimes a web page's text content appears to be
1125 funneling your attention towards a spot on the page
1126 to drive you to follow a particular link. Sometimes
1127 you don't notice.
1128 </div>
1129 </div>
1131 <style type="text/css">
1132 #float-left {
1133 shape-outside: polygon(0,0 100%,100% 0,100%);
1134 float: left;
1135 width: 40%;
1136 height: 12ex;
1137 }
1139 #float-right {
1140 shape-outside: polygon(100%,0 100%,100% 0,100%);
1141 float: right;
1142 width: 40%;
1143 height: 12ex;
1144 }
1145 </style>
1146 </div></code></pre>
1148 <img class="singleImgExample" src="images/float-shape-outside.png" alt="Using the shape-outside property with a float"/>
1149 </div>
1150 <h3 id="basic-shapes-from-svg-syntax">Basic Shapes</h3>
1151 <p>
1152 Shapes can be specified using
1153 syntax similar to SVG's <a href="http://www.w3.org/TR/SVG/shapes.html">basic shapes</a>.
1154 The definitions use
1155 <code><a href="http://www.w3.org/TR/css3-values/#lengths"><length></a></code> type
1156 and the <code><a href=""><percentage></a></code> types (see [[!CSS3VAL]]).
1157 Percentages are resolved
1158 from the computed value of the
1159 <a href="http://www.w3.org/TR/css3-ui/#box-sizing">'box-sizing'</a>
1160 property [[!CSS3UI]]
1161 on the element to which the property applies.
1162 For the radius <code>r</code> of the <code>circle</code> shape,
1163 a percentage value is resolved as
1164 <a href="http://www.w3.org/TR/SVG/coords.html#Units">specified</a>
1165 in the SVG recommendation (see [[!SVG11]]).
1166 Path styling like stroking is not considered part of the specified shape.
1167 </p>
1170 <h4 id="supported-basic-shapes">Supported Shapes</h4>
1171 The following basic shapes are supported.
1172 <dl>
1173 <dt><dfn id="rectangle">rectangle</dfn>([<length>|<percentage>]{4} [ curve [<length>|<percentage>]{1,2} ]? )</dt>
1174 <dd>
1175 <ul>
1176 <li>
1177 The four values represent
1178 <strong>x, y, width</strong> and
1179 <strong>height</strong>.
1180 They define the bounding box
1181 of the rectangle.
1182 Negative values for width and height are invalid.
1183 </li>
1184 <li>
1185 The two 'curve' values represent
1186 <strong> rx</strong> and <strong>ry</strong>.
1187 For rounded rectangles they define
1188 the x-axis radius and y-axis radius
1189 of the ellipse used to round off
1190 the corners of the rectangle.
1191 Negative values for rx and ry are invalid.
1192 </li>
1193 </ul>
1194 </dd>
1195 <dt><dfn id="circle">circle</dfn>([<length>|<percentage>]{3})</dt>
1196 <dd>
1197 <ul>
1198 <li>
1199 The three values values represent
1200 <strong>cx</strong>,
1201 <strong>cy</strong>,
1202 and <strong>r</strong>.
1203 They define the x-axis and y-axis coordinates
1204 of the center of the circle
1205 and the radius of the circle.
1206 A negative value for r is invalid.
1207 </li>
1208 </ul>
1209 </dd>
1210 <dt><dfn id="ellipse">ellipse</dfn>([<length>|<percentage>]{4})</dt>
1211 <dd>
1212 <ul>
1213 <li>
1214 The four values represent
1215 <strong>cx</strong>,
1216 <strong>cy</strong>,
1217 <strong>rx</strong>, and
1218 <strong>ry</strong>.
1219 They define the x-axis and y-axis coordinates
1220 of the center of the ellipse
1221 and the x-axis and y-axis radius
1222 of the ellipse.
1223 Negative values for rx and ry are invalid.
1224 </li>
1225 </ul>
1226 </dd>
1227 <dt><dfn id="polygon">polygon</dfn>([<fill-rule>,]? [<length>|<percentage>]{2}#)</dt>
1228 <dd>
1229 <ul>
1230 <li><strong>fill-rule</strong> - The filling rule used to determine the interior of the
1231 polygon. See <a href="http://www.w3.org/TR/SVG/painting.html#FillRuleProperty">fill-rule</a> property in SVG for details. Possible values are nonzero
1232 or evenodd. Default value when omitted is nonzero.</li>
1233 <li>
1234 The two length values represent <strong>xi</strong> and <strong>yi</strong> -
1235 the <strong>x</strong> and <strong>y</strong> axis coordinates of the i-th vertex of the polygon.
1236 </li>
1237 </ul>
1238 <p>The UA will close a polygon
1239 by connecting the last vertex
1240 with the first vertex of the list.</p>
1241 <br/>
1242 </dd>
1243 </dl>
1245 <h4 id='referencing-svg-shapes'>Referencing SVG shapes</h4>
1247 <p>An SVG shape can be referenced using the <code>url()</code> syntax. The shape can be
1248 any of the <a href="http://www.w3.org/TR/SVG/shapes.html">SVG basic shapes</a> or a
1249 <a href="http://www.w3.org/TR/SVG/paths.html">path element</a>.</p>
1251 <div class="example">
1252 <div style="float:right">
1253 <img alt="results of referencing SVG shapes" src="images/svg-shape-reference.png">
1254 </div>
1255 <code class="html"><pre>
1256 <style>
1257 div {
1258 height: 400px;
1259 width: 400px;
1260 }
1261 .in-a-circle {
1262 shape-inside: url(#circle_shape);
1263 }
1265 .in-a-path {
1266 shape-inside: url(#path-shape);
1267 }
1269 </style>
1271 <svg ...>
1272 <circle id="circle_shape" cx="50%" cy="50%" r="50%" />
1273 <path id="path-shape" d="M 100 100 L 300 100 L 200 300 z" />
1274 </svg>
1276 <div class="in-a-circle">...</div>
1277 <div class="in-a-path">...</div>
1278 </pre></code>
1279 </div>
1280 <p>
1281 When using the SVG syntax
1282 or referencing SVG elements
1283 to define shapes,
1284 the relevant box is determined
1285 by the computed value of the
1286 <a href="http://www.w3.org/TR/css3-ui/#box-sizing">'box-sizing'</a>
1287 property.
1288 All the lengths expressed in percentages
1289 are resolved from the relevant box.
1290 The coordinate system for the shape
1291 has its origin on the top-left corner of the
1292 relevant box with the x-axis
1293 running to the right
1294 and the y-axis running downwards.
1295 If the SVG element uses unitless coordinate values,
1296 they are equivalent to using
1297 'px' units.
1298 If the relevant box of the element
1299 is dependent on auto sizing
1300 (i.e., the element's 'width' or 'height' property is 'auto'),
1301 then the percentage values
1302 resolve to 0.
1303 </p>
1305 <h4 id='basic-shape-interpolation'>Interpolation of Basic Shapes</h4>
1307 <p>For interpolating between
1308 one basic shape and a second,
1309 the rules described below are applied.
1310 </p>
1311 <ul>
1312 <li>If both basic shapes are of the same type and not of type polygon:
1313 <ul><li>Interpolate between each value.</li></ul>
1314 </li>
1315 <li>If one basic shape is of type rectangle and the second of type circle or ellipse:
1316 <ul><li>Replace the circle/ellipse with a temporary rectangle of equal dimension.</li>
1317 <li>Set the values for rx and ry on the temporary rectangle to ‘50%’.</li>
1318 <li>Interpolate between the two rectangles as above.</li></ul>
1319 </li>
1320 <li>If both basic shapes are of type polygon and if both polygons have the same number of vertices:
1321 <ul><li>Interpolate between each value.</li></ul>
1322 </li>
1323 <li>In all other cases:
1324 <ul><li>No interpolation is specified.</li></ul></li>
1325 </ul>
1327 <!-- End section "Shapes from SVG Syntax -->
1329 <h3 id="shapes-from-image">Shapes from Image</h3>
1331 <div class="issue-marker wrapper">
1332 <div class="issue-marker" data-bug_id="15093" data-bug_status="NEW">
1333 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15093">Issue-15093</a><br />
1334 <div class="issue-details">
1335 <p class="short-desc">Do we need to provide properties to repeat exclusion images as for the background-image property?</p>
1336 </div>
1337 </div>
1338 <div class="issue-marker" data-bug_id="15090" data-bug_status="NEW">
1339 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15090">Issue-15090</a>
1340 <div class="issue-details">
1341 <p class="short-desc">Use the contour keyword in shape-outside property?</p>
1342 </div>
1343 </div>
1345 <div class="issue-marker" data-bug_id="15092" data-bug_status="NEW">
1346 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15092">Issue-15092</a>
1347 <div class="issue-details">
1348 <p class="short-desc">Specify what happens with animated images</p>
1349 </div>
1350 </div>
1352 <div class="issue-marker" data-bug_id="16112" data-bug_status="NEW">
1353 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=16112">Issue-16112</a>
1354 <div class="issue-details">
1355 <p class="short-desc">Address security concern with automatic shape extractions for images</p>
1356 </div>
1357 </div>
1358 </div>
1360 <p>
1361 Another way of defining shapes is by specifying a source image whose alpha channel
1362 is used to compute the inside or outside shape. The shape is computed to be the
1363 path that encloses the area where the opacity of the specified image is greater
1364 than the 'shape-image-threshold' value. If the 'shape-image-threshold' is not specified,
1365 the initial value to be considered is 0.5.
1366 </p>
1368 <p class="note">
1369 Note, images can define cavities and inline flow content should wrap inside
1370 them. In order to avoid that, another exclusion element can be overlaid.
1371 </p>
1373 <p>For animated raster image formats (such as <a href="http://www.w3.org/Graphics/GIF/spec-gif89a.txt">GIF</a>), the first frame of the animation
1374 sequence is used. For <a href="http://www.w3.org/TR/2002/WD-SVG2Reqs-20020422/">SVG</a> images
1375 ([[SVG11]]), the image is rendered without animations applied.</p>
1377 <div class="example">
1378 <p>An image is floating to the left of a paragraph. The image shows the 3D version of the
1379 CSS logo over a transparent background. The logo has a shadow using an alpha-channel.</p>
1380 <p>The image defines its <span>float area</span> through the 'shape-outside' property and
1381 specifies a value of 35 pixels for the 'shape-margin' property.</p>
1382 <pre><code class="html">
1383 <p>
1384 <img id="CSSlogo" src="CSS-logo1s.png"/>
1385 blah blah blah blah...
1386 </p>
1388 <style>
1389 #CSSlogo {
1390 float: left;
1391 shape-outside: url("CSS-logo1s.png");
1392 shape-image-threshold: 0.1;
1393 shape-margin: 35px;
1394 }
1395 </style></code></pre>
1397 <p>The image needs two references to the image because this example uses the same image</p>
1398 <ol>
1399 <li>to render it</li>
1400 <li>as a shape defining the <span>float area</span> of the image</li>
1401 </ol>
1402 <p>It is perfectly possible to display an image and use a different image for its
1403 float area.</p>
1405 <p>In the figure below, the alpha-channel threshold is represented by the dotted line around
1406 the CSS logo and the 35px shape-margin is visible between that line and the edges of
1407 each individual line of the paragraph.</p>
1408 <p>It's then possible to affect where the lines of the paragraph start in three ways:</p>
1409 <ol>
1410 <li>Changing the value of the 'shape-margin' property</li>
1411 <li>Changing the value of the 'shape-image-threshold' property</li>
1412 <li>Modifying the alpha channel in the image</li>
1413 </ol>
1414 <div class='figure'>
1415 <img alt="A float shape around an image using its alpha-channel with a 35 pixels shape-margin" src="images/shape-outside-image.png" width="70%"/>
1416 <p class="caption">A float shape around an image using its alpha-channel with a 35 pixels shape-margin</p>
1417 </div>
1418 </div>
1419 <!-- End section "Shapes from image" -->
1421 <h3 id="declaring-shapes">Declaring Shapes</h3>
1422 <p>
1423 Shapes are declared with
1424 the 'shape-outside'
1425 or 'shape-inside' properties,
1426 with possible modifications
1427 from the 'shape-margin'
1428 and 'shape-padding' properties.
1429 The shape defined by
1430 the 'shape-outside'
1431 and 'shape-margin' properties
1432 changes the geometry
1433 of an <span>exclusion element</span>'s
1434 <span>exclusion area</span>
1435 or a float element's
1436 <span>float area</span>.
1437 If the element is not
1438 an <span>exclusion element</span>
1439 (see the 'wrap-flow' property)
1440 or a float,
1441 then the 'shape-outside' property
1442 has no effect.
1443 </p>
1444 <p>
1445 The shape defined by the 'shape-inside' and 'shape-padding' properties defines an element's <span>content area</span> and
1446 the element's inline flow content wraps into that shape. The 'shape-inside' property
1447 applies to all block-level elements.
1448 </p>
1450 <h4 id="shape-outside-property">The 'shape-outside' Property</h4>
1452 <table class="propdef">
1453 <tr>
1454 <th>Name:</th>
1455 <td><dfn title="'shape-outside'">shape-outside</dfn></td>
1456 </tr>
1457 <tr>
1458 <th>Value:</th>
1459 <td><var>auto</var> | <var><shape></var> | <var><uri></var></td>
1460 </tr>
1461 <tr>
1462 <th>Initial:</th>
1463 <td>auto</td>
1464 </tr>
1465 <tr>
1466 <th>Applies to:</th>
1467 <td>exclusion elements and floats</td>
1468 </tr>
1469 <tr>
1470 <th>Inherited:</th>
1471 <td>no</td>
1472 </tr>
1473 <tr>
1474 <th>Percentages:</th>
1475 <td>N/A</td>
1476 </tr>
1477 <tr>
1478 <th>Media:</th>
1479 <td>visual</td>
1480 </tr>
1481 <tr>
1482 <th>Computed value:</th>
1483 <td>computed lengths for <shape>, the absolute URI for <uri>, otherwise as specified</td>
1484 </tr>
1485 </table>
1487 <p>The values of this property have the following meanings:</p>
1488 <dl>
1489 <dt><dfn title="'shape-outside'!!'auto'">auto</dfn></dt>
1490 <dd>The shape is computed
1491 based on the border box of the element for exclusions,
1492 or computed based on the margin box for floats.</dd>
1493 </dl>
1494 <dl>
1495 <dt><dfn title="'shape-outside'!!'<shape>'"><shape></dfn></dt>
1496 <dd>
1497 The shape is computed based on the values of one of 'rectangle', 'circle', 'ellipse'
1498 or 'polygon'.
1499 </dd>
1500 </dl>
1501 <dl>
1502 <dt><dfn title="'shape-outside'!!'<uri>'"><uri></dfn></dt>
1503 <dd>
1504 If the <uri> references an SVG shape element, that element defines the shape.
1505 Otherwise, if the <uri> references an image, the shape is extracted and computed
1506 based on the alpha channel of the specified image.
1508 If the <uri> does not reference an SVG shape element or an image, the
1509 effect is as if the value 'auto' had been specified.
1510 </dd>
1511 </dl>
1513 <div class='figure'>
1514 <img alt="arbitrary shapes for exclusions. Illustrates how content flows around shapes" src="images/shapes-exclusions.png" width="70%"/>
1515 <p class="caption">Arbitrary shapes for exclusions</p>
1516 </div>
1518 <div>
1519 <p>The above figure shows how
1520 'shape-outside' shapes
1521 impact the <span>exclusion areas</span>.
1522 The red box represents an element's content box
1523 and 'A', 'B', 'C' and 'C' represent exclusions
1524 with a complex shape
1525 and their 'wrap-flow' property
1526 computes to 'both', 'start', 'end' and 'clear',
1527 respectively.</p>
1529 <p>As illustrated in the picture,
1530 when an exclusion allows wrapping
1531 on all sides,
1532 text can flow inside 'holes'
1533 in the exclusion
1534 (as for exclusion 'A').
1535 Otherwise, the exclusion clears
1536 the area on the side(s)
1537 defined by 'wrap-flow',
1538 as illustrated
1539 for 'B', 'C' and 'D' above.</p>
1540 </div>
1541 <!-- End section "The shape-outside Property" -->
1543 <h4 id="shape-inside-property">The 'shape-inside' Property</h4>
1544 <p>
1545 The 'shape-inside' modifies the shape of the inner inline flow content from rectangular
1546 content box to an arbitrary geometry.
1547 </p>
1549 <table class="propdef">
1550 <tr>
1551 <th>Name:</th>
1552 <td><dfn title="'shape-inside'">shape-inside</dfn></td>
1553 </tr>
1554 <tr>
1555 <th>Value:</th>
1556 <td><var>outside-shape</var> | <var>auto</var> | <var><shape></var> | <var><uri></var></td>
1557 </tr>
1558 <tr>
1559 <th>Initial:</th>
1560 <td>outside-shape</td>
1561 </tr>
1562 <tr>
1563 <th>Applies to:</th>
1564 <td>block-level elements</td>
1565 </tr>
1566 <tr>
1567 <th>Inherited:</th>
1568 <td>no</td>
1569 </tr>
1570 <tr>
1571 <th>Percentages:</th>
1572 <td>N/A</td>
1573 </tr>
1574 <tr>
1575 <th>Media:</th>
1576 <td>visual</td>
1577 </tr>
1578 <tr>
1579 <th>Computed value:</th>
1580 <td>computed lengths for <shape>, the absolute URI for <uri>, otherwise as specified</td>
1581 </tr>
1582 </table>
1584 <div class="issue-marker wrapper">
1585 <div class="issue-marker" data-bug_id="16448" data-bug_status="ASSIGNED">
1586 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=16448">Issue-16448</a>
1587 <div class="issue-details">
1588 <p class="short-desc">Should we revisit the decision to not allow SVG path syntax in the shape-inside, shape-outside properties</p>
1589 </div>
1590 </div>
1591 </div>
1593 <p>The values of this property have the following meanings:</p>
1594 <dl>
1595 <dt><dfn title="'shape-inside'!!'outside-shape'">outside-shape</dfn></dt>
1596 <dd>
1597 The shape is computed
1598 based on the computed value
1599 of the 'shape-outside' property.
1600 E.g., when shape-outside
1601 computes to 'auto',
1602 use the meaning of 'auto' below
1603 to compute the shape.
1604 </dd>
1605 </dl>
1606 <dl>
1607 <dt><dfn title="'shape-inside'!!'auto'">auto</dfn></dt>
1608 <dd>
1609 The shape is computed based on the content box of the element.
1610 </dd>
1611 </dl>
1612 <dl>
1613 <dt><dfn title="'shape-inside'!!'<shape>'"><shape></dfn></dt>
1614 <dd>
1615 The shape is computed based on the values of one of 'rectangle', 'circle', 'ellipse'
1616 or 'polygon'.
1617 </dd>
1618 </dl>
1619 <dl>
1620 <dt><dfn title="'shape-inside'!!'<uri>'"><uri></dfn></dt>
1621 <dd>
1622 If the <uri> references an SVG shape element, that element defines the shape.
1623 Otherwise, if the <uri> references an image, the shape is extracted and computed
1624 based on the alpha channel of the specified image.
1626 If the <uri> does not reference an SVG shape element or an image, the
1627 effect is as if the value 'auto' had been specified.
1628 </dd>
1629 </dl>
1631 <p>The 'shape-inside' property applies to floats.</p>
1633 <p>The 'shape-inside' property may not apply on some elements such as elements with a
1634 computed 'display' value of 'table'.</p>
1636 <div class='figure'>
1637 <img alt="Content flowing with and without a shape-inside" src="images/shape-inside-content.png"/>
1638 <p class="caption">Effect of shape-inside on inline content.</p>
1639 </div>
1641 <p>Overflow content can overlap
1642 the after edge of a shape,
1643 and overflow content can be displayed
1644 below the content area defined by shape.
1645 When content overflows in the block direction,
1646 the last line in the content area determines its width(s)
1647 by finding the minimum shape width(s)
1648 in the remaining area
1649 between the line's before edge
1650 and the shape's after edge.
1651 This can result
1652 in the line intersecting the shape's after edge,
1653 or a zero-width line
1654 if (for instance) the shape's after edge
1655 is a continuous curve.
1656 In degenerate cases,
1657 there may be no content
1658 that fits inside the content area
1659 defined by the shape.
1660 Further overflow is laid out
1661 below the after edge
1662 of the shape's bounding box
1663 as if 'shape-inside' computes to 'auto'.</p>
1665 <div class='figure'>
1666 <img alt="Overflow interacting with rounded rect" style="display:inline-block;vertical-align:top" src="images/rounded-rect-overflow.png"/>
1667 <img alt="Overflow interacting with ellipse" style="display:inline-block;vertical-align:top" src="images/ellipse-overflow.png"/>
1668 <p class="caption">Overflow interacting with the after edge of shapes defined by 'shape-inside' and 'shape-padding'.</p>
1669 </div>
1671 <!-- End section "The shape-inside property" -->
1672 <h4 id="shape-image-threshold-property">The 'shape-image-threshold' Property</h4>
1675 <p>
1676 The 'shape-image-threshold' defines the alpha channel threshold used to extract
1677 the shape using an image. A value of 0.5 means that all the pixels that are more
1678 than 50% transparent define the path of the exclusion shape. The 'shape-image-threshold'
1679 applies to both 'shape-outside' and 'shape-inside'.
1680 </p>
1681 <p class="note">
1682 The specified value of 'shape-image-threshold' is applied to both images used for
1683 'shape-outside' and 'shape-inside'.
1684 </p>
1686 <table class="propdef">
1687 <tr>
1688 <th>Name:</th>
1689 <td><dfn title="'shape-image-threshold'">shape-image-threshold</dfn></td>
1690 </tr>
1691 <tr>
1692 <th>Value:</th>
1693 <td><var><alphavalue></var></td>
1694 </tr>
1695 <tr>
1696 <th>Initial:</th>
1697 <td>0.5</td>
1698 </tr>
1699 <tr>
1700 <th>Applies to:</th>
1701 <td>block-level elements</td>
1702 </tr>
1703 <tr>
1704 <th>Inherited:</th>
1705 <td>no</td>
1706 </tr>
1707 <tr>
1708 <th>Percentages:</th>
1709 <td>alpha channel of the image specified by <uri></td>
1710 </tr>
1711 <tr>
1712 <th>Media:</th>
1713 <td>visual</td>
1714 </tr>
1715 <tr>
1716 <th>Computed value:</th>
1717 <td>The same as the specified value after clipping the <alphavalue> to the range [0.0,1.0].</td>
1718 </tr>
1719 </table>
1720 <p>The values of this property have the following meanings:</p>
1721 <dl>
1722 <dt><dfn title="'shape-image-threshold'!!'<alphavalue>'"><alphavalue></dfn></dt>
1723 <dd>
1724 A <number> value used to set the threshold used for extracting a shape from
1725 an image. Any values outside the range 0.0 (fully transparent) to 1.0 (fully opaque)
1726 will be clamped to this range.
1727 </dd>
1728 </dl>
1729 <!-- End section "The shape-image-threshold property" -->
1730 <!--
1731 <h4 id="shape-shorthand-property">The 'shape' Shorthand Property</h4>
1733 <table class="propdef">
1734 <tr>
1735 <th>Name:</th>
1736 <td><dfn title="'shape'">shape</dfn></td>
1737 </tr>
1738 <tr>
1739 <th>Value:</th>
1740 <td><var><shape-outside></var> [ / <var><shape-inside></var> ] || <var><shape-image-threshold></var></td>
1741 </tr>
1742 <tr>
1743 <th>Initial:</th>
1744 <td>see individual properties</td>
1745 </tr>
1746 <tr>
1747 <th>Applies to:</th>
1748 <td>block-level elements</td>
1749 </tr>
1750 <tr>
1751 <th>Inherited:</th>
1752 <td>no</td>
1753 </tr>
1754 <tr>
1755 <th>Percentages:</th>
1756 <td>N/A</td>
1757 </tr>
1758 <tr>
1759 <th>Media:</th>
1760 <td>visual</td>
1761 </tr>
1762 <tr>
1763 <th>Computed value:</th>
1764 <td>see individual properties</td>
1765 </tr>
1766 </table>
1767 <p>
1768 The 'shape' property is a shorthand property for setting the individual shape properties
1769 at the same place in a style sheet.
1770 </p>
1772 <div class="example">
1773 <p>Style declaration using the 'shape' shorthand property.</p>
1774 <pre><code class="html">
1775 <style type="text/css">
1776 .shape {
1777 shape: rectangle(50px, 50px, 200px, 100px) / url("shape_image.png") 0.7;
1778 }
1779 </style>
1780 </code></pre>
1781 </div>
1782 <p class="issue">The example above must be finished.</p>
1784 -->
1785 <!-- End section "Shape Shorthand property -->
1786 <!-- End section "Declaring Shapes" -->
1788 <h4 id="shape-margin-property">The 'shape-margin' property</h4>
1789 <p>
1790 The 'shape-margin' property adds a margin to a shape-outside.
1791 This defines a new shape where every point
1792 is the specified distance from the shape-outside.
1793 This property takes on positive values only.
1794 </p>
1795 <table class="propdef">
1796 <tr>
1797 <th>Name:</th>
1798 <td><dfn title="'shape-margin'">shape-margin</dfn></td>
1799 </tr>
1800 <tr>
1801 <th>Value:</th>
1802 <td><var><length></var></td>
1803 </tr>
1804 <tr>
1805 <th>Initial:</th>
1806 <td>0</td>
1807 </tr>
1808 <tr>
1809 <th>Applies to:</th>
1810 <td>exclusion elements and floats</td>
1811 </tr>
1812 <tr>
1813 <th>Inherited:</th>
1814 <td>no</td>
1815 </tr>
1816 <tr>
1817 <th>Percentages:</th>
1818 <td>N/A</td>
1819 </tr>
1820 <tr>
1821 <th>Media:</th>
1822 <td>visual</td>
1823 </tr>
1824 <tr>
1825 <th>Computed value:</th>
1826 <td>the absolute length</td>
1827 </tr>
1828 </table>
1830 <div class="example">
1831 <p>A 'shape-margin' creating an offset
1832 from a circlular shape-outside.
1833 The blue rectangles represent
1834 inline content affected
1835 by the shape created
1836 by the margin.</p>
1837 <img src="images/wrap-margin.png"
1838 alt="Example of a shape-margin offset"/>
1839 </div>
1841 <!-- End secion "shape-margin property" -->
1843 <h4 id="shape-padding-property">The 'shape-padding' Property</h4>
1844 <p>
1845 The 'shape-padding' property adds padding to a shape-inside.
1846 This defines a new shape where every point
1847 is the specified distance from the shape-inside.
1848 This property takes on positive values only.
1849 </p>
1850 <table class="propdef">
1851 <tr>
1852 <th>Name:</th>
1853 <td><dfn title="'shape-padding'">shape-padding</dfn></td>
1854 </tr>
1855 <tr>
1856 <th>Value:</th>
1857 <td><var><length></var></td>
1858 </tr>
1859 <tr>
1860 <th>Initial:</th>
1861 <td>0</td>
1862 </tr>
1863 <tr>
1864 <th>Applies to:</th>
1865 <td>block-level elements</td>
1866 </tr>
1867 <tr>
1868 <th>Inherited:</th>
1869 <td>no</td>
1870 </tr>
1871 <tr>
1872 <th>Percentages:</th>
1873 <td>N/A</td>
1874 </tr>
1875 <tr>
1876 <th>Media:</th>
1877 <td>visual</td>
1878 </tr>
1879 <tr>
1880 <th>Computed value:</th>
1881 <td>the absolute length</td>
1882 </tr>
1883 </table>
1885 <div class="example">
1886 <p>A 'shape-padding' creating an offset
1887 from a circlular shape-inside.
1888 The light blue rectangles represent
1889 inline content affected
1890 by the shape created
1891 by the padding.</p>
1892 <img src="images/shape-padding.png"
1893 alt="Example of a shape-padding offset"/>
1894 </div>
1895 <!-- End section "shape-padding property" -->
1897 <div class="note">Note that the 'shape-padding' property only affects layout of content inside
1898 the element it applies to while the 'shape-margin' property only affects layout of content
1899 outside the element.</div>
1901 <!-- End section "Shapes" -->
1902 <h2 id="conformance">Conformance</h2>
1903 <h3 id="conventions">Document Conventions</h3>
1904 <p>
1905 Conformance requirements are expressed with a combination of descriptive assertions
1906 and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”,
1907 “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the
1908 normative parts of this document are to be interpreted as described in RFC 2119.
1909 However, for readability, these words do not appear in all uppercase letters in
1910 this specification.
1911 </p>
1912 <p>
1913 All of the text of this specification is normative except sections explicitly marked
1914 as non-normative, examples, and notes. [[!RFC2119]]
1915 </p>
1916 <p>
1917 Examples in this specification are introduced with the words “for example” or are
1918 set apart from the normative text with <code>class="example"</code>, like this:
1919 </p>
1920 <div class="example">
1921 <p>This is an example of an informative example.</p>
1922 </div>
1923 <p>
1924 Informative notes begin with the word “Note” and are set apart from the normative
1925 text with <code>class="note"</code>, like this:
1926 </p>
1927 <p class="note">Note, this is an informative note.</p>
1928 <h3 id="conformance-classes">Conformance Classes</h3>
1929 <p>Conformance to CSS Exclusions and Shapes is defined for three conformance classes:</p>
1930 <dl>
1931 <dt><dfn title="style sheet!!as conformance class">style sheet</dfn></dt>
1932 <dd>
1933 A <a href="http://www.w3.org/TR/CSS21/conform.html#style-sheet">CSS style sheet</a>.</dd>
1934 <dt><dfn>renderer</dfn></dt>
1935 <dd>
1936 A <a href="http://www.w3.org/TR/CSS21/conform.html#user-agent">UA</a> that interprets
1937 the semantics of a style sheet and renders documents that use them.</dd>
1938 <dt><dfn id="authoring-tool">authoring tool</dfn></dt>
1939 <dd>
1940 A <a href="http://www.w3.org/TR/CSS21/conform.html#user-agent">UA</a> that writes
1941 a style sheet.</dd>
1942 </dl>
1943 <p>
1944 A style sheet is conformant to CSS Exclusions and Shapes if all of its declarations
1945 that use properties defined in this module have values that are valid according
1946 to the generic CSS grammar and the individual grammars of each property as given
1947 in this module.
1948 </p>
1949 <p>
1950 A renderer is conformant to CSS Exclusions and Shapes if, in addition to interpreting
1951 the style sheet as defined by the appropriate specifications, it supports all the
1952 features defined by CSS Exclusions and Shapes by parsing them correctly and rendering
1953 the document accordingly. However, the inability of a UA to correctly render a document
1954 due to limitations of the device does not make the UA non-conformant. (For example,
1955 a UA is not required to render color on a monochrome monitor.)
1956 </p>
1957 <p>
1958 An authoring tool is conformant to CSS Exclusions and Shapes if it writes style
1959 sheets that are syntactically correct according to the generic CSS grammar and the
1960 individual grammars of each feature in this module, and meet all other conformance
1961 requirements of style sheets as described in this module.
1962 </p>
1963 <h3 id="partial">
1964 Partial Implementations</h3>
1965 <p>
1966 So that authors can exploit the forward-compatible parsing rules to assign fallback
1967 values, CSS renderers <strong>must</strong> treat as invalid (and <a href="http://www.w3.org/TR/CSS21/conform.html#ignore">
1968 ignore as appropriate</a>) any at-rules, properties, property values, keywords,
1969 and other syntactic constructs for which they have no usable level of support. In
1970 particular, user agents <strong>must not</strong> selectively ignore unsupported
1971 component values and honor supported values in a single multi-value property declaration:
1972 if any value is considered invalid (as unsupported values must be), CSS requires
1973 that the entire declaration be ignored.
1974 </p>
1975 <h3 id="experimental">
1976 Experimental Implementations</h3>
1977 <p>
1978 To avoid clashes with future CSS features, the CSS2.1 specification reserves a <a
1979 href="http://www.w3.org/TR/CSS21/syndata.html#vendor-keywords">prefixed syntax</a>
1980 for proprietary and experimental extensions to CSS.</p>
1981 <p>
1982 Prior to a specification reaching the Candidate Recommendation stage in the W3C
1983 process, all implementations of a CSS feature are considered experimental. The CSS
1984 Working Group recommends that implementations use a vendor-prefixed syntax for such
1985 features, including those in W3C Working Drafts. This avoids incompatibilities with
1986 future changes in the draft.
1987 </p>
1988 <h3 id="testing">
1989 Non-Experimental Implementations</h3>
1990 <p>
1991 Once a specification reaches the Candidate Recommendation stage, non-experimental
1992 implementations are possible, and implementors should release an unprefixed implementation
1993 of any CR-level feature they can demonstrate to be correctly implemented according
1994 to spec.
1995 </p>
1996 <p>
1997 To establish and maintain the interoperability of CSS across implementations, the
1998 CSS Working Group requests that non-experimental CSS renderers submit an implementation
1999 report (and, if necessary, the testcases used for that implementation report) to
2000 the W3C before releasing an unprefixed implementation of any CSS features. Testcases
2001 submitted to W3C are subject to review and correction by the CSS Working Group.
2002 </p>
2003 <p>
2004 Further information on submitting testcases and implementation reports can be found
2005 from on the CSS Working Group's website at <a href="http://www.w3.org/Style/CSS/Test/">
2006 http://www.w3.org/Style/CSS/Test/</a>. Questions should be directed to the <a href="http://lists.w3.org/Archives/Public/public-css-testsuite">
2007 public-css-testsuite@w3.org</a> mailing list.
2008 </p>
2009 <h3 id="cr-exit-criteria">
2010 CR Exit Criteria</h3>
2011 <p>
2012 For this specification to be advanced to Proposed Recommendation, there must be
2013 at least two independent, interoperable implementations of each feature. Each feature
2014 may be implemented by a different set of products, there is no requirement that
2015 all features be implemented by a single product. For the purposes of this criterion,
2016 we define the following terms:
2017 </p>
2018 <dl>
2019 <dt>independent </dt>
2020 <dd>
2021 each implementation must be developed by a different party and cannot share, reuse,
2022 or derive from code used by another qualifying implementation. Sections of code
2023 that have no bearing on the implementation of this specification are exempt from
2024 this requirement.</dd>
2025 <dt>interoperable</dt>
2026 <dd>
2027 passing the respective test case(s) in the official CSS test suite, or, if the implementation
2028 is not a Web browser, an equivalent test. Every relevant test in the test suite
2029 should have an equivalent test created if such a user agent (UA) is to be used to
2030 claim interoperability. In addition if such a UA is to be used to claim interoperability,
2031 then there must one or more additional UAs which can also pass those equivalent
2032 tests in the same way for the purpose of interoperability. The equivalent tests
2033 must be made publicly available for the purposes of peer review.
2034 </dd>
2035 <dt>implementation</dt>
2036 <dd>
2037 a user agent which:
2038 <ol class="inline">
2039 <li>implements the specification.</li>
2040 <li>is available to the general public. The implementation may be a shipping product
2041 or other publicly available version (i.e., beta version, preview release, or “nightly
2042 build”). Non-shipping product releases must have implemented the feature(s) for
2043 a period of at least one month in order to demonstrate stability.</li>
2044 <li>is not experimental (i.e., a version specifically designed to pass the test suite
2045 and is not intended for normal usage going forward).</li>
2046 </ol>
2047 </dd>
2048 </dl>
2049 <p>
2050 The specification will remain Candidate Recommendation for at least six months.
2051 </p>
2052 <h2 class="no-num" id="acknowledgments">Acknowledgments</h2>
2053 <p>This specification is made possible by input from
2054 Andrei Bucur,
2055 Alexandru Chiculita,
2056 Arron Eicholz,
2057 Daniel Glazman,
2058 Arno Gourdol,
2059 Chris Jones,
2060 Bem Jones-Bey,
2061 Marcus Mielke,
2062 Alex Mogilevsky,
2063 Hans Muller,
2064 Mihnea Ovidenie,
2065 Virgil Palanciuc,
2066 Peter Sorotokin,
2067 Bear Travis,
2068 Eugene Veselov,
2069 Stephen Zilles
2070 and the CSS Working Group members.
2071 </p>
2072 <h2 class="no-num" id="references">References</h2>
2073 <h3 class="no-num" id="normative-references">Normative references</h3>
2074 <!--normative-->
2075 <h3 class="no-num" id="other-references">Other references</h3>
2076 <!--informative-->
2077 <h2 class="no-num" id="index">Index</h2>
2078 <!--index-->
2079 <h2 class="no-num" id="property-index">Property index</h2>
2080 <!-- properties -->
2082 <!-- template markup for issues pulled from Bugzilla -->
2083 <script type="text/template" id="issue-template">
2084 <div class="issue-marker" data-bug_id="{{bug_id}}" data-bug_status="{{bug_status}}">
2085 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id={{bug_id}}">Issue-{{bug_id}}</a>
2086 <div class="issue-details">
2087 <p class="short-desc">{{short_desc}}</p>
2088 </div>
2089 </div>
2090 </script>
2092 <script type="text/javascript" src="../shared/scripts/BugzillaTrackerUtil.js"></script>
2093 <script type="text/javascript" src="../shared/scripts/BugzillaTracker.js"></script>
2094 <script type="text/javascript">
2095 checkSpecificationIssues('CSS', 'Exclusions');
2096 </script>
2098 <h2 class="no-num" id="change-log">Change Log</h2>
2100 <h3>Since <a href="http://www.w3.org/TR/2012/WD-css3-exclusions-20120503/">May 3rd 2012</a></h3>
2101 <ul>
2102 <li>Defined exclusion edges relative to wrapping content's writing mode</li>
2103 <li>Made use of start, end, before and after consistent</li>
2104 <li>Added interpolation for basic shapes</li>
2105 <li>Changed basic shapes to depend on box specified with box-sizing</li>
2106 <li>Added overflow behavior for shape-inside.</li>
2107 <li>Added wrap-flow:minimum.</li>
2108 <li>Clarified processing model.</li>
2109 <li>Changed wrap-margin and wrap-padding to shape-margin and shape-padding.</li>
2110 <li>Removed wrap shorthand.</li>
2111 </ul>
2113 <h3>Since <a href="http://www.w3.org/TR/2011/WD-css3-exclusions-20111213/">December 13th 2011</a></h3>
2114 <ul>
2115 <li>Clarified processing model.</li>
2116 <li>Clarified interaction with floats.</li>
2117 <li>Clarified that an exclusion element establishes a new block formatting context.</li>
2118 </ul>
2120 </body>
2121 </html>
2122 <!-- Keep this comment at the end of the file
2123 Local variables:
2124 mode: sgml
2125 sgml-declaration:"~/SGML/HTML4.decl"
2126 sgml-default-doctype-name:"html"
2127 sgml-minimize-attributes:t
2128 sgml-nofill-elements:("pre" "style" "br")
2129 sgml-live-element-indicator:t
2130 sgml-omittag:nil
2131 sgml-shorttag:nil
2132 sgml-namecase-general:t
2133 sgml-general-insert-case:lower
2134 sgml-always-quote-attributes:t
2135 sgml-indent-step:nil
2136 sgml-indent-data:t
2137 sgml-parent-document:nil
2138 sgml-exposed-tags:nil
2139 sgml-local-catalogs:nil
2140 sgml-local-ecat-files:nil
2141 End:
2142 -->