XUL Tutorial - The Box Model

In this section, we'll look at how XUL handles layout.

Introduction to Boxes

The main form of layout in XUL is called the 'Box Model'. This model allows you to divide a window into a series of boxes. Elements inside of a box will orient themselves horizontally or vertically. By combining a series of boxes, springs and elements will flex, you can control the layout of a window.

Although a box is the fundamental part of XUL element layout, it follows a few very simple rules. Boxes simply lay out their children either horizontally in a single row or vertically in a single column. Various attributes placed on the child elements in addition to some CSS style properties control the exact position and size of the children.

A box can lay out in one of two orientations, either horizontal or vertical. A horizontal box lines up its elements horizontally and a vertical box orients its elements vertically. You can think of a box as one row or one column from an HTML table.

The basic syntax of a box is as follows:

<box orient="horizontal">
  ...
</box>

Each element placed in the box will be placed horizontally in a row. The orient attribute controls the orientation of the box. In this case, a horizontal orientation is used. If you change the orient attribute to vertical the elements inside the box will be placed vertically in a column. If you leave the orient attribute out entirely, the box will default to a horizontal layout.

Note that earlier builds of Mozilla use align instead of orient. Newer code should use orient instead.

The following example shows how to place three buttons vertically.

<box orient="vertical">
  <button id="yes" value="Yes"/>
  <button id="no" value="No"/>
  <button id="maybe" value="Maybe"/>
</box>

The three buttons here are oriented vertcally as was indicated by the box. To change the buttons so that they are oriented horizontally, all you need to do is change the orient attribute.

You can add as many elements as you want inside a box, including HTML elements or other boxes. In the case of a horizontal box, each additional element will be placed to the right of the previous one. The elements will not wrap at all so the more elements you add, the wider the window will be. Similarly, each element added to a vertical box will be placed underneath the previous one. The example below shows a set of text boxes inside a box.

<box orient="vertical">
  <html:div>
    <html:label for="login">Login:</html:label>
    <html:input id="login"/>
  </html:div>
  <html:div>
    <html:label for="pass">Password:</html:label>
    <html:input id="pass"/>
  </html:div>
  <button id="ok" value="OK"/>
  <button id="cancel" value="Cancel"/>
</box>

Here four elements have been oriented vertically, two div tags and two button elements. Notice that only the elements that are direct descendants of the box are oriented vertcally. The labels and text inputs are inside the div so they are oriented according to the div. You can see in the image that each label and text input is oriented horizontally. The box has no influence over orientation inside the divs.

If you look closely at the image of the user name dialog above, you can see that the two text inputs are not aligned with each other vertically. It would probably be better if they were. In order to do this we need to add another box in there. Actually, we'll need to add two boxes. However, we'll be able to take out the div tag.

<box orient="vertical">
  <box orient="horizontal">
    <box orient="vertical">
      <html:label for="login">Login:</html:label>
      <html:label for="pass">Password:</html:label>
    </box>
    <box orient="vertical">
      <html:input id="login"/>
      <html:input id="pass"/>
    </box>
  </box>
  <button id="ok" value="OK"/>
  <button id="cancel" value="Cancel"/>
</box>

Notice how the text boxes are now aligned with each other. To do this, we needed to add boxes inside of the main box. The two labels and text inputs are all placed inside a horizontal box. Then, the labels are placed inside another box, this time a vertical one, as are the text inputs. This inner box is what makes the elements orient vertically. The horizontal box is needed as we want the labels box and the inputs box to be placed horizontally with each other. If this box was removed, both text inputs would appear below both of the labels.

Boxes in the Find Files Dialog

Let's add some boxes to the find files dialog. A vertical box will added around all of the elements, and a horizontal box with be added around the text field and the buttons. The result will be that the buttons will appear below the text field. While we're at it, we'll get rid of the HTML div and replace it with the html element.

<box orient="vertical" flex="1"> <html> Enter your search criteria below and select the Find button to begin the search. </html> <box orient="horizontal"> <text value="Search for:"/> <textfield id="find-text"/> </box> <box orient="horizontal"> <spring flex="1"/> <button id="find-button" class="dialog" value="Find" default="true"/> <button id="cancel-button" class="dialog" value="Cancel"/> </box> </box>

The vertical box causes the main text, the box with the text field and the box with the buttons to orient vertically. The inner boxes orient their elements horizontally. As you see in the image below, the label and text input are placed side by side. The spring and two buttons are also placed horizontally in their box. Notice how the spring causes the buttons to appear on the right side, because it is flexible.

There's also a second element, vbox which is just a box that defaults to vertical orientation instead or horizontal. Thus, the two lines below are equivalent:

<box orient="vertical">

<vbox>

(Next) Next, we'll see some additional features of a window.

Examples: 3.1.1 3.1.2 3.1.3