SignDoc SDK (C++)  5.0.0
Migrating from SignDoc SDK 2.x to SignDoc SDK 3.0

This section lists the API changes between version 2.0 and version 3.0 of SignDoc SDK and how to change your application to work with the new API.

Multiple widgets for PDF fields

PDF fields with multiple "widgets" are now supported. In most cases, each PDF field has one widget, that is, each PDF field has one visible rectangle on a page of the document.

Radio buttons usually have multiple widgets, one widget for each button of the button group.

Check box fields also can have multiple widgets (but usually don't); different widgets for one check box field can have different button values (but usually don't).

Other fields (except for signature fields) also can have multiple widgets, but all of them display the same value.

The schema (PdfFields.xsd) for the output of SignDocDocument::exportFields() has been changed:

  • page, left, bottom, right, top, and defaultAppearanceString have been moved from PdfField to PdfFieldWidget, PdfField now has a new element, widget.
  • the Justification attribute of PdfFieldType has been replaced by element "justification" of PdfFieldWidget

SignDocDocument::getFieldFont() has been removed, use SignDocDocument::getField() and SignDocField::getTextFieldAttributes() instead.

SignDocDocument::getFieldsOfPage() may return multiple copies of a field, with different widgets selected. For instance, if there is a radio button group with 4 radio buttons on the specified page, getFieldsOfPage() will return 4 instances of that radio button field, but each instance will have a different widget selected.

For radio button groups and check box fields, each widget is assigned a "button value" by means of SignDocField::setButtonValue().

Radio button groups and check box fields can have multiple widgets having the same button value. For check box fields and radio buttons without SignDocField::f_RadiosInUnison set, specifying the selected button by value string is ambiguous in that case. A 0-based value index can be used to find out which button is selected or to select a button, see SignDocField::getValueIndex() and SignDocField::setValueIndex(). Element valueIndex has been added to PdfFields.xsd.

In earlier versions, SignDocDocument::setField() could be used to update a field without setting all attributes of the SignDocField object. Now, all attributes (except for the field type and a couple of flags) can be changed by setField(). For instance, a PDF field can be moved from one page to another one. In consequence, you must obtain the current state of the field by calling SignDocDocument::getField(), SignDocDocument::getFields(), or SignDocDocument::getFieldsOfPage(), then apply your changes to the SignDocField object, then call SignDocDocument::setField() to change the field in the document.

SignDocField::setFlagsModify() and SignDocField::getFlagsModify() have been removed. SignDocDocument::setField() always changes all flags.

The SignDocDocument::addField() function no longer chooses a default value for radio button groups and check box fields. You have to call SignDocField::setValue() or SignDocField::setValueIndex(). When adding a text field, the justification must be set with SignDocField::setJustification().

The new SignDocField::clickButton() function can be used to perform a click for check boxes and radio buttons.

You can now get and set the annotation flags for the widgets of a field in a PDF document with the new SignDocField::getWidgetFlags() and SignDocField::setWidgetFlags() functions.

The rotation of the contents of the widgets of a field in a PDF document can be retrieved and set with the new SignDocField::getRotation() and SignDocField::setRotation() functions, respectively.

SignDocDocument::flattenField() now takes a widget index. To get the old behavior, pass -1.

List boxes and combo boxes

List boxes and combo boxes in PDF documents are now supported. SignDocField::t_choice has been replaced by SignDocField::t_list_box and SignDocField::t_choice_field.

The set of available values (SignDocField::getAvailable() and friends) has been replaced by a set of choice values (SignDocField::getChoiceValue() and friends). See also SignDocField::setTopIndex().

Likewise, element "available" has been replaced by element "choice" in PdfFields.xsd, element topIndex has been added.

Other changes

In PdfFields.xml, the "MaxLen" attribute of the type element has been turned into an element named "maxLen".

The new function SignDocDocument::getRequiredSaveToFileFlags() can be used to find out if the document must be saved incrementally.

The new function SignDocDocument::flattenFields() flattens all fields on the selected pages.

The new functions SignDocField::getAlternateName() and SignDocField::getMappingName() retrieve the alternate name (tool tip) and the mapping name (for exporting) of the field.

An FDF file can be applied to a PDF document by calling SignDocDocument::applyFdf(). SignDocDocumentLoader::loadFromFile() now can open an FDF file and will apply it to the PDF document specified by that FDF file.

The aDecorations parameter of SignDocDocument::renderPageAsImage(), SignDocDocument::renderPageAsSpoocImage(), and SignDocDocument::renderPageAsSpoocImage() has been replaced by SignDocRenderParameters::setDecorations(), SignDocRenderParameters::setPrint() has been added.