Skip to content
Back to top

# 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:

  `"button" | "checkbox" | "combobox" | "listbox" | "radiobutton" | "signature" | "text"`

  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()