Recipe 11.7 Adding Radio Buttons to a Group

11.7.1 Problem

You want to add a group of radio buttons to your form.

11.7.2 Solution

Add radio button instances and assign them to a group using setGroupName( ).

11.7.3 Discussion

Use the radio button UI component to present several mutually exclusive choices. Radio buttons work best with a limited number of items. For a choice among many items, use a combo box or list box. When you create a radio button, you must assign it a label and, in many cases, some data. The label is the text displayed next to the radio button, and the data is stored for programmatic processing when the radio button has been selected and submitted. Even in cases where the label and data are the same, you should still assign a value for the data. This is because it is good practice to retrieve the value for a selected radio button from its data value, not from its label. You should set these values using the setLabel( ) and setData( ) methods. The label should be a string value, but the data can be of any datatype.

This example shows that the data can be a complex object, which can be stored, used for processing or transmitted to a server when the radio button is selected:

// Create a radio button named myRadioButton0_rb.
_root.attachMovie("FRadioButtonSymbol", "myRadioButton0_rb", 1);

// Set the label so that the radio button displays the text "item 1".
myRadioButton0_rb.setLabel("item 1");

// Assign a data object with id and description properties.
myRadioButton0_rb.setData({id: 25, description: "this is an item"});

Every radio button must belong to a radio button group so that ActionScript can ensure that radio buttons within the group are mutually exclusive.

If you want to allow a user to select multiple options from a list, use multiple checkboxes or a multiple-selection list box instead of radio buttons. If there is only one choice, use a checkbox.

You should add each radio button to a group using the setGroupName( ) method, which takes a string parameter specifying the name of the group to which the radio button should be assigned:

myRadioButton0_rb.setGroupName("myRadioButtons");

Radio button group names are arbitrary, but it is good practice to give each group a name that relates to its purpose and name each radio button in a numbered sequence. Here is an example that illustrates this point with a radio button group for travel preferences:

// Create four radio buttons, travelPrefs0_rb through travelPrefs3_rb, and assign
// them to the "travelPrefs" group. Note that the label and data are both set for
// each button, as is good practice, even though both contain the same value.
_root.attachMovie("FRadioButtonSymbol", "travelPrefs0_rb", 1);
_root.attachMovie("FRadioButtonSymbol", "travelPrefs1_rb", 2);
_root.attachMovie("FRadioButtonSymbol", "travelPrefs2_rb", 3);
_root.attachMovie("FRadioButtonSymbol", "travelPrefs3_rb", 4);

travelPrefs0_rb.setGroupName("travelPrefs");
travelPrefs1_rb.setGroupName("travelPrefs");
travelPrefs2_rb.setGroupName("travelPrefs");
travelPrefs3_rb.setGroupName("travelPrefs");

travelPrefs0_rb.setLabel("spring");
travelPrefs0_rb.setData ("spring");
travelPrefs1_rb.setLabel("summer");
travelPrefs1_rb.setData ("summer");
travelPrefs2_rb.setLabel("fall");
travelPrefs2_rb.setData ("fall");
travelPrefs3_rb.setLabel("winter");
travelPrefs3_rb.setData ("winter");

// Position the radio buttons.
travelPrefs0_rb._y = 100;
travelPrefs1_rb._y = 120;
travelPrefs2_rb._y = 140;
travelPrefs3_rb._y = 160;

There are two important potential problems that become apparent when you start programmatically adding radio buttons. First of all, the labels appear on the right side of the buttons by default. Fortunately, you can use setLabelPlacement("left") to place the label to the left of the radio button. Furthermore, to set the same placement for all radio buttons in a group, you can invoke setLabelPlacement( ) on the radio group object (the group object is automatically created with the name passed to setGroupName( )). You must create the radio buttons and assign them to the group before invoking setLabelPlacement( ) on the group object. For example:

// Align the labels to the left of the radio buttons in the travelPrefs group.
travelPrefs0_rb.setGroupName("travelPrefs");
travelPrefs1_rb.setGroupName("travelPrefs");
travelPrefs2_rb.setGroupName("travelPrefs");
travelPrefs3_rb.setGroupName("travelPrefs");
travelPrefs.setLabelPlacement("left");

Another problem becomes apparent when you add labels that extend beyond the default width of the radio button, in which case the text is cut off in the display. You can create a custom method for FRadioButtonGroupClass (the class for radio button groups) to automatically resize the labels of all the radio buttons in the group. To do so, you must be able to reference the text fields containing the radio buttons' label text. The path to the text field of a radio button is undocumented, but it can be referenced as this.fLabel_mc.labelField from each radio button. You also must be able to reference each radio button from the group object. Radio button groups have an undocumented property—an array named radioInstances containing references to the radio button instances—that works perfectly for this purpose.

Here is a custom adjustWidth( ) method for the FRadioButtonGroupClass class, which you can add to your Form.as file for easy inclusion in future projects:

FRadioButtonGroupClass.prototype.adjustWidth = function (  ) {
  var tf;

  // Loop through all the radio buttons in the group.
  for (var i = 0; i < this.radioInstances.length; i++) {

    // Set each label text field to auto size.
    tf = this.radioInstances[i].fLabel_mc.labelField;
    tf.autoSize = true;

    // Set the width of each radio button to the width of the text field plus 13. The
    // 13 pixels account for the width of the button graphic.
    this.radioInstances[i].setSize(tf._width + 13);

  }
};