MozAfterPaint

Important notes

• MozAfterPaint is a Gecko-only event, and for compatibility (and performance) reasons should not be used outside chrome code, such as extensions.
• For security reasons, regular Web content is only notified of repainting that occurred in its own document.  Repainting caused by iframes is not reported to untrusted listeners.  Listeners added by trusted content, such as extensions or other chrome code, are notified of all repaints.
• If your event handler does anything that triggers repainting, such as changing the style of an element, you will probably trigger an infinite loop.  So please don't do that.
• Repainting of areas scrolled outside the viewport is reported, but repainting of areas scrolled outside overflow:auto elements and the like is not.
• Repainting in windowed plugins (which is most plugins on Windows and GTK) is not reported.

Possible uses

There are several situations in which MozAfterPaint can be useful.  For example, you can use it in an extension that wants to capture the contents of a window using it in tandem with the canvas.drawWindow() method.  You can also use it while testing web content to add JavaScript instrumentation to measure what gets painted by Firefox and when, in order to optimize your site.

Example

This example adjusts the background color of elements that get painted, making them increasingly darker red each time they're updated.

(function(){
  var store = [];

  window.addEventListener("MozAfterPaint", log, false);

  if ( document.body )
    bind();
  else
    window.addEventListener("load", bind, false);

  function log(e){
    store.push( [(new Date).getTime(), e.clientRects] );
  }

  function bind(){
    document.body.addEventListener("click", function(){
      window.removeEventListener("MozAfterPaint", log, false);

      for ( var pos = 0; pos < store.length; pos++ ) {
        var rects = store[pos][1];

        for ( var i = 0; i < rects.length; i++ ) {
          var rect = rects[i];
          var div = document.createElement("div");

          with (div.style) {
            background = "red";
            opacity = "0.1";
            position = "absolute";
            top = rect.top + "px";
            left = rect.left + "px";
            width = (rect.right - rect.left) + "px";
            height = (rect.bottom - rect.top) + "px";
          }

          document.body.appendChild( div );
        }
      }

      document.body.removeEventListener("click", arguments.callee, false);
    }, false);
  }
})();

The most interesting bits of this example:

• Line 4 installs the event listener to watch for MozAfterPaint events; when the event fires, the log() function gets called.
• Lines 11-13 contain the log() function, which pushes the rectangle list for each update onto a stack for later reference; the actual DOM changes are done after the logging is complete, in order to avoid an infinite loop caused by repaints while logging repaints.
• Line 16 installs a click event listener.  When the user finishes mousing around the window, causing repaints as they hover over various elements, clicking the mouse will cause the actual drawing of the results.
• Line 17, the first line of the click event handler, removes the MozAfterPaint event handler.  This is done before any changes to the document in order to avoid the previously-mentioned infinite loop problem.
• Lines 19-37 add div elements to the DOM for each painted rectangle, overlaying them on top of the painted content with a pale, translucent red background.

To use this example, you can create a bookmarklet containing the following code:

javascript:(function(s){s.src='http://developer.mozilla.org/@api/deki/files/2937/=track.js';document.body.appendChild(s);})(document.createElement('script'));

Determining the scroll direction

If e is a DOMMouseScroll event, e.axis will be equal to:

• undefined prior to Firefox 3.5,
• e.HORIZONTAL_AXIS for horizontal scroll movement or
• e.VERTICAL_AXIS for vertical scroll movement.

Firefox 3.5 note

The MozMousePixelScroll event was added in Firefox 3.5 (Gecko 1.9.1).