Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# `PDFWidget`

Widgets refer to components which make up form items such as buttons, text inputs and signature fields.

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

Instance methods

getFieldType()

  Return `String` indicating type of widget: “button”, “checkbox”, “combobox”, “listbox”, “radiobutton”, “signature” or “text”.

  Returns:

    `String`.

  EXAMPLE

      var type = widget.getFieldType();

getFieldFlags()

  Return the field flags. Refer to the PDF specification for their meanings.

  Returns:

    `Integer` which determines the bit-field value.

  EXAMPLE

      var flags = widget.getFieldFlags();

getRect()

  Get the widget bounding box.

  Returns:

    `[ulx,uly,lrx,lry]` Rectangle.

  EXAMPLE

      var rect = widget.getRect();

setRect(rect)

  Set the widget bounding box.

  Arguments:

    - rect – `[ulx,uly,lrx,lry]` Rectangle.

  EXAMPLE

      widget.setRect([0,0,100,100]);

getMaxLen()

  Get maximum allowed length of the string value.

  Returns:

    `Integer`.

  EXAMPLE

      var length = widget.getMaxLen();

getValue()

  Get the widget value.

  Returns:

    `String`.

  EXAMPLE

      var value = widget.getValue();

setTextValue(value)

  Set the widget string value.

  Arguments:

    - value – `String`.

  EXAMPLE

      widget.setTextValue("Hello World!");

setChoiceValue(value)

  Sets the value against the widget.

  Arguments:

    - value – `String`.

  EXAMPLE

      widget.setChoiceValue("Yes");

toggle()

  Toggle the state of the widget, returns `1` if the state changed.

  Returns:

    `Integer`.

  EXAMPLE

      var state = widget.toggle();

getOptions()

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

  Returns:

    `[...]`.

  EXAMPLE

      var options = widget.getOptions();

layoutTextWidget()

  mutool only

  Layout the value of a text widget. Returns a Text Layout Object.

  Returns:

    `Object`.

  EXAMPLE

      var layout = widget.layoutTextWidget();

isReadOnly()

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

  Returns:

    `Boolean`.

  EXAMPLE

      var isReadOnly = widget.isReadOnly();

getLabel()

  Get the field name as a string.

  Returns:

    `String`.

  EXAMPLE

      var label = widget.getLabel();

getEditingState()

  mutool only

  Gets whether the widget is in editing state.

  Returns:

    `Boolean`.

  EXAMPLE

      var state = widget.getEditingState();

setEditingState(state)

  mutool only

  Set whether the widget is in editing state.

  Arguments:

    - state – `Boolean`.

  EXAMPLE

      widget.getEditingState(false);

Note

When in editing state any changes to the widget value will not cause any side-effects such as changing other widgets or running JavaScript. 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.

update()

  Update the appearance stream to account for changes to the widget.

  EXAMPLE

      widget.update();

## Signature Methods

isSigned()

  mutool only

  Returns true if the signature is signed.

  Returns:

    `Boolean`.

  EXAMPLE

      var isSigned = widget.isSigned();

validateSignature()

  mutool only

  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:

    `Integer`.

  EXAMPLE

      var validNum = widget.validateSignature();

checkCertificate()

  mutool only

  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`.

  EXAMPLE

      var result = widget.checkCertificate();

getSignatory()

  mutool only

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

  Returns:

    `String`.

  EXAMPLE

      var signatory = widget.getSignatory();

previewSignature(signer, signatureConfig, image, reason, location)

  mutool only

  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 – Signature Configuration Object.

    - image – Image.

    - reason – `String`.

    - location – `String`.

  Returns:

    `Pixmap`.

  EXAMPLE

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

sign(signer, signatureConfig, image, reason, location)

  mutool only

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

  Arguments:

    - signer – PDFPKCS7Signer.

    - signatureConfig – Signature Configuration Object.

    - image – Image.

    - reason – `String`.

    - location – `String`.

  EXAMPLE

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

clearSignature()

  mutool only

  Clear a signed signature, making it unsigned again.

  EXAMPLE

      widget.clearSignature();

incrementalChangesSinceSigning()

  mutool only

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

  EXAMPLE

      var changed = widget.incrementalChangesSinceSigning();

## Widget Events

eventEnter()

  mutool only

  Trigger the event when the pointing device enters a widget’s active area.

  EXAMPLE

      widget.eventEnter();

eventExit()

  mutool only

  Trigger the event when the pointing device exits a widget’s active area.

  EXAMPLE

      widget.eventExit();

eventDown()

  mutool only

  Trigger the event when the pointing device’s button is depressed within a widget’s active area.

  EXAMPLE

      widget.eventDown();

eventUp()

  mutool only

  Trigger the event when the pointing device’s button is released within a widget’s active area.

  EXAMPLE

      widget.eventUp();

eventFocus()

  mutool only

  Trigger the event when the a widget gains input focus.

  EXAMPLE

      widget.eventFocus();

eventBlur()

  mutool only

  Trigger the event when the a widget loses input focus.

  EXAMPLE

      widget.eventBlur();

# `PDFPKCS7Signer`

Creating a Signer

To create a signer object an instance of `PDFPKCS7Signer` is required.

new(filename, password)

  mutool only

  Read a certificate and private key from a pfx file and create a signer to hold this information. Used with PDFWidget.sign().

  Arguments:

    - filename – `String`.

    - password – `String`.

  Returns:

    `PDFPKCS7Signer`.

  EXAMPLE

      var signer = new PDFPKCS7Signer(<file_name>, <password>);