PDFWidget¶

Widgets are annotations that represent form components such as buttons, text inputs and signature fields.

Because PDFWidget inherits PDFAnnotation, they also provide the same interface as other annotation types.

Many widgets, e.g. text inputs or checkboxes, are the visual representation of an associated form field. As the widget changes state, so does its corresponding field value; for example when the text is edited in a text input or a checkbox is checked. Note that widgets may be changed by Javascript event handlers triggered by edits on other widgets.

The PDF specification has sections on Widget annotations and Interactive forms with further details.

Constructors¶

class PDFWidget()¶: You cannot create instances of this class with the new operator!

To get the widgets on a page, see PDFPage.prototype.getWidgets().

Instance methods¶

PDFWidget.prototype.getFieldType()¶

Return the widget type, one of the following:

Returns:: string

var type = widget.getFieldType()

PDFWidget.prototype.getFieldFlags()¶

Return the field flags which indicate attributes for the field. There are convenience functions to check some of these: isReadOnly, isMultiline, isPassword, isComb, isButton, isPushButton, isCheckbox, isRadioButton, isText, isChoice, isListBox, and isComboBox.

For details refer to the PDF specification’s sections on flags common to all field types, for button fields, for text fields, and for choice fields.

Returns:: number

var flags = widget.getFieldFlags()

PDFWidget.prototype.getName()¶

Retrieve the name of the field.

Returns:: string

var fieldName = widget.getName()

PDFWidget.prototype.getMaxLen()¶

Get maximum allowed length of the string value.

Returns:: number

var length = widget.getMaxLen()

PDFWidget.prototype.getOptions()¶

Returns an array of strings which represent the value for each corresponding radio button or checkbox field.

Returns:: Array of string

var options = widget.getOptions()

PDFWidget.prototype.getLabel()¶

Get the field name as a string.

Returns:: string

var label = widget.getLabel()

Editing¶

PDFWidget.prototype.getValue()¶

Get the widget value.

Returns:: string

var value = widget.getValue()

PDFWidget.prototype.setTextValue(value)¶

Set the widget string value.

Arguments:

value (string) – New text value.

widget.setTextValue("Hello World!")

PDFWidget.prototype.setChoiceValue(value)¶

Sets the choice value against the widget.

Arguments:

value (string) – New choice value.

widget.setChoiceValue("Yes")

PDFWidget.prototype.toggle()¶

Toggle the state of the widget, returns true if the state changed.

Returns:: boolean

var state = widget.toggle()

PDFWidget.prototype.getEditingState()¶

only mutool run

Get whether the widget is in editing state.

Returns:: boolean

var state = widget.getEditingState()

PDFWidget.prototype.setEditingState(state)¶

only mutool run

Set whether the widget is in editing state.

When in editing state any changes to the widget value will not cause any side-effects such as changing other widgets or running Javascript event handlers. This is intended for, e.g. when a text widget is interactively having characters typed into it. Once editing is finished the state should reverted back, before updating the widget value again.

Arguments:

state (boolean)

widget.getEditingState(false)

PDFWidget.prototype.layoutTextWidget()¶

only mutool run

Layout the value of a text widget. Returns a text layout object.

Returns:: Object

var layout = widget.layoutTextWidget()

Flags¶

PDFWidget.prototype.isReadOnly()¶

If the value is read only and the widget cannot be interacted with.

Returns:: boolean

var isReadOnly = widget.isReadOnly()

PDFWidget.prototype.isMultiline()¶

only mupdf.js

Return whether the widget is multi-line.

Returns:: boolean

PDFWidget.prototype.isPassword()¶

only mupdf.js

Return whether the widget is a password input.

Returns:: boolean

PDFWidget.prototype.isComb()¶

only mupdf.js

Return whether the widget is a text field laid out in “comb” style (forms where you write one character per square).

Returns:: boolean

PDFWidget.prototype.isButton()¶

only mupdf.js

Return whether the widget is of “button”, “checkbox” or “radiobutton” type.

Returns:: boolean

PDFWidget.prototype.isPushButton()¶

only mupdf.js

Return whether the widget is of “button” type.

Returns:: boolean

PDFWidget.prototype.isCheckbox()¶

only mupdf.js

Return whether the widget is of “checkbox” type.

Returns:: boolean

PDFWidget.prototype.isRadioButton()¶

Return whether the widget is of “radiobutton” type.

Returns:: boolean

PDFWidget.prototype.isText()¶

only mupdf.js

Return whether the widget is of “text” type.

Returns:: boolean

PDFWidget.prototype.isChoice()¶

only mupdf.js

Return whether the widget is of “combobox” or “listbox” type.

Returns:: boolean

PDFWidget.prototype.isListBox()¶

only mupdf.js

Return whether the widget is of “listbox” type.

Returns:: boolean

PDFWidget.prototype.isComboBox()¶

only mupdf.js

Return whether the widget is of “combobox” type.

Returns:: boolean

Signatures¶

PDFWidget.prototype.isSigned()¶

only mutool run

Returns true if the signature is signed.

Returns:: boolean

var isSigned = widget.isSigned()

PDFWidget.prototype.validateSignature()¶

only mutool run

Returns number of updates ago when signature became invalid. Returns 0 is signature is still valid, 1 if it became invalid during the last save, etc.

Returns:: number

var validNum = widget.validateSignature()

PDFWidget.prototype.checkCertificate()¶

only mutool run

Returns “OK” if signature checked out OK, otherwise a text string containing an error message, e.g. “Self-signed certificate.” or “Signature invalidated by change to document.”, etc.

Returns:: string

var result = widget.checkCertificate()

PDFWidget.prototype.checkDigest()¶

only mutool run

Returns “OK” if digest checked out OK, otherwise a text string containing an error message.

Returns:: string

var result = widget.checkDigest()

PDFWidget.prototype.getSignatory()¶

only mutool run

Returns a text string with the distinguished name from a signed signature, or a text string with an error message.

The returned string follows the format:

"cn=Name, o=Organization, ou=Organizational Unit, email=jane.doe@example.com, c=US"

Returns:: string

var signatory = widget.getSignatory()

PDFWidget.prototype.previewSignature(signer, signatureConfig, image, reason, location)¶

only mutool run

Return a Pixmap preview of what the signature would look like if signed with the given configuration. Reason and location may be undefined, in which case they are not shown.

Arguments:

signer (PDFPKCS7Signer)
signatureConfig (Object)
image (Image)
reason (string)
location (string)

Returns:

Pixmap

var pixmap = widget.previewSignature(
        signer,
        {
                showLabels: true,
                showDate: true
        },
        image,
        "",
        ""
)

PDFWidget.prototype.sign(signer, signatureConfig, image, reason, location)¶

only mutool run

Sign the signature with the given configuration. Reason and location may be undefined, in which case they are not shown.

Arguments:

signer (PDFPKCS7Signer)
signatureConfig (Object)
image (Image)
reason (string)
location (string)

widget.sign(
        signer,
        {
                showLabels: true,
                showDate: true
        },
        image,
        "",
        ""
)

PDFWidget.prototype.clearSignature()¶

only mutool run

Clear a signed signature, making it unsigned again.

widget.clearSignature()

PDFWidget.prototype.incrementalChangesSinceSigning()¶

only mutool run

Returns true if there have been incremental changes since the signature widget was signed.

Returns:: boolean

var changed = widget.incrementalChangesSinceSigning()