← Back to branch summary

~ubuntu-branches/ubuntu/precise/kompozer/precise

« back to all changes in this revision

Viewing changes to mozilla/layout/doc/HLD-SpaceManager.html

  • Committer: Bazaar Package Importer
  • Author(s): Anthony Yarusso
  • Date: 2007-08-27 01:11:03 UTC
  • Revision ID: james.westby@ubuntu.com-20070827011103-2jgf4s6532gqu2ka
Tags: upstream-0.7.10
Import upstream version 0.7.10

Show diffs side-by-side

added added

removed removed

Lines of Context:
mozilla/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 witht eh 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
Manger 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 Manger 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 Manger is saved off.</li>
 
120
     <li>The new Space Manger 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 Manger 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 retriven 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 Manger. 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 Manger is checked to see if ther 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>