summaryrefslogtreecommitdiffstats
path: root/layout/doc/obsolete/block.html
diff options
context:
space:
mode:
authorMatt A. Tobin <mattatobin@localhost.localdomain>2018-02-02 04:16:08 -0500
committerMatt A. Tobin <mattatobin@localhost.localdomain>2018-02-02 04:16:08 -0500
commit5f8de423f190bbb79a62f804151bc24824fa32d8 (patch)
tree10027f336435511475e392454359edea8e25895d /layout/doc/obsolete/block.html
parent49ee0794b5d912db1f95dce6eb52d781dc210db5 (diff)
downloadUXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.gz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.lz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.xz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.zip
Add m-esr52 at 52.6.0
Diffstat (limited to 'layout/doc/obsolete/block.html')
-rw-r--r--layout/doc/obsolete/block.html209
1 files changed, 209 insertions, 0 deletions
diff --git a/layout/doc/obsolete/block.html b/layout/doc/obsolete/block.html
new file mode 100644
index 000000000..255b84cd6
--- /dev/null
+++ b/layout/doc/obsolete/block.html
@@ -0,0 +1,209 @@
+<!-- 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.0 transitional//en">
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+ <meta name="GENERATOR" content="Mozilla/4.61 [en] (X11; I; Linux 2.2.5-22 i686) [Netscape]">
+</head>
+<body>
+
+<h1>
+<u>Block Layout</u></h1>
+This document attempts to describe how "block" layout works in the mozilla
+layout engine.
+<p><tt>nsBlockFrame</tt> implements layout behavior that conforms to the
+CSS "display:block" and "display: list-item" layout. It has several responsibilities:
+<ol>
+<li>
+&nbsp;Line layout. The block is responsible for flowing inline elements
+into "lines" and applying all of the css behavior as one might expect,
+including line-height, vertical-align, relative positioning, etc.</li>
+
+<li>
+Float management. The block is responsible for the reflow and placement
+of floating elements.</li>
+
+<li>
+Child block management. Blocks can contain inline elements and block elements.
+Hence, blocks are responsible for reflowing child blocks. The majority
+of that logic has been split out into nsBlockReflowContext, but a fair
+amount remains here.</li>
+
+<li>
+Supporting table reflow. The block has to carefully compute the "max-element-size"
+information needed by tables. Hence, any time changes are made here one
+should always run the table regression tests because the odds are you broke
+one of them!</li>
+</ol>
+
+<h3>
+<u>The Big Picture for Block Reflow</u></h3>
+The block frame uses a list of nsLineBox's to keep track of each "line"
+of frames it manages. There are two types of lines:
+<blockquote>"inline" lines which contain only inline elements
+<br>"block" lines which contain exactly one block element</blockquote>
+Each line has a "dirty" bit which indicates that it needs reflow. Reflow
+consists of identifying which lines need to be marked dirty and then reflowing
+all lines. For lines which are "clean" the reflow logic will endeavor to
+recover the state of reflow <i>as if the line had been reflowed</i>. This
+saves time and allows for a faster incremental reflow. For lines which
+are dirty, the line is reflowed appropriately.
+<p>The only special thing about incremental reflow command handling is
+that it marks lines dirty before proceeding, and keeps track of the child
+frame that is the next frame on the reflow command path.
+<p>Here is a list of the various classes involved in block layout:
+<p><b>nsBlockFrame</b>
+<blockquote>The primary culprit.</blockquote>
+<b>nsBlockReflowState</b>
+<blockquote>This helper class is used to augment the nsHTMLReflowState
+with other information needed by the block reflow logic during reflow.
+It is a temporary object that is designed to live on the processor stack
+and contains "running" state used by the blocks reflow logic.</blockquote>
+<b>nsBlockBandData</b>
+<blockquote>Another helper class that wraps up management of a space manager
+(nsISpaceManager, nsSpaceManager) and nsBandData. It also assists in management
+of floating elements. While nsSpaceManager is policy free, nsBlockBandData
+provides specific HTML and CSS policy.</blockquote>
+<b>nsBlockReflowContext</b>
+<blockquote>A helper class that encapsulates the logic needed to reflow
+a child block frame. This is used by the block code reflow a child block
+and to reflow floating elements (which are to be treated as blocks according
+to the CSS2 spec).</blockquote>
+<b>nsLineBox</b>
+<blockquote>A data class used to store line information for the block frame
+code. Each line has a list of children (though the frames are linked together
+across lines to maintain the sibling list for nsIFrame::FirstChild) and
+some other state used to assist in incremental reflow.</blockquote>
+<b>nsLineLayout</b>
+<blockquote>This class is the line layout engine. Its a passive entity
+in the sense that its the responsibility of the block/inline code to use
+the class (this is done so that the line layout engine doesn't have to
+manage child frame lists so that both nsBlockFrame and nsInlineFrame can
+use the class).</blockquote>
+<b>nsTextRun</b>
+<blockquote>This is a data class used to store text run information. Text
+runs are <i>logically</i> contiguous runs of text (they may or may not
+be structurally contiguous). The block frame stores a pointer to a list
+of nsTextRun's and during line layout provides the list to the nsLineLayout
+engine so that when text is reflowed the text layout code (nsTextFrame)
+can find related text to properly handle word breaking.</blockquote>
+
+<h3>
+<u>Frame construction methods</u></h3>
+When the blocks child list is modified (AppendFrames, InsertFrames, RemoveFrame)
+the block code updates its nsLineBox list. Since each nsLineBox is typed
+(some are marked "inline" and some are marked "block"), the update logic
+maintains the invariant of "one block frame per block line".
+<p>When structural changes are made to the blocks children (append/insert/remove)
+the block code updates the line's and then marks the affected lines "dirty"
+(each nsLineBox has a dirty bit). After the structural changes are finished
+then the block will generate an incremental reflow command of type "ReflowDirty".
+<h3>
+<u>Line Layout</u></h3>
+Line layout consists of the placement of inline elements on a line until
+there is no more room on the line. At that point the line is "broken" and
+continued on the next line. This process continues until all inline elements
+have been exhausted. The block code maintains a list of "nsLineBox"'s to
+facilitate this. These are used instead of frames because they use less
+memory and because it allows the block to directly control their behavior.
+<p>The helper class nsLineLayout provides the majority of the line layout
+behavior needed by the block.
+<p>The block does keep "text-run" information around for the nsLineLayout
+logic to use during reflow. Text runs keep track of logically adjacent
+pieces of text within a block. This information is essential for properly
+computing line and word breaking. Why? Well, because in html you can write
+something like this:
+<p>&nbsp; &lt;p>I &lt;b>W&lt;/b>as thinking one day&lt;/p>
+<p>Notice that the word "Was" is composed of two pieces of text, and that
+they do <i>not</i> have the same parent (content or frame). To properly
+reflow this and not break the word prematurely after the "W", the text-run
+information is used by the text frame code to "look ahead" and prevent
+premature breaking.
+<p>Lines also keep track of the type of "break" that occurred on the line.
+This is used, for example, to support html's "&lt;br clear=left>" behavior.
+<h3>
+<u>Float Management</u></h3>
+Since child block elements are containing blocks for floats, the only
+place where a block frame will see a float is as part of an inline line.
+Consequently, the nsLineBox will only keep track of floats on inline
+lines (saving storage for block lines).
+<p>The nsLineLayout class and the block frame cooperate in the management
+of floats. Since the frame construction code leaves a "placeholder" frame
+in-flow where the float was found, when nsLineLayout reflows a placeholder
+frame it knows to inform the block about it. That triggers the blocks "AddFloat"
+logic which then determines where the float should be placed (on the
+current line or below the current line).
+<p>The block frame uses the space manager to manage the effects of floats,
+namely the consumption of available space. For example, for a left aligned
+floating element, the inline elements must be placed to the right of the
+float. To simplify this process, the spacemanager is used to keep track
+of available and busy space. Floats when placed mark space as busy and
+the spacemanager will them compute the available space. Most of this logic
+is handled by the nsBlockReflowState which uses a helper class, nsBlockBandData,
+in concert with the space manager, to do the available space computations.
+<h3>
+<u>Child Block Placement</u></h3>
+Child block reflow is done primarily by using the nsBlockReflowContext
+code. However, a key detail worth mentioning here is how margins are handled.
+When the nsHTMLReflowState was created, we placed into it the logic for
+computing margins, border and padding (among other things). Unfortunately,
+given the css rules for sibling and generational margin collapsing, the
+nsHTMLReflowState is unable to properly compute top and bottom margins.
+Hence, the block frame and the nsBlockReflowContext code perform that function.
+At the time that the nsBlockReflowContext was designed and implemented
+we thought that it could compute the top-margin itself and then proceed
+to place the child block element. However, that turned out to be wrong
+(oh well) because the correct available space isn't known until <i>after</i>
+the top margin is computed. Hence, there is some unfortunate duplication
+of reflow state calculations present in the block frame code.
+<h3>
+<u>Bullets</u></h3>
+Another type of block frame is the "display: list-item". List-items use
+nsBulletFrame's to manage bullet reflow. However, the block is responsible
+for bullet placement. In most situations, the nsLineLayout class is used
+to do the placement. However, if the first effective child of the block
+is another block, then the block has to do the placement itself.
+<h3>
+<u>Blank lines</u></h3>
+Because our content model contains as much of the original source documents
+content as possible, we end up with a lot of white space that ends up being
+compressed into nothingness. This white space ends up impacting this logic
+in several ways. For example:
+<p>&nbsp; &lt;div>
+<br>&nbsp;&nbsp; &lt;p>abc&lt;/p>
+<br>&nbsp;&nbsp; &lt;p>def&lt;/p>
+<br>&nbsp; &lt;/div>
+<p>In the content model for the above html, there is white space between
+the various block elements (some after the &lt;div>, some after the first
+&lt;/p>, again after the second &lt;/p>).
+<p>For css margin collapsing to work properly, each of those instances
+of white space has to behave as if they didn't exist. Consequently, there
+is special logic in the inline line reflow code, and in the nsBlockReflowContext
+code and in the GetTopBlockChild method, to basically ignore such lines.
+<h3>
+<u>First-letter style</u></h3>
+The block contributes, in a small way, to first-letter style reflow. The
+frame construction code is responsible for creating the list of child frames
+for all frames, including the block. It manages the creation of letter-frames,
+where appropriate, so that all the block has to do is reflow them almost
+normally like other inline frames.
+<p>There are two things different that the block does:
+<p>It is responsible for calling nsLineLayout::SetFirstLetterStyleOK
+<br>It is responsible for continuing to place frames on a line, even after
+a frame has said "it can't fit". Normally during inline reflow, if a frame
+comes back and says it can't fit, the block will end the line, push all
+remaining frames to the next line and pick up the reflow from there after
+making sure the frame that didn't fit is continued. For letter-frames,
+this would result in the first-letter being on one line with the remaining
+text on subsequent lines. Hence, the block code handles this special case.
+<br>&nbsp;
+<h3>
+<u>First-line style</u></h3>
+First-line is handled entirely by the frame construction code.
+<br>&nbsp;
+<br>&nbsp;
+</body>
+</html>