Chapter 3. XUL Elements and Features

The XML-based User-interface Language (XUL) includes all of the basic widgets you need to build application user interfaces. These interfaces include tabs, text areas, buttons, and menus, as well as handy interfaces you may not have thought you needed, such as the <stack> widget or <colorpicker>.

Chapter 2 introduced some of the XUL elements that make up a window and basic applications. This chapter examines XUL elements and features in more detail, describing the rationale behind them, their look and behavior, and common usage. Though not comprehensive, the chapter provides more than enough information about XUL to get you started on building your own Mozilla applications, particularly when used in conjunction with the XUL reference in Appendix C.

The elements described here, such as menus, buttons, trees, and boxes, are needed in almost any type of application, and most of the examples are generic, so you can plug them into any application or customize them to your needs. We've packed a lot of information in this chapter and it will be a useful reference as you begin to develop your applications.

3.1. The XUL Document Object

At the core of a XUL file is the document object. As in HTML, document is an object that represents the XUL document itself -- the content as opposed to the window that surrounds it. The document provides methods for getting individual elements, manipulating the structure of the document, or updating style rules.

A document object provides methods such as getElementById, getElementsByTagName, createElement, and createTextNode for DOM querying and manipulation of the actual document. Further details about the DOM are available in Chapter 5.

Other types of document objects include the width and height of the window, a popupNode property that accesses the elements currently displaying a pop up (a XUL widget that attaches to another widget and appears above it holding some content), a tooltipNode property that accesses the element currently displaying a tooltip, and a documentElement property that accesses the body of the document:

var docEl = document.documentElement;
var secondLevelNodes = new Array( );
for (var I=0; I<docEl.childNodes.length;I++)  {
    secondLevelNodes[I] = docEl.childNodes[I];

This example creates an array of all the second-level nodes in relation to the document, and could be extended to walk to the whole tree. Using nodes in the structural representation of the document to get to other nodes in this way allows you to quickly access and change any part of a document with script.

The document object is global only for the particular scope that you are working in, so every window, dialog, and page has its own document object. To access it, just use the document. prefix followed by the name of the property you want to access:

var title = document.getElementById("bookTitle");

It is possible to access document outside the current scope -- for example, the window that opened another one using window.opener:

var title = window.opener.document.getElementById("bookTitle");