[Table of Contents] [Previous: Toolbars and Toolboxes] [Next: Tree Widget]

Feature Owner: Eric Vaughan

Change History:

• 8/22/99 - Added info about crop and oncommand.

A titled button is similar to its HTML counterparts, although unlike the HTML button, it cannot contain arbitrary content. Instead the titled button can contain a single image and a single text string. The titledbutton tag is used to insert a titled button into a XUL document.

The titled button's image can be described either using CSS or by using the src attribute. The attribute's value is the URL to use for the image.

<titledbutton src="http://www.mozilla.org/myImage.gif"/>

If the src attribute is omitted, then the button will pick up its image from the list-style-image CSS property.

CSS .folderButton { list-style-image: url("http://www.mozilla.org/folder.gif"); } XUL <titledbutton class="folderButton"/>

The titled button's text string is specified using the value attribute. The text string can be placed above the image, to the left of the image, below the image, or to the right of the image. The align attribute can be used to specify the text string's position relative to the image (e.g., an alignment of right indicates that the text should be placed to the right of the image.

<titledbutton class="folderButton" value="Bookmarks" align="right"/>

The titled button can be disabled by setting the disabled attribute on the button element. This attribute can be set and unset using the setAttribute and unsetAttribute AOM APIs.

When a titled button is clicked, it executes a command handler (in addition to the normal click handler). This can be set on the button using the oncommand attribute.

The button can be locked into a pressed state by setting the toggled attribute on the button to a value of 1. This attribute, when set, indicates that the button should appear in a depressed state. When the toggled value is 2, the state is considered mixed.

The titled button's appearance is highly customizable using CSS. The button's rollover appearance can be set using the :hover pseudoclass. Its depressed look can be set using the :active pseudoclass.

titledbutton:hover { ... }

Because the button's image can be specified in CSS, different style rules can contain different images for the button's various states. Buttons can therefore have rollover, depressed, and disabled images. Buttons can even animate when certain conditions are met by switching between animated and static images (e.g., the Netscape throbber has a style rule that switches to an animated gif when a busy attribute is set on the button element).

When a titled button's width is constrained, it can be made to crop its text string. The button's cropping style can be specified using an attribute. The attribute is called crop, and it has values of left, middle, and right. For example, with crop right, the string is truncated by removing characters on the right hand side of the string until the string fits inside the button. The button places ellipses (...) on the right of the string.