Personal tools
You are here: Home / cmgui / Zinc / XUL Overlays

XUL Overlays

One of the main strengths of XUL is the ability to extend GUIs through the use of XUL Overlays.

An overlay is a file containing some content that you overlay onto an existing page. The extra content is added to the existing page. Only a couple of lines need to be added to a page to use an overlay and it is even possible to add one without editing the existing file (through registering it against a page in the browser).

Overlays allow even your browser to be modified. Plugins routinely use overlays to add items to menus, tool bars and the like.

Overlays should be used for generic GUIs that will be used in more than one place. For example every filter preview dialog I write has some widgets to control the preview window. Rather than manually adding all the controls to each dialogs xul file I write a single overlay that can be applied to every dialog. This has the big advantage that if I want to add another control I only have to edit one file to add it to every preview dialog.

For my dialog to apply this overlay I need a few extra lines of code.

Near the top of the file, after the lines declaring it be an xml file we need a line added to tell this page about the overlay

<?xml version="1.0"?>
<?xml-stylesheet href="chrome://global/skin/" type="text/css"?>

<?xul-overlay href="chrome://zinc/content/filters/previewOverlay.xul"?>

The file can then declare its root element (eg dialog) and the various widgets to add.

To add the contents of the overlay in the page I need to specify where they go by adding a xul element which has the same id as a xul element in my overlay. This results in the element on my filter preview dialog page being replaced by the one in the overlay file. Any child elements are also added to my filter preview dialog page.

As all the filter controls are inside a group box element named preview-group-box, I simply add this element to my filter preview dialog

<groupbox id="preview-group-box"/>

The overlay file has the following form

<?xml version="1.0"?>

<overlay id="previewOverlay"
    xmlns:html="http://www.w3.org/1999/xhtml"
    xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">

  <groupbox id="preview-group-box" flex="0"> <caption label="Preview options" />

  LOTS OF STUFF HERE

  </groupbox>

</overlay>