1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/layout/doc/Layout_Overview.html Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,354 @@
1.4 +<!-- This Source Code Form is subject to the terms of the Mozilla Public
1.5 + - License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + - file, You can obtain one at http://mozilla.org/MPL/2.0/. -->
1.7 +
1.8 +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
1.9 +<html>
1.10 +<head>
1.11 + <title>Layout Overview</title>
1.12 + <meta http-equiv="content-type"
1.13 + content="text/html; charset=ISO-8859-1">
1.14 +</head>
1.15 +<body>
1.16 +<h1>Layout System Overview</h1>
1.17 +<br>
1.18 +<h3>Layout's Job: Provide the Presentation</h3>
1.19 +Layout is primarily concerned with providing a presentation to an HTML or
1.20 +XML document. This presentation is typically formatted in accordance with
1.21 +the requirements of the <a href="http://www.w3.org/TR/REC-CSS1">CSS1</a>
1.22 +and <a href="http://www.w3.org/TR/REC-CSS2/">CSS2</a> specifications from
1.23 +the W3C. Presentation formatting is also required to provide compatibility
1.24 +with legacy browsers (Microsoft Internet Explorer and Netscape Navigator
1.25 +4.x). The decision about when to apply CSS-specified formatting and when
1.26 +to apply legacy formatting is controlled by the document's DOCTYPE specification.
1.27 +These layout modes are referred to as 'Standards' and 'NavQuirks' modes. (DOCTYPE
1.28 +and modes are explained in more detail <a
1.29 + href="http://www.mozilla.org/quality/help/bugzilla-helper.html">here</a>).<br>
1.30 +<br>
1.31 +The presentation generally is constrained by the width of the window in which
1.32 +the presentation is to be displayed, and a height that extends as far as
1.33 +necessary. This is referred to as the Galley Mode presentation, and is what
1.34 +one expects from a typical browser. Additionally, layout must support a paginated
1.35 +presentation, where the width of the presentation is constrained by the dimensions
1.36 +of the printed output (paper) and the height of each page is fixed. This
1.37 +paged presentation presents several challenges not present in the galley
1.38 +presentation, namely how to break up elements that are larger than a single
1.39 +page, and how to handle changes to page dimensions.<br>
1.40 +<br>
1.41 +The original design of the Layout system allowed for multiple, possibly different,
1.42 +presentations to be supported simultaneously from the same content model.
1.43 +In other words, the same HTML or XML document could be viewed as a normal
1.44 +galley presentation in a browser window, while simultaneously being presented
1.45 +in a paged presentation to a printer, or even an aural presentation to a
1.46 +speech-synthesizer. To date the only real use of this multiple presentation
1.47 +ability is seen in printing, where multiple presentations are managed, all
1.48 +connected to the same content model. (note: it is unclear if this is really
1.49 +a benefit - it may have been better to use a copy of the content model for
1.50 +each presentation, and to remove the complexity of managing separate presentations
1.51 +- analysis is needed here). The idea of supporting a non-visual presentation
1.52 +is interesting. Layout's support for aural presentations is undeveloped,
1.53 +though conceptually, it is possible and supported by the architecture.<br>
1.54 +<br>
1.55 +<h3>How Layout Does its Job: Frames and Reflow</h3>
1.56 +So, layout is concerned with providing a presentation, in galley or paged
1.57 +mode. Given a content model, how does the layout system actually create the
1.58 +presentation? Through the creation and management of frames. Frames are an
1.59 +encapsulation of a region on the screen, a region that contains geometry
1.60 +(size and location, stacking order). Generally frames correspond to the content
1.61 +elements, though there is often a one-to-many correspondence between content
1.62 +elements and frames. Layout creates frames for content based on either the
1.63 +specific HTML rules for an element or based on the CSS display type of the
1.64 +element. In the case of the HTML-specific elements, the frame types that
1.65 +correspond to the element are hard-coded, but in the more general case where
1.66 +the display type is needes, the layout system must determine that display
1.67 +type by using the Style System. A content element is passed to the Style
1.68 +System and a request is made to resolve the style for that element. This
1.69 +causes the Style System to apply all style rules that correspond to the element
1.70 +and results in a resolved Style Context - the style data specific to that
1.71 +element. The Layout module looks at the 'display' field of the style context
1.72 +to determine what kind of frame to create (block, inline, table, etc.). The
1.73 +style context is associated with the frame via a reference because it is
1.74 +needed for many other computations during the formatting of the frames.<br>
1.75 +<br>
1.76 +Once a frame is created for a content element, it must be formatted. We refer
1.77 +to this as 'laying out' the frame, or as 'reflowing' the frame. Each frame
1.78 +implements a Reflow method to compute its position and size, among other
1.79 +things. For more details on the Reflow mechanism, see the Reflow Overview
1.80 +document... The CSS formatting requirements present two distinct layout
1.81 +models: 1) the in-flow model, where the geometry of an element is influenced
1.82 +by the geometry of the elements that precede it, and 2) the positioned model,
1.83 +where the geometry of an element is not influenced by the geometry of the
1.84 +elements that precede it, or in any case, is influenced more locally. The
1.85 +in-flow cased is considered the 'normal' case, and corresponds to normal
1.86 +HTML formatting. The later case, called 'out of flow' puts the document author
1.87 +in control of the layout, and the author must specify the locations and sizes
1.88 +of all of the elements that are positioned. There is, of course, some complexity
1.89 +involved with managing these two models simultanelusly...<br>
1.90 +<br>
1.91 +So far the general flow of layout looks like this:<br>
1.92 +<br>
1.93 +1) Obtain a document's content model<br>
1.94 +2) Utilize the Style System to resolve the style of each element in the content
1.95 +model<br>
1.96 +3) Construct the frames that correspond to the content model, according to
1.97 +the resolved style data.<br>
1.98 +4) Perform the initial layout, or initial reflow, on the newly constructed
1.99 +frame.<br>
1.100 +<br>
1.101 +This is pretty straight-forward, but is complicated somewhat by the notion
1.102 +of <i>incrementalism</i>. One of the goals of the Layout system's design
1.103 +is to create parts of the presentation as they become available, rather than
1.104 +waiting for the entire document to be read, parsed, and then presented. This
1.105 +is a major benefit for large documents because the user does not have to wait
1.106 +for the 200th page of text to be read in before the first page can be displayed
1.107 +- they can start reading something right away. So really, this sequence of
1.108 +operations Resolve Style, Create Frame, Layout Frame, gets repeated many
1.109 +times as the content becomes available. In the normal in-flow case this is
1.110 +quite natural because the sequential addition of new content results in sequential
1.111 +addition of new frames, and because everything is in-flow, the new frames
1.112 +do not influence the geometry of the frames that have already been formatted.
1.113 +When out-of-flow frames are present this is a more difficult problem, however.
1.114 +Sometimes a content element comes in incrementally, and invalidates the formatting
1.115 +of some of the frames that precede it, frame that have already been formatted.
1.116 +In this case the Layout System has to detect that impact and reflow again
1.117 +the impacted frames. This is referred to as an <i>incremental reflow</i>.<br>
1.118 +<br>
1.119 +<a name="DHTML_interaction"></a>Another responsibility of layout is to manage
1.120 +dynamic changes to the content model, changes that occur after the document
1.121 +has been loaded and (possibly) presented. These dynamic changes are caused
1.122 +by manipulations of the content model via the <acronym
1.123 + title="Document Object Model">DOM<acronym></acronym></acronym> (generally
1.124 +through java script). When a content element is modified, added or removed,
1.125 +Layout is notified. If content elements have been inserted, new frames are
1.126 +created and formatted (and impacts to other frames are managed by performing
1.127 +further incremental reflows). If content is removed, the corresponding frames
1.128 +are destroyed (again, impacts to other elements are managed). If a content
1.129 +element is modified, layout must determine if the chage influences the formatting
1.130 +of that or other elements' presentations, and must then reformat, or re-reflow,
1.131 +the impacted elements. In all cases, the determination of the impact is critical
1.132 +to avoid either the problem of not updating impacted elements, thus presenting
1.133 +an invalid presentation, or updating too much of the presentation and thus
1.134 +doing too much work, potentially causing performance problems.<br>
1.135 +<br>
1.136 +One very special case of dynamic content manipulation is the HTML Editor.
1.137 +Layout is used to implement both a full-blown WYSIWYG HTML editor, and a single
1.138 +and multi-line text entry control. In both cases, the content is manipulated
1.139 +by the user (via the DOM) and the resulting visual impacts must be shown as
1.140 +quickly as possible, without disconcerting flicker or other artifacts that
1.141 +might bother the user. Consider a text entry field: the user types text into
1.142 +a form on the web. As the user types a new character it is inserted into
1.143 +the content model. This causes layout to be notified that a new piece of
1.144 +content has been entered, which causes Layout to create a new frame and format
1.145 +it. This must happen very fast, so the user's typing is not delayed. In the
1.146 +case of the WYSIWYG HTML editor, the user expects that the modifications
1.147 +they make to the document will apear immediately, not seconds later. This
1.148 +is especially critical when the user is typing into the document: it would
1.149 +be quite unusable if typing a character at the end of a document in the HTML
1.150 +editor caused the entire document to be reformated - it would be too slow,
1.151 +at least on low-end machines. Thus the HTML editor and text controls put
1.152 +considerable performance requirements on the layout system's handling of dynamic
1.153 +content manipulation.<br>
1.154 +<h3>The Fundamentals of Frames: Block and Line</h3>
1.155 +There are many types of frames that are designed to model various formatting
1.156 +requirements of different HTML and XML elements. CSS2 defines several (block,
1.157 +inline, list-item, marker, run-in, compact, and various table types) and
1.158 +the standard HTML form controls require their own special frame types to
1.159 +be formatted as expected. The most essential frame types are Block and Inline,
1.160 +and these correspond to the most important Layout concepts, the Block and
1.161 +Line.<br>
1.162 +<br>
1.163 +A block is a rectangular region that is composed of one or more lines. A
1.164 +line is a single row of text or other presentational elements. All layout
1.165 +happens in the context of a block, and all of the contents of a block are
1.166 +formatted into lines within that block. As the width of a block is changed,
1.167 +the contents of the lines must be reformatted. consider for example a large
1.168 +paragraph of text sitting in paragraph:<br>
1.169 +<br>
1.170 +<pre><p><br> We need documentation for users, web developers, and developers working
1.171 + on Mozilla. If you write your own code, document it. Much of the
1.172 + existing code <b>isn’t very well documented</b>. In the process of figuring
1.173 + things out, try and document your discoveries.
1.174 + If you’d like to contribute, let us know.<br></p></pre>
1.175 +There is one block that corresponds to the <p> element, and then a number
1.176 +of lines of text that correspond to the text. As the width of the block changes
1.177 +(due to the window being resized, for example) the length of the lines within
1.178 +it changes, and thus more or less text appears on each line. The block is
1.179 +responsible for managing the lines. Note that lines may contain only inline
1.180 +elements, whereas block may contain both inline elements and other blocks.<br>
1.181 +<h3>Other Layout Models: XUL</h3>
1.182 +In addition to managing CSS-defined formatting, the layout system provides
1.183 +a way to integrate other layout schemes into the presentation. Currently
1.184 +layout supports the formatting of XUL elements, which utilize a constraint-based
1.185 +layout language. The Box is introduced into the layout system's frame model
1.186 +via an adapter (BoxToBlockAdapter) that translates the normal layout model
1.187 +into the box formatting model. Conceptually, this could be used to introduce
1.188 +other layout systems, but it might be worth noting that there was no specific
1.189 +facility designed into the layout system to accommodate this. Layout deals
1.190 +with frames, but as long as the layout system being considered has no need
1.191 +to influence presentational elements from other layout systems, it can be
1.192 +adapted using a frame-based adapter, ala XUL.<br>
1.193 +<br>
1.194 +<h2>Core Classes</h2>
1.195 +At the highest level, the layout system is a group of classes that manages
1.196 +the presentation within a fixed width and either unlimited height (galley
1.197 +presentation) or discrete page heights (paged presentation). Digging just
1.198 +a tiny bit deeper into the system we find that the complexity (and interest)
1.199 +mushrooms very rapidly. The idea of formatting text and graphics to fit within
1.200 +a given screen area sounds simple, but the interaction of in-flow and out-of-flow
1.201 +elements, the considerations of incremental page rendering, and the performance
1.202 +concerns of dynamic content changes makes for a system that has a lot of
1.203 +work to do, and a lot of data to manage. Here are the high-level classes
1.204 +that make up the layout system. Of course this is a small percentage of the
1.205 +total clases in layout (see the detailed design documents for the details
1.206 +on all of the classes, in the context of their actual role).<br>
1.207 +<h3>Presentation Shell / Presentation Context</h3>
1.208 +Together the presentation shell and the presentation context provide the
1.209 +root of the current presentation. The original design provided for a single
1.210 +Presentation Shell to manage multiple Presentation Contexts, to allow a single
1.211 +shell to handle multiple presentations. It is unclear if this is really possible,
1.212 +however, and in general it is assumed that there is a one-to-one correspondence
1.213 +between a presentation shell and a presentation context. The two classes
1.214 +should probably be folded into one, or the distinction between them formalized
1.215 +and utilized in the code. The Presentation Shell currently owns a controlling
1.216 +reference to the Presentation Context. Further references to the Presentation
1.217 +Shell and Presentation Context will be made by using the term Presentation
1.218 +Shell.<br>
1.219 +<br>
1.220 +The Presentation Shell is the root of the presentation, and as such it owns
1.221 +and manges a lot of layout objects that are used to create and maintain a
1.222 +presentation (<font color="#990000">note that the DocumentViewer is the owner
1.223 +of the Presentation Shell, and in some cases the creator of the objects
1.224 +used by the Presentation Shell to manage the presentation. More details
1.225 +of the Document Viewer are needed here...</font>). The Presentation Shell,
1.226 +or PresShell, is first and foremost the owner of the formatting objects,
1.227 +the frames. Management of the frames is facilitated by the Frame Manager,
1.228 +an instance of which the PresShell owns. Additionally, the PresShell provides
1.229 +a specialized storage heap for frames, called an Arena, that is used to make
1.230 +allocation and deallocation of frames faster and less likely to fragment
1.231 +the global heap. <br>
1.232 +<br>
1.233 +The Presentation Shell also owns the root of the Style System, the Style
1.234 +Set. In many cases the Presentation Shell provides pass-through methods to
1.235 +the Style Set, and generally uses the Style Set to do style resolution and
1.236 +Style Sheet management.<br>
1.237 +<br>
1.238 +One of the critical aspects of the Presentation Shell is the handling of
1.239 +frame formatting, or reflow. The Presentation Shell owns and maintains a
1.240 +Reflow Queue where requests for reflow are held until it is time to perform
1.241 +a reflow, and then pulled out and executed.<br>
1.242 +<br>
1.243 +It is also important to see the Presentation Shell as an observer of many
1.244 +kinds of events in the system. For example, the Presentation Shell receives
1.245 +notifications of document load events, which are used to trigger updates
1.246 +to the formatting of the frames in some cases. The Presentation Shell also
1.247 +receives notifications about changes in cursor and focus states, whereby
1.248 +the selection and caret updates can be made visible.<br>
1.249 +<br>
1.250 +There are dozens of other data objects managed by the Presentation Shell
1.251 +and Presentation Context, all necessary for the internal implementation.
1.252 +These data members and their roles will be discussed in the Presentation
1.253 +Shell design documents. For this overview, the Frames, Style Set, and Reflow
1.254 +Queue are the most important high-level parts of the Presentation Shell.<br>
1.255 +<h3>Frame Manager</h3>
1.256 +The Frame Manager is used to, well, manage frames. Frames are basic formatting
1.257 +objects used in layout, and the Frame Manager is responsible for making frames
1.258 +available to clients. There are several collections of frames maintained
1.259 +by the Frame Manager. The most basic is a list of all of the frames starting
1.260 +at the root frame. Clients generally do not want to incur the expense of
1.261 +traversing all of the frames from the root to find the frame they are interested
1.262 +in, so the Frame Manager provides some other mappings based on the needs of
1.263 +the clients.<br>
1.264 +<br>
1.265 +The most crucial mapping is the Primary Frame Map. This collection provides
1.266 +access to a frame that is designated as the primary frame for a piece of
1.267 +content. When a frame is created for a piece of content, it may be the 'primary
1.268 +frame' for that content element (content elements that require multiple
1.269 +frames have primary and secondary frames; only the primary frame is mapped).
1.270 +The Frame Manager is then instructed to store the mapping from a content
1.271 +element to the primary frame. This mapping facilitates updates to frames
1.272 +that result in changes to content (see <a href="#DHTML_interaction">discussion
1.273 +above</a>).<br>
1.274 +<br>
1.275 +Another important mapping maintained by the Frame Manager is that of the
1.276 +undisplayed content. When a content element is defined as having no display
1.277 +(via the CSS property 'display:none') it is noted by a special entry in the
1.278 +undisplayed map. This is important because no frame is generated for these
1.279 +elements yet changes to their style values and to the content elements still
1.280 +need to be handled by layout, in case their display state changes from 'none'
1.281 +to something else. The Undisplayed Map keeps track of all content and style
1.282 +data for elements that currently have no frames. (<font color="#990000">note:
1.283 +the original architecture of the layout system included the creation of frames
1.284 +for elements with no display. This changed somewhere along the line, but
1.285 +there is no indication of why the change was made. Presumably it is more
1.286 +time and space-efficient to prevent frame creation for elements with no display.)</font><br>
1.287 +<br>
1.288 +The Frame Manager also maintains a list of Forms and Form Controls, as <i>content
1.289 +nodes</i>. This is presumably related to the fact that layout is responsible
1.290 +for form submission, but this is a design flaw that is being corrected by
1.291 +moving form submission into the content world. These collections of Forms
1.292 +and Form Controls should be removed eventually.<br>
1.293 +<br>
1.294 +<h3>CSS Frame Constructor</h3>
1.295 +The Frame Constructor is responsible for resolving style values for content
1.296 +elements and creating the appropriate frames corresponding to that element.
1.297 +In addition to managing the creation of frames, the Frame Constructor is
1.298 +responsible for managing changes to the frames. Frame Construction is generally
1.299 +achieved by the use of stateless methods, but in some cases there is the
1.300 +need to provide context to frames created as children of a container. The
1.301 +Frame Manager uses the Frame Constructor State class to manage the important
1.302 +information about the container of a frame being created (<font
1.303 + color="#990000">and lots of other state-stuff too - need to describe more
1.304 +fully</font>).<br>
1.305 +<h3>Frame</h3>
1.306 +The Frame is the most fundamental layout object. The class nsFrame is the
1.307 +base class for all frames, and it inherits from the base class nsIFrame (note:
1.308 +nsIFrame is NOT an interface, it is an abstract base class. It was once an
1.309 +interface but was changed to be a base class when the Style System was modified
1.310 +- the name was not changed to reflect that it is not an interface). The Frame
1.311 +provides generic functionality that can be used by subclasses but cannot
1.312 +itself be instantiated.<br>
1.313 +<br>
1.314 +nsFrame:<br>
1.315 +The Frame provides a mechanism to navigate to a parent frame as well as child
1.316 +frames. All frames have a parent except for the root frame. The Frame is
1.317 +able to provide a reference to its parent and to its children upon request.
1.318 +The basic data that all frames maintain include: a rectangle describing the
1.319 +dimensions of the frame, a pointer to the content that the frame is representing,
1.320 +the style context representing all of the stylistic data corresponding to
1.321 +the frame, a parent frame pointer, a sibling frame pointer, and a series
1.322 +of state bits.<br>
1.323 +<br>
1.324 +Frames are chained primarily by the sibling links. Given a frame, one can
1.325 +walk the sibling of that frame, and can also navigate back up to the parent
1.326 +frame. Specializations of the frame also allow for the management of child
1.327 +frames; this functionality is provided by the Container Frame.<br>
1.328 +<br>
1.329 +Container Frames:<br>
1.330 +The Container Frame is a specialization of the base frame class that introduces
1.331 +the ability to manage a list of child frames. All frames that need to manage
1.332 +child frames (e.g. frames that are not themselves leaf frames) derive from
1.333 +Container Frame.<br>
1.334 +<br>
1.335 +<br>
1.336 +<br>
1.337 +<h3>Block Frame<br>
1.338 +</h3>
1.339 +<h3>Reflow State</h3>
1.340 +<h3>Reflow Metrics<br>
1.341 +</h3>
1.342 +<h3>Space Manager<br>
1.343 +</h3>
1.344 +<h3>StyleSet</h3>
1.345 +<h3>StyleContext</h3>
1.346 +<br>
1.347 +<br>
1.348 +<hr width="100%" size="2"><br>
1.349 +<b>Document History:<br>
1.350 +</b>
1.351 +<ul>
1.352 + <li>05/20/2002 - Marc Attinasi: created, wrote highest level introduction
1.353 +to general layout concepts, links to relevant specs and existing documents.<br>
1.354 + </li>
1.355 +</ul>
1.356 +</body>
1.357 +</html>
