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

Table of Contents
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