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