layout/doc/obsolete/layout.xml@7e26c7da4463
layout/doc/obsolete/layout.xml
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 <?xml version="1.0"?>
2 <!-- This Source Code Form is subject to the terms of the Mozilla Public
3 - License, v. 2.0. If a copy of the MPL was not distributed with this
4 - file, You can obtain one at http://mozilla.org/MPL/2.0/. -->
6 <?xml-stylesheet href="layout.css" type="text/css"?>
7 <!DOCTYPE Documentation>
9 <Documentation xmlns:html="http://www.w3.org/1999/xhtml"
10 xmlns:xlink="http://www.w3.org/1999/xlink">
12 <Title>Gecko Layout Engine</Title>
13 <Author xlink:type="simple" xlink:show="new" xlink:href="mailto:troy@netscape.com">Troy Chevalier</Author>
14 <UpdateDate>8 August 1999</UpdateDate>
16 <SectionHeading>Overview</SectionHeading>
17 <Body>Gecko is Mozilla's new layout engine. It is based on the HTML4, CSS1, XML 1.0,
18 and DOM Internet standards, and it is built using a modular XPCOM-based
19 architecture.</Body>
21 <Body>When we talk about layout, we're referring to the formatting process that applies
22 presentation styles to a source document. The formatting process is controlled
23 by the style specification.</Body>
25 <SectionHeading>Components</SectionHeading>
26 <Body>Here are a list of components and terms that will be referenced by this document.</Body>
28 <Components>
29 <Term>Parser</Term>
30 <Definition>Either the <A xlink:type="simple" xlink:show="replace" xlink:href="http://www.mozilla.org/newlayout/doc/parser.html">HTML</A>
31 or XML parser. Processes the document and makes calls to the content sink.</Definition>
33 <Term>Content sink</Term>
34 <Definition>Called by the parser. Responsible for building the content model.</Definition>
36 <Term><A xlink:type="simple" xlink:show="replace" xlink:href="http://www.mozilla.org/newlayout/doc/contentmodel.html">Content model</A></Term>
37 <Definition>Consists of document object and a tree of content objects. Changes to the
38 content model result in modifications of the frame model.</Definition>
40 <Term>Frame model</Term>
41 <Definition><A xlink:type="simple" xlink:show="replace" xlink:href="#Frames">Frames</A> are formatting
42 objects. Each frame defines a particular set of formatting characteristics.</Definition>
44 <Term><A xlink:type="simple" xlink:show="replace" xlink:href="#Reflow">Reflow</A></Term>
45 <Definition>The formatting process. Reflow of the frame model defines the visual appearance
46 of the formatted document.</Definition>
48 <Term><A xlink:type="simple" xlink:show="replace" xlink:href="#FrameConstruction">Frame construction</A></Term>
49 <Definition>Initial creation and updating of the frame model in response to changes to the
50 content model and changes to the style data.</Definition>
52 <Term><A xlink:type="simple" xlink:show="replace" xlink:href="http://www.mozilla.org/newlayout/doc/style.html">Style system</A></Term>
53 <Definition>Provide the mapping and management of style data onto document content in a given
54 presentation. Major components are style set, style sheets, style sheet and
55 rules, style context, and style sheet loader.</Definition>
57 <Term>Presentation shell</Term>
58 <Definition>Controlling point for managing the presentation of a document.</Definition>
60 <Term><A xlink:type="simple" xlink:show="replace" xlink:href="http://www.mozilla.org/newlayout/doc/viewsystem.html">View system</A></Term>
61 <Definition>Consists of a view manager and view objects arranged in a tree hierarchy.
62 Views support overlapped positioning, z-order sorting, and opacity levels.</Definition>
63 </Components>
65 <SectionHeading>Document Loading</SectionHeading>
66 <Body>The basic flow of control is as follows: as the parser encounters tokens it notifies
67 the content sink that a new node (or child node) is encountered. The content sink
68 creates the appropriate type content object and inserts it into the content model.</Body>
70 <Body>Whenever the content model changes the document's observers are notified. The presentation
71 shell is one of the document observers. The presentation shell forwards the document
72 change notification to the style set object</Body>
74 <Body>The style set passes the notification to the frame construction code, the
75 frame construction code creates new frames and inserts them into the frame model. The
76 document is reflowed, and the formatted changes are displayed.
77 </Body>
79 <Body>
80 The actual interfaces involved are:
81 <Interfaces>
82 <Interface>nsIDocument</Interface>
83 <Interface>nsIDocumentObserver</Interface>
84 <Interface>nsIPresShell</Interface>
85 <Interface>nsIStyleSet</Interface>
86 <Interface>nsIStyleFrameConstruction</Interface>
87 <Interface>nsIFrame</Interface>
88 </Interfaces>
89 </Body>
91 <Body>All of the interface files are located in the mozilla/layout/base/public
92 directory.</Body>
94 <SectionHeading>Object Lifetimes</SectionHeading>
95 <Body>Gecko supports multiple views of the same document. This means you can print the
96 same document that you're viewing on the screen, and there's only one content
97 model. Because there's just a single content model, each of the content objects
98 is referenced counted. The document holds a reference to the root content object,
99 and each content node holds a reference to its child content nodes.</Body>
101 <Body>Each view of the document has a separate presentation shell, style manager,
102 style set, and frame hierarchy. The presentation shell is the controlling point for
103 the presentation of a document, and it holds a reference to the document object.</Body>
105 <Body>Frames and views are not referenced counted. The lifetime of the frame hierarchy
106 is bounded by the lifetime of the presentation shell which owns the frames. The
107 lifetime of the view hierarchy is bounded by the lifetime of the view manager
108 that owns the views.</Body>
110 <SectionHeading><html:a name="Frames">Frames</html:a></SectionHeading>
111 <Body>Each frame defines a particular set of formatting characteristics. Frames have
112 the opportunity to:
113 <Characteristics>
114 <Characteristic>reflow (format) their child frames</Characteristic>
115 <Characteristic>render their appearance</Characteristic>
116 <Characteristic>handle mouse and keyboard events</Characteristic>
117 <Characteristic>display a cursor</Characteristic>
118 <Characteristic>have an associated view object</Characteristic>
119 </Characteristics>
120 </Body>
122 <Body>Frames can have multiple child lists, the default unnamed child list
123 (referred to as the principal child list) and additional named child lists.
124 There is an ordering of frames within a child list, but no ordering
125 between frames in different child lists of the same parent frame.</Body>
127 <Body>The principal child list contains the flowed children, and the additional
128 child lists are for out-of-flow frames like floated elements and absolutely
129 positioned elements.</Body>
131 <Body>Child frames are linked together in a singly linked list. Each frame
132 defines its own local coordinate space. Frame bounding rects are in twips,
133 and the origin is relative to the upper-left corner of its parent frame.
134 The bounding rect includes the content area, borders, and padding.</Body>
136 <SectionHeading><html:a name="FrameConstruction">Frame Construction</html:a></SectionHeading>
137 <Body>The frame construction process begins with a notification that content
138 has been added or removed or that style has changed.</Body>
140 <Body>The first step is to resolve style information for the content element.
141 This process creates a style context that is stored in the frame (see
142 nsIStyleContext).</Body>
144 <Body>Once style is resolved construction rules are used to decide the type of
145 frame to create. First we look at the element's tag and special case some
146 things like IMG elements. If we don't create a frame that way, then we use
147 the 'display' property to dictate what type of frame to create. Typically
148 it's a block or inline frame.</Body>
150 <Body>For a 'display' value of 'none' no frame is created. For elements that are
151 out of the flow (for example, a floated element or an absolutely positioned
152 element), a placeholder frame is also created. The placeholder frame is inserted
153 into the flow exactly where the out-of-flow frame would have been inserted.
154 The out-of-flow frame is then inserted as a child of its containing block in
155 one of the additional child lists. Floated frames are inserted into the
156 "Float-list" and absolutely positioned frames are inserted into the
157 "Absolute-list".</Body>
159 <SectionHeading>Frame Manager</SectionHeading>
160 <Body>The frame manager is owned by the presentation shell and used by both the
161 presentation shell and the frame construction code. It serves two main
162 purposes:
163 <Purposes>
164 <Purpose>provides a service for mapping from content object to frame and from out-of-flow
165 frame to placeholder frame</Purpose>
166 <Purpose>coordinates structural modifications to the frame model</Purpose>
167 </Purposes>
168 </Body>
170 <Body>In many places in the frame code we need to find the frame associated with
171 a particular content object. In order to quickly implement this operation we
172 maintain a mapping from content objects to frames. The frame construction adds
173 and removes entries from the map as frames are created and destroyed.</Body>
175 <Body>When creating new frames and removing existing frames, the frame construction
176 code doesn't directly modify the frame hierarchy. Instead if informs the frame
177 manager and has it coordinate the request. If the frame model lock is available,
178 the change is processed immediately; otherwise, the request is queued and
179 processed later.</Body>
181 <Body>The frame manager also coordinates processing of replaced elements that can't
182 be rendered (for example, an IMG or OBJECT element), and it allows client to
183 register to be notified when a particular frame is being destroyed. This is
184 needed because frames are not reference counted. It's used by the event manager
185 and other clients to ensure that any outstanding references to the frame are
186 cleaned up.</Body>
188 <SectionHeading><html:a name="Reflow">Reflow</html:a> Process</SectionHeading>
189 <Note>The fact that are two reflow interfaces reflects an early
190 goal of having core layout and HTML specific layout. The core reflow process would
191 be the same for all frames, and each class of formatting objects (for
192 example, CSS and DSSSL) would have their own reflow additions.</Note>
194 <Body>The reflow process is a top-down protocol where a frame is given some
195 available space and asked to reflow its child frames and return a desired
196 size.</Body>
198 <Body>The reflow process is not part of the nsIFrame interface. The generic reflow
199 interface is defined in the nsIFrameReflow interface, and the HTML/CSS specific
200 reflow interface is defined in the nsIHTMLReflow interface.</Body>
202 <Body>An important part of the reflow process is the calculation of the computed
203 values for the CSS properties. This includes things like 'width', 'height',
204 and 'margin', and involves calculation of the containing block width and height
205 and percentage based values and properties whose value is inherited.</Body>
207 <Body>This process is encapsulated in the HTML specific reflow state struct
208 (struct nsHTMLReflowState) that is passed in as part of reflow. The reflow
209 states are linked together with the reflow state for a child frame pointing
210 to its parent frame's reflow state. This allows us to walk up the reflow state
211 structures and calculate containing block width and height and percentage
212 based values.</Body>
214 <Body>In addition to the computed values for the CSS box model properties, the
215 following items are also included:
216 <Items>
217 <Item>reflow reason that indicates why the frame is being reflowed</Item>
218 <Item>a rendering context that can be used to measure text</Item>
219 <Item>reflow command (only used for incremental reflow)</Item>
220 <Item>space manager</Item>
221 </Items>
222 </Body>
224 <Body>The most common reflow reasons are 'eReflowReason_Resize' (the viewport
225 has changed size) and 'eReflowReason_Incremental' (processing of an incremental
226 reflow command).</Body>
228 <Body>Reflow commands (see nsHTMLReflowCommand in mozilla/layout/html/base/src) are used
229 to kick off an incremental reflow. They're generated either by the style system
230 (in response to a style change) or by a frame itself (for example, if a frame has
231 dirty child frames that need to be reflowed it will generate a reflow command).</Body>
233 <Body>Reflow commands are queued by the presentation shell and then dispatched. Reflow
234 commands have a target frame, which is the frame for which the reflow command
235 is destined. In the example above the target frame is the frame with dirty child
236 frames that need to be reflowed. Reflow command processing follows a path from
237 the root frame down to the target frame.</Body>
239 <Body>The space manager (see nsISpaceManager in mozilla/layout/base/public) is used
240 when flowing text around floated elements. It has an API for managing bands of
241 unavailable space (space that is reserved for a floated element). Internally it
242 organizes the band data similar to how a region data structure works.</Body>
244 <SectionHeading>Frame Classes</SectionHeading>
245 <Body>There are four main categories of frame classes, all of which are located
246 in mozilla/layout/html/src:
248 <Categories>
249 <Category>core frame classes</Category>
250 <Category>table frame classes</Category>
251 <Category>form frame classes</Category>
252 <Category>frameset frame classes</Category>
253 </Categories>
254 </Body>
256 <Body><RunIn>The core frame classes</RunIn> implement the CSS viewport abstraction, scrolling,
257 block and inline display of flowed elements, floats, and absolute positioning.</Body>
259 <Body>For more information on block layout, click
260 <A xlink:type="simple" xlink:show="replace" xlink:href="block.html">here</A>. For more information about
261 line layout, click <A xlink:type="simple" xlink:show="replace" xlink:href="line-layout.html">here</A>.</Body>
263 <Body><RunIn>The table frame classes</RunIn> correspond to the HTML4 table spec, and in addition
264 to the table frame there are row group frames, row frames, column group frames,
265 column frames, and cell frames. There is an "outer" table frame as well that's
266 really an anonymous frame that contains the caption frame and the table frame
267 itself.</Body>
269 <Body>Table layout is determined in a 3-step process. In the first step, the table
270 is flowed into an infinitely wide and tall space. This gives us the minimum and
271 desired sizes for every cell in the table. In the second step, the table constraints
272 are factored in and widths are assigned to every cell. In the third step, heights are
273 assigned to every cell based on the computed width constraint. The results of the first
274 step are cached and only need to be recomputed when content or constraints are changed.</Body>
276 <SectionHeading>Event Manager</SectionHeading>
277 <Body>To be written</Body>
279 </Documentation>
