"Fossies" - the Fresh Open Source Software Archive

Member "firefox-69.0.1/layout/doc/HLD-SpaceManager.html" (17 Sep 2019, 11631 Bytes) of package /linux/www/firefox-69.0.1.source.tar.xz:

Caution: In this restricted "Fossies" environment the current HTML page may not be correctly presentated and may have some non-functional links. You can here alternatively try to browse the pure source code or just view or download the uninterpreted raw source code. If the rendering is insufficient you may try to find and view the page on the firefox-69.0.1.source.tar.xz project site itself.

Gecko Layout High Level Design Document

Space Manager High Level Design


The Space Manager and associated classes and strructures are used by Block and Line layout to manage rectangular regions that are occupied and available, for correct handling of floated elements and the elements that flow around them.  When elements are floated to the left or right in a layout, they take up space and influence where other elements can be placed.  The Space Manager is responsible for keeping track of where space is taken up and where it is available. This information is used by block layout to correctly compute where other floated elements should be placed, and how much space is available to normal in-flow elements that flow around the floated bits.

The Space Manager works in concert with several other classes to do its job. The classes that are considered part of the Space Manager are:
Outside of the Space Manager itself, the clients of the Space Manager also play an inportant part in the management of he available and used space.  The primary classes that interact with the Space Manager are:
The general interaction model is to create a Space Manager for a block frame in the context of a Reflow, and to associate it with the BlockReflowState so it is passed down to child frames' reflow methods. After reflow, the Space Manager is destroyed.  During reflow, the space manager stores the space taken up by floats (UpdateSpaceManager in nsBlockFrame) and provides information about the space available for other elements (GetAvailableSpace in nsBlockReflowState).  

Additionally, there is a need to manage impacts to lines caused by changes to floated elements.  This is referred to as Propagation of Float Damage and is handled by the Block Frame, making use of the Space Manager. When a float is incrementally reflowed, the Space Manager is notified if the float's region has changed. If so, the vertical space that has been affected (including both the float's old region and the float's new region) is noted in the internal nsIntervalSet as potential float damage (the method is IncludeInDamage). During the incremental reflow of dirty lines the block frame may encounter lines that are NOT dirty. In this case the Space Manager is also asked if  there is any float damage, and if there is then the block further checks to see if that damage intersects the area of the non-dirty line, marking it dirty if there is intersection.  Thus, changes to floats on other lines may cause impact to otherwise clean lines, and the Space Manager facilitates the detection of this.

Data Model

Class/Component Diagram

SpaceManager Class Diagram

Use Case

Use Case 1: Space Manager is Created / Destroyed

Space Manager instances are created in the nsBlockFrame's Reflow method.  
If the BlockReflowState already had a Space Manager instance associated with it, it is stored off before being replaced, and the returned to the BlockReflowState instance after the new one has been destroyed.  Thus, Space Managers are effectively 'nested' during reflow, with each new block introducing its own Space Manager.

Use Case 2: Float is added to the Space Manager

After a Space Manager is created for a block context's reflow chain, a floated block may be added to it.  This happens in the method nsBlockReflowState::RecoverFloats and nsBlockReflowState::FlowAndPlaceFloat (formerly this was done in nsBlockFrame::UpdateSpaceManager).  

The general algorightm in nsBlockReflowState::RecoverFloats is:

The general algorightm in nsBlockReflowState::FlowAndPlaceFloat is:

Use Case 3: Space Manager is used to find available space to reflow into

The nsBlockFrame makes use of the Space Manager indirectly to get the available space to reflow a child block or inline frame into. The block frame uses a helper method on the nsBlockReflowState class to do the actual computation of available space based on the data in the Space Manager. Here is how it works for reflowing an inline frame within a block (this also occurs for reflowing a block frame and, partially, for preparing for a resize reflow).

Use Case 4: Propagation of Float Damage: detecting and handling float damage

This process is driven by the Block Frame.

Problems / bugs found during documentation: