happypdf / PDFOptionList

Class: PDFOptionList

Defined in: src/api/form/PDFOptionList.ts:43

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]]).

Extends

PDFField

Properties

acroField

readonly acroField: PDFAcroListBox;

Defined in: src/api/form/PDFOptionList.ts:60

The low-level PDFAcroListBox wrapped by this option list.

Overrides

PDFField.acroField

doc

readonly doc: PDFDocument;

Defined in: src/api/form/PDFField.ts:96

The document to which this field belongs.

Inherited from

PDFField.doc

ref

readonly ref: PDFRef;

Defined in: src/api/form/PDFField.ts:93

The unique reference assigned to this field within the document.

Inherited from

PDFField.ref

Methods

addOptions()

addOptions(options): void;

Defined in: src/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

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

Returns

void

addToPage()

addToPage(page, options?): void;

Defined in: src/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

Parameter	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: src/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

createImageAppearanceStream()

protected createImageAppearanceStream(
   widget, 
   image, 
   alignment): PDFRef;

Defined in: src/api/form/PDFField.ts:498

Create a FormXObject of the supplied image and add it to context. The FormXObject size is calculated based on the widget (including the alignment).

Parameters

Parameter	Type	Description
`widget`	`PDFWidgetAnnotation`	The widget that should display the image.
`image`	`PDFImage`	The image that should be displayed.
`alignment`	`ImageAlignment`	The alignment of the image.

Returns

PDFRef

The ref for the FormXObject that was added to the context.

Inherited from

PDFField.createImageAppearanceStream

createWidget()

protected createWidget(options): PDFWidgetAnnotation;

Defined in: src/api/form/PDFField.ts:333

Parameters

Parameter	Type
`options`	{ `backgroundColor?`: `Color`; `borderColor?`: `Color`; `borderWidth`: `number`; `caption?`: `string`; `height`: `number`; `hidden?`: `boolean`; `page?`: `PDFRef`; `rotate`: `Rotation`; `textColor?`: `Color`; `width`: `number`; `x`: `number`; `y`: `number`; }
`options.backgroundColor?`	`Color`
`options.borderColor?`	`Color`
`options.borderWidth`	`number`
`options.caption?`	`string`
`options.height`	`number`
`options.hidden?`	`boolean`
`options.page?`	`PDFRef`
`options.rotate`	`Rotation`
`options.textColor?`	`Color`
`options.width`	`number`
`options.x`	`number`
`options.y`	`number`

Returns

PDFWidgetAnnotation

Inherited from

PDFField.createWidget

defaultUpdateAppearances()

defaultUpdateAppearances(font): void;

Defined in: src/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

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

Returns

void

Overrides

PDFField.defaultUpdateAppearances

disableExporting()

disableExporting(): void;

Defined in: src/api/form/PDFField.ts:251

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

Inherited from

PDFField.disableExporting

disableMultiselect()

disableMultiselect(): void;

Defined in: src/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;

Defined in: src/api/form/PDFField.ts:174

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

Inherited from

PDFField.disableReadOnly

disableRequired()

disableRequired(): void;

Defined in: src/api/form/PDFField.ts:212

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

Inherited from

PDFField.disableRequired

disableSelectOnClick()

disableSelectOnClick(): void;

Defined in: src/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: src/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;

Defined in: src/api/form/PDFField.ts:239

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

Inherited from

PDFField.enableExporting

enableMultiselect()

enableMultiselect(): void;

Defined in: src/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;

Defined in: src/api/form/PDFField.ts:162

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

Inherited from

PDFField.enableReadOnly

enableRequired()

enableRequired(): void;

Defined in: src/api/form/PDFField.ts:200

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

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

Returns

void

Inherited from

PDFField.enableRequired

enableSelectOnClick()

enableSelectOnClick(): void;

Defined in: src/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: src/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

getAction()

getAction(): PDFJavaScriptAction | undefined;

Defined in: src/api/form/PDFField.ts:290

Get the default action (A) for this field. This is typically a submit or reset action, or can be a JavaScript action. For example:

const field = form.getField('some.field')
const action = field.getAction()
if (action) {
  console.log('Action script:', action.getScript())
}

Returns

PDFJavaScriptAction | undefined

The JavaScript action, or undefined if not a JavaScript action.

Inherited from

PDFField.getAction

getJavaScriptActions()

getJavaScriptActions(): 
  | JavaScriptActionMap
  | undefined;

Defined in: src/api/form/PDFField.ts:271

Get the JavaScript actions associated with this field. Returns a map of action types to JavaScript actions. For example:

const field = form.getField('some.field')
const actions = field.getJavaScriptActions()
if (actions.keystroke) {
  console.log('Keystroke script:', actions.keystroke.getScript())
}
if (actions.calculate) {
  console.log('Calculate script:', actions.calculate.getScript())
}

Returns

| JavaScriptActionMap | undefined

A map of JavaScript actions for this field, or undefined if none exist.

Inherited from

PDFField.getJavaScriptActions

getName()

getName(): string;

Defined in: src/api/form/PDFField.ts:132

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.

Inherited from

PDFField.getName

getOptions()

getOptions(): string[];

Defined in: src/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: src/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.

isDirty()

protected isDirty(): boolean;

Defined in: src/api/form/PDFField.ts:329

Returns

boolean

Inherited from

PDFField.isDirty

isExported()

isExported(): boolean;

Defined in: src/api/form/PDFField.ts:227

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.

Inherited from

PDFField.isExported

isMultiselect()

isMultiselect(): boolean;

Defined in: src/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;

Defined in: src/api/form/PDFField.ts:147

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.

Inherited from

PDFField.isReadOnly

isRequired()

isRequired(): boolean;

Defined in: src/api/form/PDFField.ts:188

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.

Inherited from

PDFField.isRequired

isSelectOnClick()

isSelectOnClick(): boolean;

Defined in: src/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: src/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.

markAsClean()

protected markAsClean(): void;

Defined in: src/api/form/PDFField.ts:325

Returns

void

Inherited from

PDFField.markAsClean

markAsDirty()

protected markAsDirty(): void;

Defined in: src/api/form/PDFField.ts:321

Returns

void

Inherited from

PDFField.markAsDirty

needsAppearancesUpdate()

needsAppearancesUpdate(): boolean;

Defined in: src/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.

Overrides

PDFField.needsAppearancesUpdate

of()

static of(
   acroListBox, 
   ref, 
   doc): PDFOptionList;

Defined in: src/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

Parameter	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

select()

select(options, merge?): void;

Defined in: src/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

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

Returns

void

setFontSize()

setFontSize(fontSize): void;

Defined in: src/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

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

Returns

void

setOptions()

setOptions(options): void;

Defined in: src/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

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

Returns

void

updateAppearances()

updateAppearances(font, provider?): void;

Defined in: src/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

Parameter	Type	Description
`font`	`PDFFont`	The font to be used for creating the appearance streams.
`provider?`	`OptionListAppearanceProvider`	Optionally, the appearance provider to be used for generating the contents of the appearance streams.

Returns

void

updateOnOffWidgetAppearance()

protected updateOnOffWidgetAppearance(
   widget, 
   onValue, 
   __namedParameters): void;

Defined in: src/api/form/PDFField.ts:412

Parameters

Parameter	Type
`widget`	`PDFWidgetAnnotation`
`onValue`	`PDFName`
`__namedParameters`	`AppearanceMapping`<{ `off`: `PDFOperator`[]; `on`: `PDFOperator`[]; }>

Returns

void

Inherited from

PDFField.updateOnOffWidgetAppearance

updateWidgetAppearances()

protected updateWidgetAppearances(widget, __namedParameters): void;

Defined in: src/api/form/PDFField.ts:429

Parameters

Parameter	Type
`widget`	`PDFWidgetAnnotation`
`__namedParameters`	`AppearanceMapping`<`PDFRef` \| `PDFDict`>

Returns

void

Inherited from

PDFField.updateWidgetAppearances

updateWidgetAppearanceWithFont()

protected updateWidgetAppearanceWithFont(
   widget, 
   font, 
   __namedParameters): void;

Defined in: src/api/form/PDFField.ts:400

Parameters

Parameter	Type
`widget`	`PDFWidgetAnnotation`
`font`	`PDFFont`
`__namedParameters`	`AppearanceMapping`<`PDFOperator`[]>

Returns

void

Inherited from

PDFField.updateWidgetAppearanceWithFont

Class: PDFOptionList ​

Extends ​

Properties ​

acroField ​

Overrides ​

doc ​

Inherited from ​

ref ​

Inherited from ​

Methods ​

addOptions() ​

Parameters ​

Returns ​

addToPage() ​

Parameters ​

Returns ​

clear() ​

Returns ​

createImageAppearanceStream() ​

Parameters ​

Returns ​

Inherited from ​

createWidget() ​

Parameters ​

Returns ​

Inherited from ​

defaultUpdateAppearances() ​

Parameters ​

Returns ​

Overrides ​

disableExporting() ​

Returns ​

Inherited from ​

disableMultiselect() ​

Returns ​

disableReadOnly() ​

Returns ​

Inherited from ​

disableRequired() ​

Returns ​

Inherited from ​

disableSelectOnClick() ​

Returns ​

disableSorting() ​

Returns ​

enableExporting() ​

Returns ​

Inherited from ​

enableMultiselect() ​

Returns ​

enableReadOnly() ​

Returns ​

Inherited from ​

enableRequired() ​

Returns ​

Inherited from ​

enableSelectOnClick() ​

Returns ​

enableSorting() ​

Returns ​

getAction() ​

Returns ​

Inherited from ​

getJavaScriptActions() ​

Returns ​

Inherited from ​

getName() ​

Returns ​

Inherited from ​

getOptions() ​

Returns ​

getSelected() ​

Returns ​

isDirty() ​

Returns ​

Inherited from ​

isExported() ​

Returns ​

Inherited from ​

isMultiselect() ​

Class: PDFOptionList

Extends

Properties

acroField

Overrides

doc

Inherited from

ref

Inherited from

Methods

addOptions()

Parameters

Returns

addToPage()

Parameters

Returns

clear()

Returns

createImageAppearanceStream()

Parameters

Returns

Inherited from

createWidget()

Parameters

Returns

Inherited from

defaultUpdateAppearances()

Parameters

Returns

Overrides

disableExporting()

Returns

Inherited from

disableMultiselect()

Returns

disableReadOnly()

Returns

Inherited from

disableRequired()

Returns

Inherited from

disableSelectOnClick()

Returns

disableSorting()

Returns

enableExporting()

Returns

Inherited from

enableMultiselect()

Returns

enableReadOnly()

Returns

Inherited from

enableRequired()

Returns

Inherited from

enableSelectOnClick()

Returns

enableSorting()

Returns

getAction()

Returns

Inherited from

getJavaScriptActions()

Returns

Inherited from

getName()

Returns

Inherited from

getOptions()

Returns

getSelected()

Returns

isDirty()

Returns

Inherited from

isExported()

Returns

Inherited from

isMultiselect()