Recipe 11.10 Adding Checkboxes to a Form

11.10.1 Problem

You want to add checkboxes to your form.

11.10.2 Solution

Use checkbox UI components.

11.10.3 Discussion

You should use checkboxes in situations in which you want a user to be able to select multiple options from a list, but you do not wish to use a list box. Or, alternatively, you should use a checkbox in any situation that calls for a simple yes/no or true/false answer. Checkboxes function similarly to radio buttons, except for a few important distinctions:

• You cannot set a data value for a checkbox. Checkboxes have only two possible values: true (checked) or false (unchecked).

• Checkboxes do not have a natively available group as radio buttons do.

• Multiple checkboxes should not be used for mutually exclusive choices.

You can set the label of a checkbox with the setLabel( ) method, and you can set the placement of the label (right or left) using the setLabelPlacement( ) method, just as with radio buttons.

The fact that checkboxes don't provide native support for grouping, as radio buttons do, is not necessarily a problem. However, by adding grouping functionality to checkboxes (and coding the checkbox group class to inherit from the radio button group class), you can easily leverage the resizing and positioning code from Recipe 11.7 and Recipe 11.8 for radio button groups to work with checkboxes.

You can create a custom checkbox group class as follows:

The following code uses variables and properties with "radio" in their names instead of "checkbox." Do not be confused by this. This is merely because the checkbox group class inherits from the radio button group class, and therefore the references are to radio buttons even though in truth they are checkboxes.

Here is our custom setGroupName( ) code for the FCheckBoxGroupClass class:

// FCheckBoxGroupClass should be defined globally just as the other UI component
// classes. Set the class to inherit from FRadioButtonGroupClass. This means that all
// the functionality of FRadioButtonGroupClass is accessible to the new class.
_global.FCheckBoxGroupClass = function (  ) {};
FCheckBoxGroupClass.prototype = new FRadioButtonGroupClass(  );

// Define a setGroupName(  ) method for checkboxes, which is the 
// same as the one for radio buttons.  
FCheckBoxClass.prototype.setGroupName = function (groupName) {
  for (var i = 0; i < this._parent[this.groupName].radioInstances.length; i++) {
    if (this._parent[this.groupName].radioInstances[i] == this) {
      delete this._parent[this.groupName].radioInstances[i];
    }
  }
  this.groupName = groupName;
  this.addToRadioGroup(  );
};

// Define addToRadioGroup(  ) for checkboxes. This method is called from
// setGroupName(  ). It is the same method as the addToRadioGroup(  ) method for radio
// buttons, except it creates a new instance of FCheckBoxGroupClass instead of
// FRadioButtonGroupClass.
FCheckBoxClass.prototype.addToRadioGroup = function (  ) {
  if (this._parent[this.groupName] == undefined) {
    this._parent[this.groupName] = new FCheckBoxGroupClass(  );
  }
  this._parent[this.groupName].addRadioInstance(this);
};

Once you have defined the preceding code, and added it to Forms.as, you can assign checkboxes to checkbox groups as you would assign radio buttons to radio button groups:

#include "Forms.as"
myCheckBox0_ch.setGroupName("myCheckBoxGroup");

The methods of radio button groups are then available to checkbox groups. Though most of the methods are not applicable, the custom setPositions( ) and adjustWidth( ) methods from Recipe 11.7 and Recipe 11.8 are:

// You can call the adjustWidth(  ) and setPositions(  ) methods from checkbox groups.
myCheckBoxGroup.adjustWidth(  );
myCheckBoxGroup.setPositions(100, 100, 2);

Another useful feature of checkbox groups is that you can also call the setLabelPlacement( ) method from the group, as you can from a radio button group!

// Set the label placement for all the checkboxes in the group to the left.
myCheckBoxGroup.setLabelPlacement("left");