XUL Programmer's Reference Manual

<box>

Attributes Common Children
align <box>
valign <menu>
class <button>
id <text>
flex <image
width <tree>
height  
autostretch  
orient  
oncommand  
observes (OR) <observes>
equalsize  
collapsed  
context  

<hbox>

Attributes Common Children
same as above - orient same as above
   

<vbox>

Attributes Common Children
same as above - orient same as above
   

<titledbox>

Attributes Common Children
same as above same as above +
  <title>
   

<scrollbox>

Attributes Common Children
same as above + same as above
scrollByLine  
scrollByIndex  
scrollToLine  
getPosition  

The <box> widget provides a general purpose and flexible layout mechanism. Using boxes, you can specify the position and relationship of almost any combination of widgets in the UI. Many XUL widgets inherit from boxes, including:

Boxes use flex to stretch their positions in a UI. Springs with flex push back against boxes, constraining them within the parent container. The following example shows a simple box and spring layout using all of box's basic attributes:
 
<box id="parent_box" 
  orient="vertical" 
  style="background-color:lightblue;">
    <box flex="1">
       <button class="borderless" value="Start" />
       <button class="borderless" value="Stop" />
    </box>
    <spring flex="3" />
</box>

Titled Boxes

The titledbox is derived from the basic box, but supports a special child element for attaching a label-like title to the box container, as in the following example:

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

<window id="new-menu-stuff" 
  xmlns:html="http://www.w3.org/1999/xhtml"
  xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">

<titledbox style="background-color: lightblue;" orient="vertical">
<title>
<button value="Click Me" />
<button value="Push Me" />
</titledbox>
</window>

In all other respects, the <titledbox> element is the same as the box.
 

hboxes and vboxes

The box widget also includes two conveniences, <hbox> and <vbox>. These are regular boxes that have their orient attribute preset to horizontal and vertical, respectively. The following example shows the hbox being
 
 

align
Description
align is an optional attribute that specifies the alignment of the current element's children.
Syntax
<element align="left | right | center | vertical | horizontal">
Example
 
 
<box width="150" orient="vertical" autostretch="never" 
style="border: solid 2px; background-color: lightblue" 
align="left">
       <button value="button1" style="font-size: 12pt"/>
       <button value="button2" style="font-size: 12pt"/>
       <button value="button3" style="font-size: 12pt"/>
</box>
<box width="150" orient="vertical" autostretch="never" style="border: solid 2px; background-color: lightblue" align="right">
       <button value="button1" style="font-size: 12pt"/>
       <button value="button2" style="font-size: 12pt"/>
       <button value="button3" style="font-size: 12pt"/>
</box>
 
Notes
The default value for align is left. In addition to the left, center, and right values, align also supports "horizontal" and "vertical", though these latter two are both deprecated. Remember that the attribute referes to the alignment of the children and not the parent element.
 


 

valign
Description
valign is an optional attribute that specifies the vertical alignment of the current element's children.
Syntax
<element valign="top | middle | baseline | bottom ">
Example
<box width="150" orient="vertical" autostretch="never" 
  style="border: solid 2px; background-color: lightblue" 
  valign="baseline">
    <button value="button1" style="font-size: 12pt"/>
    <button value="button2" style="font-size: 12pt"/>
    <button value="button3" style="font-size: 12pt"/>
</box>
<box width="150" orient="vertical" autostretch="never" 
  style="border: solid 2px; background-color: lightblue" 
  valign="middle"
    <button value="button1" style="font-size: 12pt"/>
    <button value="button2" style="font-size: 12pt"/>
    <button value="button3" style="font-size: 12pt"/>
</box>
Notes
The default value for valign is middle. Remember that the attribute referes to the vertical alignment of the children and not the parent element.
 


 

flex
Description
flex is used to position widgets and establish their flexibility relative to one another.


Syntax

<element flex="integer">
Examples
 
<box orient="vertical" style="background-color:lightblue;">
    <box flex="1">
       <button class="borderless" value="Start" />
       <button class="borderless" value="Stop" />
    </box>
    <spring flex="3" />
</box>
Notes
Flex is one of the principal ways to size and arrange widgets in the UI. Using boxes, springs, flex, and the functional XUL widgets you need, you can layout the interface in any way you choose.

In the example above, the inner box widget is vying for space with the spring widget. Both of them have been given flex, but the greater flex of the spring widget has resulted in a spring element (below the two buttons) that is three times as tall as the buttons themselves. 

When flexible widgets (widgets for which some flex value has been specified) are arranged with other, unflexible widgets, the flex of the flexible widgets is always understood to be complete. The inflexible widgets in this case take up only as much space as they need to fulfill their other requirements: that their values be displayed, that the style considerations like padding and borders are met, and so on.

When the flex attribute is not specified, an element is understood to have a flex of zero.


 

width
Description
width is an optional attribute that specifies the width of the box in pixels or percentage of available space.
Syntax
<element width="width in pixels">
Example
<menubar width="100px" 
  style="background-color:lightblue;">
Notes
When you do not specify a width or height, boxes and other elements will rely upon flex to figure out how much space to occupy. With no flex and no size attributes, a box will take only as much space as is needed to display whatever value or name attributes that have been specified.

When an element does have some flexibility, the width is understood to be the minimum width, past which the element flexes into the containing space.


 

height
Description
height is an optional attribute that specifies the width of the box in pixels or percentage of available space.
Syntax
<element height="height in pixels">
Example
<menubar height="100" 
  style="background-color:lightblue;">
Notes
When you do not specify a width of height, boxes and other elements will rely upon flex to figure out how much space to occupy. With no flex and no size attributes, a box will take only as much space as is needed to display whatever value or name attributes that have been specified.

When an element does have some flexibility, the height is understood to be the minimum height, past which the element flexes into the containing space.


 

 

autostretch
Description
autostretch is an optional attribute that turns a box's autostrething on and off.
Syntax
<element autostretch="never | always">
Example
<box autostretch="never" 
  style="background-color:lightblue;">
Notes
The autostretch attribute gives you control over a box's tendency to stretch its child elements to fit in the opposite direction of the box. When a box is aligned vertically, for example, it will stretch its children out horizontally automatically unless you specify otherwise. The figure below demonstrates how autostretch prevents the stretching of the box's button children.
<box style="background-color: lightblue; border: solid 2px" orient="vertical">
  <button value="button1" style="font-size: 10pt"/>
  <button value="button2" style="font-size: 14pt"/>
  <button value="button3" style="font-size: 24pt"/>
  <button value=" default stretching " style="font-size: 10pt"/>
</box>

<box style="background-color: lightblue; border: solid 2px" autostretch="never" orient="vertical">
  <button value="button1" style="font-size: 10pt"/>
  <button value="button2" style="font-size: 14pt"/>
  <button value="button3" style="font-size: 24pt"/>
  <button value=" autostretch=never " style="font-size: 10pt"/>
</box>
 

 

orient
Description
orient is an optional attribute that specifies the alignment of the children of the current element.
Syntax
<element orient="vertical | horizontal">
Example
 
 
<menubar orient="horizontal" 
  style="background-color:lightblue;">
<menubar orient="vertical" 
  style="background-color:lightblue;">
Notes
The orient attribute takes the place of align as the way to orient an element's child elements either end-to-end or top-to-bottom. Though align still accepts "vertical" and "horizontal" as values, these are now deprecated.


 

oncommand
Description
oncommand is a generalized event listener attribute that's called when the user takes some action on the element.
Syntax
<element oncommand="javascript event handler code">
Example
<box oncommand="alert('Parent box got the event')">
  <menulist ...
  ...
</box>
Notes
The oncommand attribute is available to all elements that inherit from box, which is just about everyrthing in the toolkit. Use oncommand whenever you want to write an event handler for an element that doesn't have some more specific event listener attributes.


 

observes
Description
observes is a special attribute used to get attribute information from a separate, broadcasting element.
Syntax
<element observes="id of broadcaster">
Example
<broadcaster 
   id="cut_cast"
   oncommand="toClipBoard()" />
   
<box observes="cut_cast" />
...
Notes
The observes attribute is available to any element, and is a convenience for elements that want to observe all the attributes (with the exception of the id) of a broadcasting element. In the previous example, the <box> element is observing the attributes of the broadcaster, in this case the oncommand event listener attribute. The observing box element effectively inherits the oncommand attribute and its event listener value.

The broadcaster/observer relationship typically exists between an invisible broadcaster and observing user interface elements (such as menuitems, checkboxes, and so on), though any element can broadcast or observe attributes from another.

To observe only particular attributes of a broadcasting element, use the <observes> element and its special attributes.


 

equalsize
Description
equalsize is an optional attribute that makes the preferred size of each chld in a box the same.
Syntax
<element equalsize="[always | never]">
Example
<box equalsize="always">
  <button flex="1" value="fooa" />
  <button flex="1" value="fooaaa" />
  <button flex="1" value="fooaaabbb" />
  <button flex="1" value="fooaaabbbccc" />
  <button flex="1" value="fooaaabbbcccddd" />
</box>
Notes
In the example above, all of the buttons stretch to the same child within the box. When equalsize is set to "never", their sizes are various. This attribute affects both the height and the width of the child nodes.

equalsize has the following effect on the attributes of the child nodes:

  • each width of a child becomes the width of the widest child
  • min-width of each child becomes the min-width of the child with the largest min-width
  • max-width of each child becomes the max-width of the smallest max-width


 

collapsed
Description
collapsed is an optional attribute that collapses the box and removes it from view.
Syntax
<box collapsed="[ true | false ]" />
Example
<box collapsed="true" >
...
Notes

The collapsed attribute is equivalent to the display: none CSS property. Note: collapsing an element makes it fully invisible (as opposed to "collapsing" a toolbar in the UI, which folds it up into a smaller form, and which is managed with other CSS properties).

 
 
 

 
 
 
 
Last updated: 2/22/01 Ian Oeschger