Firebug Overlays

From FirebugWiki
Revision as of 21:55, 2 June 2011 by Honza (Talk | contribs)

Jump to: navigation, search

This page describes all XUL overlays used in Firebug UI.


See description of all individual overlays from the picture loaded by Firefox in the same order.

  • browser.xul Represents the main Firefox UI and global scope that can contain further extensions.
  • browserOverlayWithFrame.xul This is the main Firebug overlay. It's the first thing loaded in Firebug. Scope of this overlay is global and all Firebug files used to live in this global scope (prior 1.7), which could cause collisions with other extensions. Newer versions of Firebug uses this overlay to define an iframe (firebugFrame.xul) that consequently contains all Firebug source files.
  • startButtonOverlay.xul This overlay defines Firebug start button (aka the Status bar icon used in Firefox status bar).
  • browserMenuOverlay.xul This overlay extends various Firefox/SeaMonkey menus and appends Firebug entry to it. This overlay should also contain definition of all commands and shortcuts that are active even if Firebug UI is closed/minimized.
  • firebugOverlay.xul This overlay contains the entire Firebug UI definition.
  • firebugMenuOverlay.xul Defines the Firebug menu. This menu is inserted at various places defined in browserMenuOverlay.xul. This overlay should contain definition of all commands and shortcuts that are active only within Firebug UI (when Firebug UI has focus).
  • editorsOverlay.xul' Extends firebugMenuOverlay.xul with additional items for integration with external IDEs.
  • firebug.xul This is actually not an overlay but a XUL window that is used for detached Firebug UI. The entire UI within this window is created using the firebugOverlay.xul

Extension Developers

Extension developers should (in 99% of cases) overlay the firebugOverlay.xul.

The URL of the file is: chrome://firebug/content/firebugOverlay.xul

Relation Definition

There are two ways how relations between two overlays are defined

  • In chrome.manifest file:
overlay chrome://browser/content/browser.xul  chrome://firebug/content/firefox/browserOverlayWithFrame.xul
  • In the target overlay file:
<?xul-overlay href="chrome://firebug/content/firebugOverlay.xul"?>

Firebug Modules

All Firebug Modules are loaded into the firebugFrame.xul scope. This isolates Firebug API from the global scope and avoids possible collisions with other extensions (they often live in browser.xul scope).

The module loading starts as soon as the firebugOverlay.xul is fully loaded (including bindings defined in bindings.xul) and happens asynchronously.

Accessing Elements

  • Use Firefox.getElementById to get elements from browser.xul scope (Firefox UI).
  • Use$ to get elements from firebugFrame.xul scope (Firebug UI).