Method createListbox

src/api/pdf-form.ts:891–985

* Create a new list box field. * * @param name - Field name (must be unique) * @param options - Listbox options (options array is required) * @returns The created listbox field * @throws {Error} If a field with the same name already exists * @throws {Error} If options array is empt

(name: string, options: ListboxOptions)

   * ```
   */
  createListbox(name: string, options: ListboxOptions): ListBoxField {
    this.validateUniqueName(name);

    if (!options.options || options.options.length === 0) {
      throw new Error("Listbox must have at least one option");
    }

    // Choice field type without Combo flag = list box
    let flags = 0;

    if (options.multiSelect) {
      flags |= FieldFlags.MULTI_SELECT;
    }

    // Build default appearance string
    const da = this.buildDefaultAppearance(options.font, options.fontSize, options.color);

    // Create field dictionary with /Kids array (separate widget model)
    const fieldDict = PdfDict.of({
      FT: PdfName.of("Ch"),
      T: PdfString.fromString(name),
      Kids: new PdfArray([]),
      Opt: PdfArray.of(...options.options.map(o => PdfString.fromString(o))),
    });

    if (flags !== 0) {
      fieldDict.set("Ff", PdfNumber.of(flags));
    }

    if (da) {
      fieldDict.set("DA", PdfString.fromString(da));
    }

    // Handle default value(s)
    if (options.defaultValue && options.defaultValue.length > 0) {
      const validDefaults = options.defaultValue.filter(v => options.options.includes(v));

      if (validDefaults.length === 1) {
        fieldDict.set("V", PdfString.fromString(validDefaults[0]));
        fieldDict.set("DV", PdfString.fromString(validDefaults[0]));
      } else if (validDefaults.length > 1) {
        fieldDict.set("V", PdfArray.of(...validDefaults.map(v => PdfString.fromString(v))));
        fieldDict.set("DV", PdfArray.of(...validDefaults.map(v => PdfString.fromString(v))));

        // Set /I (selection indices)
        const indices = validDefaults
          .map(v => options.options.indexOf(v))
          .filter(i => i >= 0)
          .sort((a, b) => a - b);
        fieldDict.set("I", PdfArray.of(...indices.map(i => PdfNumber.of(i))));
      }
    }

    // Register font in form resources if embedded font provided
    if (options.font) {
      this.registerFontInFormResources(options.font);
    }