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

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.