[This local archive copy is from the official and canonical URL, http://www.mozilla.org/xpfe/dialogs.html; please refer to the canonical source document if possible.]

The Mozilla
Our Mission
Who We Are
Getting Involved
What's New
Module Owners
Blue Sky
Source Code
License Terms
Bug Reports

XUI Window Language

First Draft
30 Nov 98

This document will (eventually) detail the XML DTD used for describing the layout of XPFE windows. See the XUI Language Spec for an overview of language directions. An XPFE window is a top-level application window containing XPFE widgets (by "top-level," we mean an OS window on the desktop, rather than controls and various pieces of top-level windows).


The "resource description" by which XPFE windows are built will be an XML file as outlined in the aforementioned language spec. It will describe the elements (including controls and layout specifications) that make up a window; their attributes and interrelationships. This resource description can be handed to Mozilla for parsing into a W3 compliant DOM, which will subsequently be used as a template to build the window itself. Windows thus constructed will be addressable and scriptable through that underlying DOM. Settings for dialog controls, specifically, can be initialized and queried directly through the DOM both before and after the window is shown.

A window is a conglomeration of individual widgets. A dialog window can be built from button and text edit widgets. A browser window can be built from toolbar and HTML display widgets. Widgets' behaviour is a function of their internal programming, and therefore outside the scope of this document. This document instead covers their placement on windows and interactions via JavaScript.

The window building code will accept standard XML as described by the W3, minus unimplemented features. UI designers are free, subject to the "unimplemented" restriction, to design UIs from any combination of features of the language. For example, the authors encourage a separate description of content (in the XML) and form (applied through XSL and CSS stylesheets) to ease the task of writing for multiple platforms, which may have their own standards regarding placement of controls. Suggestions for accomplishing this will be sprinkled throughout the document. But in the end, the toolkit cares only that you provide it with valid XML.

Design Notes

This spec details an expected direction, and describes design elements the authors believe will be useful for describing a window and its contents. It is necessarily incomplete; it will be filled out as real windows and dialogs are constructed, and shortcomings in the spec are highlighted through actual use. Two glaring shortcomings in the current spec are the missing mechanisms for tying JavaScript and COM objects to dialog elements.

The XML presented to the internal DOM builder will necessarily have platform dependencies. Individual platforms have unique guidelines about, for instance, the placement of OK and Cancel buttons. Windows may also contain grouping elements and other details unique to certain platforms. This is a problem ideally solved by writing one, cross-platform XUI spec defining the window, and a series of platform-specific stylesheets to transform the window into its actual displayable version. Realistically, it will probably often involve maintaining separate XUI specs.

Window Description Language

Windows are not designed to be laid out in terms of absolute positions. They are instead specified by struts and springy elements; a design borrowed from the Java world which lends itself well to layouts which work without change in multiple platform environments.

A window specification is nothing more than a list of widgets and rules for their placement and interactions. Placement and interactions are both under development at time of writing. Placement details will depend on details of the NGLayout window layout manager, as yet unwritten. Interactions will depend on the scripting model, under development. At this time, there is little to say about windows but a list of expected widgets.

Windows are delineated by a <window> element. The window will contain widgets, layout rules, and scripts. Attributes suitable for individual widgets is really a subject for separate papers describing the widgets themselves. But lacking those, several simple widgets are described here.

The elements of a window, and their legal attributes and possible children are currently

XML Element

Allowed Children



(all but option)

Root element for defining a dialog

layout elements


(all but dialog, option)

Children of this item are displayed as a group


integer defining width of delineating box (can be 0)


"horizontal" or"vertical". controls on which axis child elements are laid out.


Layout hints which control interelement spacing. The dimension in which the strut acts is controlled by its bounding "box" element (and without a bounding box, it is useless). Thus, the "height" and "width" attributes are equivalent.



A tab widget responsible for managing a multi-paned dialog. Tab titles are drawn from the child boxes' titles.


"horizontal" or "vertical" controls on which axis the tab is built

decoration widgets


Static text


Icons and pictures


URL to the graphic to be displayed under normal conditions


URL for the disabled graphic


URL for the depressed graphic


URL for the disabled graphic

input control widgets



A command-issuing input control


A radio button input control. Note that other radio buttons in the button group are simply the other radio button siblings in the parent element (which could be a box with border 0).


A checkbox button input control



A list of choices


A special height attribute; it specifies the number of lines of options displayed in the dialog. "1" implies a popup menu. Larger values imply a scrolling list.


"single" or "multiple". Controls the number of items which can be simultaneously selected.



An item in a select control.


An editable text box


A special height attribute; it specifies the number of lines of text in the control.



A collection of command buttons


A "web widget," or HTML display area.

Some attributes may be applied to (nearly) any object. These are layout attributes expected by the window manager. Other attributes listed above are more a concern of the widgets themselves.


Applies to




Optional identifier unique within the dialog for addressing specific elements. This is a convenience for locating the specific item within the document model describing the dialog or dialog set. The ID will also likely be the mechanism by which COM objects are tied to a control for programmability.


dialog, box, label, select, text

The aspect ratio to which the layout manager should try its best to size the element. It describes the element's width as a multiple its height. Thus, the "golden ratio" would be represented as "1.62".



Optional desired height (in twips?) for the element. height and width are taken as minima; elements are resized by their springiness



the desired width


box, button, image, strut

the amount by which the element will expand or compress as its environment is resized, relative to its sibling elements with spring attributes.


dialog, box, label, button, checkbox, option, radio

the text displayed on the dialog for this element.


Spec is incomplete

Glaring omissions at this point are: the process of creating a window from an XML document, scripting, and loading arbitrary widgets.

Copyright © 1998 The Mozilla Organization.