The Tor Browser: layout/doc/Layout_Overview.html@97036ab72558 (annotated)

layout/doc/Layout_Overview.html@97036ab72558 (annotated)

layout/doc/Layout_Overview.html

Tue, 06 Jan 2015 21:39:09 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Tue, 06 Jan 2015 21:39:09 +0100
branch: TOR_BUG_9701
changeset 8: 97036ab72558
permissions: -rw-r--r--

Conditionally force memory storage according to privacy.thirdparty.isolate;
This solves Tor bug #9701, complying with disk avoidance documented in
https://www.torproject.org/projects/torbrowser/design/#disk-avoidance.

 <!-- This Source Code Form is subject to the terms of the Mozilla Public
    - License, v. 2.0. If a copy of the MPL was not distributed with this
    - file, You can obtain one at http://mozilla.org/MPL/2.0/. -->
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
 <html>
 <head>
   <title>Layout Overview</title>
   <meta http-equiv="content-type"
  content="text/html; charset=ISO-8859-1">
 </head>
 <body>
 <h1>Layout System Overview</h1>
 <br>
 <h3>Layout's Job: Provide the Presentation</h3>
 Layout is primarily concerned with providing a presentation to an HTML or
 XML document. This presentation is typically formatted in accordance with
 the requirements of the <a href="http://www.w3.org/TR/REC-CSS1">CSS1</a>
 and <a href="http://www.w3.org/TR/REC-CSS2/">CSS2</a> specifications from
 the W3C. Presentation formatting is also required to provide compatibility
 with legacy browsers (Microsoft Internet Explorer and Netscape Navigator
 .x). The decision about when to apply CSS-specified formatting and when
 to apply legacy formatting is controlled by the document's DOCTYPE specification.
 These layout modes are referred to as 'Standards' and 'NavQuirks' modes. (DOCTYPE
 and modes are explained in more detail <a
  href="http://www.mozilla.org/quality/help/bugzilla-helper.html">here</a>).<br>
 <br>
 The presentation generally is constrained by the width of the window in which
 the presentation is to be displayed, and a height that extends as far as
 necessary. This is referred to as the Galley Mode presentation, and is what
 one expects from a typical browser. Additionally, layout must support a paginated
 presentation, where the width of the presentation is constrained by the dimensions
 of the printed output (paper) and the height of each page is fixed. This
 paged presentation presents several challenges not present in the galley
 presentation, namely how to break up elements that are larger than a single
 page, and how to handle changes to page dimensions.<br>
 <br>
 The original design of the Layout system allowed for multiple, possibly different,
 presentations to be supported simultaneously from the same content model.
 In other words, the same HTML or XML document could be viewed as a normal
 galley presentation in a browser window, while simultaneously being presented
 in a paged presentation to a printer, or even an aural presentation to a
 speech-synthesizer. To date the only real use of this multiple presentation
 ability is seen in printing, where multiple presentations are managed, all
 connected to the same content model. (note: it is unclear if this is really
 a benefit - it may have been better to use a copy of the content model for
 each presentation, and to remove the complexity of managing separate presentations
 - analysis is needed here). The idea of supporting a non-visual presentation
 is interesting. Layout's support for aural presentations is undeveloped,
 though conceptually, it is possible and supported by the architecture.<br>
 <br>
 <h3>How Layout Does its Job: Frames and Reflow</h3>
 So, layout is concerned with providing a presentation, in galley or paged
 mode. Given a content model, how does the layout system actually create the
 presentation? Through the creation and management of frames. Frames are an
 encapsulation of a region on the screen, a region that contains geometry
 (size and location, stacking order). Generally frames correspond to the content
 elements, though there is often a one-to-many correspondence between content
 elements and frames. Layout creates frames for content based on either the
 specific HTML rules for an element or based on the CSS display type of the
 element. In the case of the HTML-specific elements, the frame types that
 correspond to the element are hard-coded, but in the more general case where
 the display type is needes, the layout system must determine that display
 type by using the Style System. A content element is passed to the Style
 System and a request is made to resolve the style for that element. This
 causes the Style System to apply all style rules that correspond to the element
 and results in a resolved Style Context - the style data specific to that
 element. The Layout module looks at the 'display' field of the style context
 to determine what kind of frame to create (block, inline, table, etc.). The
 style context is associated with the frame via a reference because it is
 needed for many other computations during the formatting of the frames.<br>
 <br>
 Once a frame is created for a content element, it must be formatted. We refer
 to this as 'laying out' the frame, or as 'reflowing' the frame. Each frame
 implements a Reflow method to compute its position and size, among other
 things. For more details on the Reflow mechanism, see the Reflow Overview
 document... &nbsp;The CSS formatting requirements present two distinct layout
 models: 1) the in-flow model, where the geometry of an element is influenced
 by the geometry of the elements that precede it, and 2) the positioned model,
 where the geometry of an element is not influenced by the geometry of the
 elements that precede it, or in any case, is influenced more locally. The
 in-flow cased is considered the 'normal' case, and corresponds to normal
 HTML formatting. The later case, called 'out of flow' puts the document author
 in control of the layout, and the author must specify the locations and sizes
 of all of the elements that are positioned. There is, of course, some complexity
 involved with managing these two models simultanelusly...<br>
 <br>
 So far the general flow of layout looks like this:<br>
 <br>
 ) Obtain a document's content model<br>
 ) Utilize the Style System to resolve the style of each element in the content
 model<br>
 ) Construct the frames that correspond to the content model, according to
 the resolved style data.<br>
 ) Perform the initial layout, or initial reflow, on the newly constructed
 frame.<br>
 <br>
 This is pretty straight-forward, but is complicated somewhat by the notion
 of <i>incrementalism</i>. One of the goals of the Layout system's design
 is to create parts of the presentation as they become available, rather than
 waiting for the entire document to be read, parsed, and then presented. This
 is a major benefit for large documents because the user does not have to wait
 for the 200th page of text to be read in before the first page can be displayed
 - they can start reading something right away. So really, this sequence of
 operations Resolve Style, Create Frame, Layout Frame, gets repeated many
 times as the content becomes available. In the normal in-flow case this is
 quite natural because the sequential addition of new content results in sequential
 addition of new frames, and because everything is in-flow, the new frames
 do not influence the geometry of the frames that have already been formatted.
 When out-of-flow frames are present this is a more difficult problem, however.
 Sometimes a content element comes in incrementally, and invalidates the formatting
 of some of the frames that precede it, frame that have already been formatted.
 In this case the Layout System has to detect that impact and reflow again
 the impacted frames. This is referred to as an <i>incremental reflow</i>.<br>
 <br>
 <a name="DHTML_interaction"></a>Another responsibility of layout is to manage
 dynamic changes to the content model, changes that occur after the document
 has been loaded and (possibly) presented. These dynamic changes are caused
 by manipulations of the content model via the&nbsp;<acronym
  title="Document Object Model">DOM<acronym></acronym></acronym> (generally
 through java script). When a content element is modified, added or removed,
 Layout is notified. If content elements have been inserted, new frames are
 created and formatted (and impacts to other frames are managed by performing
 further incremental reflows). If content is removed, the corresponding frames
 are destroyed (again, impacts to other elements are managed). If a content
 element is modified, layout must determine if the chage influences the formatting
 of that or other elements' presentations, and must then reformat, or re-reflow,
 the impacted elements. In all cases, the determination of the impact is critical
 to avoid either the problem of not updating impacted elements, thus presenting
 an invalid presentation, or updating too much of the presentation and thus
 doing too much work, potentially causing performance problems.<br>
 <br>
 One very special case of dynamic content manipulation is the HTML Editor.
 Layout is used to implement both a full-blown WYSIWYG HTML editor, and a single
 and multi-line text entry control. In both cases, the content is manipulated
 by the user (via the DOM) and the resulting visual impacts must be shown as
 quickly as possible, without disconcerting flicker or other artifacts that
 might bother the user. Consider a text entry field: the user types text into
 a form on the web. As the user types a new character it is inserted into
 the content model. This causes layout to be notified that a new piece of
 content has been entered, which causes Layout to create a new frame and format
 it. This must happen very fast, so the user's typing is not delayed. In the
 case of the WYSIWYG HTML editor, the user expects that the modifications
 they make to the document will apear immediately, not seconds later. This
 is especially critical when the user is typing into the document: it would
 be quite unusable if typing a character at the end of a document in the HTML
 editor caused the entire document to be reformated - it would be too slow,
 at least on low-end machines. Thus the HTML editor and text controls put
 considerable performance requirements on the layout system's handling of dynamic
 content manipulation.<br>
 <h3>The Fundamentals of Frames: Block and Line</h3>
 There are many types of frames that are designed to model various formatting
 requirements of different HTML and XML elements. CSS2 defines several (block,
 inline, list-item, marker, run-in, compact, and various table types) and
 the standard HTML form controls require their own special frame types to
 be formatted as expected. The most essential frame types are Block and Inline,
 and these correspond to the most important Layout concepts, the Block and
 Line.<br>
 <br>
 A block is a rectangular region that is composed of one or more lines. A
 line is a single row of text or other presentational elements. All layout
 happens in the context of a block, and all of the contents of a block are
 formatted into lines within that block. As the width of a block is changed,
 the contents of the lines must be reformatted. consider for example a large
 paragraph of text sitting in paragraph:<br>
 <br>
 <pre>&lt;p&gt;<br> We need documentation for users, web developers, and developers working
  on Mozilla. If you write your own code, document it. Much of the
  existing code &lt;b&gt;isn&#8217;t very well documented&lt;/b&gt;. In the process of figuring
  things out, try and document your discoveries.
  If you&#8217;d like to contribute, let us know.<br>&lt;/p&gt;</pre>
 There is one block that corresponds to the &lt;p&gt; element, and then a number
 of lines of text that correspond to the text. As the width of the block changes
 (due to the window being resized, for example) the length of the lines within
 it changes, and thus more or less text appears on each line. The block is
 responsible for managing the lines. Note that lines may contain only inline
 elements, whereas block may contain both inline elements and other blocks.<br>
 <h3>Other Layout Models: XUL</h3>
 In addition to managing CSS-defined formatting, the layout system provides
 a way to integrate other layout schemes into the presentation. Currently
 layout supports the formatting of XUL elements, which utilize a constraint-based
 layout language. The Box is introduced into the layout system's frame model
 via an adapter (BoxToBlockAdapter) that translates the normal layout model
 into the box formatting model. Conceptually, this could be used to introduce
 other layout systems, but it might be worth noting that there was no specific
 facility designed into the layout system to accommodate this. Layout deals
 with frames, but as long as the layout system being considered has no need
 to influence presentational elements from other layout systems, it can be
 adapted using a frame-based adapter, ala XUL.<br>
 <br>
 <h2>Core Classes</h2>
 At the highest level, the layout system is a group of classes that manages
 the presentation within a fixed width and either unlimited height (galley
 presentation) or discrete page heights (paged presentation). Digging just
 a tiny bit deeper into the system we find that the complexity (and interest)
 mushrooms very rapidly. The idea of formatting text and graphics to fit within
 a given screen area sounds simple, but the interaction of in-flow and out-of-flow
 elements, the considerations of incremental page rendering, and the performance
 concerns of dynamic content changes makes for a system that has a lot of
 work to do, and a lot of data to manage. Here are the high-level classes
 that make up the layout system. Of course this is a small percentage of the
 total clases in layout (see the detailed design documents for the details
 on all of the classes, in the context of their actual role).<br>
 <h3>Presentation Shell / Presentation Context</h3>
 Together the presentation shell and the presentation context provide the
 root of the current presentation. The original design provided for a single
 Presentation Shell to manage multiple Presentation Contexts, to allow a single
 shell to handle multiple presentations. It is unclear if this is really possible,
 however, and in general it is assumed that there is a one-to-one correspondence
 between a presentation shell and a presentation context. The two classes
 should probably be folded into one, or the distinction between them formalized
 and utilized in the code. The Presentation Shell currently owns a controlling
 reference to the Presentation Context. Further references to the Presentation
 Shell and Presentation Context will be made by using the term Presentation
 Shell.<br>
 <br>
 The Presentation Shell is the root of the presentation, and as such it owns
 and manges a lot of layout objects that are used to create and maintain a
 presentation (<font color="#990000">note that the DocumentViewer is the owner
 of the Presentation Shell, and in some cases the creator of the objects
 used by the Presentation Shell to manage the presentation. More details
 of the Document Viewer are needed here...</font>). The Presentation Shell,
 or PresShell, is first and foremost the owner of the formatting objects,
 the frames. Management of the frames is facilitated by the Frame Manager,
 an instance of which the PresShell owns. Additionally, the PresShell provides
 a specialized storage heap for frames, called an Arena, that is used to make
 allocation and deallocation of frames faster and less likely to fragment
 the global heap. <br>
 <br>
 The Presentation Shell also owns the root of the Style System, the Style
 Set. In many cases the Presentation Shell provides pass-through methods to
 the Style Set, and generally uses the Style Set to do style resolution and
 Style Sheet management.<br>
 <br>
 One of the critical aspects of the Presentation Shell is the handling of
 frame formatting, or reflow. The Presentation Shell owns and maintains a
 Reflow Queue where requests for reflow are held until it is time to perform
 a reflow, and then pulled out and executed.<br>
 <br>
 It is also important to see the Presentation Shell as an observer of many
 kinds of events in the system. For example, the Presentation Shell receives
 notifications of document load events, which are used to trigger updates
 to the formatting of the frames in some cases. The Presentation Shell also
 receives notifications about changes in cursor and focus states, whereby
 the selection and caret updates can be made visible.<br>
 <br>
 There are dozens of other data objects managed by the Presentation Shell
 and Presentation Context, all necessary for the internal implementation.
 These data members and their roles will be discussed in the Presentation
 Shell design documents. For this overview, the Frames, Style Set, and Reflow
 Queue are the most important high-level parts of the Presentation Shell.<br>
 <h3>Frame Manager</h3>
 The Frame Manager is used to, well, manage frames. Frames are basic formatting
 objects used in layout, and the Frame Manager is responsible for making frames
 available to clients. There are several collections of frames maintained
 by the Frame Manager. The most basic is a list of all of the frames starting
 at the root frame. Clients generally do not want to incur the expense of
 traversing all of the frames from the root to find the frame they are interested
 in, so the Frame Manager provides some other mappings based on the needs of
 the clients.<br>
 <br>
 The most crucial mapping is the Primary Frame Map. This collection provides
 access to a frame that is designated as the primary frame for a piece of
 content. When a frame is created for a piece of content, it may be the 'primary
 frame' for that content element (content elements that require multiple
 frames have primary and secondary frames; only the primary frame is mapped).
 The Frame Manager is then instructed to store the mapping from a content
 element to the primary frame. This mapping facilitates updates to frames
 that result in changes to content (see <a href="#DHTML_interaction">discussion
 above</a>).<br>
 <br>
 Another important mapping maintained by the Frame Manager is that of the
 undisplayed content. When a content element is defined as having no display
 (via the CSS property 'display:none') it is noted by a special entry in the
 undisplayed map. This is important because no frame is generated for these
 elements yet changes to their style values and to the content elements still
 need to be handled by layout, in case their display state changes from 'none'
 to something else. The Undisplayed Map keeps track of all content and style
 data for elements that currently have no frames. (<font color="#990000">note:
 the original architecture of the layout system included the creation of frames
 for elements with no display. This changed somewhere along the line, but
 there is no indication of why the change was made. Presumably it is more
 time and space-efficient to prevent frame creation for elements with no display.)</font><br>
 <br>
 The Frame Manager also maintains a list of Forms and Form Controls, as <i>content
 nodes</i>. This is presumably related to the fact that layout is responsible
 for form submission, but this is a design flaw that is being corrected by
 moving form submission into the content world. These collections of Forms
 and Form Controls should be removed eventually.<br>
 <br>
 <h3>CSS Frame Constructor</h3>
 The Frame Constructor is responsible for resolving style values for content
 elements and creating the appropriate frames corresponding to that element.
 In addition to managing the creation of frames, the Frame Constructor is
 responsible for managing changes to the frames. Frame Construction is generally
 achieved by the use of stateless methods, but in some cases there is the
 need to provide context to frames created as children of a container. The
 Frame Manager uses the Frame Constructor State class to manage the important
 information about the container of a frame being created (<font
  color="#990000">and lots of other state-stuff too - need to describe more
 fully</font>).<br>
 <h3>Frame</h3>
 The Frame is the most fundamental layout object. The class nsFrame is the
 base class for all frames, and it inherits from the base class nsIFrame (note:
 nsIFrame is NOT an interface, it is an abstract base class. It was once an
 interface but was changed to be a base class when the Style System was modified
 - the name was not changed to reflect that it is not an interface). The Frame
 provides generic functionality that can be used by subclasses but cannot
 itself be instantiated.<br>
 <br>
 nsFrame:<br>
 The Frame provides a mechanism to navigate to a parent frame as well as child
 frames. All frames have a parent except for the root frame. The Frame is
 able to provide a reference to its parent and to its children upon request.
 The basic data that all frames maintain include: a rectangle describing the
 dimensions of the frame, a pointer to the content that the frame is representing,
 the style context representing all of the stylistic data corresponding to
 the frame, a parent frame pointer, a sibling frame pointer, and a series
 of state bits.<br>
 <br>
 Frames are chained primarily by the sibling links. Given a frame, one can
 walk the sibling of that frame, and can also navigate back up to the parent
 frame. Specializations of the frame also allow for the management of child
 frames; this functionality is provided by the Container Frame.<br>
 <br>
 Container Frames:<br>
 The Container Frame is a specialization of the base frame class that introduces
 the ability to manage a list of child frames. All frames that need to manage
 child frames (e.g. frames that are not themselves leaf frames) derive from
 Container Frame.<br>
 <br>
 <br>
 <br>
 <h3>Block Frame<br>
 </h3>
 <h3>Reflow State</h3>
 <h3>Reflow Metrics<br>
 </h3>
 <h3>Space Manager<br>
 </h3>
 <h3>StyleSet</h3>
 <h3>StyleContext</h3>
 <br>
 <br>
 <hr width="100%" size="2"><br>
 <b>Document History:<br>
 </b>
 <ul>
   <li>05/20/2002 - Marc Attinasi: &nbsp;created, wrote highest level introduction
 to general layout concepts, links to relevant specs and existing documents.<br>
   </li>
 </ul>
 </body>
 </html>

The Tor Browser / annotate

layout/doc/Layout_Overview.html@97036ab72558 (annotated)

layout/doc/Layout_Overview.html