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:

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:
  • valueString.

EXAMPLE

widget.setTextValue("Hello World!");
setChoiceValue(value)

Sets the value against the widget.

Arguments:
  • valueString.

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:
  • stateBoolean.

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

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:
  • filenameString.

  • passwordString.

Returns:

PDFPKCS7Signer.

EXAMPLE

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