Creating Applications with Mozilla

Appendix C. Programmer's Reference

This appendix is an easy-to-use reference that contains information about XUL elements, XBL elements, and event attributes. Details about how each element and event works within a Mozilla application are covered in the rest of the book; to learn how to use XUL or XBL, read Chapter 3 and Chapter 7.

Once you know how to use XUL and XBL, this reference allows you to look up all available tags and elements quickly. Each entry listed below includes a brief description of the element or event, its purpose, what attributes the element or event has, and what other related elements or events you can look at to get more information.

C.1. XUL Element Set

action -- Child element in a XUL template structure that draws content for matched data

arrowscrollbox -- Container box for scrolling contents

autorepeatbutton -- Provides arrows for a scrolling area

binding -- Child element in a XUL template that optionally matches in the data

bindings -- Substructure in a XUL template that collects the optional binding rules

box -- Generic container and layout element

broadcaster -- Notifies elements when a change occurs in the UI

broadcasterset -- Container for broadcaster elements

browser -- Web-content container

button -- A widget that activates some functionality when pressed

caption -- Provides heading for a groupbox element

checkbox -- Indicates a specified feature's on/off state

colorpicker -- Widget used to choose a color

column -- A column in a grid

columns -- Container for the number of columns in a grid

command -- Defines functionality that can be called from multiple sources

commands -- Container for a group of command sets

commandset -- A container for multiple command elements

conditions -- Defines the conditions within a template rule

content -- Binds variables in a template

deck -- Box container that displays one child element at a time

description -- Holder for block of text that can wrap to multiple lines

dialog -- Root element for secondary XUL window

dialogheader -- Styled text heading for UI panel

editor -- Content area for editable web content

grid -- Widget for laying out content in a structured tabular fashion

grippy -- Visible widget used on a grippy bar to expand or collapse a UI region

groupbox -- Box with frame surrounding it

hbox -- Box container whose children are laid out horizontally

iframe -- Web content area

image -- Display of a supported type image

key -- Definition for a keyboard shortcut

keybinding -- Container for a keyset or group of keysets

keyset -- Container for one or more key elements

label -- Simple text display element and label for a control element

listbox -- Used for display of a flat list of items

listcell -- Single cell of a listbox

listcol -- Listbox column definition

listcols -- Container for listbox columns (listcol)

listhead -- Container for column header in list boxes (listheader)

listheader -- Text header for listbox column

listitem -- Listbox row definition

member -- Matches container relationships in which the parent element is given by a container element and the child by a child element

menu -- A menu element for containing menu items

menubar -- Containing element for one or more menus

menuitem -- Single selectable choice in a menu

menulist -- Drop-down list of selectable items

menupopup -- Pop-up container for menu items

menuseparator -- Line separating menu items

observes -- Broadcast event and attribute listener

overlay -- Root element in a separate file that contains reusable XUL content

page -- Root element of XUL file loaded in a content frame

popup -- Box container as child window

popupset -- Container for popup elements

progressmeter -- Visual progress indicator of a time-consuming operation

radio -- Single on/off choice represented as selectable circle

radiogroup -- Framed box for containing radio elements

resizer -- Window-resizing element

row -- Container for grid cells laid out consecutively

rows -- Definition for grid rows

rule -- Defines rules for rendering data as XUL

script -- Declaration of script used in XUL file

scrollbar -- Widget for scrolling in a container

scrollbarbutton -- Button used to move position of scrollbar thumb

scrollbox -- Box for scrolling content

separator -- Bar between elements

slider -- A scrollbar without buttons

spacer -- Blank space separating element

splitter -- Element for dragging and resizing associated elements

stack -- Shows children one on top of one another, all at the same time

statusbar -- Box container for status elements

statusbarpanel -- Single unit of a statusbar

stringbundle -- Holder of localized properties for use in script

stringbundleset -- Container for stringbundle elements

tab -- A single selectable tab of a tabbox

tabbox -- Box container for tab panels

tabbrowser -- Tabbed holder for a set of web content views

tabpanel -- A single panel of a tabbox

tabpanels -- Container for tabpanel elements

tabs -- Container for tab elements

template -- A high-level widget used to build content dynamically from data

textbox -- Accepts text input from user

thumb -- Object used to move content in scrollable area

toolbar -- Holder of buttons for quick-access UI functionality

toolbarbutton -- Specially adapted button for use in a toolbar

toolbarseparator -- Visible separator for elements contained in a toolbar

toolbox -- Optional container for menu bars and toolbars

tooltip -- Pop-up window for context-sensitive help

tree -- Hierarchical holder of information represented as rows

treecell -- A single cell in a tree

treechildren -- The main body of a tree; a container for treeitems

treecol -- A single column of a tree

treecols -- Container for tree columns

treeitem -- A treerow container

treerow -- A single row of a tree

triple -- Substructure of a template that matches RDF statements in the data

vbox -- Box container with vertically laid out children

window -- Root element of a top-level XUL window document

wizard -- Window used to step though a task

wizardpage -- A single panel (step) of a wizard

XUL isn't yet identified as a specification, and the language is still changing. The elements and attributes given here represent a stable subset of the XUL widget set. XML allows you to define new elements and attributes arbitrarily (which is partly what makes a powerful extension like XBL possible) in your markup. Although it's discouraged in practice, Mozilla application developers -- even those working on the Mozilla source itself -- often use this flexibility to manage data in one-off attributes. For example, you may find XUL buttons in the source with attributes like “loading,” which is not part of the XUL specification. In fact, XBL's presence, XML's flexibility, and DOM interfaces blur the distinction between valid XUL and other XML markup. This reference tries to document all widgets in the XUL 1.0 release, any additional attributes these elements have, and their use in Mozilla application development.

All XUL elements have the attributes shown in Table C-1.

Table C-1. Common XUL element attributes

Attribute	Description
align	Specifies how child elements are aligned: baseline, center, end, start, or stretch
allowevents	(Boolean) Specifies whether events should be passed to the child elements
class	The element class of the ; often used for class-based style rules
collapsed	(Boolean) Specifies whether the element is collapsed or displayed; defaults to false
container	(Boolean) Specifies whether the element can have child elements
containment	Used in templates; points to RDF property represented by this XUL element
context	Points to the context menu that this element should use
datasources	Used in templates; points to the RDF data that gets processed
debug	Used for debugging XUL; adds borders to make the element and its layout easily visible
dir	Specifies the direction of the children: normal or reverse
empty	(Boolean) Used for template; specifies that the container has no children
equalsize	Specifies whether the children should be of the same size: always or never
flex	Provides an integer or percent value that specifies the flexibility of an element relative to its siblings within a container
flexgroup	Provides an integer that can group elements and give them the same degree of flexibility
height	Specifies an element's height
hidden	(Boolean) Specifies whether the element is displayed; defaults to false
id	A unique identifier for the element
insertafter	Names the ID of the element after which this element should be overlaid; this attribute works only in overlays
insertbefore	Names the ID of the element which this element should be overlaid before; this attribute works only in overlays
left	Specifies an element's position within a container in pixels to the left
maxheight	Specifies an element's maximum height
maxwidth	Specifies an element's maximum width
minheight	Specifies an element's minimum height
minwidth	Specifies an element's minimum width
observes	Points to a broadcasting element whose state this element observes
ordinal	(Integer) Specifies the element's order within the parent
orient	Shows the element's orientation: vertical or horizontal
pack	Shows how children should be distributed within this container: center, end, or start
persist	Shows which of the element's attributes should be persisted/stored for reuse
position	Shows the element's position within a list (e.g., menuitems in a menu)
ref	Specifies the RDF data root to begin processing (used in templates)
style	Provides style rules for the current element
template	Specifies an existing template to use for this content (used in templates)
tooltip	Specifies a pop up or tooltip ID to be used for this element
tooltiptext	Specifies text to be displayed in the element's tooltip (doesn't require a separate tooltip attribute)
top	Shows the current element's position within a container in pixels from the top
uri	Specifies the root in the XUL where content processing begins (used in templates)
width	Specifies an element's width

C.2. XBL Element Set

binding -- A single XBL binding

bindings -- An XBL document's root element

body -- Container for JavaScript code to be executed by an XBL method

children -- Insertion point for children of a bound element, or inherited binding

constructor -- Container for code to be executed when a binding is created

content -- Container for anonymous content to be inserted into a bound document

destructor -- Container for code to be executed when a binding is destroyed

element -- Insertion point for bound elements in anonymous content

field -- Holder property for simple data

getter -- Script access point for an element's property

handler -- Single event handler for an XBL element

handlers -- Container for event-handler elements

image -- An image resource in a binding

implementation -- Container for binding methods and properties

method -- Script function to be accessed on a binding object

parameter -- Single paramter declaration for a method

property -- Definition of a single binding object property

resources -- Container for list of resources that can be used by a binding

setter -- Change a binding property's value

stylesheet -- Captures an external stylesheet for use by anonymous content

The XBL 1.0 specification published on the mozilla.org web site appeared to be a beacon for application developers. Because the specification was available early in the development process, XBL seemed to be a tighter, more comprehensible language that was easier to learn and master than XUL. Since then, XBL development has strayed from the specification quite a bit, however, and now people consider XBL as opaque as XUL without good documentation that helps people learn and to create a roadmap for use based on continuing development.

This reference section tries to capture basic elements and attributes in XBL. Because it binds rather than creates content, XBL is smaller and inherently more formal than XUL. Nonetheless, as you will see, the language has quite a bit of range and complexity. Each entry in this section describes the XBL element and its purpose, its position in the hierarchy (i.e., which elements it contains and which elements it is contained by), and lists the element's attributes. Chapter 7 introduces XBL and shows how to use it. However, once you are familiar with the basics of XBL, you can consult this reference to find the XBL items you want.

C.3. Event Attributes

onblur -- //FIXME purpose should go here

onbroadcast -- //FIXME purpose should go here

onchange -- //FIXME purpose should go here

onclick -- //FIXME purpose should go here

onclose -- //FIXME purpose should go here

oncommand -- //FIXME purpose should go here

oncommandupdate -- //FIXME purpose should go here

oncontextmenu -- //FIXME purpose should go here

oncreate -- //FIXME purpose should go here

ondblclick -- //FIXME purpose should go here

ondestroy -- //FIXME purpose should go here

ondragdrop -- //FIXME purpose should go here

ondragenter -- //FIXME purpose should go here

ondragexit -- //FIXME purpose should go here

ondraggesture -- //FIXME purpose should go here

ondragover -- //FIXME purpose should go here

onfocus -- //FIXME purpose should go here

oninput -- //FIXME purpose should go here

onkeydown -- //FIXME purpose should go here

onkeypress -- //FIXME purpose should go here

onkeyup -- //FIXME purpose should go here

onload -- //FIXME purpose should go here

onmousedown -- //FIXME purpose should go here

onmousemove -- //FIXME purpose should go here

onmouseout -- //FIXME purpose should go here

onmouseover -- //FIXME purpose should go here

onmouseup -- //FIXME purpose should go here

onoverflow -- //FIXME purpose should go here

onoverflowchanged -- //FIXME purpose should go here

onpopuphidden -- //FIXME purpose should go here

onpopuphiding -- //FIXME purpose should go here

onpopupshowing -- //FIXME purpose should go here

onpopupshown -- //FIXME purpose should go here

onselect -- //FIXME purpose should go here

onunderflow -- //FIXME purpose should go here

onunload -- //FIXME purpose should go here

Events are built-in constructs that are part of the interaction between JavaScript and HTML. These constructs have been crucial to DHTML for many years. They are designed to capture and handle actions triggered by the user, such as a mouse click or the pressing of a certain key. Event handlers have been brought into the world of XUL/XBL and allow dynamic, interactive Mozilla applications. In XUL, events can exist on any attribute, and typically bubble up through the hierarchy. An event attribute of the empty string generates a JS strict warning (if this is turned on in the user preferences), and removing an event attribute from a XUL event does not remove the event listener (although it does in HTML).

The events are listed in the form on<eventName>, which is how events are used as attributes on XUL elements. The attribute contains lines of script or a function call, when a script is too long. Here is an example of an event attribute that carries out a function each time a menulist value changes:

<menulist id="eventList" editable="true" flex="1" onchange="addEvent(this)">

The syntax is different in XBL. Here the event is specified as the value of the name attribute, which is attached to the handler element. One or more of these elements can optionally be contained in a binding. The given value is the event's name, minus the “on” prefix. The executed code is contained in the body of the handler inline, or in the action attribute, as shown in this example:

<handler name="focus" action="this.activate( )"/>

Chapter 7 provides a closer look at events in XBL. All the events listed here are available for use in XUL and XBL.