XUL Programmer's Reference Manual
Third Draft   
Submit comments and feedback

Zipped HTML version of this doc

Introduction

About This Document
Widget Overview
Reference Information
XUL Syntax
Organization of XUL Interfaces
About This Document
This document is a reference for the XML-based User Interface Language (XUL). Like the interface widgets that XUL describes, this reference is organized hierarchically. For example, many of the widgets inherit from the box widget, which means that they share the attributes described in that area of the reference. Where attributes are inherited, those attributes are italicized in the spelling for that widget. The menubar object and the attributes it inherits from box are a good example of this.

A very small collection of attributes are general to all widgets but not inherited from generalized widgets or tools like <box>. These include attributes like id, with which every XUL widget can be specified. These attributes are defined in a common file. Where common attributes are implemented or used differently by different widgets, the attributes are described with their respective widgets. Values for class vary quite a bit from widget to widget, for example, so class is defined separately for each widget that includes it.

The following sections contain a very brief introduction to XUL. This introduction is intended merely to preface the XUL reference information that this document contains. For more detailed information, see the XUL Programmer's Guide.
 

Widget Overview
The root element in a XUL file and the top level of the interface it defines is the <window> element. All XUL files must contain one and only one window element. The entire XUL interface is defined within this root element.

Typically, a XUL interface is composed of some combination of menubars and toolbars and a content area. A typical XUL file might define a very simple window with the following basic (but too simple to be technically valid) structure:

<window>
  <menubar>
        <menu value="File" />
        <menu value="Edit" />
  </menubar>
  <box>
        <browser />
  </box>
</window>
Each of the children of <window> (i.e., menubar and box) may themselves contain child elements. XUL provides for the absolute positioning and nesting of elements. In this way the interface is built up from the basic window.

The list of XUL widget groups are as follows:

Reference Information
What makes the example XUL snippet in the previous section nearly useless is the lack of detail. The box widget, for example, should be positioned and identified, the window itself should be given a title and various event listeners, and so on. For the most part, this sort of functionality is specified with attributes of the widgets in the XPToolkit. Some of the attributes, such as the box's flex attribute are optional, and are used for laying out the widgets in the interface; other attributes, such as the value of menuitems or the namespace declarations for the window element itself are required, and break the interface if they do not appear. This document describes all of the values and attributes that the XPToolkit widgets support, as well as the genealogy and structure of valid XUL documents. These two main categories of information appear as the Attributes and Common Children for each XUL widget, respectively.
 
 
XUL Syntax
XUL is an XML-based interface definition language. There are a couple of very slight departures from the core XML syntax, but for the most part, the syntax rules are the same. The four cardinal XUL syntax rules are as follows:
  • All events and attributes must be written in lowercase
  • All strings must be double quoted
  • Every XUL widget must use close tags (either <tag></tag> or <tag/>) to be well-formed
  • All attributes must have a value 
Note that XUL is not very forgiving about syntax problems and typos. Most of the time, a XUL file will not display at all if one or another element has been improperly marked up. Ignore these cardinal rules at your peril and vexation!
 
 
Organization of XUL Interfaces
There are a number of additional files that work with the XUL file to create a single window. Collectively, these files are referred to as a package, and include such things as the style sheet for the XUL, a DTD specifying localization strings in the interface, and additional XUL that may overlay the basic XUL file. Menu items and other commands issued in one XUL file can display other XUL files. For example, the Edit Bookmarks command invoked from the navigator.xul file brings up the Bookmarks window, as does the key combination Ctrl + B. In this way, the interface is laid out file by file. 
 
 

Last updated: 3/21/00 Ian Oeschger