3.9. The Box Model

3.9.1. Box Attributes

The XUL element <box> defines a number of attributes and some implicit behavior for layout. Boxes can be oriented within other boxes to define the general layout of the UI. Some boxes stretch to fit the space available within the top-level window or their containing element; others take only as much space as needed to display their own children.

Attributes on the box and its child elements determine the flexibility of the content contained within the box, the way that windows are resized, and the alignment of elements, as Table 3-4 describes.

The attribute names in Table 3-4 (with the exception of style) are defined directly on the box. But there are also CSS versions of these properties that use the prefix box-. pack becomes box-pack when it's defined in CSS, for example. These properties are not part of the CSS specification, so you may need to go one step further and use the format -moz-box-pack. These special extensions to CSS are described in the section Section 4.2.3 in Chapter 4.

The most commonly used attributes are orient, align, and pack. The orientation of the children of a box can be either vertical or horizontal. The default is horizontal for a plain <box>, but not for all box containers (<groupbox> is vertical). The <vbox> and <hbox> conveniences were created to bypass the use of this attribute and increase box layout efficiency in the rendering phase.

Here is a look at how the pack and align properties can effect the layout of widgets. First, here is a bit of code with no constraints:

<vbox style="width: 90px; height: 90px">
  <button label="Pack Me!" />
  <label value="This text is naturally aligned to the left" />
</vbox>

This XUL does not tell the button and text inside where to go, so they occupy the default positions shown in Figure 3-9.

Here is a changed box definition with the align and pack attributes set:

<vbox style="width: 90px; height: 90px" align="right" pack="center">

A noticeable visual difference can be seen in Figure 3-10.

The align value moves the items to the right of the box, while simultaneously constraining the button to fit only the text label, making better use of space. pack centers both the items horizontally.

3.9.2. Box-Like Containers

The basic XUL box is represented by the <box>, <vbox>, and <hbox> elements, but several more XUL elements are designed as box-like containers. They include:

• <radiogroup>

• <scrollbox>

• <tabbox>

• <groupbox>

• <toolbox>

• <stack>

• <deck>

• <listbox>

• <popup>

• <statusbar>

Descriptions of the tabbed box and the group box follow. Additional information on other box widgets can be found in the XUL element reference in Appendix C.

<tabbox orient="vertical" flex="1"> 
  <tabs> 
    <tab label="Fish" /> 
    <tab label="Birds" /> 
    <tab label="Coders" />
  </tabs>
  <tabpanels flex="1"> 
    <button label="Swim"/> 
    <button label="Fly"/> 
    <button label="Hack"/>
  </tabpanels> 
</tabbox>

<statusbar id="ch3-bar" persist="collapsed">
  <statusbarpanel class="statusbarpanel-iconic" id="book-icon"/>
  <statusbarpanel id="status-text" label="Thanks for reading chapter 3"
      flex="1" crop="right"/>
  <statusbarpanel class="statusbarpanel-iconic" id="book-icon-2"/>
</statusbar>

3.9.3. Additional Box Features

Boxes work in concert with a few other special elements, including the <separator> and <spacer>. These two elements create space between widgets in a box and can be horizontal or vertical depending on the orientation of the box. The separator is a visible divider and the spacer is invisible space. The default size for both of them is small, but they can be given flex, width, and height values like other elements. Used correctly, they can make all the difference in how your UI looks.

<box flex="1" collapsed="true" />

<box flex="1" style="display: none;" />

<box flex="1" style="visibility: hidden;" />

<vbox flex="1" style="height:39px;overflow: auto;">

3.9.4. Stacks and Decks

A variant and special model of the box is available in the stack and deck elements. Both are boxes, but they lay their children out one on top of the other like a stack of crates or a deck of cards, rather than sequentially.

A stack shows all its levels at once. If you have transparency or extra space on one level, you can see underneath. Stacks are useful when you want to add shadows in your content or if you want to create transparent layering effects. If you have a bird's eye view of XUL content, you can see the elements on each layer flowing into each other, like the text on top of an image in Figure 3-11.

<stack>
  <image src="logo5.gif"/>
  <label value="BUZZ ..." 
      style="font-weight:bold; font-size: large" top="70px" left="140px"/>
</stack>

Decks show only one level at a time. In Example 3-17, logo3.gif is foremost because the selectedIndex attribute on the deck is set to 2 in a zero-based index.

<deck id="fly-deck" selectedIndex="2">
  <image src="logo1.gif" />
  <image src="logo2.gif" />
  <image src="logo3.gif" />
</deck>

As Example 3-18 shows, it is possible to switch pages using the DOM by changing the index on the deck. The setAttribute method changes the selectedIndex attribute of the deck element in script and can be executed, for example, when a user clicks a button or in other places in the interface.

var deck = document.getElementById("fly-deck");
var selected = deck.getAttribute("selectedIndex");
if (!selected)
    selected = 0;
if (selected < 2)  {
    selected = parseInt(selected) + 1;
    deck.setAttribute("selectedIndex", selected);
}
else  {
    selected = 0;
    deck.setAttribute("selectedIndex", selected);
}

When applied to the deck in Example 3-17, the code in Example 3-18 continuously flips to the next image in the sequence and returns to the top of the deck when the last image is reached. In this case, there are only three images, so a maximum of 2 is put on the index check.

<stack> 
 <box id="box1" top="20px" left="40px"> 
  <image src="logo1.gif" />
 </box>
 <box id="box2" top="40px" left="50px"> 
  <image src="logo2.gif" /> 
 </box> 
</stack>

Box1=document.getElementById("box1")
Box1.setAttribute("top","40px")
Box1.setAttribute("left","50px")
Box2=document.getElementById("box2")
Box2.setAttribute("top","20px")
Box2.setAttribute("left","40px")