layout/doc/debugtable.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
   2
   3 <html>
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   6
   7  <style type="text/css">
   8   body {font-family:arial}
   9 .log {background-color:silver; color:blue}
  10 pre.log {display:table-cell}
  11   </style>
  12
  13   <title>Debugging facilities in HTML-Table code</title>
  14 </head>
  15 <body>
  16  <h1>Debugging facilities in HTML-table code</h1>
  17  <h2>Reflow</h2>
  18  <p>The most efficient tool to claim that html-table code is the victim and not the source of layout bugs is a  <a href="http://lxr.mozilla.org/seamonkey/source/layout/doc/frame_reflow_debug.html">frame reflow  debug log</a>.  Look there especially how the maxElementsize (MES)  and desired size are propagated.
  19
  20  <h2>Block Reflow</h2>
  21 <p>
  22 Another way to debug the reflow process is implemented inside <a href="http://lxr.mozilla.org/seamonkey/source/layout/html/base/src/nsBlockFrame.cpp">nsBlockFrame.cpp</a>. It can be invoked by<p>
  23 <code>set GECKO_BLOCK_DEBUG_FLAGS=reflow</code>
  24 <p>
  25 The available options are:
  26 <ul>
  27 <li><code>reflow</code>
  28 <li> <code>really-noisy-reflow</code>
  29 <li><code>max-element-size</code>
  30 <li><code> space-manager</code>
  31 <li><code>verify-lines</code>
  32 <li><code>damage-repair</code>
  33 <li><code>lame-paint-metrics</code>
  34 <li><code>lame-reflow-metrics</code>
  35 <li><code>disable-resize-opt</code>
  36 </ul>
  37 <p>
  38 These options can be combined with a comma separated list
  39 Messages generated by the <code>reflow</code> switch:
  40 <ul>
  41 <li><code> Block(div)(1)@00BE5AC4: reflowing dirty lines computedWidth=9000 computedHeight=1500</code>
  42 <ul>
  43 <li> this message is generated inside of <br>
  44 <code>nsresult nsBlockFrame::ReflowDirtyLines(nsBlockReflowState& aState)</code>
  45 <li> it first shows the Block ID and Address
  46 <li>and then the computed width and Height from the HTMLReflowState.
  47 </ul>
  48 </ul>
  49
  50 <h2>DEBUG_TABLE_STRATEGY</h2>
  51 <p>
  52 The table layout strategy can be visualized by defining in the <a href="http://lxr.mozilla.org/seamonkey/source/layout/html/table/src/Makefile.in">makefiles</a> the constant DEBUG_TABLE_STRATEGY.
  53
  54 If one takes for instance the following table
  55 <table cellspacing="10"><tr><th>rendering</th><th>code</th></tr>
  56 <tr valign="top"><td valign="top" style="padding-top:10px">
  57 <table border width="300">
  58 <colgroup>
  59 <col>
  60 <col width="50%">
  61 <col width="1*">
  62 <col>
  63 </colgroup>
  64         <tr>
  65               <td style="width:80px">cell 1</td>
  66             <td>cell 2</td>
  67             <td>cell 3</td>
  68             <td>cell 4</td>
  69         </tr>
  70 </table>
  71 </td>
  72 <td valign="top"><pre class="log">
  73 &lt;table border width="300"&gt;
  74 &lt;colgroup&gt;
  75 &lt;col&gt;
  76 &lt;col width="50%"&gt;
  77 &lt;col width="1*"&gt;
  78 &lt;col&gt;
  79 &lt;/colgroup&gt;
  80         &lt;tr&gt;
  81               &lt;td style="width:80px"&gt;cell 1&lt;/td&gt;
  82             &lt;td&gt;cell 2&lt;/td&gt;
  83             &lt;td&gt;cell 3&lt;/td&gt;
  84             &lt;td&gt;cell 4&lt;/td&gt;
  85         &lt;/tr&gt;
  86 &lt;/table&gt;
  87 </pre>
  88 </td>
  89 </tr>
  90 </table>
  91 <p>
  92 it will produce the following log at the entrance of <code>AssignNonPctColWidths</code>:
  93 <p>
  94 <table class="log"><tr><td>
  95 <pre>
  96 AssignNonPctColWidths en max=4500 count=0
  97 ***START TABLE DUMP***
  98 mColWidths=-1 -1 -1 -1
  99
 100  col frame cache -&gt;
 101 0=00B93138 1=00B931F0 2=024DD728 3=024DD780
 102  **START COL DUMP** colIndex=0 isAnonymous=0 constraint=0
 103   widths=-1 -1 -1 -1 -1 -1 -1 -1 -1 -1  **END COL DUMP**
 104  **START COL DUMP** colIndex=1 isAnonymous=0 constraint=0
 105   widths=-1 -1 -1 -1 -1 -1 -1 -1 -1 -1  **END COL DUMP**
 106  **START COL DUMP** colIndex=2 isAnonymous=0 constraint=0
 107   widths=-1 -1 -1 -1 -1 -1 -1 -1 -1 -1  **END COL DUMP**
 108  **START COL DUMP** colIndex=3 isAnonymous=0 constraint=0
 109   widths=-1 -1 -1 -1 -1 -1 -1 -1 -1 -1  **END COL DUMP**
 110 ***END TABLE DUMP***
 111 </pre>
 112 </td></tr></table>
 113
 114
 115 <p>
 116 The <span class="log">en</span> stands for entrance (<span class="log">ex</span> for leaving a routine). The first line of the data dump shows that no width has yet been assigned to the columns <span class="log">mColWidths=-1 -1 -1 -1</span>,  <code>-1</code> stands for:
 117 <pre>
 118 #define WIDTH_NOT_SET   -1
 119 </pre>
 120 <p>
 121 This is followed by a reference to the column frame pointers:
 122 <p>
 123 <pre class="log">
 124 col frame cache -&gt;
 125 0=00B93138 1=00B931F0 2=024DD728 3=024DD780
 126 </pre>
 127 <p>
 128 This is followed by the information which width has been set for each column. The index of the column, whether it is anonymous and what kind of constrained has been applied<span class="log">colIndex=0 isAnonymous=0 constraint=0</span>. The following constraint types are known:
 129 <p>
 130 <pre>
 131   eNoConstraint          = 0,
 132   ePixelConstraint       = 1,      // pixel width
 133   ePercentConstraint     = 2,      // percent width
 134   eProportionConstraint  = 3,      // 1*, 2*, etc. cols attribute assigns 1*
 135   e0ProportionConstraint = 4       // 0*, means to force to min width
 136 </pre>
 137 <p>
 138 After this follows the width information for each column:
 139 <p>
 140 <pre class="log">
 141 widths=-1 -1 -1 -1 -1 -1 -1 -1 -1 -1
 142 </pre>
 143 <p>
 144 The table code knows ten different width's:
 145 <pre>
 146 #define NUM_WIDTHS       10
 147 #define NUM_MAJOR_WIDTHS 3 // MIN, DES, FIX
 148 #define MIN_CON          0 // minimum width required of the content + padding
 149 #define DES_CON          1 // desired width of the content + padding
 150 #define FIX              2 // fixed width either from the content or cell, col, etc. + padding
 151 #define MIN_ADJ          3 // minimum width + padding due to col spans
 152 #define DES_ADJ          4 // desired width + padding due to col spans
 153 #define FIX_ADJ          5 // fixed width + padding due to col spans
 154 #define PCT              6 // percent width of cell or col
 155 #define PCT_ADJ          7 // percent width of cell or col from percent colspan
 156 #define MIN_PRO          8 // desired width due to proportional &lt;col&gt;s or cols attribute
 157 #define FINAL            9 // width after the table has been balanced, considering all of the others
 158 </pre>
 159 <p>
 160 In the last log snippet none of these width's has been set.
 161 Leaving  AssignNonPctColWidths shows that already to all columns a width of 360 twips has been assigned
 162 <pre class="log">
 163 AssignNonPctColWidths ex
 164 ***START TABLE DUMP***
 165 mColWidths=360 360 360 360
 166
 167  col frame cache -&gt;
 168 0=00B93138 1=00B931F0 2=024DD728 3=024DD780
 169  **START COL DUMP** colIndex=0 isAnonymous=0 constraint=0
 170   widths=360 540 1230 -1 -1 -1 -1 -1 -1 360  **END COL DUMP**
 171  **START COL DUMP** colIndex=1 isAnonymous=0 constraint=0
 172   widths=360 540 -1 -1 -1 -1 -1 -1 -1 360  **END COL DUMP**
 173  **START COL DUMP** colIndex=2 isAnonymous=0 constraint=3
 174   widths=360 540 -1 -1 -1 -1 -1 -1 540 360  **END COL DUMP**
 175  **START COL DUMP** colIndex=3 isAnonymous=0 constraint=0
 176   widths=360 540 -1 -1 -1 -1 -1 -1 -1 360  **END COL DUMP**
 177 ***END TABLE DUMP***
 178 </pre>
 179 <p>
 180 The first column has already the minimum content width, the table column can't shrink below that, the desired content width of <span class="log">540</span> twips, that's the space to layout <code>cell 1</code> without wrapping the text and the <span class="log">1230</span> which correspond to the <code>style="width:80px"</code> at the first cell. At this step the final size is <span class="log">360</span> twips.
 181 <p>
 182 <table cellpadding="8">
 183 <tr>
 184 <th> MIN_CON</th><th>DES_CON</th><th>FIX</th><th>MIN_ADJ</th><th>DES_ADJ</th><th>FIX_ADJ</th><th>PCT</th><th> PCT_ADJ</th><th> MIN_PRO</th><th>FINAL</th>
 185 </tr>
 186 <tr align="center">
 187 <td>360</td><td> 540</td><td> 1230 </td><td>-1</td><td> -1 </td><td>-1</td><td> -1</td><td> -1</td><td> -1</td><td> 360</td></tr></table>
 188 <p>
 189 There was no change till the entrance of <code>BalanceColumnWidths
 190 </code>
 191 <p>
 192 <pre class="log">
 193 BalanceColumnWidths en count=1
 194 ***START TABLE DUMP***
 195 mColWidths=360 360 360 360
 196
 197  col frame cache -&gt;
 198 0=00B93138 1=00B931F0 2=024DD728 3=024DD780
 199  **START COL DUMP** colIndex=0 isAnonymous=0 constraint=0
 200   widths=360 540 1230 -1 -1 -1 -1 -1 -1 360  **END COL DUMP**
 201  **START COL DUMP** colIndex=1 isAnonymous=0 constraint=0
 202   widths=360 540 -1 -1 -1 -1 -1 -1 -1 360  **END COL DUMP**
 203  **START COL DUMP** colIndex=2 isAnonymous=0 constraint=3
 204   widths=360 540 -1 -1 -1 -1 -1 -1 540 360  **END COL DUMP**
 205  **START COL DUMP** colIndex=3 isAnonymous=0 constraint=0
 206   widths=360 540 -1 -1 -1 -1 -1 -1 -1 360  **END COL DUMP**
 207 ***END TABLE DUMP***
 208 </pre>
 209 <p>
 210 But at the end the final distribution between the columns has been reached.
 211 <p>
 212 <pre class="log">
 213 BalanceColumnWidths ex
 214 ***START TABLE DUMP***
 215 mColWidths=1230 2160 465 465
 216
 217  col frame cache -&gt;
 218 0=00B93138 1=00B931F0 2=024DD728 3=024DD780
 219  **START COL DUMP** colIndex=0 isAnonymous=0 constraint=0
 220   widths=360 540 1230 -1 -1 -1 -1 -1 -1 1230  **END COL DUMP**
 221  **START COL DUMP** colIndex=1 isAnonymous=0 constraint=0
 222   widths=360 540 -1 -1 -1 -1 2160 -1 -1 2160  **END COL DUMP**
 223  **START COL DUMP** colIndex=2 isAnonymous=0 constraint=3
 224   widths=360 540 -1 -1 -1 -1 -1 -1 540 465  **END COL DUMP**
 225  **START COL DUMP** colIndex=3 isAnonymous=0 constraint=0
 226   widths=360 540 -1 -1 -1 -1 -1 -1 -1 465  **END COL DUMP**
 227 ***END TABLE DUMP***
 228 </pre>
 229 <p>
 230 The column dump is implemented in <code>nsTableColFrame.cpp</code> in the routine:
 231 <code>void nsTableColFrame::Dump(PRInt32 aIndent)</code>.
 232
 233 <h2>DEBUG_TABLE_REFLOW_TIMING</h2>
 234 <p>needs to be written
 235
 236 <hr>
 237 <p style="text-align:right">author: Bernd Mielke <br>2002-06-05</p>
 238
 239 </body>
 240
 241 </html>