Mon, 23 Apr 2012 22:27:12 -0700
added CSSRegionStyleRule to OM section
stearns@5447 | 1 | <!DOCTYPE html public '-//W3C//DTD HTML 4.01//EN' |
vhardy@3547 | 2 | 'http://www.w3.org/TR/html4/strict.dtd'> |
vhardy@3547 | 3 | <html lang="en"> |
vhardy@3547 | 4 | <head profile="http://www.w3.org/2006/03/hcard"> |
vhardy@3547 | 5 | <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> |
vhardy@3548 | 6 | <title>CSS Regions Module Level 3</title> |
vhardy@5539 | 7 | <link rel="stylesheet" type="text/css" href="../shared/style/default.css"> |
vhardy@2779 | 8 | |
vhardy@3660 | 9 | <style type="text/css"> |
vhardy@3973 | 10 | #region-style-example p, #region-style-example pre { |
vhardy@3973 | 11 | clear: both; |
vhardy@3973 | 12 | } |
vhardy@3973 | 13 | |
vhardy@3973 | 14 | #region_styling_illustration { |
vhardy@3973 | 15 | margin: 0px auto; |
vhardy@3973 | 16 | width: 70ex; |
vhardy@3973 | 17 | } |
vhardy@3660 | 18 | </style> |
vhardy@3973 | 19 | |
vhardy@3973 | 20 | <link rel="stylesheet" type="text/css" |
bert@3953 | 21 | href="http://www.w3.org/StyleSheets/TR/W3C-ED.css"> |
vhardy@3972 | 22 | |
vhardy@5556 | 23 | <link rel="stylesheet" type="text/css" |
vhardy@5556 | 24 | href="../shared/style/issues.css"> |
vhardy@5556 | 25 | |
vhardy@5539 | 26 | <link id="st" href="../shared/style/alternate-spec-style.css" rel="stylesheet" |
vhardy@4119 | 27 | type="text/css" title="alternate spec style"> |
vhardy@2779 | 28 | </head> |
vhardy@2779 | 29 | |
vhardy@3547 | 30 | |
vhardy@2779 | 31 | <body> |
vhardy@2779 | 32 | <div class="head" id="div-head"> |
vhardy@4119 | 33 | <p><a href="http://www.w3.org/"><img id="mobile-logo" alt="W3C" height="53" src= |
vhardy@4119 | 34 | "http://www.w3.org/2008/site/images/logo-w3c-mobile-lg" width="90"></a> |
vhardy@4119 | 35 | |
vhardy@4119 | 36 | |
vhardy@2779 | 37 | <!--begin-logo--> |
vhardy@2779 | 38 | |
vhardy@4119 | 39 | <p><a href="http://www.w3.org/"><img id="logo" alt="W3C" height="48" src= |
vhardy@2779 | 40 | "http://www.w3.org/Icons/w3c_home" width="72"></a> <!--end-logo--></p> |
vhardy@2779 | 41 | |
bert@3938 | 42 | <h1 id="css-regions-module">CSS Regions Module Level 3</h1> |
vhardy@2779 | 43 | |
bert@3938 | 44 | <h2 class="no-num no-toc" id="longstatus-date">[LONGSTATUS] |
vhardy@2779 | 45 | [DATE]</h2> |
vhardy@2779 | 46 | |
vhardy@2779 | 47 | <dl> |
vhardy@2779 | 48 | <dt>This version:</dt> |
vhardy@2779 | 49 | |
vhardy@2779 | 50 | <dd><a href= |
vhardy@3073 | 51 | "[VERSION]">http://www.w3.org/csswg/css3-regions</a></dd> |
vhardy@2779 | 52 | |
vhardy@2779 | 53 | <dt>Latest version:</dt> |
vhardy@2779 | 54 | |
vhardy@2779 | 55 | <dd><a href= |
bert@3938 | 56 | "http://www.w3.org/TR/css3-regions/">http://www.w3.org/TR/css3-regions/</a></dd> |
vhardy@2779 | 57 | |
vhardy@2779 | 58 | <dt>Previous version:</dt> |
vhardy@2779 | 59 | |
vhardy@4397 | 60 | <dd><a href="http://www.w3.org/TR/2011/WD-css3-regions-20111129/">http://www.w3.org/TR/2011/WD-css3-regions-20111129/</a></dd> |
vhardy@4395 | 61 | |
vhardy@2779 | 62 | <dt>Editors:</dt> |
vhardy@2779 | 63 | |
vhardy@2779 | 64 | <dd class="vcard"><span class="fn">Vincent Hardy</span>, |
vhardy@2779 | 65 | <span class="org">Adobe Systems, Inc.</span>, <span class= |
vhardy@2779 | 66 | "email">vhardy@adobe.com</span></dd> |
vhardy@3073 | 67 | <dd class="vcard"><span class="fn">Alex Mogilevsky</span>, |
vhardy@3073 | 68 | <span class="org">Microsoft</span>, <span class= |
vhardy@3073 | 69 | "email">alexmog@microsoft.com</span></dd> |
vhardy@4679 | 70 | |
vhardy@4679 | 71 | <dt>Issues List:</dt> |
stearns@5453 | 72 | <dd><a href="https://www.w3.org/Bugs/Public/buglist.cgi?product=CSS&component=Regions&resolution=---">Bugzilla Bugs for CSS regions</a></dd> |
vhardy@4679 | 73 | <dt>Discussion:</dt> |
vhardy@4679 | 74 | <dd><a href="http://lists.w3.org/Archives/Public/www-style/">www-style@w3.org</a> with subject line "<code>[css3-regions] message topic</code>"</dd> |
vhardy@2779 | 75 | </dl><!--begin-copyright--><!--end-copyright--> |
vhardy@2779 | 76 | <hr title="Separator for header"> |
vhardy@2779 | 77 | </div> |
vhardy@4395 | 78 | |
vhardy@2779 | 79 | <h2 class="no-num no-toc" id="abstract">Abstract</h2> |
vhardy@3277 | 80 | |
vhardy@3301 | 81 | <p>The CSS regions module allows content to flow across multiple areas |
vhardy@3549 | 82 | called regions. The regions are not necessarily contiguous in the document order. |
vhardy@3301 | 83 | The CSS regions module provides an advanced content flow mechanism, which |
vhardy@2791 | 84 | can be combined with positioning schemes as defined by other CSS modules |
vhardy@3073 | 85 | such as the Multi-Column Module [[CSS3COL]] or the Grid Layout Module |
vhardy@2791 | 86 | [[CSS3-GRID-LAYOUT]] to position the regions where content flows.</p> |
vhardy@2779 | 87 | |
vhardy@2945 | 88 | <h2 class="no-num no-toc" id="status-of-this-document">Status of this |
vhardy@3977 | 89 | document</h2> |
vhardy@3977 | 90 | |
vhardy@4314 | 91 | <p class="big note"><span class="note-prefix">Note </span>This document uses an experimental style |
vhardy@3977 | 92 | sheet. We welcome your feedback on the styles at |
vhardy@3977 | 93 | <a href="mailto:site-comments@w3.org">site-comments@w3.org</a>.</p> |
vhardy@3977 | 94 | |
vhardy@3977 | 95 | <!--begin-status--> |
vhardy@2779 | 96 | <p><em>This section describes the status of this document at the time of |
vhardy@2779 | 97 | its publication. Other documents may supersede this document. A list of |
vhardy@2779 | 98 | current W3C publications and the latest revision of this technical report |
vhardy@2779 | 99 | can be found in the <a href="http://www.w3.org/TR/">W3C technical reports |
vhardy@2779 | 100 | index at http://www.w3.org/TR/.</a></em></p> |
vhardy@2779 | 101 | |
vhardy@2779 | 102 | <p>This is a public copy of the editors' draft. It is provided for |
vhardy@2779 | 103 | discussion only and may change at any moment. Its publication here does not |
vhardy@2779 | 104 | imply endorsement of its contents by W3C. Don't cite this document other |
vhardy@2779 | 105 | than as work in progress.</p> |
vhardy@2779 | 106 | |
vhardy@2779 | 107 | <p>The archived public mailing list www-style@w3.org is preferred for |
vhardy@2779 | 108 | discussion of this specification. When sending e-mail, please put the text |
vhardy@2779 | 109 | "css3-regions" in the subject, preferably like this: "[css3-regions] |
vhardy@2779 | 110 | …summary of comment…"</p> |
bert@3938 | 111 | <!--end-status--> |
vhardy@2779 | 112 | |
bert@3953 | 113 | <p>This draft is related to the drafts about Multi-column Layout |
bert@3953 | 114 | [[CSS3COL]], Grid Layout [[CSS3GRID]], Flexible Box Layout |
bert@3953 | 115 | [[CSS3-FLEXBOX]], and Template Layout [[CSS3LAYOUT]].</p> |
vhardy@2779 | 116 | |
vhardy@2945 | 117 | <h2 class="no-num no-toc" id="table-of-contents">Table of contents</h2> |
vhardy@2779 | 118 | <!--begin-toc--><!--end-toc--> |
vhardy@2779 | 119 | |
vhardy@2779 | 120 | <h2 id="introduction">Introduction</h2> |
vhardy@2779 | 121 | |
vhardy@3073 | 122 | <p><em>This section is non-normative.</em></p> |
vhardy@4395 | 123 | |
stearns@5445 | 124 | <p>Displaying the complex layouts |
stearns@5445 | 125 | of a typical magazine, newspaper, or textbook on the web |
stearns@5445 | 126 | requires capabilities beyond those available in existing CSS modules. |
stearns@5445 | 127 | Dynamic magazine layout in particular requires flexibility |
stearns@5445 | 128 | in placement of boxes for content flows. |
stearns@5445 | 129 | This is the purpose of the CSS regions module.</p> |
vhardy@4395 | 130 | |
vhardy@4412 | 131 | <div class="issue-marker" data-bug_id="15733" data-bug_status="NEW"> |
vhardy@4395 | 132 | <a href= |
vhardy@4404 | 133 | "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15733">Bug-15733</a> |
vhardy@2779 | 134 | |
vhardy@4395 | 135 | <div class="issue-details"> |
vhardy@4395 | 136 | <p class="short-desc">Should the region specification define a |
vhardy@4395 | 137 | mechanism to create blocks that can be regions with CSS |
vhardy@4395 | 138 | syntax?</p> |
vhardy@4395 | 139 | </div> |
vhardy@4395 | 140 | </div> |
vhardy@2779 | 141 | |
stearns@5445 | 142 | <p>For more complex layouts, |
stearns@5445 | 143 | content needs to flow from one area of the page to the next |
stearns@5445 | 144 | without limitation on the areas' sizes and positions. |
stearns@5445 | 145 | These arbitrary areas are the target of specific content flows |
stearns@5445 | 146 | which this document calls <span>named flows</span>. |
stearns@5445 | 147 | Each <span>named flow</span> can be associated |
stearns@5445 | 148 | with a set of CSS Regions called a region chain. |
stearns@5445 | 149 | CSS Regions are based on the rectangular geometry |
stearns@5445 | 150 | of the CSS box model. |
stearns@5445 | 151 | Elements in a <span>named flow</span> |
stearns@5445 | 152 | are taken out of the normal visual formatting |
stearns@5445 | 153 | and rendered in a chain of CSS Regions.</p> |
stearns@5445 | 154 | |
stearns@5445 | 155 | <h3 id="named-flows-and-regions">Named flows and region chains</h3> |
vhardy@2779 | 156 | |
vhardy@2779 | 157 | <p>Consider the layout illustrated in figure 1.</p> |
vhardy@2779 | 158 | |
vhardy@4395 | 159 | |
vhardy@2779 | 160 | <div class="figure"> |
vhardy@5373 | 161 | <img src="images/intro-example-layout.svg" width="400" alt= |
vhardy@2779 | 162 | "multiple chained regions which should receive content from a flow"> |
vhardy@2779 | 163 | |
vhardy@2779 | 164 | <p class="caption">Layout requiring sophisticated content flow</p> |
vhardy@2779 | 165 | </div> |
vhardy@4395 | 166 | |
stearns@5445 | 167 | <p>The designer's intent is |
stearns@5445 | 168 | to position an image in box 'A' |
stearns@5445 | 169 | and to flow an article's content |
stearns@5445 | 170 | from box '1' through boxes '2', '3' and '4'. |
stearns@5445 | 171 | Note that the second box should have two columns, |
stearns@5445 | 172 | and the image is not contained in the article. |
stearns@5445 | 173 | Box '4' should auto-size to render |
stearns@5445 | 174 | the remainder of the article content |
stearns@5445 | 175 | that did not fit in the earlier boxes.</p> |
vhardy@2779 | 176 | |
stearns@5423 | 177 | <p>Figure 2 shows an example |
stearns@5423 | 178 | of the intended visual rendering |
stearns@5423 | 179 | of the content.</p> |
alexmog@2565 | 180 | |
vhardy@2779 | 181 | <div class="figure"> |
vhardy@2779 | 182 | <img src="images/regions-intro-rendering.png" width="450" alt= |
vhardy@2779 | 183 | "Sample rendering showing a single thread of text flowing through a chain of regions"> |
alexmog@2565 | 184 | |
vhardy@2779 | 185 | <p class="caption">Sample rendering for desired layout</p> |
vhardy@2779 | 186 | </div> |
alexmog@2565 | 187 | |
vhardy@3940 | 188 | |
stearns@5445 | 189 | <p>There is no existing mechanism in CSS |
stearns@5445 | 190 | to associate the content with these boxes |
stearns@5445 | 191 | arranged in this manner |
stearns@5423 | 192 | so that content flows as intended. |
stearns@5423 | 193 | The CSS regions module properties provide that mechanism.</p> |
vhardy@4413 | 194 | |
stearns@5445 | 195 | <p>The following example illustrates |
vhardy@5490 | 196 | how the content of an <code><article></code> element |
stearns@5445 | 197 | becomes a <span>named flow</span> |
stearns@5445 | 198 | and how boxes marked with 'region1', 'region2', 'region3' and 'region4' IDs |
stearns@5445 | 199 | become CSS Regions that consume the 'article_flow' content.</p> |
alexmog@2565 | 200 | |
vhardy@2779 | 201 | <div class="example"> |
stearns@5423 | 202 | <pre> |
vhardy@2779 | 203 | <style> |
vhardy@5490 | 204 | article { |
stearns@5445 | 205 | <strong>flow-into: article_flow;</strong> |
stearns@5445 | 206 | } |
alexmog@2565 | 207 | |
stearns@5445 | 208 | #region1, #region2, #region3, #region4 { |
stearns@5445 | 209 | <strong>flow-from: article_flow;</strong> |
stearns@5445 | 210 | } |
vhardy@2779 | 211 | </style> |
stearns@5423 | 212 | </pre> |
vhardy@2779 | 213 | </div> |
vhardy@3301 | 214 | |
stearns@5423 | 215 | <p>The 'article_flow' value on the 'flow-into' property |
stearns@5445 | 216 | directs the <code>article</code> element |
stearns@5423 | 217 | to the 'article_flow' <span>named flow</span>. |
stearns@5575 | 218 | Setting the 'flow-from' property on block containers |
stearns@5445 | 219 | to 'article_flow' makes them CSS Regions |
stearns@5445 | 220 | and associates the resulting region chain |
stearns@5423 | 221 | with the <span>named flow</span>: |
stearns@5423 | 222 | the flow is ''poured'' |
stearns@5445 | 223 | into the region chain.</p> |
alexmog@2565 | 224 | |
stearns@5445 | 225 | <p>See <a href="#intro-example-code">Appendix A</a> |
stearns@5445 | 226 | for sample code using grid layout |
stearns@5445 | 227 | that implements this example</p> |
vhardy@5373 | 228 | |
stearns@5445 | 229 | <div class="note"><span class="note-prefix">Note </span> |
stearns@5445 | 230 | <p><strong>CSS Regions are independent from layout</strong></p> |
stearns@5445 | 231 | |
stearns@5445 | 232 | <p>Any of the CSS layout facilities can be used |
stearns@5445 | 233 | to create, position and size boxes that can become CSS Regions. |
stearns@5445 | 234 | Using a grid layout [[CSS3-GRID-LAYOUT]] is just an example. |
stearns@5445 | 235 | The example could use |
stearns@5445 | 236 | a flexible box layout [[CSS3-FLEXBOX]] instead.</p> |
stearns@5445 | 237 | <p>The CSS regions specification does not |
stearns@5445 | 238 | define a layout mechanism |
stearns@5445 | 239 | and is meant to integrate |
stearns@5445 | 240 | with existing and future CSS layout facilities.</p> |
vhardy@5373 | 241 | |
stearns@5445 | 242 | <p><strong>CSS Regions do not have to be elements</strong></p> |
stearns@5445 | 243 | |
stearns@5445 | 244 | <p>The CSS regions module is independent |
stearns@5445 | 245 | of the layout of boxes and |
stearns@5445 | 246 | the mechanism used to create them. |
stearns@5445 | 247 | For simplicity, |
stearns@5445 | 248 | our example code in <a href="#intro-example-code">Appendix A</a> |
stearns@5445 | 249 | uses elements to define the boxes.</p> |
vhardy@5373 | 250 | |
vhardy@5373 | 251 | |
stearns@5445 | 252 | <p>While the example uses elements for CSS Regions |
stearns@5445 | 253 | (since [[CSS3-GRID-LAYOUT]] requires elements to create grid items) |
stearns@5445 | 254 | it is important to note that |
stearns@5445 | 255 | this is not required. |
stearns@5445 | 256 | CSS Regions can be pseudo-elements, |
stearns@5445 | 257 | such as '::before' and '::after'. |
stearns@5445 | 258 | The only requirement |
stearns@5445 | 259 | for an element or pseudo-element |
stearns@5445 | 260 | to become a CSS Region |
stearns@5445 | 261 | is that it needs to be subject |
stearns@5445 | 262 | to CSS styling |
stearns@5445 | 263 | to receive the 'flow-from' property. |
stearns@5445 | 264 | The CSS page template module |
stearns@5445 | 265 | (see [[CSS3-PAGE-TEMPLATE]]) |
stearns@5445 | 266 | proposes another mechanism |
stearns@5445 | 267 | to create stylable boxes that can become CSS Regions |
stearns@5445 | 268 | with the <code class="css">@slot</code> syntax.</p> |
vhardy@5373 | 269 | </div> |
vhardy@5373 | 270 | |
stearns@5445 | 271 | <h3 id="region-styling">CSS Region names and styling</h3> |
alexmog@2565 | 272 | |
stearns@5445 | 273 | <p>Content can be styled depending on |
stearns@5445 | 274 | the CSS Region it flows into. |
stearns@5445 | 275 | It is an extension |
stearns@5423 | 276 | of pseudo-element styling such as |
stearns@5423 | 277 | <a href="http://www.w3.org/TR/css3-selectors/#first-line"> |
stearns@5423 | 278 | <code class="css">::first-line</code> |
stearns@5423 | 279 | </a> |
stearns@5445 | 280 | which applies a particular style |
stearns@5423 | 281 | to a fragment of content. |
stearns@5445 | 282 | With CSS Region styling, |
stearns@5423 | 283 | additional selectors may apply |
stearns@5445 | 284 | depending on the CSS Region |
stearns@5423 | 285 | into which content flows.</p> |
alexmog@2565 | 286 | |
stearns@5423 | 287 | <p>In our example, |
stearns@5423 | 288 | the designer wants to make |
stearns@5445 | 289 | text flowing into #region1 |
stearns@5423 | 290 | dark blue and bold.</p> |
alexmog@2565 | 291 | |
stearns@5445 | 292 | <p>This design can be expressed as shown below.</p> |
alexmog@2565 | 293 | |
vhardy@2779 | 294 | <div class="example"> |
vhardy@2779 | 295 | <pre> |
vhardy@2779 | 296 | <style> |
vhardy@5489 | 297 | @region #region1 { |
vhardy@5489 | 298 | p { |
vhardy@5489 | 299 | color: #0C3D5F; |
vhardy@5489 | 300 | font-weight: bold; |
vhardy@5489 | 301 | } |
vhardy@5489 | 302 | </style></pre> |
vhardy@2779 | 303 | </div> |
alexmog@2565 | 304 | |
vhardy@5489 | 305 | <p>The <code class="css">@region #region1</code> rule |
stearns@5423 | 306 | limits its selectors to content |
vhardy@5489 | 307 | flowing into <code class="css">#region1</code>. |
stearns@5423 | 308 | The following figure shows how |
stearns@5423 | 309 | the rendering changes |
vhardy@5489 | 310 | if we apply styling specific to <code>#region1</code>. |
stearns@5445 | 311 | Note how less text fits into this box |
stearns@5423 | 312 | now that the 'font-weight' is |
stearns@5423 | 313 | bold instead of normal.</p> |
vhardy@2945 | 314 | |
vhardy@2779 | 315 | <div class="figure"> |
vhardy@2779 | 316 | <img src="images/region-styling.png" width="450" alt= |
vhardy@2779 | 317 | "Illustrate how changing region styling affects the flow of content."> |
alexmog@2565 | 318 | |
vhardy@2779 | 319 | <p class="caption">Different rendering with a different region |
vhardy@2779 | 320 | styling</p> |
vhardy@2779 | 321 | </div> |
alexmog@2565 | 322 | |
vhardy@3272 | 323 | <h2 id="css-regions-concepts">CSS regions concepts</h2> |
alexmog@2565 | 324 | |
vhardy@3267 | 325 | <h3 id="regions">Regions</h3> |
alexmog@2565 | 326 | |
vhardy@4412 | 327 | <div class="issue-marker wrapper"> |
vhardy@4412 | 328 | <div class="issue-marker" data-bug_id="15186" data-bug_status="NEW"> |
vhardy@4395 | 329 | <a href= |
vhardy@4404 | 330 | "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15186">Bug-15186</a> |
vhardy@4395 | 331 | |
vhardy@4395 | 332 | <div class="issue-details"> |
vhardy@4395 | 333 | <p class="short-desc">Is a mechanism to auto-generate regions |
vhardy@4395 | 334 | necessary in order to support reusable style sheets?</p> |
vhardy@4395 | 335 | </div> |
vhardy@4395 | 336 | </div> |
vhardy@4395 | 337 | |
vhardy@4412 | 338 | <div class="issue-marker" data-bug_id="15187" data-bug_status="NEW"> |
vhardy@4412 | 339 | <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15187">Bug-15187</a> |
vhardy@4412 | 340 | <div class="issue-details"> |
vhardy@4412 | 341 | <p class="short-desc">Explain how regions and pages interact. How can regions be placed onto certain pages, and how can they be positiond wrt. pages.</p> |
vhardy@4412 | 342 | </div> |
vhardy@4412 | 343 | </div> |
vhardy@4412 | 344 | </div> |
vhardy@4412 | 345 | |
vhardy@5489 | 346 | <p id="region"> |
stearns@5579 | 347 | A <dfn title="region">CSS Region</dfn> |
stearns@5579 | 348 | is a block container |
stearns@5579 | 349 | that has an associated |
stearns@5579 | 350 | <em><span>named flow</span></em> |
stearns@5579 | 351 | (see the 'flow-from' property).</p> |
vhardy@4395 | 352 | |
vhardy@5489 | 353 | <h3 id="region-chain">Region chain</h3> |
vhardy@5489 | 354 | |
vhardy@5489 | 355 | <p>A <dfn>region chain</dfn> is the sequence of regions that are associated with |
vhardy@5489 | 356 | a <span>named flow</span>. <span title="region">CSS Regions</span> in a |
vhardy@5489 | 357 | region chain receive content from the |
vhardy@5489 | 358 | named flow following their order in the chain. <span title="region">CSS Regions</span> are organized |
vhardy@5489 | 359 | into a <span title="region-chain">region chain</span> |
vhardy@5489 | 360 | according to the document order.</p> |
vhardy@5489 | 361 | |
stearns@5445 | 362 | <h3 id="named-flow">Named flows</h3> |
vhardy@3267 | 363 | |
bert@3938 | 364 | <p>A <dfn>named flow</dfn> is the ordered sequence of elements |
stearns@5445 | 365 | associated with a flow with a given identifier. |
stearns@5445 | 366 | Elements in a <span>named flow</span> are ordered |
vhardy@3267 | 367 | according to the document order.</p> |
vhardy@3267 | 368 | |
stearns@5445 | 369 | <p>Elements are placed into a <span>named flow</span> |
stearns@5445 | 370 | with the 'flow-into' property. |
stearns@5445 | 371 | The elements in a <span>named flow</span> are laid out |
stearns@5445 | 372 | in the <span title="region-chain">region chain</span> |
stearns@5445 | 373 | that is associated with this <span>named flow</span>. |
vhardy@5489 | 374 | </p> |
vhardy@3267 | 375 | |
stearns@5445 | 376 | <p>Content from a <span>named flow</span> |
stearns@5445 | 377 | is broken up between regions |
stearns@5445 | 378 | according to the regions flow breaking rules.</p> |
vhardy@3267 | 379 | |
alexmog@2565 | 380 | |
vhardy@3272 | 381 | <h3 id="regions-flow-breaking-rules">Regions flow breaking rules</h3> |
alexmog@2565 | 382 | |
stearns@5445 | 383 | <p>Breaking a <span>named flow</span> across a region chain |
stearns@5445 | 384 | is similar to breaking a document's content across pages |
stearns@5445 | 385 | (see [[CSS3PAGE]]) |
stearns@5445 | 386 | or a multi-column element's content across column boxes |
stearns@5445 | 387 | (see [[CSS3COL]]). |
stearns@5445 | 388 | One difference is that page boxes are generated |
stearns@5445 | 389 | based on the available content |
stearns@5445 | 390 | whereas a region chain is a set of recipient boxes |
stearns@5445 | 391 | for the <span>named flow</span> content |
stearns@5445 | 392 | whose dynamic generation is not in the scope |
stearns@5445 | 393 | of this specification.</p> |
alexmog@2565 | 394 | |
stearns@5445 | 395 | <p>Each CSS Region in turn |
stearns@5445 | 396 | consumes content from its associated <span>named flow</span>. |
stearns@5445 | 397 | The <span>named flow</span> content is positioned |
stearns@5445 | 398 | in the <dfn title="current-region">current region</dfn> |
stearns@5445 | 399 | until a natural or forced region break occurs, |
stearns@5445 | 400 | at which point the next region |
stearns@5445 | 401 | in the <span title="region-chain">region chain</span> |
stearns@5445 | 402 | becomes the <span title="current-region">current region</span>. |
stearns@5445 | 403 | If there are no more <span>region</span>s |
stearns@5445 | 404 | in the region chain |
stearns@5445 | 405 | and there is still content in the flow, |
stearns@5445 | 406 | the positioning of the remaining content |
stearns@5445 | 407 | is controlled by the 'region-overflow' property |
stearns@5445 | 408 | on the last <span>region</span> in the chain.</p> |
vhardy@5373 | 409 | |
stearns@5445 | 410 | <p>The CSS regions module follows |
stearns@5445 | 411 | the fragmentation rules defined |
stearns@5445 | 412 | in the CSS Fragmentation Module Level 3 |
stearns@5445 | 413 | (see [[!CSS3-BREAK]]).</p> |
vhardy@2945 | 414 | |
alexmog@2565 | 415 | |
vhardy@3272 | 416 | <h2 id="properties-and-rules">Properties and rules</h2> |
alexmog@2565 | 417 | |
vhardy@3262 | 418 | <h3 id="the-flow-into-property">The 'flow-into' property</h3> |
alexmog@2565 | 419 | |
stearns@5576 | 420 | <div class="issue-marker wrapper"> |
vhardy@4412 | 421 | <div class="issue-marker" data-bug_id="15811" data-bug_status="NEW"> |
vhardy@4398 | 422 | <a href= |
vhardy@4404 | 423 | "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15811">Bug-15811</a> |
vhardy@4398 | 424 | |
vhardy@4398 | 425 | <div class="issue-details"> |
vhardy@4398 | 426 | <p class="short-desc">Creating a named flow from external resource</p> |
vhardy@4398 | 427 | </div> |
vhardy@4398 | 428 | </div> |
stearns@5576 | 429 | <div class="issue-marker" data-bug_id="16002" data-bug_status="NEW"> |
stearns@5576 | 430 | <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=16002">Bug-16002</a> |
stearns@5576 | 431 | <div class="issue-details"> |
stearns@5576 | 432 | <p class="short-desc">flow-into and anonymous blocks or fix-ups</p> |
stearns@5576 | 433 | </div> |
stearns@5576 | 434 | </div> |
stearns@5576 | 435 | <div class="issue-marker" data-bug_id="16527" data-bug_status="ASSIGNED"> |
stearns@5576 | 436 | <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=16527">Bug-16527</a> |
stearns@5576 | 437 | <div class="issue-details"> |
stearns@5576 | 438 | <p class="short-desc">[Shadow]: getFlowByName and shadow DOM</p> |
stearns@5576 | 439 | </div> |
stearns@5576 | 440 | </div> |
stearns@5576 | 441 | </div> |
vhardy@4398 | 442 | |
stearns@5453 | 443 | <p>The ‘flow-into’ property can place an element |
stearns@5453 | 444 | into a <span>named flow</span>. |
stearns@5453 | 445 | Elements that belong to the same flow |
stearns@5453 | 446 | are laid out in the region chain |
stearns@5453 | 447 | associated with that flow.</p> |
alexmog@2565 | 448 | |
vhardy@2779 | 449 | <table class="propdef" summary="flow property definition"> |
vhardy@2779 | 450 | <tr> |
vhardy@2779 | 451 | <th>Name:</th> |
alexmog@2565 | 452 | |
vhardy@3272 | 453 | <td><dfn id="flow-into">flow-into</dfn></td> |
vhardy@2779 | 454 | </tr> |
alexmog@2565 | 455 | |
vhardy@2779 | 456 | <tr> |
vhardy@2779 | 457 | <th>Value:</th> |
alexmog@2565 | 458 | |
vhardy@3660 | 459 | <td><ident> | none | inherit</td> |
vhardy@2779 | 460 | </tr> |
alexmog@2565 | 461 | |
vhardy@2779 | 462 | <tr> |
vhardy@2779 | 463 | <th>Initial:</th> |
alexmog@2565 | 464 | |
vhardy@3660 | 465 | <td>none</td> |
vhardy@2779 | 466 | </tr> |
alexmog@2565 | 467 | |
vhardy@2779 | 468 | <tr> |
vhardy@2779 | 469 | <th>Applies to:</th> |
alexmog@2565 | 470 | |
vhardy@5267 | 471 | <td>any element. <p>The 'flow-into' property does not apply to any <a href="http://www.w3.org/TR/selectors/#pseudo-elements">pseudo-element</a> such as |
vhardy@5267 | 472 | <code class="css">::first-line</code>, <code class="css">::first-letter</code>, |
vhardy@5267 | 473 | <code class="css">::before</code> or <code class="css">::after</code>.</p></td> |
vhardy@2779 | 474 | </tr> |
alexmog@2565 | 475 | |
vhardy@2779 | 476 | <tr> |
vhardy@2779 | 477 | <th>Inherited:</th> |
alexmog@2565 | 478 | |
vhardy@2779 | 479 | <td>no</td> |
vhardy@2779 | 480 | </tr> |
alexmog@2565 | 481 | |
vhardy@2779 | 482 | <tr> |
vhardy@2779 | 483 | <th>Percentages:</th> |
alexmog@2565 | 484 | |
vhardy@2779 | 485 | <td>N/A</td> |
vhardy@2779 | 486 | </tr> |
alexmog@2565 | 487 | |
vhardy@2779 | 488 | <tr> |
vhardy@2779 | 489 | <th>Media:</th> |
alexmog@2565 | 490 | |
vhardy@2779 | 491 | <td>visual</td> |
vhardy@2779 | 492 | </tr> |
alexmog@2565 | 493 | |
vhardy@2779 | 494 | <tr> |
vhardy@2779 | 495 | <th>Computed value:</th> |
alexmog@2565 | 496 | |
vhardy@2779 | 497 | <td>as specified</td> |
vhardy@2779 | 498 | </tr> |
vhardy@2779 | 499 | </table> |
alexmog@2565 | 500 | |
vhardy@2779 | 501 | <dl> |
vhardy@3660 | 502 | <dt>none</dt> |
alexmog@2565 | 503 | |
vhardy@5352 | 504 | <dd>The element is not moved to a <span>named flow</span> and normal CSS processing takes place.</dd> |
alexmog@2565 | 505 | |
vhardy@3073 | 506 | <dt><a href="http://www.w3.org/TR/2011/REC-CSS2-20110607/syndata.html#value-def-identifier"><ident></a></dt> |
alexmog@2565 | 507 | |
stearns@5453 | 508 | <dd>The element is taken out |
stearns@5453 | 509 | of its parent's flow |
stearns@5453 | 510 | and placed into the flow |
stearns@5453 | 511 | with the name '<ident>'. |
stearns@5453 | 512 | The element is said to have |
stearns@5453 | 513 | a <dfn id="specified-flow">specified flow</dfn>. |
stearns@5453 | 514 | The values 'none', 'inherit', 'default', 'auto' and 'initial' |
stearns@5453 | 515 | are invalid flow names.</dd> |
vhardy@2779 | 516 | </dl> |
alexmog@2565 | 517 | |
stearns@5453 | 518 | <p>A <span>named flow</span> needs to be associated |
stearns@5453 | 519 | with a region chain |
stearns@5453 | 520 | (one or more CSS regions) |
stearns@5453 | 521 | for its elements to be visually formatted. |
stearns@5453 | 522 | If no region chain is associated |
stearns@5453 | 523 | with a given <span>named flow</span>, |
stearns@5453 | 524 | the elements in the <span>named flow</span> |
stearns@5453 | 525 | are not rendered: |
stearns@5453 | 526 | they do not generate boxes |
stearns@5453 | 527 | and are not displayed.</p> |
alexmog@2565 | 528 | |
stearns@5453 | 529 | <p>The children of an element |
stearns@5453 | 530 | with a specified flow |
stearns@5453 | 531 | may themselves have a specified flow.</p> |
alexmog@2565 | 532 | |
stearns@5453 | 533 | <p>If an element has the same specified flow |
stearns@5453 | 534 | as one of its ancestors, |
stearns@5453 | 535 | it becomes a sibling of its ancestor |
stearns@5453 | 536 | for the purpose of layout |
stearns@5453 | 537 | in the region chain |
stearns@5453 | 538 | laying out content |
stearns@5453 | 539 | from that flow.</p> |
alexmog@2565 | 540 | |
stearns@5453 | 541 | <p>The 'flow-into' property does not affect |
stearns@5453 | 542 | the CSS cascade and inheritance |
stearns@5453 | 543 | for the elements on which it is specified. |
stearns@5453 | 544 | The 'flow-into' property affects |
stearns@5453 | 545 | the visual formatting of elements |
stearns@5453 | 546 | placed into a <span>named flow</span> |
stearns@5453 | 547 | and of the region chain laying out content |
stearns@5453 | 548 | from a <span>named flow</span>.</p> |
vhardy@3301 | 549 | |
vhardy@4412 | 550 | <div class="issue-marker wrapper"> |
vhardy@4412 | 551 | |
vhardy@4412 | 552 | <div class="issue-marker" data-bug_id="15870" data-bug_status="NEW"> |
vhardy@4412 | 553 | <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15870">Bug-15870</a> |
vhardy@4412 | 554 | <div class="issue-details"> |
vhardy@4412 | 555 | <p class="short-desc">Describe how containing blocks are used for element fragments</p> |
vhardy@4412 | 556 | </div> |
vhardy@4412 | 557 | </div> |
vhardy@4412 | 558 | </div> |
vhardy@4412 | 559 | |
stearns@5574 | 560 | <p>The edges of the first CSS region in a region chain |
stearns@5453 | 561 | associated with a <span>named flow</span> |
stearns@5453 | 562 | establish the rectangle that is the |
stearns@5453 | 563 | <a href="http://www.w3.org/TR/CSS2/visudet.html#containing-block-details">containing block</a> |
stearns@5453 | 564 | used for absolutely positioned elements |
stearns@5453 | 565 | in the <span>named flow</span> |
stearns@5453 | 566 | which do not have an ancestor |
stearns@5453 | 567 | with a 'position' of 'absolute', 'relative' or 'fixed' |
stearns@5453 | 568 | (see [[!CSS21]]). |
stearns@5574 | 569 | That first CSS region rectangle is used |
stearns@5453 | 570 | as the containing block |
stearns@5453 | 571 | instead of the initial containing block.</p> |
vhardy@3301 | 572 | |
stearns@5453 | 573 | <p>The first region defines the |
stearns@5453 | 574 | <a href="http://www.w3.org/TR/css3-writing-modes/#writing-mode">writing mode</a> |
stearns@5453 | 575 | for the entire flow. |
stearns@5453 | 576 | The writing mode |
stearns@5453 | 577 | on subsequent regions is ignored.</p> |
vhardy@3660 | 578 | |
stearns@5453 | 579 | <p>Elements in a <span>named flow</span> |
stearns@5453 | 580 | are sequenced in document order.</p> |
vhardy@3301 | 581 | |
vhardy@4314 | 582 | <div class="note"><span class="note-prefix">Note </span> |
stearns@5453 | 583 | <p>The 'flow-into' property moves an element into the flow |
stearns@5453 | 584 | and the interplay with selectors should be considered carefully.</p> |
vhardy@3301 | 585 | <p>For example, </p> |
vhardy@3272 | 586 | <pre>table {flow-into: table-content}</pre> |
stearns@5453 | 587 | <p>will move all tables in the 'table-content' |
stearns@5453 | 588 | <span>named flow</span>. |
stearns@5453 | 589 | However, the</p> |
vhardy@4415 | 590 | <pre>table > * {flow-into: table-content} ...</pre> |
stearns@5453 | 591 | <p>selector will move all immediate children |
stearns@5453 | 592 | of all table elements |
stearns@5453 | 593 | into the ‘table-content’ <span>named flow</span> |
stearns@5453 | 594 | (which may be useful as it will usually result, |
stearns@5453 | 595 | if the immediate children are rows, |
stearns@5453 | 596 | in merging rows of multiple tables), |
stearns@5453 | 597 | but the</p> |
vhardy@3272 | 598 | <pre>table * {flow-into: table-content}</pre> |
stearns@5453 | 599 | <p>selector will move all descendants |
stearns@5453 | 600 | of table elements into the ‘table-content’ <span>named flow</span>, |
stearns@5453 | 601 | transforming the element tree |
stearns@5453 | 602 | into a flat list in order of opening tags |
stearns@5453 | 603 | (which is probably not intentional). |
stearns@5453 | 604 | This will make all the descendants |
stearns@5453 | 605 | of table elements siblings |
stearns@5453 | 606 | in the <span>named flow</span>. |
stearns@5453 | 607 | Having the descendants become siblings |
stearns@5453 | 608 | in the <span>named flow</span> |
stearns@5453 | 609 | results in a different processing |
stearns@5453 | 610 | (see <a href="http://www.w3.org/TR/2011/REC-CSS2-20110607/tables.html#anonymous-boxes">CSS 2.1's anonymous table objects</a>). |
stearns@5453 | 611 | This note illustrates how authors must exercise caution |
stearns@5453 | 612 | when choosing a particular selector |
stearns@5453 | 613 | for setting the 'flow-into' property |
stearns@5453 | 614 | to avoid unintended results.</p> |
vhardy@2945 | 615 | </div> |
vhardy@3272 | 616 | |
vhardy@3660 | 617 | |
vhardy@3302 | 618 | |
vhardy@3302 | 619 | |
vhardy@3547 | 620 | <h3 id="the-flow-from-property">The 'flow-from' property</h3> |
alexmog@2565 | 621 | |
stearns@5579 | 622 | <p>The 'flow-from' property makes |
stearns@5579 | 623 | a block container a region |
stearns@5579 | 624 | and associates it with |
stearns@5579 | 625 | a <span>named flow</span>.</p> |
stearns@5579 | 626 | |
vhardy@3547 | 627 | <table class="propdef" summary="flow-from property definition"> |
vhardy@2779 | 628 | <tr> |
vhardy@2779 | 629 | <th>Name:</th> |
alexmog@2565 | 630 | |
vhardy@3547 | 631 | <td><dfn id="flow-from">flow-from</dfn></td> |
vhardy@2779 | 632 | </tr> |
alexmog@2565 | 633 | |
vhardy@2779 | 634 | <tr> |
vhardy@2779 | 635 | <th>Value:</th> |
alexmog@2565 | 636 | |
vhardy@3660 | 637 | <td><ident> | none | inherit</td> |
vhardy@2779 | 638 | </tr> |
alexmog@2565 | 639 | |
vhardy@2779 | 640 | <tr> |
vhardy@2779 | 641 | <th>Initial:</th> |
alexmog@2565 | 642 | |
vhardy@3547 | 643 | <td>none</td> |
vhardy@2779 | 644 | </tr> |
alexmog@2565 | 645 | |
vhardy@2779 | 646 | <tr> |
vhardy@2779 | 647 | <th>Applies to:</th> |
alexmog@2565 | 648 | |
stearns@5575 | 649 | <td>Non-replaced <a href="http://www.w3.org/TR/CSS21/visuren.html#block-boxes">block containers</a>. |
vhardy@3547 | 650 | <br /> |
vhardy@3547 | 651 | This might be expanded in future versions of the specification |
vhardy@3547 | 652 | to allow other types of containers to receive flow content.</td> |
vhardy@2779 | 653 | </tr> |
alexmog@2565 | 654 | |
vhardy@2779 | 655 | <tr> |
vhardy@2779 | 656 | <th>Inherited:</th> |
vhardy@2779 | 657 | |
vhardy@2779 | 658 | <td>no</td> |
vhardy@2779 | 659 | </tr> |
vhardy@2779 | 660 | |
vhardy@2779 | 661 | <tr> |
vhardy@2779 | 662 | <th>Percentages:</th> |
vhardy@2779 | 663 | |
vhardy@2779 | 664 | <td>N/A</td> |
vhardy@2779 | 665 | </tr> |
vhardy@2779 | 666 | |
vhardy@2779 | 667 | <tr> |
vhardy@2779 | 668 | <th>Media:</th> |
vhardy@2779 | 669 | |
vhardy@2779 | 670 | <td>visual</td> |
vhardy@2779 | 671 | </tr> |
vhardy@2779 | 672 | |
vhardy@2779 | 673 | <tr> |
vhardy@2779 | 674 | <th>Computed value:</th> |
vhardy@2779 | 675 | |
vhardy@2779 | 676 | <td>as specified</td> |
vhardy@2779 | 677 | </tr> |
vhardy@2779 | 678 | </table> |
vhardy@2779 | 679 | |
vhardy@2779 | 680 | <dl> |
vhardy@3547 | 681 | <dt><strong>none</strong></dt> |
vhardy@2779 | 682 | |
stearns@5575 | 683 | <dd>The block container is not a <span title="region">region</span>.</dd> |
vhardy@2779 | 684 | |
vhardy@3547 | 685 | <dt><strong><ident></strong></dt> |
vhardy@2779 | 686 | |
vhardy@3547 | 687 | <dd> |
stearns@5453 | 688 | If the 'content' property computes |
stearns@5453 | 689 | to something else than 'normal', |
stearns@5575 | 690 | the block container does not become a <span>CSS Region</span>. |
stearns@5453 | 691 | If the 'content' property computes to 'normal', |
stearns@5575 | 692 | then the block container becomes a <span>CSS Region</span> |
stearns@5453 | 693 | and is ordered in a <span>region chain</span> |
stearns@5453 | 694 | according to its document order. |
stearns@5453 | 695 | The content from the flow |
stearns@5453 | 696 | with the <a href="http://www.w3.org/TR/2011/REC-CSS2-20110607/syndata.html#value-def-identifier"><ident></a> |
stearns@5453 | 697 | name will be <a href="#region-flow-break">broken |
stearns@5453 | 698 | into fragments</a> and visually formatted in the |
stearns@5453 | 699 | <a href="http://www.w3.org/TR/CSS21/visuren.html#principal-box">principal boxes</a> |
stearns@5453 | 700 | of the <span>regions</span> |
stearns@5453 | 701 | in the <span>region chain</span>. |
stearns@5453 | 702 | <br/> |
stearns@5453 | 703 | If there is no flow with name <ident>, |
stearns@5575 | 704 | then the block container does not |
stearns@5453 | 705 | format any content visually. |
stearns@5453 | 706 | <br/> |
stearns@5575 | 707 | Likewise, if the block container is part |
stearns@5453 | 708 | of the flow with name <ident>, |
stearns@5575 | 709 | then the block container does not format any content visually. |
vhardy@3262 | 710 | </dd> |
vhardy@2779 | 711 | </dl> |
vhardy@2779 | 712 | |
stearns@5578 | 713 | <div class="issue-marker" data-bug_id="16819" data-bug_status="ASSIGNED"> |
stearns@5578 | 714 | <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=16819">Bug-16819</a> |
stearns@5578 | 715 | <div class="issue-details"> |
stearns@5578 | 716 | <p class="short-desc">No display when combining flow-from and flow-into is bad</p> |
stearns@5578 | 717 | </div> |
stearns@5578 | 718 | </div> |
stearns@5578 | 719 | |
stearns@5453 | 720 | <p>A <span>CSS Region</span>'s document children |
stearns@5453 | 721 | are not visually formatted |
stearns@5453 | 722 | unless they are directed |
stearns@5453 | 723 | to a <span>named flow</span> |
stearns@5453 | 724 | with an associated <span>region chain</span>.</p> |
vhardy@3267 | 725 | |
stearns@5453 | 726 | <div class="note"><span class="note-prefix">Note </span> |
stearns@5575 | 727 | <p>An block container becomes a <span>CSS Region</span> |
stearns@5453 | 728 | when its 'flow-from' property is set |
stearns@5453 | 729 | to a valid <ident> value, |
stearns@5453 | 730 | even if there is no content contributing |
stearns@5453 | 731 | to the referenced flow. |
vhardy@3728 | 732 | For example:</p> |
bert@3938 | 733 | <pre> |
vhardy@3728 | 734 | <style> |
vhardy@3728 | 735 | .article{ |
vhardy@3728 | 736 | flow-into: thread; |
vhardy@3728 | 737 | } |
vhardy@3728 | 738 | .region{ |
vhardy@3728 | 739 | flow-from: thread; |
vhardy@3728 | 740 | } |
vhardy@3728 | 741 | </style> |
vhardy@3728 | 742 | <html> |
vhardy@3728 | 743 | <body> |
vhardy@3728 | 744 | <div class=region>div content</div> |
vhardy@3728 | 745 | </body> |
vhardy@3728 | 746 | </html> |
bert@3938 | 747 | </pre> |
vhardy@3728 | 748 | |
stearns@5453 | 749 | There is no element matching the <code>.article</code> selector |
stearns@5453 | 750 | and therefore no content |
stearns@5453 | 751 | in the <code>thread</code> flow. |
stearns@5575 | 752 | However, the block container matching the <code>.region</code> selector |
stearns@5453 | 753 | is still associated with that empty <span>named flow</span> |
stearns@5453 | 754 | and, consequently, |
stearns@5453 | 755 | its children are not formatted visually. |
vhardy@3728 | 756 | </div> |
vhardy@3138 | 757 | |
vhardy@4412 | 758 | <div class="issue-marker wrapper"> |
vhardy@4412 | 759 | <div class="issue-marker" data-bug_id="15189" data-bug_status="NEW"> |
vhardy@4395 | 760 | <a href= |
vhardy@4404 | 761 | "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15189">Bug-15189</a> |
vhardy@4395 | 762 | |
vhardy@4395 | 763 | <div class="issue-details"> |
vhardy@4395 | 764 | <p class="short-desc">Should regions be non-breakable?</p> |
vhardy@4395 | 765 | </div> |
vhardy@4412 | 766 | </div> |
vhardy@4412 | 767 | <div class="issue-marker" data-bug_id="15824" data-bug_status="NEW"> |
vhardy@4400 | 768 | |
vhardy@4400 | 769 | <a href= |
vhardy@4404 | 770 | "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15824">Bug-15824</a> |
vhardy@4400 | 771 | |
vhardy@4400 | 772 | <div class="issue-details"> |
vhardy@4400 | 773 | <p class="short-desc">Should regions not create a new stacking context?</p> |
vhardy@4412 | 774 | </div> |
vhardy@4412 | 775 | </div> |
vhardy@4412 | 776 | <div class="issue-marker" data-bug_id="15827" data-bug_status="NEW"> |
vhardy@4400 | 777 | |
vhardy@4400 | 778 | <a href= |
vhardy@4404 | 779 | "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15824">Bug-15827</a> |
vhardy@4400 | 780 | |
vhardy@4400 | 781 | <div class="issue-details"> |
vhardy@4400 | 782 | <p class="short-desc">Specify behavior of stacking contexts that are split between regions</p> |
vhardy@4400 | 783 | </div> |
vhardy@4412 | 784 | </div> |
stearns@5469 | 785 | |
stearns@5469 | 786 | <div class="issue-marker" data-bug_id="16636" data-bug_status="NEW"> |
stearns@5469 | 787 | <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=16636">Bug-16636</a> |
stearns@5469 | 788 | <div class="issue-details"> |
stearns@5469 | 789 | <p class="short-desc">Should re-introduce region order</p> |
stearns@5469 | 790 | </div> |
stearns@5469 | 791 | </div> |
stearns@5469 | 792 | </div> |
vhardy@2779 | 793 | |
stearns@5453 | 794 | <p><span title="region">CSS Regions</span> create a new <a href="http://www.w3.org/TR/CSS2/visuren.html#z-index">stacking context</a>. <span title="region">CSS Regions</span> establish a new <a href="http://www.w3.org/TR/CSS2/visuren.html#block-formatting">block formatting Context</a>.</p> |
vhardy@3301 | 795 | |
vhardy@4314 | 796 | <div class="note"><span class="note-prefix">Note </span> |
stearns@5453 | 797 | <p>With <span>region chains</span>, |
stearns@5453 | 798 | an element may be split across multiple boxes |
stearns@5453 | 799 | and these boxes may overlap |
stearns@5453 | 800 | (for example if they are absolutely positioned). |
stearns@5453 | 801 | So fragments of the same element |
stearns@5453 | 802 | can overlap each other. |
stearns@5453 | 803 | Since each element has a single z-index, |
stearns@5453 | 804 | it would be required to find another mechanism |
stearns@5453 | 805 | to decide in which order |
stearns@5453 | 806 | the fragments are rendered. |
stearns@5453 | 807 | Since each <span>CSS Region</span> creates |
stearns@5453 | 808 | a new stacking context, |
stearns@5453 | 809 | it is clear that each fragment is rendered separately |
stearns@5453 | 810 | and their rendering order follows |
stearns@5453 | 811 | the regular CSS rendering model.</p> |
vhardy@3301 | 812 | </div> |
vhardy@3301 | 813 | |
stearns@5453 | 814 | <p>Floats or other exclusions |
stearns@5453 | 815 | (see [[CSS3-EXCLUSIONS]]) |
stearns@5453 | 816 | potentially impact the content |
stearns@5453 | 817 | laid out in region chains, |
stearns@5453 | 818 | just as for non-regions.</p> |
vhardy@3301 | 819 | |
stearns@5453 | 820 | <p>See the |
stearns@5453 | 821 | <a href="#regions-visual-formatting-details">regions visual formatting details</a> |
stearns@5453 | 822 | section for a description of how |
stearns@5453 | 823 | 'width' and 'height' values are resolved |
stearns@5453 | 824 | for <span>CSS Region</span> boxes.</p> |
stearns@5469 | 825 | |
vhardy@2945 | 826 | <h3 id= |
vhardy@3377 | 827 | "region-flow-break">Region |
vhardy@2945 | 828 | flow break properties: 'break-before', 'break-after', 'break-inside'</h3> |
vhardy@2779 | 829 | |
vhardy@3547 | 830 | <p>User agents laying out content in multiple regions must |
vhardy@2819 | 831 | determine where content breaks occur. The problem of breaking content into |
vhardy@5353 | 832 | fragments fitting in regions is similar to breaking content into pages or |
vhardy@2779 | 833 | columns.</p> |
vhardy@2779 | 834 | |
vhardy@2779 | 835 | <p>Each break ends layout in the current region and causes remaining pieces |
vhardy@5352 | 836 | of content from the <span>named flow</span> to be visually formatted in the following |
vhardy@4415 | 837 | region in the region chain, if there is one.</p> |
vhardy@2779 | 838 | |
vhardy@2779 | 839 | <p>The following extends the 'break-before', 'break-after' and |
vhardy@2779 | 840 | 'break-inside' properties from the [[!CSS3COL]] specification to account |
vhardy@2779 | 841 | for regions. The additional values are described below.</p> |
vhardy@2779 | 842 | |
vhardy@2779 | 843 | <table class="propdef" summary="break-before property definition"> |
vhardy@2779 | 844 | <tr> |
vhardy@2779 | 845 | <td><em>Name:</em></td> |
vhardy@2779 | 846 | |
vhardy@2779 | 847 | <td><dfn>break-before</dfn></td> |
vhardy@2779 | 848 | </tr> |
vhardy@2779 | 849 | |
vhardy@2779 | 850 | <tr> |
vhardy@2779 | 851 | <td><em>Value:</em></td> |
vhardy@2779 | 852 | |
vhardy@2779 | 853 | <td>auto | always | avoid | left | right | page | column | region | |
vhardy@2779 | 854 | avoid-page | avoid-column | avoid-region</td> |
vhardy@2779 | 855 | </tr> |
vhardy@2779 | 856 | |
vhardy@2779 | 857 | <tr> |
vhardy@2779 | 858 | <td><em>Initial:</em></td> |
vhardy@2779 | 859 | |
vhardy@2779 | 860 | <td>auto</td> |
vhardy@2779 | 861 | </tr> |
vhardy@2779 | 862 | |
vhardy@2779 | 863 | <tr> |
vhardy@2779 | 864 | <td><em>Applies to:</em></td> |
vhardy@2779 | 865 | |
vhardy@2779 | 866 | <td>block-level elements</td> |
vhardy@2779 | 867 | </tr> |
vhardy@2779 | 868 | |
vhardy@2779 | 869 | <tr> |
vhardy@2779 | 870 | <td><em>Inherited:</em></td> |
vhardy@2779 | 871 | |
vhardy@2779 | 872 | <td>no</td> |
vhardy@2779 | 873 | </tr> |
vhardy@2779 | 874 | |
vhardy@2779 | 875 | <tr> |
vhardy@2779 | 876 | <td><em>Percentages:</em></td> |
vhardy@2779 | 877 | |
vhardy@2779 | 878 | <td>N/A</td> |
vhardy@2779 | 879 | </tr> |
vhardy@2779 | 880 | |
vhardy@2779 | 881 | <tr> |
vhardy@2779 | 882 | <td><em>Media:</em></td> |
vhardy@2779 | 883 | |
stearns@5453 | 884 | <td>visual</td> |
vhardy@2779 | 885 | </tr> |
vhardy@2779 | 886 | |
vhardy@2779 | 887 | <tr> |
vhardy@2779 | 888 | <td><em>Computed value:</em></td> |
vhardy@2779 | 889 | |
vhardy@2779 | 890 | <td>specified value</td> |
vhardy@2779 | 891 | </tr> |
vhardy@2779 | 892 | </table> |
vhardy@2779 | 893 | |
vhardy@2779 | 894 | <table class="propdef" summary="break-after property definition"> |
vhardy@2779 | 895 | <tr> |
vhardy@2779 | 896 | <td><em>Name:</em></td> |
vhardy@2779 | 897 | |
vhardy@2779 | 898 | <td><dfn>break-after</dfn></td> |
vhardy@2779 | 899 | </tr> |
vhardy@2779 | 900 | |
vhardy@2779 | 901 | <tr> |
vhardy@2779 | 902 | <td><em>Value:</em></td> |
vhardy@2779 | 903 | |
vhardy@2779 | 904 | <td>auto | always | avoid | left | right | page | column | region | |
vhardy@2779 | 905 | avoid-page | avoid-column | avoid-region</td> |
vhardy@2779 | 906 | </tr> |
vhardy@2779 | 907 | |
vhardy@2779 | 908 | <tr> |
vhardy@2779 | 909 | <td><em>Initial:</em></td> |
vhardy@2779 | 910 | |
vhardy@2779 | 911 | <td>auto</td> |
vhardy@2779 | 912 | </tr> |
vhardy@2779 | 913 | |
vhardy@2779 | 914 | <tr> |
vhardy@2779 | 915 | <td><em>Applies to:</em></td> |
vhardy@2779 | 916 | |
vhardy@2779 | 917 | <td>block-level elements</td> |
vhardy@2779 | 918 | </tr> |
vhardy@2779 | 919 | |
vhardy@2779 | 920 | <tr> |
vhardy@2779 | 921 | <td><em>Inherited:</em></td> |
vhardy@2779 | 922 | |
vhardy@2779 | 923 | <td>no</td> |
vhardy@2779 | 924 | </tr> |
vhardy@2779 | 925 | |
vhardy@2779 | 926 | <tr> |
vhardy@2779 | 927 | <td><em>Percentages:</em></td> |
vhardy@2779 | 928 | |
vhardy@2779 | 929 | <td>N/A</td> |
vhardy@2779 | 930 | </tr> |
vhardy@2779 | 931 | |
vhardy@2779 | 932 | <tr> |
vhardy@2779 | 933 | <td><em>Media:</em></td> |
vhardy@2779 | 934 | |
stearns@5453 | 935 | <td>visual</td> |
vhardy@2779 | 936 | </tr> |
vhardy@2779 | 937 | |
vhardy@2779 | 938 | <tr> |
vhardy@2779 | 939 | <td><em>Computed value:</em></td> |
vhardy@2779 | 940 | |
vhardy@2779 | 941 | <td>specified value</td> |
vhardy@2779 | 942 | </tr> |
vhardy@2779 | 943 | </table> |
vhardy@2779 | 944 | |
vhardy@2779 | 945 | <table class="propdef" summary="break-inside property definition"> |
vhardy@2779 | 946 | <tr> |
vhardy@2779 | 947 | <td><em>Name:</em></td> |
vhardy@2779 | 948 | |
vhardy@2779 | 949 | <td><dfn>break-inside</dfn></td> |
vhardy@2779 | 950 | </tr> |
vhardy@2779 | 951 | |
vhardy@2779 | 952 | <tr> |
vhardy@2779 | 953 | <td><em>Value:</em></td> |
vhardy@2779 | 954 | |
vhardy@2779 | 955 | <td>auto | avoid | avoid-page | avoid-column | avoid-region</td> |
vhardy@2779 | 956 | </tr> |
vhardy@2779 | 957 | |
vhardy@2779 | 958 | <tr> |
vhardy@2779 | 959 | <td><em>Initial:</em></td> |
vhardy@2779 | 960 | |
vhardy@2779 | 961 | <td>auto</td> |
vhardy@2779 | 962 | </tr> |
vhardy@2779 | 963 | |
vhardy@2779 | 964 | <tr> |
vhardy@2779 | 965 | <td><em>Applies to:</em></td> |
vhardy@2779 | 966 | |
vhardy@2779 | 967 | <td>block-level elements</td> |
vhardy@2779 | 968 | </tr> |
vhardy@2779 | 969 | |
vhardy@2779 | 970 | <tr> |
vhardy@2779 | 971 | <td><em>Inherited:</em></td> |
vhardy@2779 | 972 | |
vhardy@2779 | 973 | <td>no</td> |
vhardy@2779 | 974 | </tr> |
vhardy@2779 | 975 | |
vhardy@2779 | 976 | <tr> |
vhardy@2779 | 977 | <td><em>Percentages:</em></td> |
vhardy@2779 | 978 | |
vhardy@2779 | 979 | <td>N/A</td> |
vhardy@2779 | 980 | </tr> |
vhardy@2779 | 981 | |
vhardy@2779 | 982 | <tr> |
vhardy@2779 | 983 | <td><em>Media:</em></td> |
vhardy@2779 | 984 | |
stearns@5453 | 985 | <td>visual</td> |
vhardy@2779 | 986 | </tr> |
vhardy@2779 | 987 | |
vhardy@2779 | 988 | <tr> |
vhardy@2779 | 989 | <td><em>Computed value:</em></td> |
vhardy@2779 | 990 | |
vhardy@2779 | 991 | <td>specified value</td> |
vhardy@2779 | 992 | </tr> |
vhardy@2779 | 993 | </table> |
vhardy@2779 | 994 | |
vhardy@2779 | 995 | <p>These properties describe page, column and region break behavior |
vhardy@2779 | 996 | before/after/inside the generated box. These values are normatively defined |
vhardy@2779 | 997 | in [[!CSS3COL]]:</p> |
vhardy@2779 | 998 | |
vhardy@2779 | 999 | <p>This specification adds the following new values:</p> |
vhardy@2779 | 1000 | |
vhardy@2779 | 1001 | <dl> |
vhardy@2779 | 1002 | <dt>region</dt> |
vhardy@2779 | 1003 | |
vhardy@2779 | 1004 | <dd>Always force a region break before (after) the generated box.</dd> |
vhardy@2779 | 1005 | |
vhardy@2779 | 1006 | <dt>avoid-region</dt> |
vhardy@2779 | 1007 | |
vhardy@2779 | 1008 | <dd>Avoid a region break before (after, inside) the generated box.</dd> |
vhardy@2779 | 1009 | </dl> |
vhardy@2779 | 1010 | |
vhardy@4336 | 1011 | <p>The behavior of region breaks with regards to regions is identical to the behavior |
vhardy@4336 | 1012 | of page breaks with regards to pages, as defined in the [[!CSS21]].</p> |
vhardy@3267 | 1013 | |
vhardy@2945 | 1014 | <h3 id="the-region-overflow-property">The region-overflow property</h3> |
vhardy@2779 | 1015 | |
vhardy@4415 | 1016 | <div class="issue-marker" data-bug_id="15878" data-bug_status="NEW"> |
vhardy@4415 | 1017 | <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15878">Bug-15878</a> |
vhardy@4415 | 1018 | <div class="issue-details"> |
vhardy@4415 | 1019 | <p class="short-desc">region-overflow:nobreak</p> |
vhardy@4415 | 1020 | </div> |
vhardy@4415 | 1021 | </div> |
vhardy@4415 | 1022 | |
vhardy@2945 | 1023 | <table class="propdef" summary="break-after property definition"> |
vhardy@2945 | 1024 | <tr> |
vhardy@2945 | 1025 | <td><em>Name:</em></td> |
vhardy@2779 | 1026 | |
vhardy@2945 | 1027 | <td><dfn>region-overflow</dfn></td> |
vhardy@2945 | 1028 | </tr> |
vhardy@2945 | 1029 | |
vhardy@2945 | 1030 | <tr> |
vhardy@2945 | 1031 | <td><em>Value:</em></td> |
vhardy@2945 | 1032 | |
vhardy@2945 | 1033 | <td>auto | break</td> |
vhardy@2945 | 1034 | </tr> |
vhardy@2945 | 1035 | |
vhardy@2945 | 1036 | <tr> |
vhardy@2945 | 1037 | <td><em>Initial:</em></td> |
vhardy@2945 | 1038 | |
vhardy@2945 | 1039 | <td>auto</td> |
vhardy@2945 | 1040 | </tr> |
vhardy@2945 | 1041 | |
vhardy@2945 | 1042 | <tr> |
vhardy@2945 | 1043 | <td><em>Applies to:</em></td> |
vhardy@2945 | 1044 | |
stearns@5574 | 1045 | <td><em title="region element">CSS Regions</em></td> |
vhardy@2945 | 1046 | </tr> |
vhardy@2945 | 1047 | |
vhardy@2945 | 1048 | <tr> |
vhardy@2945 | 1049 | <td><em>Inherited:</em></td> |
vhardy@2945 | 1050 | |
vhardy@2945 | 1051 | <td>no</td> |
vhardy@2945 | 1052 | </tr> |
vhardy@2945 | 1053 | |
vhardy@2945 | 1054 | <tr> |
vhardy@2945 | 1055 | <td><em>Percentages:</em></td> |
vhardy@2945 | 1056 | |
vhardy@2945 | 1057 | <td>N/A</td> |
vhardy@2945 | 1058 | </tr> |
vhardy@2945 | 1059 | |
vhardy@2945 | 1060 | <tr> |
vhardy@2945 | 1061 | <td><em>Media:</em></td> |
vhardy@2945 | 1062 | |
stearns@5453 | 1063 | <td>visual</td> |
vhardy@2945 | 1064 | </tr> |
vhardy@2945 | 1065 | |
vhardy@2945 | 1066 | <tr> |
vhardy@2945 | 1067 | <td><em>Computed value:</em></td> |
vhardy@2945 | 1068 | |
vhardy@2945 | 1069 | <td>specified value</td> |
vhardy@2945 | 1070 | </tr> |
vhardy@2945 | 1071 | </table> |
vhardy@4404 | 1072 | |
stearns@5469 | 1073 | <div class="issue-marker wrapper"> |
vhardy@4412 | 1074 | <div class="issue-marker" data-bug_id="15832" data-bug_status="NEW"> |
vhardy@4404 | 1075 | <a href= |
vhardy@4404 | 1076 | "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15832">Bug-15832</a> |
vhardy@4404 | 1077 | |
vhardy@4404 | 1078 | <div class="issue-details"> |
vhardy@5232 | 1079 | <p class="short-desc">Should we have region-overflow:nobreak and have 'region-overflow' apply to all regions, not just the last?</p> |
vhardy@4404 | 1080 | </div> |
vhardy@4404 | 1081 | </div> |
stearns@5469 | 1082 | <div class="issue-marker" data-bug_id="16622" data-bug_status="NEW"> |
stearns@5469 | 1083 | <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=16622">Bug-16622</a> |
stearns@5469 | 1084 | <div class="issue-details"> |
stearns@5469 | 1085 | <p class="short-desc">Should we rename region-overflow to flow-overset?</p> |
stearns@5469 | 1086 | </div> |
stearns@5469 | 1087 | </div> |
stearns@5469 | 1088 | </div> |
vhardy@2945 | 1089 | |
vhardy@2945 | 1090 | <p>The 'region-overflow' property controls the behavior of the <em id= |
vhardy@2945 | 1091 | "last-region">last region</em> associated with a <span>named |
vhardy@2945 | 1092 | flow</span>.</p> |
vhardy@2945 | 1093 | |
vhardy@2945 | 1094 | <dl> |
vhardy@2945 | 1095 | <dt>auto</dt> |
vhardy@2945 | 1096 | |
stearns@5574 | 1097 | <dd>Content flows as it would in a regular content box. If the |
vhardy@2945 | 1098 | content exceeds the container box, it is subject to the <a href= |
vhardy@3073 | 1099 | "http://www.w3.org/TR/CSS21/visufx.html#propdef-overflow">overflow</a> |
stearns@5574 | 1100 | property's computed value on the CSS Region. Region breaks must be |
vhardy@3138 | 1101 | ignored on the last region.</dd> |
vhardy@2945 | 1102 | |
vhardy@2945 | 1103 | <dt>break</dt> |
vhardy@2945 | 1104 | |
stearns@5574 | 1105 | <dd><p>If the content fits within the <em>CSS Region</em>, then this |
vhardy@2945 | 1106 | property has no effect. If the content does not fit within the |
stearns@5574 | 1107 | <em>CSS Region</em>, the content breaks as if flow was going to |
vhardy@3073 | 1108 | continue in a subsequent region. See the <a href= |
bert@3938 | 1109 | "#regions-flow-breaking-rules">breaking rules</a> section. A forced region break takes precedence over |
vhardy@3660 | 1110 | a natural break point.</p> |
vhardy@3660 | 1111 | |
vhardy@3660 | 1112 | <p>Flow content that follows the last break in the last region, if any is not rendered.</p> |
vhardy@3660 | 1113 | |
vhardy@3660 | 1114 | |
vhardy@3660 | 1115 | </dd> |
vhardy@2945 | 1116 | </dl> |
vhardy@2945 | 1117 | |
stearns@5423 | 1118 | <p>The 'region-overflow' property does not influence |
stearns@5423 | 1119 | the size of the region it applies to.</p> |
vhardy@3660 | 1120 | |
stearns@5423 | 1121 | <p>The following code sample illustrates |
stearns@5423 | 1122 | the usage of the 'region-overflow' property.</p> |
vhardy@2779 | 1123 | |
vhardy@2779 | 1124 | <div class="example"> |
stearns@5423 | 1125 | <pre> |
alexmog@2565 | 1126 | <style> |
vhardy@5490 | 1127 | article { |
stearns@5423 | 1128 | flow-into: "article"; |
vhardy@2779 | 1129 | } |
vhardy@2779 | 1130 | |
vhardy@2945 | 1131 | #region_1, #region_2 { |
stearns@5423 | 1132 | flow-from: article; |
stearns@5423 | 1133 | <strong>region-overflow: break;</strong> /* or none */ |
stearns@5423 | 1134 | <strong>overflow: visible;</strong> /* or hidden */ |
vhardy@2779 | 1135 | } |
vhardy@2779 | 1136 | |
vhardy@2779 | 1137 | </style> |
vhardy@2945 | 1138 | |
vhardy@5490 | 1139 | <article>...</article> |
vhardy@2945 | 1140 | |
vhardy@2945 | 1141 | <div id="region_1"></div> |
vhardy@2945 | 1142 | <div id="region_2"></div> |
vhardy@2945 | 1143 | |
stearns@5423 | 1144 | </pre> |
vhardy@2779 | 1145 | </div> |
vhardy@2779 | 1146 | |
vhardy@2945 | 1147 | <div class="figure"> |
vhardy@2945 | 1148 | <table style="border: 1px solid gray;width: 100%;" summary= |
vhardy@2945 | 1149 | "Different values for the region-overflow property - Illustration."> |
vhardy@2945 | 1150 | <tr> |
vhardy@3262 | 1151 | <td>''flow-into: "article"''</td> |
vhardy@2945 | 1152 | |
vhardy@2945 | 1153 | <td><code class="html">region_1</code> and <code class= |
vhardy@2945 | 1154 | "html">region_2</code></td> |
vhardy@2945 | 1155 | |
vhardy@2945 | 1156 | <td>''region-overflow: auto''<br> |
vhardy@2945 | 1157 | ''overflow:visible''</td> |
vhardy@2945 | 1158 | </tr> |
vhardy@2945 | 1159 | |
vhardy@2945 | 1160 | <tr> |
vhardy@2945 | 1161 | <td rowspan="3" style="vertical-align: top;"><img src= |
vhardy@2945 | 1162 | "images/region-overflow-flow.png" alt= |
vhardy@2945 | 1163 | "regions receiving the flow content"></td> |
vhardy@2945 | 1164 | |
vhardy@2945 | 1165 | <td><img src="images/region-overflow-regions.png" alt= |
vhardy@2945 | 1166 | "result if region-overflow is set to 'break'"></td> |
vhardy@2945 | 1167 | |
vhardy@2945 | 1168 | <td><img src="images/region-overflow-auto-overflow-visible.png" |
vhardy@2945 | 1169 | alt="regions receiving the flow content"></td> |
vhardy@2945 | 1170 | </tr> |
vhardy@2945 | 1171 | |
vhardy@2945 | 1172 | <tr> |
vhardy@2945 | 1173 | <td>''region-overflow: break''</td> |
vhardy@2945 | 1174 | |
vhardy@2945 | 1175 | <td>''region-overflow: auto''<br> |
vhardy@2945 | 1176 | ''overflow:hidden''</td> |
vhardy@2945 | 1177 | </tr> |
vhardy@2945 | 1178 | |
vhardy@2945 | 1179 | <tr> |
vhardy@2945 | 1180 | <td><img src="images/region-overflow-break.png" alt= |
vhardy@2945 | 1181 | "result if region-overflow is set to 'break'"></td> |
vhardy@2945 | 1182 | |
vhardy@2945 | 1183 | <td><img src="images/region-overflow-auto-overflow-hidden.png" |
vhardy@2945 | 1184 | alt="regions receiving the flow content"></td> |
vhardy@2945 | 1185 | </tr> |
vhardy@2945 | 1186 | </table> |
vhardy@2945 | 1187 | |
vhardy@2945 | 1188 | <p class="caption">Different values for the region-overflow |
vhardy@2945 | 1189 | property</p> |
vhardy@2945 | 1190 | </div> |
vhardy@3377 | 1191 | |
vhardy@4314 | 1192 | <div class="note"><span class="note-prefix">Note </span> |
vhardy@3377 | 1193 | <p>The 'overflow' property is honored on a region: if region content overflows, |
vhardy@3377 | 1194 | such as the borders of elements on the |
vhardy@3377 | 1195 | last line, the 'overflow' property controls the visibility of the overflowing |
vhardy@3377 | 1196 | content. See the 'overflow' property definition |
vhardy@3377 | 1197 | ([[CSS21]]).</p> |
vhardy@3377 | 1198 | </div> |
vhardy@2945 | 1199 | |
vhardy@2945 | 1200 | <h3 id="the-at-region-style-rule">The @region rule</h3> |
vhardy@4412 | 1201 | |
vhardy@2945 | 1202 | <p>An '@region' rule contains style declarations specific to particular |
vhardy@2945 | 1203 | regions.</p> |
vhardy@2945 | 1204 | |
vhardy@3660 | 1205 | <pre> |
vhardy@3660 | 1206 | @region <selector> { |
vhardy@3660 | 1207 | ... CSS styling rules ... |
vhardy@3660 | 1208 | } |
vhardy@3660 | 1209 | </pre> |
vhardy@3660 | 1210 | |
vhardy@2945 | 1211 | <p>The '@region' rule consists of the keyword '@region' followed by a |
vhardy@2945 | 1212 | <a href="http://www.w3.org/TR/css3-selectors/#selector-syntax">selector</a> |
vhardy@4314 | 1213 | and a block of style rules. The '@region' rule and the selector constitute |
vhardy@5353 | 1214 | the region's 'flow fragment' selector. The region's flow fragment selector |
vhardy@4314 | 1215 | specifies which range of elements in the flow are subject to the style rules in the |
vhardy@4314 | 1216 | following block: it applies to the range (see |
vhardy@5094 | 1217 | [[!DOM]]) from the region's flow that flows in the |
vhardy@2945 | 1218 | selected region(s).</p> |
vhardy@2945 | 1219 | |
vhardy@4412 | 1220 | <div class="issue-marker" data-bug_id="15713" data-bug_status="NEW"> |
vhardy@4395 | 1221 | <a href= |
vhardy@4404 | 1222 | "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15713">Bug-15713</a> |
vhardy@4395 | 1223 | |
vhardy@4395 | 1224 | <div class="issue-details"> |
vhardy@4395 | 1225 | <p class="short-desc">Model for styling element fragments</p> |
vhardy@4395 | 1226 | </div> |
vhardy@4395 | 1227 | </div> |
vhardy@4395 | 1228 | |
vhardy@5353 | 1229 | <p>Elements that are fully or partially in the 'flow fragment' may match any of the |
vhardy@4338 | 1230 | selectors found in the style rule. However, the style rules only apply to the |
vhardy@4338 | 1231 | portion of the element that falls into the corresponding region.</p> |
vhardy@4338 | 1232 | |
vhardy@4338 | 1233 | |
vhardy@2945 | 1234 | |
vhardy@3547 | 1235 | <p>Only a limited list of properties can be set in a region style rule:</p> |
vhardy@4395 | 1236 | |
vhardy@4412 | 1237 | <div class="issue-marker" data-bug_id="15190" data-bug_status="NEW"> |
vhardy@4395 | 1238 | <a href= |
vhardy@4404 | 1239 | "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15190">Bug-15190</a> |
vhardy@4395 | 1240 | |
vhardy@4395 | 1241 | <div class="issue-details"> |
vhardy@4395 | 1242 | <p class="short-desc">List of region style properties</p> |
vhardy@4395 | 1243 | </div> |
vhardy@4395 | 1244 | </div> |
vhardy@3547 | 1245 | |
vhardy@3547 | 1246 | <ol> |
bert@3938 | 1247 | <li><a href="http://www.w3.org/TR/CSS2/fonts.html">font properties</a></li> |
bert@3938 | 1248 | <li><a href="http://www.w3.org/TR/CSS2/colors.html">color property</a></li> |
stearns@5453 | 1249 | <li><a href="http://www.w3.org/TR/css3-color/#transparency">opacity property</a></li> |
bert@3938 | 1250 | <li><a href="http://www.w3.org/TR/css3-background/#backgrounds">background property</a></li> |
bert@3938 | 1251 | <li><a href="http://www.w3.org/TR/CSS2/text.html#propdef-word-spacing">'word-spacing'</a></li> |
bert@3938 | 1252 | <li><a href="http://www.w3.org/TR/CSS2/text.html#propdef-letter-spacing">'letter-spacing'</a></li> |
bert@3938 | 1253 | <li><a href="http://www.w3.org/TR/CSS2/text.html#propdef-text-decoration">'text-decoration'</a></li> |
bert@3938 | 1254 | <li><a href="http://www.w3.org/TR/CSS2/text.html#propdef-text-transform">'text-transform'</a></li> |
bert@3938 | 1255 | <li><a href="http://www.w3.org/TR/CSS2/visudet.html#propdef-line-height">'line-height'</a></li> |
bert@3938 | 1256 | <li><a href="http://www.w3.org/TR/css3-background/#borders">border properties</a></li> |
bert@3938 | 1257 | <li><a href="http://www.w3.org/TR/css3-background/#corners">rounded corner properties</a></li> |
bert@3938 | 1258 | <li><a href="http://www.w3.org/TR/css3-background/#border-images">border images properties</a></li> |
bert@3938 | 1259 | <li><a href="http://www.w3.org/TR/CSS2/box.html#margin-properties">margin properties</a></li> |
bert@3938 | 1260 | <li><a href="http://www.w3.org/TR/CSS2/box.html#padding-properties">padding properties</a></li> |
bert@3938 | 1261 | <li><a href="http://www.w3.org/TR/css3-text/#text-shadow">'text-shadow' property</a></li> |
bert@3938 | 1262 | <li><a href="http://www.w3.org/TR/css3-background/#the-box-shadow">'box-shadow' property</a></li> |
bert@3938 | 1263 | <li><a href="http://www.w3.org/TR/css3-background/#the-box-decoration-break">'box-decoration-break' property</a></li> |
vhardy@3547 | 1264 | <li><a href="http://www.w3.org/TR/CSS2/visudet.html#the-width-property">'width' property</a></li> |
vhardy@3547 | 1265 | </ol> |
vhardy@3547 | 1266 | |
vhardy@3547 | 1267 | |
vhardy@2945 | 1268 | |
vhardy@2945 | 1269 | <div class="example" id="region-style-example"> |
vhardy@5352 | 1270 | <p>In the following example, the <span>named flow</span> 'article_flow' flows |
vhardy@2945 | 1271 | through 'region_1' and 'region_2'.</p> |
vhardy@2945 | 1272 | <pre> |
vhardy@2945 | 1273 | <style> |
vhardy@2945 | 1274 | #div_1 { |
vhardy@3262 | 1275 | <strong>flow-into: article_flow;</strong> |
vhardy@2945 | 1276 | } |
vhardy@2945 | 1277 | |
vhardy@4119 | 1278 | #region1, #region2 { |
vhardy@3547 | 1279 | <strong>flow-from: article_flow;</strong> |
vhardy@2945 | 1280 | } |
vhardy@2945 | 1281 | |
vhardy@4119 | 1282 | /* region style "RSA" */ |
vhardy@4119 | 1283 | <strong>@region #region1, #region2</strong> { |
vhardy@2945 | 1284 | div {...} |
vhardy@2945 | 1285 | p {...} |
vhardy@2945 | 1286 | } |
vhardy@2945 | 1287 | |
vhardy@4119 | 1288 | /* region style "RSB" */ |
vhardy@4119 | 1289 | <strong>@region #region1</strong> { |
vhardy@2945 | 1290 | p {...} |
vhardy@2945 | 1291 | } |
vhardy@2945 | 1292 | |
vhardy@2945 | 1293 | </style> |
vhardy@2945 | 1294 | |
vhardy@2945 | 1295 | <div id="div_1"> |
vhardy@2945 | 1296 | <p id="p_1">...</p> |
vhardy@2945 | 1297 | <p id="p_2">...</p> |
vhardy@2945 | 1298 | </div> |
vhardy@2945 | 1299 | |
vhardy@4119 | 1300 | <div id="region1"></div> |
vhardy@4119 | 1301 | <div id="region2"></div> |
vhardy@2945 | 1302 | |
vhardy@2945 | 1303 | </pre> |
vhardy@2945 | 1304 | |
vhardy@2945 | 1305 | <div id="region_styling_illustration"> |
vhardy@2945 | 1306 | <img id="region_styling_img_2" src="images/region-styling-2.png" |
vhardy@2945 | 1307 | alt= |
vhardy@2945 | 1308 | "Illustration showing how a named flow content fits into regions to illustrate the @region styling." |
vhardy@2945 | 1309 | name="region_styling_img_2"> |
vhardy@2945 | 1310 | |
vhardy@2945 | 1311 | <ul class="swatch-list"> |
vhardy@2945 | 1312 | <li><span class="swatch" style= |
vhardy@2945 | 1313 | "background:#1C75BC"> </span>div div_1</li> |
vhardy@2945 | 1314 | |
vhardy@2945 | 1315 | <li><span class="swatch" style= |
vhardy@2945 | 1316 | "background:crimson"> </span>paragraph p_1</li> |
vhardy@2945 | 1317 | |
vhardy@2945 | 1318 | <li><span class="swatch" style= |
vhardy@2945 | 1319 | "background:white"> </span>paragraph p_2</li> |
vhardy@2945 | 1320 | |
vhardy@2945 | 1321 | <li><span class="swatch" style= |
vhardy@2945 | 1322 | "background:#E6E7E8"> </span>range of flow that fits into |
vhardy@2945 | 1323 | region_1</li> |
vhardy@2945 | 1324 | |
vhardy@2945 | 1325 | <li><span class="swatch" style= |
vhardy@2945 | 1326 | "background:#BCBEC0"> </span>range of flow that fits into |
vhardy@2945 | 1327 | region_2</li> |
vhardy@2945 | 1328 | </ul> |
vhardy@2945 | 1329 | </div> |
vhardy@2945 | 1330 | |
vhardy@3547 | 1331 | <p>The region style ''RSA'' applies to flow content that is laid out in either |
vhardy@2945 | 1332 | 'region_1' or 'region_2'.</p> |
vhardy@2945 | 1333 | |
vhardy@3547 | 1334 | <p>The first rule set ''div {...}'' applies to all <code class= |
vhardy@3547 | 1335 | "html"><div></code> elements that fit partially or fully into 'region_1' or |
vhardy@3547 | 1336 | 'region_2'. <code class="html">div_1</code> is split between 'region_1' and |
vhardy@3547 | 1337 | 'region_2' and gets the style from this style rule.</p> |
vhardy@2945 | 1338 | |
vhardy@3547 | 1339 | <p>The second rule set ''p {...}'' applies to all <code class= |
vhardy@3547 | 1340 | "html"><p></code> elements that fit into 'region_1' or |
vhardy@3547 | 1341 | 'region_2'. In our example, both <code class="html">p_1</code> |
vhardy@3547 | 1342 | and <code class="html">p_2</code> are selected.</p> |
vhardy@2945 | 1343 | |
vhardy@2945 | 1344 | <p>The region style ''RSB'' applies to flow content that fits in |
vhardy@2945 | 1345 | 'region_1'.</p> |
vhardy@2945 | 1346 | |
vhardy@2945 | 1347 | <p>The first rule set ''p {...}'' matches <code class="html">p_1</code> |
vhardy@3547 | 1348 | and <code class="html">p_2</code> |
vhardy@5353 | 1349 | because these paragraphs flow into 'region_1'. Only the fragment of |
vhardy@3547 | 1350 | <code class="html">p_2</code> that flows into <code class="html">region_1</code> |
vhardy@3547 | 1351 | is styled with this rule.</p> |
vhardy@2945 | 1352 | </div> |
vhardy@2945 | 1353 | |
vhardy@2779 | 1354 | |
vhardy@2779 | 1355 | |
vhardy@4412 | 1356 | <div class="issue-marker" data-bug_id="15734" data-bug_status="NEW"> |
vhardy@4395 | 1357 | <a href= |
vhardy@4404 | 1358 | "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15734">Bug-15734</a> |
vhardy@4395 | 1359 | |
vhardy@4395 | 1360 | <div class="issue-details"> |
vhardy@4395 | 1361 | <p class="short-desc">@region and specificity</p> |
vhardy@4395 | 1362 | </div> |
vhardy@4395 | 1363 | </div> |
vhardy@4395 | 1364 | |
vhardy@2945 | 1365 | <p>The specificity of the selectors in a '@region' rule is calculated as |
vhardy@2945 | 1366 | <a href="http://www.w3.org/TR/css3-selectors/#specificity">defined</a> in |
vhardy@3073 | 1367 | the CSS Selectors module (see [[SELECT]]). In other words, the '@region' |
vhardy@2945 | 1368 | rule adds an extra condition to the selector's matching, but does not |
vhardy@2945 | 1369 | change the selector's specificity. This is the same behavior as selectors |
vhardy@2945 | 1370 | appearing in '@media' rules declaration blocks (see [[MEDIAQ]]), where the |
vhardy@2945 | 1371 | rule does not influence the selectors' specificity.</p> |
vhardy@2779 | 1372 | |
vhardy@2779 | 1373 | <p>Consequently, selectors that match a given element (as describe above), |
bert@3938 | 1374 | participate in the <a href="http://www.w3.org/TR/2011/REC-CSS2-20110607/cascade.html#cascading-order">CSS Cascading |
vhardy@3073 | 1375 | order</a> as defined in [[!CSS21]].</p> |
vhardy@3660 | 1376 | |
vhardy@4314 | 1377 | <div> |
vhardy@4314 | 1378 | Region styling does not apply to nested regions. For example, if a region |
vhardy@3660 | 1379 | 'A' receives content from a flow that contains region 'B', the content that |
vhardy@3660 | 1380 | flows into 'B' does not receive the region styling specified for region 'A'. |
vhardy@3660 | 1381 | </div> |
vhardy@5131 | 1382 | |
vhardy@5131 | 1383 | <h2 id="multi-column-regions">Multi-column regions</h2> |
vhardy@5131 | 1384 | |
stearns@5579 | 1385 | <p>A |
stearns@5469 | 1386 | <a href="http://dev.w3.org/csswg/css3-multicol/#multi-column-element">multi-column</a> |
stearns@5579 | 1387 | [[CSS3COL]] |
stearns@5579 | 1388 | element can have |
stearns@5579 | 1389 | an assigned <em><span>named flow</span></em>. |
stearns@5579 | 1390 | The element becomes part |
stearns@5579 | 1391 | of the region chain |
stearns@5579 | 1392 | for that named flow, |
stearns@5579 | 1393 | and flows its content fragments |
stearns@5579 | 1394 | through columns according to |
stearns@5579 | 1395 | the multi-column specification |
stearns@5579 | 1396 | [[!CSS3COL]]. |
stearns@5469 | 1397 | In particular, |
stearns@5579 | 1398 | when computing the |
stearns@5579 | 1399 | <a href="#flow-fragment-height-resolution">flow fragment height</a> |
stearns@5469 | 1400 | of a multi-column element |
stearns@5469 | 1401 | that is associated with a <em><span>named flow</span></em>, |
stearns@5469 | 1402 | the <a href="http://dev.w3.org/csswg/css3-multicol/#column-fill">'column-fill'</a> |
stearns@5579 | 1403 | [[!CSS3COL]] |
stearns@5469 | 1404 | property is honored |
stearns@5469 | 1405 | to balance the fragments of content |
stearns@5579 | 1406 | that would flow through |
stearns@5579 | 1407 | its columns.</p> |
vhardy@2779 | 1408 | |
vhardy@5131 | 1409 | <div class="example"> |
vhardy@5131 | 1410 | <p>The following example:</p> |
vhardy@5131 | 1411 | <pre> |
vhardy@5131 | 1412 | <style> |
vhardy@5131 | 1413 | #multi-col { |
vhardy@5131 | 1414 | column-count: 2; |
vhardy@5131 | 1415 | flow-from: article; |
vhardy@5131 | 1416 | height: 6em; |
vhardy@5131 | 1417 | column-gap: 1em; |
vhardy@5131 | 1418 | } |
vhardy@5131 | 1419 | |
vhardy@5131 | 1420 | #remainder { |
vhardy@5131 | 1421 | flow-from: article; |
vhardy@5131 | 1422 | height: auto; |
vhardy@5131 | 1423 | } |
vhardy@5131 | 1424 | </style> |
vhardy@5131 | 1425 | |
vhardy@5490 | 1426 | <article>...</article> |
vhardy@5131 | 1427 | <div id="multicol"></div> |
vhardy@5131 | 1428 | <div id="remainder"></div></pre> |
stearns@5469 | 1429 | <p>is equivalent in rendering to, for example:</p> |
vhardy@5131 | 1430 | <pre> |
vhardy@5131 | 1431 | <style> |
vhardy@5131 | 1432 | #flex { |
vhardy@5131 | 1433 | display: flex; |
vhardy@5131 | 1434 | flex-pack: justify; |
stearns@5469 | 1435 | height: 6em; |
vhardy@5131 | 1436 | } |
vhardy@5131 | 1437 | #flex > div { |
vhardy@5131 | 1438 | flow-from: article; |
vhardy@5131 | 1439 | width: calc(50% - 0.5em); |
vhardy@5131 | 1440 | } |
vhardy@5131 | 1441 | |
vhardy@5131 | 1442 | #remainder { |
vhardy@5131 | 1443 | flow-from: article; |
vhardy@5131 | 1444 | height: auto; |
vhardy@5131 | 1445 | } |
vhardy@5131 | 1446 | </style> |
vhardy@5131 | 1447 | |
vhardy@5490 | 1448 | <article>...</article> |
vhardy@5131 | 1449 | <div id="flex"> |
vhardy@5131 | 1450 | <div /> |
vhardy@5131 | 1451 | <div /> |
vhardy@5131 | 1452 | </div> |
vhardy@5131 | 1453 | <div id="remainder"></div></pre> |
vhardy@5131 | 1454 | |
vhardy@5131 | 1455 | |
vhardy@5131 | 1456 | |
vhardy@5131 | 1457 | </div> |
vhardy@5131 | 1458 | |
stearns@5579 | 1459 | <p>Overflow of multicol regions |
stearns@5579 | 1460 | is mostly handled |
stearns@5579 | 1461 | according to the same rules |
stearns@5579 | 1462 | as other CSS Regions. |
stearns@5579 | 1463 | If the remainder of the named flow |
stearns@5579 | 1464 | does not fit |
stearns@5579 | 1465 | in the multicol region, |
stearns@5579 | 1466 | then the rest |
stearns@5579 | 1467 | of the content flows into |
stearns@5579 | 1468 | the remaining region chain. |
stearns@5579 | 1469 | However, |
stearns@5579 | 1470 | if a multicol region |
stearns@5579 | 1471 | is the last region |
stearns@5579 | 1472 | in a <span>region chain</a>, |
stearns@5579 | 1473 | then the multicol region must follow the |
stearns@5579 | 1474 | <a href="http://dev.w3.org/csswg/css3-multicol/#overflow-columns">overflow column rules</a> |
stearns@5579 | 1475 | [[!CSS3COL]].</p> |
vhardy@5131 | 1476 | |
vhardy@3272 | 1477 | <h2 id="pseudo_elements">Pseudo-elements</h2> |
vhardy@3558 | 1478 | |
vhardy@4412 | 1479 | <div class="issue-marker" data-bug_id="15188" data-bug_status="NEW"> |
vhardy@4395 | 1480 | <a href= |
vhardy@4404 | 1481 | "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15188">Bug-15188</a> |
vhardy@4395 | 1482 | |
vhardy@4395 | 1483 | <div class="issue-details"> |
vhardy@4412 | 1484 | <p class="short-desc">add functionality for having textual description like "continued here" or "continued on page x" to regions.</p> |
vhardy@4395 | 1485 | </div> |
vhardy@4395 | 1486 | </div> |
vhardy@3272 | 1487 | |
stearns@5470 | 1488 | <p>It can be useful |
stearns@5470 | 1489 | to visually mark the content |
stearns@5470 | 1490 | to highlight that a content thread |
stearns@5470 | 1491 | is flowing through the region chain. |
stearns@5470 | 1492 | For example, a marker |
stearns@5470 | 1493 | such as <em>'continued below'</em> clearly indicates, |
stearns@5470 | 1494 | at the end of a CSS Region, |
stearns@5470 | 1495 | that there is more content in the flow |
stearns@5470 | 1496 | which can be found by scrolling past |
stearns@5470 | 1497 | whatever content interrupts the region chain.</p> |
vhardy@3272 | 1498 | |
stearns@5470 | 1499 | <p>The '::before' and '::after' pseudo-elements (see [[!SELECT]]) |
stearns@5470 | 1500 | let content authors mark the beginning |
stearns@5470 | 1501 | and end of a region with such markers.</p> |
vhardy@3272 | 1502 | |
vhardy@3547 | 1503 | <h3 id="processing-model">Processing model</h3> |
vhardy@3272 | 1504 | |
stearns@5470 | 1505 | <p>The '::before' content is laid out |
stearns@5470 | 1506 | in the region prior to |
stearns@5470 | 1507 | any other content coming from the flow. |
stearns@5470 | 1508 | Note that it is possible |
stearns@5470 | 1509 | to set the '::before' pseudo-element's 'display' property |
stearns@5470 | 1510 | to 'run-in' to align it |
stearns@5470 | 1511 | with the content's inline boxes.</p> |
vhardy@3547 | 1512 | |
stearns@5470 | 1513 | <p>The '::after' content is laid out |
stearns@5470 | 1514 | in the region after laying out |
stearns@5470 | 1515 | the flow fragment content. |
stearns@5470 | 1516 | Then, flow content is removed from the fragment |
stearns@5470 | 1517 | to accommodate the '::after' content. |
stearns@5470 | 1518 | Accommodating means that the '::after' content |
stearns@5470 | 1519 | is laid out without overflowing the region. |
stearns@5470 | 1520 | The 'display' property of the '::after' content |
stearns@5470 | 1521 | can be set to 'run-in' to align |
stearns@5470 | 1522 | with the region's content's inline boxes. |
stearns@5470 | 1523 | In that case, the '::after' content becomes |
stearns@5470 | 1524 | the last inline box of the previous element |
stearns@5470 | 1525 | in the flow that has some visual rendering |
stearns@5470 | 1526 | in the region and can accommodate for the '::after' box.</p> |
stearns@5470 | 1527 | |
stearns@5470 | 1528 | <p>If there is not enough room to accommodate |
stearns@5470 | 1529 | the ::before content, |
stearns@5470 | 1530 | the '::after' content after removing all flow fragment content, |
stearns@5470 | 1531 | or a combination of the two, |
stearns@5470 | 1532 | then the ::before and/or ::after content overflows.</p> |
vhardy@3272 | 1533 | |
stearns@5472 | 1534 | <h2 id="cssom_view_and_css_regions">CSSOM</h2> |
vhardy@2779 | 1535 | |
stearns@5576 | 1536 | <div class="issue-marker-wrapper"> |
vhardy@4412 | 1537 | <div class="issue-marker" data-bug_id="15679" data-bug_status="NEW"> |
vhardy@4395 | 1538 | <a href= |
vhardy@4404 | 1539 | "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15679">Bug-15679</a> |
vhardy@4395 | 1540 | |
vhardy@4395 | 1541 | <div class="issue-details"> |
vhardy@4395 | 1542 | <p class="short-desc">elementFromPoint and CSS regions</p> |
vhardy@4395 | 1543 | </div> |
vhardy@4395 | 1544 | </div> |
stearns@5576 | 1545 | <div class="issue-marker" data-bug_id="15933" data-bug_status="ASSIGNED"> |
stearns@5576 | 1546 | <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15933">Bug-15933</a> |
stearns@5576 | 1547 | <div class="issue-details"> |
stearns@5576 | 1548 | <p class="short-desc">Terms in WebIDL snippets inconsistently linked</p> |
stearns@5576 | 1549 | </div> |
stearns@5576 | 1550 | </div> |
stearns@5576 | 1551 | </div> |
vhardy@3558 | 1552 | |
vhardy@2779 | 1553 | <p>Since content may flow into multiple regions, authors need a way to |
vhardy@2945 | 1554 | determine if there are enough regions to flow all the content from a named |
vhardy@5349 | 1555 | flow. This is especially important considering that the size of regions or |
vhardy@5349 | 1556 | the size of the content may change depending on the display context. For |
vhardy@5349 | 1557 | example, flowing the same content on a mobile phone with a small screen may |
vhardy@5349 | 1558 | require more regions than on a large desktop display. Another example is the |
vhardy@5349 | 1559 | user changing the font size of text flowing through regions. Depending on |
vhardy@5349 | 1560 | the change, new regions may be needed to accommodate for the additional |
vhardy@5349 | 1561 | space required to fit the larger text or some regions may need to be removed |
vhardy@5349 | 1562 | for smaller text. |
vhardy@5349 | 1563 | </p> |
vhardy@4395 | 1564 | |
vhardy@2945 | 1565 | <h3 id="the-namedflow-interface">The NamedFlow interface</h3> |
vhardy@5232 | 1566 | |
vhardy@5232 | 1567 | <p>A <span>named flow</span> is created when it becomes referenced by the |
vhardy@5349 | 1568 | 'flow-into' and/or 'flow-from' computed values. The following APIs allow |
vhardy@5232 | 1569 | scripts to reference a <code class="idl">NamedFlow</code> object representation |
vhardy@5232 | 1570 | of a <span>named flow</span>.</p> |
vhardy@5232 | 1571 | |
vhardy@5537 | 1572 | <p>An additional method and an additional attribute on the <a href= |
vhardy@5094 | 1573 | "http://www.w3.org/TR/dom/#interface-document"><code class= |
vhardy@5352 | 1574 | "idl">Document</code></a> interface provide access to <span>named flows</span>.</p> |
vhardy@4400 | 1575 | |
vhardy@4400 | 1576 | <pre class="idl"> |
vhardy@5095 | 1577 | partial interface <a href= |
vhardy@5094 | 1578 | "http://www.w3.org/TR/dom/#interface-document">Document</a> { |
stearns@5423 | 1579 | readonly attribute <a href="#dom-named-flow-collection">NamedFlowCollection</a> <a href="#document-namedflows">namedFlows</a>; |
stearns@5423 | 1580 | <a href="#dom-named-flow">NamedFlow?</a> <a href="#document-getflowbyname">getFlowByName(DOMString name)</a>; |
vhardy@4400 | 1581 | }; |
vhardy@4400 | 1582 | </pre> |
vhardy@4400 | 1583 | |
vhardy@5349 | 1584 | <p>The <dfn id="document-namedflows"><code class="idl">namedFlows</code></dfn> attribute on the <a href= |
vhardy@5094 | 1585 | "http://www.w3.org/TR/dom/#interface-document"><code class= |
vhardy@5232 | 1586 | "idl">Document</code></a> interface returns the live list of all the current <span>named |
vhardy@5537 | 1587 | flows</span> in the document. </p> |
vhardy@4400 | 1588 | |
vhardy@5352 | 1589 | <p>The <code class="idl">namedFlows</code> collection must include all <span>named flows</span> |
vhardy@5537 | 1590 | that are currently in the <code>CREATED</code> state. |
vhardy@5537 | 1591 | The list must not include <span>named flows</span> that are in the <code>NULL</code> state. </p> |
vhardy@5232 | 1592 | |
vhardy@5349 | 1593 | <p>The <dfn id="document-getflowbyname"><code class="idl">getFlowByName</code></dfn> method on the <a href= |
vhardy@5094 | 1594 | "http://www.w3.org/TR/dom/#interface-document"><code class= |
vhardy@5352 | 1595 | "idl">Document</code></a> interface provides access to the document's <code class="idl">NamedFlow</code> |
vhardy@5352 | 1596 | instances. The return value depends on the <span>named flow</span> |
vhardy@5232 | 1597 | state:</p> |
vhardy@4400 | 1598 | |
vhardy@5232 | 1599 | <ul> |
vhardy@5255 | 1600 | <li><code class="idl">NULL</code>: the user agent must return <code>null</code>.</li> |
vhardy@5537 | 1601 | <li><code class="idl">CREATED</code>: the user agent must return a valid |
vhardy@5537 | 1602 | <code class="idl">NamedFlow</code> instance.</li> |
vhardy@5232 | 1603 | </ul> |
vhardy@5537 | 1604 | |
vhardy@4400 | 1605 | |
vhardy@5349 | 1606 | <p>The <dfn id="dom-named-flow-collection"><code class="idl">NamedFlowCollection</code></dfn> |
vhardy@4400 | 1607 | interface provides a list of current <code class="idl">NamedFlow</code> instances in the |
vhardy@4400 | 1608 | document. The collection is live and methods operate on the underlying data, not a snapshot of |
vhardy@4400 | 1609 | the data.</p> |
vhardy@4400 | 1610 | |
vhardy@2945 | 1611 | <pre class="idl"> |
vhardy@4400 | 1612 | interface NamedFlowCollection { |
stearns@5423 | 1613 | readonly attribute unsigned long <a href="#dom-named-flow-collection-length">length</a>; |
stearns@5423 | 1614 | getter <a href="#dom-named-flow">NamedFlow?</a> <a href="#named-flow-collection-item">item (unsigned long index)</a>; |
stearns@5423 | 1615 | };</pre> |
vhardy@4400 | 1616 | |
vhardy@5349 | 1617 | <p>The <dfn id="dom-named-flow-collection-length"><code class="idl">length</code></dfn> |
vhardy@4415 | 1618 | attribute returns the number of items in the collection.</p> |
vhardy@5349 | 1619 | <p>The <dfn id="dom-named-flow-collection-item"><code class="idl">item(index)</code></dfn> |
vhardy@4400 | 1620 | method returns the item at index <em>index</em> |
vhardy@5095 | 1621 | in the collection or <code class="idl">null</code> if <em>index</em> is out of range. |
vhardy@5095 | 1622 | An object <code>collection</code> implementing <code>NamedFlowCollection</code> supports |
vhardy@5095 | 1623 | indices in the range <code>0 ≤ index < collection.length</code>.</p> |
vhardy@2945 | 1624 | |
vhardy@5349 | 1625 | <p>The <dfn id="dom-named-flow"><code class="idl">NamedFlow</code></dfn> |
vhardy@5537 | 1626 | interface offers a representation of a <span>named flow</span> instance.</p> |
vhardy@5537 | 1627 | |
vhardy@5537 | 1628 | <p>The <code class="idl">NamedFlow</code> interface |
vhardy@5537 | 1629 | can be used for different purposes. |
vhardy@5537 | 1630 | For example, the <code>getRegionsByContent()</code> method |
vhardy@5537 | 1631 | can help navigate by bookmark: |
vhardy@5537 | 1632 | a script can find the <span>region</span>s |
vhardy@5537 | 1633 | that display a particular anchor |
vhardy@5537 | 1634 | and bring them to view.</p> |
vhardy@5537 | 1635 | |
vhardy@5537 | 1636 | <p>Likewise, the interface allows authors |
vhardy@5537 | 1637 | to check if all content has been fitted |
vhardy@5537 | 1638 | into existing regions. |
vhardy@5537 | 1639 | If it has, the <code>overset</code> attribute |
vhardy@5537 | 1640 | would be false.</p> |
vhardy@5537 | 1641 | |
vhardy@2945 | 1642 | <pre class="idl"> |
vhardy@5349 | 1643 | interface <a href="#dom-named-flow">NamedFlow</a> implements <a href="http://www.w3.org/TR/dom/#interface-eventtarget">EventTarget</a> { |
vhardy@5349 | 1644 | readonly attribute DOMString <a href="#dom-named-flow-name">name</a>; |
vhardy@5349 | 1645 | readonly attribute boolean <a href="#dom-named-flow-overset">overset</a>; |
vhardy@5349 | 1646 | sequence<<a href="#region-interface">Region</a>> <a href="#dom-named-flow-get-regions">getRegions()</a>; |
vhardy@5349 | 1647 | readonly attribute integer <a href="#dom-named-flow-first-empty-region-index">firstEmptyRegionIndex</a>; |
vhardy@5349 | 1648 | <a href="http://www.w3.org/TR/dom/#interface-nodelist">NodeList</a> <a href="#dom-named-flow-get-content">getContent()</a>; |
vhardy@5349 | 1649 | sequence<<a href="#region-interface">Region</a>> <a href="#dom-named-flow-get-regions-by-content">getRegionsByContent</a>(<a href="http://www.w3.org/TR/dom/#interface-node">Node</a> node)</a>; |
vhardy@3681 | 1650 | };</pre> |
vhardy@2945 | 1651 | |
vhardy@5349 | 1652 | <p>The <dfn id="dom-named-flow-name"><code class="idl">name</code></dfn> attribute |
vhardy@4415 | 1653 | returns the name of the <code class="idl">NamedFlow</code> instance.</p> |
vhardy@4400 | 1654 | |
stearns@5472 | 1655 | <p>The <dfn id="dom-named-flow-overset"><code class= "idl">overset</code></dfn> |
stearns@5472 | 1656 | attribute returns true |
stearns@5472 | 1657 | if there are <span>named flow</span> fragments |
stearns@5472 | 1658 | that do not fit in the associated region chain. |
stearns@5472 | 1659 | The attribute also returns true |
stearns@5472 | 1660 | if there is no associated region chain. |
stearns@5472 | 1661 | Otherwise, it returns false. </p> |
vhardy@3681 | 1662 | |
stearns@5472 | 1663 | <p>The <dfn id="dom-named-flow-get-regions"><code class="idl">getRegions()</code></dfn> |
stearns@5472 | 1664 | method returns the sequence |
stearns@5472 | 1665 | of regions in the <span>region chain</span> |
stearns@5472 | 1666 | associated with the <span>named flow</span>. |
stearns@5472 | 1667 | Note that the returned values |
stearns@5472 | 1668 | is a static sequence |
stearns@5472 | 1669 | in document order.</p> |
vhardy@5255 | 1670 | |
stearns@5472 | 1671 | <p>The <dfn id="dom-named-flow-first-empty-region-index">firstEmptyRegionIndex</dfn> |
stearns@5472 | 1672 | is the index of the first region |
stearns@5472 | 1673 | in the region chain with the <code>regionOverset</code> attribute |
stearns@5472 | 1674 | set to <code>empty</code>. |
stearns@5472 | 1675 | If all regions have the <code>regionOverset</code> attribute |
stearns@5472 | 1676 | set to <code>fit</code> or <code>overset</code>, |
stearns@5472 | 1677 | the value for <code>firstEmptyRegionIndex</code> is <code>-1</code>. |
stearns@5472 | 1678 | If there are no regions in the <span>region chain</span>, |
stearns@5472 | 1679 | the value is <code>-1</code> as well. </p> |
vhardy@5264 | 1680 | |
stearns@5472 | 1681 | <p>The <dfn id="dom-named-flow-get-content">getContent()</dfn> |
stearns@5472 | 1682 | method returns an ordered collection |
stearns@5472 | 1683 | of nodes that constitute the <span>named flow</span>. |
stearns@5472 | 1684 | The returned list is a static snapshot |
stearns@5472 | 1685 | of the <span>named flow</span> content |
stearns@5472 | 1686 | at the time the method is invoked. |
stearns@5472 | 1687 | This list contains the elements |
stearns@5472 | 1688 | that were moved to the <span>named flow</span> |
stearns@5472 | 1689 | but not their descendants |
stearns@5472 | 1690 | (unless the descendants are themselves |
stearns@5472 | 1691 | moved to the <span>named flow</span>). |
vhardy@3681 | 1692 | </p> |
vhardy@3681 | 1693 | |
stearns@5472 | 1694 | <p>The <dfn id="dom-named-flow-get-regions-by-content">getRegionsByContent()</dfn> |
stearns@5472 | 1695 | method returns the sequence of regions |
stearns@5472 | 1696 | that contain at least part |
stearns@5472 | 1697 | of the target content node. |
stearns@5472 | 1698 | Note that the returned values |
stearns@5472 | 1699 | is a static sequence |
stearns@5472 | 1700 | in document order.</p> |
vhardy@5255 | 1701 | |
vhardy@5537 | 1702 | |
vhardy@5537 | 1703 | <p>The <span>named flow</span> states are :</p> |
vhardy@5537 | 1704 | |
vhardy@5537 | 1705 | <ul> |
vhardy@5537 | 1706 | <li><code class="idl">NULL</code>: the <span>named flow</span> is not referenced |
vhardy@5537 | 1707 | by any 'flow-into' or 'flow-from' computed value.</li> |
vhardy@5537 | 1708 | <li><code class="idl">CREATED</code>: the <span>named flow</span> is referenced by |
vhardy@5537 | 1709 | at least one 'flow-into' or 'flow-from' computed value.</li> |
vhardy@5537 | 1710 | </ul> |
vhardy@5537 | 1711 | |
vhardy@5537 | 1712 | <p>A <code class="idl">NamedFlow</code> |
vhardy@5537 | 1713 | object is live: it always represents the <span>named flow</span> with the corresponding |
vhardy@5537 | 1714 | name even if that <span>named flow</span> has transitioned to the <code>NULL</code> state.</p> |
vhardy@5537 | 1715 | |
vhardy@5537 | 1716 | <p>If a script holds a reference to a <code class="idl">NamedFlow</code> instance that |
vhardy@5537 | 1717 | has entered the <code>NULL</code> state, its attributes and methods should behave |
vhardy@5537 | 1718 | as follows:</p> |
vhardy@5537 | 1719 | |
vhardy@5537 | 1720 | <ul> |
vhardy@5537 | 1721 | <li>the <code class="idl">name</code> attribute returns its value as normal.</li> |
vhardy@5537 | 1722 | <li>the <code class="idl">overset</code> attribute returns <code class="idl">true</code>.</li> |
vhardy@5537 | 1723 | <li>the <code class="idl">getRegions</code> method returns an empty sequence.</li> |
vhardy@5537 | 1724 | <li>the <code class="idl">firstEmptyRegionIndex</code> attribute returns <code class="idl">-1</code>.</li> |
vhardy@5537 | 1725 | <li>the <code class="idl">getContent()</code> method returns an empty <code class="idl">NodeList</code> instance.</li> |
vhardy@5537 | 1726 | <li>the <code class="idl">getRegionsByContentNode()</code> method retuns an empty sequence.</li> |
vhardy@5537 | 1727 | </ul> |
vhardy@5255 | 1728 | |
stearns@5576 | 1729 | <div class="issue-marker" data-bug_id="16382" data-bug_status="ASSIGNED"> |
stearns@5576 | 1730 | <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=16382">Bug-16382</a> |
stearns@5576 | 1731 | <div class="issue-details"> |
stearns@5576 | 1732 | <p class="short-desc">Should we have a NamedFlow.getRegionsByFlowRanges?</p> |
stearns@5576 | 1733 | </div> |
stearns@5576 | 1734 | </div> |
stearns@5576 | 1735 | |
vhardy@5255 | 1736 | <h3 id="the-region-interface">The Region interface</h3> |
vhardy@2945 | 1737 | |
vhardy@5255 | 1738 | <p>The <dfn id='region-interface'><code class="idl">Region</code> interface</dfn> |
vhardy@5255 | 1739 | provides an abstraction for <a href= |
vhardy@5255 | 1740 | "http://www.w3.org/TR/dom/#interface-element"><code class= |
vhardy@5255 | 1741 | "idl">Element</code>s</a>, pseudo-elements or other CSS constructs (such as |
vhardy@5390 | 1742 | <a href="http://dev.w3.org/csswg/css3-page-template/#templates-and-slots">slots</a> |
vhardy@5390 | 1743 | [[!CSS3-PAGE-TEMPLATE]]) which can be regions.</p> |
vhardy@5255 | 1744 | |
vhardy@5255 | 1745 | <pre class="idl"> |
stearns@5423 | 1746 | interface Region { |
stearns@5423 | 1747 | readonly attribute DOMString <a href="#dom-region-regionoverset">regionOverset</a>; |
stearns@5423 | 1748 | readonly attribute DOMString <a href="#dom-region-flowfrom">flowFrom</a>; |
stearns@5423 | 1749 | sequence<<a href="#">Range</a>>? <a href= |
stearns@5423 | 1750 | "#dom-region-getregionflowranges">getRegionFlowRanges()</a>; |
stearns@5423 | 1751 | };</pre> |
vhardy@2945 | 1752 | |
vhardy@5255 | 1753 | <p>The <dfn id="dom-region-regionoverset"><code class= |
vhardy@5255 | 1754 | "idl">regionOverset</code></dfn> attribute returns one of the following |
vhardy@5255 | 1755 | values:</p> |
vhardy@2945 | 1756 | |
vhardy@5255 | 1757 | <dl> |
vhardy@5255 | 1758 | <dt>'overset'</dt> |
vhardy@2945 | 1759 | |
vhardy@5349 | 1760 | <dd>The region is the last one in the |
vhardy@5255 | 1761 | <span title="region-chain">region chain</span> and |
vhardy@5255 | 1762 | not able to fit the remaining content from the <span>named flow</span>. |
vhardy@5255 | 1763 | Note that the region's <a href= |
vhardy@5255 | 1764 | "http://www.w3.org/TR/CSS21/visufx.html#overflow"><code class= |
vhardy@5255 | 1765 | "idl">overflow</code></a> property value can be used to control the |
vhardy@5255 | 1766 | visibility of the overflowing content and the |
vhardy@5255 | 1767 | 'region-overflow' property controls whether or not fragmentation happens |
vhardy@5349 | 1768 | on the content that overflows the last region.</dd> |
vhardy@2945 | 1769 | |
vhardy@5255 | 1770 | <dt>'fit'</dt> |
vhardy@2945 | 1771 | |
vhardy@5349 | 1772 | <dd>The region's flow fragment content fits into the region's <a href= |
vhardy@5255 | 1773 | "http://www.w3.org/TR/CSS21/box.html#box-dimensions">content box</a>. |
vhardy@5255 | 1774 | If the region is the last one in the <span title= |
vhardy@5255 | 1775 | "region-chain">region chain</span>, it means that the content fits |
vhardy@5255 | 1776 | without overflowing. If the region is not the last one in the region |
vhardy@5255 | 1777 | chain, that means the <span>named flow</span> |
vhardy@5349 | 1778 | content is further fitted in subsequent regions. In this |
vhardy@5349 | 1779 | last case, note that the <span>named flow</span> fragment may be |
vhardy@5349 | 1780 | empty (for example if the region is too small to accommodate any content).</dd> |
vhardy@2945 | 1781 | |
vhardy@5255 | 1782 | <dt>'empty'</dt> |
vhardy@2945 | 1783 | |
vhardy@5349 | 1784 | <dd>All content from the <span>named flow</span> was fitted in prior regions.</dd> |
vhardy@5255 | 1785 | |
vhardy@5255 | 1786 | </dl> |
vhardy@2945 | 1787 | |
vhardy@5352 | 1788 | <p>Note that if there is no content in the <span>named flow</span>, all regions associated |
vhardy@5352 | 1789 | with that <span>named flow</span> should have their <code class="idl">regionOverset</code> |
vhardy@5255 | 1790 | attribute return 'empty'. |
vhardy@5255 | 1791 | If there is content in the flow but that content does not generate any box |
vhardy@5255 | 1792 | for visual formatting, the 'overset' attribute on the first region in the |
vhardy@5255 | 1793 | region chain associated with the flow will return 'fit'.</p> |
vhardy@2945 | 1794 | |
vhardy@5255 | 1795 | <p>The <dfn id="dom-region-flowfrom">flowFrom</dfn> attribute returns the name of the |
vhardy@5255 | 1796 | <span>named flow</span> this region is associated with.</p> |
vhardy@5255 | 1797 | |
stearns@5472 | 1798 | <p>The <dfn id="dom-region-getregionflowranges">getRegionFlowRanges</dfn> method |
stearns@5472 | 1799 | returns an array of <a href= "http://www.w3.org/TR/dom/#interface-range">Range</a> |
stearns@5472 | 1800 | instances corresponding to fragment |
stearns@5472 | 1801 | from the <span>named flow</span> |
stearns@5472 | 1802 | that is laid out in the region. |
stearns@5472 | 1803 | If the region has not received a fragment |
stearns@5472 | 1804 | because it is too small to accommodate any, |
stearns@5472 | 1805 | the method returns a single <code class="idl">Range</code> |
stearns@5472 | 1806 | where the <code>startContainer</code> |
stearns@5472 | 1807 | and <code>startOffset</code> |
stearns@5472 | 1808 | have the same values as |
stearns@5472 | 1809 | the <code>endContainer</code> |
stearns@5472 | 1810 | and <code>endOffset</code> |
stearns@5472 | 1811 | and therefore the collapsed attribute |
stearns@5472 | 1812 | on the <code class="idl">Range</code> is true. |
stearns@5472 | 1813 | In that situation, |
stearns@5472 | 1814 | if the region is the first |
stearns@5472 | 1815 | in the <span>region chain</span>, |
stearns@5472 | 1816 | the <code>startContainer</code> |
stearns@5472 | 1817 | is the first <code>Node</code> |
stearns@5472 | 1818 | in the <span>named flow</span> |
stearns@5472 | 1819 | and the <code>startOffset</code> is zero. |
stearns@5472 | 1820 | If the region is the last region |
stearns@5472 | 1821 | in the region chain |
stearns@5472 | 1822 | (but not the first and only one), |
stearns@5472 | 1823 | the <code>startContainer</code> |
stearns@5472 | 1824 | and <code>startOffset</code> |
stearns@5472 | 1825 | are the same values as |
stearns@5472 | 1826 | the <code>endContainer</code> |
stearns@5472 | 1827 | and <code>endOffset</code> |
stearns@5472 | 1828 | on the previous region |
stearns@5472 | 1829 | in the <span>region chain</span>. |
stearns@5472 | 1830 | The method returns null |
stearns@5472 | 1831 | if the <span>region</span> object |
stearns@5472 | 1832 | is not (or no longer) a region.</p> |
vhardy@2945 | 1833 | |
vhardy@5255 | 1834 | <div class="note"> |
vhardy@5255 | 1835 | <p>A <code class="idl">Region</code> instance may represent and |
vhardy@5255 | 1836 | object that is no longer a <span>region</span>. This may happen, for example if the |
vhardy@5255 | 1837 | 'flow-from' property on the corresponding pseudo-element, element or other construct |
vhardy@5255 | 1838 | becomes 'none' but a script is still holding a reference to the <code class="idl">Region</code> object.</p> |
vhardy@5350 | 1839 | </div> |
vhardy@5350 | 1840 | |
vhardy@5350 | 1841 | <p>If a <code class="idl">Region</code> instance is no longer a <span>region</span>, |
vhardy@5255 | 1842 | accessing its attributes (<code class="idl">regionOverset</code> and <code class="idl">flowFrom</code>) or |
vhardy@5255 | 1843 | invoking its <code class= |
vhardy@5255 | 1844 | "idl"><span title="#document-element-getregionflowranges">getRegionFlowRanges</span></code> |
vhardy@5255 | 1845 | method throws a <a href="http://www.w3.org/TR/dom/#interface-domexception"><code class="idl">DOMException</code></a> with the |
vhardy@5255 | 1846 | <a href="http://www.w3.org/TR/dom/#dom-domexception-invalid_access_err"><code class="idl">INVALID_ACCESS_ERR</code></a> error code.</p> |
vhardy@5255 | 1847 | </div> |
stearns@5598 | 1848 | |
stearns@5598 | 1849 | <h3 id="region-style-rule-interface">The CSSRegionStyleRule interface</h3> |
stearns@5598 | 1850 | |
stearns@5598 | 1851 | <p>The CSSRegionStyleRule interface represents |
stearns@5598 | 1852 | an '@region' rule |
stearns@5598 | 1853 | in a CSS style sheet. |
stearns@5598 | 1854 | This rule type is added |
stearns@5598 | 1855 | to the <a href="http://dev.w3.org/csswg/cssom/#cssrule"><code>CSSRule</code></a> [[!CSSOM]] interface.</p> |
stearns@5598 | 1856 | |
stearns@5598 | 1857 | <pre class="idl"> |
stearns@5598 | 1858 | partial interface CSSRule { |
stearns@5598 | 1859 | const unsigned short REGION_STYLE_RULE = 1001; |
stearns@5598 | 1860 | } |
stearns@5598 | 1861 | </pre> |
stearns@5598 | 1862 | <dt>REGION_STYLE_RULE</dt> |
stearns@5598 | 1863 | <dd>The rule is a CSSRegionStyleRule</dd> |
stearns@5598 | 1864 | |
stearns@5598 | 1865 | <pre class="idl"> |
stearns@5598 | 1866 | interface CSSRegionStyleRule : CSSRule { |
stearns@5598 | 1867 | attribute DOMString selectorText; |
stearns@5598 | 1868 | readonly attribute CSSRuleList cssRules; |
stearns@5598 | 1869 | unsigned long insertRule(DOMString rule, unsigned long index) |
stearns@5598 | 1870 | raises(DOMException); |
stearns@5598 | 1871 | void deleteRule(unsigned long index) |
stearns@5598 | 1872 | raises(DOMException); |
stearns@5598 | 1873 | }; |
stearns@5598 | 1874 | </pre> |
stearns@5598 | 1875 | |
stearns@5598 | 1876 | <p>The <dfn id="region-style-rule-selectorText"> |
stearns@5598 | 1877 | <code class="idl">selectorText</code></dfn> |
stearns@5598 | 1878 | attribute gets and sets |
stearns@5598 | 1879 | the associated selector |
stearns@5598 | 1880 | as defined in section <a href="http://dev.w3.org/csswg/cssom/#dom-cssstylerule-selectortext">6.4.3</a> of [[!CSSOM]]. |
stearns@5598 | 1881 | |
stearns@5598 | 1882 | <p>The <dfn id="region-style-rule-cssRules"> |
stearns@5598 | 1883 | <code class="idl">cssRules</code></dfn> |
stearns@5598 | 1884 | attribute must return a |
stearns@5598 | 1885 | <a href="http://dev.w3.org/csswg/cssom/#cssrulelist"><code>CSSRuleList</code></a> [[!CSSOM]] |
stearns@5598 | 1886 | object for the list of |
stearns@5598 | 1887 | <a href="http://www.w3.org/TR/DOM-Level-2-Style/css.html#CSS-CSSStyleRule"><code class="idl">CSSStyleRules</code></a> |
stearns@5598 | 1888 | specified in the region style block.</p> |
stearns@5598 | 1889 | |
stearns@5598 | 1890 | <p>The <dfn id="region-style-rule-insertRule"> |
stearns@5598 | 1891 | <code class="idl">insertRule(rule, index)</code></dfn> |
stearns@5598 | 1892 | method inserts a |
stearns@5598 | 1893 | <a href="http://www.w3.org/TR/DOM-Level-2-Style/css.html#CSS-CSSStyleRule"><code class="idl">CSSStyleRule</code></a> |
stearns@5598 | 1894 | into the region style block |
stearns@5598 | 1895 | before the specified index. |
stearns@5598 | 1896 | If the index is equal to the length |
stearns@5598 | 1897 | of the <a href="http://dev.w3.org/csswg/cssom/#cssrulelist"><code>CSSRuleList</code></a> the |
stearns@5598 | 1898 | <a href="http://www.w3.org/TR/DOM-Level-2-Style/css.html#CSS-CSSStyleRule"><code class="idl">CSSStyleRule</code></a> |
stearns@5598 | 1899 | is inserted at the end of the list.</p> |
stearns@5598 | 1900 | |
stearns@5598 | 1901 | <p>Possible exceptions:</p> |
stearns@5598 | 1902 | <ul> |
stearns@5598 | 1903 | <li>HIERARCHY_REQUEST_ERR: |
stearns@5598 | 1904 | Raised if the rule to insert is not a |
stearns@5598 | 1905 | <a href="http://www.w3.org/TR/DOM-Level-2-Style/css.html#CSS-CSSStyleRule"><code class="idl">CSSStyleRule</code></a>.</li> |
stearns@5598 | 1906 | <li>INDEX_SIZE_ERR: |
stearns@5598 | 1907 | Raised if the specified index |
stearns@5598 | 1908 | is not a valid insertion point.</li> |
stearns@5598 | 1909 | <li>SYNTAX_ERR: |
stearns@5598 | 1910 | Raised if the specified rule |
stearns@5598 | 1911 | has a syntax error |
stearns@5598 | 1912 | and is unparsable.</li> |
stearns@5598 | 1913 | </ul> |
stearns@5598 | 1914 | <p>The <dfn id="region-style-rule-deleteRule"> |
stearns@5598 | 1915 | <code class="idl">deleteRule(index)</code></dfn> |
stearns@5598 | 1916 | method deletes the <a href="http://www.w3.org/TR/DOM-Level-2-Style/css.html#CSS-CSSStyleRule"><code class="idl">CSSStyleRule</code></a> in the CSSRuleList |
stearns@5598 | 1917 | at the specified index.</p> |
stearns@5598 | 1918 | |
stearns@5598 | 1919 | <p>Possible exceptions:</p> |
stearns@5598 | 1920 | <ul> |
stearns@5598 | 1921 | <li>INDEX_SIZE_ERR: |
stearns@5598 | 1922 | Raised if the specified index |
stearns@5598 | 1923 | does not correspond to a rule |
stearns@5598 | 1924 | in the region style block.</li> |
stearns@5598 | 1925 | </ul> |
stearns@5598 | 1926 | |
vhardy@3272 | 1927 | <h3 id="region-flow-layout-events">Region flow layout events</h3> |
vhardy@4395 | 1928 | |
vhardy@5349 | 1929 | <p><a href="#dom-named-flow"><code class="idl">NamedFlow</code></a> objects are |
vhardy@5264 | 1930 | <a href="">Event Targets</a> which |
vhardy@5352 | 1931 | dispatch <code class="idl">regionLayoutUpdate</code> events when there is a |
vhardy@5353 | 1932 | possible layout change of their <span>named flow</span> fragment. Note that the event is asynchronous.</p> |
vhardy@3073 | 1933 | |
stearns@5576 | 1934 | <div class="issue-marker" data-bug_id="16391" data-bug_status="ASSIGNED"> |
stearns@5576 | 1935 | <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=16391">Bug-16391</a> |
stearns@5576 | 1936 | <div class="issue-details"> |
stearns@5576 | 1937 | <p class="short-desc">regionLayoutUpdate needs to be async</p> |
stearns@5576 | 1938 | </div> |
stearns@5576 | 1939 | </div> |
stearns@5576 | 1940 | <div class="note">The remaining issue in this bug is when the event gets fired.</div> |
stearns@5576 | 1941 | |
vhardy@3073 | 1942 | <table class="event-desc" border="0" summary="This table contains information about the semantics of the given event type" cellpadding="2" cellspacing="0"> |
vhardy@3073 | 1943 | <tbody><tr class="assert must"><th>Type</th> |
vhardy@3272 | 1944 | <td class="eventname"><strong><code>regionLayoutUpdate</code></strong></td></tr> |
vhardy@5264 | 1945 | <tr class="assert must"><th>Interface</th> <td><code><a href="http://www.w3.org/TR/DOM-Level-3-Events/#webidl-events-UIEvent">UIEvent</a></code> (see [[!DOM-LEVEL-3-EVENTS]])</td></tr> |
vhardy@3302 | 1946 | <tr class="assert must"><th>Sync / Async</th> <td>Async</td></tr> |
vhardy@3073 | 1947 | <tr class="assert must"><th>Bubbles</th> <td>Yes</td></tr> |
vhardy@5349 | 1948 | <tr class="assert must"><th>Target</th> <td><a href="#dom-named-flow"><code class="idl">NamedFlow</code></a></td></tr> |
vhardy@3073 | 1949 | <tr class="assert must"><th>Cancelable</th> <td>Yes</td></tr> |
vhardy@3073 | 1950 | <tr class="assert must"><th>Default action</th> <td>none</td></tr> |
vhardy@3073 | 1951 | <tr class="assert must"><th>Context info</th> |
vhardy@3073 | 1952 | <td> |
vhardy@3073 | 1953 | <ul> |
vhardy@5264 | 1954 | <li><code class="attribute-name">Event.target</code>: |
vhardy@5349 | 1955 | <a href="#dom-named-flow"><code class="idl">NamedFlow</code></a> whose layout may have changed</li> |
vhardy@3073 | 1956 | </ul> |
vhardy@3073 | 1957 | </td> |
vhardy@3073 | 1958 | </tr> |
vhardy@3073 | 1959 | </tbody></table> |
vhardy@2819 | 1960 | |
stearns@5472 | 1961 | <h3 id="cssomview-and-regions">Clarifications on pre-existing APIs</h3> |
vhardy@5270 | 1962 | |
vhardy@5270 | 1963 | |
vhardy@5270 | 1964 | <h4 id="cssomview-getclientrects-and-getboundingclientrect"><code class="idl">getClientRects()</code> and <code>getBoundingClientRects()</code></h4> |
vhardy@5270 | 1965 | |
stearns@5472 | 1966 | <p>The <a href="http://www.w3.org/TR/cssom-view/">CSSOM View Module</a> |
stearns@5472 | 1967 | defines how user agents compute |
stearns@5472 | 1968 | the bounding client rectangle |
stearns@5472 | 1969 | for an element (<code class="idl">getBoundingClientRect()</code>) |
stearns@5472 | 1970 | and its generated boxes (<code class="idl">getClientRects()</code>).</p> |
vhardy@5270 | 1971 | |
stearns@5472 | 1972 | <p>This definition applies to |
stearns@5472 | 1973 | the (possibly) multiple boxes |
stearns@5472 | 1974 | generated for an element in a named flow |
stearns@5472 | 1975 | flowing through a region chain. |
stearns@5472 | 1976 | The <code class="idl">getClientRects()</code> method |
stearns@5472 | 1977 | returns the list of boxes generated |
stearns@5472 | 1978 | for each of the element fragments |
stearns@5472 | 1979 | laid out in different regions. |
stearns@5472 | 1980 | The <code>getBoundingClientRect()</code> method |
stearns@5472 | 1981 | operates as specified in the |
stearns@5472 | 1982 | <a href="http://www.w3.org/TR/cssom-view/">CSSOM View Module</a> |
stearns@5472 | 1983 | as well and is computed |
stearns@5472 | 1984 | from the set of rectangles |
stearns@5472 | 1985 | returned by <code class="idl">getClientRects()</code>.</p> |
vhardy@5270 | 1986 | |
vhardy@5270 | 1987 | <h4 id="cssomview-offset-attributes"><code class="idl">offsetTop</code>, <code class="idl">offsetLeft</code>, |
vhardy@5270 | 1988 | <code class="idl">offsetWidth</code> and <code class="idl">offsetWidth</code></h4> |
vhardy@5270 | 1989 | |
vhardy@5270 | 1990 | <p>The computation of the <a href="http://dev.w3.org/csswg/cssom-view/#offset-attributes">offset attributes</a> |
vhardy@5270 | 1991 | for elements laid out in a <span>named flow</code> follow the <a href="http://dev.w3.org/csswg/cssom-view/#offset-attribute">specification</a>. For the purpose of the |
vhardy@5270 | 1992 | algorithm, the <em>first CSS layout box</em> associated |
vhardy@5270 | 1993 | with an element laid out in a <span>named flow</span> is the box generated for the first region |
vhardy@5270 | 1994 | the element is laid out into.</p> |
vhardy@5270 | 1995 | |
vhardy@5289 | 1996 | <h2 id="regions-visual-formatting-details">Regions visual formatting details</h2> |
vhardy@5289 | 1997 | |
vhardy@5377 | 1998 | <p>Regions are laid out by CSS and take part in the normal box model and other layout models |
vhardy@5335 | 1999 | offered by CSS modules such as flexible boxes ([[CSS3-FLEXBOX]]). However, <span>regions</span> |
vhardy@5378 | 2000 | lay out a fragment of their <span>named flow</span> instead of laying out descendant content as happens with other |
vhardy@5335 | 2001 | boxes.</p> |
vhardy@5289 | 2002 | |
stearns@5423 | 2003 | <p>This section describes the model for laying out <span>regions</span> |
stearns@5423 | 2004 | and for laying out <span>named flow</span> content into regions. |
stearns@5423 | 2005 | The descriptions in this section are biased towards a horizontal writing mode, |
stearns@5423 | 2006 | using <span>width</span> for logical width (or measure) |
stearns@5423 | 2007 | and <span>height</span> for logical height (or extent) |
stearns@5423 | 2008 | as <a href="http://www.w3.org/TR/css3-writing-modes/#abstract-dimensions">defined</a> |
stearns@5423 | 2009 | in the CSS Writing Modes Module [[!CSS3-WRITING-MODES]]). |
stearns@5423 | 2010 | To use this model in a vertical writing mode apply the principles |
stearns@5423 | 2011 | <a href="http://www.w3.org/TR/css3-writing-modes/#vertical-layout">described</a> |
stearns@5423 | 2012 | in that specification.</p> |
vhardy@5335 | 2013 | |
vhardy@5289 | 2014 | <h3 id="regions-flow-content-box">The Region Flow Content Box (RFBC)</h3> |
vhardy@5289 | 2015 | |
vhardy@5289 | 2016 | <p>A region box lays out the following boxes:</p> |
vhardy@5289 | 2017 | |
vhardy@5289 | 2018 | <ul> |
vhardy@5289 | 2019 | <li>The boxes generated by its <code class="css">::before</code> and |
vhardy@5335 | 2020 | <code class="css">::after</code> pseudo-elements, if any.</code> |
vhardy@5335 | 2021 | <li>The anonymous <def>region flow content box</dev> (called <def>RFCB</def> in this document) which |
vhardy@5352 | 2022 | contains the fragment of the <span>named flow</span> that the region receives.</li> |
vhardy@5289 | 2023 | </ul> |
vhardy@5289 | 2024 | |
vhardy@5289 | 2025 | <div class="figure"> |
vhardy@5289 | 2026 | <img src="images/RFCB.svg" width="600px" /> |
vhardy@5289 | 2027 | <p class="caption">The Region Flow Content Box (RFCB)</p> |
vhardy@5289 | 2028 | </div> |
vhardy@5289 | 2029 | |
vhardy@5366 | 2030 | <p>Laying out a <span>region</span> box follows the same processing rules as for any other |
vhardy@5335 | 2031 | <a href="http://www.w3.org/TR/CSS2/visuren.html#block-boxes">block container box</a>.</p> |
vhardy@5289 | 2032 | |
vhardy@5354 | 2033 | <p>The <span>RFCB</span> is a <a href="http://www.w3.org/TR/CSS21/visuren.html#block-boxes">block container box</a> |
vhardy@5354 | 2034 | with a <a href="">computed</a> 'width' of 'auto' and a whose <a href="">used</a> 'height' is |
vhardy@5354 | 2035 | resolved as detailed below.</li> |
vhardy@5335 | 2036 | |
vhardy@5354 | 2037 | <h4 id="rfbc-width-resolution">RFCB 'width' resolution</h4> |
vhardy@5335 | 2038 | |
vhardy@5335 | 2039 | <p>At various points in the visual formatting of documents containing regions, the |
vhardy@5366 | 2040 | used 'width' of RFCBs and regions need to be resolved. In all cases, the resolution is done following the |
vhardy@5354 | 2041 | rules for <a href="http://www.w3.org/TR/CSS2/visudet.html#Computing_widths_and_margins">calculating |
vhardy@5366 | 2042 | widths and margins</a> (see [[!CSS21]]). Sometimes, resolving the used 'width' value |
vhardy@5366 | 2043 | requires measuring the content's |
vhardy@5366 | 2044 | <code class="css">min-content</code> and <code class="css">max-content</code> values (as |
vhardy@5366 | 2045 | <a href="http://www.w3.org/TR/css3-writing-modes/#intrinsic-sizing">defined</a> in the CSS Writing Modes Module [[!CSS3-WRITING-MODES]]). For an RFCB, <strong>these measures are |
vhardy@5366 | 2046 | made on the <em>entire</em> associated <span>named flow</span> content</strong>.</p> |
vhardy@5335 | 2047 | |
vhardy@5366 | 2048 | <p>As a consequence, all <span>RFCBs</span> of <span>regions</span> associated with a given |
vhardy@5366 | 2049 | <span>named flow</span> share the |
vhardy@5366 | 2050 | same <code class="css">min-content</code> and <code class="css">max-content</code> measures.</p> |
vhardy@5366 | 2051 | |
vhardy@5366 | 2052 | <p>This approach is consistent with the <a href="http://www.w3.org/TR/css3-break/#varying-size-boxes">box model for breaking</a> ([[!CSS3-BREAK]]).</p> |
vhardy@5335 | 2053 | |
vhardy@5335 | 2054 | |
vhardy@5335 | 2055 | <h3 id="regions-visual-formatting-steps">Regions visual formatting steps</h3> |
vhardy@5289 | 2056 | |
vhardy@5377 | 2057 | <p>Formatting documents that contain <span>named flows</span> laid out in regions is a three-step |
vhardy@5335 | 2058 | process:</p> |
vhardy@5335 | 2059 | |
vhardy@5335 | 2060 | <ul> |
vhardy@5377 | 2061 | <li><em>Step 1: RFCB <def>flow fragment height</def> resolution</em>. In this step, the heights of fragments |
vhardy@5377 | 2062 | fitting in the regions' RFCBs are resolved.</li> |
vhardy@5366 | 2063 | <li><em>Step 2: document and regions layout</em>. In this step, the document content and regions are |
vhardy@5366 | 2064 | laid out. However, <span>named flow</span> content is not laid out in regions yet.</li> |
vhardy@5352 | 2065 | <li><em>Step 3: <span>named flow</span> layout</em>. In this step, the content of <span>named flows</span> is laid |
vhardy@5335 | 2066 | out in their respective <span>region chains</span>.</li> |
vhardy@5335 | 2067 | </ul> |
vhardy@5291 | 2068 | |
vhardy@5335 | 2069 | <div class="figure"> |
vhardy@5335 | 2070 | <img src="images/regions-layout-three-steps.svg" width="600px" /> |
vhardy@5335 | 2071 | <p class="caption">Regions visual formatting steps</p> |
vhardy@5335 | 2072 | </div> |
vhardy@5335 | 2073 | |
vhardy@5289 | 2074 | |
vhardy@5354 | 2075 | <h4 id="rfcb-flow-fragment-height-resolution">Step 1: RFCB flow fragment height resolution</h4> |
vhardy@5335 | 2076 | |
vhardy@5354 | 2077 | <p>Conceptually, resolving the flow fragment height is a two phase process.</p> |
vhardy@5289 | 2078 | |
vhardy@5354 | 2079 | <h5 id="rfcb-flow-fragment-height-resolution-phase-1">RFCB flow fragment height resolution, Phase 1</h5> |
vhardy@5289 | 2080 | |
vhardy@5291 | 2081 | <p>The document is laid out with a |
vhardy@5289 | 2082 | <a href="http://www.w3.org/TR/CSS2/cascade.html#used-value">used</a> height of zero |
vhardy@5289 | 2083 | for all <span>RFCB</span>s. In this phase, the content of <span>named flows</span> is not laid out in |
vhardy@5291 | 2084 | <span>regions</span>. This phase yields resolved position and sizes for all regions and |
vhardy@5289 | 2085 | their RFCBs in the document.</p> |
vhardy@5289 | 2086 | |
vhardy@5366 | 2087 | <h5 id="rfcb-flow-fragment-height-resolution-phase-2">RFCB flow fragment height resolution, Phase 2</h5> |
vhardy@5289 | 2088 | |
vhardy@5354 | 2089 | <p><span>Named flows</span> are laid out in <span>regions</span>. The |
vhardy@5378 | 2090 | user agent resolves the <em><span>flow fragment height</span></em> for |
vhardy@5354 | 2091 | the <span>RFCB</span>s using the remainder of the flow and accounting for |
vhardy@5354 | 2092 | <a href="http://www.w3.org/TR/css3-break/">fragmentation rules</a>. |
vhardy@5378 | 2093 | This process accounts for constraints such as the 'height' or 'max-height' values, as described |
vhardy@5289 | 2094 | in the CSS 2.1 section on |
vhardy@5289 | 2095 | <a href="http://www.w3.org/TR/CSS2/visudet.html#Computing_heights_and_margins">calculating heights |
vhardy@5302 | 2096 | and margins</a> (see the <a href="http://www.w3.org/TR/CSS2/visudet.html#normal-block">Block-level |
vhardy@5302 | 2097 | non-replaced elements in normal flow when 'overflow' computes to 'visible'</a> section and the |
vhardy@5335 | 2098 | <a href="http://www.w3.org/TR/CSS2/visudet.html#block-root-margin">complicated cases</a> section). |
vhardy@5335 | 2099 | During this phase, generated content is laid out according to the |
vhardy@5378 | 2100 | <a href="#processing-model">rules</a> described earlier in this document. |
vhardy@5335 | 2101 | </p> |
vhardy@5302 | 2102 | |
stearns@5579 | 2103 | <h4 id="regions-boxes-layout">Step 2: region boxes layout</h4> |
vhardy@5335 | 2104 | |
vhardy@5366 | 2105 | <p>In this step, the document is laid out according to the normal CSS layout rules.</p> |
vhardy@5366 | 2106 | |
vhardy@5366 | 2107 | <p>If a measure of the content is required to resolve the used 'width' of the region box, the value |
vhardy@5366 | 2108 | is resolved as described in the |
vhardy@5366 | 2109 | <a href="#rfbc-width-resolution">RFCB width resolution</a> section.</p> |
vhardy@5366 | 2110 | |
vhardy@5366 | 2111 | <p>If a measure of the content |
vhardy@5413 | 2112 | is required to resolve the used height of the RFCB (for example if the region box is absolutely positioned), |
vhardy@5366 | 2113 | the <span>flow fragment height</span> resolved in Step 1 is used for the vertical content measure of the |
vhardy@5413 | 2114 | RFCB.</p> |
vhardy@5366 | 2115 | |
vhardy@5335 | 2116 | <p>At the end of this step, regions are laid out and ready to receive |
vhardy@5352 | 2117 | content from their associated <span>named flows</span>.</p> |
vhardy@5335 | 2118 | |
vhardy@5335 | 2119 | <h4 id="named-flows-layout">Step 3: named flows layout</h4> |
vhardy@5335 | 2120 | |
vhardy@5352 | 2121 | <p>In this final step, the content of <span>named flows</span> is laid out in the <span>regions</span>' RFCBs |
vhardy@5335 | 2122 | along with the generated content boxes.</p> |
vhardy@5335 | 2123 | |
vhardy@5366 | 2124 | <p>The used 'width' for RFCBs is resolved <a href="#rfbc-width-resolution">as described before</a>.</p> |
vhardy@5366 | 2125 | |
vhardy@5366 | 2126 | <p>The used 'height' of RFCBs is resolved such that none of the boxes in the region box's normal flow |
vhardy@5366 | 2127 | overflow the region's box. In other words, the RFCB boxes are stretched vertically |
vhardy@5366 | 2128 | to accommodate as much of the flow as possible without overflowing the region box and |
vhardy@5366 | 2129 | accounting for <a href="http://www.w3.org/TR/css3-break/">fragmentation rules</a> and |
vhardy@5366 | 2130 | generated content boxes.</p> |
vhardy@5366 | 2131 | |
vhardy@5366 | 2132 | <p>During this phase, generated content is laid out according to the |
vhardy@5378 | 2133 | <a href="#processing-model">rules</a> |
vhardy@5366 | 2134 | described earlier in this document.</p> |
vhardy@5366 | 2135 | |
vhardy@5413 | 2136 | <div class="note"> |
vhardy@5413 | 2137 | <p>The model for resolving auto sized regions will cause, under certain circumstances, |
vhardy@5413 | 2138 | the flow content to be overset or underset. In other words, it will not fit tightly. |
vhardy@5413 | 2139 | The model prevents having circular dependencies in the layout model. Implementations |
vhardy@5413 | 2140 | may decide to apply further layout steps to ensure that the whole flow content is |
vhardy@5413 | 2141 | displayed to the user, even in edge cases.</p> |
vhardy@5413 | 2142 | </div> |
vhardy@5413 | 2143 | |
vhardy@5335 | 2144 | <h3 id="regions-visual-formatting-implementation-note">Regions visual formatting: implementation note</h3> |
vhardy@5335 | 2145 | |
vhardy@5377 | 2146 | <p>The process for resolving an RFCB's 'height' and the three-step process used to |
vhardy@5378 | 2147 | lay out documents containing regions and <span>named flows</span> are |
vhardy@5335 | 2148 | <em>conceptual</em> descriptions of what the layout |
vhardy@5335 | 2149 | should yield and implementations should optimize to reduce the number of |
vhardy@5335 | 2150 | steps and phases necessary wherever possible.</p> |
vhardy@5335 | 2151 | |
vhardy@5335 | 2152 | <h3 id="regions-visual-formatting-examples">Regions visual formatting example</h3> |
vhardy@5335 | 2153 | |
vhardy@5335 | 2154 | <p>This section is non-normative.</p> |
vhardy@5335 | 2155 | |
vhardy@5335 | 2156 | <p>This example considers a document where content flows between three regions, |
vhardy@5335 | 2157 | and region boxes are intermixed with the normal document content.</p> |
vhardy@5335 | 2158 | |
vhardy@5335 | 2159 | <div class="example"> |
vhardy@5335 | 2160 | <pre> |
vhardy@5336 | 2161 | <style> |
vhardy@5490 | 2162 | article { |
stearns@5422 | 2163 | flow-into: article; |
vhardy@5336 | 2164 | } |
vhardy@5336 | 2165 | |
vhardy@5336 | 2166 | #rA, #rB, #rC { |
stearns@5445 | 2167 | flow-from: article; |
vhardy@5336 | 2168 | height: auto; |
vhardy@5366 | 2169 | margin: 1em 1em 0em 1em; |
vhardy@5366 | 2170 | padding: 1em; |
vhardy@5366 | 2171 | border: 3px solid #46A4E9; |
vhardy@5336 | 2172 | } |
vhardy@5336 | 2173 | |
vhardy@5336 | 2174 | #rA { |
vhardy@5336 | 2175 | width: auto; |
vhardy@5336 | 2176 | height: auto; |
vhardy@5336 | 2177 | } |
vhardy@5336 | 2178 | |
vhardy@5336 | 2179 | #rB { |
vhardy@5336 | 2180 | float: left; |
vhardy@5366 | 2181 | width: 15em; |
vhardy@5336 | 2182 | height: auto; |
vhardy@5336 | 2183 | max-height: 150px; |
vhardy@5336 | 2184 | } |
vhardy@5336 | 2185 | |
vhardy@5336 | 2186 | #rC { |
vhardy@5336 | 2187 | float: right; |
vhardy@5366 | 2188 | width: 12em; |
vhardy@5336 | 2189 | height: auto; |
vhardy@5336 | 2190 | } |
vhardy@5336 | 2191 | |
vhardy@5336 | 2192 | #main-flow { |
vhardy@5366 | 2193 | padding: 0em 1em 0em 1em; |
vhardy@5336 | 2194 | } |
vhardy@5336 | 2195 | |
vhardy@5336 | 2196 | </style> |
vhardy@5336 | 2197 | <body> |
vhardy@5490 | 2198 | <article> |
stearns@5422 | 2199 | <p style="region-break-after:always;">I am not a ... </p> |
vhardy@5336 | 2200 | <p>...</p> |
vhardy@5490 | 2201 | </article> |
vhardy@5336 | 2202 | <div id="rA"></div> |
vhardy@5336 | 2203 | <div id="rB"></div> |
vhardy@5336 | 2204 | <div id="rC"></div> |
vhardy@5336 | 2205 | |
vhardy@5336 | 2206 | <div id="main-flow"> |
vhardy@5336 | 2207 | <p>Lorem ipsum dolor ...</p> |
vhardy@5336 | 2208 | </div> |
vhardy@5336 | 2209 | </body> |
vhardy@5335 | 2210 | </pre> |
vhardy@5335 | 2211 | </div> |
vhardy@5335 | 2212 | |
vhardy@5366 | 2213 | <p>The following sections and figures illustrate the intermediate results for the visual formatting process. |
vhardy@5366 | 2214 | In the following, we call RFCB-A, RFCB-B and RFCB-C the <span>RFCBs</span> for |
vhardy@5366 | 2215 | regions rA, rB and rC respectively. </p> |
vhardy@5366 | 2216 | |
vhardy@5366 | 2217 | <h4>Step 1 - Phase 1: Laying out RFCBs with used height of zero</h4> |
vhardy@5366 | 2218 | |
vhardy@5366 | 2219 | <p>Applying the rules for Step 1, Phase 1, the computed 'auto' 'width' values for the RFCBs are resolved |
vhardy@5366 | 2220 | to used values according to the normal |
vhardy@5366 | 2221 | <a href="http://www.w3.org/TR/CSS2/visudet.html#Computing_widths_and_margins">CSS layout rules</a> meaning they |
vhardy@5366 | 2222 | stretch to the width of their containing block's content box.</p> |
vhardy@5366 | 2223 | |
vhardy@5366 | 2224 | <ol> |
vhardy@5366 | 2225 | <li>RFCB-A: stretches to fit the rA content box.</li> |
vhardy@5366 | 2226 | Since rA also has an 'auto' 'width', its own used 'width' is stretched to fit the |
vhardy@5366 | 2227 | <code><body></code> content box.</p> |
vhardy@5366 | 2228 | <li>RFCB-B: stretches to fit the <code>rB</code> content box.</li> |
vhardy@5366 | 2229 | <li>RFCB-C: stretches to fit the <code>rC</code> content box.</li> |
vhardy@5366 | 2230 | </ol> |
vhardy@5366 | 2231 | |
vhardy@5366 | 2232 | <p>Also applying the rules for Step 1, Phase 1, the used values for the RFCBs 'height' properties are all zero.</p> |
vhardy@5366 | 2233 | |
vhardy@5366 | 2234 | <p>Conceptually, this produces the layout illustrated below.</p> |
vhardy@5335 | 2235 | |
vhardy@5335 | 2236 | <div class="figure"> |
vhardy@5366 | 2237 | <img src="images/flow-fragment-height-phase-1.png" width="500px" alt="Step 1 - Phase 1: Layout RFBCs with used heights of 0"/> |
vhardy@5366 | 2238 | <p class="caption">Step 1 - Phase 1: Layout RFBCs with used heights of 0</p> |
vhardy@5335 | 2239 | </div> |
vhardy@5366 | 2240 | |
vhardy@5366 | 2241 | <h4>Step 1 - Phase 2: Layout flow to compute the RFCBs' flow fragments heights</h4> |
vhardy@5335 | 2242 | |
vhardy@5366 | 2243 | <p>In this second phase of Step 1, the named flow is laid out in <span>regions</span> |
vhardy@5366 | 2244 | and the height of each fragment falling in each RFCB is computed.</p> |
vhardy@5366 | 2245 | |
vhardy@5366 | 2246 | <p>The user agent lays out as much of the flow into an area |
vhardy@5366 | 2247 | with RFCB-A's used 'width'. rA's 'height' computes to 'auto' and there is no vertical maximum |
vhardy@5366 | 2248 | height for RFCA's 'height'. However, because there is a break after the |
vhardy@5366 | 2249 | first paragraph in the 'article' <code>named flow</code>, only this first paragraph is |
vhardy@5366 | 2250 | laid out in RFCB-A and FH-A (the flow fragment height for RFCB-A) is resolved by laying out |
vhardy@5366 | 2251 | this first paragraph in the used 'width'.</p> |
vhardy@5366 | 2252 | |
vhardy@5366 | 2253 | <p>At this point, the user agent lays out as much of the remaining flow as possible in RFCB-B. |
vhardy@5366 | 2254 | Because rB's 'max-height' computed value is '150px', the user agent only lays out |
vhardy@5366 | 2255 | the 'article' named flow using RFCB-B's used 'width' until the point where |
vhardy@5366 | 2256 | laying out additional content would cause RFCB-B to overflow rB's box. |
vhardy@5366 | 2257 | The fragment height for RFCB-B is resolved: FH-B (<code class="css">150px</code>).</p> |
vhardy@5366 | 2258 | |
vhardy@5366 | 2259 | <p>Finally, the user agent lays out the remainder of the flow in RFCB-C. |
vhardy@5366 | 2260 | Because rC has no other constraints and no region breaks, the remaining content is |
vhardy@5366 | 2261 | laid out in RFCB-C's used 'width'. This results in a resolved flow fragment height: FH-C.</p> |
vhardy@5366 | 2262 | |
vhardy@5335 | 2263 | <div class="figure"> |
vhardy@5366 | 2264 | <img src="images/flow-fragment-height-phase-2.png" width="370px" alt="Step 1 - Phase 2: Measure flow fragments heights"/> |
vhardy@5354 | 2265 | <p class="caption">Step 1 - Phase 2: Measure flow fragments heights</p> |
vhardy@5335 | 2266 | </div> |
vhardy@5335 | 2267 | |
vhardy@5366 | 2268 | <h4>Step 2: Layout document and regions without named flows</h4> |
vhardy@5366 | 2269 | |
vhardy@5366 | 2270 | <p>The used 'width' of RFCB-A, RFCB-B and RFCB-C are resolved as in the previous step. However, the |
vhardy@5366 | 2271 | 'height' is resolved differently.</p> |
vhardy@5366 | 2272 | |
vhardy@5366 | 2273 | <p>Resolving the 'height' of rA <a href="http://www.w3.org/TR/CSS2/visudet.html#normal-block">requires a content measure</a> |
vhardy@5366 | 2274 | which is FH-A (the flow fragment height for RFCB-A).</p> |
vhardy@5366 | 2275 | |
vhardy@5366 | 2276 | <p>The 'height' of rB results from first computing its |
vhardy@5366 | 2277 | <a href="http://www.w3.org/TR/CSS2/visudet.html#block-root-margin">content measure</a> and then applying the |
vhardy@5366 | 2278 | <a href="http://www.w3.org/TR/CSS2/visudet.html#min-max-heights">rules for 'max-height'</a>. Here, the |
vhardy@5366 | 2279 | vertical content measure evaluates to FH-B. After applying the |
vhardy@5366 | 2280 | rules for 'max-height' and accounting for margins, padding and borders, the used 'height' of rB |
vhardy@5366 | 2281 | is resolved to LH-B (<code class="css">150px</code>).</a>. |
vhardy@5366 | 2282 | |
vhardy@5366 | 2283 | <p>The 'height' of rC's box results from |
vhardy@5366 | 2284 | <a href="http://www.w3.org/TR/CSS2/visudet.html#block-root-margin">calculating |
vhardy@5366 | 2285 | its content measure</a>: FH-C becomes rC's used 'height'.</a> |
vhardy@5366 | 2286 | |
vhardy@5335 | 2287 | <div class="figure"> |
vhardy@5335 | 2288 | <img src="images/regions-visual-formatting-step-2.png" width="370px" alt="Step 2: Layout document and regions without named flows"/> |
vhardy@5352 | 2289 | <p class="caption">Step 2: Layout document and regions without <span>named flows</span></p> |
vhardy@5335 | 2290 | </div> |
vhardy@5335 | 2291 | |
vhardy@5366 | 2292 | <h4>Step 3: named flows layout</h4> |
vhardy@5366 | 2293 | |
vhardy@5366 | 2294 | <p>In this final step, the <code class="css">article</code> <span>named flow</span> is laid out in its |
vhardy@5366 | 2295 | <span>region chain</span>. The used 'width' for each of the RFCB is resolved as in step 1 above.</p> |
vhardy@5366 | 2296 | |
vhardy@5366 | 2297 | <p>The used 'height' for the RFCB is a result of laying out the as much of the content in the |
vhardy@5366 | 2298 | <span>region</span> without overflowing its content box and following the |
vhardy@5366 | 2299 | <a href="http://www.w3.org/TR/css3-break/">fragmentation rules</a>.</p> |
vhardy@5366 | 2300 | |
vhardy@5366 | 2301 | <p>Because the computed 'width' of the RFCB has not changed and the fragmentation rules applied are |
vhardy@5366 | 2302 | the same as in Phase 1, Step 2, the used 'height' for RFCB-A, RFCB-B and RFCB-C are |
vhardy@5366 | 2303 | LH-A, LH-B and LH-C, respectively.</p> |
vhardy@5366 | 2304 | |
vhardy@5366 | 2305 | <p>There may be situations where the used 'height' of RFCBs resolved in Step 3 are different from the |
vhardy@5366 | 2306 | <span>flow fragment height</span> computed in Step 1 Phase 2.</p> |
vhardy@5366 | 2307 | |
vhardy@5354 | 2308 | <div class="figure"> |
vhardy@5366 | 2309 | <img src="images/regions-visual-formatting-step-3.png" width="370px" alt="Step 3: Final result after laying out named flows in regions"/> |
vhardy@5354 | 2310 | <p class="caption">Step 3: Final result after laying out named flows in regions</p> |
vhardy@5354 | 2311 | </div> |
vhardy@5354 | 2312 | |
vhardy@5335 | 2313 | |
vhardy@5289 | 2314 | <h2 id="relation-to-document-events">Relation to document events</h2> |
vhardy@5289 | 2315 | |
vhardy@5289 | 2316 | <p>The CSS regions module does not alter the normal processing of |
vhardy@5289 | 2317 | events in the document tree. In particular, if an event occurs on an |
vhardy@5352 | 2318 | element that is part of a <span>named flow</span>, the <a href= |
vhardy@5289 | 2319 | "http://www.w3.org/TR/dom/#events">event's |
vhardy@5289 | 2320 | bubble and capture phases</a> happen following the document tree order.</p> |
vhardy@5289 | 2321 | |
vhardy@5289 | 2322 | |
vhardy@2945 | 2323 | <h2 id="relation-to-other-specifications">Relation to other |
vhardy@2945 | 2324 | specifications</h2> |
alexmog@2565 | 2325 | |
vhardy@2779 | 2326 | <p>This specification is related to other specifications as described in |
vhardy@2779 | 2327 | the <a href='#references'>references</a> section. In addition, it is |
vhardy@2779 | 2328 | related to the following specifications:</p> |
alexmog@2565 | 2329 | |
vhardy@2779 | 2330 | <ol> |
vhardy@5373 | 2331 | <li>CSS Fragmentation Module Level 3 [[CSS3-BREAK]]. This module defines the |
vhardy@5373 | 2332 | rules for fragmenting content over multiple containers and applies to |
vhardy@5373 | 2333 | CSS regions in addition to applying to multi-column and paged media.</li> |
vhardy@5373 | 2334 | |
vhardy@5390 | 2335 | <li>CSS Pagination Templates Module Level 3 [[CSS3-PAGE-TEMPLATE]]. This module |
vhardy@5373 | 2336 | defines a syntax to define layout templates which can be used |
vhardy@5373 | 2337 | when paginating content. The page templates use regions.</li> |
vhardy@5373 | 2338 | |
bert@3938 | 2339 | <li>CSS Exclusions Module [[CSS3-EXCLUSIONS]]. This module defines a |
vhardy@2779 | 2340 | generic way to define arbitrarily shaped exclusions into which content |
vhardy@2779 | 2341 | can flow or around which content can flow. This can be seen as an |
vhardy@2791 | 2342 | extension to the way CSS floats provide rectangular areas into which |
vhardy@2779 | 2343 | content flows and around which content flows. In advanced layout |
vhardy@2791 | 2344 | designs, it is expected that the CSS Exclusions module will be commonly |
vhardy@3301 | 2345 | combined with the CSS regions module.</li> |
alexmog@2565 | 2346 | |
bert@3938 | 2347 | <li>CSS Line Grid Module [[CSS3-LINE-GRID]]. This module defines a |
vhardy@2779 | 2348 | concept of line grid to align the position of lines in different |
vhardy@2779 | 2349 | elements. The line grid functionality is related and needed for |
vhardy@2779 | 2350 | aligning content flowing in separate regions.</li> |
vhardy@2779 | 2351 | </ol> |
vhardy@3940 | 2352 | |
vhardy@3940 | 2353 | <h2 id="usecases">Use Cases</h2> |
vhardy@3940 | 2354 | |
vhardy@3940 | 2355 | <p>Use cases are described on <a href="http://wiki.csswg.org/spec/css3-regions/regions-use-cases">this |
vhardy@3940 | 2356 | page</a>.</p> |
alexmog@2565 | 2357 | |
vhardy@2779 | 2358 | <h2 id="conformance">Conformance</h2> |
vhardy@3073 | 2359 | |
vhardy@3073 | 2360 | <h2 id="changes">Changes</h2> |
alexmog@2565 | 2361 | |
stearns@5470 | 2362 | <h3 id="changes_from_November_29_2011">Changes from <a href="http://www.w3.org/TR/2011/WD-css3-regions-20111129/">November 29<sup>th</sup> 2011</a> version</h3> |
vhardy@4119 | 2363 | |
vhardy@4119 | 2364 | <ul> |
vhardy@4119 | 2365 | <li>Modified region styling examples to use element selector instead of of pseudo-code selectors (this had been omitted in the |
vhardy@4119 | 2366 | previous pass at removing pseudo-code from the examples).</li> |
vhardy@4119 | 2367 | <li>Removed divs with class set to "issue moved", "issue stale" and "issue resolved" since these divs where not displayed. |
vhardy@4119 | 2368 | <li>Minor updates to the alternate stylesheet.</li> |
vhardy@4314 | 2369 | <li>Removed "This section is normative" paragraphs since in CSS specifications, sections are normative unless |
vhardy@4314 | 2370 | otherwise specified.</li> |
vhardy@4314 | 2371 | <li>Removed "This section is informative" paragraphs since in CSS specifications notes are always informative.</li> |
vhardy@4318 | 2372 | <li>Reworded the text about flow-into: <ident> and removed obsolete text about the interaction with the |
vhardy@4318 | 2373 | 'content' property.</li> |
vhardy@4331 | 2374 | <li>Removed "this section is non-normative" from the "Regions Concepts" section.</li> |
vhardy@4336 | 2375 | <li>In the section on region breaks, removed descriptions of break values normatively defined in external specifications. |
vhardy@4336 | 2376 | Removed the section about split boxes and replaced with paragraph referencing the page breaking behavior. |
vhardy@4336 | 2377 | Removed the discussion about how the 'overflow' property applies to content flown in regions from the |
vhardy@4336 | 2378 | break section, since this is covered in the section on 'region-overflow' already. See <a href="http://lists.w3.org/Archives/Public/www-style/2011Dec/0477.html">mailing list feedback.</a></li> |
vhardy@4338 | 2379 | <li>Clarified that @region style rules only apply to the 'portion' of an element that falls into |
vhardy@4338 | 2380 | the corresponding region and added an issue that the model for 'partial' styling needs to |
vhardy@4338 | 2381 | be defined. See <a href="http://lists.w3.org/Archives/Public/www-style/2011Dec/0480.html">mailing list feedback</a>.</li> |
vhardy@4395 | 2382 | <li>Clarified that the <code>NodeList</code> returned by <code>getRegionsByContentNode</code> is live.</li> |
vhardy@4400 | 2383 | <li>Added a name property to the <code>NamedFlow</code> interface. Added a <code>NamedFlowCollection</code> |
vhardy@4400 | 2384 | interface and added a <code>getNamedFlows</code> method on the <code>Document</code> interface, as |
vhardy@4400 | 2385 | per <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15828">Bug 15828</a>.</li> |
vhardy@4409 | 2386 | <li>Modified wording about containing block resolution for absolutely positioned elements in a |
vhardy@4409 | 2387 | named flow.</li> |
vhardy@4413 | 2388 | <li>Modified initial examples as per <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15131">Bug 15131</a></li> |
vhardy@4415 | 2389 | <li>Multiple editorial changes following |
vhardy@4415 | 2390 | <a href="http://lists.w3.org/Archives/Public/www-style/2012Feb/0001.html">mailing list review comments</a></li> |
vhardy@5094 | 2391 | <li>Fixed DOM references to now point to the DOM TR</li> |
vhardy@5095 | 2392 | <li>Fixed Web IDL issues as reported in <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15931">Issue 15931</a></li> |
vhardy@5131 | 2393 | <li>Added text to explain support for multi-column elements as required by <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15191">Issue 15191</a> and <a href="http://www.w3.org/Style/CSS/Tracker/actions/375">Action 375</a>.</li> |
vhardy@5232 | 2394 | <li>Renamed 'regionOverflow' to 'regionOverset' to avoid confusion between fitting a flow in |
vhardy@5232 | 2395 | regions and the concept of visual overflow that the word 'overflow' (and the property) carry.</li> |
vhardy@5232 | 2396 | <li>Reworked the partial document interface following the <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=14948">Issue 14948</a> on <code>getFlowByName</code>.</li> |
vhardy@5255 | 2397 | <li>Updated the object model section as proposed on the <a href="http://wiki.csswg.org/spec/css3-regions/css-om">wiki</a> and in particular: |
vhardy@5255 | 2398 | <ul> |
vhardy@5255 | 2399 | <li>introduced a <code>Region</code> interface to replace the supplemental Element interface</li> |
vhardy@5255 | 2400 | <li>Added a 'flowFrom' attribute on the Region interface</li> |
vhardy@5255 | 2401 | <li>NamedFlow.getRegions() was added</li> |
vhardy@5255 | 2402 | <li>Renamed getContentNode to getContent and getRegionsByContentNode to getRegionsByContent as |
vhardy@5255 | 2403 | per <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15879">Isseu 15879</a></li> |
vhardy@5255 | 2404 | <li>NamedFlow now returns static lists (see <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=16286">Issue 16286</a>)</li> |
vhardy@5255 | 2405 | |
vhardy@5255 | 2406 | </ul> |
vhardy@5255 | 2407 | </li> |
vhardy@5264 | 2408 | <li>Modified region layout event to be dispatched on <code>NamedFlow</code> instead of region |
vhardy@5264 | 2409 | as before. Was requested by <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15938">Issue 15938</a> |
vhardy@5264 | 2410 | and required in the general effort to have the DOM APIs work with non-element regions.</li> |
vhardy@5267 | 2411 | <li>Changed paragraph on pseudo-elements to disallow 'flow-into' on all pseudo-elements because |
vhardy@5267 | 2412 | moving a '::before' element (for a example) to a named flow does not seem useful and causes specification |
vhardy@5267 | 2413 | and implementation complexity.</li> |
vhardy@5270 | 2414 | <li>Added section about getClientRects(), getBoundingClientRect(), offsetWidth, offsetHeight, offsetTop and |
vhardy@5270 | 2415 | offsetLeft.</li> |
vhardy@5290 | 2416 | <li>Added 'Regions visual formatting details' section to better describe the model for |
vhardy@5290 | 2417 | resolving auto sizing on regions.</li> |
vhardy@5373 | 2418 | <li>Reworked the initial specification example.</li> |
stearns@5453 | 2419 | <li>Changed break and region-overflow properties to apply to visual media instead of paged.</li> |
stearns@5453 | 2420 | <li>Added opacity to region styling.</li> |
stearns@5470 | 2421 | <li>Added possibility of ::before content contributing to overflow.</li> |
stearns@5598 | 2422 | <li>Added CSSRegionStyleRule</li> |
vhardy@4119 | 2423 | </ul> |
vhardy@4119 | 2424 | |
vhardy@4119 | 2425 | |
vhardy@3073 | 2426 | <h3 id="changes_from_June_09_2011">Changes from <a href="http://www.w3.org/TR/2011/WD-css3-regions-20110609/">June 09<sup>th</sup> 2011</a> version</h3> |
vhardy@3073 | 2427 | |
vhardy@3073 | 2428 | <ul> |
vhardy@3301 | 2429 | <li>Editorial changes (typos, rephrasings).</li> |
vhardy@3547 | 2430 | <li>Made 'content-order' a <integer> and not a <float> following a working group |
vhardy@3073 | 2431 | <a href="http://lists.w3.org/Archives/Public/www-style/2011Jun/0329.html">resolution</a></li> |
vhardy@3073 | 2432 | <li>Added Alex Mogilevsky as an editor</li> |
vhardy@3558 | 2433 | <li>Flow names became <ident> instead of <string> following a working group |
vhardy@3073 | 2434 | <a href="http://lists.w3.org/Archives/Public/www-style/2011Jun/0413.html">resolution</a></li> |
vhardy@3073 | 2435 | <li>Removed issue about possibly altering the DOM Events model for region events following |
vhardy@3073 | 2436 | a working group |
vhardy@3073 | 2437 | <a href="http://lists.w3.org/Archives/Public/www-style/2011Jun/0413.html">resolution</a></li> |
vhardy@3073 | 2438 | <li>Made the "relation to document events" section informative following a working group |
vhardy@3073 | 2439 | <a href="http://lists.w3.org/Archives/Public/www-style/2011Jun/0413.html">resolution</a></li> |
vhardy@3073 | 2440 | <li>Removed issue in section "The NamedFlow interface" following the working group's |
vhardy@3073 | 2441 | <a href="http://lists.w3.org/Archives/Public/www-style/2011Jun/0413.html">resolution</a> to |
vhardy@3073 | 2442 | have both NamedFlow and the Element interface extension</li> |
vhardy@3073 | 2443 | <li>Following a working group <a href="http://lists.w3.org/Archives/Public/www-style/2011Jun/0413.html">resolution</a>: |
vhardy@3073 | 2444 | <ul> |
vhardy@3073 | 2445 | <li>Turned the first issue in the "Extensions to the Element interface" into a note |
vhardy@3073 | 2446 | explaining that the NamedFlow interface can be used when regions are pseudo-elements.</li> |
vhardy@3138 | 2447 | <li>Added NamedFlowUpdate</li> |
vhardy@3073 | 2448 | </ul> |
vhardy@3073 | 2449 | </li> |
vhardy@3073 | 2450 | <li>Excluded 'none', 'inherit' and 'initial' from the possible identifier names on |
vhardy@3073 | 2451 | the flow property following <a href="http://lists.w3.org/Archives/Public/www-style/2011Jun/0583.html">discussion</a> on the mailing list.</li> |
vhardy@3073 | 2452 | <li>Simplified integration discussion on multi-column layout and just state that since |
vhardy@3073 | 2453 | column boxes are not addressable by selectors, they cannot be regions.</li> |
vhardy@3262 | 2454 | <li>Added specification of how the 'flow-into' property interacts with object, embed and iframe |
vhardy@3073 | 2455 | elements.</li> |
vhardy@3138 | 2456 | <li>Excluded 'default' from the possible identifier names on the flow property because it |
vhardy@3138 | 2457 | <a href="http://www.w3.org/TR/2006/WD-css3-values-20060919/#keywords">may get reserved</a>.</li> |
vhardy@3138 | 2458 | <li>Added to the definition of 'auto' on 'region-overflow' specifying that region breaks must |
vhardy@3138 | 2459 | be ignored.</li> |
vhardy@3138 | 2460 | <li>Renamed 'Document.flowWithName' to 'Document.getFlowByName' since it is not a property.</li> |
vhardy@3138 | 2461 | <li>Added a note that a 'NamedFlow' instance is live.</li> |
vhardy@3138 | 2462 | <li>Added an 'undefined' string value to the regionOverflow property on the Element interface |
vhardy@3138 | 2463 | extension.</li> |
vhardy@3272 | 2464 | <li>Renamed NamedFlowEvent to regionLayoutUpdate to avoid having 'Event' in the event name.</li> |
alexmog@3156 | 2465 | <li>Added description for special behavior of iframe/object/embed as |
alexmog@3156 | 2466 | flow source</li> |
vhardy@3262 | 2467 | <li>Removed issue on copying content to a named flow instead of moving elements to named |
vhardy@3262 | 2468 | flow following working group <a href="http://lists.w3.org/Archives/Public/www-style/2011Aug/0069.html">resolution</a>.</li> |
vhardy@3262 | 2469 | <li>Removed issue on content:flow-from v.s., flow-from property following working group <a href="http://lists.w3.org/Archives/Public/www-style/2011Aug/0069.html">resolution</a>.</li> |
vhardy@3262 | 2470 | <li>Renamed 'flow' to 'flow-into' following working group <a href="http://lists.w3.org/Archives/Public/www-style/2011Aug/0069.html">resolution</a>.</li> |
vhardy@3262 | 2471 | <li>Updated the css3-grid-align example following working group <a href="http://lists.w3.org/Archives/Public/www-style/2011Aug/0069.html">resolution</a> that |
vhardy@3262 | 2472 | it should use <div> instead of grid-cell pseudo elements that were removed |
vhardy@3262 | 2473 | from the CSS Grid Layout specification.</li> |
vhardy@3262 | 2474 | <li>Renamed 'from-flow' to 'flow-from' following a working group <a href="http://lists.w3.org/Archives/Public/www-style/2011Aug/0069.html">resolution</a>.</li> |
vhardy@3262 | 2475 | <li>Limited the applicability of 'content: flow-from()' to block container box and added |
vhardy@3262 | 2476 | a note that this might be expanded in the future, following a working group <a href="http://lists.w3.org/Archives/Public/www-style/2011Aug/0069.html">resolution</a>.</li> |
vhardy@3262 | 2477 | <li>Removed issue about API to find which region displays an element in a named flow |
vhardy@3262 | 2478 | since <a href="http://www.w3.org/Style/CSS/Tracker/actions/350">ACTION-350</a> was |
vhardy@3262 | 2479 | created to add this API.</li> |
vhardy@3267 | 2480 | <li>In the 'flow' property description, removed the required wrapper anonymous |
vhardy@3267 | 2481 | block as agreed on <a href="http://lists.w3.org/Archives/Public/www-style/2011Aug/0161.html">mailing list discussion</a>.</li> |
vhardy@3267 | 2482 | <li>Reworded the paragraph on how regions create a new stacking context, as |
vhardy@3302 | 2483 | per the <a href="http://lists.w3.org/Archives/Public/www-style/2011Aug/0025.html">mailing list discussion</a>.</li> |
vhardy@3301 | 2484 | <li>Reworked the "CSS regions Model" section to now be "CSS regions Layout". Moved the |
vhardy@3267 | 2485 | definition of a region as the first sub-section.</li> |
vhardy@3267 | 2486 | <li>Removed the "Visual Formatting Model and Flows" section to match the new Regions Model |
vhardy@3301 | 2487 | (now CSS regions Layout) section.</li> |
vhardy@3267 | 2488 | <li>Moved the sections on allowed region breaks, forced region breaks and "best" regions |
vhardy@3267 | 2489 | breaks to follow the property definitions to follow the formatting of the paged |
vhardy@3267 | 2490 | media section in CSS 2.1.</li> |
vhardy@3267 | 2491 | <li>Added note about why regions create a new stacking context following the discussion |
vhardy@3267 | 2492 | on the <a href="http://lists.w3.org/Archives/Public/www-style/2011Jul/0158.html">mailing list</a>.</li> |
vhardy@3267 | 2493 | <li>Removed sentence about content:none making elements disconnected following the |
vhardy@3267 | 2494 | discussion on the <a href="http://lists.w3.org/Archives/Public/www-style/2011Jul/0158.html">mailing list</a>.</li> |
vhardy@3267 | 2495 | <li>Removed sentence about content:none making elements disconnected following the |
vhardy@3267 | 2496 | discussion on the <a href="http://lists.w3.org/Archives/Public/www-style/2011Jul/0158.html">mailing list</a>.</li> |
vhardy@3272 | 2497 | <li>Added the ::region-before and a ::region-after pseudo-elements.</li> |
vhardy@3272 | 2498 | <li>Added note of caution when using selectors and the 'flow-into' property following |
vhardy@3272 | 2499 | a <a href="http://lists.w3.org/Archives/Public/www-style/2011Jul/0191.html">mailing list discussion</a>.</li> |
vhardy@3301 | 2500 | <li>Removed sections about allowed, forced and best region breaks to align with the |
vhardy@3301 | 2501 | multi-column specification approach and until the group agrees on where and how the |
vhardy@3301 | 2502 | general issue of breaks (regions/pages/columns) should be addressed.</li> |
vhardy@3301 | 2503 | <li>Removed the section on Integration with other specifications since specifications that |
vhardy@3301 | 2504 | was superfluous especially since there is no specific integration with multi column, |
vhardy@3301 | 2505 | grid or template layout.</li> |
vhardy@3377 | 2506 | <li>Added a note that regions establish a new block formatting context.</li> |
vhardy@3377 | 2507 | <li>Renamed content-order to region-order.</li> |
vhardy@3377 | 2508 | <li>Added a note about overflowing content in regions (e.g., for content with borders).</li> |
vhardy@3377 | 2509 | <li>Added a note that a region cannot layout content it is part of (to avoid creating a |
vhardy@3377 | 2510 | circular dependency) in the flow-from description, specifying that if flow-from |
vhardy@3377 | 2511 | references the flow an element is part of, then the element does not format |
vhardy@3377 | 2512 | anything visually.</li> |
vhardy@3547 | 2513 | <li>Replaced 'content:flow-from(<ident>)' with 'flow-from: <ident>' following a |
vhardy@3547 | 2514 | <a href="http://krijnhoetmer.nl/irc-logs/css/20110824">working group resolution</a>.</li> |
vhardy@3547 | 2515 | <li>Added more specific wording about auto width and auto height, following |
vhardy@3547 | 2516 | <a href="http://www.w3.org/Style/CSS/Tracker/actions/351">ACTION 351</a>.</li> |
vhardy@3547 | 2517 | <li>Reworked section on region markers to now use '::before' and '::after' and explain |
vhardy@3547 | 2518 | how 'display:run-in' works with regions.</li> |
vhardy@3547 | 2519 | <li>Modified the @region style rule to remove the ::region-lines pseudo-selector.</li> |
vhardy@3547 | 2520 | <li>Removed the 'region-order' property following implementation feedback.</li> |
vhardy@3660 | 2521 | <li>Specified that region-overflow does not influence a region's size.</li> |
vhardy@3660 | 2522 | <li>Specified that the flow's writing mode is defined by the first region's writing mode |
vhardy@3660 | 2523 | following <a href="http://lists.w3.org/Archives/Public/www-style/2011Aug/0306.html">mailing list discussion</a>.</li> |
vhardy@3660 | 2524 | <li>Made iframe, object and embed support of flow-into optional following |
vhardy@3660 | 2525 | <a href="http://lists.w3.org/Archives/Public/www-style/2011Sep/0073.html">mailing list discussion</a>.</li> |
vhardy@3660 | 2526 | <li>Clarified that flow content following the last break in the last region is not rendered, |
vhardy@3660 | 2527 | following <a href="http://lists.w3.org/Archives/Public/www-style/2011Oct/0167.html">mailing list |
bert@3938 | 2528 | discussions.</a></li> |
vhardy@3660 | 2529 | <li>Modified the rule for computing the width and height of a region when they are set to auto, |
vhardy@3660 | 2530 | following <a href="http://lists.w3.org/Archives/Public/www-style/2011Oct/0216.html">a mailing list |
vhardy@3660 | 2531 | discussion.</a></li> |
vhardy@3660 | 2532 | <li>Added 'auto' to the list of invalid flow identifiers.</li> |
vhardy@3660 | 2533 | <li>Made 'none' the initial value for 'flow-into' and aligned with 'flow-from', as |
vhardy@3660 | 2534 | explained in this <a href="http://lists.w3.org/Archives/Public/www-style/2011Oct/0576.html">email</a>. |
vhardy@3660 | 2535 | Also allowed the 'inherit' value on 'flow-from' and 'flow-into' (same email).</li> |
vhardy@3660 | 2536 | <li>Added note about nested region styling following <a href="http://lists.w3.org/Archives/Public/www-style/2011Oct/0650.html">a mailing list discussion</a>.</li> |
vhardy@3681 | 2537 | <li>Added additional DOM interface following <a href="http://www.w3.org/Style/CSS/Tracker/actions/350">Action 350</a>.</li> |
vhardy@3940 | 2538 | <li>Clarified that a region becomes a region only if its 'content' property computes to |
vhardy@3940 | 2539 | normal, following the resolution of <a href="http://wiki.csswg.org/spec/css3-regions#issue-22content-vs-flow-from-precedence">Issue 22</a>.</li> |
vhardy@3940 | 2540 | <li>Removed text about special iframe behavior as a result of |
vhardy@3940 | 2541 | <a href="http://www.w3.org/Style/CSS/Tracker/actions/376">ACTION 376</a>.</li> |
vhardy@3940 | 2542 | <li>Made the selectors explicit in the initial section code examples, following |
vhardy@3940 | 2543 | discussion in <a href="http://krijnhoetmer.nl/irc-logs/css/20111030">San Jose, October 2011</a> face to face meeting.</li> |
vhardy@3940 | 2544 | <li>Added section on use cases following <a href="http://www.w3.org/Style/CSS/Tracker/actions/377">ACTION-377</a>.</li> |
vhardy@3073 | 2545 | </ul> |
vhardy@3073 | 2546 | |
vhardy@2779 | 2547 | <h2 class="no-num" id="acknowledgments">Acknowledgments</h2> |
alexmog@2565 | 2548 | |
vhardy@3547 | 2549 | <p>The editors are grateful to the CSS working group for their feedback and help with |
vhardy@3547 | 2550 | the genesis of this specification.</p> |
vhardy@3547 | 2551 | |
vhardy@3547 | 2552 | <p>In addition, the editors would like to thank the following individuals for their contributions, |
vhardy@3547 | 2553 | either during the conception of CSS regions or during its development and specification review |
vhardy@3547 | 2554 | process:</p> |
vhardy@3547 | 2555 | <ul> |
vhardy@4437 | 2556 | <li>Rossen Atanassov</li> |
stearns@5445 | 2557 | <li>Tab Atkins</li> |
vhardy@4437 | 2558 | <li>Andrei Bucur</li> |
vhardy@4437 | 2559 | <li>Alexandru Chiculita</li> |
vhardy@4437 | 2560 | <li>Phil Cupp</li> |
vhardy@4437 | 2561 | <li>Arron Eicholz</li> |
vhardy@4437 | 2562 | <li>John Jansen</li> |
stearns@5445 | 2563 | <li>Daniel Glazman</li> |
vhardy@4437 | 2564 | <li>Arno Gourdol</li> |
vhardy@4437 | 2565 | <li>David Hyatt</li> |
vhardy@4437 | 2566 | <li>Brian Heuston</li> |
vhardy@4437 | 2567 | <li>Ian Hickson</li> |
vhardy@4437 | 2568 | <li>Jonathan Hoersch</li> |
vhardy@4437 | 2569 | <li>Michael Jolson</li> |
vhardy@4437 | 2570 | <li>Brad Kemper</li> |
vhardy@4437 | 2571 | <li>Håkon Wium Lie</li> |
vhardy@4437 | 2572 | <li>Markus Mielke</li> |
vhardy@4437 | 2573 | <li>Robert O'Callahan</li> |
vhardy@4437 | 2574 | <li>Edward O'Connor</li> |
vhardy@4437 | 2575 | <li>Mihnea Ovidenie</li> |
vhardy@4437 | 2576 | <li>Virgil Palanciuc</li> |
vhardy@4437 | 2577 | <li>Olga Popiv</li> |
vhardy@3547 | 2578 | <li>Christoph Päper</li> |
vhardy@4437 | 2579 | <li>Anton Prowse</li> |
vhardy@4437 | 2580 | <li>Peter Sorotokin</li> |
vhardy@4437 | 2581 | <li>Alan Stearns</li> |
vhardy@4437 | 2582 | <li>Christian Stockwell</li> |
vhardy@4437 | 2583 | <li>Eugene Veselov</li> |
stearns@5445 | 2584 | <li>Boris Zbarsky</li> |
vhardy@4437 | 2585 | <li>Stephen Zilles</li> |
vhardy@3547 | 2586 | </ul> |
stearns@5445 | 2587 | |
stearns@5445 | 2588 | <h2 id="intro-example-code" class="no-num">Appendix A. Example Code for Introduction</h2> |
stearns@5445 | 2589 | <p>The following is one possible way |
stearns@5445 | 2590 | to code the example from |
stearns@5445 | 2591 | the <a href="#introduction">introduction</a>. |
stearns@5445 | 2592 | This code uses grid cells |
stearns@5445 | 2593 | to define, size and position the region areas |
stearns@5445 | 2594 | but table layout, absolute positioning, |
stearns@5445 | 2595 | or any other CSS layout facility could be used.</p> |
stearns@5445 | 2596 | |
vhardy@5489 | 2597 | <div class="example"><pre> |
stearns@5445 | 2598 | <style> |
stearns@5445 | 2599 | #grid { |
stearns@5445 | 2600 | width: 80vw; |
stearns@5445 | 2601 | height: 60vw; |
stearns@5445 | 2602 | grid-template: "aaa.d" |
stearns@5445 | 2603 | "....d" |
stearns@5445 | 2604 | "bbb.d" |
stearns@5445 | 2605 | "....d" |
stearns@5445 | 2606 | "ccc.d"; |
stearns@5445 | 2607 | grid-rows: 52% 4% 20% 4% 20%; |
stearns@5445 | 2608 | grid-columns: 30% 5% 30% 5% 30%; |
stearns@5445 | 2609 | } |
stearns@5445 | 2610 | #region1 { grid-cell: a; } |
stearns@5445 | 2611 | #region2 { grid-cell: b; } |
stearns@5445 | 2612 | #boxA { grid-cell: c; } |
stearns@5445 | 2613 | #region3 { grid-cell: d; } |
stearns@5445 | 2614 | |
stearns@5445 | 2615 | #region4 { |
stearns@5445 | 2616 | width: 80vw; |
stearns@5445 | 2617 | } |
stearns@5445 | 2618 | |
stearns@5445 | 2619 | #region2 { |
stearns@5445 | 2620 | column-count: 2; |
stearns@5445 | 2621 | } |
vhardy@5489 | 2622 | |
vhardy@5489 | 2623 | <span class="highlight">/* |
vhardy@5489 | 2624 | * Creates the named flow |
vhardy@5489 | 2625 | */</span> |
vhardy@5490 | 2626 | article { |
vhardy@5489 | 2627 | <strong>flow-into: article_flow;</strong> |
vhardy@5489 | 2628 | } |
vhardy@5489 | 2629 | |
vhardy@5489 | 2630 | <span class="highlight">/* |
vhardy@5489 | 2631 | * Associate it with the intended CSS Regions. |
vhardy@5489 | 2632 | * This creates a region chain for the named flow. |
vhardy@5489 | 2633 | */</span> |
vhardy@5489 | 2634 | #region1, #region2, #region3, #region4 { |
vhardy@5489 | 2635 | <strong>flow-from: article_flow;</strong> |
vhardy@5489 | 2636 | } |
vhardy@5489 | 2637 | |
stearns@5445 | 2638 | </style> |
stearns@5445 | 2639 | |
vhardy@5489 | 2640 | <span class="highlight"><!-- |
vhardy@5489 | 2641 | The following code element is the content to flow |
vhardy@5489 | 2642 | through the region chain. |
vhardy@5489 | 2643 | --></span> |
vhardy@5489 | 2644 | |
vhardy@5490 | 2645 | <article</em>> |
vhardy@5489 | 2646 | <h1>Introduction</h1> |
vhardy@5489 | 2647 | <p>This is an example ...</p> |
vhardy@5489 | 2648 | |
vhardy@5489 | 2649 | <h2>More Details</h2> |
vhardy@5489 | 2650 | <p>This illustrates ...</p> |
vhardy@5489 | 2651 | <p>Then, the example ...</p> |
vhardy@5489 | 2652 | <p>Finally, this ...</p> |
vhardy@5490 | 2653 | </article> |
vhardy@5489 | 2654 | |
vhardy@5489 | 2655 | <span class="highlight"><!-- |
vhardy@5489 | 2656 | For this example, we layout the regions with a grid. |
vhardy@5489 | 2657 | Regions could be pseudo-elements and could be laid out |
vhardy@5489 | 2658 | with another layout module (e.g., flexible boxes) |
vhardy@5489 | 2659 | --></span> |
stearns@5445 | 2660 | <div id="grid"> |
stearns@5445 | 2661 | <div id="region1"></div> |
stearns@5445 | 2662 | <div id="region2"></div> |
stearns@5445 | 2663 | <div id="boxA"></div> |
stearns@5445 | 2664 | <div id="region3"></div> |
stearns@5445 | 2665 | </div> |
stearns@5445 | 2666 | <div id="region4"></div> |
vhardy@5489 | 2667 | </pre></div> |
stearns@5445 | 2668 | |
stearns@5445 | 2669 | |
stearns@5445 | 2670 | |
stearns@5445 | 2671 | <div class="note"><span class="note-prefix">Note </span> |
stearns@5445 | 2672 | <p> |
stearns@5445 | 2673 | Note that a multi-column element is used for #region2, |
stearns@5445 | 2674 | which is a bit gratuitous here |
stearns@5445 | 2675 | (because grid cells could be used). |
stearns@5445 | 2676 | The reason to use a multi-column element |
stearns@5445 | 2677 | is to illustrate that |
stearns@5445 | 2678 | regions can be multi-column.</p> |
stearns@5445 | 2679 | </div> |
stearns@5445 | 2680 | |
stearns@5445 | 2681 | |
vhardy@2779 | 2682 | <h2 class="no-num" id="references">References</h2> |
alexmog@2565 | 2683 | |
stearns@5576 | 2684 | <div class="issue-marker" data-bug_id="16404" data-bug_status="ASSIGNED"> |
stearns@5576 | 2685 | <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=16404">Bug-16404</a> |
stearns@5576 | 2686 | <div class="issue-details"> |
stearns@5576 | 2687 | <p class="short-desc">Fix specification dependencies</p> |
stearns@5576 | 2688 | </div> |
stearns@5576 | 2689 | </div> |
stearns@5576 | 2690 | |
vhardy@2779 | 2691 | <h3 class="no-num" id="normative-references">Normative references</h3> |
vhardy@2779 | 2692 | <!--begin-normative--><!--end-normative--> |
alexmog@2565 | 2693 | |
vhardy@2779 | 2694 | <h3 class="no-num" id="other-references">Other references</h3> |
vhardy@2779 | 2695 | <!--begin-informative--><!--end-informative--> |
alexmog@2565 | 2696 | |
vhardy@2779 | 2697 | <h2 class="no-num" id="index">Index</h2><!--index--> |
alexmog@2565 | 2698 | |
vhardy@2779 | 2699 | <h2 class="no-num" id="property-index">Property index</h2> |
vhardy@4412 | 2700 | |
vhardy@4412 | 2701 | <!-- template markup for issues pulled from Bugzilla --> |
vhardy@4412 | 2702 | <script type="text/template" id="issue-template"> |
vhardy@4536 | 2703 | <div class="issue-marker" style="display:none" data-bug_id="{{bug_id}}" data-bug_status="{{bug_status}}"> |
vhardy@4412 | 2704 | <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id={{bug_id}}">Bug-{{bug_id}}</a> |
vhardy@4412 | 2705 | <div class="issue-details"> |
vhardy@4412 | 2706 | <p class="short-desc">{{short_desc}}</p> |
vhardy@4412 | 2707 | </div> |
vhardy@4412 | 2708 | </div> |
vhardy@4412 | 2709 | </script> |
vhardy@4415 | 2710 | |
vhardy@5539 | 2711 | <script type="text/javascript" src="../shared/scripts/BugzillaTrackerUtil.js"></script> |
vhardy@5539 | 2712 | <script type="text/javascript" src="../shared/scripts/BugzillaTracker.js"></script> |
vhardy@5539 | 2713 | <script type="text/javascript"> |
vhardy@5539 | 2714 | checkSpecificationIssues('CSS', 'Regions'); |
vhardy@5539 | 2715 | </script> |
vhardy@4437 | 2716 | |
vhardy@4412 | 2717 | |
vhardy@4412 | 2718 | <div id="issue-manager"> |
vhardy@4412 | 2719 | <h2>Issue manager</h2> |
vhardy@4412 | 2720 | <form action="#"> |
vhardy@4412 | 2721 | <label> |
vhardy@4412 | 2722 | <input type="radio" name="issue-filter" value="all" checked/> |
vhardy@4412 | 2723 | All issues |
vhardy@4412 | 2724 | </label> |
vhardy@4412 | 2725 | <label> |
vhardy@4412 | 2726 | <input type="radio" name="issue-filter" value="updated" /> |
vhardy@4412 | 2727 | Updated issues |
vhardy@4412 | 2728 | </label> |
vhardy@4412 | 2729 | <label> |
vhardy@4412 | 2730 | <input type="radio" name="issue-filter" value="new" /> |
vhardy@4412 | 2731 | New issues |
vhardy@4412 | 2732 | </label> |
vhardy@4412 | 2733 | </form> |
vhardy@4412 | 2734 | |
vhardy@4412 | 2735 | <!-- all the bugs are dumped the #issue-list after being retreived and matched to the ones in the page --> |
vhardy@4412 | 2736 | <div id="issue-list"> |
vhardy@4412 | 2737 | |
vhardy@4412 | 2738 | </div> |
vhardy@4412 | 2739 | </div> |
vhardy@4412 | 2740 | |
vhardy@3547 | 2741 | </body> |
vhardy@3547 | 2742 | </html> |
vhardy@3547 | 2743 | <!-- Keep this comment at the end of the file |
alexmog@2565 | 2744 | Local variables: |
alexmog@2565 | 2745 | mode: sgml |
alexmog@2565 | 2746 | sgml-declaration:"~/SGML/HTML4.decl" |
alexmog@2565 | 2747 | sgml-default-doctype-name:"html" |
alexmog@2565 | 2748 | sgml-minimize-attributes:t |
alexmog@2565 | 2749 | sgml-nofill-elements:("pre" "style" "br") |
alexmog@2565 | 2750 | sgml-live-element-indicator:t |
alexmog@2565 | 2751 | sgml-omittag:nil |
alexmog@2565 | 2752 | sgml-shorttag:nil |
alexmog@2565 | 2753 | sgml-namecase-general:t |
alexmog@2565 | 2754 | sgml-general-insert-case:lower |
alexmog@2565 | 2755 | sgml-always-quote-attributes:t |
alexmog@2565 | 2756 | sgml-indent-step:nil |
alexmog@2565 | 2757 | sgml-indent-data:t |
alexmog@2565 | 2758 | sgml-parent-document:nil |
alexmog@2565 | 2759 | sgml-exposed-tags:nil |
alexmog@2565 | 2760 | sgml-local-catalogs:nil |
alexmog@2565 | 2761 | sgml-local-ecat-files:nil |
alexmog@2565 | 2762 | End: |
vhardy@2779 | 2763 | --> |
vhardy@3547 | 2764 |