Adding Labels and Images

This section describes a way to add labels and images to a window. In addition, we look at how to include elements into groups.

Text Elements

You cannot embed text directly into a XUL file without tags around it and expect it to be displayed. You can use two XUL elements for this purpose.

Label Element

The most basic way to include text in a window is to use the label element. It should be used when you want to place a descriptive label beside a control, such as a button. An example is shown below:

var el = env.locale; Example 1 : Source View

<label value="This is some text"/>

The value attribute can be used to specify the text that you wish to have displayed. The text will not wrap, so the text will all be displayed on a single line. This syntax is the most common of labels.

If the text needs to wrap, you can place the text content inside opening and closing tags as in the following example:

var el = env.locale; Example 2 :

<label>This is some longer text that will wrap onto several lines.</label>

As with HTML, line breaks and extra whitespace are collapsed into a single space. Later, we'll find out how to constrain the width of elements so that we can see the wrapping more easily.

Control Attribute

You can use the control attribute to set which control the label is associated with. When the user clicks on an associated label, that control will be focused. This association is also important for accessibility, so that screen readers read aloud the label for the control as the user tabs to it. Set the value of the control attribute to the id of the element to be focused.

var el = env.locale; Example 3 : Source View

<label value="Click here:" control="open-button"/>
<button id="open-button" label="Open"/>

In the example above, clicking the label will cause the button to be focused.

Description Element

For descriptive text not associated with any particular control, you can use the description tag. This element is useful for informative text at the top of a dialog or a group of controls for example. As with the label element, you can either use the value attribute for a single line of text or place text or XHTML content inside opening and closing description tags for longer blocks of text. It is more common to use the attribute syntax for labels, and the text content syntax for descriptions.

var el = env.locale; Example 4 : Source View

<description>
  This longer section of text is displayed.
</description>

You can set the text via script using the textContent property, as in the following example:

<description id="text" width="200"/>
document.getElementById('text').textContent = "Some lengthy word wrapped text goes here.";

Internally, both the label element and the description elements are the same. The label element is intended for labels of controls, such as text fields. The control attribute is only supported for labels. The description element is intended for other descriptive text such as informative text at the top of a dialog box.

Images

XUL has an element to display images within a window. This element is appropriately named image. Note that the tag name is different than HTML (image instead of img). You can use the src attribute to specify the URL of the image file. The example below shows this:

<image src="images/banner.jpg"/>

Although you can use this syntax, it would be better in order to support different themes to use a style sheet to set the image URL. A later section will describe how to use style sheets, but an example will be shown here for completeness. You can use the list-style-image CSS property to set the URL for the image. Here are some examples:

XUL:
 <image id="image1"/>
 <image id="search"/>

Style Sheet:
 #image1 {
   list-style-image: url("chrome://findfile/skin/banner.jpg");
 }
 #search {
   list-style-image: url("http://example.com/images/search.png");
 }

These images come from within the chrome directory, in the skin for the findfile package. Because images vary by theme, you would usually place images in the skin directory.

In the next section, we will learn how to add some input controls to a window.