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