XFA choice item scripting
Unit: HPDFXFARuntime
A field with ui.choiceList exposes choice item methods during native JavaScript and FormCalc event execution, including repeated field instances and aliases retained by script objects
Methods and properties
| Member | Behaviour |
|---|---|
length | Read-only number of current export items |
selectedIndex | First selected zero-based index, or -1 when none is selected; assigning any negative integer clears the selection, whilst an out-of-range non-negative value or noninteger throws before changing it |
getDisplayItem(index) | Display text at the index, or null when the index is invalid |
getSaveItem(index) | Export text at the index, or null when the index is invalid |
boundItem(display) | Export text for the first exact matching display text, or null when no display text matches |
getItemState(index) | Whether the item is selected; an invalid index throws |
setItemState(index, selected) | Update the selection of the item; selecting an item replaces the previous selection for a single-select field and preserves other selected indices for a multi-select field |
addItem(display, bound) | Append an item without changing the existing selected items; omitting the second argument uses an empty export string |
deleteItem(index) | Delete an item and shift later indices whilst retaining the identity of surviving item aliases; return false for an invalid index |
clearItems() | Remove current items and clear selection; an explicitly empty runtime list remains empty after save and reload |
setItems(text, columns) | Replace current items from comma-separated columns and clear selection; columns defaults to 1, a one-column row supplies both display and export text, and a longer row uses its first column as display text and last column as export text; return false if the column count is invalid or does not divide the input field count |
Indices are integers and are never coerced from strings; item methods require their documented argument counts, with the optional second argument accepted by addItem and setItems
Item values preserve Unicode, leading and trailing spaces, explicit empty exports and line breaks; invalid XML control characters and unpaired UTF-16 surrogates are rejected before list mutation
Immediate state and aliases
New items are immediately visible through item methods and the property DOM, and a deleted item alias cannot redirect to a surviving item that moves into the deleted index
Replacing or clearing the list creates distinct replacement identities; retained script-object aliases to removed items fail on later reads and writes, whilst surviving aliases continue to address the same item across event executions
A direct rawValue assignment, bound Data DOM write, public widget value commit or export-item scalar mutation invalidates cached explicit indices, including assignments that preserve the same raw string
Persistence and exact selection
SaveToBytes writes the actual per-instance form items and synchronised values; modifying a repeated instance preserves other instances and their data scopes
Duplicate and empty exports can be selected by exact indices through the item API; the saved form field records the canonical indices and matching raw value in optional attributes in the urn:hotpdf:xfa:runtime namespace
Standard XFA items and value nodes remain present independently of these optional attributes; later value writes invalidate the attributes so stale indices cannot select the wrong duplicate export
The native PDF consumer writes matching /Opt export/display pairs, exact /I indices and /V strings or arrays, and builds appearances from the selected display labels
Transactions and limits
Item changes participate in the existing event transaction and script journal; a native value-limit failure, caller cancellation or unhandled event exception restores saved XDP, script lexical state and bindings before a later retry
Node allocations, input columns, UTF-8 values, XML operation payloads, native property traversal and cloning retain the configured script and runtime budgets and cancellation checks
Example
var list = this.parent.choice;
list.clearItems();
list.addItem("Display A", "same");
list.addItem("Display B", "same");
list.selectedIndex = 1;
if (list.getDisplayItem(list.selectedIndex) !== "Display B")
throw new Error("Unexpected selected label");For FormCalc variables that retain a field rather than its scalar value, use var list = Ref($.parent.choice) before calling item methods
The method vocabulary and column arguments follow the Adobe Designer Scripting Reference; the runtime uses replacement semantics for setItems, as described in Adobe's HTML5 forms scripting support