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.
You cannot create instances of this class with the new operator!
To get the widgets on a page, see PDFPage.prototype.getWidgets().
Return the widget type, one of the following:
"button" | "checkbox" | "combobox" | "listbox" | "radiobutton" | "signature" | "text"
var type = widget.getFieldType()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.
var flags = widget.getFieldFlags()Retrieve the name of the field.
var fieldName = widget.getName()Get maximum allowed length of the string value.
var length = widget.getMaxLen()Returns an array of strings which represent the value for each corresponding radio button or checkbox field.
var options = widget.getOptions()Get the field name as a string.
var label = widget.getLabel()Get the widget value.
var value = widget.getValue()Set the widget string value.
string) – New text value.widget.setTextValue("Hello World!")Sets the choice value against the widget.
string) – New choice
value.widget.setChoiceValue("Yes")Toggle the state of the widget, returns true if the state changed.
var state = widget.toggle()only mutool run
Get whether the widget is in editing state.
var state = widget.getEditingState()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.
boolean)widget.getEditingState(false)only mutool run
Layout the value of a text widget. Returns a text layout object.
var layout = widget.layoutTextWidget()If the value is read only and the widget cannot be interacted with.
var isReadOnly = widget.isReadOnly()only mupdf.js
Return whether the widget is multi-line.
only mupdf.js
Return whether the widget is a password input.
only mupdf.js
Return whether the widget is a text field laid out in “comb” style (forms where you write one character per square).
only mupdf.js
Return whether the widget is of “button”, “checkbox” or “radiobutton” type.
only mupdf.js
Return whether the widget is of “button” type.
only mupdf.js
Return whether the widget is of “checkbox” type.
Return whether the widget is of “radiobutton” type.
only mupdf.js
Return whether the widget is of “text” type.
only mupdf.js
Return whether the widget is of “combobox” or “listbox” type.
only mupdf.js
Return whether the widget is of “listbox” type.
only mupdf.js
Return whether the widget is of “combobox” type.
only mutool run
Returns true if the signature is signed.
var isSigned = widget.isSigned()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.
var validNum = widget.validateSignature()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.
var result = widget.checkCertificate()only mutool run
Returns “OK” if digest checked out OK, otherwise a text string containing an error message.
var result = widget.checkDigest()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"
var signatory = widget.getSignatory()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.
PDFPKCS7Signer)Object)Image)string)string)var pixmap = widget.previewSignature(
signer,
{
showLabels: true,
showDate: true
},
image,
"",
""
)only mutool run
Sign the signature with the given configuration. Reason and location
may be undefined, in which case they are not shown.
PDFPKCS7Signer)Object)Image)string)string)widget.sign(
signer,
{
showLabels: true,
showDate: true
},
image,
"",
""
)only mutool run
Clear a signed signature, making it unsigned again.
widget.clearSignature()only mutool run
Returns true if there have been incremental changes since the signature widget was signed.
var changed = widget.incrementalChangesSinceSigning()