Checkbox (Tri-State)

[Table of Contents] [Previous: Progress Meter] [Next: The Box System]

Feature Owner: Mike Pinkerton

Note: currently the -moz-tristate style property is not implemented, but is implemented as an attribute. This should be fixed by M10.

There are two types of checkboxes: regular and tri-state. Regular checkboxes are exactly the same as checkboxes on web pages in HTML. Tri-state checkboxes are capable of being in three states: unchecked, mixed, and checked in that order.

Both types of checkboxes are declared using the normal HTML tag <html:input type="checkbox">. The only difference is that for tri-state checkboxes, you specify a style rule indicating it is tri-state (setting -moz-tristate equal to true).

For normal checkboxes, you can use the checked property for accessing and changing the state of the checkbox. Since this property is a boolean, we cannot use it when the checkbox is in tri-state mode. As a result, you must use the getAttribute and setAttribute AOM functions to access the -mox-tristatevalue attribute.

At any time, a checkbox may be switched to the other mode by setting -moz-tristate appropriately. The current value will be maintained, unless of course it is in the mixed state and it is transforming back into a normal checkbox. In this case, the box will revert to being checked. Note that the -mox-tristatevalue attribute is not present when the checkbox is in normal mode, and will be removed when transforming from tri-state to normal mode. This is to ensure that the normal checkbox does not deviate from the HTML4 standard.

Checkboxes may be placed within labels (<html:label>) so that clicking on the explanitory text of the checkbox will toggle it.

<?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"
  align="vertical"> 
                  
<html:script>
                  
function setTriMixed()
{
  var tsbox = document.getElementById("tristate"); 
  tsbox.setAttribute("-moz-tristatevalue", "2");
}
                  
function setNormalChecked ()
{
  var tsbox = document.getElementById("normal"); 
  tsbox.checked = true;
}
                  
</html:script>
                  
<html:hr/>
                  
<!-- this is a normal checkbox -->
<html:label>
<html:input type="checkbox" id="normal"/>Normal checkbox
</html:label>
                  
<html:br/>
                  
<!-- this is a tristate checkbox -->
<html:label>
<html:input type=checkbox id="tristate" style="-moz-tristate: true"/>
   Tri-state checkbox
</html:label>
                  
<!-- some buttons that just set the value of the checkboxes -->
<html:button onclick="setTriMixed()">Set Tri-State To Mixed State
</html:button>
<html:button onclick="setNormalChecked()">Set Normal To Checked
</html:button>
                  
</window>

The checkbox's look on a mouse down can be controlled using CSS, as well as the look when the mouse is hovering over the box.

input[type=checkbox]:active {
   background: darkGray;
   border: 1px inset black;
}
                  
input[type=checkbox]:hover {
   border: 1px solid black;
}

[Table of Contents] [Previous: Progress Meter] [Next: The Box System]
Contact us at xptoolkitstaff@netscape.com. Want to complain about the new documentation? Email Dave Hyatt.