XUL Overlay Usage in Firefox

xul_overlay_usage.md

XUL Overlays Usage

There are three ways to use an overlay 1) explicitly, 2) dynamically, and 3) runtime dynamic.

Overlays Used

Explicit

Loaded using <?xul-overlay in xul file.

https://searchfox.org/mozilla-central/search?q=%3C%3Fxul-overlay&case=false&regexp=false&path=*.xul

Used	Overlay
4	chrome://browser/content/baseMenuOverlay.xul
2	chrome://browser/content/downloads/allDownloadsViewOverlay.xul
6	chrome://browser/content/macBrowserOverlay.xul
2	chrome://browser/content/places/editBookmarkOverlay.xul
10	chrome://browser/content/places/placesOverlay.xul
1	chrome://communicator/content/tasksOverlay.xul
17	chrome://global/content/editMenuOverlay.xul
1	chrome://global/content/globalOverlay.xul
1	chrome://pippki/content/CAOverlay.xul
1	chrome://pippki/content/certDump.xul
1	chrome://pippki/content/MineOverlay.xul
1	chrome://pippki/content/OrphanOverlay.xul
1	chrome://pippki/content/OthersOverlay.xul
1	chrome://pippki/content/viewCertDetails.xul
1	chrome://pippki/content/WebSitesOverlay.xul

Dynamically

Loaded using % overlay in jar manifest file.

https://searchfox.org/mozilla-central/search?q=%5C%25%5Cs%2Boverlay&case=false&regexp=true&path=*.mn

Used	Overlay
1	chrome://browser/content/softwareUpdateOverlay.xul
2	chrome://browser/content/viewSourceOverlay.xul
1	chrome://browser/content/report-phishing-overlay.xul
1	chrome://browser/content/places/downloadsViewOverlay.xul
2	chrome://layoutdebug/content/layoutdebug-overlay.xul

Runtime Dynamic

Loaded using document.loadOverlay or ensureOverlayLoaded (which calls document.loadOverlay).

https://searchfox.org/mozilla-central/search?q=document.loadOverlay&case=false&regexp=false&path= https://searchfox.org/mozilla-central/search?q=symbol:%23ensureOverlayLoaded&redirect=false

Used	Overlay
1	chrome://browser/content/places/editBookmarkOverlay.xul
1	chrome://browser/content/downloads/downloadsOverlay.xul
1	chrome://browser/content/downloads/indicatorOverlay.xul

Note: There's a usage in preferences, but Myk will be removing that.

Overlay Details

What does an overlay contain?

Explicit

• chrome://browser/content/baseMenuOverlay.xul
  • Loads: utilityOverlay.js
  • Defines: menupopup id="menu_ToolsPopup", menu id="helpMenu", keyset id="baseMenuKeyset", stringbundleset id="stringbundleset"
• chrome://browser/content/downloads/allDownloadsViewOverlay.xul
  • Loads: downloads.css, allDownloadsViewOverlay.css, allDownloadsViewOverlay.js, contentAreaUtils.js
  • Defines: richlistbox id="downloadsRichListBox", commandset id="downloadCommands", menupopup id="downloadsContextMenu"
• chrome://browser/content/macBrowserOverlay.xul
  • Loads: skin/, places.css, editMenuOverlay.xul, baseMenuOverlay.xul, baseMenuOverlay.xul, placesOverlay.xul, inline JS
  • Defines: popupset
  • Includes: browser-doctype.inc, global-scripts.inc, browser-sets.inc, browser-menubar.inc
• chrome://browser/content/places/editBookmarkOverlay.xul
  • Loads: editBookmarkOverlay.css, places.css
  • Defines: vbox id="editBookmarkPanelContent" (whole UI for editing bookmarks)
• chrome://browser/content/places/placesOverlay.xul
  • Loads: globalOverlay.js, utilityOverlay.js, , controller.js, treeView.js
  • Defines: tooltip id="bhTooltip", commandset id="placesCommands", menupopup id="placesContext"
• chrome://communicator/content/tasksOverlay.xul
  • It doesn't appear this file exists anymore!
• chrome://global/content/editMenuOverlay.xul
  • Loads: editMenuOverlay.js
  • Defines: commandset id="editMenuCommands", keyset id="editMenuKeys", menu id="menu_edit"
• chrome://global/content/globalOverlay.xul
  • It doesn't appear this file exists anymore!
• chrome://pippki/content/CAOverlay.xul
  • Loads: skin/
  • Defines: vbox id="CACerts" (CACerts UI)
• chrome://pippki/content/certDump.xul
  • Defines: vbox id="certPrettyPrint" (Cert DUMP UI)
• chrome://pippki/content/MineOverlay.xul
  • Defines: vbox id="myCerts" (My Cert UI)
• chrome://pippki/content/OrphanOverlay.xul
  • Defines: vbox id="OrphanCerts" (Orphan cert UI)
• chrome://pippki/content/OthersOverlay.xul
  • Defines: vbox id="othersCerts" (Other cert UI)
• chrome://pippki/content/viewCertDetails.xul
  • Defines: vbox id="general_info" (Details cert UI)
• chrome://pippki/content/WebSitesOverlay.xul
  • Defines: vbox id="webCerts" (Website cert UI)

Dynamically

• chrome://browser/content/softwareUpdateOverlay.xul
  • Includes: browserMountPoints.inc
  • TODO
• chrome://browser/content/viewSourceOverlay.xul
  • Defines: window id="viewSource", menubar id="viewSource-main-menubar"
• chrome://browser/content/report-phishing-overlay.xul
  • Defines: broadcasterset id="mainBroadcasterSet", menupopup id="menu_HelpPopup"
• chrome://browser/content/places/downloadsViewOverlay.xul
  • Includes: inline js
  • Defines: window id="places", deck id="placesViewsDeck", toolbar id="placesToolbar"
• chrome://layoutdebug/content/layoutdebug-overlay.xul
  • Defines: menupopup id="taskPopup", menupopup id="menu_ToolsPopup"

Runtime Dynamic

• chrome://browser/content/places/editBookmarkOverlay.xul
  • see above
• chrome://browser/content/downloads/downloadsOverlay.xul
  • Defines: commandset, popupset id="mainPopupSet"
• chrome://browser/content/downloads/indicatorOverlay.xul
  • Defines: toolbarbutton id="downloads-button"

How Overlay Elements Are Merged

Information on merging http://mb.eschew.org/12

I tried to break down how the elements are merged.

• id-include: the element is simply included in the master document and the overlay defines all of the structure
• id-advanced: the element in the master document and also has children
• no id: the element is simply appended to the master document (these aren't listed below, look above for elments without id's)

Elements can all change position with these attributes:

• position
  • not used
• insertbefore
  • report-phishing-overlay.xul
• insertafter
  • layoutdebug-overlay.xul
• removeelement
  • not used

Note: some usages also add additional attributes to the id-included element.

• menupopup id="menu_ToolsPopup"
  • id-advanced
• menu id="helpMenu"
  • id-advanced
• keyset id="baseMenuKeyset"
  • id-include and id-advanced
• stringbundleset id="stringbundleset"
  • ???
• richlistbox id="downloadsRichListBox"
  • id-include
• commandset id="downloadCommands"
  • id-include
• menupopup id="downloadsContextMenu"
  • id-include (note: there's potentially an id-advanced in downloadsOverlay.xul, need to look into how these all interact)
• vbox id="editBookmarkPanelContent" (whole UI for editing bookmarks)
  • id-include w/ few attributes
• tooltip id="bhTooltip"
  • id-include
• commandset id="placesCommands"
  • id-include and one id-advanced
• menupopup id="placesContext"
  • id-include
• commandset id="editMenuCommands"
  • id-include
• keyset id="editMenuKeys"
  • id-include and few id-advanced
• menu id="menu_edit"
  • id-advanced
• vbox id="CACerts" (CACerts UI)
  • id-include w/ attribute
• vbox id="certPrettyPrint" (Cert DUMP UI)
  • id-include
• vbox id="myCerts" (My Cert UI)
  • id-include w/ attribute
• vbox id="OrphanCerts" (Orphan cert UI)
  • id-include w/ attribute
• vbox id="othersCerts" (Other cert UI)
  • id-include w/ attribute
• vbox id="general_info" (Details cert UI)
  • id-include
• vbox id="webCerts" (Website cert UI)
  • id-include w/ attribute
• window id="viewSource"
  • lots going on here
• menubar id="viewSource-main-menubar"
  • lots of id-advanceds here
• broadcasterset id="mainBroadcasterSet"
  • id-advanced
• menupopup id="menu_HelpPopup"
  • insert before, also seems fishy
• window id="places"
  • id-advanced, basically id-include
• deck id="placesViewsDeck"
  • id-advanced, basically id-include
• toolbar id="placesToolbar"
  • id-advanced, basically id-include
• menupopup id="taskPopup"
  • no matching id (orphan)
• menupopup id="menu_ToolsPopup"
  • id-include
• popupset id="mainPopupSet"
  • ??? needs investigation
• toolbarbutton id="downloads-button"
  • attribute change (note in there about perf and lazy load)