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).
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.
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.
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
|
||||||||
|
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.
|
||||||||
|
decoration widgets |
||||||||||
|
label |
Static text |
|||||||||
|
image |
Icons and pictures
|
|||||||||
|
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
|
||||||||
|
option |
image |
An item in a select control. |
||||||||
|
text |
An editable text box
|
|||||||||
|
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. |
Glaring omissions at this point are: the process of creating a window from an XML document, scripting, and loading arbitrary widgets.