layout/doc/Layout_Overview.html@7e26c7da4463
layout/doc/Layout_Overview.html
Wed, 31 Dec 2014 06:55:50 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:55:50 +0100
- changeset 2
- 7e26c7da4463
- permissions
- -rw-r--r--
Added tag UPSTREAM_283F7C6 for changeset ca08bd8f51b2
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/. -->
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>
