XUL Tutorial

Prev Next

Background color

Font

Font size

Line height

directory.

Input Controls

XUL has elements that are similar to the HTML form controls.

Text Entry Fields

HTML has an input element which can be used for text entry controls. XUL has a similar element, textbox, used for text entry fields. Without any attributes, the textbox element creates a box in which the user can enter text. Textboxes accept many of the same attributes as HTML input controls. The following are some of them:

A unique identifier so that you can identify the textbox.

class

The style class of the textbox.

value

If you want the textbox to have default text, supply it with the value attribute.

disabled

Set to true to have text entry disabled.

type

You can set this attribute to the special value password to create a textbox that hides what it types. This is usually used for password entry fields.

maxlength

The maximum number of characters that the textbox allows.

Note that while in HTML, several different kinds of fields can be created with the input element, in XUL there are separate elements for each type. The following example shows some textboxes:

Example 2.4.1: Source View

The textbox examples above will create text inputs that can only be used for entering one line of text. HTML also has a textarea element for creating a larger text entry area. In XUL, you can use the textbox element for this purpose as well -- two separate elements are not necessary. If you set the multiline attribute to true, the text entry field will display multiple rows.

For example:

Example 2.4.2: Source View

<textbox multiline="true"

value="This is some text that could wrap onto multiple lines."/>

Like the HTML textarea, you can use the rows and cols attributes to set the size. This should be set to the number of rows and columns of characters to display.

Let's add a search entry field to the find file dialog. We'll use the textbox element.

Add these lines before the buttons we created in the last section. If you open this window, you will see something much like that shown in the image below.

Notice that the label and the text input field have now appeared in the window. The textbox is fully functional and you can type into it and select text. Note that the control attribute has been used so that the textbox is selected when the label is clicked.

Checkboxes and Radio Buttons

Two additional elements are used for creating check boxes and radio buttons. They are variations of buttons. The checkbox is used for options that can be enabled or disabled. Radio buttons can be used for a similar purpose when there are a set of them where only one can be selected at once.

You can use most of the same attributes on checkboxes and radio buttons as with buttons. The example below shows some simple checkboxes and radio buttons.

The first line creates a simple checkbox. When the user clicks the checkbox, it switches between checked and unchecked. The checked attribute can be used to indicate the default state. You should set this to either true or false. The label attribute can be used to assign a label that will appear beside the check box. For radio buttons, you should use the selected attribute instead of the checked attribute. Set it to true to have a radio button selected by default, or leave it out for other radio buttons.

In order to group radio buttons together, you need to use the radiogroup element. Only one of the radio buttons in a radio group can be selected at once. Clicking one will turn off all of the others in the same group. The following example demonstrates this.

Example 2.4.3: Source View

</radiogroup>

Like buttons, check boxes and radio buttons are made up of a label and an image, where the image switches between checked and unchecked when it is pressed. Check boxes have many of the same attributes as buttons:

label

The label on the check box or radio button.

disabled

Set this to either true or false to disable or enable the check box or radio button.

accesskey

The shortcut key that can be used to select the element. The letter specified is usually drawn underlined in the label.

List Controls

XUL has a number of types of elements for creating list boxes.

List Boxes

A list box is used to display a number of items in a list. The user may select an item from the list.

XUL provides two types of elements to create lists, a listbox element to create multi-row list boxes, and a menulist element to create drop-down list boxes. They work similar to the HTML select element, which performs both functions, but the XUL elements have additional features.

The simplest list box uses the listbox element for the box itself, and the listitem element for each item. For example, this list box will have four rows, one for each item.

Example 2.5.1: Source View

</listbox>

Like with the HTML option element, you can assign a value for each item using the value attribute. You can then use the value in a script. The list box will default to a suitable size, but you can control the size with the rows attribute. Set it to the number of rows to display in the list box. A scroll bar will appear that the user can use to display the additional rows.

The following example demonstrates these additional features:

Example 2.5.2: Source View

</listbox>

The example has been changed to display only 3 rows at a time. Values have also been added to each item in the list. List boxes have some additional features, which will be described later.

Multi-Column List Boxes

The listbox also supports multiple columns. Each cell may have arbitrary content within it, although usually only text is used. When the user selects an item in the list, the entire row is selected. You cannot have a single cell selected.

Two tags are used to specify the columns in the listbox. The listcols element is used to hold the column information, each of which is specified using a listcol element. You will need one listcol element for each column in the listbox.

The listcell element may be used for each cell in a row. If you want to have three columns, you will need to add three listcell elements inside each listitem. To specify the text content of a cell, place a label attribute on a listcell. For the simple case where there is only one column, you may also place the label attributes directly on the listitem elements and leave the listcell elements out entirely, as was seen in the earlier listbox examples.

The following example is of a listbox with two columns and three rows:

Example 2.5.3: Source View

</listcols>

</listitem>

</listitem>

</listitem>

</listbox>

Header Rows

List boxes also allow a special header row to be used. This is much like a regular row except that it is displayed differently. You would use this to create column headers. Two new elements are used.

The listhead element is used for the header rows, just as the listitem element is used for regular rows. The header row is not a normal row however, so using a script to get the first row in the list box will skip the header row.

The listheader element is used for each cell in the header row. Use the label attribute to set the label for the header cell.

Here is the earlier example with a header row:

Example 2.5.4: Source View

</listhead>

</listcols>

</listitem>

</listitem>

</listitem>

</listbox>

In this example, the flex attribute is used to make the column flexible. This attribute will be described in a later section, but here it allows the column to fill all of the remaining space horizontally. You can resize the window to see that the column stretches as the window does. If you shrink the size horizontally, the labels on the cells will crop themselves automatically using an ellipsis. You can use the crop attribute on the cells or items set to the value none to disable the ellipsis.

Drop-down Lists

Drop-down lists can be created in HTML using the select element. The user can see a single choice in a textbox and may click the arrow or some similar such button next to the textbox to make a different selection. The other choices will appear in a pop-up window. XUL has a menulist element which can be used for this purpose. It is made from a textbox with a button beside it. Its name was chosen because it pops up a menu with the choices in it.

Three elements are needed to describe a drop-down box. The first is the menulist element, which creates the textbox with the button beside it. The second, menupopup, creates the popup window which appears when the button is clicked. The third, menuitem, creates the individual choices.

Its syntax is best described with the example below:

Example 2.5.5: Source View

</menupopup>

</menulist>

This menulist will contain four choices, one for each menuitem element. To show the choices, click the arrow button on the menulist. When one is selected, it appears as the choice in the menulist. The selected attribute is used to indicate the value that is selected by default.

By default, you can only select choices from the list. You cannot enter your own text by typing it in. A variant of the menulist allows editing the text in the field. For example, the URL field in the browser has a drop-down for selecting previously typed URLs, but you can also type them in yourself.

To create an editable menulist, add the editable attribute as follows:

Example 2.5.6: Source View

</menupopup>

</menulist>

The URL field created here has three pre-populated choices that the user can select or they can enter one of their own by typing it into the field. The text the user enters is not added as a new choice. Because the label attribute was not used in this example, the default value will be blank.

Progress Meters

In this section, we'll look at creating progress meters.

Adding a Progress Meter

A progress meter is a bar that indicates how much of a task has been completed. You typically see it when downloading files or when performing a lengthy operation. XUL has a progress meter element which can be used to create these. There are two types of progress meters: determinate and undeterminate.

Determinate progress meters are used when you know the length of time that an operation will take. The progress meter will fill up and, once full, the operation should be finished. This can be used for the download file dialog as the size of the file is known.

Undeterminate progress meters are used when you do not know the length of time of an operation. The progress meter will have an animation such as a spinning barber pole or a sliding box, depending on the platform and theme used.

Determinate progress meter:

Undeterminate progress meter:

The progress meter has the following syntax:

<progressmeter

id="identifier"

mode="determined"

value="0%"/>

The attributes are as follows:

The unique identifer of the progress meter

mode

The type of the progress meter. If this is set to determined, the progress meter is a determinate progress meter where it fills up as the task completes. If this is set to undetermined, the progress meter is undeterminate where you do not know the length of time. The value determined is the default if you do not specify this attribute.

value

The current value of the progress meter. You should only use this for a progress meter that is determinate. The value should be set to a percentage from 0% to 100%. The value would be changed by a script as the task completes.

Let's add a progress meter to our find file dialog. We would normally put an undeterministic progress meter as we don't know how many files we'll be searching or how long the search will take. However, we'll add a normal one for now as an animating one can be distracting during development. The progress meter would normally only appear while the search is taking place. We'll add a script later to turn it on and off.

<hbox>

The value has been set to 50% so that we can see the meter on the window. A margin has been set to 4 pixels so that it is separated from the edge of the window. As was stated earlier, we only want the progress bar to be displayed while the search was occuring. A script will show and hide it as necessary.

Adding HTML Elements

Now that we've added some buttons, let's add some other elements.

Adding HTML Elements to a Window

In addition to all of the XUL elements that are available, you can also add HTML elements directly within a XUL file. You can actually use any HTML element in a XUL file, meaning that Java applets and tables can be placed in a window. You should avoid using HTML elements in XUL files if you can. However, this section will describe how to use them anyways. Remember that XML is case-sensitive though, so you'll have to enter the tags and attributes in lowercase.

In order to use HTML elements in a XUL file, you must declare that you are doing so using the XHTML namespace. This way, Mozilla can distinguish the HTML tags from the XUL ones. The attribute below should to be added to the window tag of the XUL file, or to the outermost HTML element.

xmlns:html="http://www.w3.org/1999/xhtml"

This is a declaration of HTML much like the one we used to declare XUL. This must be entered exactly as shown or it won't work correctly. Note that Mozilla does not actually download this URL, but it does recognize it as being HTML.

Here is an example as it might be added to the find file window:

<?xml version="1.0"?>

<?xml-stylesheet href="chrome://global/skin/" type="text/css"?>

<window

id="findfile-window"

title="Find Files"

orient="horizontal"

xmlns:html="http://www.w3.org/1999/xhtml"

xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">

Then, you can use HTML tags as you would normally, keeping in mind the following:

You must add a html: prefix to the beginning of each tag, assuming you declared the HTML namespace as above.

The tags must be entered in lowercase.

Quotes must be placed around all attribute values.

XML requires a trailing slash at the end of tags that have no content. This may be clearer from the examples below.

You can use any HTML tag although some such as head and body are not really useful. Some examples of using HTML elements are shown below.

<html:img src="banner.jpg"/>

<html:input type="checkbox" value="true"/>

<html:table>

<html:tr>

<html:td>

A simple table

</html:td>

</html:tr>

</html:table>

These examples will create an image from the file banner.jpg, a checkbox and a single-cell table. You should always use XUL features if they are available and you probably should not use tables for layout in XUL. (There are XUL elements for doing layout). Notice that the prefix html: was added to the front of each tag. This is so that Mozilla knows that this is an HTML tag and not a XUL one. If you left out the html: part, the browser would think that the elements were XUL elements and they would not display because img, input, table, and so on are not valid XUL tags.

In XUL, you can add labels with the description or label element. You should use these elements when you can. You can also add labels to controls either by using the HTML label element, or you can simply put the text inside another HTML block element (such as p or div) as in the example below.

Example 2.7.1: Source View

<html:p>

Search for:

<html:input id="find-text"/>

</html:p>

This code will cause the text 'Search for:' to be displayed, followed by an input element and an OK button. Notice that the XUL button can appear inside the HTML elements, as it does here. Plain text will only be displayed when placed inside an HTML element that would normally allow you to display text (such as a p tag). Text outside of one will not be displayed, unless the XUL element the text is inside allows this (the

You are reading the story above: TeenFic.Net

Prev Next

#development #mozilla #programming #tutorial #xml #xul