css3-exclusions/Exclusions.src.html@757d9e99cd55
css3-exclusions/Exclusions.src.html
Thu, 12 Apr 2012 12:57:08 -0700
- author
- Vincent Hardy <vhardy@adobe.com>
- date
- Thu, 12 Apr 2012 12:57:08 -0700
- changeset 5468
- 757d9e99cd55
- parent 5466
- fb0270eb9aa2
- child 5488
- d3306d846020
- permissions
- -rw-r--r--
Added note about animated images, as per https://www.w3.org/Style/CSS/Tracker/actions/441
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="../default.css" />
9 <style type="text/css">
11 /* Alternate stylesheet fonts are here because in some browsers (Opera 11.5) */
12 /* The fonts are not applied if only loaded from the alternate stylesheet */
14 /* License font the following two fonts: fonts/Droid-Serif-fontfacekit/Google Android License.txt */
15 @import url(fonts/Droid-Serif-fontfacekit/stylesheet.css);
16 @import url(fonts/Droid-Sans-Mono-fontfacekit/stylesheet.css);
18 .singleImgExample {
19 display: block;
20 margin: auto;
21 }
23 .example-table {
24 table-layout: fixed;
25 width: 100%;
26 }
28 .example-table tr td img {
29 width: 90%;
30 }
32 @media screen and (min-width: 68em){
33 .issue-marker {
34 position: absolute;
35 width: 20ex;
36 margin-left: -22ex;
37 text-align: right;
38 margin-bottom: 1em;
39 }
41 div.issue-marker .issue-marker {
42 position: static;
43 width: auto;
44 margin-left: 0;
45 text-align: right;
46 }
48 div.issue-marker {
49 position: absolute;
50 width: 20ex;
51 margin-left: -22ex;
52 }
53 }
55 @media screen and (max-width: 68em){
56 .issue-marker {
57 margin-bottom: 1em;
58 }
60 .issue-marker a:link {
61 padding-left: 0.5em;
62 }
63 }
65 .issue-marker {
66 background:#eee;
67 border:1px solid #ddd;
68 font-size: 1em;
69 }
71 .issue-marker.wrapper {
72 background: none;
73 border: none;
74 }
76 .issue-marker a:link {
77 color: #c00;
78 background: none;
79 font-weight: normal;
80 padding-right: 0.5em;
81 }
83 .issue-details {
84 padding:0.5em;
85 font-size: 0.8em;
86 line-height: 1.5;
87 }
89 .issue-details p{
90 padding:0;
91 margin:0;
92 }
94 .issue-details .status{
95 background:#333;
96 color:white;
97 float:left;
98 padding:0.15em 0.8em;
99 font-size:0.8em;
100 margin-right:0.8em;
101 text-transform:uppercase;
102 }
104 </style>
105 <link rel="stylesheet" type="text/css" href="http://www.w3.org/StyleSheets/TR/W3C-ED.css" />
107 <link id="st" href="../alternate-spec-style.css" rel="stylesheet"
108 type="text/css" title="alternate spec styles">
111 </head>
112 <body>
113 <div id="div-head" class="head">
114 <p><a href="http://www.w3.org/"><img id="mobile-logo" alt="W3C" height="53" src=
115 "http://www.w3.org/2008/site/images/logo-w3c-mobile-lg" width="90"></a>
118 <!--begin-logo-->
120 <p><a href="http://www.w3.org/"><img id="logo" alt="W3C" height="48" src=
121 "http://www.w3.org/Icons/w3c_home" width="72"></a> <!--end-logo--></p>
122 <h1 id="css-exclusions-module">CSS Exclusions and Shapes Module Level 3</h1>
123 <h2 class="no-num no-toc">[LONGSTATUS] [DATE]</h2>
124 <dl>
125 <dt>This version:</dt>
126 <dd><a href="http://dev.w3.org/csswg/css3-exclusions/">http://dev.w3.org/csswg/css3-exclusions/</a></dd>
127 <!--<dd><a href="[VERSION]">http://www.w3.org/TR/[YEAR]/WD-css3-exclusions-[CDATE]/</a></dd>-->
129 <dt>Latest version:</dt>
130 <dd><a href="http://www.w3.org/TR/[SHORTNAME]/">http://www.w3.org/TR/[SHORTNAME]/</a></dd>
132 <dt>Editor's Draft:</dt>
133 <dd><a href="http://dev.w3.org/csswg/[SHORTNAME]/">http://dev.w3.org/csswg/[SHORTNAME]/</a>
135 <dt>Previous version:</dt>
136 <dd>None</dd>
138 <dt>Editors:</dt>
139 <dd class="vcard"><span class="fn">Vincent Hardy</span>, <span class="org">Adobe Systems, Inc.</span>, <span class="email">vhardy@adobe.com</span></dd>
140 <dd class="vcard"><span class="fn">Rossen Atanassov</span>, <span class="org">Microsoft Corporation</span>, <span class="email">ratan@microsoft.com</span></dd>
142 <dt>Issues List:</dt>
143 <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>
145 <dt>Discussion:</dt>
146 <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>"
148 </dl>
149 <!--copyright-->
150 <hr title="Separator for header">
151 </div>
153 <h2 class="no-num no-toc" id="abstract">Abstract</h2>
156 <p>
157 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.
158 CSS Exclusions can be defined on any CSS block-level elements. CSS
159 Exclusions extend the notion of content wrapping previously limited to
160 floats.</p>
162 <p>CSS Shapes control the geometric shapes used for wrapping inline flow
163 content outside or inside an element. CSS Shapes can be applied to any
164 element. A circle shape on a float will cause inline content to wrap around
165 the circle shape instead of the float's bounding box.</p>
167 <p>Combining CSS Exclusions and CSS Shapes allows sophisticated layouts,
168 allowing interactions between shapes in complex positioning schemes.</p>
170 <h2 class="no-num no-toc" id="status">Status of this document</h2>
171 <!--status-->
172 <p>This is the First Public Working Draft of the CSS Exclusions and Shapes Level 3 Module.</p>
174 <h2 class="no-num no-toc" id="contents">Table of contents</h2>
175 <!--toc-->
177 <h2 id="intro">Introduction</h2>
178 <p><em>This section is not normative.</em></p>
179 <p>
180 The exclusions section of this specification defines features that allow inline flow
181 content to wrap around outside the <span>exclusion area</span> of elements.
182 </p>
183 <p>
184 The shapes section of the specification defines properties to control the geometry of
185 an element's <span>exclusion area</span> as well as the geometry used for wrapping
186 an element's inline flow content.
187 </p>
189 <h2 id="definitions">Definitions</h2>
191 <dfn>Exclusion box</dfn>
193 <p>
194 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'
195 property is used to make an element's generated box an exclusion box. An exclusion box contributes
196 its <span>exclusion area</span> to its <a href="http://www.w3.org/TR/CSS2/visudet.html#containing-block-details">
197 containing block's</a> <span>wrapping context</span>. An element with a 'float'
198 computed value other than 'none' does not become an exclusion.
199 </p>
201 <dfn>Exclusion area</dfn>
202 <div class="issue-marker" data-bug_id="15087" data-bug_status="NEW">
203 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15087">Bug-15087</a>
204 <div class="issue-details">
205 <p class="short-desc">Interaction of floats and exclusions (Howcome's questions)</p>
206 </div>
207 </div>
208 <p>
209 The area used for excluding inline flow content around an exclusion element. The
210 exclusion area is equivalent to the <a href="http://www.w3.org/TR/CSS2/box.html#box-dimensions">
211 border box</a>.
212 This specification's
213 'shape-outside' property can be used to define arbitrary, non-rectangular exclusion
214 areas.
215 </p>
217 <dfn>Float area</dfn>
219 <p>
220 The area used for excluding inline flow content around a float element. By default, the
221 float area is the <a href="http://www.w3.org/TR/CSS2/box.html#box-dimensions">margin box</a>.
222 This specification's
223 'shape-outside' property can be used to define arbitrary, non-rectangular float
224 areas.
225 </p>
228 <dfn>Wrapping context</dfn>
229 <div class="issue-marker" data-bug_id="15086" data-bug_status="NEW">
230 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15086">Bug-15086</a>
231 <div class="issue-details">
232 <p class="short-desc">should the wrapping context be generic and include floats?</p>
233 </div>
234 </div>
236 <p>
237 The wrapping context of a box is a collection of 'exclusion areas'. During layout,
238 a box wraps its inline flow content in the area that corresponds to the subtraction of
239 its wrapping context from its own <span>content area</span>.
240 </p>
242 <p>
243 A box inherits its
244 <a href="http://www.w3.org/TR/CSS2/visudet.html#containing-block-details">containing block's</a>
245 wrapping context unless it specifically
246 resets it using the 'wrap-through' property.
247 </p>
249 <dfn>Content area</dfn>
250 <p>
251 The area used for layout of the inline flow content of a box. By default the
252 area is equivalent to the <a href="http://www.w3.org/TR/CSS2/box.html#box-dimensions">content box</a>.
253 This specification's 'shape-inside' property can define arbitrary, non-rectangular content areas.
254 </p>
256 <dfn title="outside-inside">Outside and inside</dfn>
258 <p>
259 In this specification, 'outside' refers to DOM content that is not a descendant of an element
260 while 'inside' refers to the element's descendants.
261 </p>
263 <h2 id="exclusions">Exclusions</h2>
264 <p>
265 Exclusion elements define exclusion areas that contribute to their containing block's
266 <span>wrapping context</span>. As a consequence, exclusions impact the layout of their
267 containing block's descendants.
268 <p>
270 <p>
271 Elements layout their inline content in their <span>content area</span> and wrap around the
272 areas in their associated wrapping context. If the element is itself an exclusion, it
273 does not wrap around its own exclusion shape and the impact of other exclusions on other
274 exclusions is controlled by the 'z-index' property as explained in the
275 <a href="#exclusions-order">exclusions order</a> section.
276 </p>
277 The <a href="#shapes">shape properties</a> can be used to change the shape of
278 <span>exclusion areas</span>.
279 </p>
281 <h3 id="declaring-exclusions">Declaring exclusions</h3>
282 <p>
283 An element becomes an exclusion when its 'wrap-flow' property has a computed value other than
284 'auto'.
285 </p>
287 <h4 id="wrap-flow-property">The 'wrap-flow' property</h4>
288 <table class="propdef">
289 <tr>
290 <th>Name:</th>
291 <td><dfn title="'wrap-flow'">wrap-flow</dfn></td>
292 </tr>
293 <tr>
294 <th>Value:</th>
295 <td><var>auto</var> | <var>both</var> | <var>start</var> | <var>end</var> | <var>maximum</var> | <var>clear</var></td>
296 </tr>
297 <tr>
298 <th>Initial:</th>
299 <td>auto</td>
300 </tr>
301 <tr>
302 <th>Applies to:</th>
303 <td>block-level elements. Does not apply to elements with a 'float' computed value other than
304 <code class="css">none</code></td>
305 </tr>
306 <tr>
307 <th>Inherited:</th>
308 <td>no</td>
309 </tr>
310 <tr>
311 <th>Percentages:</th>
312 <td>N/A</td>
313 </tr>
314 <tr>
315 <th>Media:</th>
316 <td>visual</td>
317 </tr>
318 <tr>
319 <th>Computed value:</th>
320 <td>as specified</td>
321 </tr>
322 </table>
324 <p>The values of this property have the following meanings:</p>
325 <dl>
326 <dt><dfn title="'wrap-flow'!!'auto'">auto</dfn></dt>
327 <dd>
328 No exclusion is created. Inline flow content interacts with the element as usual.
329 </dd>
330 <dt><dfn title="'wrap-flow'!!'both'">both</dfn></dt>
331 <dd>
332 Inline flow content can flow on all sides of the exclusion.
333 </dd>
334 <dt><dfn title="'wrap-flow'!!'start'">start</dfn></dt>
335 <dd>
336 Inline flow content can flow before the start edge of the exclusion area but
337 must leave the area after the end edge of the exclusion empty.
338 </dd>
339 <dt><dfn title="'wrap-flow'!!'end'">end</dfn></dt>
340 <dd>
341 Inline flow content can flow after the end edge of the exclusion area but
342 must leave the area before the start edge of the exclusion empty.
343 </dd>
344 <dt><dfn title="'wrap-flow'!!'maximum'">maximum</dfn></dt>
345 <dd>
346 Inline flow content can flow on the edge of the exclusion with the largest
347 available space for the given line, and must leave the other edge of the exclusion
348 empty.
349 </dd>
350 <dt><dfn title="'wrap-flow'!!'clear'">clear</dfn></dt>
351 <dd>
352 Inline flow content can only flow on top and bottom edges of the exclusion
353 and must leave the areas before the start and after the end edges of the
354 exclusion empty.
355 </dd>
356 </dl>
358 <p>
359 If the property's computed value is 'auto', the element does not become an
360 <span>exclusion</span>.
361 </p>
362 <p>
363 Otherwise, a computed 'wrap-flow' property value of 'both', 'start', 'end', 'maximum' or 'clear' on an
364 element makes that element an <span>exclusion element</a>. It's <span>exclusion shape</span>
365 is contributed to its containing block's <span>wrapping context</span>, causing the containing block's descendants
366 to wrap around its exclusion area.
367 </p>
369 <div class="figure">
370 <img alt="General illustration showing how exclusions combine" src="images/exclusions-illustration.png" width="70%" />
371 <p class="caption">Combining exclusions</p>
372 </div>
374 <p>
375 The above figure illustrates how exclusions are combined. The outermost box represents
376 an element's content box. The A, B, C and D darker gray boxes represent exclusions
377 in the element's wrapping context. A, B, C and D have their respective 'wrap-flow'
378 set to 'both', 'start', 'end' and 'clear' respectively. The lighter gray areas show
379 the additional areas that are excluded for inline layout as a result of the 'wrap-flow'
380 value. For example, the area to the right of 'B' cannot be used for inline layout
381 because the 'wrap-flow' for 'B' is 'start'.
382 </p>
383 <p>
384 The background 'blue' area shows what areas are available for the element's inline content layout.
385 All areas represented with a light or dark shade of gray are not available for inline
386 content layout.
387 </p>
389 <div class="issue-marker" data-bug_id="15088" data-bug_status="FIXED">
390 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15088">Bug-15088</a>
391 <div class="issue-details">
392 <p class="short-desc">Add an example with auto-height content and z-index for exclusions order.</p>
393 </div>
394 </div>
396 <div class="issue-marker" data-bug_id="15084" data-bug_status="NEW">
397 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15084">Bug-15084</a>
398 <div class="issue-details">
399 <p class="short-desc">Fluidity of the layout with respect to different amounts of content</p>
400 </div>
401 </div>
403 <div class="example">
404 <p>
405 The 'wrap-flow' property values applied to an absolutely positioned element.
406 </p>
407 <code class="html"><pre>
409 <div id="grid">
410 <div id="exclusion">Donec metus …</div>
411 <div id="content">Lorem ipsum…</div>
412 </div>
414 <style type="text/css">
415 #grid {
416 width: 100em;
417 height: 100em;
418 display: grid;
419 grid-columns: 50% 20% 20%;
420 grid-rows: 40% 20% 40%;
421 }
423 #exclusion {
424 grid-row: 2;
425 grid-column: 2;
426 wrap-flow: <see below>
427 }
429 #content {
430 grid-row: 1;
431 grid-row-span: 3;
432 grid-column: 1;
433 grid-column-span: 3;
434 }
435 </style>
436 </pre></code>
437 <table class="example-table">
438 <tr>
439 <td><code class="html">#exclusion{ wrap-flow: auto; }</code></td>
440 <td><code class="html">#exclusion{ wrap-flow: both; }</code></td>
441 </tr>
442 <tr>
443 <td><img src="images/exclusion_wrap_side_auto.png" alt="Example rendering for wrap-side: auto" /></td>
444 <td><img src="images/exclusion_wrap_side_both.png" alt="Example rendering for wrap-side: both" /></td>
445 </tr>
446 <tr>
447 <td><code class="html">#exclusion{ wrap-flow: start; }</code></td>
448 <td><code class="html">#exclusion{ wrap-flow: end; }</code></td>
449 </tr>
450 <tr>
451 <td><img src="images/exclusion_wrap_side_left.png" alt="Example rendering for wrap-side: start" /></td>
452 <td><img src="images/exclusion_wrap_side_right.png" alt="Example rendering for wrap-side: end" /></td>
453 </tr>
454 <tr>
455 <td><code class="html">#exclusion{ wrap-flow: maximum; }</code></td>
456 <td><code class="html">#exclusion{ wrap-flow: maximum; }</code></td>
457 </tr>
458 <tr>
459 <td><img src="images/exclusion_wrap_side_maximum_L.png" alt="Example rendering for wrap-side: maximum" /></td>
460 <td><img src="images/exclusion_wrap_side_maximum_R.png" alt="Example rendering for wrap-side: maximum" /></td>
461 </tr>
462 <tr>
463 <td><code class="html">#exclusion{ wrap-flow: clear; }</code></td>
464 <td><code class="html"> </code></td>
465 </tr>
466 <tr>
467 <td><img src="images/exclusion_wrap_side_clear.png" alt="Example rendering for wrap-side: clear" /></td>
468 <td> </td>
469 </tr>
470 </table>
471 </div>
472 <!-- End section "wrap-flow Property" -->
473 <!-- End section "Declaring Exclusions" -->
475 <h3 id="scope-and-effect-of-exclusions">Scope and effect of exclusions</h3>
476 <p>
477 An <span>exclusion</span> affects the inline flow content descended from the exclusion's containing
478 blocks (defined in <a href="http://www.w3.org/TR/CSS2/visudet.html#containing-block-details">
479 CSS 2.1 10.1</a>) and that of all descendant elements of the same containing
480 block. All inline flow content inside the containing block of the exclusions is
481 affected. To stop the effect of exclusions defined outside an element, the 'wrap-through'
482 property can be used (see the <a href="#propagation-of-exclusions">propagation of exclusions</a>
483 section below).
484 </p>
486 <p>
487 For exclusions with 'position:fixed', the containing block is that of the root
488 element.
489 </p>
491 <h4 id="wrap-margin-property">The 'wrap-margin' property</h4>
492 <p>
493 The 'wrap-margin' property can be used to offset the inline flow content wrapping
494 on the outside of exclusions. Offsets created by the 'wrap-margin' property are
495 offset from the outside of the exclusion. This property takes on positive values
496 only.
497 </p>
498 <table class="propdef">
499 <tr>
500 <th>Name:</th>
501 <td><dfn title="'wrap-margin'">wrap-margin</dfn></td>
502 </tr>
503 <tr>
504 <th>Value:</th>
505 <td><var><length></var></td>
506 </tr>
507 <tr>
508 <th>Initial:</th>
509 <td>0</td>
510 </tr>
511 <tr>
512 <th>Applies to:</th>
513 <td><span>exclusion</span> elements</td>
514 </tr>
515 <tr>
516 <th>Inherited:</th>
517 <td>no</td>
518 </tr>
519 <tr>
520 <th>Percentages:</th>
521 <td>N/A</td>
522 </tr>
523 <tr>
524 <th>Media:</th>
525 <td>visual</td>
526 </tr>
527 <tr>
528 <th>Computed value:</th>
529 <td>the absolute length</td>
530 </tr>
531 </table>
533 <!-- End secion "wrap-margin property" -->
535 <h4 id="wrap-padding-property">The 'wrap-padding' Property</h4>
536 <p>
537 The 'wrap-padding' property can be used to offset the inline flow content wrapping
538 on the inside of elements. Offsets created by the 'wrap-padding' property are offset
539 from the <span>content area</span> of the element. This property takes on positive values only.
540 </p>
541 <table class="propdef">
542 <tr>
543 <th>Name:</th>
544 <td><dfn title="'wrap-padding'">wrap-padding</dfn></td>
545 </tr>
546 <tr>
547 <th>Value:</th>
548 <td><var><length></var></td>
549 </tr>
550 <tr>
551 <th>Initial:</th>
552 <td>0</td>
553 </tr>
554 <tr>
555 <th>Applies to:</th>
556 <td><span>exclusion</span> elements</td>
557 </tr>
558 <tr>
559 <th>Inherited:</th>
560 <td>no</td>
561 </tr>
562 <tr>
563 <th>Percentages:</th>
564 <td>N/A</td>
565 </tr>
566 <tr>
567 <th>Media:</th>
568 <td>visual</td>
569 </tr>
570 <tr>
571 <th>Computed value:</th>
572 <td>the absolute length</td>
573 </tr>
574 </table>
575 <!-- End section "wrap-padding property" -->
577 <div class="note">Note that the 'wrap-padding' property affects layout of content inside
578 the element it applies to while the 'wrap-margin' property affects layout of content
579 outside the element.</div>
581 <!-- End section "Scope and Effect of Exclusions" -->
583 <h3 id="propagation-of-exclusions">Propagation of Exclusions</h3>
584 <p>
585 By default, an element inherits its parent <span>wrapping context</span>. In other words
586 it is subject to the exclusions defined <span title="outside-inside">outside</sapn> the element.
587 </p>
588 <p>Setting the 'wrap-through' property to 'none' prevents an element from inheriting its parent
589 wrapping context. In other words, exclusions defined 'outside' the element, have not effect
590 on the element's children layout.
591 </p>
592 <div class="note">
593 Exclusions defined by an element's descendants still contribute to their containing block's
594 <span>wrapping context</span>. If that containing block is a child of an element with 'wrap-through'
595 set to none, or the element itself, then exclusion still have an effect on the children of that
596 containing block element.
597 </div>
599 <h4 id="wrap-through-property">The 'wrap-through' Property</h4>
601 <div class="issue-marker" data-bug_id="15085" data-bug_status="NEW">
602 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15085">Bug-15085</a>
603 <div class="issue-details">
604 <p class="short-desc">do we need wrap-through?</p>
605 </div>
606 </div>
608 <table class="propdef">
609 <tr>
610 <th>Name:</th>
611 <td><dfn title="'wrap-through'">wrap-through</dfn></td>
612 </tr>
613 <tr>
614 <th>Value:</th>
615 <td><var>wrap</var> | <var>none</var></td>
616 </tr>
617 <tr>
618 <th>Initial:</th>
619 <td>wrap</td>
620 </tr>
621 <tr>
622 <th>Applies to:</th>
623 <td>block-level elements</td>
624 </tr>
625 <tr>
626 <th>Inherited:</th>
627 <td>no</td>
628 </tr>
629 <tr>
630 <th>Percentages:</th>
631 <td>N/A</td>
632 </tr>
633 <tr>
634 <th>Media:</th>
635 <td>visual</td>
636 </tr>
637 <tr>
638 <th>Computed value:</th>
639 <td>as specified</td>
640 </tr>
641 </table>
643 <p>The values of this property have the following meanings:</p>
644 <dl>
645 <dt><dfn title="'wrap-through'!!'wrap'">wrap</dfn></dt>
646 <dd>
647 The element inherits its parent node's <span>wrapping context</span>. Its descendant
648 inline content wraps around exclusions defined <span title="outside-inside">outside</span>
649 the element.
650 </dd>
651 </dl>
652 <dl>
653 <dt><dfn title="'wrap-through'!!'none'">none</dfn></dt>
654 <dd>
655 The element does not inherit its parent node's <span>wrapping context</span>. Its
656 descendants are only subject to exclusion shapes defined <span title="outside-inside">inside</span>
657 the element.
658 </dd>
659 </dl>
660 <div class="example">
661 <p>
662 Using the 'wrap-through' property to control the effect of exclusions.
663 </p>
664 <pre><code class="html">
666 <style type="text/css">
667 #grid {
668 display: grid;
669 grid-columns: 25% 50% 25%;
670 grid-rows: 25% 25% 25% 25%;
671 }
673 #exclusion {
674 grid-row: 2;
675 grid-row-span: 2;
676 grid-column: 2;
677 wrap-flow: <see below>
678 }
680 #rowA, #rowB {
681 grid-row-span: 2;
682 grid-column: 1;
683 grid-column-span: 3;
684 }
686 #rowA {
687 grid-row: 1;
688 }
690 #rowB {
691 grid-row: 3;
692 }
693 </style>
695 <style type="text/css">
696 .exclusion {
697 wrap-flow: both;
698 position: absolute;
699 left: 20%;
700 top: 20%;
701 width: 50%;
702 height: 50%;
703 background-color: rgba(220, 230, 242, 0.5);
704 }
705 </style>
707 <div id="grid">
708 <div class=”exclusion”></div>
709 <div id="rowA" style=”wrap-through: wrap;”> Lorem ipsum dolor sit amet...</div>
710 <div id="rowB" style=”wrap-through: none;”> Lorem ipsum dolor sit amet...</div>
711 </div>
712 </code></pre>
714 <img class="singleImgExample" src="images/exclusion_wrap_through.png" alt="Example rendering of wrap-through: wrap | none" style="max-width:40%"/>
715 </div>
716 <!-- End section "wrap-through property" -->
719 <h4 id="wrap-shorthand-property">The 'wrap' Shorthand Property</h4>
720 <table class="propdef">
721 <tr>
722 <th>Name:</th>
723 <td><dfn title="'wrap'">wrap</dfn></td>
724 </tr>
725 <tr>
726 <th>Value:</th>
727 <td><var><wrap-flow></var> || <var><wrap-margin></var> [ / <var><wrap-padding></var>]</td>
728 </tr>
729 <tr>
730 <th>Initial:</th>
731 <td>see individual properties</td>
732 </tr>
733 <tr>
734 <th>Applies to:</th>
735 <td>block-level elements</td>
736 </tr>
737 <tr>
738 <th>Inherited:</th>
739 <td>no</td>
740 </tr>
741 <tr>
742 <th>Percentages:</th>
743 <td>N/A</td>
744 </tr>
745 <tr>
746 <th>Media:</th>
747 <td>visual</td>
748 </tr>
749 <tr>
750 <th>Computed value:</th>
751 <td>see individual properties</td>
752 </tr>
753 </table>
754 <p>
755 The 'wrap' property is a shorthand property for setting the exclusions properties
756 at the same place in the style sheet.
757 </p>
760 <!-- End section "wrap shorthand property" -->
761 <!-- End section "Propagation of Exclusions" -->
763 <h3 id="exclusions-order">Exclusions order</h3>
764 <p>
765 Exclusions follow the painting order (See [[!CSS21]] Appendix E). Exclusions are
766 applied in reverse to the document order in which they are defined. The last exclusion
767 appears on top of all other exclusion, thus it affects the inline flow content of
768 all other preceding exclusions or elements descendant of the same containing block.
769 To change the ordering of exclusions with 'position' property computed to a value
770 other than 'static', 'z-index' can be used. Exclusions with 'position' property
771 computed to 'static' are not affected by the 'z-index' property, thus follow the painting
772 order.
773 </p>
775 <div class="example">
776 <p>Ordering of exclusions.</p>
777 <pre><code class="html">
778 <style type="text/css">
779 .exclusion {
780 wrap-flow: both;
781 position: absolute;
782 width: 50%;
783 height: auto;
784 }
785 </style>
787 <div class=”exclusion” style=”top: 0px; left: 0px;”>
788 Lorem ipsum dolor sit amet...
789 </div>
790 <div id="orderedExclusion" class=”exclusion” style=”top: 25%; left: 25%;”>
791 Lorem ipsum dolor sit amet...
792 </div>
793 <div class=”exclusion” style=”top: 50%; left: 50%;”>
794 Lorem ipsum dolor sit amet...
795 </div>
796 </code></pre>
798 <table class="example-table">
799 <tr>
800 <td style="width:50%"><code class="html">#orderedExclusion{ z-index: auto; }</code></td>
801 <td style="width:50%"><code class="html">#orderedExclusion{ z-index: 1; }</code></td>
802 </tr>
803 <tr>
804 <td><img class="singleImgExample" src="images/exclusion_ordering.png" alt="Example rendering of default exclusion ordering." /></td>
805 <td><img class="singleImgExample" src="images/exclusion_ordering_z_order.png" alt="Example rendering of default exclusion ordering." /></td>
806 </tr>
807 </table>
809 </div>
810 <!-- End section "Order of Exclusions" -->
812 <div class="issue-marker" data-bug_id="15183" data-bug_status="NEW">
813 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15183">Bug-15183</a>
814 <div class="issue-details">
815 <p class="short-desc">Is the CSS exclusions processing model incorrect?</p>
816 </div>
817 </div>
819 <div class="issue-marker" data-bug_id="15083" data-bug_status="NEW">
820 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15083">Bug-15083</a>
821 <div class="issue-details">
822 <p class="short-desc">Concerns over Error accumulation vs. performance</p>
823 </div>
824 </div>
825 <p class="issue">
826 The rules for exclusions order and exclusions on absolutely positioned elements
827 (particularly those with static position) build this exclusions model on top of
828 the absolute positioning model in CSS Level 2, rather than on top of floats, the
829 existing exclusion model in CSS Level 1 and 2. The CSS Working Group has not reached
830 consensus on whether it intends to base the new exclusions features in this specification
831 on top of absolute positioning (as these sections of this specification do) or on
832 top of floats.
833 </p>
835 <p class="note">
836 This module does not depend on any particular positioning scheme.
837 </p>
839 <h3 id="exclusions-processing-model">Processing model</h3>
841 <h4 id="exclusions-processing-model-description">Description</h4>
843 <p>Applying exclusions is a two-step process:</p>
845 <ul>
846 <li><strong>Step 1</strong>: resolve exclusion boxes belonging to each wrapping context</li>
847 <li><strong>Step 2</strong>: resolve wrapping contexts and layout each containing block in turn:
848 <ul>
849 <li><strong>Step 2-A</strong>: resolve the position and size of exclusions</li>
850 <li><strong>Step 2-B</strong>: layout containing block, wrapping around exclusion areas</li>
851 </ul>
852 </li>
853 </ul>
855 <h4 id="step-1-resolve-exclusion-boxes-belonging-to-each-wrapping-context">Step 1: resolve exclusion boxes belonging to each wrapping context</h4>
857 <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
858 <span>exclusion area</span> belongs to. This is a simple step, based on the
859 definition of containing blocks and elements with a computed value for 'wrap-flow'
860 that is not <code class="css">none</code>.</p>
862 <h4 id="step-2-resolve wrapping-contexts-layout-containing-blocks">Step 2: resolve wrapping contexts and layout containing blocks</h4>
864 <p>In this step, starting from the
865 top of the rendering tree, the the agent processes each containing block in two sub-steps.</p>
867 <h4 id="step-2-A-resolve-exclusions-position-and-size">Step 2-A: resolve exclusions position and size</h4>
869 <p>Resolving the position and size of exclusions in the wrapping context may or may not require
870 a layout. For example, if an exclusion is absolutely positioned and sized, there is no need to
871 perform a layout to resolve its position and size. In other situations, laying out the
872 containing block's content is required.</p>
874 <p>When a layout is required,
875 it is carried out without applying any exclusion area. In other words, the containing
876 block is laid out without a wrapping context. </p>
878 <p>Step 2-A yields a position and size
879 for all exclusion areas in the wrapping context.</p>
881 <p>Scrolling is ignored in this step when resolving the position and size of
882 'position:fixed' <span>exclusions</span>.</p>
885 <h4 id="step-2-B-layout-containing-block-applying-wrapping">Step 2-B: layout containing block applying wrapping</h4>
887 <p>Finally, the content of the containing block is laid out, with the
888 inline content wrapping around the wrapping content's exclusion areas.</p>
890 <h4 id="exclusions-processing-model-example">Example</h4>
892 <p>This section illustrates the exclusions processing model with an example. It is meant
893 to be simple. Yet, it contains enough complexity to address the issues of
894 layout dependencies and re-layout.</p>
897 <p>The code snippet in the following example has two exclusions affecting
898 the document's inline content.</p>
900 <div class="example">
901 <pre class="code idl">
902 <html>
903 <body>
904 <div id="d1" style="width:100%;height:auto;position:relative">
905 Lorem ipsusm ...
906 <p id="e1" style="wrap-flow: both;position:absolute; left:50%; top:50%;
907 width:40%;height:40%; margin-left:-20%;" ></p>
908 </div>
909 <div id="d2" style="width:100%;height:auto;position:static">
910 Lorem ipsusm ...
911 <p id="e2" style="wrap-flow: both;position:absolute; right:5ex; top:1em;
912 width:12ex;height:10em; margin-left:-20%;" ></p>
913 </div>
914 </body>
915 </html>
916 </pre>
917 </div>
918 <p>The following figures illustrate:</p>
920 <ul>
921 <li>the document's DOM tree</li>
922 <li>the layout tree of generated block boxes</p>
923 </ul>
925 <div class="figure">
926 <img src="images/processing-model-example-dom.svg" width="200" />
927 <p class="caption">DOM tree</p>
928 </div>
930 <div class="figure">
931 <img src="images/processing-model-example-layout-tree.svg" width="250" />
932 <p class="caption">Layout tree of generated block boxes</p>
933 </div>
935 <h5>Step 1: resolve exclusion boxes belonging to each wrapping context</h5>
937 <p>The figures illustrate how the boxes corresponding to the element sometimes
938 have a different containment hierarchy in the layout tree than in the DOM tree.
939 For example, the box generated by <code class="idl">e1</code> is positioned in
940 its containing block's box, which is the <code class="idl">d1-block</code> box, because
941 <code class="idl">e1</code> is absolutely positioned and <code class="idl">d1</code>
942 is relatively positioned. However, while <code class="idl">e2</code> is also absolutely
943 positioned, its containing block is the initial containing block (ICB). See the
944 section 10.1 of the CSS 2.1 specification ([[!CSS21]]) for details.</p>
946 <p>As a result of the computation of containing blocks for the tree, the boxes belonging
947 to the wrapping contexts of all the elements can be determined:</p>
949 <ul>
950 <li>The wrapping context for the html element contains the <code class="idl">e2</code> box: WC-1 (Wrapping Context 1)</li>
951 <li>The wrapping context for the body element inherits the html element's wrapping context: WC-1</li>
952 <li>The wrapping context for <code class="idl">d1</code> inherits the body element's
953 wrapping context and adds the <code class="idl">e1</code> box to it. So the wrapping
954 context is made of both the <code class="idl">e1</code> box and the
955 <code class="idl">e2</code> box: WC-2</li>
956 <li>The wrapping context for <code class="idl">d2</code> inherits the body element's
957 wrapping context: WC-1</li>
958 </ul>
960 <h5>Step 2: resolve wrapping contexts and layout containing blocks</h5>
962 <p>In this step, each containing block is processed in turn. For each containing block,
963 we (conceptually) go through two phases:</p>
964 <ol>
965 <li>resolve the wrapping context: resolve the position and size of its exclusions</li>
966 <li>layout the containing block</li>
967 </ol>
969 <p>In our example, this breaks down to:</p>
970 <ol>
971 <li>resolve the position and size of the exclusions belonging to WC-1: RWC-1 (Resolved Wrapping Context 1).</li>
972 <li>layout the initial containing block (i.e., layout its content):
973 <ol>
974 <li>resolve the html element's wrapping context: RWC-1</li>
975 <li>layout the html element:
976 <ol>
977 <li>resolve the body element's wrapping context: RWC-1</li>
978 <li>layout the body element:
979 <ol>
980 <li>resolve the d1 element's wrapping context: RWC-2</li>
981 <li>layout the d1 element</li>
982 <li>resolve the d2 element's wrapping context: RWC-1</li>
983 <li>layout the d2 element</li>
984 </ol>
985 </li>
986 </ol>
987 </li>
988 </ol>
989 </li>
990 </ol>
992 <h6>Resolving RWC-1</h6>
994 <p>The top-most wrapping context in the layout tree contains the <code class="idl">e2</code>
995 exclusion. Its position and size needs to be resolved. In general, computing an
996 exclusion's position and size may or may not require laying out other content.
997 In our example, no content needs to be laid out to resolve the <code class="idl">e2</code>
998 exclusion's position because it is absolutely positioned and its size can be resolved
999 without layout either. At this point, RWC-1 is resolved and can be used when
1000 laying inline content out.</p>
1002 <h6>Resolving RWC-2</h6>
1004 <p>The process is similar: the position of the
1005 <code class="idl">e1</code> exclusion needs to be resolved. Again, resolving the exclusion's
1006 position and size may require processing the containing block (d1 here).
1007 It is the case here because the size and position of
1008 <code class="idl">e1</code> depend on resolving the percentage lengths. The percentages are relative
1009 to the size of
1010 <code class="idl">d1</code>'s box. As a result, in order to resolve
1011 a size for <code class="idl">d1</code>'s box, a first layout of <code class="idl">d1</code>
1012 is done without any wrapping context (i.e., no exclusions applied). The layout yields a
1013 position and size for <code class="idl">e1</code>'s box.
1014 </p>
1015 <p>At this point, RWC-2 is resolved because the position and size of both
1016 e1 and e2 are resolved.</p>
1018 <p class="note">The important aspect of the above processing example is that once an element's wrapping context
1019 is resolved (by resolving its exclusions' position and size), the position and size of the
1020 exclusions are not re-processed if the element's size changes between the layout that may be done
1021 without considering any wrapping context (as for RWC-2) and the layout done with the resolved wrapping context.
1022 This is what breaks the possible circular dependency between the resolution of wrapping contexts
1023 and the layout of containing blocks.</p>
1025 <h3 id="floats-and-exclusions">Floats and exclusions</h3>
1027 <h4 id="floats-and-exclusions-similarities">Similarities</h4>
1029 <p>This section is non-normative.</p>
1030 <p>There are similarities between floats an exclusions in that inline content wraps around floats
1031 and also wraps around exclusion areas. However, there are very significant differences.</p>
1033 <h4 id="floats-and-exclusions-differences">Differences</h4>
1035 <p>This section is non-normative.</p>
1036 <ul>
1037 <li><strong>scope</strong>. While floats apply to content that follows in the
1038 document, exclusions apply to content in their containing block.</li>
1039 <li><strong>positioning</strong>. Floats are part of the inline flow and 'float' on the
1040 line box. Authors can control how the floats move on the line box, to the right or to the
1041 left. By contrast, exclusions can be positioned using any positioning scheme such
1042 as grid layout ([[CSS3-GRID-LAYOUT]]), flexible box ([[CSS3-FLEXBOX]]) or any other
1043 CSS positioning scheme.</li>
1044 <li><strong>separation of concerns</strong>. Making an element a float determines both
1045 its positioning scheme and its effect on inline content. Making an element an
1046 exclusion only determines its impact on inline content and does not impose constraints
1047 on its positioning method.</li>
1048 </ul>
1050 <h4 id="floats-and-exclusions-interoperability">Interoperability</h4>
1052 <h5 id="effect-of-floats-on-exclusions">Effect of floats on exclusions</h5>
1054 <p>Floats have an effect on the positioning of exclusions and the layout of their inline content. For
1055 example, if an exclusion is an inline-box which happens to be on the same line as a float,
1056 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
1057 is any other inline content.</p>
1059 <h5 id="effect-of-exclusions-on-floats">Effect of exclusions on floats</h5>
1061 <p>Exclusions have an effect on the positioning of floats as they have an effect on inline content.
1062 Therefore, in <a href="step-2-B-layout-containing-block-applying-wrapping">Step 2-B</a>, floats will avoid <span>exclusion areas</span>.</p>
1064 <!-- End section "Exclusions" -->
1066 <h2 id="shapes">Shapes</h2>
1068 <div class="issue-marker" data-bug_id="15091" data-bug_status="NEW">
1069 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15091">Bug-15091</a><br />
1070 <div class="issue-details">
1071 <p class="short-desc">Simplify the syntax for shapes</p>
1072 </div>
1073 </div>
1075 <p>
1076 Shapes define arbitrary geometric contours around which or into which inline flow
1077 content flows. There are two different types of shapes – 'outside' and 'inside'.
1078 The outside shape defines the <span>exclusion area</span> for an <span>exclusion element</span>
1079 or the <span>float area</span> for a float.
1080 The inside shape defines an element's <span>content shape</span> and the element's inline
1081 content will flow within that shape.
1082 </p>
1084 <p class="note">It is important to note that while outside shapes only apply to
1085 <span>exclusions</span> and floats, inside shapes apply to all block-level elements.</p>
1087 <h3 id="relation-to-box-model-and-float-behavior">Relation to the box model and float behavior</h3>
1089 <p>
1090 While the boundaries used for wrapping inline flow content outside and inside
1091 an element can be defined using shapes, the actual box model does not change. If
1092 the element has specified margins, borders or paddings they will be computed and
1093 rendered according to the [[!CSS3BOX]] module.
1094 </p>
1096 <p>
1097 However, floats are an exception. If a float has an outside shape, its positioning
1098 is resolved as
1099 <a href="http://www.w3.org/TR/CSS2/visuren.html#float-position">defined</a> in
1100 [[!CSS21]] but using the
1101 outside shape's bounding box is used in lieu of the float's margin box.
1102 </p>
1104 <div class="example">
1105 <p>CSS 'shape' and CSS box model relation.</p>
1106 <pre><code class="html">
1107 <style type="text/css">
1108 .exclusion {
1109 wrap-flow: both;
1110 position: absolute;
1111 shape-outside: circle(50%, 50%, 50%);
1112 border: 1px solid red;
1113 }
1114 </style>
1116 <div style=”position: relative;”>
1117 <div class=”exclusion”></div>
1118 Lorem ipsum dolor sit amet...
1119 </div>
1120 </code></pre>
1121 <img class="singleImgExample" src="images/shapes_CSS2.1_MBP.png" alt="Example rendering of circle shape and box model." style="max-width:40%"/>
1122 </div>
1124 <h3 id="shapes-from-svg-syntax">Shapes from SVG Syntax</h3>
1125 <p>
1126 Shapes can be specified using <a href="http://www.w3.org/TR/SVG/shapes.html">SVG basic shapes</a>.
1127 </p>
1130 <h4 id="supported-svg-shapes">Supported SVG Shapes</h4>
1131 The following SVG shapes are supported by the CSS shapes module.
1132 <dl>
1133 <dt>rectangle(<length>{4} [ curve <length>{1,2} ]? )</dt>
1134 <dd>
1135 <ul>
1136 <li>The four values represent <strong>x, y, width and height</strong> - define the bounding box of the rectangle</li>
1137 <li>
1138 The two 'curve' values represent <strong>
1139 rx</strong> and <strong>ry</strong> - define the rounded rectangles, the <strong>x</strong>
1140 and <strong>y</strong> axis and radius of the ellipse used to round off the corners
1141 of the rectangle
1142 </li>
1143 </ul>
1144 </dd>
1145 <dt>circle(<length>{3})</dt>
1146 <dd>
1147 <ul>
1148 <li>
1149 The three values values represent <strong>cx</strong>, <strong>cy</strong>,
1150 <strong>r</strong> - The <strong>x</strong> and <strong>y</strong> axis coordinate
1151 of the center of the circle and the radius of the circle
1152 </li>
1153 </ul>
1154 </dd>
1155 <dt>ellipse(<length>{4})</dt>
1156 <dd>
1157 <ul>
1158 <li>The four values represent <strong>cx</strong>, <strong>cy</strong>, <strong>rx</strong> and <strong>ry</strong> -
1159 The <strong>x</strong> and <strong>y</strong> coordinate of the center of the ellipse and
1160 the <strong>x</strong> and <strong>y</strong> axis radius of the ellipse
1161 </li>
1162 </ul>
1163 </dd>
1164 <dt>polygon([<fill-rule>,]? <length>{2}#)</dt>
1165 <dd>
1166 <ul>
1167 <li><strong>fillRule</strong> - The filling rule used to determine the interior of the
1168 polygon. See fill-rule property in SVG for details. Possible values are nonzero
1169 or evenodd. Default value when omitted is nonzero.</li>
1170 <li>
1171 The two length values represent <strong>xi</strong> and <strong>yi</strong> -
1172 the <strong>x</strong> and <strong>y</strong> axis coordinates of the i-th vertex of the polygon.
1173 </li>
1174 </ul>
1175 <p>
1176 If the polygon is not closed the user-agent will automatically add a new vertex
1177 at the end.</p>
1178 <br/>
1179 </dd>
1180 </dl>
1182 <h4 id='referencing-svg-shapes'>Referencing SVG shapes</h4>
1184 <p>An SVG shape can be referenced using the <code>url()</code> syntax. The shape can be
1185 any of the <a href="http://www.w3.org/TR/SVG/shapes.html">SVG basic shapes</a> or a
1186 <a href="http://www.w3.org/TR/SVG/paths.html">path element</a>.</p>
1188 <p>In all cases, percentages are resolved from the border box of the element.</p>
1190 <div class="example">
1191 <code class="html"><pre>
1192 <style>
1193 .in-a-circle {
1194 shape-inside: url(#circle_shape);
1195 }
1197 .in-a-path {
1198 shape-inside: url(#path-shape);
1199 }
1201 </style>
1203 <svg ...>
1204 <circle id="circle_shape" cx="50%" cy="50%" r="50%" />
1205 <path id="path-shape" d="..." />
1206 </svg>
1208 <div class="in-a-circle">...</div>
1209 <div class="in-a-path">...</div>
1210 </pre></code>
1211 </div>
1212 <p>
1213 When using the SVG syntax or referencing SVG elements to define shapes, all the
1214 lengths expressed in percentages are resolved from the border box of the element.
1215 The coordinate system for the shape has its origin on the top-left corner of the
1216 border box with the x-axis running to the right and the y-axis running downwards.
1217 If the SVG element uses unitless coordinate values, they are equivalent to using
1218 'px' units. If the border box of the element is dependent on auto sizing (i.e.,
1219 the element's 'width' or 'height' property is 'auto'), then the percentage values
1220 resolve to 0.
1221 </p>
1222 <!-- End section "Shapes from SVG Syntax -->
1224 <h3 id="shapes-from-image">Shapes from Image</h3>
1226 <div class="issue-marker" data-bug_id="15093" data-bug_status="NEW">
1227 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15093">Bug-15093</a><br />
1228 <div class="issue-details">
1229 <p class="short-desc">
1230 Do we need to provide properties to repeat exclusion images as for the
1231 background-image property?
1232 </p>
1233 </div>
1234 </div>
1236 <div class="issue-marker" data-bug_id="15090" data-bug_status="NEW">
1237 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15090">Bug-15090</a><br />
1238 <div class="issue-details">
1239 <p class="short-desc">
1240 Use the contour() keyword. <img id=shape-me url=foo><style>#shape-me
1241 { shape-outside: contour; }</style> //equal to 'shape-outside: url(foo)'
1242 shape-outside: attr(src as url);
1243 </p>
1244 </div>
1245 </div>
1247 <div class="issue-marker" data-bug_id="15092" data-bug_status="NEW">
1248 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15092">Bug-15092</a>
1249 <div class="issue-details">
1250 <p class="short-desc">Specify what happens with animated images</p>
1251 </div>
1252 </div>
1254 <p>
1255 Another way of defining shapes is by specifying a source image whose alpha channel
1256 is used to compute the inside or outside shape. The shape is computed to be the
1257 path that encloses the area where the opacity of the specified image is greater
1258 than the 'shape-image-threshold' value. If the 'shape-image-threshold' is not specified,
1259 the initial value to be considered is 0.5.
1260 </p>
1262 <p class="note">
1263 Note, images can define cavities and inline flow content should wrap inside
1264 them. In order to avoid that, another exclusion element can be overlaid.
1265 </p>
1267 <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
1268 sequence is used. For <a href="http://www.w3.org/TR/2002/WD-SVG2Reqs-20020422/">SVG</a> images
1269 ([[SVG11]]), the image is rendered without animations applied.</p>
1271 <!-- End section "Shapes from image" -->
1273 <h3 id="declaring-shapes">Declaring Shapes</h3>
1274 <p>
1275 Shapes are declared with the 'shape-outside' or 'shape-inside' properties.
1276 The 'shape-outside' property changes the geometry of an <span>exclusion element</span>'s
1277 <span>exclusion area</span> or or a float element's <span>float area</span>.
1278 If the element is not an <span>exclusion element</span>
1279 (see the 'wrap-flow' property) or a float, then the 'shape-outside' property has no effect.
1280 </p>
1281 <p>
1282 The 'shape-inside' property defines an element's <span>content area</span> and
1283 the element's inline flow content wraps into that shape. The 'shape-inside' property
1284 applies to all block-level elements.
1285 </p>
1287 <h4 id="shape-outside-property">The 'shape-outside' Property</h4>
1289 <table class="propdef">
1290 <tr>
1291 <th>Name:</th>
1292 <td><dfn title="'shape-outside'">shape-outside</dfn></td>
1293 </tr>
1294 <tr>
1295 <th>Value:</th>
1296 <td><var>auto</var> | <var><shape></var> | <var><uri></var></td>
1297 </tr>
1298 <tr>
1299 <th>Initial:</th>
1300 <td>auto</td>
1301 </tr>
1302 <tr>
1303 <th>Applies to:</th>
1304 <td>exclusion elements and floats</td>
1305 </tr>
1306 <tr>
1307 <th>Inherited:</th>
1308 <td>no</td>
1309 </tr>
1310 <tr>
1311 <th>Percentages:</th>
1312 <td>N/A</td>
1313 </tr>
1314 <tr>
1315 <th>Media:</th>
1316 <td>visual</td>
1317 </tr>
1318 <tr>
1319 <th>Computed value:</th>
1320 <td>computed lengths for <shape>, the absolute URI for <uri>, otherwise as specified</td>
1321 </tr>
1322 </table>
1324 <p>The values of this property have the following meanings:</p>
1325 <dl>
1326 <dt><dfn title="'shape-outside'!!'auto'">auto</dfn></dt>
1327 <dd>The shape is computed based on the border box of the element.</dd>
1328 </dl>
1329 <dl>
1330 <dt><dfn title="'shape-outside'!!'<shape>'"><shape></dfn></dt>
1331 <dd>
1332 The shape is computed based on the values of one of 'rectangle', 'circle', 'ellipse'
1333 or 'polygon'.
1334 </dd>
1335 </dl>
1336 <dl>
1337 <dt><dfn title="'shape-outside'!!'<uri>'"><uri></dfn></dt>
1338 <dd>
1339 If the <uri> references an SVG shape element, that element defines the shape.
1340 Otherwise, if the <uri> references an image, the shape is extracted and computed
1341 based on the alpha channel of the specified image.
1343 If the <uri> does not reference an SVG shape element or an image, the
1344 effect is as if the value 'auto' had been specified.
1345 </dd>
1346 </dl>
1348 <div class='figure'>
1349 <img alt="arbitrary shapes for excluions. Illustrates how content flows around shapes" src="images/shapes-exclusions.png" width="70%"/>
1350 <p class="caption">Arbitrary shapes for exclusions</p>
1351 </div>
1353 <div>
1354 <p>The above figure shows how 'shape-outside' shapes impact the exclusion areas.
1355 The red box represents an element's content box and 'A', 'B', 'C' and 'C'
1356 represent exclusions with a complex shape and their 'wrap-flow' property set
1357 to 'both', 'start', 'end' and 'clear', respectively.</p>
1359 <p>As illustrated in the picture, when an exclusion allows wrapping on all sides,
1360 text can flow inside 'holes' in the exclusion (as for exclusion 'A'). Otherwise,
1361 the exclusion clears the area on the side(s) defined by wrap flow, as illustrated
1362 for 'B', 'C' and 'D' above.</p>
1363 </div>
1364 <!-- End section "The shape-outside Property" -->
1366 <h4 id="shape-inside-property">The 'shape-inside' Property</h4>
1367 <p>
1368 The 'shape-inside' modifies the shape of the inner inline flow content from rectangular
1369 content box to an arbitrary geometry.
1370 </p>
1372 <table class="propdef">
1373 <tr>
1374 <th>Name:</th>
1375 <td><dfn title="'shape-inside'">shape-inside</dfn></td>
1376 </tr>
1377 <tr>
1378 <th>Value:</th>
1379 <td><var>outside-shape</var> | <var>auto</var> | <var><shape></var> | <var><uri></var></td>
1380 </tr>
1381 <tr>
1382 <th>Initial:</th>
1383 <td>outside-shape</td>
1384 </tr>
1385 <tr>
1386 <th>Applies to:</th>
1387 <td>block-level elements</td>
1388 </tr>
1389 <tr>
1390 <th>Inherited:</th>
1391 <td>no</td>
1392 </tr>
1393 <tr>
1394 <th>Percentages:</th>
1395 <td>N/A</td>
1396 </tr>
1397 <tr>
1398 <th>Media:</th>
1399 <td>visual</td>
1400 </tr>
1401 <tr>
1402 <th>Computed value:</th>
1403 <td>computed lengths for <shape>, the absolute URI for <uri>, otherwise as specified</td>
1404 </tr>
1405 </table>
1406 <p>The values of this property have the following meanings:</p>
1407 <dl>
1408 <dt><dfn title="'shape-inside'!!'outside-shape'">outside-shape</dfn></dt>
1409 <dd>
1410 The shape is computed based on the computed value of the 'shape-outside' property.
1411 </dd>
1412 </dl>
1413 <dl>
1414 <dt><dfn title="'shape-inside'!!'auto'">auto</dfn></dt>
1415 <dd>
1416 The shape is computed based on the content box of the element.
1417 </dd>
1418 </dl>
1419 <dl>
1420 <dt><dfn title="'shape-inside'!!'<shape>'"><shape></dfn></dt>
1421 <dd>
1422 The shape is computed based on the values of one of 'rectangle',' circle', 'ellipse'
1423 or 'polygon'.
1424 </dd>
1425 </dl>
1426 <dl>
1427 <dt><dfn title="'shape-inside'!!'<uri>'"><uri></dfn></dt>
1428 <dd>
1429 If the <uri> references an SVG shape element, that element defines the shape.
1430 Otherwise, if the <uri> references an image, the shape is extracted and computed
1431 based on the alpha channel of the specified image.
1433 If the <uri> does not reference an SVG shape element or an image, the
1434 effect is as if the value 'auto' had been specified.
1435 </dd>
1436 </dl>
1438 <p>The 'shape-inside' property applies to floats.</p>
1440 <p>The 'shape-inside' property may not apply on some elements such as elements with a
1441 computed 'display' value of 'table'.</p>
1443 <!-- End section "The shape-inside property" -->
1444 <h4 id="shape-image-threshold-property">The 'shape-image-threshold' Property</h4>
1447 <p>
1448 The 'shape-image-threshold' defines the alpha channel threshold used to extract
1449 the shape using an image. A value of 0.5 means that all the pixels that are more
1450 than 50% transparent define the path of the exclusion shape. The 'shape-image-threshold'
1451 applies to both 'shape-outside' and 'shape-inside'.
1452 </p>
1453 <p class="note">
1454 The specified value of 'shape-image-threshold' is applied to both images used for
1455 'shape-outside' and 'shape-inside'.
1456 </p>
1458 <table class="propdef">
1459 <tr>
1460 <th>Name:</th>
1461 <td><dfn title="'shape-image-threshold'">shape-image-threshold</dfn></td>
1462 </tr>
1463 <tr>
1464 <th>Value:</th>
1465 <td><var><alphavalue></var></td>
1466 </tr>
1467 <tr>
1468 <th>Initial:</th>
1469 <td>0.5</td>
1470 </tr>
1471 <tr>
1472 <th>Applies to:</th>
1473 <td>block-level elements</td>
1474 </tr>
1475 <tr>
1476 <th>Inherited:</th>
1477 <td>no</td>
1478 </tr>
1479 <tr>
1480 <th>Percentages:</th>
1481 <td>alpha channel of the image specified by <uri></td>
1482 </tr>
1483 <tr>
1484 <th>Media:</th>
1485 <td>visual</td>
1486 </tr>
1487 <tr>
1488 <th>Computed value:</th>
1489 <td>The same as the specified value after clipping the <alphavalue> to the range [0.0,1.0].</td>
1490 </tr>
1491 </table>
1492 <p>The values of this property have the following meanings:</p>
1493 <dl>
1494 <dt><dfn title="'shape-image-threshold'!!'<alphavalue>'"><alphavalue></dfn></dt>
1495 <dd>
1496 A <number> value used to set the threshold used for extracting a shape from
1497 an image. Any values outside the range 0.0 (fully transparent) to 1.0 (fully opaque)
1498 will be clamped to this range.
1499 </dd>
1500 </dl>
1501 <!-- End section "The shape-image-threshold property" -->
1502 <!--
1503 <h4 id="shape-shorthand-property">The 'shape' Shorthand Property</h4>
1505 <table class="propdef">
1506 <tr>
1507 <th>Name:</th>
1508 <td><dfn title="'shape'">shape</dfn></td>
1509 </tr>
1510 <tr>
1511 <th>Value:</th>
1512 <td><var><shape-outside></var> [ / <var><shape-inside></var> ] || <var><shape-image-threshold></var></td>
1513 </tr>
1514 <tr>
1515 <th>Initial:</th>
1516 <td>see individual properties</td>
1517 </tr>
1518 <tr>
1519 <th>Applies to:</th>
1520 <td>block-level elements</td>
1521 </tr>
1522 <tr>
1523 <th>Inherited:</th>
1524 <td>no</td>
1525 </tr>
1526 <tr>
1527 <th>Percentages:</th>
1528 <td>N/A</td>
1529 </tr>
1530 <tr>
1531 <th>Media:</th>
1532 <td>visual</td>
1533 </tr>
1534 <tr>
1535 <th>Computed value:</th>
1536 <td>see individual properties</td>
1537 </tr>
1538 </table>
1539 <p>
1540 The 'shape' property is a shorthand property for setting the individual shape properties
1541 at the same place in a style sheet.
1542 </p>
1544 <div class="example">
1545 <p>Style declaration using the 'shape' shorthand property.</p>
1546 <pre><code class="html">
1547 <style type="text/css">
1548 .shape {
1549 shape: rectangle(50px, 50px, 200px, 100px) / url("shape_image.png") 0.7;
1550 }
1551 </style>
1552 </code></pre>
1553 </div>
1554 <p class="issue">The example above must be finished.</p>
1556 -->
1557 <!-- End section "Shape Shorthand property -->
1558 <!-- End section "Declaring Shapes" -->
1560 <p>The shape properties apply to
1561 <!-- End section "Shapes" -->
1562 <h2 id="conformance">Conformance</h2>
1563 <h3 id="conventions">Document Conventions</h3>
1564 <p>
1565 Conformance requirements are expressed with a combination of descriptive assertions
1566 and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”,
1567 “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the
1568 normative parts of this document are to be interpreted as described in RFC 2119.
1569 However, for readability, these words do not appear in all uppercase letters in
1570 this specification.
1571 </p>
1572 <p>
1573 All of the text of this specification is normative except sections explicitly marked
1574 as non-normative, examples, and notes. [[!RFC2119]]
1575 </p>
1576 <p>
1577 Examples in this specification are introduced with the words “for example” or are
1578 set apart from the normative text with <code>class="example"</code>, like this:
1579 </p>
1580 <div class="example">
1581 <p>This is an example of an informative example.</p>
1582 </div>
1583 <p>
1584 Informative notes begin with the word “Note” and are set apart from the normative
1585 text with <code>class="note"</code>, like this:
1586 </p>
1587 <p class="note">Note, this is an informative note.</p>
1588 <h3 id="conformance-classes">Conformance Classes</h3>
1589 <p>Conformance to CSS Exclusions and Shapes is defined for three conformance classes:</p>
1590 <dl>
1591 <dt><dfn title="style sheet!!as conformance class">style sheet</dfn></dt>
1592 <dd>
1593 A <a href="http://www.w3.org/TR/CSS21/conform.html#style-sheet">CSS style sheet</a>.</dd>
1594 <dt><dfn>renderer</dfn></dt>
1595 <dd>
1596 A <a href="http://www.w3.org/TR/CSS21/conform.html#user-agent">UA</a> that interprets
1597 the semantics of a style sheet and renders documents that use them.</dd>
1598 <dt><dfn id="authoring-tool">authoring tool</dfn></dt>
1599 <dd>
1600 A <a href="http://www.w3.org/TR/CSS21/conform.html#user-agent">UA</a> that writes
1601 a style sheet.</dd>
1602 </dl>
1603 <p>
1604 A style sheet is conformant to CSS Exclusions and Shapes if all of its declarations
1605 that use properties defined in this module have values that are valid according
1606 to the generic CSS grammar and the individual grammars of each property as given
1607 in this module.
1608 </p>
1609 <p>
1610 A renderer is conformant to CSS Exclusions and Shapes if, in addition to interpreting
1611 the style sheet as defined by the appropriate specifications, it supports all the
1612 features defined by CSS Exclusions and Shapes by parsing them correctly and rendering
1613 the document accordingly. However, the inability of a UA to correctly render a document
1614 due to limitations of the device does not make the UA non-conformant. (For example,
1615 a UA is not required to render color on a monochrome monitor.)
1616 </p>
1617 <p>
1618 An authoring tool is conformant to CSS Exclusions and Shapes if it writes style
1619 sheets that are syntactically correct according to the generic CSS grammar and the
1620 individual grammars of each feature in this module, and meet all other conformance
1621 requirements of style sheets as described in this module.
1622 </p>
1623 <h3 id="partial">
1624 Partial Implementations</h3>
1625 <p>
1626 So that authors can exploit the forward-compatible parsing rules to assign fallback
1627 values, CSS renderers <strong>must</strong> treat as invalid (and <a href="http://www.w3.org/TR/CSS21/conform.html#ignore">
1628 ignore as appropriate</a>) any at-rules, properties, property values, keywords,
1629 and other syntactic constructs for which they have no usable level of support. In
1630 particular, user agents <strong>must not</strong> selectively ignore unsupported
1631 component values and honor supported values in a single multi-value property declaration:
1632 if any value is considered invalid (as unsupported values must be), CSS requires
1633 that the entire declaration be ignored.
1634 </p>
1635 <h3 id="experimental">
1636 Experimental Implementations</h3>
1637 <p>
1638 To avoid clashes with future CSS features, the CSS2.1 specification reserves a <a
1639 href="http://www.w3.org/TR/CSS21/syndata.html#vendor-keywords">prefixed syntax</a>
1640 for proprietary and experimental extensions to CSS.</p>
1641 <p>
1642 Prior to a specification reaching the Candidate Recommendation stage in the W3C
1643 process, all implementations of a CSS feature are considered experimental. The CSS
1644 Working Group recommends that implementations use a vendor-prefixed syntax for such
1645 features, including those in W3C Working Drafts. This avoids incompatibilities with
1646 future changes in the draft.
1647 </p>
1648 <h3 id="testing">
1649 Non-Experimental Implementations</h3>
1650 <p>
1651 Once a specification reaches the Candidate Recommendation stage, non-experimental
1652 implementations are possible, and implementors should release an unprefixed implementation
1653 of any CR-level feature they can demonstrate to be correctly implemented according
1654 to spec.
1655 </p>
1656 <p>
1657 To establish and maintain the interoperability of CSS across implementations, the
1658 CSS Working Group requests that non-experimental CSS renderers submit an implementation
1659 report (and, if necessary, the testcases used for that implementation report) to
1660 the W3C before releasing an unprefixed implementation of any CSS features. Testcases
1661 submitted to W3C are subject to review and correction by the CSS Working Group.
1662 </p>
1663 <p>
1664 Further information on submitting testcases and implementation reports can be found
1665 from on the CSS Working Group's website at <a href="http://www.w3.org/Style/CSS/Test/">
1666 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">
1667 public-css-testsuite@w3.org</a> mailing list.
1668 </p>
1669 <h3 id="cr-exit-criteria">
1670 CR Exit Criteria</h3>
1671 <p>
1672 For this specification to be advanced to Proposed Recommendation, there must be
1673 at least two independent, interoperable implementations of each feature. Each feature
1674 may be implemented by a different set of products, there is no requirement that
1675 all features be implemented by a single product. For the purposes of this criterion,
1676 we define the following terms:
1677 </p>
1678 <dl>
1679 <dt>independent </dt>
1680 <dd>
1681 each implementation must be developed by a different party and cannot share, reuse,
1682 or derive from code used by another qualifying implementation. Sections of code
1683 that have no bearing on the implementation of this specification are exempt from
1684 this requirement.</dd>
1685 <dt>interoperable</dt>
1686 <dd>
1687 passing the respective test case(s) in the official CSS test suite, or, if the implementation
1688 is not a Web browser, an equivalent test. Every relevant test in the test suite
1689 should have an equivalent test created if such a user agent (UA) is to be used to
1690 claim interoperability. In addition if such a UA is to be used to claim interoperability,
1691 then there must one or more additional UAs which can also pass those equivalent
1692 tests in the same way for the purpose of interoperability. The equivalent tests
1693 must be made publicly available for the purposes of peer review.
1694 </dd>
1695 <dt>implementation</dt>
1696 <dd>
1697 a user agent which:
1698 <ol class="inline">
1699 <li>implements the specification.</li>
1700 <li>is available to the general public. The implementation may be a shipping product
1701 or other publicly available version (i.e., beta version, preview release, or “nightly
1702 build”). Non-shipping product releases must have implemented the feature(s) for
1703 a period of at least one month in order to demonstrate stability.</li>
1704 <li>is not experimental (i.e., a version specifically designed to pass the test suite
1705 and is not intended for normal usage going forward).</li>
1706 </ol>
1707 </dd>
1708 </dl>
1709 <p>
1710 The specification will remain Candidate Recommendation for at least six months.
1711 </p>
1712 <h2 class="no-num" id="acknowledgments">Acknowledgments</h2>
1713 <p>
1714 This specification is made possible by input from Stephen Zilles, Alexandru Chiculita,
1715 Andrei Bucur, Mihnea Ovidenie, Peter Sorotokin, Virgil Palanciuc, Alan Stearns,
1716 Arno Gourdol, Eugene Veselov, Arron Eicholz, Alex Mogilevsky, Chris Jones, Marcus
1717 Mielke, and the CSS Working Group members.
1718 </p>
1719 <h2 class="no-num" id="references">References</h2>
1720 <h3 class="no-num" id="normative-references">Normative references</h3>
1721 <!--normative-->
1722 <h3 class="no-num" id="other-references">Other references</h3>
1723 <!--informative-->
1724 <h2 class="no-num" id="index">Index</h2>
1725 <!--index-->
1726 <h2 class="no-num" id="property-index">Property index</h2>
1727 <!-- properties -->
1729 <h2 class="no-num" id="change-log">Change Log</h2>
1731 <h3>Since <a href="http://www.w3.org/TR/2011/WD-css3-exclusions-20111213/">December 13th 2011</h3>
1732 <ul>
1733 <li>Clarified processing model</li>
1734 <li>Clarified interaction with floats</li>
1735 </ul>
1736 </body>
1737 </html>
1738 <!-- Keep this comment at the end of the file
1739 Local variables:
1740 mode: sgml
1741 sgml-declaration:"~/SGML/HTML4.decl"
1742 sgml-default-doctype-name:"html"
1743 sgml-minimize-attributes:t
1744 sgml-nofill-elements:("pre" "style" "br")
1745 sgml-live-element-indicator:t
1746 sgml-omittag:nil
1747 sgml-shorttag:nil
1748 sgml-namecase-general:t
1749 sgml-general-insert-case:lower
1750 sgml-always-quote-attributes:t
1751 sgml-indent-step:nil
1752 sgml-indent-data:t
1753 sgml-parent-document:nil
1754 sgml-exposed-tags:nil
1755 sgml-local-catalogs:nil
1756 sgml-local-ecat-files:nil
1757 End:
1758 -->
