This section lists the API changes between 1.x versions and version 2.0 of SignDoc SDK and how to change your application to work with the new API. See also Migrating from SignDoc SDK 2.x to SignDoc SDK 3.0 when migrating to version 3.x. The changes can be grouped into these API areas:

New flag sf_pdf_1_4

By default, SignDoc SDK 2.x saves PDF documents in an optimized way that is not compatible with PDF 1.4 and earlier. Use the sf_pdf_1_4 flag to get the old behavior.

Loading font configuration files

In SignDoc SDK 1.x, the loadFontConfig*() and loadPdfFontConfig*() functions of SignDocDocumentLoader failed if any font file specified by the font configuration file could not be loaded.

In SignDoc SDK 2.x, the loadFontConfig*() and loadPdfFontConfig*() functions of SignDocDocumentLoader no longer fail if a font file specified by a font configuration file cannot be loaded. You can find out if any font file could not be loaded by calling getFailedFontFiles().

Font configuration file

In SignDoc SDK 1.x, fonts used for text fields are embedded into the PDF document if not already referenced by the PDF document. In SignDoc SDK 2.x, a font configuration file also specifies whether a font is to be embedded into the PDF document or not.

In SignDoc SDK 1.x, the FontFlags signature parameter controls whether the font used for a signature field is embedded into the PDF document or not. In SignDoc SDK 2.x, a font configuration file also specifies whether a font is to be embedded into the PDF document or not.

The syntax of font configuration files has been changed:

An attribute named "embed" has been added to the FontFiles element.
An attribute named "embed" has been added to the Substitute element.
An attribute named "type" has been added to the Substitute element.

The "embed" attribute of the FontFiles and Substitute elements controls whether the font is to be embedded into the PDF document or not. When adding a field that uses a font with an "embed" attribute of "subset", the font file must be available when the field's text is modified or (for a signature field) is signed.

The "type" attribute of the Substitute element controls whether the substitution rule is always applied or only if no suitable font has been found.

Moreover, the sequence in which the PDF document is searched for existing fonts has been changed.

See Font Configuration for details.

Setting the value of text fields

In SignDoc SDK 1.x, setField() does not fail if the appearance of a text field cannot be created due to no suitable font being available.

In SignDoc SDK 2.x, setField() fails if the appearance of a text field cannot be created. The application must ensure that suitable font files and substitutions are specified by a font configuration file.

Font management for signature fields

In SignDoc SDK 1.x, the font to be used for text in the appearance of signature fields in PDF documents is specified at signing time. In SignDoc SDK 2.x, the font is specified by the signature field's default appearance string.

In detail, the changes to the API are these:

SignDocSignatureParameters: integer parameter "FontFlags" has been removed.
SignDocSignatureParameters: string parameter "Font" has been removed.
SignDocSignatureParameters: string parameter "FontPath" has been removed.
SignDocDocument: addSignature(): the font and the text color are taken from the field's default appearance string (or the document's default appearance string if the field doesn't have or inherit a default appearance string). In SignDoc SDK 1.x, the font was provided by SignDocSignatureParameters and the color was a gray level of 30%.
SignDocField: getTextFieldFieldAttributes() can be used for signature fields.
SignDocField: setTextFieldFieldAttributes() can be used for signature fields.

To migrate an application from SignDoc SDK 1.x to SignDoc SDK 2.x, do this:

Set the default appearance string when inserting a signature field.
Optionally set the default appearance string of existing signature fields.
Call setTextColor(SignDocGrayColor(77)) for your SignDocTextFieldAttributes object to get a gray level of 30% as in SignDoc SDK 1.x.
Specify whether the fonts are to be embedded or not by means of a font configuration file.

New argument for setField() and addField()

In SignDoc SDK 2.x, an argument has been added to the setField() and addField() functions which controls how those functions should behave when no suitable font (covering all characters) can be found.

Function getFontResourceName() has been added to the SignDocTextFieldAttributes class. The font resource name in the SignDocField object passed to setField() and addField() is updated if the update to the document changes the font resource name.

SignDocProperties removed

In SignDoc SDK 2.x, class SignDocProperties has been removed and all member functions have been moved to class SignDocDocument.

To migrate an application from SignDoc SDK 1.x to SignDoc SDK 2.x, pass the name of the collection to the SignDocDocument member function instead of calling a SignDocProperties member function.