New List Object Properties and Methods

Some of you may recall my tutorial on sorting lists at runtime which I posted last June. Oh how I wish I had waited until the release of Designer and Acrobat 8.0 in order to write it! With the new release of these two products comes a new API for list objects that would’ve significantly simplified things: Rather than having to know details about how list object items are represented in XFA (using an <items> node for item text values and an <items save="1"> node for item data values) and manipulating these nodes in script, I could’ve used methods such as getDisplayItem and getSaveItem.

New Properties

  • length: Returns the number of items in the list object. This property is read-only.
  • selectedIndex: Returns the zero-based index of the first-found item which is selected or -1 if the list has no selection. You may set this property in order to set a new selection in the list or set it to -1 in order to remove the selection entirely. Note that setting this property will first de-select any currently-selected items prior to applying the new selection.

New Methods

  • bool getItemState(int index): Returns true (1 in FormCalc) if the list item specified by the zero-based index parameter is currently selected in the list.
  • setItemState(int index, bool state): Add or remove a list item from the selection by specifying its zero-based index and true to select or false to de-select it (1 or 0, respectively, in FormCalc). Note that if the list object does not support multiple selection (drop down lists typically don’t), using this method will have the same effect as setting the selectedIndex property.
  • string getDisplayItem(int index): Returns a list item’s text value (this pertains to the list’s <items> element in XFA) based on a zero-based index into the list.
  • string getSaveItem(int index): Returns a list item’s data value (this pertains to the list’s <items save="1"> element in XFA) based on a zero-based index into the list.
  • bool deleteItem(int index): Deletes the list item specified by a zero-based index and returns true (1 in FormCalc) to indicate that the item was effectively deleted.

Demo Form

In order to show-off this cool new API (available in both JavaScript and FormCalc), I designed a little form that uses all the new properties and methods. Play with it in Acrobat 8.0 and check out the script in Designer 8.0. I’m certain it’ll make your life a whole lot easier when it comes to scripting list boxes and drop down lists.

Download Sample [pdf]

Minimum Requirements: Designer 8.0, Acrobat 8.0.

Note that you must click away from the "List Box" object after you’ve set a selection since the list is set to commit its selection on exit (as is recommended when supporting multiple selection). You can specify this by setting the "Commit On" property on the Object palette’s Field tab to "Exit".