1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/layout/doc/obsolete/layout.xml Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,279 @@
1.4 +<?xml version="1.0"?>
1.5 +<!-- This Source Code Form is subject to the terms of the Mozilla Public
1.6 + - License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + - file, You can obtain one at http://mozilla.org/MPL/2.0/. -->
1.8 +
1.9 +<?xml-stylesheet href="layout.css" type="text/css"?>
1.10 +<!DOCTYPE Documentation>
1.11 +
1.12 +<Documentation xmlns:html="http://www.w3.org/1999/xhtml"
1.13 + xmlns:xlink="http://www.w3.org/1999/xlink">
1.14 +
1.15 +<Title>Gecko Layout Engine</Title>
1.16 +<Author xlink:type="simple" xlink:show="new" xlink:href="mailto:troy@netscape.com">Troy Chevalier</Author>
1.17 +<UpdateDate>8 August 1999</UpdateDate>
1.18 +
1.19 +<SectionHeading>Overview</SectionHeading>
1.20 +<Body>Gecko is Mozilla's new layout engine. It is based on the HTML4, CSS1, XML 1.0,
1.21 +and DOM Internet standards, and it is built using a modular XPCOM-based
1.22 +architecture.</Body>
1.23 +
1.24 +<Body>When we talk about layout, we're referring to the formatting process that applies
1.25 +presentation styles to a source document. The formatting process is controlled
1.26 +by the style specification.</Body>
1.27 +
1.28 +<SectionHeading>Components</SectionHeading>
1.29 +<Body>Here are a list of components and terms that will be referenced by this document.</Body>
1.30 +
1.31 +<Components>
1.32 +<Term>Parser</Term>
1.33 +<Definition>Either the <A xlink:type="simple" xlink:show="replace" xlink:href="http://www.mozilla.org/newlayout/doc/parser.html">HTML</A>
1.34 +or XML parser. Processes the document and makes calls to the content sink.</Definition>
1.35 +
1.36 +<Term>Content sink</Term>
1.37 +<Definition>Called by the parser. Responsible for building the content model.</Definition>
1.38 +
1.39 +<Term><A xlink:type="simple" xlink:show="replace" xlink:href="http://www.mozilla.org/newlayout/doc/contentmodel.html">Content model</A></Term>
1.40 +<Definition>Consists of document object and a tree of content objects. Changes to the
1.41 +content model result in modifications of the frame model.</Definition>
1.42 +
1.43 +<Term>Frame model</Term>
1.44 +<Definition><A xlink:type="simple" xlink:show="replace" xlink:href="#Frames">Frames</A> are formatting
1.45 +objects. Each frame defines a particular set of formatting characteristics.</Definition>
1.46 +
1.47 +<Term><A xlink:type="simple" xlink:show="replace" xlink:href="#Reflow">Reflow</A></Term>
1.48 +<Definition>The formatting process. Reflow of the frame model defines the visual appearance
1.49 +of the formatted document.</Definition>
1.50 +
1.51 +<Term><A xlink:type="simple" xlink:show="replace" xlink:href="#FrameConstruction">Frame construction</A></Term>
1.52 +<Definition>Initial creation and updating of the frame model in response to changes to the
1.53 +content model and changes to the style data.</Definition>
1.54 +
1.55 +<Term><A xlink:type="simple" xlink:show="replace" xlink:href="http://www.mozilla.org/newlayout/doc/style.html">Style system</A></Term>
1.56 +<Definition>Provide the mapping and management of style data onto document content in a given
1.57 +presentation. Major components are style set, style sheets, style sheet and
1.58 +rules, style context, and style sheet loader.</Definition>
1.59 +
1.60 +<Term>Presentation shell</Term>
1.61 +<Definition>Controlling point for managing the presentation of a document.</Definition>
1.62 +
1.63 +<Term><A xlink:type="simple" xlink:show="replace" xlink:href="http://www.mozilla.org/newlayout/doc/viewsystem.html">View system</A></Term>
1.64 +<Definition>Consists of a view manager and view objects arranged in a tree hierarchy.
1.65 +Views support overlapped positioning, z-order sorting, and opacity levels.</Definition>
1.66 +</Components>
1.67 +
1.68 +<SectionHeading>Document Loading</SectionHeading>
1.69 +<Body>The basic flow of control is as follows: as the parser encounters tokens it notifies
1.70 +the content sink that a new node (or child node) is encountered. The content sink
1.71 +creates the appropriate type content object and inserts it into the content model.</Body>
1.72 +
1.73 +<Body>Whenever the content model changes the document's observers are notified. The presentation
1.74 +shell is one of the document observers. The presentation shell forwards the document
1.75 +change notification to the style set object</Body>
1.76 +
1.77 +<Body>The style set passes the notification to the frame construction code, the
1.78 +frame construction code creates new frames and inserts them into the frame model. The
1.79 +document is reflowed, and the formatted changes are displayed.
1.80 +</Body>
1.81 +
1.82 +<Body>
1.83 +The actual interfaces involved are:
1.84 +<Interfaces>
1.85 +<Interface>nsIDocument</Interface>
1.86 +<Interface>nsIDocumentObserver</Interface>
1.87 +<Interface>nsIPresShell</Interface>
1.88 +<Interface>nsIStyleSet</Interface>
1.89 +<Interface>nsIStyleFrameConstruction</Interface>
1.90 +<Interface>nsIFrame</Interface>
1.91 +</Interfaces>
1.92 +</Body>
1.93 +
1.94 +<Body>All of the interface files are located in the mozilla/layout/base/public
1.95 +directory.</Body>
1.96 +
1.97 +<SectionHeading>Object Lifetimes</SectionHeading>
1.98 +<Body>Gecko supports multiple views of the same document. This means you can print the
1.99 +same document that you're viewing on the screen, and there's only one content
1.100 +model. Because there's just a single content model, each of the content objects
1.101 +is referenced counted. The document holds a reference to the root content object,
1.102 +and each content node holds a reference to its child content nodes.</Body>
1.103 +
1.104 +<Body>Each view of the document has a separate presentation shell, style manager,
1.105 +style set, and frame hierarchy. The presentation shell is the controlling point for
1.106 +the presentation of a document, and it holds a reference to the document object.</Body>
1.107 +
1.108 +<Body>Frames and views are not referenced counted. The lifetime of the frame hierarchy
1.109 +is bounded by the lifetime of the presentation shell which owns the frames. The
1.110 +lifetime of the view hierarchy is bounded by the lifetime of the view manager
1.111 +that owns the views.</Body>
1.112 +
1.113 +<SectionHeading><html:a name="Frames">Frames</html:a></SectionHeading>
1.114 +<Body>Each frame defines a particular set of formatting characteristics. Frames have
1.115 +the opportunity to:
1.116 +<Characteristics>
1.117 +<Characteristic>reflow (format) their child frames</Characteristic>
1.118 +<Characteristic>render their appearance</Characteristic>
1.119 +<Characteristic>handle mouse and keyboard events</Characteristic>
1.120 +<Characteristic>display a cursor</Characteristic>
1.121 +<Characteristic>have an associated view object</Characteristic>
1.122 +</Characteristics>
1.123 +</Body>
1.124 +
1.125 +<Body>Frames can have multiple child lists, the default unnamed child list
1.126 +(referred to as the principal child list) and additional named child lists.
1.127 +There is an ordering of frames within a child list, but no ordering
1.128 +between frames in different child lists of the same parent frame.</Body>
1.129 +
1.130 +<Body>The principal child list contains the flowed children, and the additional
1.131 +child lists are for out-of-flow frames like floated elements and absolutely
1.132 +positioned elements.</Body>
1.133 +
1.134 +<Body>Child frames are linked together in a singly linked list. Each frame
1.135 +defines its own local coordinate space. Frame bounding rects are in twips,
1.136 +and the origin is relative to the upper-left corner of its parent frame.
1.137 +The bounding rect includes the content area, borders, and padding.</Body>
1.138 +
1.139 +<SectionHeading><html:a name="FrameConstruction">Frame Construction</html:a></SectionHeading>
1.140 +<Body>The frame construction process begins with a notification that content
1.141 +has been added or removed or that style has changed.</Body>
1.142 +
1.143 +<Body>The first step is to resolve style information for the content element.
1.144 +This process creates a style context that is stored in the frame (see
1.145 +nsIStyleContext).</Body>
1.146 +
1.147 +<Body>Once style is resolved construction rules are used to decide the type of
1.148 +frame to create. First we look at the element's tag and special case some
1.149 +things like IMG elements. If we don't create a frame that way, then we use
1.150 +the 'display' property to dictate what type of frame to create. Typically
1.151 +it's a block or inline frame.</Body>
1.152 +
1.153 +<Body>For a 'display' value of 'none' no frame is created. For elements that are
1.154 +out of the flow (for example, a floated element or an absolutely positioned
1.155 +element), a placeholder frame is also created. The placeholder frame is inserted
1.156 +into the flow exactly where the out-of-flow frame would have been inserted.
1.157 +The out-of-flow frame is then inserted as a child of its containing block in
1.158 +one of the additional child lists. Floated frames are inserted into the
1.159 +"Float-list" and absolutely positioned frames are inserted into the
1.160 +"Absolute-list".</Body>
1.161 +
1.162 +<SectionHeading>Frame Manager</SectionHeading>
1.163 +<Body>The frame manager is owned by the presentation shell and used by both the
1.164 +presentation shell and the frame construction code. It serves two main
1.165 +purposes:
1.166 +<Purposes>
1.167 +<Purpose>provides a service for mapping from content object to frame and from out-of-flow
1.168 +frame to placeholder frame</Purpose>
1.169 +<Purpose>coordinates structural modifications to the frame model</Purpose>
1.170 +</Purposes>
1.171 +</Body>
1.172 +
1.173 +<Body>In many places in the frame code we need to find the frame associated with
1.174 +a particular content object. In order to quickly implement this operation we
1.175 +maintain a mapping from content objects to frames. The frame construction adds
1.176 +and removes entries from the map as frames are created and destroyed.</Body>
1.177 +
1.178 +<Body>When creating new frames and removing existing frames, the frame construction
1.179 +code doesn't directly modify the frame hierarchy. Instead if informs the frame
1.180 +manager and has it coordinate the request. If the frame model lock is available,
1.181 +the change is processed immediately; otherwise, the request is queued and
1.182 +processed later.</Body>
1.183 +
1.184 +<Body>The frame manager also coordinates processing of replaced elements that can't
1.185 +be rendered (for example, an IMG or OBJECT element), and it allows client to
1.186 +register to be notified when a particular frame is being destroyed. This is
1.187 +needed because frames are not reference counted. It's used by the event manager
1.188 +and other clients to ensure that any outstanding references to the frame are
1.189 +cleaned up.</Body>
1.190 +
1.191 +<SectionHeading><html:a name="Reflow">Reflow</html:a> Process</SectionHeading>
1.192 +<Note>The fact that are two reflow interfaces reflects an early
1.193 +goal of having core layout and HTML specific layout. The core reflow process would
1.194 +be the same for all frames, and each class of formatting objects (for
1.195 +example, CSS and DSSSL) would have their own reflow additions.</Note>
1.196 +
1.197 +<Body>The reflow process is a top-down protocol where a frame is given some
1.198 +available space and asked to reflow its child frames and return a desired
1.199 +size.</Body>
1.200 +
1.201 +<Body>The reflow process is not part of the nsIFrame interface. The generic reflow
1.202 +interface is defined in the nsIFrameReflow interface, and the HTML/CSS specific
1.203 +reflow interface is defined in the nsIHTMLReflow interface.</Body>
1.204 +
1.205 +<Body>An important part of the reflow process is the calculation of the computed
1.206 +values for the CSS properties. This includes things like 'width', 'height',
1.207 +and 'margin', and involves calculation of the containing block width and height
1.208 +and percentage based values and properties whose value is inherited.</Body>
1.209 +
1.210 +<Body>This process is encapsulated in the HTML specific reflow state struct
1.211 +(struct nsHTMLReflowState) that is passed in as part of reflow. The reflow
1.212 +states are linked together with the reflow state for a child frame pointing
1.213 +to its parent frame's reflow state. This allows us to walk up the reflow state
1.214 +structures and calculate containing block width and height and percentage
1.215 +based values.</Body>
1.216 +
1.217 +<Body>In addition to the computed values for the CSS box model properties, the
1.218 +following items are also included:
1.219 +<Items>
1.220 +<Item>reflow reason that indicates why the frame is being reflowed</Item>
1.221 +<Item>a rendering context that can be used to measure text</Item>
1.222 +<Item>reflow command (only used for incremental reflow)</Item>
1.223 +<Item>space manager</Item>
1.224 +</Items>
1.225 +</Body>
1.226 +
1.227 +<Body>The most common reflow reasons are 'eReflowReason_Resize' (the viewport
1.228 +has changed size) and 'eReflowReason_Incremental' (processing of an incremental
1.229 +reflow command).</Body>
1.230 +
1.231 +<Body>Reflow commands (see nsHTMLReflowCommand in mozilla/layout/html/base/src) are used
1.232 +to kick off an incremental reflow. They're generated either by the style system
1.233 +(in response to a style change) or by a frame itself (for example, if a frame has
1.234 +dirty child frames that need to be reflowed it will generate a reflow command).</Body>
1.235 +
1.236 +<Body>Reflow commands are queued by the presentation shell and then dispatched. Reflow
1.237 +commands have a target frame, which is the frame for which the reflow command
1.238 +is destined. In the example above the target frame is the frame with dirty child
1.239 +frames that need to be reflowed. Reflow command processing follows a path from
1.240 +the root frame down to the target frame.</Body>
1.241 +
1.242 +<Body>The space manager (see nsISpaceManager in mozilla/layout/base/public) is used
1.243 +when flowing text around floated elements. It has an API for managing bands of
1.244 +unavailable space (space that is reserved for a floated element). Internally it
1.245 +organizes the band data similar to how a region data structure works.</Body>
1.246 +
1.247 +<SectionHeading>Frame Classes</SectionHeading>
1.248 +<Body>There are four main categories of frame classes, all of which are located
1.249 +in mozilla/layout/html/src:
1.250 +
1.251 +<Categories>
1.252 +<Category>core frame classes</Category>
1.253 +<Category>table frame classes</Category>
1.254 +<Category>form frame classes</Category>
1.255 +<Category>frameset frame classes</Category>
1.256 +</Categories>
1.257 +</Body>
1.258 +
1.259 +<Body><RunIn>The core frame classes</RunIn> implement the CSS viewport abstraction, scrolling,
1.260 +block and inline display of flowed elements, floats, and absolute positioning.</Body>
1.261 +
1.262 +<Body>For more information on block layout, click
1.263 +<A xlink:type="simple" xlink:show="replace" xlink:href="block.html">here</A>. For more information about
1.264 +line layout, click <A xlink:type="simple" xlink:show="replace" xlink:href="line-layout.html">here</A>.</Body>
1.265 +
1.266 +<Body><RunIn>The table frame classes</RunIn> correspond to the HTML4 table spec, and in addition
1.267 +to the table frame there are row group frames, row frames, column group frames,
1.268 +column frames, and cell frames. There is an "outer" table frame as well that's
1.269 +really an anonymous frame that contains the caption frame and the table frame
1.270 +itself.</Body>
1.271 +
1.272 +<Body>Table layout is determined in a 3-step process. In the first step, the table
1.273 +is flowed into an infinitely wide and tall space. This gives us the minimum and
1.274 +desired sizes for every cell in the table. In the second step, the table constraints
1.275 +are factored in and widths are assigned to every cell. In the third step, heights are
1.276 +assigned to every cell based on the computed width constraint. The results of the first
1.277 +step are cached and only need to be recomputed when content or constraints are changed.</Body>
1.278 +
1.279 +<SectionHeading>Event Manager</SectionHeading>
1.280 +<Body>To be written</Body>
1.281 +
1.282 +</Documentation>
