layout/doc/HLD-SpaceManager.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4
   5   <meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
   6   <title>Space Manager High Level Design</title>
   7   <meta name="author" content="Marc Attinasi (attinasi@netscape.com)">
   8 </head>
   9   <body>
  10
  11 <h1><font color="#cc0000">Gecko Layout High Level Design Document</font></h1>
  12
  13 <h1>Space Manager High Level Design</h1>
  14  <br>
  15
  16 <h2>Overview</h2>
  17   The Space Manager and associated classes and strructures are used by Block
  18 and Line layout to manage rectangular regions that are occupied and available,
  19 for correct handling of floated elements and the elements that flow around
  20 them. &nbsp;When elements are floated to the left or right in a layout, they
  21 take up space and influence where other elements can be placed. &nbsp;The
  22 Space Manager is responsible for keeping track of where space is taken up
  23 and where it is available. This information is used by block layout to correctly
  24 compute where other floated elements should be placed, and how much space
  25 is available to normal in-flow elements that flow around the floated bits.<br>
  26  <br>
  27   The Space Manager works in concert with several other classes to do its
  28 job. The classes that are considered part of the Space Manager are:<br>
  29
  30 <ul>
  31    <li>nsSpaceManager</li>
  32    <li>nsBandData</li>
  33    <li>nsBlockBandData</li>
  34    <li>BandRect / BandList (private structs)</li>
  35    <li>FrameInfo (private struct)</li>
  36    <li>nsBandtrapezoid</li>
  37
  38 </ul>
  39   Outside of the Space Manager itself, the clients of the Space Manager also
  40  play an inportant part in the management of he available and used space.
  41 &nbsp;The primary classes that interact with the Space Manager are:<br>
  42
  43 <ul>
  44    <li>nsBlockReflowState</li>
  45    <li>nsBlockFrame</li>
  46    <li>nsBoxToBlockAdaptor</li>
  47
  48 </ul>
  49   The general interaction model is to create a Space Manager for a block
  50 frame  in the context of a Reflow, and to associate it with the BlockReflowState
  51  so it is passed down to child frames' reflow methods. After reflow, the
  52 Space  Manager is destroyed. &nbsp;During reflow, the space manager stores
  53 the space  taken up by floats (UpdateSpaceManager in nsBlockFrame) and
  54 provides information  about the space available for other elements (GetAvailableSpace
  55 in nsBlockReflowState).  &nbsp;<br>
  56  <br>
  57  Additionally, there is a need to manage impacts to lines caused by
  58 changes to floated elements. &nbsp;This is referred to as Propagation
  59 of Float Damage and is handled by the Block Frame, making use of the
  60 Space Manager. When a float is incrementally reflowed, the Space
  61 Manager is notified if the float's region has changed. If so, the
  62 vertical space that has been affected (including both the float's old
  63 region and the float's new region) is noted in the internal
  64 nsIntervalSet as potential float damage (the method is
  65 IncludeInDamage).  During the incremental reflow of dirty lines the
  66 block frame may encounter lines that are NOT dirty. In this case the
  67 Space Manager is also asked if &nbsp;there is any float damage, and
  68 if there is then the block further checks to see if that damage
  69 intersects the area of the non-dirty line, marking it dirty if there
  70 is intersection. &nbsp;Thus, changes to floats on other lines may
  71 cause impact to otherwise clean lines, and the Space Manager
  72 facilitates the detection of this.  <h2>Data Model</h2>
  73
  74 <h4>Class/Component Diagram</h4>
  75
  76 <blockquote>
  77   <div align="Left"><img src="SpaceManagerClasses.png" alt="SpaceManager Class Diagram" idth="500" eight="459" title="Example Class Diagram">
  78    <br>
  79    </div>
  80    </blockquote>
  81
  82   <ul>
  83      <li>nsSpaceManager: The central point of management of the space taken
  84  up by floats in a block</li>
  85      <li>nsBandData: Provides information about the frames occupying a band
  86  of occupied or available space</li>
  87      <li>nsBlockBandData: A specialization of nsBandData that is used by
  88 nsBlockReflowState   to determine the available space, float impacts, and
  89 where floats are  cleared. &nbsp;Essentially a CSS-specific wrapper for
  90 generic nsBandData.</li>
  91      <li>BandRect: Keeps the bounds of a band, along with the frames associated
  92  with the band. &nbsp;BandRects are a linked list (provided by PRCListStr
  93 super-class) and also provide some geometry-management methods (SplitVertically,
  94 SplitHorizontally) and some methods that query or manipulate the frames associated
  95 with the band (IsOccupiedBy, AddFrame, RemoveFrame).</li>
  96      <li>BandList: A subclass of BandRect that provides a list interface
  97 -  Head(), Tail(), IsEmpty(), etc.</li>
  98      <li>FrameInfo: A structure that keeps information about the rectangle
  99  associated with a specific frame, in a linked list.</li>
 100      <li>nsBandTrapezoid: Represents the discrete regions within a band that
 101  are either Available, Occupied by a single frame, or Occupied by several
 102 frames. &nbsp;This is used to communicate information about the space in
 103 the band to the clients of the SpaceManager. &nbsp;There is no internal use
 104 of the nsBandTrapezoid by the Space Manager, rather it uses its internal
 105 BandList to create a BandData collection, which is largely made up of nsTrapezoid
 106 data.<br>
 107      </li>
 108
 109   </ul>
 110
 111   <h2>Use Case</h2>
 112
 113   <h4>Use Case 1: Space Manager is Created / Destroyed</h4>
 114   Space Manager instances are created in the nsBlockFrame's Reflow method.
 115  &nbsp;<br>
 116
 117   <ul>
 118      <li>An instance is created&nbsp;</li>
 119      <li>The BlockReflowState's previous Space Manager is saved off.</li>
 120      <li>The new Space Manager instance is associated with the BlockReflowState.
 121 &nbsp;</li>
 122      <li>After the block frame's Reflow has completed, the old Space Manager
 123 instance is re-associated with the BlockReflowState</li>
 124      <li>The new Space Manager is destroyed.</li>
 125
 126   </ul>
 127  If the BlockReflowState already had a Space Manager instance associated
 128 with  it, it is stored off before being replaced, and the returned to the
 129 BlockReflowState  instance after the new one has been destroyed. &nbsp;Thus,
 130 Space Managers  are effectively 'nested' during reflow, with each new block
 131 introducing its  own Space Manager.
 132
 133   <h4>Use Case 2: Float is added to the Space Manager</h4>  After a Space Manager is created for a block context's reflow chain, a
 134 floated  block may be added to it. &nbsp;This happens in the method <i>nsBlockReflowState::RecoverFloats</i> and
 135 <i>nsBlockReflowState::FlowAndPlaceFloat</i> (formerly this was done in nsBlockFrame::UpdateSpaceManager). &nbsp;<br>
 136 <br>
 137 The general algorightm in <i>nsBlockReflowState::RecoverFloats</i> is:<br>
 138
 139   <ul>
 140      <li>For each line in the block, see if it has floated blocks</li>
 141      <li>If floats are in the line, iterate over the floats and add each
 142  one to the Space Manager via the AddRectRegion method. &nbsp;The actual rect
 143  for the frame is cached in an nsFloatCache so it does not have to be recomputed.</li>
 144      <li>If the block has any block children, then translate the Space Manager
 145  to the child block's origin and update the space manager in the context
 146 for the child block, recursively. When done with the child, restore the Space
 147  Managers coordinates by translating by the negative of the child block's
 148 origin.&nbsp;       <br>
 149      </li>
 150
 151   </ul><br>
 152
 153 The general algorightm in <i>nsBlockReflowState::FlowAndPlaceFloat</i> is:<br>
 154 <ul>
 155   <li>The region that the float currently occupies is recorded.</li>
 156   <li>The band of available space is searched (with nsBlockReflowState::GetAvailableSpace);</li>
 157   <li>The float frame that is get from the passed nsFloatCache argument is reflowed
 158   and its rect is retrieved with GetRect;</li>
 159   <li>The floats margins are added;</li>
 160   <li>Check if the float can be placed in the acutal band: if not advance to the next band;</li>
 161   <li>Check the float type and if it can be added to the space manager;</li>
 162   <li>Align the float to its containing block top if rule
 163       <a href="http://www.w3.org/TR/REC-CSS2/visuren.html#float-position">CSS2/9.5.1/4</a>
 164       is not respected;</li>
 165   <li>Add the float using <i>nsSpaceManager::AddRectRegion</i> </li>
 166   <li>Compare the area that the float used to occupy with the area that it now occupies: if different,
 167       record the vertically affected interval using <i>nsSpaceManager::IncludeInDamage</i></li>
 168 </ul>
 169   <h4>Use Case 3: Space Manager is used to find available space to reflow
 170  into</h4>
 171   The nsBlockFrame makes use of the Space Manager indirectly to get the available
 172  space to reflow a child block or inline frame into. The block frame uses
 173 a helper method on the nsBlockReflowState class to do the actual computation
 174  of available space based on the data in the Space Manager. Here is how it
 175 works for reflowing an inline frame within a block (this also occurs for
 176 reflowing a block frame and, partially, for preparing for a resize reflow).<br>
 177
 178   <ul>
 179      <li>nsBlockFrame first frees all float information for the line that
 180  is being reflowed.</li>
 181      <li>GetAvailableSpace is called on the BlockReflowState</li>
 182      <li>the BlockReflowState calls GetAvailableSpace on its BlockBandData
 183  instance (which was setup in the BlockReflowState's constructor based on
 184 the SpaceManager passed in and computed content area).</li>
 185      <li>BlockBandData then gets the band data from the space manager via
 186 a call to the Space Manager associated with the BlockBandData instance.</li>
 187      <li>The BlockBandData then walks the collection of trapezoids that were
 188  returned by the SpaceManager method GetBandData (as nsBandData wrappers)
 189 and determines the right-most edge of the available space.</li>
 190      <li>The BlockReflowState then stores this available space rect for use
 191  in the rest of the reflow chain.<br>
 192      </li>
 193
 194   </ul>
 195
 196   <h4>Use Case 4: Propagation of Float Damage: detecting and handling float
 197 damage</h4>
 198   This process is driven by the Block Frame.<br>
 199
 200   <ul>
 201      <li>A non-dirty line is encountered by the Block Frame in ReflowDirtyLines</li>
 202      <li>Block Frame calls its PropagateFloatDamage method</li>
 203      <li>The Space Manager is checked to see if there is any float damage</li>
 204      <li>If there is, then the block frame asks the Space Manager if the
 205 line in question intersects the float damage</li>
 206      <li>If the line does intersect a damage interval, then the line is marked
 207 dirty</li>
 208      <li>If the line does not intersect a damage interval, it may still be
 209 marked dirty if:</li>
 210
 211     <ul>
 212        <li>it was impacted by floats before, but is not any longer</li>
 213        <li>it was not impacted by floats befre, but is now</li>
 214        <li><a name="block-line-impact"></a>
 215  it is impacted by floats and is a block<br>
 216        </li>
 217
 218     </ul>
 219
 220   </ul>
 221    <br>
 222
 223   <hr width="100%" size="2"><br>
 224
 225   <h1><font color="#ff0000">Problems / bugs found during documentation:</font></h1>
 226
 227   <ul>
 228      <li>BandRect and BandList are public in nsSpaceManager.h - should be
 229 private (compiles fine)</li>
 230      <li>nsSpaceManager data members are declared protected, but there are
 231  no subclasses. Should be private (compiles fine)</li>
 232      <li>nsBlockFrame::Paint is mucking with nsBlockBandData in and #if 0
 233 block - remove that and the include (compiles fine)</li>
 234      <li>nsSpaceManger has no way of clearing the float damage interval
 235 set - this might be needed if the SpaceManager persists beyond a Reflow</li>
 236   </ul>
 237    <br>
 238    <br>
 239
 240   </body>
 241   </html>