PDFOptionList · PDF-LIB

Represents an option list field of a PDFForm.

PDFOptionList fields are interactive lists of options. The purpose of an option list is to enable users to select one or more options from a set of possible options. Users are able to see the full set of options without first having to click on the field (though scrolling may be necessary). Clicking an option in the list will cause it to be selected and displayed with a highlighted background. Some option lists allow users to select more than one option (see PDFOptionList.isMultiselect).

Hierarchy

PDFField

↳ PDFOptionList

Index

Properties

Methods

Properties

acroField

• acroField: PDFAcroListBox

Overrides PDFField.acroField

Defined in api/form/PDFOptionList.ts:60

The low-level PDFAcroListBox wrapped by this option list.

doc

• doc: PDFDocument

Inherited from PDFField.doc

Defined in api/form/PDFField.ts:92

The document to which this field belongs.

ref

• ref: PDFRef

Inherited from PDFField.ref

Defined in api/form/PDFField.ts:89

The unique reference assigned to this field within the document.

Methods

addOptions

▸ addOptions(options: string | string[]): void

Defined in api/form/PDFOptionList.ts:176

Add to the list of options that are available for this option list. Users will be able to select these values in a PDF reader. In addition to the values passed as options, any preexisting options for this option list will still be available for users to select. For example:

const optionList = form.getOptionList('rockets.optionList')
optionList.addOptions(['Saturn IV', 'Falcon Heavy'])

This method will mark this option list as dirty. See PDFOptionList.setOptions for more details about what this means.

Parameters:

Name	Type	Description
`options`	string \| string[]	New options that should be available in this option list.

Returns: void

addToPage

▸ addToPage(page: PDFPage, options?: FieldAppearanceOptions): void

Defined in api/form/PDFOptionList.ts:448

Show this option list on the specified page. For example:

const ubuntuFont = await pdfDoc.embedFont(ubuntuFontBytes)
const page = pdfDoc.addPage()

const form = pdfDoc.getForm()
const optionList = form.createOptionList('best.gundams')
optionList.setOptions(['Exia', 'Dynames', 'Kyrios', 'Virtue'])
optionList.select(['Exia', 'Virtue'])

optionList.addToPage(page, {
  x: 50,
  y: 75,
  width: 200,
  height: 100,
  textColor: rgb(1, 0, 0),
  backgroundColor: rgb(0, 1, 0),
  borderColor: rgb(0, 0, 1),
  borderWidth: 2,
  rotate: degrees(90),
  font: ubuntuFont,
})

This will create a new widget for this option list field.

Parameters:

Name	Type	Description
`page`	PDFPage	The page to which this option list widget should be added.
`options?`	FieldAppearanceOptions	The options to be used when adding this option list widget.

Returns: void

clear

▸ clear(): void

Defined in api/form/PDFOptionList.ts:254

Clear all selected values for this option list. This operation is equivalent to selecting an empty list. This method will update the underlying state of the option list to indicate that no values have been selected. For example:

const optionList = form.getOptionList('some.optionList.field')
optionList.clear()

This method will mark this option list as dirty. See PDFOptionList.setOptions for more details about what this means.

Returns: void

defaultUpdateAppearances

▸ defaultUpdateAppearances(font: PDFFont): void

Overrides void

Defined in api/form/PDFOptionList.ts:519

Update the appearance streams for each of this option list's widgets using the default appearance provider for option lists. For example:

const helvetica = await pdfDoc.embedFont(StandardFonts.Helvetica)
const optionList = form.getOptionList('some.optionList.field')
optionList.defaultUpdateAppearances(helvetica)

Parameters:

Name	Type	Description
`font`	PDFFont	The font to be used for creating the appearance streams.

Returns: void

disableExporting

▸ disableExporting(): void

Inherited from PDFField.disableExporting

Defined in api/form/PDFField.ts:247

Indicate that this field's value should not be exported when the form is submitted in a PDF reader. For example:

const field = form.getField('some.field')
field.disableExporting()

Returns: void

disableMultiselect

▸ disableMultiselect(): void

Defined in api/form/PDFOptionList.ts:372

Do not allow users to select more than one option from this option list. For example:

const optionList = form.getOptionList('some.optionList.field')
optionList.disableMultiselect()

Returns: void

disableReadOnly

▸ disableReadOnly(): void

Inherited from PDFField.disableReadOnly

Defined in api/form/PDFField.ts:170

Allow users to interact with this field and change its value in PDF readers via mouse and keyboard input. For example:

const field = form.getField('some.field')
field.disableReadOnly()

Returns: void

disableRequired

▸ disableRequired(): void

Inherited from PDFField.disableRequired

Defined in api/form/PDFField.ts:208

Do not require this field to have a value when the form is submitted. For example:

const field = form.getField('some.field')
field.disableRequired()

Returns: void

disableSelectOnClick

▸ disableSelectOnClick(): void

Defined in api/form/PDFOptionList.ts:416

Wait to store the option selected by a user until they leave this option list field (by clicking outside of it - on another field, for example). For example:

const optionList = form.getOptionList('some.optionList.field')
optionList.disableSelectOnClick()

Returns: void

disableSorting

▸ disableSorting(): void

Defined in api/form/PDFOptionList.ts:334

Do not always display the options of this option list in alphabetical order. Instead, display the options in whichever order they were added to this option list. For example:

const optionList = form.getOptionList('some.optionList.field')
optionList.disableSorting()

Returns: void

enableExporting

▸ enableExporting(): void

Inherited from PDFField.enableExporting

Defined in api/form/PDFField.ts:235

Indicate that this field's value should be exported when the form is submitted in a PDF reader. For example:

const field = form.getField('some.field')
field.enableExporting()

Returns: void

enableMultiselect

▸ enableMultiselect(): void

Defined in api/form/PDFOptionList.ts:360

Allow users to select more than one option from this option list. For example:

const optionList = form.getOptionList('some.optionList.field')
optionList.enableMultiselect()

Returns: void

enableReadOnly

▸ enableReadOnly(): void

Inherited from PDFField.enableReadOnly

Defined in api/form/PDFField.ts:158

Prevent PDF readers from allowing users to interact with this field or change its value. The field will not respond to mouse or keyboard input. For example:

const field = form.getField('some.field')
field.enableReadOnly()

Useful for fields whose values are computed, imported from a database, or prefilled by software before being displayed to the user.

Returns: void

enableRequired

▸ enableRequired(): void

Inherited from PDFField.enableRequired

Defined in api/form/PDFField.ts:196

Require this field to have a value when the form is submitted. For example:

const field = form.getField('some.field')
field.enableRequired()

Returns: void

enableSelectOnClick

▸ enableSelectOnClick(): void

Defined in api/form/PDFOptionList.ts:403

Store the option selected by a user immediately after the user clicks the option. Do not wait for the user to leave this option list field (by clicking outside of it - on another field, for example). For example:

const optionList = form.getOptionList('some.optionList.field')
optionList.enableSelectOnClick()

Returns: void

enableSorting

▸ enableSorting(): void

Defined in api/form/PDFOptionList.ts:321

Always display the options of this option list in alphabetical order, irrespective of the order in which the options were added to this option list. For example:

const optionList = form.getOptionList('some.optionList.field')
optionList.enableSorting()

Returns: void

getName

▸ getName(): string

Inherited from PDFField.getName

Defined in api/form/PDFField.ts:128

Get the fully qualified name of this field. For example:

const fields = form.getFields()
fields.forEach(field => {
  const name = field.getName()
  console.log('Field name:', name)
})

Note that PDF fields are structured as a tree. Each field is the descendent of a series of ancestor nodes all the way up to the form node, which is always the root of the tree. Each node in the tree (except for the form node) has a partial name. Partial names can be composed of any unicode characters except a period (.). The fully qualified name of a field is composed of the partial names of all its ancestors joined with periods. This means that splitting the fully qualified name on periods and taking the last element of the resulting array will give you the partial name of a specific field.

Returns: string

The fully qualified name of this field.

getOptions

▸ getOptions(): string[]

Defined in api/form/PDFOptionList.ts:85

Get the list of available options for this option list. These options will be displayed to users who view this option list in a PDF reader. For example:

const optionList = form.getOptionList('some.optionList.field')
const options = optionList.getOptions()
console.log('Option List options:', options)

Returns: string[]

The options for this option list.

getSelected

▸ getSelected(): string[]

Defined in api/form/PDFOptionList.ts:109

Get the selected options for this option list. These are the values that were selected by a human user via a PDF reader, or programatically via software. For example:

const optionList = form.getOptionList('some.optionList.field')
const selections = optionList.getSelected()
console.log('Option List selections:', selections)

Returns: string[]

The selected options for this option list.

isExported

▸ isExported(): boolean

Inherited from PDFField.isExported

Defined in api/form/PDFField.ts:223

Returns true if this field's value should be exported when the form is submitted. See PDFField.enableExporting and PDFField.disableExporting. For example:

const field = form.getField('some.field')
if (field.isExported()) console.log('Exporting is enabled')

Returns: boolean

Whether or not this field's value should be exported.

isMultiselect

▸ isMultiselect(): boolean

Defined in api/form/PDFOptionList.ts:348

Returns true if multiple options can be selected from this option list. See PDFOptionList.enableMultiselect and PDFOptionList.disableMultiselect. For example:

const optionList = form.getOptionList('some.optionList.field')
if (optionList.isMultiselect()) console.log('Multiselect is enabled')

Returns: boolean

Whether or not multiple options can be selected.

isReadOnly

▸ isReadOnly(): boolean

Inherited from PDFField.isReadOnly

Defined in api/form/PDFField.ts:143

Returns true if this field is read only. This means that PDF readers will not allow users to interact with the field or change its value. See PDFField.enableReadOnly and PDFField.disableReadOnly. For example:

const field = form.getField('some.field')
if (field.isReadOnly()) console.log('Read only is enabled')

Returns: boolean

Whether or not this is a read only field.

isRequired

▸ isRequired(): boolean

Inherited from PDFField.isRequired

Defined in api/form/PDFField.ts:184

Returns true if this field must have a value when the form is submitted. See PDFField.enableRequired and PDFField.disableRequired. For example:

const field = form.getField('some.field')
if (field.isRequired()) console.log('Field is required')

Returns: boolean

Whether or not this field is required.

isSelectOnClick

▸ isSelectOnClick(): boolean

Defined in api/form/PDFOptionList.ts:390

Returns true if the option selected by a user is stored, or "committed", when the user clicks the option. The alternative is that the user's selection is stored when the user leaves this option list field (by clicking outside of it - on another field, for example). See PDFOptionList.enableSelectOnClick and PDFOptionList.disableSelectOnClick. For example:

const optionList = form.getOptionList('some.optionList.field')
if (optionList.isSelectOnClick()) console.log('Select on click is enabled')

Returns: boolean

Whether or not options are selected immediately after they are clicked.

isSorted

▸ isSorted(): boolean

Defined in api/form/PDFOptionList.ts:307

Returns true if the options of this option list are always displayed in alphabetical order, irrespective of the order in which the options were added to the option list. See PDFOptionList.enableSorting and PDFOptionList.disableSorting. For example:

const optionList = form.getOptionList('some.optionList.field')
if (optionList.isSorted()) console.log('Sorting is enabled')

Returns: boolean

Whether or not this option list is sorted.

needsAppearancesUpdate

▸ needsAppearancesUpdate(): boolean

Overrides void

Defined in api/form/PDFOptionList.ts:495

Returns true if this option list has been marked as dirty, or if any of this option list's widgets do not have an appearance stream. For example:

const optionList = form.getOptionList('some.optionList.field')
if (optionList.needsAppearancesUpdate()) console.log('Needs update')

Returns: boolean

Whether or not this option list needs an appearance update.

select

▸ select(options: string | string[], merge: boolean): void

Defined in api/form/PDFOptionList.ts:213

Select one or more values for this option list. This operation is analogous to a human user opening the option list in a PDF reader and clicking on one or more values to select them. This method will update the underlying state of the option list to indicate which values have been selected. PDF libraries and readers will be able to extract these values from the saved document and determine which values were selected. For example:

const optionList = form.getOptionList('best.superheroes.optionList')
optionList.select(['One Punch Man', 'Iron Man'])

This method will mark this option list as dirty. See PDFOptionList.setOptions for more details about what this means.

Parameters:

Name	Type	Default	Description
`options`	string \| string[]	-	The options to be selected.
`merge`	boolean	false	Whether or not existing selections should be preserved.

Returns: void

setFontSize

▸ setFontSize(fontSize: number): void

Defined in api/form/PDFOptionList.ts:290

Set the font size for this field. Larger font sizes will result in larger text being displayed when PDF readers render this option list. Font sizes may be integer or floating point numbers. Supplying a negative font size will cause this method to throw an error.

For example:

const optionList = form.getOptionList('some.optionList.field')
optionList.setFontSize(4)
optionList.setFontSize(15.7)

This method depends upon the existence of a default appearance (/DA) string. If this field does not have a default appearance string, or that string does not contain a font size (via the Tf operator), then this method will throw an error.

Parameters:

Name	Type	Description
`fontSize`	number	The font size to be used when rendering text in this field.

Returns: void

setOptions

▸ setOptions(options: string[]): void

Defined in api/form/PDFOptionList.ts:151

Set the list of options that are available for this option list. These are the values that will be available for users to select when they view this option list in a PDF reader. Note that preexisting options for this option list will be removed. Only the values passed as options will be available to select.

For example:

const optionList = form.getOptionList('planets.optionList')
optionList.setOptions(['Earth', 'Mars', 'Pluto', 'Venus'])

This method will mark this option list as dirty, causing its appearance streams to be updated when either PDFDocument.save or PDFForm.updateFieldAppearances is called. The updated streams will display the options this field contains inside the widgets of this text field (with selected options highlighted).

IMPORTANT: The default font used to update appearance streams is StandardFonts.Helvetica. Note that this is a WinAnsi font. This means that encoding errors will be thrown if this field contains any options with characters outside the WinAnsi character set (the latin alphabet).

Embedding a custom font and passing it to PDFForm.updateFieldAppearances or PDFOptionList.updateAppearances allows you to generate appearance streams with characters outside the latin alphabet (assuming the custom font supports them).

Parameters:

Name	Type	Description
`options`	string[]	The options that should be available in this option list.

Returns: void

updateAppearances

▸ updateAppearances(font: PDFFont, provider?: AppearanceProviderFor‹PDFOptionList›): void

Defined in api/form/PDFOptionList.ts:540

Update the appearance streams for each of this option list's widgets using the given appearance provider. If no provider is passed, the default appearance provider for option lists will be used. For example:

const helvetica = await pdfDoc.embedFont(StandardFonts.Helvetica)
const optionList = form.getOptionList('some.optionList.field')
optionList.updateAppearances(helvetica, (field, widget, font) => {
  ...
  return drawOptionList(...)
})

Parameters:

Name	Type	Description
`font`	PDFFont	The font to be used for creating the appearance streams.
`provider?`	AppearanceProviderFor‹PDFOptionList›	Optionally, the appearance provider to be used for generating the contents of the appearance streams.

Returns: void

`Static` of

▸ of(acroListBox: PDFAcroListBox, ref: PDFRef, doc: PDFDocument): PDFOptionList‹›

Defined in api/form/PDFOptionList.ts:56

NOTE: You probably don't want to call this method directly. Instead, consider using the PDFForm.getOptionList method, which will create an instance of PDFOptionList for you.

Create an instance of PDFOptionList from an existing acroListBox and ref

Parameters:

Name	Type	Description
`acroListBox`	PDFAcroListBox	-
`ref`	PDFRef	The unique reference for this option list.
`doc`	PDFDocument	The document to which this option list will belong.

Returns: PDFOptionList‹›

Hierarchy

Index

Properties

Methods

Properties

acroField

doc

ref

Methods

addOptions

addToPage

clear

defaultUpdateAppearances

disableExporting

disableMultiselect

disableReadOnly

disableRequired

disableSelectOnClick

disableSorting

enableExporting

enableMultiselect

enableReadOnly

enableRequired

enableSelectOnClick

enableSorting

getName

getOptions

getSelected

isExported

isMultiselect

isReadOnly

isRequired

isSelectOnClick

isSorted

needsAppearancesUpdate

select

setFontSize

setOptions

updateAppearances

Static of

`Static` of