[Table of Contents] [Previous: Menu Bars and Menus] [Next: Titled Buttons]

Feature Owner: Mike Pinkerton

A toolbar is a strip that contains a set of widgets called toolbar items. The toolbar can lay out its components either horizontally or vertically, and it can optionally wrap to multiple rows/columns. (In fact, a toolbar is really just an extension of the box element. See The Box System for details.)

The toolbar is specified using the toolbar tag. The attribute align is used to specify whether or not the toolbar is a horizontal toolbar or a vertical toolbar. If this attribute is omitted, the toolbar will lay out its children horizontally. [Note: The align attribute should be moved into CSS, but for now it must be specified as an attribute on the toolbar.]

<toolbar align="vertical"> <html:button>Button One</html:button> <html:button>Button Two</html:button> <html:button>Button Three</html:button> </toolbar>

[NOT YET IMPLEMENTED] Toolbars are capable of supporting drag and drop operations of DOM subtrees. The drag and drop code for toolbars can provide feedback for insertion before or after other items on the toolbar. In order for this code to work, the contents of the toolbar (e.g., buttons and input fields) must be logically grouped into discrete toolbar items using the toolbaritem tag.

A toolbar item is also an extension of a box and it can therefore contain arbitrary HTML and XUL content that is treated as a single toolbar item for the purposes of drag and drop, deletion operations on the toolbar, cut and paste of toolbar items, and context/popup menus on toolbar items.

The toolbar item can lay out its contents horizontally or vertically (with horizontal being the default) using the align attribute.

<toolbar> <toolbaritem> <html:button>Button One</html:button> </toolbaritem> <toolbaritem> <html:button>Button Two</html:button> </toolbaritem> <toolbaritem> <html:img src="icon.gif"/>Input Label: <html:input/> </toolbaritem> </toolbar>

A toolbar's contents can be marked as unmodifiable by setting the readonly attribute on the toolbar. Toolbars with this attribute set will disallow any drops into their content area, and they will not allow their contents to be altered in any way.

Although toolbars can be embedded directly in the window, they are commonly placed inside another object called the toolbox. The toolbox is represented using the toolbox tag. A toolbox contains one or more toolbars as children, and it surfaces the UI that allows the toolbars within the toolbox to be reordered and collapsed.

When a toolbar is placed inside of a toolbox, it acquires a stripe on its left hand side (if the toolbox stacks its components) or on its top side (if the toolbox is horizontal). This stripe is affectionately referred to as the grippy, and it is the object that the user manipulates in order to move the toolbar around or to collapse it.

Collapsed toolbars appear in a thin strip at the bottom of the toolbox (if vertical) or the right of the toolbox (if horizontal). This strip is only shown if at least one of the toolbars in the toolbox is collapsed.

<toolbox> <toolbar id="Command Toolbar"> <html:button>Button One</html:button> </toolbar> <toolbar id="Personal Toolbar> <html:button>Button Two</html:button> </toolbar> <toolbar id="Location Toolbar> <html:img src="icon.gif"/>URL: <html:input/> </toolbar> </toolbox>

When a toolbar is collapsed, an attribute called collapsed is set to true on the toolbar element. When the toolbar is shown again, this attribute is unset. If this attribute is specified in the XUL file, it indicates that the initial state of the toolbar is to be collapsed inside the toolbox, although a new state may be stored persistently in order for the user's visibility preferences to be retained. (See Persistence and Sharing for details.)

The collapsed attribute is ignored if the toolbar is not contained in a toolbox.

The toolbar or toolbox can also be hidden using the standard mechanism (in both HTML and XUL) for hiding content elements: myToolbar.style.display = none. Showing the toolbar requires setting it back to its original display type (which for toolbars is block).

The look of the toolbox grippies can be customized using the pseudoelements :toolbox-normal and :toolbox-rollover. The former is used by default for the grippies, and the latter is used when the user mouses over the grippies.

:toolbox-rollover { background-color: #ccccff; background-image: url("resource:/res/toolbar/TB_Tab_mo.gif"); background-repeat: no-repeat; color: green; border-bottom: solid darkGray 1px; border-top: solid white 0px; border-left: solid white 0px; border-right: solid darkGray 1px; }