3.5. Words and Pictures

The text widgets described here are used to label other widgets, or simply to display messages or instructions to the user in the interface and include a text input widget. Images can be displayed with the main image element or in various ways on other elements, such as buttons or menus.

3.5.1. Text Input

The <textbox> element is a text input box not unlike the HTML <textarea> element. The default <textbox> element has a single line.

<textbox id="singleFlyInput" />

However, setting the multiline attribute makes it into a larger text area.

<textbox id="multiFlyInput" value="Fly Name" multiline="true" rows="4" />

A multiline textbox defaults to three lines unless constricted by a fixed size on a container or stretched out with flex. To force the number of lines, use the rows attribute. If you want to restrict the number of characters inputted, set the size attribute to a numeric value.

<textbox id="holdtheFlyInput" cols="3" rows="2" />

The initial value of an input widget is blank if no value is specified. Setting the readonly attribute to true or false can control editing access.

3.5.2. Text Display

Three tags available in XUL handle basic text display in the UI, and each has its own context for use. They include a <caption>, a <label>, and a <description> element.

The caption is designed specifically for the text that appears inline in the border of a group box. You can control where the caption appears by putting the caption element above or below the other content in the group box:

<groupbox id="textWidgetsBox">
    <caption id="textTitle" label="Text Widgets"/>
    <!-- content here -->
</groupbox>

label is more flexible than caption because it isn't tied to a particular widget and can even be used as a standalone.

For longer text, the <description> element is best. You can embed text in the description element and have it wrap to the maximum size of the containing element:

<description>
The mozdev.org site provides free project hosting for the Mozilla community. You are welcome to take a look at the more than 60 projects hosted on the site or to start your own development project. 
</description>

Or you can use the value attribute when you're sure the text will not overflow. In this case, <description> is interchangeable with the <label> element for use in identifying other items in the UI:

<description value="Start a project today." />

3.5.3. Images

XUL supports the display of images in the native web formats of JPEG, PNG, and GIF. Most images you will find in the Mozilla UI are GIF files, which retain the best quality when compressed. Chapter 4 discusses theme issues and considerations in more detail. The basic syntax for displaying an image is:

<image src="myImage.png" />

The <image> element is analogous to the HTML <img> element. The image to be displayed is directly associated with the element using the src attribute. You can also use list-style-image, which is a CSS2 property used to associate an image with an element. To do this, you need a style selector -- in this case, the id.

<image id="foo" />

The style property takes a value of src, which has one parameter, the image, or a chrome or resource URL pointing to the image.

#foo  {
    list-style-image: url("myImage.png");
}

src is good for single images and for convenience, but in general, using the CSS property is recommended because it follows the principal of separating functionality from presentation and it better fits into a theme-swapping architecture, as used in the Mozilla suite.