| blob | 6e5824ee262a314f150a93a75c7f712e278169e0 |
2 <html>
3 <head>
6 </head>
7 <body>
9 <h1>
11 This document attempts to describe how "block" layout works in the mozilla
12 layout engine.
15 <ol>
16 <li>
17 Line layout. The block is responsible for flowing inline elements
18 into "lines" and applying all of the css behavior as one might expect,
19 including line-height, vertical-align, relative positioning, etc.</li>
21 <li>
22 Float management. The block is responsible for the reflow and placement
23 of floating elements.</li>
25 <li>
26 Child block management. Blocks can contain inline elements and block elements.
27 Hence, blocks are responsible for reflowing child blocks. The majority
28 of that logic has been split out into nsBlockReflowContext, but a fair
29 amount remains here.</li>
31 <li>
32 Supporting table reflow. The block has to carefully compute the "max-element-size"
33 information needed by tables. Hence, any time changes are made here one
34 should always run the table regression tests because the odds are you broke
35 one of them!</li>
36 </ol>
38 <h3>
40 The block frame uses a list of nsLineBox's to keep track of each "line"
41 of frames it manages. There are two types of lines:
44 Each line has a "dirty" bit which indicates that it needs reflow. Reflow
45 consists of identifying which lines need to be marked dirty and then reflowing
46 all lines. For lines which are "clean" the reflow logic will endeavor to
48 saves time and allows for a faster incremental reflow. For lines which
49 are dirty, the line is reflowed appropriately.
50 <p>The only special thing about incremental reflow command handling is
51 that it marks lines dirty before proceeding, and keeps track of the child
52 frame that is the next frame on the reflow command path.
53 <p>Here is a list of the various classes involved in block layout:
57 <blockquote>This helper class is used to augment the nsHTMLReflowState
58 with other information needed by the block reflow logic during reflow.
59 It is a temporary object that is designed to live on the processor stack
62 <blockquote>Another helper class that wraps up management of a space manager
63 (nsISpaceManager, nsSpaceManager) and nsBandData. It also assists in management
64 of floating elements. While nsSpaceManager is policy free, nsBlockBandData
65 provides specific HTML and CSS policy.</blockquote>
67 <blockquote>A helper class that encapsulates the logic needed to reflow
68 a child block frame. This is used by the block code reflow a child block
69 and to reflow floating elements (which are to be treated as blocks according
70 to the CSS2 spec).</blockquote>
72 <blockquote>A data class used to store line information for the block frame
73 code. Each line has a list of children (though the frames are linked together
74 across lines to maintain the sibling list for nsIFrame::FirstChild) and
75 some other state used to assist in incremental reflow.</blockquote>
77 <blockquote>This class is the line layout engine. Its a passive entity
78 in the sense that its the responsibility of the block/inline code to use
79 the class (this is done so that the line layout engine doesn't have to
80 manage child frame lists so that both nsBlockFrame and nsInlineFrame can
81 use the class).</blockquote>
83 <blockquote>This is a data class used to store text run information. Text
85 be structurally contiguous). The block frame stores a pointer to a list
86 of nsTextRun's and during line layout provides the list to the nsLineLayout
87 engine so that when text is reflowed the text layout code (nsTextFrame)
88 can find related text to properly handle word breaking.</blockquote>
90 <h3>
92 When the blocks child list is modified (AppendFrames, InsertFrames, RemoveFrame)
93 the block code updates its nsLineBox list. Since each nsLineBox is typed
95 maintains the invariant of "one block frame per block line".
96 <p>When structural changes are made to the blocks children (append/insert/remove)
97 the block code updates the line's and then marks the affected lines "dirty"
98 (each nsLineBox has a dirty bit). After the structural changes are finished
99 then the block will generate an incremental reflow command of type "ReflowDirty".
100 <h3>
102 Line layout consists of the placement of inline elements on a line until
103 there is no more room on the line. At that point the line is "broken" and
104 continued on the next line. This process continues until all inline elements
105 have been exhausted. The block code maintains a list of "nsLineBox"'s to
106 facilitate this. These are used instead of frames because they use less
107 memory and because it allows the block to directly control their behavior.
108 <p>The helper class nsLineLayout provides the majority of the line layout
109 behavior needed by the block.
111 logic to use during reflow. Text runs keep track of logically adjacent
112 pieces of text within a block. This information is essential for properly
113 computing line and word breaking. Why? Well, because in html you can write
114 something like this:
118 reflow this and not break the word prematurely after the "W", the text-run
119 information is used by the text frame code to "look ahead" and prevent
120 premature breaking.
122 This is used, for example, to support html's "<br clear=left>" behavior.
123 <h3>
125 Since child block elements are containing blocks for floats, the only
126 place where a block frame will see a float is as part of an inline line.
127 Consequently, the nsLineBox will only keep track of floats on inline
128 lines (saving storage for block lines).
129 <p>The nsLineLayout class and the block frame cooperate in the management
130 of floats. Since the frame construction code leaves a "placeholder" frame
131 in-flow where the float was found, when nsLineLayout reflows a placeholder
132 frame it knows to inform the block about it. That triggers the blocks "AddFloat"
133 logic which then determines where the float should be placed (on the
134 current line or below the current line).
135 <p>The block frame uses the space manager to manage the effects of floats,
136 namely the consumption of available space. For example, for a left aligned
137 floating element, the inline elements must be placed to the right of the
138 float. To simplify this process, the spacemanager is used to keep track
139 of available and busy space. Floats when placed mark space as busy and
140 the spacemanager will them compute the available space. Most of this logic
141 is handled by the nsBlockReflowState which uses a helper class, nsBlockBandData,
142 in concert with the space manager, to do the available space computations.
143 <h3>
145 Child block reflow is done primarily by using the nsBlockReflowContext
146 code. However, a key detail worth mentioning here is how margins are handled.
147 When the nsHTMLReflowState was created, we placed into it the logic for
148 computing margins, border and padding (among other things). Unfortunately,
149 given the css rules for sibling and generational margin collapsing, the
150 nsHTMLReflowState is unable to properly compute top and bottom margins.
151 Hence, the block frame and the nsBlockReflowContext code perform that function.
152 At the time that the nsBlockReflowContext was designed and implemented
153 we thought that it could compute the top-margin itself and then proceed
154 to place the child block element. However, that turned out to be wrong
156 the top margin is computed. Hence, there is some unfortunate duplication
157 of reflow state calculations present in the block frame code.
158 <h3>
160 Another type of block frame is the "display: list-item". List-items use
161 nsBulletFrame's to manage bullet reflow. However, the block is responsible
162 for bullet placement. In most situations, the nsLineLayout class is used
163 to do the placement. However, if the first effective child of the block
164 is another block, then the block has to do the placement itself.
165 <h3>
167 Because our content model contains as much of the original source documents
168 content as possible, we end up with a lot of white space that ends up being
169 compressed into nothingness. This white space ends up impacting this logic
170 in several ways. For example:
175 <p>In the content model for the above html, there is white space between
178 <p>For css margin collapsing to work properly, each of those instances
179 of white space has to behave as if they didn't exist. Consequently, there
180 is special logic in the inline line reflow code, and in the nsBlockReflowContext
181 code and in the GetTopBlockChild method, to basically ignore such lines.
182 <h3>
184 The block contributes, in a small way, to first-letter style reflow. The
185 frame construction code is responsible for creating the list of child frames
186 for all frames, including the block. It manages the creation of letter-frames,
187 where appropriate, so that all the block has to do is reflow them almost
188 normally like other inline frames.
189 <p>There are two things different that the block does:
190 <p>It is responsible for calling nsLineLayout::SetFirstLetterStyleOK
191 <br>It is responsible for continuing to place frames on a line, even after
192 a frame has said "it can't fit". Normally during inline reflow, if a frame
193 comes back and says it can't fit, the block will end the line, push all
194 remaining frames to the next line and pick up the reflow from there after
195 making sure the frame that didn't fit is continued. For letter-frames,
196 this would result in the first-letter being on one line with the remaining
197 text on subsequent lines. Hence, the block code handles this special case.
199 <h3>
201 First-line is handled entirely by the frame construction code.
204 </body>
205 </html>