Checkbox Spec

by Mike Pinkerton
Last Modified 5/5/99

Overview

This document is the engineering details behind the XUL checkbox, which in addition to being a normal checkbox, can also be placed into a "tri-state" mode that adds a third, mixed, state.

Syntax

The XUL syntax for Checkboxes.

Toolboxes

Tag	Children	Attributes	Description
checkbox	n/a	value	A normal checkbox. To place in tristate mode, set the value to "2". From that moment on, the checkbox will behave as a tristate.

 

Important usage note: You must use the getAttribute and setAttribute JavaScript functions to access the "value" attribute. This is because we don't support the value property for non-HTML content elements in XUL.

Modify the look of the checkbox using CSS. xul.css uses the following two style rules, one for normal state, one for the depressed state (when the mouse is down and within the checkbox):

checkbox {
   display:inline;
   border: 1px solid black;
}

checkbox[depress] {
   background: darkGray;
   border: 1px inset black;
}

Behavior

The expected behavior of the checkbox is the following:

In "normal" mode, clicking the box will toggle the value between on and off, represented by the "value" attribute having the string values "1" and "0", respectively. The transitions, starting in the "on" state, are as follows:

on "1" -> off "0" -> on "1"

To get the checkbox into tristate mode, set the "value" attribute to "2". This will set the tristate checkbox to a "mixed" state and make it so that it is forever a tristate checkbox. The transitions, starting in "mixed" state, are as follows:

mixed "2" -> on "1" -> off "0" -> mixed "2"

---

Examples

Here is an example of XUL for both kinds of checkboxes. The first checkbox behaves normally. By setting the second checkbox's value to "2," it becomes a tristate checkbox from that moment on.

Notice that you must use the getAttribute and setAttribute JavaScript functions to access the "value" attribute. This is because we don't support the value property for non-HTML content.

<?xml version="1.0"?> 
<?xml-stylesheet href="xul.css" type="text/css"?> 

<!DOCTYPE window> 

<window style="width: 100%; height: 100%" xmlns:html="http://www.w3.org/TR/REC-html40"
        xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
        onload="setTri()"> 

<html:h1>TriStateCheckbox Test 1</html:h1>

<html:script>

function setTri()
{
  var tsbox = document.getElementById("tristate"); tsbox.setAttribute("value", "2");
}

</html:script>

<html:hr/>

<!-- this is a normal checkbox -->
<checkbox/>Dual state<html:br/>

<!-- this is a tristate checkbox after the setTri() function has been called -->
<checkbox id="tristate"/>Tri state baby!<html:br/>

<html:button onclick="setTri()">Click Me To Set TriState</html:button>

</window>