Layout debugger

The Layout Debugger was written by David Baron as a replacement for the old viewer.exe. It's now available in any debug trunk build. The tool provides access to some advanced debugging facilities that can be useful when diagnosing and fixing layout bugs.

The Layout Debugger can show you:

  • Box dimensions of blocks without a border.
  • The targets of mouse events.
  • Flashes for every paint.
  • How many times a frame has been reflown.
  • Frame and view information.

Layout debugger with shown toggle menu

Using the Layout Debugger

To start the Layout Debugger, launch Firefox with the -layoutdebug command line option.  If you're using a debug build with --enable-tests (which is the default for debug builds), you can also choose the Layout Debugger menu item from the Tools menu.

Onscreen information

This section covers common display options and when they are useful.

Visual debugging

This is useful for spotting box size errors.


Event debugging

Helps track down problems with links that aren't working, for example.


Reflow Statistics

For identifying and solving problems related to missing reflows.


Paint and invalidate information

These options provide useful information about the process of painting and invalidating content.

Paint dumping

Dumps pointers to the widgets that are being painted, as well as their IDs and rectangles.

   1 PAINT      widget=02F0FD14  id=000A0318 rect=587,0    15,343
   2 PAINT      widget=03083564  id=00070330 rect=  0,0   587,343

Invalidate dumping

As content is invalidated (that is, marked to be redrawn next time painting occurs), the corresponding widgets' pointers, IDs, and regions are dumped.

  49 Invalidate widget=03083564  id=00070330 rect=  0,0   587,343 sync=no
  50 Invalidate widget=02F0FD14  id=000A0318 rect=  0,0   602,343 sync=no

Paint + invalidate dumping

You should usually use both paint and invalidate dumping at the same time when tracking invalidate and/or paint issues, since they're closely related.

 100 Invalidate widget=02F0FD14  id=000A0318 rect=587,15   15,313 sync=no
 101 Invalidate widget=02F0FD14  id=000A0318 rect=587,0    15,343 sync=no
 102 PAINT      widget=02F0FD14  id=000A0318 rect=587,0    15,343


Event information

These options provide useful information about events, which can help debug assorted event related problems.

Event dumping

Dumps information about events as they get handled.

 740 NS_LOSTFOCUS  widget=02EE042C name=something    id=000802E8 pos=0,0
 741 NS_GOTFOCUS   widget=03583E34 name=something    id=00080330 pos=0,0
 742 UNKNOWN: 108  widget=03583E34 name=something    id=00080330 pos=0,0

Motion event dumping

Dumps additional mouse movement events.

 845 NS_MOUSE_MOVE widget=03079A4C name=something    id=007D046A pos=22,69
 846 NS_MOUSE_MOVE widget=03079A4C name=something    id=007D046A pos=2,67

Crossing events dumping

This works only for gtk builds.

Note: Need content here.

Webshells and content

Options that provide information about webshells and content.

Dump webshells

Dumps information about webshells.

Note: This could use more details.
02EBC3D4 '' parent=00000000 <
  035756EC '' parent=02EBC3D4 <


Dump content

This dumps the content tree; however, you'll find that Firebug and DOM Inspector are much better debugging tools for this task.

        tr@03696298 refcount=2<
          Text@036962F0 refcount=1<\n\n>

          td@03695298 refcount=3<
            Text@036952F0 refcount=2<This is column one.>
          Text@036953D8 refcount=1<\n\n>
          td@03695468 refcount=3<
            Text@036954C0 refcount=2<This is column two.>

          Text@03693A80 refcount=1<\n\n>

Debug frame construction

Options that provide information about frame construction.

Dump frames

Provides a dump of the frames that comprise the content.

TableCell(td)(1)@036D4034 next=036D41C4 {24,0,4956,288}[state=00000014] [content=03695298] [sc=036D3F78]<
  Block(td)(1)@036D40A8 {24,24,4908,240} [state=00c00014] sc=036D40FC(i=1,b=0)<
    line 036D4194: count=1 state=inline,clean,prevmargin clean,not impacted,not wrapped,nobr[0x1000] mew=516 {0,0,1380,240} <

      Text(0)@036D4154[0,19,T]  {0,6,1380,228} [state=40000034] sc=036D4128<
          "This is column one."
Parameter Value in the above example
frame TableCell(td)
frame's address @036D4034
next sibling next=036D41C4
box parameter {24,0,4956,288}
frame state [state=00000014]
corresponding content node [content=03695298]
style context [sc=036D3F78]