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

Feature Owner: Eric Vaughan

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.

[NOT YET IMPLEMENTED] The button can be locked into a pressed state by setting the depressed attribute on the button. This attribute, when set, indicates that the button should appear in a depressed state.

The titled button's appearance is highly customizable using CSS. The button's rollover appearance can be set using the :hover pseudoelement. Its depressed look can be set using the :active pseudoelement. Currently these are not yet implemented, but there is a workaround in place. Right now the titled button sets a pseudoclass attribute on itself when it is in the hover or active states, and this allows XUL writers to define style rules using attribute selector rules based on this attribute.

CSS [The Right Way] titledbutton:hover { ... } CSS [The Workaround] titledbutton[pseudoclass~="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 automatically crops its text string. The default behavior is to crop the string 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.

[NOT YET IMPLEMENTED] The button's cropping style can be specified using either an attribute or CSS. The attribute is called cropstyle, and it has values of left, middle, and right. CSS mechanism is currently unspecified.