The Tor Browser / file comparison
comparison: layout/doc/Layout_Overview.html
layout/doc/Layout_Overview.html
- branch
- TOR_BUG_9701
- changeset 14
- 925c144e1f1f
equal
deleted
inserted
replaced
| -1:000000000000 | 0:0c127e0bf3fe |
|---|---|
| 1 <!-- This Source Code Form is subject to the terms of the Mozilla Public | |
| 2 - License, v. 2.0. If a copy of the MPL was not distributed with this | |
| 3 - file, You can obtain one at http://mozilla.org/MPL/2.0/. --> | |
| 4 | |
| 5 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> | |
| 6 <html> | |
| 7 <head> | |
| 8 <title>Layout Overview</title> | |
| 9 <meta http-equiv="content-type" | |
| 10 content="text/html; charset=ISO-8859-1"> | |
| 11 </head> | |
| 12 <body> | |
| 13 <h1>Layout System Overview</h1> | |
| 14 <br> | |
| 15 <h3>Layout's Job: Provide the Presentation</h3> | |
| 16 Layout is primarily concerned with providing a presentation to an HTML or | |
| 17 XML document. This presentation is typically formatted in accordance with | |
| 18 the requirements of the <a href="http://www.w3.org/TR/REC-CSS1">CSS1</a> | |
| 19 and <a href="http://www.w3.org/TR/REC-CSS2/">CSS2</a> specifications from | |
| 20 the W3C. Presentation formatting is also required to provide compatibility | |
| 21 with legacy browsers (Microsoft Internet Explorer and Netscape Navigator | |
| 22 4.x). The decision about when to apply CSS-specified formatting and when | |
| 23 to apply legacy formatting is controlled by the document's DOCTYPE specification. | |
| 24 These layout modes are referred to as 'Standards' and 'NavQuirks' modes. (DOCTYPE | |
| 25 and modes are explained in more detail <a | |
| 26 href="http://www.mozilla.org/quality/help/bugzilla-helper.html">here</a>).<br> | |
| 27 <br> | |
| 28 The presentation generally is constrained by the width of the window in which | |
| 29 the presentation is to be displayed, and a height that extends as far as | |
| 30 necessary. This is referred to as the Galley Mode presentation, and is what | |
| 31 one expects from a typical browser. Additionally, layout must support a paginated | |
| 32 presentation, where the width of the presentation is constrained by the dimensions | |
| 33 of the printed output (paper) and the height of each page is fixed. This | |
| 34 paged presentation presents several challenges not present in the galley | |
| 35 presentation, namely how to break up elements that are larger than a single | |
| 36 page, and how to handle changes to page dimensions.<br> | |
| 37 <br> | |
| 38 The original design of the Layout system allowed for multiple, possibly different, | |
| 39 presentations to be supported simultaneously from the same content model. | |
| 40 In other words, the same HTML or XML document could be viewed as a normal | |
| 41 galley presentation in a browser window, while simultaneously being presented | |
| 42 in a paged presentation to a printer, or even an aural presentation to a | |
| 43 speech-synthesizer. To date the only real use of this multiple presentation | |
| 44 ability is seen in printing, where multiple presentations are managed, all | |
| 45 connected to the same content model. (note: it is unclear if this is really | |
| 46 a benefit - it may have been better to use a copy of the content model for | |
| 47 each presentation, and to remove the complexity of managing separate presentations | |
| 48 - analysis is needed here). The idea of supporting a non-visual presentation | |
| 49 is interesting. Layout's support for aural presentations is undeveloped, | |
| 50 though conceptually, it is possible and supported by the architecture.<br> | |
| 51 <br> | |
| 52 <h3>How Layout Does its Job: Frames and Reflow</h3> | |
| 53 So, layout is concerned with providing a presentation, in galley or paged | |
| 54 mode. Given a content model, how does the layout system actually create the | |
| 55 presentation? Through the creation and management of frames. Frames are an | |
| 56 encapsulation of a region on the screen, a region that contains geometry | |
| 57 (size and location, stacking order). Generally frames correspond to the content | |
| 58 elements, though there is often a one-to-many correspondence between content | |
| 59 elements and frames. Layout creates frames for content based on either the | |
| 60 specific HTML rules for an element or based on the CSS display type of the | |
| 61 element. In the case of the HTML-specific elements, the frame types that | |
| 62 correspond to the element are hard-coded, but in the more general case where | |
| 63 the display type is needes, the layout system must determine that display | |
| 64 type by using the Style System. A content element is passed to the Style | |
| 65 System and a request is made to resolve the style for that element. This | |
| 66 causes the Style System to apply all style rules that correspond to the element | |
| 67 and results in a resolved Style Context - the style data specific to that | |
| 68 element. The Layout module looks at the 'display' field of the style context | |
| 69 to determine what kind of frame to create (block, inline, table, etc.). The | |
| 70 style context is associated with the frame via a reference because it is | |
| 71 needed for many other computations during the formatting of the frames.<br> | |
| 72 <br> | |
| 73 Once a frame is created for a content element, it must be formatted. We refer | |
| 74 to this as 'laying out' the frame, or as 'reflowing' the frame. Each frame | |
| 75 implements a Reflow method to compute its position and size, among other | |
| 76 things. For more details on the Reflow mechanism, see the Reflow Overview | |
| 77 document... The CSS formatting requirements present two distinct layout | |
| 78 models: 1) the in-flow model, where the geometry of an element is influenced | |
| 79 by the geometry of the elements that precede it, and 2) the positioned model, | |
| 80 where the geometry of an element is not influenced by the geometry of the | |
| 81 elements that precede it, or in any case, is influenced more locally. The | |
| 82 in-flow cased is considered the 'normal' case, and corresponds to normal | |
| 83 HTML formatting. The later case, called 'out of flow' puts the document author | |
| 84 in control of the layout, and the author must specify the locations and sizes | |
| 85 of all of the elements that are positioned. There is, of course, some complexity | |
| 86 involved with managing these two models simultanelusly...<br> | |
| 87 <br> | |
| 88 So far the general flow of layout looks like this:<br> | |
| 89 <br> | |
| 90 1) Obtain a document's content model<br> | |
| 91 2) Utilize the Style System to resolve the style of each element in the content | |
| 92 model<br> | |
| 93 3) Construct the frames that correspond to the content model, according to | |
| 94 the resolved style data.<br> | |
| 95 4) Perform the initial layout, or initial reflow, on the newly constructed | |
| 96 frame.<br> | |
| 97 <br> | |
| 98 This is pretty straight-forward, but is complicated somewhat by the notion | |
| 99 of <i>incrementalism</i>. One of the goals of the Layout system's design | |
| 100 is to create parts of the presentation as they become available, rather than | |
| 101 waiting for the entire document to be read, parsed, and then presented. This | |
| 102 is a major benefit for large documents because the user does not have to wait | |
| 103 for the 200th page of text to be read in before the first page can be displayed | |
| 104 - they can start reading something right away. So really, this sequence of | |
| 105 operations Resolve Style, Create Frame, Layout Frame, gets repeated many | |
| 106 times as the content becomes available. In the normal in-flow case this is | |
| 107 quite natural because the sequential addition of new content results in sequential | |
| 108 addition of new frames, and because everything is in-flow, the new frames | |
| 109 do not influence the geometry of the frames that have already been formatted. | |
| 110 When out-of-flow frames are present this is a more difficult problem, however. | |
| 111 Sometimes a content element comes in incrementally, and invalidates the formatting | |
| 112 of some of the frames that precede it, frame that have already been formatted. | |
| 113 In this case the Layout System has to detect that impact and reflow again | |
| 114 the impacted frames. This is referred to as an <i>incremental reflow</i>.<br> | |
| 115 <br> | |
| 116 <a name="DHTML_interaction"></a>Another responsibility of layout is to manage | |
| 117 dynamic changes to the content model, changes that occur after the document | |
| 118 has been loaded and (possibly) presented. These dynamic changes are caused | |
| 119 by manipulations of the content model via the <acronym | |
| 120 title="Document Object Model">DOM<acronym></acronym></acronym> (generally | |
| 121 through java script). When a content element is modified, added or removed, | |
| 122 Layout is notified. If content elements have been inserted, new frames are | |
| 123 created and formatted (and impacts to other frames are managed by performing | |
| 124 further incremental reflows). If content is removed, the corresponding frames | |
| 125 are destroyed (again, impacts to other elements are managed). If a content | |
| 126 element is modified, layout must determine if the chage influences the formatting | |
| 127 of that or other elements' presentations, and must then reformat, or re-reflow, | |
| 128 the impacted elements. In all cases, the determination of the impact is critical | |
| 129 to avoid either the problem of not updating impacted elements, thus presenting | |
| 130 an invalid presentation, or updating too much of the presentation and thus | |
| 131 doing too much work, potentially causing performance problems.<br> | |
| 132 <br> | |
| 133 One very special case of dynamic content manipulation is the HTML Editor. | |
| 134 Layout is used to implement both a full-blown WYSIWYG HTML editor, and a single | |
| 135 and multi-line text entry control. In both cases, the content is manipulated | |
| 136 by the user (via the DOM) and the resulting visual impacts must be shown as | |
| 137 quickly as possible, without disconcerting flicker or other artifacts that | |
| 138 might bother the user. Consider a text entry field: the user types text into | |
| 139 a form on the web. As the user types a new character it is inserted into | |
| 140 the content model. This causes layout to be notified that a new piece of | |
| 141 content has been entered, which causes Layout to create a new frame and format | |
| 142 it. This must happen very fast, so the user's typing is not delayed. In the | |
| 143 case of the WYSIWYG HTML editor, the user expects that the modifications | |
| 144 they make to the document will apear immediately, not seconds later. This | |
| 145 is especially critical when the user is typing into the document: it would | |
| 146 be quite unusable if typing a character at the end of a document in the HTML | |
| 147 editor caused the entire document to be reformated - it would be too slow, | |
| 148 at least on low-end machines. Thus the HTML editor and text controls put | |
| 149 considerable performance requirements on the layout system's handling of dynamic | |
| 150 content manipulation.<br> | |
| 151 <h3>The Fundamentals of Frames: Block and Line</h3> | |
| 152 There are many types of frames that are designed to model various formatting | |
| 153 requirements of different HTML and XML elements. CSS2 defines several (block, | |
| 154 inline, list-item, marker, run-in, compact, and various table types) and | |
| 155 the standard HTML form controls require their own special frame types to | |
| 156 be formatted as expected. The most essential frame types are Block and Inline, | |
| 157 and these correspond to the most important Layout concepts, the Block and | |
| 158 Line.<br> | |
| 159 <br> | |
| 160 A block is a rectangular region that is composed of one or more lines. A | |
| 161 line is a single row of text or other presentational elements. All layout | |
| 162 happens in the context of a block, and all of the contents of a block are | |
| 163 formatted into lines within that block. As the width of a block is changed, | |
| 164 the contents of the lines must be reformatted. consider for example a large | |
| 165 paragraph of text sitting in paragraph:<br> | |
| 166 <br> | |
| 167 <pre><p><br> We need documentation for users, web developers, and developers working | |
| 168 on Mozilla. If you write your own code, document it. Much of the | |
| 169 existing code <b>isn’t very well documented</b>. In the process of figuring | |
| 170 things out, try and document your discoveries. | |
| 171 If you’d like to contribute, let us know.<br></p></pre> | |
| 172 There is one block that corresponds to the <p> element, and then a number | |
| 173 of lines of text that correspond to the text. As the width of the block changes | |
| 174 (due to the window being resized, for example) the length of the lines within | |
| 175 it changes, and thus more or less text appears on each line. The block is | |
| 176 responsible for managing the lines. Note that lines may contain only inline | |
| 177 elements, whereas block may contain both inline elements and other blocks.<br> | |
| 178 <h3>Other Layout Models: XUL</h3> | |
| 179 In addition to managing CSS-defined formatting, the layout system provides | |
| 180 a way to integrate other layout schemes into the presentation. Currently | |
| 181 layout supports the formatting of XUL elements, which utilize a constraint-based | |
| 182 layout language. The Box is introduced into the layout system's frame model | |
| 183 via an adapter (BoxToBlockAdapter) that translates the normal layout model | |
| 184 into the box formatting model. Conceptually, this could be used to introduce | |
| 185 other layout systems, but it might be worth noting that there was no specific | |
| 186 facility designed into the layout system to accommodate this. Layout deals | |
| 187 with frames, but as long as the layout system being considered has no need | |
| 188 to influence presentational elements from other layout systems, it can be | |
| 189 adapted using a frame-based adapter, ala XUL.<br> | |
| 190 <br> | |
| 191 <h2>Core Classes</h2> | |
| 192 At the highest level, the layout system is a group of classes that manages | |
| 193 the presentation within a fixed width and either unlimited height (galley | |
| 194 presentation) or discrete page heights (paged presentation). Digging just | |
| 195 a tiny bit deeper into the system we find that the complexity (and interest) | |
| 196 mushrooms very rapidly. The idea of formatting text and graphics to fit within | |
| 197 a given screen area sounds simple, but the interaction of in-flow and out-of-flow | |
| 198 elements, the considerations of incremental page rendering, and the performance | |
| 199 concerns of dynamic content changes makes for a system that has a lot of | |
| 200 work to do, and a lot of data to manage. Here are the high-level classes | |
| 201 that make up the layout system. Of course this is a small percentage of the | |
| 202 total clases in layout (see the detailed design documents for the details | |
| 203 on all of the classes, in the context of their actual role).<br> | |
| 204 <h3>Presentation Shell / Presentation Context</h3> | |
| 205 Together the presentation shell and the presentation context provide the | |
| 206 root of the current presentation. The original design provided for a single | |
| 207 Presentation Shell to manage multiple Presentation Contexts, to allow a single | |
| 208 shell to handle multiple presentations. It is unclear if this is really possible, | |
| 209 however, and in general it is assumed that there is a one-to-one correspondence | |
| 210 between a presentation shell and a presentation context. The two classes | |
| 211 should probably be folded into one, or the distinction between them formalized | |
| 212 and utilized in the code. The Presentation Shell currently owns a controlling | |
| 213 reference to the Presentation Context. Further references to the Presentation | |
| 214 Shell and Presentation Context will be made by using the term Presentation | |
| 215 Shell.<br> | |
| 216 <br> | |
| 217 The Presentation Shell is the root of the presentation, and as such it owns | |
| 218 and manges a lot of layout objects that are used to create and maintain a | |
| 219 presentation (<font color="#990000">note that the DocumentViewer is the owner | |
| 220 of the Presentation Shell, and in some cases the creator of the objects | |
| 221 used by the Presentation Shell to manage the presentation. More details | |
| 222 of the Document Viewer are needed here...</font>). The Presentation Shell, | |
| 223 or PresShell, is first and foremost the owner of the formatting objects, | |
| 224 the frames. Management of the frames is facilitated by the Frame Manager, | |
| 225 an instance of which the PresShell owns. Additionally, the PresShell provides | |
| 226 a specialized storage heap for frames, called an Arena, that is used to make | |
| 227 allocation and deallocation of frames faster and less likely to fragment | |
| 228 the global heap. <br> | |
| 229 <br> | |
| 230 The Presentation Shell also owns the root of the Style System, the Style | |
| 231 Set. In many cases the Presentation Shell provides pass-through methods to | |
| 232 the Style Set, and generally uses the Style Set to do style resolution and | |
| 233 Style Sheet management.<br> | |
| 234 <br> | |
| 235 One of the critical aspects of the Presentation Shell is the handling of | |
| 236 frame formatting, or reflow. The Presentation Shell owns and maintains a | |
| 237 Reflow Queue where requests for reflow are held until it is time to perform | |
| 238 a reflow, and then pulled out and executed.<br> | |
| 239 <br> | |
| 240 It is also important to see the Presentation Shell as an observer of many | |
| 241 kinds of events in the system. For example, the Presentation Shell receives | |
| 242 notifications of document load events, which are used to trigger updates | |
| 243 to the formatting of the frames in some cases. The Presentation Shell also | |
| 244 receives notifications about changes in cursor and focus states, whereby | |
| 245 the selection and caret updates can be made visible.<br> | |
| 246 <br> | |
| 247 There are dozens of other data objects managed by the Presentation Shell | |
| 248 and Presentation Context, all necessary for the internal implementation. | |
| 249 These data members and their roles will be discussed in the Presentation | |
| 250 Shell design documents. For this overview, the Frames, Style Set, and Reflow | |
| 251 Queue are the most important high-level parts of the Presentation Shell.<br> | |
| 252 <h3>Frame Manager</h3> | |
| 253 The Frame Manager is used to, well, manage frames. Frames are basic formatting | |
| 254 objects used in layout, and the Frame Manager is responsible for making frames | |
| 255 available to clients. There are several collections of frames maintained | |
| 256 by the Frame Manager. The most basic is a list of all of the frames starting | |
| 257 at the root frame. Clients generally do not want to incur the expense of | |
| 258 traversing all of the frames from the root to find the frame they are interested | |
| 259 in, so the Frame Manager provides some other mappings based on the needs of | |
| 260 the clients.<br> | |
| 261 <br> | |
| 262 The most crucial mapping is the Primary Frame Map. This collection provides | |
| 263 access to a frame that is designated as the primary frame for a piece of | |
| 264 content. When a frame is created for a piece of content, it may be the 'primary | |
| 265 frame' for that content element (content elements that require multiple | |
| 266 frames have primary and secondary frames; only the primary frame is mapped). | |
| 267 The Frame Manager is then instructed to store the mapping from a content | |
| 268 element to the primary frame. This mapping facilitates updates to frames | |
| 269 that result in changes to content (see <a href="#DHTML_interaction">discussion | |
| 270 above</a>).<br> | |
| 271 <br> | |
| 272 Another important mapping maintained by the Frame Manager is that of the | |
| 273 undisplayed content. When a content element is defined as having no display | |
| 274 (via the CSS property 'display:none') it is noted by a special entry in the | |
| 275 undisplayed map. This is important because no frame is generated for these | |
| 276 elements yet changes to their style values and to the content elements still | |
| 277 need to be handled by layout, in case their display state changes from 'none' | |
| 278 to something else. The Undisplayed Map keeps track of all content and style | |
| 279 data for elements that currently have no frames. (<font color="#990000">note: | |
| 280 the original architecture of the layout system included the creation of frames | |
| 281 for elements with no display. This changed somewhere along the line, but | |
| 282 there is no indication of why the change was made. Presumably it is more | |
| 283 time and space-efficient to prevent frame creation for elements with no display.)</font><br> | |
| 284 <br> | |
| 285 The Frame Manager also maintains a list of Forms and Form Controls, as <i>content | |
| 286 nodes</i>. This is presumably related to the fact that layout is responsible | |
| 287 for form submission, but this is a design flaw that is being corrected by | |
| 288 moving form submission into the content world. These collections of Forms | |
| 289 and Form Controls should be removed eventually.<br> | |
| 290 <br> | |
| 291 <h3>CSS Frame Constructor</h3> | |
| 292 The Frame Constructor is responsible for resolving style values for content | |
| 293 elements and creating the appropriate frames corresponding to that element. | |
| 294 In addition to managing the creation of frames, the Frame Constructor is | |
| 295 responsible for managing changes to the frames. Frame Construction is generally | |
| 296 achieved by the use of stateless methods, but in some cases there is the | |
| 297 need to provide context to frames created as children of a container. The | |
| 298 Frame Manager uses the Frame Constructor State class to manage the important | |
| 299 information about the container of a frame being created (<font | |
| 300 color="#990000">and lots of other state-stuff too - need to describe more | |
| 301 fully</font>).<br> | |
| 302 <h3>Frame</h3> | |
| 303 The Frame is the most fundamental layout object. The class nsFrame is the | |
| 304 base class for all frames, and it inherits from the base class nsIFrame (note: | |
| 305 nsIFrame is NOT an interface, it is an abstract base class. It was once an | |
| 306 interface but was changed to be a base class when the Style System was modified | |
| 307 - the name was not changed to reflect that it is not an interface). The Frame | |
| 308 provides generic functionality that can be used by subclasses but cannot | |
| 309 itself be instantiated.<br> | |
| 310 <br> | |
| 311 nsFrame:<br> | |
| 312 The Frame provides a mechanism to navigate to a parent frame as well as child | |
| 313 frames. All frames have a parent except for the root frame. The Frame is | |
| 314 able to provide a reference to its parent and to its children upon request. | |
| 315 The basic data that all frames maintain include: a rectangle describing the | |
| 316 dimensions of the frame, a pointer to the content that the frame is representing, | |
| 317 the style context representing all of the stylistic data corresponding to | |
| 318 the frame, a parent frame pointer, a sibling frame pointer, and a series | |
| 319 of state bits.<br> | |
| 320 <br> | |
| 321 Frames are chained primarily by the sibling links. Given a frame, one can | |
| 322 walk the sibling of that frame, and can also navigate back up to the parent | |
| 323 frame. Specializations of the frame also allow for the management of child | |
| 324 frames; this functionality is provided by the Container Frame.<br> | |
| 325 <br> | |
| 326 Container Frames:<br> | |
| 327 The Container Frame is a specialization of the base frame class that introduces | |
| 328 the ability to manage a list of child frames. All frames that need to manage | |
| 329 child frames (e.g. frames that are not themselves leaf frames) derive from | |
| 330 Container Frame.<br> | |
| 331 <br> | |
| 332 <br> | |
| 333 <br> | |
| 334 <h3>Block Frame<br> | |
| 335 </h3> | |
| 336 <h3>Reflow State</h3> | |
| 337 <h3>Reflow Metrics<br> | |
| 338 </h3> | |
| 339 <h3>Space Manager<br> | |
| 340 </h3> | |
| 341 <h3>StyleSet</h3> | |
| 342 <h3>StyleContext</h3> | |
| 343 <br> | |
| 344 <br> | |
| 345 <hr width="100%" size="2"><br> | |
| 346 <b>Document History:<br> | |
| 347 </b> | |
| 348 <ul> | |
| 349 <li>05/20/2002 - Marc Attinasi: created, wrote highest level introduction | |
| 350 to general layout concepts, links to relevant specs and existing documents.<br> | |
| 351 </li> | |
| 352 </ul> | |
| 353 </body> | |
| 354 </html> |
