Toolbox/Toolbar Spec

by Mike Pinkerton
Last Modified 2/11/98

Overview

This document is the engineering details behind the Toolbox/Toolbar Requirements document. It supplements that document with examples and a comprehensive listing of attributes and parent/child relationships.

From the Requirements document:

A Toolbar is a bar which contains arbitrary HTML (but normally XUL elements). The look of the toolbar can be customizable through CSS and is smart enough to wrap to multiple lines if there are too many elements on it to fit within a single line. Toolbars can live anywhere within a XUL window, not just at the top.

A Toolbox contains one or more toolbars and is used to group multiple bars together so the user can rearrange, collapse, and hide individual toolbars within the box. Within the toolbox, each toolbar gets a "grippy" which is the mechanism for collapsing (by clicking inside it) or rearranging (by dragging the grippy). When a toolbar is collapsed, it appears only as a horizontal grippy in a special area below all visible toolbars. This area is hidden when no toolbars are collapsed. Clicking on the horizontal grippy associated with the toolbar will make it reappear in its previous position.

Syntax

The XUL syntax for Toolbars and Toolboxes.Unfortunately, we're still shaking down CSS support in XML and our XPToolkit UI elements are just starting to come on line. This listing is VERY preliminary, but this is the place where it will live once we figure it all out.

Toolboxes

Tag	Children	Attributes	Description
toolbox	toolbar		Contains multiple toolbars.

Toolbars

Tag	Children	Attributes	Description
toolbar	contextmenu, toolbaritem, toolbarfolder	name, tooltip, description, position, size	Represents a single toolbar.
<<toolbar items>>	contextmenu	name, tooltip, description, disabled, selected	A collection of XUL items and any arbitrary HTML. A style attached to the item indicates which widget to use to present the item (e.g., to present a button). size can be used to hardcode a size value for the item, and/or to make the item springy. Any CSS style may be applied to these items as in HTML

 

---

Examples

Here is an example of XUL for a toolbox which contains two toolbars:

<?xml version="1.0"?>
<window xmlns:html="http://www.w3.org/1999/xhtml">
<window xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"> 

<style type="text/css">
  toolbox { background-color=darkGray }
  toolbar { background-color=lightGray; background-image=url(marble.gif) }
  button { background-color=lightGray }
</style>

<window>
  <broadcaster id="canGoBack"/>
  <broadcaster id="canGoForward"/>

  <toolbox>
    <toolbar>
      <titledbutton src="Back.gif" align="bottom" value="Back" onclick="BrowserBack()">	
        <observes element="canGoBack" attribute="disabled"/>			
      </titledbutton>
      <titledbutton src="Forward.gif" align="bottom" value="Forward" onclick="BrowserForward()";">
        <observes element="canGoForward" attribute="disabled"/>
      </titledbutton>

      <html:input></input>
                
      <html:image src="MozillaImg.gif" alt="Mozilla.org"></html:image>
      <titledbutton src="http://www.mozilla.org" img="throbber.gif"></throbber>
    </xul:toolbar>
        
    <toolbar>
      <titledbutton align="right" src="Location.gif" value="Mozilla" 
        onclick="window.frames[0].location.href='http://www.mozilla.org'"/>
      <titledbutton align="right" src="Location.gif" value="ABC News"
        onclick="window.frames[0].location.href='http://www.abcnews.com'"/>
    </toolbar>
  </toolbox>

</window>

Note that this example doesn't show more complicated features such as:

• how to make the throbber right justified
• how to hook up a toolbar to an RDF data source for local/remote merging
• how to make one element on a toolbar expand to fill remaining space
• how to make elements on a toolbar shrink and expand to best fill remaining space before wrapping
• how to customize the grippy look with CSS

These will appear here shortly.