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:

These will appear here shortly.


maintained by Mike Pinkerton (pinkerton@netscape.com)