Tue, 27 Mar 2012 12:14:16 -0700
Implemented 'access to flow content' section of OM changes proposed at http://wiki.csswg.org/spec/css3-regions/css-om
css3-regions/Overview.html | file | annotate | diff | comparison | revisions | |
css3-regions/Overview.src.html | file | annotate | diff | comparison | revisions |
1.1 --- a/css3-regions/Overview.html Tue Mar 27 12:13:58 2012 -0700 1.2 +++ b/css3-regions/Overview.html Tue Mar 27 12:14:16 2012 -0700 1.3 @@ -224,13 +224,13 @@ 1.4 1.5 <h1 id=css-regions-module>CSS Regions Module Level 3</h1> 1.6 1.7 - <h2 class="no-num no-toc" id=longstatus-date>Editor's Draft 19 March 2012</h2> 1.8 + <h2 class="no-num no-toc" id=longstatus-date>Editor's Draft 27 March 2012</h2> 1.9 1.10 <dl> 1.11 <dt>This version: 1.12 1.13 <dd><a 1.14 - href="http://www.w3.org/TR/2012/ED-css3-regions-20120319/">http://www.w3.org/csswg/css3-regions</a> 1.15 + href="http://www.w3.org/TR/2012/ED-css3-regions-20120327/">http://www.w3.org/csswg/css3-regions</a> 1.16 1.17 <dt>Latest version: 1.18 1.19 @@ -420,8 +420,8 @@ 1.20 <li><a href="#the-namedflow-interface"><span class=secno>7.1. </span>The 1.21 NamedFlow interface</a> 1.22 1.23 - <li><a href="#extension-to-the-element-interface"><span class=secno>7.2. 1.24 - </span>Extension to the Element interface</a> 1.25 + <li><a href="#the-region-interface"><span class=secno>7.2. </span>The 1.26 + Region interface</a> 1.27 1.28 <li><a href="#region-flow-layout-events"><span class=secno>7.3. 1.29 </span>Region flow layout events</a> 1.30 @@ -1425,7 +1425,9 @@ 1.31 href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15832">Bug-15832</a> 1.32 <div class=issue-details> 1.33 <p class=short-desc>Should we have region-overflow:nobreak and have 1.34 - region-overflow apply to all regions, not just the last?</p> 1.35 + ‘<a href="#region-overflow"><code 1.36 + class=property>region-overflow</code></a>’ apply to all regions, 1.37 + not just the last?</p> 1.38 </div> 1.39 </div> 1.40 1.41 @@ -1530,14 +1532,12 @@ 1.42 </div> 1.43 1.44 <div class=note><span class=note-prefix>Note </span> 1.45 - <p>The ‘<a href="#dom-namedflow-overflow"><code 1.46 - class=property>overflow</code></a>’ property is honored on a 1.47 - region: if region content overflows, such as the borders of elements on 1.48 - the last line, the ‘<a href="#dom-namedflow-overflow"><code 1.49 - class=property>overflow</code></a>’ property controls the 1.50 - visibility of the overflowing content. See the ‘<a 1.51 - href="#dom-namedflow-overflow"><code 1.52 - class=property>overflow</code></a>’ property definition (<a 1.53 + <p>The ‘<code class=property>overflow</code>’ property is 1.54 + honored on a region: if region content overflows, such as the borders of 1.55 + elements on the last line, the ‘<code 1.56 + class=property>overflow</code>’ property controls the visibility of 1.57 + the overflowing content. See the ‘<code 1.58 + class=property>overflow</code>’ property definition (<a 1.59 href="#CSS21" rel=biblioentry>[CSS21]<!--{{CSS21}}--></a>).</p> 1.60 </div> 1.61 1.62 @@ -1936,6 +1936,24 @@ 1.63 <h3 id=the-namedflow-interface><span class=secno>7.1. </span>The NamedFlow 1.64 interface</h3> 1.65 1.66 + <p>A <a href="#named-flow0">named flow</a> is created when it becomes 1.67 + referenced by the ‘<a href="#flow-into"><code 1.68 + class=property>flow-into</code></a>’ and/or ‘<a 1.69 + href="#flow-from"><code class=property>flow-from</code></a>’ 1.70 + computed values. The following APIs also allow scripts to reference a <a 1.71 + href="#dom-namedflow"><code class=idl>NamedFlow</code></a> object 1.72 + representation of a <a href="#named-flow0">named flow</a>. 1.73 + 1.74 + <p>The possible states for a <a href="#named-flow0">named flow</a> are 1.75 + described in the following figure. These states are referenced in 1.76 + subsequent text. 1.77 + 1.78 + <div class=figure> <img alt="NamedFlow states" 1.79 + src="images/named-flow-states.svg" width=600px> 1.80 + <p class=caption><a href="#named-flow0">named flow</a> states and 1.81 + transitions</p> 1.82 + </div> 1.83 + 1.84 <div class=issue-marker data-bug_id=14948 data-bug_status=NEW> <a 1.85 href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=14948">Bug-14948</a> 1.86 <div class=issue-details> 1.87 @@ -1952,21 +1970,54 @@ 1.88 partial interface <a 1.89 href="http://www.w3.org/TR/dom/#interface-document">Document</a> { 1.90 <a 1.91 - href="#dom-namedflow">NamedFlow</a> getFlowByName(DOMString name); 1.92 - <a 1.93 - href="#dom-namedflow-collection">NamedFlowCollection</a> getNamedFlows(); 1.94 + href="#dom-namedflow">NamedFlow?</a> getFlowByName(DOMString name); 1.95 + readonly attribute <a 1.96 + href="#dom-namedflow-collection">NamedFlowCollection</a> namedFlows; 1.97 }; 1.98 </pre> 1.99 1.100 - <p>The <code class=idl>getNamedFlows</code> method on the <a 1.101 + <p>The <a href="#dom-namedflow"><code class=idl>namedFlows</code></a> 1.102 + attribute on the <a 1.103 href="http://www.w3.org/TR/dom/#interface-document"><code 1.104 - class=idl>Document</code></a> interface returns the list of all the <a 1.105 - href="#named-flow0">named flow</a>s in the document. 1.106 + class=idl>Document</code></a> interface returns the live list of all the 1.107 + current <a href="#named-flow0">named flow</a>s in the document. 1.108 + 1.109 + <p>The <a href="#dom-namedflow"><code class=idl>namedFlows</code></a> 1.110 + collection must include all <a href="#named-flow0">named flow</a> that are 1.111 + currently in the <code>CREATED</code> and <code>CREATED-REFERENCED</code> 1.112 + states. The list may include <a href="#named-flow0">named flows</a> that 1.113 + are in the <code>REFERENCED</code> state. The list may also include 1.114 + <span>named flow instances that are in the STALE state.</span> 1.115 1.116 <p>The <code class=idl>getFlowByName</code> method on the <a 1.117 href="http://www.w3.org/TR/dom/#interface-document"><code 1.118 class=idl>Document</code></a> interface provides access to the document's 1.119 - <a href="#named-flow0">named flow</a> instances. 1.120 + <a href="#named-flow0">named flow</a> instances. The return value depends 1.121 + on the <a href="#named-flow0">named flow</a> state: 1.122 + 1.123 + <ul> 1.124 + <li><code class=idl>NULL</code>: the user agent must return 1.125 + <code>null</code>. 1.126 + 1.127 + <li><code class=idl>STALE</code>: the user agent may return null or a 1.128 + valid <a href="#dom-namedflow"><code class=idl>NamedFlow</code></a> 1.129 + instance. If the user agent returns a valid instance, subsequent calls to 1.130 + the <code class=idl>getFlowByName</code> method for the same name 1.131 + argument must return the same object instance, no matter what the state 1.132 + of the <a href="#named-flow0">named flow</a> is. 1.133 + 1.134 + <li><code class=idl>CREATED</code> or <code 1.135 + class=idl>CREATED-REFERENCED</code>: the user agent must return a valid 1.136 + <a href="#dom-namedflow"><code class=idl>NamedFlow</code></a> instance. 1.137 + 1.138 + <li><code class=idl>REFERENCED</code>: the user agent may return 1.139 + <code>null</code> or it may return a valid <a href="#dom-namedflow"><code 1.140 + class=idl>NamedFlow</code></a> instance. If the user agent returns a 1.141 + valid object, subsequent calls to the <code 1.142 + class=idl>getFlowByName</code> method with the same name argument must 1.143 + return the same object instance, no matter what the state of the <a 1.144 + href="#named-flow0">named flow</a> is. 1.145 + </ul> 1.146 1.147 <div class=issue-marker data-bug_id=15828 data-bug_status=NEW> <a 1.148 href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15828">Bug-15828</a> 1.149 @@ -2007,7 +2058,11 @@ 1.150 1.151 <p>The <dfn id=dom-namedflow><code class=idl>NamedFlow</code></dfn> 1.152 interface offers a representation of the <a href="#named-flow0">named 1.153 - flow</a>. 1.154 + flow</a>. A <a href="#dom-namedflow"><code class=idl>NamedFlow</code></a> 1.155 + object is live meaning that it always represents the <a 1.156 + href="#named-flow0">named flow</a> with the corresponding name, even if 1.157 + that <a href="#named-flow0">named flow</a> has transitioned to the 1.158 + <code>REFERENCED</code> or the <code>STALE</code> states. 1.159 1.160 <div class=issue-marker data-bug_id=15879 data-bug_status=NEW> <a 1.161 href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15879">Bug-15879</a> 1.162 @@ -2021,11 +2076,13 @@ 1.163 interface <a href="#dom-namedflow">NamedFlow</a> { 1.164 readonly attribute DOMString name; 1.165 readonly attribute boolean <a 1.166 - href="#dom-namedflow-overflow">overflow</a>; 1.167 - readonly attribute <a 1.168 - href="http://www.w3.org/TR/dom/#interface-nodelist">NodeList</a> contentNodes; 1.169 + href="#dom-namedflow-overset">overset</a>; 1.170 + sequence<<a 1.171 + href="#region-interface">Region</a>> getRegions(); 1.172 <a 1.173 - href="http://www.w3.org/TR/dom/#interface-nodelist">NodeList</a> getRegionsByContentNode(<a 1.174 + href="http://www.w3.org/TR/dom/#interface-nodelist">NodeList</a> getContent(); 1.175 + sequence<<a 1.176 + href="#region-interface">Region</a>> getRegionsByContent(<a 1.177 href="http://www.w3.org/TR/dom/#interface-node">Node</a> node); 1.178 };</pre> 1.179 1.180 @@ -2033,72 +2090,87 @@ 1.181 attribute returns the name of the <a href="#dom-namedflow"><code 1.182 class=idl>NamedFlow</code></a> instance. 1.183 1.184 - <p>The <dfn id=dom-namedflow-overflow><code class=idl>overflow</code></dfn> 1.185 + <p>The <dfn id=dom-namedflow-overset><code class=idl>overset</code></dfn> 1.186 attribute returns true if the named flow does not fully fit in the 1.187 - associated regions. Otherwise, it returns false. A <a 1.188 - href="#dom-namedflow"><code class=idl>NamedFlow</code></a> object is live. 1.189 - 1.190 - <p>The <dfn id=dom-namedflow-contentnodes>contentNodes</dfn> attribute 1.191 - returns an ordered collection of nodes that constitute the named flow. 1.192 - Note that this collection is live: every time it is queried it must return 1.193 - the same object, and the object is always up to date. 1.194 + associated regions. Otherwise, it returns false. 1.195 + 1.196 + <p>The <dfn id=dom-namedflow-getregions><code 1.197 + class=idl>getRegions()</code></dfn> method returns the sequence of regions 1.198 + in the <span>region chain</span> associated with the <a 1.199 + href="#named-flow0">named flow</a>. Note that the returned values is a 1.200 + static sequence. 1.201 + 1.202 + <p>The <dfn id=dom-namedflow-getcontent>getContent()</dfn> methods returns 1.203 + an ordered collection of nodes that constitute the named flow. The 1.204 + returned list is a static snapshot of the named flow content at the time 1.205 + the method is invoked. 1.206 1.207 <p>The <dfn 1.208 - id=dom-namedflow-getregionsbycontentnodes>getRegionsByContentNode()</dfn> 1.209 - method gets a collection of regions that contain at least part of the 1.210 - target content node. The returned <code class=idl>NodeList</code> is live: 1.211 - every time the method is called with the same <code class=idl>node</code> 1.212 - argument, it must return the same object, and the object is always up to 1.213 - date.This can be used to navigate by bookmark in paginated view: the 1.214 - method returns regions containing the bookmarked element, which are then 1.215 - passed to pagination UI to show desired region or page. 1.216 - 1.217 - <p>With the <a href="#dom-namedflow"><code class=idl>NamedFlow</code></a> 1.218 - interface, authors can easily check if all content has been fitted into 1.219 - existing regions. If it has, the overflow property would be false. 1.220 - 1.221 - <h3 id=extension-to-the-element-interface><span class=secno>7.2. 1.222 - </span>Extension to the Element interface</h3> 1.223 - 1.224 - <p>When an region is an actual <a 1.225 - href="http://www.w3.org/TR/dom/#interface-element">Element</a>, it is 1.226 - convenient to easily find out if content fully fits into the 1.227 - <span>region</span> or not. The supplemental interface on <a 1.228 + id=dom-namedflow-getregionsbycontentnodes>getRegionsByContent()</dfn> 1.229 + method returns the sequence of regions that contain at least part of the 1.230 + target content node. Note that the returned values is a static sequence. 1.231 + 1.232 + <p>The <a href="#dom-namedflow"><code class=idl>NamedFlow</code></a> 1.233 + interface can be used for different purposes. For example, the <a 1.234 + href="#dom-namedflow-getregionsbycontentnodes"><code>getRegionsByContent()</code></a> 1.235 + method can help navigate by bookmark: a script can find the 1.236 + <span>region</span>s that display a particular anchor and bring them to 1.237 + view. 1.238 + 1.239 + <p>Likewise, the interface allows authors to check if all content has been 1.240 + fitted into existing regions. If it has, the <a 1.241 + href="#dom-namedflow-overset"><code>overset</code></a> attribute would be 1.242 + false. 1.243 + 1.244 + <h3 id=the-region-interface><span class=secno>7.2. </span>The Region 1.245 + interface</h3> 1.246 + 1.247 + <p>The <dfn id=region-interface><code class=idl>Region</code> 1.248 + interface</dfn> provides an abstraction for <a 1.249 href="http://www.w3.org/TR/dom/#interface-element"><code 1.250 - class=idl>Element</code></a> provides that functionality. 1.251 + class=idl>Element</code>s</a>, pseudo-elements or other CSS constructs 1.252 + (such as <a 1.253 + href="http://dev.w3.org/csswg/css3-page-template/#templates-and-slots">slots</a> 1.254 + in <a href="http://dev.w3.org/csswg/css3-page-template/">CSS Page 1.255 + Templates</a>) which can be regions. 1.256 1.257 <pre class=idl> 1.258 -partial interface <a 1.259 - href="http://www.w3.org/TR/dom/#interface-element">Element</a> { 1.260 - readonly attribute DOMString <a 1.261 - href="#dom-element-regionoverflow">regionOverflow</a>; 1.262 - sequence<<a 1.263 - href="#">Range</a>> <a 1.264 - href="#dom-element-getregionflowranges">getRegionFlowRanges()</a>; 1.265 -}; 1.266 - 1.267 -</pre> 1.268 - 1.269 - <p>The <dfn id=dom-element-regionoverflow><code 1.270 - class=idl>regionOverflow</code></dfn> attribute returns one of the 1.271 + interface Region { 1.272 + readonly attribute DOMString <a 1.273 + href="#dom-region-regionoverset">regionOverset</a>; 1.274 + readonly attribute DOMString <a 1.275 + href="#dom-region-flowfrom">flowFrom</a>; 1.276 + sequence<<a 1.277 + href="#">Range</a>>? <a 1.278 + href="#dom-region-getregionflowranges">getRegionFlowRanges()</a>; 1.279 + }; 1.280 + 1.281 + </pre> 1.282 + 1.283 + <p>The <dfn id=dom-region-regionoverset><code 1.284 + class=idl>regionOverset</code></dfn> attribute returns one of the 1.285 following values: 1.286 1.287 <dl> 1.288 - <dt>‘<a href="#dom-namedflow-overflow"><code 1.289 - class=property>overflow</code></a>’ 1.290 + <dt>‘<a href="#dom-namedflow-overset"><code 1.291 + class=property>overset</code></a>’ 1.292 1.293 <dd>the region is the last one in the <span title=region-chain>region 1.294 chain</span> and not able to fit the remaining content from the <a 1.295 href="#named-flow0">named flow</a>. Note that the region's <a 1.296 href="http://www.w3.org/TR/CSS21/visufx.html#overflow"><code 1.297 class=idl>overflow</code></a> property value can be used to control the 1.298 - visibility of the overflowing content. 1.299 + visibility of the overflowing content and the ‘<a 1.300 + href="#region-overflow"><code 1.301 + class=property>region-overflow</code></a>’ property controls 1.302 + whether or not fragmentation happens on the content that flows in the 1.303 + last region. 1.304 1.305 <dt>‘<code class=property>fit</code>’ 1.306 1.307 - <dd>the region element's content fits into the region's <a 1.308 + <dd>the region's flow fragment content fits into the region's <a 1.309 href="http://www.w3.org/TR/CSS21/box.html#box-dimensions">content 1.310 - box</a>. It does not overflow. If the region is the last one in the <span 1.311 + box</a>. If the region is the last one in the <span 1.312 title=region-chain>region chain</span>, it means that the content fits 1.313 without overflowing. If the region is not the last one in the region 1.314 chain, that means the <a href="#named-flow0">named flow</a> content is 1.315 @@ -2109,44 +2181,53 @@ 1.316 1.317 <dt>‘<code class=property>empty</code>’ 1.318 1.319 - <dd>the region element has no content and is empty. All content from the 1.320 - <a href="#named-flow0">named flow</a> was fitted in regions with a lower 1.321 - document order. 1.322 - 1.323 - <dt>‘<code class=property>undefined</code>’ 1.324 - 1.325 - <dd>The element is not a <span>region</span>. 1.326 + <dd>All content from the <a href="#named-flow0">named flow</a> was fitted 1.327 + in regions with a lower document order. 1.328 </dl> 1.329 1.330 <p>Note that if there is no content in the named flow, all regions 1.331 - associated with that named flow should have their ‘<a 1.332 - href="#dom-namedflow-overflow"><code 1.333 - class=property>overflow</code></a>’ attribute return ‘<code 1.334 - class=property>empty</code>’. If there is content in the flow but 1.335 - that content does not generate any box for visual formatting, the 1.336 - ‘<a href="#dom-namedflow-overflow"><code 1.337 - class=property>overflow</code></a>’ attribute on the first region in 1.338 + associated with that named flow should have their <a 1.339 + href="#dom-region-regionoverset"><code class=idl>regionOverset</code></a> 1.340 + attribute return ‘<code class=property>empty</code>’. If there 1.341 + is content in the flow but that content does not generate any box for 1.342 + visual formatting, the ‘<a href="#dom-namedflow-overset"><code 1.343 + class=property>overset</code></a>’ attribute on the first region in 1.344 the region chain associated with the flow will return ‘<code 1.345 class=property>fit</code>’. 1.346 1.347 - <p>The <dfn id=dom-element-getregionflowranges>getRegionFlowRanges</dfn> 1.348 + <p>The <dfn id=dom-region-flowfrom>flowFrom</dfn> attribute returns the 1.349 + name of the <a href="#named-flow0">named flow</a> this region is 1.350 + associated with. 1.351 + 1.352 + <p>The <dfn id=dom-region-getregionflowranges>getRegionFlowRanges</dfn> 1.353 method returns an array of <a 1.354 href="http://www.w3.org/TR/dom/#interface-range"> Range</a> instances 1.355 - corresponding to the content from the region flow that is positioned in 1.356 - the region. 1.357 - 1.358 - <p>If an element is not a <span>region</span>, the <a 1.359 - href="#dom-element-getregionflowranges"><code class=idl><span 1.360 - title="#document-element-getregionflowranges">getRegionFlowRanges</span></code></a> 1.361 - method throws a <a 1.362 - href="http://www.w3.org/TR/dom/#interface-domexception"><code 1.363 - class=idl>DOMException</code></a> with the <a 1.364 - href="http://www.w3.org/TR/dom/#dom-domexception-invalid_access_err"><code 1.365 - class=idl>INVALID_ACCESS_ERR</code></a> error code. 1.366 - 1.367 - <div class=note><span class=note-prefix>Note </span> The Element interface 1.368 - extension is only available to regions that are document elements and not 1.369 - to regions that are pseudo-elements.</div> 1.370 + corresponding to the content from the region flow that is laid out in the 1.371 + region. The method returns null if the <span>region</span> object is not 1.372 + (or no longer) a region. 1.373 + 1.374 + <div class=note> 1.375 + <p>A <code class=idl>Region</code> instance may represent and object that 1.376 + is no longer a <span>region</span>. This may happen, for example if the 1.377 + ‘<a href="#flow-from"><code 1.378 + class=property>flow-from</code></a>’ property on the corresponding 1.379 + pseudo-element, element or other construct becomes ‘<code 1.380 + class=property>none</code>’ but a script is still holding a 1.381 + reference to the <code class=idl>Region</code> object.</p> 1.382 + 1.383 + <p>If a <code class=idl>Region</code> instance is no longer a 1.384 + <span>region</span>, accessing its attributes (<a 1.385 + href="#dom-region-regionoverset"><code class=idl>regionOverset</code></a> 1.386 + and <a href="#dom-region-flowfrom"><code class=idl>flowFrom</code></a>) 1.387 + or invoking its <a href="#dom-region-getregionflowranges"><code 1.388 + class=idl><span 1.389 + title="#document-element-getregionflowranges">getRegionFlowRanges</span></code></a> 1.390 + method throws a <a 1.391 + href="http://www.w3.org/TR/dom/#interface-domexception"><code 1.392 + class=idl>DOMException</code></a> with the <a 1.393 + href="http://www.w3.org/TR/dom/#dom-domexception-invalid_access_err"><code 1.394 + class=idl>INVALID_ACCESS_ERR</code></a> error code.</p> 1.395 + </div> 1.396 1.397 <h3 id=region-flow-layout-events><span class=secno>7.3. </span>Region flow 1.398 layout events</h3> 1.399 @@ -2278,11 +2359,10 @@ 1.400 <li>In the section on region breaks, removed descriptions of break values 1.401 normatively defined in external specifications. Removed the section about 1.402 split boxes and replaced with paragraph referencing the page breaking 1.403 - behavior. Removed the discussion about how the ‘<a 1.404 - href="#dom-namedflow-overflow"><code 1.405 - class=property>overflow</code></a>’ property applies to content 1.406 - flown in regions from the break section, since this is covered in the 1.407 - section on ‘<a href="#region-overflow"><code 1.408 + behavior. Removed the discussion about how the ‘<code 1.409 + class=property>overflow</code>’ property applies to content flown 1.410 + in regions from the break section, since this is covered in the section 1.411 + on ‘<a href="#region-overflow"><code 1.412 class=property>region-overflow</code></a>’ already. See <a 1.413 href="http://lists.w3.org/Archives/Public/www-style/2011Dec/0477.html">mailing 1.414 list feedback.</a> 1.415 @@ -2294,9 +2374,8 @@ 1.416 href="http://lists.w3.org/Archives/Public/www-style/2011Dec/0480.html">mailing 1.417 list feedback</a>. 1.418 1.419 - <li>Clarified that the <code>NodeList</code> returned by <a 1.420 - href="#dom-namedflow-getregionsbycontentnodes"><code>getRegionsByContentNode</code></a> 1.421 - is live. 1.422 + <li>Clarified that the <code>NodeList</code> returned by 1.423 + <code>getRegionsByContentNode</code> is live. 1.424 1.425 <li>Added a name property to the <a 1.426 href="#dom-namedflow"><code>NamedFlow</code></a> interface. Added a <a 1.427 @@ -2326,6 +2405,40 @@ 1.428 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15191">Issue 1.429 15191</a> and <a 1.430 href="http://www.w3.org/Style/CSS/Tracker/actions/375">Action 375</a>. 1.431 + 1.432 + <li>Renamed ‘<code class=property>regionOverflow</code>’ to 1.433 + ‘<a href="#dom-region-regionoverset"><code 1.434 + class=property>regionOverset</code></a>’ to avoid confusion between 1.435 + fitting a flow in regions and the concept of visual overflow that the 1.436 + word ‘<code class=property>overflow</code>’ (and the 1.437 + property) carry. 1.438 + 1.439 + <li>Reworked the partial document interface following the <a 1.440 + href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=14948">Issue 1.441 + 14948</a> on <code>getFlowByName</code>. 1.442 + 1.443 + <li>Updated the object model section as proposed on the <a 1.444 + href="http://wiki.csswg.org/spec/css3-regions/css-om">wiki</a> and in 1.445 + particular: 1.446 + <ul> 1.447 + <li>introduced a <code>Region</code> interface to replace the 1.448 + supplemental Element interface 1.449 + 1.450 + <li>Added a ‘<a href="#dom-region-flowfrom"><code 1.451 + class=property>flowFrom</code></a>’ attribute on the Region 1.452 + interface 1.453 + 1.454 + <li>NamedFlow.getRegions() was added 1.455 + 1.456 + <li>Renamed getContentNode to getContent and getRegionsByContentNode to 1.457 + getRegionsByContent as per <a 1.458 + href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15879">Isseu 1.459 + 15879</a> 1.460 + 1.461 + <li>NamedFlow now returns static lists (see <a 1.462 + href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=16286">Issue 1.463 + 16286</a>) 1.464 + </ul> 1.465 </ul> 1.466 1.467 <h3 id="changes_from_June_09_2011"><span class=secno>11.2. </span>Changes 1.468 @@ -2820,24 +2933,31 @@ 1.469 <li>break-inside, <a href="#break-inside" 1.470 title=break-inside><strong>4.3.</strong></a> 1.471 1.472 - <li>contentNodes, <a href="#dom-namedflow-contentnodes" 1.473 - title=contentNodes><strong>7.1.</strong></a> 1.474 - 1.475 <li>current-region, <a href="#current-region" 1.476 title=current-region><strong>2.3.</strong></a> 1.477 1.478 + <li>flowFrom, <a href="#dom-region-flowfrom" 1.479 + title=flowFrom><strong>7.2.</strong></a> 1.480 + 1.481 <li>flow-from, <a href="#flow-from" 1.482 title=flow-from><strong>4.2.</strong></a> 1.483 1.484 <li>flow-into, <a href="#flow-into" 1.485 title=flow-into><strong>4.1.</strong></a> 1.486 1.487 - <li>getRegionFlowRanges, <a href="#dom-element-getregionflowranges" 1.488 + <li>getContent(), <a href="#dom-namedflow-getcontent" 1.489 + title="getContent()"><strong>7.1.</strong></a> 1.490 + 1.491 + <li>getRegionFlowRanges, <a href="#dom-region-getregionflowranges" 1.492 title=getRegionFlowRanges><strong>7.2.</strong></a> 1.493 1.494 - <li>getRegionsByContentNode(), <a 1.495 + <li><a href="#dom-namedflow-getregions"><code 1.496 + class=idl>getRegions()</code></a>, <a href="#dom-namedflow-getregions" 1.497 + title="getRegions()"><strong>7.1.</strong></a> 1.498 + 1.499 + <li>getRegionsByContent(), <a 1.500 href="#dom-namedflow-getregionsbycontentnodes" 1.501 - title="getRegionsByContentNode()"><strong>7.1.</strong></a> 1.502 + title="getRegionsByContent()"><strong>7.1.</strong></a> 1.503 1.504 <li><a href="#dom-namedflow-collection-item"><code 1.505 class=idl>item(index)</code></a>, <a 1.506 @@ -2862,20 +2982,21 @@ 1.507 href="#dom-namedflow-collection" 1.508 title=NamedFlowCollection><strong>7.1.</strong></a> 1.509 1.510 - <li><a href="#dom-namedflow-overflow"><code class=idl>overflow</code></a>, 1.511 - <a href="#dom-namedflow-overflow" 1.512 - title=overflow><strong>7.1.</strong></a> 1.513 + <li><a href="#dom-namedflow-overset"><code class=idl>overset</code></a>, 1.514 + <a href="#dom-namedflow-overset" title=overset><strong>7.1.</strong></a> 1.515 1.516 <li>region, <a href="#region" title=region>2.1.</a> 1.517 1.518 - <li><a href="#dom-element-regionoverflow"><code 1.519 - class=idl>regionOverflow</code></a>, <a 1.520 - href="#dom-element-regionoverflow" 1.521 - title=regionOverflow><strong>7.2.</strong></a> 1.522 + <li><code class=idl>Region</code> interface, <a href="#region-interface" 1.523 + title="Region interface"><strong>7.2.</strong></a> 1.524 1.525 <li>region-overflow, <a href="#region-overflow" 1.526 title=region-overflow><strong>4.4.</strong></a> 1.527 1.528 + <li><a href="#dom-region-regionoverset"><code 1.529 + class=idl>regionOverset</code></a>, <a href="#dom-region-regionoverset" 1.530 + title=regionOverset><strong>7.2.</strong></a> 1.531 + 1.532 <li>specified flow, <a href="#specified-flow" 1.533 title="specified flow"><strong>4.1.</strong></a> 1.534 </ul>
2.1 --- a/css3-regions/Overview.src.html Tue Mar 27 12:13:58 2012 -0700 2.2 +++ b/css3-regions/Overview.src.html Tue Mar 27 12:14:16 2012 -0700 2.3 @@ -1661,7 +1661,7 @@ 2.4 change depending on the display context. For example, flowing the same 2.5 content on a mobile phone with a small screen may require more regions than 2.6 on a large desktop display.</p> 2.7 - 2.8 + 2.9 <div class="issue-marker" data-bug_id="15010" data-bug_status="NEW"> 2.10 <a href= 2.11 "https://www.w3.org/Bugs/Public/show_bug.cgi?id=15010">Bug-15010</a> 2.12 @@ -1684,16 +1684,15 @@ 2.13 on it must return the list of rectangles for the element in all the 2.14 regions it is part of.</p> 2.15 </div> 2.16 - 2.17 <h3 id="the-namedflow-interface">The NamedFlow interface</h3> 2.18 2.19 <p>A <span>named flow</span> is created when it becomes referenced by the 2.20 - 'flow-into' and 'flow-from' computed values. The following APIs also allow 2.21 + 'flow-into' and/or 'flow-from' computed values. The following APIs also allow 2.22 scripts to reference a <code class="idl">NamedFlow</code> object representation 2.23 of a <span>named flow</span>.</p> 2.24 2.25 <p>The possible states for a <span>named flow</span> are described in the following 2.26 - figure and referenced in subsequent text.</p> 2.27 + figure. These states are referenced in subsequent text.</p> 2.28 2.29 <div class="figure"> 2.30 <img src="images/named-flow-states.svg" alt="NamedFlow states" width="600px" /> 2.31 @@ -1728,7 +1727,7 @@ 2.32 flow</span>s in the document.</p> 2.33 2.34 <p>The <code class="idl">namedFlows</code> collection must include all <span>named flow</span> 2.35 - that are currently in the <code>CREATED</code> and <code>CREATED-REFERENCED</code>state. 2.36 + that are currently in the <code>CREATED</code> and <code>CREATED-REFERENCED</code> states. 2.37 The list may include <span>named flows</span> 2.38 that are in the <code>REFERENCED</code> state. The list 2.39 may also include <span>named flow</code> instances that are in the STALE state.</p> 2.40 @@ -1740,18 +1739,18 @@ 2.41 state:</p> 2.42 2.43 <ul> 2.44 - <li><code class="idl">NULL</code>: the user agent must return <code>null</code></li> 2.45 - <li><code class="idl">STALE</code> the user agent may return null or a valid 2.46 + <li><code class="idl">NULL</code>: the user agent must return <code>null</code>.</li> 2.47 + <li><code class="idl">STALE</code>: the user agent may return null or a valid 2.48 <code class="idl">NamedFlow</code> instance. 2.49 If the user agent returns a valid instance, subsequent calls to the <code class="idl">getFlowByName</code> method 2.50 - must return the same object instance, no matter what the state of the 2.51 + for the same name argument must return the same object instance, no matter what the state of the 2.52 <span>named flow</span> is.</li> 2.53 <li><code class="idl">CREATED</code> or <code class="idl">CREATED-REFERENCED</code>: the 2.54 user agent must return a valid <code class="idl">NamedFlow</code> instance.</li> 2.55 <li><code class="idl">REFERENCED</code>: the user agent may return <code>null</code> or it may return a 2.56 valid <code class="idl">NamedFlow</code> instance. If the user agent returns a 2.57 valid object, subsequent calls to the <code class="idl">getFlowByName</code> method 2.58 - must return the same object instance, no matter what the state of the 2.59 + with the same name argument must return the same object instance, no matter what the state of the 2.60 <span>named flow</span> is.</li> 2.61 </ul> 2.62 2.63 @@ -1786,7 +1785,10 @@ 2.64 indices in the range <code>0 ≤ index < collection.length</code>.</p> 2.65 2.66 <p>The <dfn id="dom-namedflow"><code class="idl">NamedFlow</code></dfn> 2.67 - interface offers a representation of the <span>named flow</span>.</p> 2.68 + interface offers a representation of the <span>named flow</span>. A <code class="idl">NamedFlow</code> 2.69 + object is live meaning that it always represents the <span>named flow</span> with the corresponding 2.70 + name, even if that <span>named flow</span> has transitioned to the <code>REFERENCED</code> or 2.71 + the <code>STALE</code> states.</p> 2.72 2.73 <div class="issue-marker" data-bug_id="15879" data-bug_status="NEW"> 2.74 <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15879">Bug-15879</a> 2.75 @@ -1798,114 +1800,128 @@ 2.76 <pre class="idl"> 2.77 interface <a href="#dom-namedflow">NamedFlow</a> { 2.78 readonly attribute DOMString name; 2.79 - readonly attribute boolean <a href="#dom-namedflow-overflow">overflow</a>; 2.80 - readonly attribute <a href="http://www.w3.org/TR/dom/#interface-nodelist">NodeList</a> contentNodes; 2.81 - <a href="http://www.w3.org/TR/dom/#interface-nodelist">NodeList</a> getRegionsByContentNode(<a href="http://www.w3.org/TR/dom/#interface-node">Node</a> node); 2.82 + readonly attribute boolean <a href="#dom-namedflow-overset">overset</a>; 2.83 + sequence<<a href="#region-interface">Region</a>> getRegions(); 2.84 + <a href="http://www.w3.org/TR/dom/#interface-nodelist">NodeList</a> getContent(); 2.85 + sequence<<a href="#region-interface">Region</a>> getRegionsByContent(<a href="http://www.w3.org/TR/dom/#interface-node">Node</a> node); 2.86 };</pre> 2.87 2.88 <p>The <dfn id="dom-namedflow-name"><code class="idl">name</code></dfn> attribute 2.89 returns the name of the <code class="idl">NamedFlow</code> instance.</p> 2.90 2.91 - <p>The <dfn id="dom-namedflow-overflow"><code class= 2.92 - "idl">overflow</code></dfn> attribute returns true if the named flow does not 2.93 - fully fit in the associated regions. Otherwise, it returns false. A 2.94 - <code class="idl">NamedFlow</code> object is live.</p> 2.95 + <p>The <dfn id="dom-namedflow-overset"><code class= 2.96 + "idl">overset</code></dfn> attribute returns true if the named flow does not 2.97 + fully fit in the associated regions. Otherwise, it returns false. </p> 2.98 2.99 - <p>The <dfn id="dom-namedflow-contentnodes">contentNodes</dfn> attribute returns 2.100 - an ordered collection of nodes that constitute the named flow. Note that this 2.101 - collection is live: every time it is 2.102 - queried it must return the same object, and the object is always up to date. 2.103 + <p>The <dfn id="dom-namedflow-getregions"><code class="idl">getRegions()</code></dfn> 2.104 + method returns the sequence of regions in the <span>region chain</span> associated 2.105 + with the <span>named flow</span>. Note that the returned values is a static sequence.</p> 2.106 + 2.107 + <p>The <dfn id="dom-namedflow-getcontent">getContent()</dfn> methods returns 2.108 + an ordered collection of nodes that constitute the named flow. The returned list 2.109 + is a static snapshot of the named flow content at the time the method is invoked. 2.110 </p> 2.111 2.112 - <p>The <dfn id="dom-namedflow-getregionsbycontentnodes">getRegionsByContentNode()</dfn> method gets a 2.113 - collection of regions that contain at least part of the target content node. The returned 2.114 - <code class="idl">NodeList</code> is live: every time the method is called with the 2.115 - same <code class="idl">node</code> argument, it must return the same object, and the 2.116 - object is always up to date.This can be used 2.117 - to navigate by bookmark in paginated view: the method returns regions containing the 2.118 - bookmarked element, which are then passed to pagination UI to show desired region or page.</p> 2.119 + <p>The <dfn id="dom-namedflow-getregionsbycontentnodes">getRegionsByContent()</dfn> method returns the 2.120 + sequence of regions that contain at least part of the target content node. 2.121 + Note that the returned values is a static sequence.</p> 2.122 + 2.123 + <p>The <code class="idl">NamedFlow</code> interface can be used for different purposes. 2.124 + For example, the <code>getRegionsByContent()</code> method can help navigate by bookmark: 2.125 + a script can find the <span>region</span>s that display a particular anchor and bring them 2.126 + to view.</p> 2.127 2.128 - <p>With the <a href="#dom-namedflow"><code class="idl">NamedFlow</code></a> 2.129 - interface, authors can easily check if all content has been fitted into 2.130 - existing regions. If it has, the overflow property would be false.</p> 2.131 + <p>Likewise, the interface allows authors to check if all content has been fitted into 2.132 + existing regions. If it has, the <code>overset</code> attribute would be false.</p> 2.133 + 2.134 + 2.135 + 2.136 + <h3 id="the-region-interface">The Region interface</h3> 2.137 2.138 - <h3 id="extension-to-the-element-interface">Extension to the Element 2.139 - interface</h3> 2.140 + <p>The <dfn id='region-interface'><code class="idl">Region</code> interface</dfn> 2.141 + provides an abstraction for <a href= 2.142 + "http://www.w3.org/TR/dom/#interface-element"><code class= 2.143 + "idl">Element</code>s</a>, pseudo-elements or other CSS constructs (such as 2.144 + <a href="http://dev.w3.org/csswg/css3-page-template/#templates-and-slots">slots</a> in <a href="http://dev.w3.org/csswg/css3-page-template/">CSS Page Templates</a>) which 2.145 + can be regions.</p> 2.146 + 2.147 + <pre class="idl"> 2.148 + interface Region { 2.149 + readonly attribute DOMString <a href="#dom-region-regionoverset">regionOverset</a>; 2.150 + readonly attribute DOMString <a href="#dom-region-flowfrom">flowFrom</a>; 2.151 + sequence<<a href="#">Range</a>>? <a href= 2.152 + "#dom-region-getregionflowranges">getRegionFlowRanges()</a>; 2.153 + }; 2.154 2.155 - <p>When an region is an actual <a href= 2.156 - "http://www.w3.org/TR/dom/#interface-element">Element</a>, 2.157 - it is convenient to easily find out if content fully fits into the 2.158 - <span>region</span> or not. The supplemental interface on <a href= 2.159 - "http://www.w3.org/TR/dom/#interface-element"><code class= 2.160 - "idl">Element</code></a> provides that functionality.</p> 2.161 - <pre class="idl"> 2.162 -partial interface <a href= 2.163 -"http://www.w3.org/TR/dom/#interface-element">Element</a> { 2.164 - readonly attribute DOMString <a href="#dom-element-regionoverset">regionOverset</a>; 2.165 - sequence<<a href="#">Range</a>> <a href= 2.166 -"#dom-element-getregionflowranges">getRegionFlowRanges()</a>; 2.167 -}; 2.168 - 2.169 -</pre> 2.170 + </pre> 2.171 2.172 - <p>The <dfn id="dom-element-regionoverset"><code class= 2.173 - "idl">regionOverset</code></dfn> attribute returns one of the following 2.174 - values:</p> 2.175 + <p>The <dfn id="dom-region-regionoverset"><code class= 2.176 + "idl">regionOverset</code></dfn> attribute returns one of the following 2.177 + values:</p> 2.178 2.179 - <dl> 2.180 - <dt>'overset'</dt> 2.181 + <dl> 2.182 + <dt>'overset'</dt> 2.183 2.184 - <dd>the region is the last one in the 2.185 - <span title="region-chain">region chain</span> and 2.186 - not able to fit the remaining content from the <span>named flow</span>. 2.187 - Note that the region's <a href= 2.188 - "http://www.w3.org/TR/CSS21/visufx.html#overflow"><code class= 2.189 - "idl">overflow</code></a> property value can be used to control the 2.190 - visibility of the overflowing content and the 2.191 - 'region-overflow' property controls whether or not fragmentation happens 2.192 - on the content that flows in the last region.</dd> 2.193 + <dd>the region is the last one in the 2.194 + <span title="region-chain">region chain</span> and 2.195 + not able to fit the remaining content from the <span>named flow</span>. 2.196 + Note that the region's <a href= 2.197 + "http://www.w3.org/TR/CSS21/visufx.html#overflow"><code class= 2.198 + "idl">overflow</code></a> property value can be used to control the 2.199 + visibility of the overflowing content and the 2.200 + 'region-overflow' property controls whether or not fragmentation happens 2.201 + on the content that flows in the last region.</dd> 2.202 2.203 - <dt>'fit'</dt> 2.204 + <dt>'fit'</dt> 2.205 2.206 - <dd>the region element's flow fragment content fits into the region's <a href= 2.207 - "http://www.w3.org/TR/CSS21/box.html#box-dimensions">content box</a>. 2.208 - If the region is the last one in the <span title= 2.209 - "region-chain">region chain</span>, it means that the content fits 2.210 - without overflowing. If the region is not the last one in the region 2.211 - chain, that means the <span>named flow</span> 2.212 - content is further fitted in subsequent regions. In particular, in this 2.213 - last case, that means the region may have received no content from the 2.214 - <span>named flow</span> (for example if the region 2.215 - is too small to accommodate any content).</dd> 2.216 + <dd>the region's flow fragment content fits into the region's <a href= 2.217 + "http://www.w3.org/TR/CSS21/box.html#box-dimensions">content box</a>. 2.218 + If the region is the last one in the <span title= 2.219 + "region-chain">region chain</span>, it means that the content fits 2.220 + without overflowing. If the region is not the last one in the region 2.221 + chain, that means the <span>named flow</span> 2.222 + content is further fitted in subsequent regions. In particular, in this 2.223 + last case, that means the region may have received no content from the 2.224 + <span>named flow</span> (for example if the region 2.225 + is too small to accommodate any content).</dd> 2.226 2.227 - <dt>'empty'</dt> 2.228 + <dt>'empty'</dt> 2.229 2.230 - <dd>the region element has no content and is empty. All content from 2.231 - the <span>named flow</span> was fitted in regions 2.232 - with a lower document order.</dd> 2.233 - </dl> 2.234 - 2.235 - <p>Note that if there is no content in the named flow, all regions associated 2.236 - with that named flow should have their 'overflow' attribute return 'empty'. 2.237 - If there is content in the flow but that content does not generate any box 2.238 - for visual formatting, the 'overflow' attribute on the first region in the 2.239 - region chain associated with the flow will return 'fit'.</p> 2.240 + <dd>All content from the <span>named flow</span> was fitted in regions with a 2.241 + lower document order.</dd> 2.242 + 2.243 + </dl> 2.244 2.245 - <p>The <dfn id="dom-element-getregionflowranges">getRegionFlowRanges</dfn> method returns 2.246 - an array of <a href= 2.247 - "http://www.w3.org/TR/dom/#interface-range"> 2.248 - Range</a> instances corresponding to the content from the region flow that 2.249 - is positioned in the region.</p> 2.250 + <p>Note that if there is no content in the named flow, all regions associated 2.251 + with that named flow should have their <code class="idl">regionOverset</code> 2.252 + attribute return 'empty'. 2.253 + If there is content in the flow but that content does not generate any box 2.254 + for visual formatting, the 'overset' attribute on the first region in the 2.255 + region chain associated with the flow will return 'fit'.</p> 2.256 2.257 - <p>If an element is not a <span>region</span>, the <code class= 2.258 - "idl"><span title="#document-element-getregionflowranges">getRegionFlowRanges</span></code> 2.259 - method throws a <a href="http://www.w3.org/TR/dom/#interface-domexception"><code class="idl">DOMException</code></a> with the 2.260 - <a href="http://www.w3.org/TR/dom/#dom-domexception-invalid_access_err"><code class="idl">INVALID_ACCESS_ERR</code></a> error code.</p> 2.261 + <p>The <dfn id="dom-region-flowfrom">flowFrom</dfn> attribute returns the name of the 2.262 + <span>named flow</span> this region is associated with.</p> 2.263 + 2.264 + <p>The <dfn id="dom-region-getregionflowranges">getRegionFlowRanges</dfn> method returns 2.265 + an array of <a href= 2.266 + "http://www.w3.org/TR/dom/#interface-range"> 2.267 + Range</a> instances corresponding to the content from the region flow that 2.268 + is laid out in the region. The method returns null if the 2.269 + <span>region</span> object is not (or no longer) a region.</p> 2.270 2.271 - <div class="note"><span class="note-prefix">Note </span> 2.272 - The Element interface extension is only available to regions that are 2.273 - document elements and not to regions that are pseudo-elements. 2.274 - </div> 2.275 + <div class="note"> 2.276 + <p>A <code class="idl">Region</code> instance may represent and 2.277 + object that is no longer a <span>region</span>. This may happen, for example if the 2.278 + 'flow-from' property on the corresponding pseudo-element, element or other construct 2.279 + becomes 'none' but a script is still holding a reference to the <code class="idl">Region</code> object.</p> 2.280 + 2.281 + <p>If a <code class="idl">Region</code> instance is no longer a <span>region</span>, 2.282 + accessing its attributes (<code class="idl">regionOverset</code> and <code class="idl">flowFrom</code>) or 2.283 + invoking its <code class= 2.284 + "idl"><span title="#document-element-getregionflowranges">getRegionFlowRanges</span></code> 2.285 + method throws a <a href="http://www.w3.org/TR/dom/#interface-domexception"><code class="idl">DOMException</code></a> with the 2.286 + <a href="http://www.w3.org/TR/dom/#dom-domexception-invalid_access_err"><code class="idl">INVALID_ACCESS_ERR</code></a> error code.</p> 2.287 + </div> 2.288 2.289 <h3 id="region-flow-layout-events">Region flow layout events</h3> 2.290 2.291 @@ -2006,6 +2022,17 @@ 2.292 <li>Renamed 'regionOverflow' to 'regionOverset' to avoid confusion between fitting a flow in 2.293 regions and the concept of visual overflow that the word 'overflow' (and the property) carry.</li> 2.294 <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> 2.295 + <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: 2.296 + <ul> 2.297 + <li>introduced a <code>Region</code> interface to replace the supplemental Element interface</li> 2.298 + <li>Added a 'flowFrom' attribute on the Region interface</li> 2.299 + <li>NamedFlow.getRegions() was added</li> 2.300 + <li>Renamed getContentNode to getContent and getRegionsByContentNode to getRegionsByContent as 2.301 + per <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=15879">Isseu 15879</a></li> 2.302 + <li>NamedFlow now returns static lists (see <a href="https://www.w3.org/Bugs/Public/show_bug.cgi?id=16286">Issue 16286</a>)</li> 2.303 + 2.304 + </ul> 2.305 + </li> 2.306 </ul> 2.307 2.308