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.

XUL Element Set

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

false

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

action

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

Additional Attributes

None.

Description

The action element defines the content drawn into the XUL when the rules defined in a template's conditions structure are met. The content to be drawn is an action element's child.

arrowscrollbox

Container box for scrolling contents

Additional Attributes

None.

Description

A box with arrows that allow scrolling through its contents. The box scrolls when the user's mouse hovers over the arrows. It is commonly used in large menus that overflow a provided space.

autorepeatbutton

Provides arrows for a scrolling area

Additional Attributes

scrolldir

Description

This element is used to internally bind the arrowscrollbox element and it surrounds a scrollbox area to provide the navigation arrows. The scrolldir attribute, which can have a value of up or down, determines the direction of the arrows.

binding

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

Additional Attributes

predicate, object, subject, template, rule, condition, action, bindings

Description

In contrast to the rule element, which must match to trigger the action, binding allows you to create an optional rule for data matching.

bindings

Substructure in a XUL template that collects the optional binding rules Additional Attributes None.

Description

Individual bindings must be defined with a bindings parent to be a part of a valid XUL template.

box

Generic container and layout element

Additional Attributes

None.

Description

This element can contain any type of content and any number of elements. Its default orientation is horizontal, unless otherwise overridden by the orient attribute, and the contents are laid out in the order they appear in the file. The box is the basic layout unit in a XUL interface. Many, if not most, XUL elements inherit from box.

broadcaster

Notifies elements when a change occurs in the UI Contained by broadcasterset

Additional Attributes

checked, accesskey, oncommand, value, label, disabled

Description

A broadcaster acts as a host for other elements, detecting changes that occur in the UI and notifying those elements of the changes via attribute changes. The elements that use it are said to observe the broadcaster. The observed attribute is typically the oncommand attribute, but can be any attribute.

broadcasterset

Container for broadcaster elements Contains broadcaster

Additional Attributes

None.

Description

The purpose of this nonvisible element is to group a set of broadcasters logically. The XUL document can contain one or multiple sets.

browser

Web-content container

Additional Attributes

src, name, content, onclick, type, disablehistory, disablesecurity

Description

A content widget or frame used to load in web content for read-only viewing. This element is used by the main Mozilla browser, so it handles HTML, XML, and plain text. To load a page, set the src attribute to a URL. Other features include the attachment of a context menu that uses the context attribute and various methods and properties exposed for web navigation and display.

button

A widget that activates some functionality when pressed

Additional Attributes

accesskey, dir, disabled, dlgType, group, image, label, orient, type, value

Description

A button typically gives the user an option to click it to carry out JavaScript code routine(s). This code can be a function call or inline script and is contained in the onclick attribute or the oncommand event handler. It can optionally have an image associated with a URL contained in the image attribute or by using the list-style-image CSS property. There are various types of buttons, determined by the type attribute, including checkbox, menu, menu-button, and radio. Leave this out for a normal button.

caption

Provides heading for a groupbox element Contained by groupbox, radiogroup

Additional Attributes

None.

Description

This element is most commonly used to provide a text label for a groupbox by setting the label attribute. However, it is flexible about other content it can contain, such as checkboxes or radio buttons.

checkbox

Indicates a specified feature's on/off state

Additional Attributes

accesskey, label, checked

Description

A checkbox appears as a small box that can be checked on or off. When checked on or off, the checked attribute is set to true or false. It can be set initially for a default value. To associate text with a checkbox, set the label attribute.

colorpicker

Widget used to choose a color Additional Attributes onchange, type, id, palettename

Description

When activated, this widget presents a choice of colors to the user in a grid format. The user selects a color by clicking on it. The palettename attribute determines the displayed colors. Three values for this attribute represent three types of palettes: standard, grey, and web.

JavaScript Methods and Properties

color

column

A column in a grid Contained by columns

Additional Attributes

None.

Description

column is a column entry in a grid, of which there can be one or more contained in a columns element. The content of cells in a column is determined by the children of each row element.

columns

Container for the number of columns in a grid Contains column

Additional Attributes

None.

Description

The children of this element are one or more column elements, the number of which determines the actual number of grid columns.

command

Defines functionality that can be called from multiple sources Contained by commandset

Additional Attributes

disabled, accesskey, observes, label, checked

Description

The command element provides a place to organize functionality used in more than one place in the interface-from a context menu, a keyboard shortcut, and a regular menu, for example. The element is identified and shared by using its ID value and an interested element's (i.e., a menu that wants the command) observes attribute. It also typically calls a JavaScript command from its oncommand event handler.

commands

Container for a group of command sets

Additional Attributes

None.

Description

commandsets no longer need to be contained within a commands element. Still, the commands group can help you organize your code and user overlays to import commands, especially related sets.

commandset

A container for multiple command elements Contains command

Additional Attributes

oncommandupdate, commandupdater, events

Description

An invisible, document-level element that acts as a logical grouping for commands or other command sets.

conditions

Defines the conditions within a template rule Contains content, member, triple

Additional Attributes

None.

Description

Within a template, the conditions, action, and sometimes the bindings elements comprise a single rule. The children of the conditions element must be matched to the processed data for that rule's action to make content.

content

Binds variables in a template Contained by conditions

Additional Attributes

None.

Description

The content element is the portion of a template's conditions element that associates a variable, often representing a URI (e.g., <content uri="?uri"/>) with the data.

deck

Box container that displays one child element at a time Additional Attributes selectedIndex

Description

deck uses the attribute selectedIndex to determine which child element to display. The others are hidden until they are displayed by index. deck is often used dynamically via the DOM to cycle through child elements, such as buttons.

description

Holder for block of text that can wrap to multiple lines

Additional Attributes

crop, onmouseover, onmouseout, value

Description

The description element replaces <html:label> and other HTML-namespaced elements to wrap text in XUL interfaces. Text in a description can be defined as content with the open and close tags or provided in the value attribute. Note that the text does not wrap when placed in the value attribute.

dialog

Root element for secondary XUL window

Additional Attributes

ondialogaccept, ondialogcancel, ondialoghelp, onunload, onload, title, buttons, windowtype, persist, y, x, screenY, screenX

Description

dialog is a version of the window element built for displaying a secondary dialog window in the application. Like window, dialog is the root element in a XUL file. Event handlers such as ondialogaccept and ondialogcancel are included as conveniences for handling user input.

dialogheader

Styled text heading for UI panel Contained by dialog

Additional Attributes

title, description

Description

This is a formatted horizontal panel that contains text specified by the title attribute. This element is the heading that appears at the top of the right panel in the Mozilla global preferences dialog.

editor

Content area for editable web content

Additional Attributes

src

Description

This high-level widget edits text and HTML. contentDocument is a reference to the document contained within the editor.

JavaScript Methods and Properties

contentDocument

grid

Widget for laying out content in a structured tabular fashion Contains rows, columns

Additional Attributes

None.

Description

The number of column elements that are placed in rows determines the number of columns and the content for each row is placed in the row element. The number of row children must correspond to the number of columns.

grippy

Visible widget used on a grippy bar to expand or collapse a UI region Contained by splitter

Additional Attributes

None.

Description

grippy appears as a child of a splitter and provides the little "handle" that opens and closes the sidebar and other collapsible elements in the interface.

groupbox

Box with frame surrounding it Contains caption

Additional Attributes

None.

Description

The border that appears around and organizes elements in the interface (e.g., in dialogs where selectable elements are grouped together); often comes from a groupbox parent.

hbox

Box container whose children are laid out horizontally

Additional Attributes

None.

Description

The hbox element is a shorthand for <box orient="horizontal">. It is the preferred way to achieve horizontal orientation in box layout.

iframe

Web content area

Additional Attributes

name, src, type

Description

Like browser, iframe allows you to display web content, XML, and other data using the src attribute, but has less intrinsic browsing functionality available (such as browser history). You can use any number of iframes in a document.

image

Display of a supported type image

Additional Attributes

src

Description

The XUL image is analogous to the HTML <img> element. The supported types in Gecko are PNG, JPG, GIF, and BMP.

key

Definition for a keyboard shortcut Contained by keyset

Additional Attributes

modifiers, command, key , keycode, observes

Description

A key is often defined with a commandkey and a modifier (e.g., P + Ctrl), and uses an oncommand event handler to fire the given command when invoked.

keybinding

Container for a keyset or group of keysets Contains keyset

Additional Attributes

None.

Description

This element is used in an overlaid file to contain a group of platform-specific key sets. It uses the ID attribute to overlay itself into XUL files that pick up sets of key bindings.

keyset

Container for one or more key elements Contains key

Additional Attributes

None.

Description

key elements no longer need to be contained within a keyset parent. Still, keysets can help organize groups of keys-particularly related ones.

label

Simple text display element and label for a control element

Additional Attributes

control, for, accesskey, crop, value

Description

This text element can just display text in the UI. Unlike the description element, the text will not wrap. If you use it with a control element (the association occurs through the for attribute, the value of which must match the element's id) such as a textbox, the focus moves to the control element when the label is clicked.

listbox

Used for display of a flat list of items

Additional Attributes

datasources, sortResource, sortDirection, rows, seltype, ref

Description

listbox is a lightweight tabular display widget. Unlike tree, it cannot handle nested rows. It does support multiple columns, however. It is easy to use and renders content very quickly.

listcell

Single cell of a listbox Contained by listitem

Additional Attributes

label, flexlabel, crop, disabled, image, checked

Description

The listcell is the element within a listbox that actually displays data.

listcol

Listbox column definition Contained by listcols

Description

This element represents a column in a listbox.

listcols

Container for listbox columns (listcol) Contained by listbox Contains listcol

Description

This element contains any number of individual listbox columns.

listhead

Container for column header in list boxes (listheader) Contained by listbox Contains listheader

Description

The listhead element is analogous to the HTML thead element, and contains the header cells for an XUL listbox table.

listheader

Text header for listbox column Contained by listhead

Additional Attributes

sortActive, sortDirection, resource, sortable

Description

The listheader element displays the header text.

listitem

Listbox row definition Contained By listbox Contains listcell

Additional Attributes

value, description, accesskey, label, context, type, name

Description

A listitem is a row in a listbox. The number of listcell children corresponds to the number of columns in the listbox.

member

Matches container relationships in which the parent element is given by a container element and the child by a child element Additional Attributes container, child

Description

The member element is part of the conditional structure in a XUL template. It creates a rule by which parent-child relationships are matched and used as a basis for drawing content in the XUL.

menubar

Containing element for one or more menus Contains menu

Additional Attributes

None.

Description

menubar is a special box for containing menus (though it can include other content). By default it has a grippy for expanding and collapsing the menubar.

menuitem

Single selectable choice in a menu Contained by menupopup

Additional Attributes

label, accesskey, crop, image, disabled, checked

Description

The menuitem is the basic element used to display a single item in a menu (e.g., <menuitem label="File"/>).

menulist

Drop-down list of selectable items Contains menupopup

Additional Attributes

None.

Description

The menulist displays a list of menuitems, the selected one of which is displayed in the menulist itself. It is a type of drop-down menu.

menupopup

Pop-up container for menu items Contained By menu, menubutton, menulist Contains menuitem

Additional Attributes

popupalign, datasources, onpopupshowing, sortResource, onpopuphiding, sortDirection, context, position, popupanchor, ref

Description

The menupopup contains the actual menu items defined for a menu and acts much like the popup element to show the window with a list of choices.

menuseparator

Line separating menu items Contained By menupopup

Additional Attributes

type

Description

The menuseparator is a line through the menu that divides menu items into different groups. You can use the position attribute on the menuseparator to make sure it appears in a particular place, or you can use the common attribute insertAfter.

observes

Broadcast event and attribute listener

Additional Attributes

element, attribute, onbroadcast

Description

The observes element observes the state of a broadcasting element and its attributes. observes can be a separate element, defined as a child of the interested observer, or it can be an attribute on any element that wants to watch changes in a broadcasting element.

overlay

Root element in a separate file that contains reusable XUL content

Additional Attributes

xmlns, title

Description

Like page, window, dialog, and wizard, overlay is a XUL document's root element. Overlay documents contain content blocks that are overlaid dynamically at runtime into XUL content whose IDs match theirs. For example, a menupopup with the ID "file" and a menuitem child in an overlay adds that new menuitem into any menupopup with the ID "file" that it finds in the base XUL.

popup

Box container as child window

Additional Attributes

onpopupshowing, onpopuphiding

Description

popup is a pop-up window that can be hooked up to any UI content. It is often used for context menus and invoked by elements that use its ID attribute in their popup or context attribute.

popupset

Container for popup elements

Additional Attributes

None.

Description

While not strictly necessary as a container for the popup element, popupset helps you organize and overlays groups of popups.

progressmeter

Visual progress indicator of a time-consuming operation

Additional Attributes

value, mode

Description

This high-level widget uses its value attribute to fill in a meter that usually represents how long a particular task takes. You can change the value attribute dynamically to update the fill or set the mode to "undetermined" (as opposed to the default "determined" mode) to display a busy meter that doesn't chart actual progress.

radio

Single on/off choice represented as selectable circle Contained By radiogroup

Additional Attributes

selected, group, label, accesskey, value

Description

Within a radiogroup element, a single radio widget is selected to indicate user choice. radio elements can also be used singularly to check an option on or off in the interface.

radiogroup

Framed box for containing radio elements Contains radio

Additional Attributes

disabled

Description

The radiogroup makes all radio elements within it belong to a single group from which only a single element can be selected.

resizer

Window-resizing element

Additional Attributes

direction

Description

A bar that changes the cursor when hovered over to signify that the bar can be dragged to resize the a window. The direction attribute specifies which way the window is resized, and can have values such as topleft, top, right, and bottomright. For example, a value of bottomleft resizes the window down and to the left.

row

Container for grid cells laid out consecutively Contained By rows

Additional Attributes

None.

Description

row is a single row in a grid. It is analogous to the <TR> element in HTML.

rows

Definition for grid rows Contains row

Additional Attributes

None.

Description

The rows element is a child of the grid element that contains any number of individual row elements. It is a sibling of columns within the grid.

rule

Defines rules for rendering data as XUL Contained by template

Additional Attributes

rdf:type, parent, isempty, iscontainer

Description

The children of the rule element define a rule: the conditions stated in the conditions element must be met, the bindings provides optional matching, and the content in the action element is rendered if the rule is matched.

script

Declaration of script used in XUL file

Additional Attributes

src, type

Description

The script element can contain script content (e.g., <script>alert("it")</script>) and can also import scripts in JavaScript files, in which case the src attribute is used. The type for JavaScript is application/x-javascript, and the src attribute may also use chrome:// type URLs to point at JavaScript in the chrome.

scrollbar

Widget for scrolling in a container Contains scrollbarbutton, slider

Additional Attributes

curpos, increment, maxpos, pageincrement

Description

The scrollbar element uses the curpos and maxpos attributes to determine where the scrollbarbutton element is drawn within its length. increment specifies how much the scrollbar should move on user input. pageincrement specifies how many pages it should move.

scrollbarbutton

Button used to move position of scrollbar thumb Contained By scrollbar

Additional Attributes

sborient, type

Description

The scrollbarbutton can use its src attribute to point to an image that should be drawn over it.

scrollbox

Box for scrolling content

Additional Attributes

crop

Description

The scrollbox is a regular box with scrollbars that display automatically when the content inside the box overflows the size of the box itself.

separator

Bar between elements

Additional Attributes

None.

Description

The separator is a general-purpose divider. In menus, use menuseparator.

slider

A scrollbar without buttons

Additional Attributes

curpos, increment, maxpos, pageincrement

Description

The slider element provides simpler user input-a thumb button and no arrows-for scrolling large content. Like scrollbar, it uses curpos and maxpos to display its position.

spacer

Blank space separating element

Additional Attributes

None.

Description

This element is a general-purpose blank space. The use of a spacer with flex to take up available space within a box and shrink its siblings is a staple of the box layout model that XUL uses.

splitter

Element for dragging and resizing associated elements

Additional Attributes

persist, state

Description

Users can drag a splitter to resize an associated element or panel that holds content and click a splitter to collapse the specified element within a box. To specify which element you manipulate with a splitter, set this element's collapse attribute accordingly: before to control the element before it in the parent; after to control the element after it.

stack

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

Description

In contrast to the deck, stack is a box that displays all of its children at once. You can use a stack to display elements and blend them together, as when you use different stack children as background images and visual layers.

statusbar

Box container for status elements Contains statusbarpanel

Additional Attributes

None.

Description

In Mozilla, the statusbar is placed at the bottom of the main windows, where it is hooked up to the window.status property and can be used to display status text. It is divided into panels, one of which is the taskbar where some main component icons are displayed.

Additional Attributes

persist, label

Description

statusbarpanels are subdivisions of the statusbar at the bottom of main browser windows. They can contain other content, text using the label attribute and an image using the list-style-image CSS style rule.

stringbundle

Holder of localized properties for use in script Contained by stringbundleset

Additional Attributes

src

Description

Like the script element, stringbundle uses the src attribute to locate a file for use. In this case, the files is a string bundle (properties file) that is used for holding localizable strings used in the UI.

Additional Attributes

None.

Description

stringbundleset is an optional container for groups of stringbundle elements. Like commandset use for commands, stringbundle organizes sets of related stringbundles, particularly when those sets are overlaid into the UI.

tab

A single selectable tab of a tabbox Contained by tabs

Additional Attributes

accesskey, crop, disabled, label, image

Description

Individual tabs correspond to panels in the tabbox.

tabbox

Box container for tab panels Contains tabs, tabpanels

Additional Attributes

None.

Description

tabbox is the container in which the tabs and tabpanels are defined. It lays out children like a regular box to the orientation specified, which defaults to vertical. The panels are defined in the tabpanels element.

tabbrowser

Tabbed holder for a set of web content views

Additional Attributes

contentcontextmenu, contenttooltip

Description

tabbrowser derives from the browser widget. Like browser, it lets you view HTML pages and other content. tabbrowser has additional methods on it that manage tabbed windows (e.g., addTab, enterTabbedMode).

tabpanel

A single panel of a tabbox Contained by tabpanels Contains XUL content

Additional Attributes

None.

Description

A tabpanel is one of the special box elements that correspond to a particular tab within a tabbox. It can hold any XUL content to be displayed on a particular tab panel.

tabpanels

Container for tabpanel elements Contained by tabbox Contains tabpanel, box

Additional Attributes

None.

Description

The tabpanels container corresponds to the tabs element that holds all individual tabs, and is a container for the tabpanel associated with that tab. This child panel can be either an optional tabpanel element that holds XUL content, or just the XUL content.

tabs

Container for tab elements Contained by tabbox Contains tab

Additional Attributes

None.

Description

This element is a required container for individual tabs.

template

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

Additional Attributes

xmlns:nc, xmlns:chrome

Description

The template element has several rule children, each of which defines rules for matching data in a datasource and rendering that data as XUL content. A template is defined within the regular XUL content.

textbox

Accepts text input from user

Additional Attributes

multiline, maxlength, disabled, readonly, type, size

Description

textbox is a user-input element. Expand it beyond its single-line default by setting multiline to true. You can also disable it, and set its size.

thumb

Object used to move content in scrollable area

Additional Attributes

sborient

Description

The thumb element appears in the slider and the scrollbar.

toolbar

Holder of buttons for quick-access UI functionality Contains toolbarbutton, toolbarseparator

Additional Attributes

grippyhidden, tborient, tbalign, tbpack

Description

Toolbars usually have horizontal orientation at the top of an application window, but this does not have to be the case. You can use the orient attribute to set it vertically and run its content down and not across. While the most common content for a toolbar is buttons and menus, it can contain any type of content.

toolbarbutton

Specially adapted button for use in a toolbar Contained by toolbar

Additional Attributes

accesskey, dir, disabled, dlgType, group, image, label, orient, type, value

Description

This is a button designed especially for a toolbar, with special stylings for this purpose. The current theme determines a toolbarbutton's look. See toolbar.css in the theme JARs to view styles and bindings for this common button.

toolbarseparator

Visible separator for elements contained in a toolbar Contained by toolbar

Additional Attributes

None.

Description

Like the menuseparator in a menu, toolbarseparator divides elements in a toolbar.

toolbox

Optional container for menu bars and toolbars Contains menubar, toolbar

Additional Attributes

None.

Description

toolbox can organize several toolbars into one parent element. toolbox inherits from box, so you can use box layout attributes to control the positioning and layout of toolbars within.

tooltip

Pop-up window for context-sensitive help

Additional Attributes

noautohide, onpopupshowing, onpopuphiding, position

Description

The tooltip element defines text to be displayed. It is associated by ID with elements that want to use its content in the pop ups they display. However, elements can also use the tooltip attribute to display a tooltip more directly for themselves.

tree

Hierarchical holder of information represented as rows Contains treecols, treechildren

Additional Attributes

multiple, datasources, enableColumnDrag, containment, sortResource, sortDirection, border, seltype, sortActive, flags, context, persist, hidecolumnpicker

Description

The tree element is a high-level widget that displays tabular data. More complex than listbox, tree allows you to define nested content, different views, and data display, and provides methods that sort and manipulate its contents.

treecell

A single cell in a tree Contained by treerow

Additional Attributes

src, indent, observes, url, value, label, sortActive, sortDirection, tag, mode, resource, allowevents, properties

Description

The treecell contains the actual content to be displayed in a tree. That content can be in the form of a value for the label attribute. It can also be content in the treecell's start and end tags (e.g., <treecell>data</treecell>).

treechildren

The main body of a tree; a container for treeitems Contains treeitem Contained by tree

Additional Attributes

open

Description

The treechildren element defines the subset of the tree where the content is actually contained (in contrast to treecols, which defines aspects of the layout).

treecol

A single column of a tree Contained by treecols

Additional Attributes

sort, resource, primary, sortSeparators, label, sortActive, sortDirection, hideheader, accesskey, type

Description

The treecol typically does not contain content. Instead, it defines the header for the columns whose contents are defined in the treerows.

treecols

Container for tree columns Contained by tree Contains treecol

Additional Attributes

None.

Description

This element is a container for a group of treecol elements, or columns, in a tree. A tree should have only one treecols.

treeitem

A treerow container Contained by treechildren Contains treerow

Additional Attributes

rdf:type, container, open

Description

The treeitem element is a container for a treerow, and makes treerow a selectable element within the tree.

treerow

A single row of a tree Contained by treeitem Contains treecell

Additional Attributes

properties

Description

Contained within a treeitem, this element represents a single row of a tree.

triple

Substructure of a template that matches RDF statements in the data

Additional Attributes

predicate, object, subject

Description

The children of triple-predicate, object, and subject-match RDF statements that appear in the data processed in the template.

vbox

Box container with vertically laid out children

Additional Attributes

None.

window

Root element of a top-level XUL window document

Additional Attributes

windowtype, xmlns:rdf, xmlns:web, titlepreface, onload, onunload, xmlns, titlemodifier, xmlns:html, title, onclose, titlemenuseparator, contenttitlesetting, y, x, screenY, screenX

Description

The window is an XUL document's basic root element. The contents of a XUL document, including the script elements, commands, keys, and broadcasters, appear as children of the window. Overlays, the XML and stylesheet-processing instructions, and the DOCTYPE declaration appear before and outside a document's root element. The window should have a unique ID and use minimally, the XUL namespace to identify markup elements as XUL: xmlns=" http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul".

wizard

Window used to step though a task Contains wizardpage

Additional Attributes

onwizardaccept, onwizardcancel, xmlns, onwizardfinish, xmlns:nc

Description

Like dialog, wizard is a specialized version of the window root element. It easily creates multistep dialog windows that help users set up accounts, password data, and other customizable information. A wizard contains one or more wizardpages.

wizardpage

A single panel (step) of a wizard Contained by wizard

Additional Attributes

label, pageid, onpageadvanced, onpageshow, onpagecancel

Description

The wizardpage can contain arbitrary XUL content. One or more wizardpages are defined in a wizard window. The intrinsic functionality of a wizard window allows you to step through wizardpages by setting the onpageshow and onpagecancel event handlers on individual pages and using the onwizardaccept and onwizardcancel event handlers on the wizard parent element.

XBL Element Set

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.

binding

A single XBL binding Contains content, implementation, handlers Contained by bindings Attributes id, extends, display, applyauthorstyles, styleexplicitcontent

Description

This element defines a single XBL binding that can be attached to a bound document. It enables the creation of self-contained widgets that can contain content, implementation, and handlers. This element must have an id attribute value; this value is how it is associated-either through a CSS style rule or a DOM method-to the bound element that acts a placeholder for the binding that is filled out during attachment. The extends attribute inherits from a XUL element or another binding.

Description

This root container can hold one or more bindings, represented by the <binding> markup. The Mozilla code base references an XBL document through its name, which has an .xml extension. The document id has to be unique. The other children of <bindings> are <resources> and <stylesheet>, which contain style and image information to be used by the document's bindings.

body

Container for JavaScript code to be executed by an XBL method Contained by method Attributes id

Description

This element is designed as a holder for the method's script. It defines a logical block and differentiates the script from the parameter element, which also lies within the method. Script contained in a method has to be in a body element, which in turn should contain a CDATA section. <![CDATA[...]]> escapes JavaScript characters like quotes and slashes that may otherwise conflict with the XML parser.

children

Insertion point for children of a bound element, or inherited binding Contained by content Attributes id, includes, type

Description

This element needs to be placed in the binding content at the point where you want to place children of the bound element when the binding is rendered. If the children tag contains its own elements, then that element will be default content. If the element the binding attaches to contains children, the default content is ignored.

constructor

Container for code to be executed when a binding is created Contained by implementation Attributes action, class, id

Description

This behavior element is contained in the implementation element and holds code that will be carried out when the binding attachment first takes place. If you picture a binding as an object, your vision is initialization code. The code can alternatively be contained as the action attribute's value.

content

Container for anonymous content to be inserted into a bound document Contains children; any markup content Contained by binding Attributes id

Description

This container for the anonymous binding content is placed at the point where the element using it is in the bound document. children is the only XBL element allowed as a child of content. All other content is either HTML or XUL, depending on the context in which you use the binding.

destructor

Container for code to be executed when a binding is destroyed Contained by implementation Attributes action, class, id

Description

Contained in the binding's implementation, this element carries out code placed within it when the binding is detached or destroyed. This detachment and destruction occurs when the bound element matches a different style rule, the bound element is removed from the document, or the document is closed or destroyed. The code can alternatively be a value of the action attribute.

element

Insertion point for bound elements in anonymous content Contained by content Attributes id

Description

This element allows placement of a bound element at a point in the anonymous content (other than the top level that is the default for it). To use it, place it at the point in the binding content where you want the bound element to be rendered. This element is part of the XBL 1.0 specification, but is not yet implemented.

field

Holder property for simple data Contained by implementation Attributes class, id name, readonly

Description

This element is a simple data holder and an alternative to a property. It differs from property because it does not use a getter or setter. It is useful for holding static/constant values for use elsewhere in the binding.

getter

Script access point for an element's property Contained by property Attributes id, type

Description

This element executes script when the property it is attached to is accessed. This is most commonly used to return the value of the property.

handler

Single event handler for an XBL element Contained by handlers Attributes id, event, action, phase, attachto, button, modifiers, keycode, charcode, type

Description

This element defines an event handler on a binding that reacts to a mouse movement or keyboard press on the binding. Some executed code is contained in the handler. This code can go directly under the element or in the action attribute. The attachto attribute determines where the event is received-in the element, document, or window. The default receiver is the bound element. The phase attribute has three possible values-capturing, bubbling, and target-that determine which part of the event flow and default is bubbling The button, charcode, keycode, and modifiers attributes act as filters. For example, the value of button must match the label of the button that triggers the event. The section "Event Attributes," later in this chapter, contains a complete list of events.

Description

This element is placed under the binding element and contains the event handlers used by that binding.

image

An image resource in a binding Contained by resources Attributes class,id, src

Description

This element preloads images; all included image resources are loaded when the binding is used.

implementation

Container for binding methods and properties Contains method, property Contained by binding Attributes id, name, implements, type

Description

This element holds a binding's <method> and <property> elements that, as a whole, make up a binding's behavior. The optional implements attribute can hold a list of comma-separated XPCOM interfaces that are used by the implementation's methods and properties. The optional type attribute represents the scripting language to be used. This attribute defaults to JavaScript, the only implemented language that scripts Mozilla's XPFE.

<implementation type="application/x-javascript" implements="nsIAccessibleProvider">
...
</implementation>

method

Script function to be accessed on a binding object Contains body, parameter Contained by implementation Attributes id, name, type

Description

This element supplies a single function to the bound element or binding object. The most important attribute is name, which calls the method and is compulsory. The method can have the <parameter> element define parameters. A <body> element contains the code that will be executed.

parameter

Single paramter declaration for a method Contained by method Attributes id, name

Description

Each <parameter> element lists a single parameter for a method. The name attribute is compulsory and is used by the method code to access the parameter's value.

property

Definition of a single binding object property Contains getter, setter Contained by implementation Attributes id, name, readonly, onget, onset, element, attribute, property, type

Description

This element defines a bound element's or binding object's property. The name attribute is compulsory because it accesses the property. <getter> and <setter> child elements are optional and get and set the property value, respectively. The onget and onset attributes are alternatives. The element attribute is a reference to the anonymous content's node id. When the property is set, it is also set on that node. The property can be set to readonly.

resources

Container for list of resources that can be used by a binding Contains image, stylesheet Contained by binding

Description

Along with <content>, <implementation>, and <handlers>, this element is one of the binding element's top-level children. It defines the binding's resources. Stylesheets and images are the current resources available to bindings. It is common for a single binding to contain all resources, which another binding can then inherit.

setter

Change a binding property's value Contained by property Attributes id, type

Description

This element commonly sets the value of the property, and optionally executes other script for the property.

stylesheet

Captures an external stylesheet for use by anonymous content Contained by resources Attributes src

Description

This element defines a stylesheet to be used by a binding. An element's bound element and explicit children as well as anonymous content can use stylesheet. The src attribute has a URL value that points to the stylesheet. If you use the xml-stylesheet processing instruction on a binding, it can be applied only at a document level. It cannot be applied at a binding level, which is covered by the <stylesheet> element.

Event Attributes

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.

onblur

Usually used for input element such as a textbox, this event triggers actions when the focus leaves a widget. This action is the opposite of the onfocus event.

onbroadcast

This event is activated when the broadcaster attributes being "listened to" are changed. It can be placed on the observes element, which is placed in an element that is being listened to, or on an element that uses the observes attribute. Refer to Chapter 3 for more information on broadcasters and observers.

onchange

This event is fired when the value of a particular widget's (element) attribute that uses it changes. A menulist selection is one example. It can also be used on an observer when the attribute the observer listens to changes.

onclick

Relevant to any element that can be clicked on, such as a button, this event occurs when the mouse is clicked on an element that uses it. For some widgets that use this event, using oncommand attribute (which covers clicking) is recommended to avoid excluding keyboard selection. Here are some commonly used properties associated with this event:

button: This property tells you which mouse button was clicked. Its values are 0 for the left mouse button, 1 for middle button, and 2 for right button.
detail: This property counts how many clicks occur over an element before the mouse is moved. The values for this property start at 1 and increment for every click.

Instead of catching double clicks this way, you can use the ondblclick event.

onclose

Usually used to evaluate script when a window is closed with the close button or via a window.close( ) call, this event traps the closure of a widow. If the JavaScript evaluates to "true," the window closes; otherwise, the window remains open.

oncommand

This event is sent when an element is activated. Activation can mean more than one thing. You can activate by selecting a menu item, hitting Enter on the keyboard when an element has focus, or clicking on an element. Use this event if you want to cover the most possibilities available for activation.

oncommandupdate

This event is used on a command set when one of its commands is updated, such as when its disabled attribute changes.

oncontextmenu

This event occurs when a request is made for a context menu-usually a right click, depending on the platform-and is activated before the menu appears. oncontextmenu is similar to the oncreate and onpopupshowing events.

oncreate

Called on a popup element, this event carries out some code before the popup appears. It can be useful for dynamically determining which items appear in the resulting menu.

ondblclick

This event cccurs when there are two consecutive mouse clicks on an element. You could also use the onclick event's detail property with a value of 2.

ondestroy

Designed to carry out functions after a pop-up window disappears, this event can be used with a popup or menupopup element.

ondragdrop

When a drag and drop session completes and the user releases the mouse over the element, this event is triggered. The accessed code can acknowledge the drop and carry out an operation after accepting the dragged object.

ondragenter

The ondragenter event is sent when the mouse cursor first moves over an element during a drag and drop session. This element differs from the mouseover event because it occurs during a drag and drop session.

ondragexit

This element is activated when the cursor moves away from an element during a drag and drop session. It occurs after the ondragdrop event.

ondraggesture

The event is triggered at the beginning of a drag and drop session when the user holds the mouse button on the dragged object.

ondragover

When an object is dragged over an element, this event is commonly used by an element to determine whether the drop can occur.

onfocus

This event is triggered when an element receives focus in the UI. When it has focus, it can accept keyboard events. The opposite of onfocus is onblur.

oninput

Used on textbox elements, this event is activated when displayable keys change the text in the box.

onkeydown

This event occurs when the user presses a key on an element that has focus and the key press is not released.

onkeypress

Similar to onkeydown, this event occurs on a focused element when a key is pressed. The distinction is that with this event, the key is released soon after being pressed. The check for which key was pressed can be using the event.keyCode property.

onkeyup

This event is activated when the key press is released on a focused element.

onload

This event is activated on a XUL window or dialog after it has fully loaded. It should be attached to the elements of the same name. It can also be attached to image elements or elements that display images.

onmousedown

This event occurs when a mouse is pressed on an element but not released.

onmousemove

A reoccuring event, this event repeatedly fires when a mouse moves over an element.

onmouseout

When the mouse moves away from an element, this event occurs.

onmouseover

A hover event, this event fires when the mouse initially moves into an element's space.

onmouseup

This event occurs when a mouse is clicked and the button is released on an element immediately afterwards.

onoverflow

Relating to a box or layout element, this event is activated when the content contained in the box is too big for its given size and and "falls over the edge."

onoverflowchanged

This element is called when an element's overflow state changes. This can indicate that it did not have enough space to display it contents fully but does now, or that it does not have enough space and thus overflowed.

onpopuphidden

This event is activated on a popup when the pop-up window is hidden.

onpopuphiding

This event is activated on a popup while it is hidden.

onpopupshowing

This event is activated on a popup just before it opens. It is commonly used to dynamically set the contents of the popup when it is requested in the UI.

onpopupshown

This is event is activated on a popup after it is opened.

onselect

When you activate or select an available option in a widget, this event is fired. This event applies to such widgets as trees and listboxes.

onunderflow

This event can be used in tandem with the onoverflow event. It is activated when a layout element's content changes to fit into its given constraints after being in an overflow state.

onunload

This event is activated when a window or dialog closes. It should be used on the root elements of these window documents.

mozdev.org

Search

Projects

Resources

Community

Creating Applications with Mozilla

Appendix C

Programmer's Reference

XUL Element Set

action

Additional Attributes

Description

See Also

arrowscrollbox

Additional Attributes

Description

See Also

autorepeatbutton

Additional Attributes

Description

See Also

binding

Additional Attributes

Description

See Also

bindings

Description

See Also

box

Additional Attributes

Description

See Also

broadcaster

Additional Attributes

Description

See Also

broadcasterset

Additional Attributes

Description

See Also

browser

Additional Attributes

Description

See Also

button

Additional Attributes

Description

See Also

caption

Additional Attributes

Description

See Also

checkbox

Additional Attributes

Description

See Also

colorpicker

Description

JavaScript Methods and Properties

column

Additional Attributes

Description

See Also

columns

Additional Attributes

Description

See Also

command

Additional Attributes

Description

See Also

commands

Additional Attributes

Description

See Also

commandset

Additional Attributes

Description

See Also

conditions