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