Recipe 11.20 Prepopulating a Form

11.20.1 Problem

You want to programmatically fill in a form with defaults or a user's previous selections.

11.20.2 Solution

Use the methods and properties that allow you to set the values of each form element.

11.20.3 Discussion

Each type of form element has different ways of selecting the element or modifying its value. For example, you can set a text field's contents using the text property:

myTextField_txt.text = value;

You can set combo boxes and single-select list boxes using the setSelectedIndex( ) method. This method requires you to know the index of the item you wish to select programmatically (and not just its label or data value).

// Selects the third item from the menu
myComboBox_cb.setSelectedIndex(2);

You can programmatically select multiple items from a multiple-selection list box using the setSelectedIndices( ) method, which accepts an array of indexes to select:

// Selects the first three menu items from a multiple-selection list box
myListBox_lb.setSelectedIndices([0, 1, 2]);

To set a combo box or list box by its label or data property (rather than by its index), you can create a custom setSelectedItem( ) method for FSelectableListClass (the superclass of both combo boxes and list boxes). The method should accept a single parameter, which is the data value for the desired menu item. If the data properties of the menu items are all undefined, the setSelectedItem( ) method should try to match the value to a label instead. Additionally, you can create a setSelectedItems( ) method using the same basic process but you would set multiple items in a multiple-selection list box. The setSelectedItems( ) method should take an array of values (data values or labels to select).

Here is the custom setSelectedItem( ) method for list boxes and combo boxes. Make sure to add this code to your Form.as file, and remember that you can always download the completed version from http://www.person13.com/ascb.

FSelectableListClass.prototype.setSelectedItem = function (val) {
  var item, itemVal;

  // Loop through all the items in the menu. The getLength(  ) method returns the
  // number of items in the menu.
  for (var i = 0; i < this.getLength(  ); i++) {

    // Get each item using the getItemAt(  ) method.
    item = this.getItemAt(i);

    // If the data property is not undefined, use it for testing matches. Otherwise,
    // use the label property.
    if (item.data != undefined) {
      itemVal = item.data;
    } else {
      itemVal = item.label;
    }

    // If the data or label property matches the input val, call setSelectedIndex(  ),
    // passing it the current for loop index (i). Use a return statement to exit once
    // one item is found and selected.
    if (val == itemVal) {
      this.setSelectedIndex(i);
      return;
    }
  }
};

Here is the custom setSelectedItems( ) method for multiple-selection list boxes:

FSelectableListClass.prototype.setSelectedItems = function (vals) {
  var item, itemVal;

  // Create an array to holds the indexes of the items to select.
  var selectedIndices = new Array(  );

  // Loop through all the menu items. This uses similar logic as the
  // setSelectedItem(  ) method.
  for (var i = 0; i < this.getLength(  ); i++) {
    item = this.getItemAt(i);
    if (item.data != undefined) {
      itemVal = item.data;
    } else {
      itemVal = item.label;
    }

    // The vals parameter is an array of values, so we loop through each element to
    // see if it matches with data or label. If so, it's a match, so add the current
    // for statement index (i) to the selectedIndices array.
    for (var j = 0; j < vals.length; j++) {
      if (vals[j] == itemVal) {
        selectedIndices.push(i);
      }
    }
  }

  // Call the setSelectedIndices(  ) method for this list box and pass it the
  // selectedIndices array that was populated in the preceding for statement.
  this.setSelectedIndices(selectedIndices);
};

Here is an example of how to use these methods:

#include "Form.as"

// Create a combo box and populate it using a simple array. This means that each item
// has a label property but not a data property.
_root.attachMovie("FComboBoxSymbol", "myComboBox0_cb", 1);
myComboBox0_cb.setDataProvider(["a", "b", "c"]);

// Call setSelectedItem(  ) with the label value "b" to select that item.
myComboBox0_cb.setSelectedItem("b");

// Create a combo box and populate it using a more complex data provider such that
// each menu item has both a label and a data property.
_root.attachMovie("FComboBoxSymbol", "myComboBox1_cb", 2, {_y: 40});
dp = new Array(  );
dp.push({label: "a", data: 24});
dp.push({label: "b", data: 33});
dp.push({label: "c", data: 42});
myComboBox1_cb.setDataProvider(dp);

// Call the setSelectedItem(  ) method with a data value. This selects the menu item
// that corresponds (label "c").
myComboBox1_cb.setSelectedItem(42);

// Create a multiple-selection list box and populate it using the same data provider
// as the preceding combo box.
_root.attachMovie("FListBoxSymbol", "myListBox_lb", 3, {_y: 80});
myListBox_lb.setSelectMultiple(true);
myListBox_lb.setDataProvider(dp);

// Call setSelectedItems(  ) with an array of data values. This selects the menu items
// with labels "a" and "c".
myListBox_lb.setSelectedItems([24, 42]);