XUL 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 XUL 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).

Scope

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

Attributes

window

(all but option)

Root element for defining a dialog

layout elements

box

(all but dialog, option)

Children of this item are displayed as a group

border

integer defining width of delineating box (can be 0)

format

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

strut

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.

tab

box

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

format

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

decoration widgets

label

Static text

image

Icons and pictures

normal

URL to the graphic to be displayed under normal conditions

disabled

URL for the disabled graphic

depressed

URL for the depressed graphic

disabled

URL for the disabled graphic

input control widgets

button

image

A command-issuing input control

radio

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).

checkbox

A checkbox button input control

select

option

A list of choices

lines

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.

type

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

option

image

An item in a select control.

text

An editable text box

lines

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

toolbar

button

A collection of command buttons

web

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.

Attribute

Applies to

Meaning

id

(all)

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.

aspect

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".

height

(all)

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

width

(all)

the desired width

springiness

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.

title

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

the text displayed on the dialog for this element.

Weaknesses

Spec is incomplete

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