C interface changes for PDF Toolbox SDK

There are several changes in naming and behavior in the C interface to bear in mind when migrating from the 3-Heights® PDF Toolbox API to the PDF Toolbox SDK.

Prefixes

The name of all interface elements such as declared structs and functions, starts with a prefix. In 3-Heights® PDF Toolbox API PDF Toolbox API, all interface elements have the same prefix. The PDF Toolbox SDK introduces the following new prefixes:

Prefix	Area of usage
Ptx	Base prefix
PtxGeom	Geometric related
PtxGeomReal	For floating point numbers
PtxGeomInteger	For integer numbers
PtxPdf	General PDF related
PtxPdfAnnots	Annotation related
PtxPdfContent	Page content related
PtxPdfForms	Form field related
PtxPdfNav	Document navigation related

The Sdk functions

License keys and product version

In 3-Heights® PDF Toolbox API, PdfSetLicenseKey and PdfGetProductVersion functions allows setting a license key and querying the version of the API.

In the, this functionality has been moved to the class TPtx_Sdk. Specifically:

• Ptx_Sdk_Initialize must be called to set a license key. See also License keys.
• Ptx_Sdk_GetVersion gets the API’s version number as a string.

The PDF Producer entry

In 3-Heights® PDF Toolbox API, when creating a PDF, the TPdfMetadata object sets the PDF’s “Producer” entry via the related function PdfMetadataSetProducer.

In the PDF Toolbox SDK, the class TPtxPdf_Metadata has no related function PtxPdf_Metadata_SetProducer. Instead, the “Producer” entry for all output PDFs is preconfigured as a string consisting of two parts:

1. The first part (the “base” part) is encoded in the license key. Hence, this part is determined when buying a licensef rom Pdftools.
2. The second part (the “suffix” part) is configured when calling Ptx_Sdk_Initialize as an argument. It is recommended to use the suffix solely for version information.

The assembled “Producer” entry can be obtained after calling Ptx_Sdk_Initialize using the related function Ptx_Sdk_GetProducerFullName.

Closing and releasing

In 3-Heights® PDF Toolbox API, all native objects support a “closing” operation by means of the PdfClose function.

In the PDF Toolbox SDK, only the following classes support closing by means of a dedicated function:

• TPtxPdf_Document
• TPtxPdfContent_ContentGenerator
• TPtxPdfContent_TextGenerator

Specifically, the objects on which these classes operate are not fully constructed until closing. For all other objects, associated resources can be freed by calling Ptx_Release. Using an object after releasing results in undefined behavior.

Elements changed to class or struct

The following 3-Heights® PDF Toolbox API structs have changed to opaque classes in the PDF Toolbox SDK:

• TPdfEncryptionParams → TPtxPdf_Encryption
• TPdfFillParams → TPtxPdfContent_Fill
• TPdfStrokeParams → TPtxPdfContent_Stroke
• TPdfTransparencyParams → TPtxPdfContent_Transparency

Hence, such objects cannot be allocated on the stack. The related initialization functions ...Initialize have been removed. In turn, they receive allocation functions ...New.

As a consequence, the following functions now directly return a pointer to the object:

• PtxPdfContent_Paint_GetTransparency
• PtxPdfContent_PathElement_GetFill
• PtxPdfContent_PathElement_GetStroke
• PtxPdfContent_TextFragment_GetFill
• PtxPdfContent_TextFragment_GetStroke

Conversely, the following 3-Heights® PDF Toolbox API class has changed to an explicitly defined struct in the PDF Toolbox SDK:

• TPdfTransformation → TPtxGeomReal_AffineTransform

Hence, such objects can be allocated on the stack. See also Affine transform objects should be initialized.

As a consequence, the following functions take a last argument TPtxGeomReal_AffineTransform*, a pointer to an already allocated struct:

• PtxPdfContent_TextFragment_GetTransform
• PtxPdfContent_ContentElement_GetTransform

Renaming

Some interface elements have been renamed in addition to the introduction of new Prefixes. The following principles apply:

• Interface elements that include abbreviations are now written consistently in Pascal case, e.g. RGB → Rgb, except for two-letter abbreviations, which are written as two capital letters, e.g. IO.
• Some abbreviations have been changed to full words, e.g. Char → Character.
• Some words that are repeated in the introduced prefix namespace have been dropped, e.g.TPdfAnnotationPopup → TPtxPdfAnnots_Popup.
• List appending function are renamed: ...Append→...Add.
• Improved clarity, brevity, jargon, and technical correctness.

Affine transform objects should be initialized

In 3-Heights® PDF Toolbox API, TPdfTransformation is a “class”. In the PDF Toolbox SDK, this element has been renamed to TPtxGeomReal_AffineTransformation, and its type has changed to “struct”. See Elements changed to class or struct.

Specifically, default constructed TPtxGeomReal_AffineTransform objects are not valid. (A matrix with all values0is singular.) Default constructed TPtxGeomReal_AffineTransform objects should always be initialized with PtxGeomReal_AffineTransform_GetIdentity.

For example:

TPtxGeomReal_AffineTransform transform;
PtxGeomReal_AffineTransform_GetIdentity(&transform);

Creation and copying methods

In 3-Heights® PDF Toolbox API, most document-associated objects are created in an output document by related functions PdfDocumentCreate... and copied from an input document to an output document by related functions PdfDocumentCopy..., e.g. PdfDocumentCreatePage, PdfDocumentCopyPage.

In the PDF Toolbox SDK, all these related functions have been moved from the TPdfDocument class to the class that is created or copied. For example, related function PdfDocumentCreatePage → PtxPdf_Page_Create. This affects the following classes:

• TPdfPage
• TPdfImage
• TPdfImageMask
• TPdfFont
• TPdfGroup
• TPdfColorSpace
• TPdfPaint
• TPdfText
• TPdfMetadata
• TPdfFileReference
• TPdfSubForm
• TPdfGeneralTextField
• TPdfCombTextField
• TPdfCheckBoxField
• TPdfRadioButtonField
• TPdfListBoxField
• TPdfComboBoxField
• TPdfNamedDestination
• TPdfOutlineItem
• TPdfAnnotation
• TPdfLink
• TPdfFileAttachmentAnnotation
• TPdfFreeTextAnnotation
• TPdfStickyNoteAnnotation
• TPdfTextStampAnnotation
• TPdfCustomStampAnnotation
• TPdfCircleAnnotation
• TPdfSquareAnnotation
• TPdfLineAnnotation
• TPdfPolyLineAnnotation
• TPdfPolygonAnnotation
• TPdfFreeDrawingAnnotation
• TPdfContentElement
• TPdfFormFieldNode

Constructors

In 3-Heights® PDF Toolbox API, some document-associated objects are created by means of a constructor. For example: PdfNewFitPageDestination.

In the PDF Toolbox SDK, most of these document-associated objects are now created and copied with related functions ..._Create and ..._Copy.

This affects the following classes:

• TPdfEmbeddedPdfLink
• TPdfFitHeightDestination
• TPdfFitPageDestination
• TPdfFitRectangleDestination
• TPdfFitWidthDestination
• TPdfLocationZoomDestination
• TPdfWebLink

In the PDF Toolbox SDK, the following classes (most of them not document-associated) have constructors:

• TPtxPdf_Encryption
• TPtxPdfContent_ContentExtractor
• TPtxPdfContent_ContentGenerator
• TPtxPdfContent_Fill
• TPtxPdfContent_PageCopyOptions
• TPtxPdfContent_PathGenerator
• TPtxPdfContent_Path
• TPtxPdfContent_Stroke
• TPtxPdfContent_TextGenerator
• TPtxPdfContent_Transparency
• TPtxPdfNav_OutlineCopyOptions

All constructors have been renamed: PdfNew‹Type› → ‹Prefix›_‹Type›_New

Unknown PDF conformance

In 3-Heights® PDF Toolbox API, the TPdfConformance enumeration has a value ePdfUnk. The PDF Toolbox SDK enum TPtxPdf_Conformance has no such value.

The handling of unknown (i.e. automatically upgrading) PDF conformance is now done as follows:

• In the related function PtxPdf_Document_Create, the type of the second argument has changed from TPdfConformance to TPtxPdf_Conformance*, where a NULL value has the same meaning as the removed value ePdfUnk.
• The related function PtxPdf_Document_GetConformance always returns the current conformance. For input documents, this is the claimed conformance. For output documents, this is either the explicit conformance set when creating, or (if created with NULL), the conformance the output PDF would have if closed now.

Copy options

In 3-Heights® PDF Toolbox API, page copying and outline copying behavior is configurable by means of the TPdfCopyOption enum.

In the PDF Toolbox SDK, this enum has been substituted by new classes:

• TPtxPdf_PageCopyOptions Used in related functions PtxPdf_Page_Copy and PtxPdf_Group_CreateFromPage.
• TPtxPdfNav_OutlineCopyOptions
• Used in related function PtxPdfNav_OutlineItem_Copy.

Each copying configuration decision is reflected in a class member. Apart from `BOOL for on-off decisions, the following enumerations model possible choices:

• TPtxPdf_CopyStrategy
• TPtxPdf_RemovalStrategy
• TPtxPdf_NameConflictResolution
• TPtxPdfForms_FormFieldCopyStrategy
• TPtxPdfNav_NamedDestinationCopyStrategy

This clarifies the copying behavior and allows sensible default values.

Color space classes

Class hierarchy
In 3-Heights® PDF Toolbox API, there is a single class TPdfColorSpace, which covers all types of color spaces.

In the PDF Toolbox SDK, there are the following new classes, all extending TPtxPdfContent_ColorSpace:

• TPtxPdfContent_CalibratedGrayColorSpace
• TPtxPdfContent_CalibratedRgbColorSpace
• TPtxPdfContent_DeviceCmykColorSpace
• TPtxPdfContent_DeviceGrayColorSpace
• TPtxPdfContent_DeviceRgbColorSpace
• TPtxPdfContent_IccBasedColorSpace
• TPtxPdfContent_IndexedColorSpace
• TPtxPdfContent_LabColorSpace
• TPtxPdfContent_NChannelColorSpace
• TPtxPdfContent_SeparationColorSpace

The 3-Heights® PDF Toolbox API color space type“DeviceN”now is subsumed by the more generalTPtxPdfContent_NChannelColorSpace.

Device color spaces versus process color spaces
In 3-Heights® PDF Toolbox API, the related function PdfDocumentCreateDeviceColorSpace does not necessarily create a device color space, e.g., in case of PDF/A.

In the PDF Toolbox SDK, the enumeration TPdfDeviceColorSpaceType has been renamed to TPtxPdfContent_ProcessColorSpaceType. The struct TPtxPdfContent_ColorSpace now has the following related function:

TPtxPdfContent_ColorSpace* PtxPdfContent_ColorSpace_CreateProcessColorSpace(TPtxPdf_Document*,
    TPtxPdfContent_DeviceColorSpaceTypeiType)

This method creates either a device color space, or, in case of PDF/A, a calibrated (grayscale or RGB) or an ICC-based(CMYK) color space.

Embedded/Associated/Attached files

In 3-Heights® PDF Toolbox API, embedded files, associated files, and files contained in a TPdfFileAttachmentAnnotation are jointly listed in the related function PdfDocumentGetEmbeddedFiles.

In the PDF Toolbox SDK, embedded files, associated files, and files contained in fileattachment annotations are treated separately. ATPtxPdf_Document now has two lists for appending:

• PtxPdf_Document_GetAssociatedFiles
• PtxPdf_Document_GetPlainEmbeddedFiles

The former related function PdfDocumentGetEmbeddedFiles has been renamed to PtxPdf_Document_GetAllEmbeddedFiles, a read-only list that contains embedded files and files contained in TPtxPdfAnnots_FileAttachment annotations. This list is equivalent to what a viewer normally lists in an embedded files pane. For example, the “Attachments” pane in the Adobe PDF viewer.

Annotations

In the PDF Toolbox SDK, the following annotation classes have been renamed for technical correctness:

• TPdfFreeDrawingAnnotation → TPtxPdfAnnots_InkAnnotation
• TPdfCircleAnnotation → TPtxPdfAnnots_EllipseAnnotation
• TPdfSquareAnnotation → TPtxPdfAnnots_RectangleAnnotation

The related functions PdfRadioButtenFieldGetCanToggleOff and PdfRadioButtenFieldSetCanToggleOff have been removed. In most PDF viewers, there is no support for this feature.

Class hierarchy
In 3-Heights® PDF Toolbox API, TPdfWidget and TPdfLink extend the base class TPdfAnnotation.

In the PDF Toolbox SDK, the classes TPtxPdfForms_Widget and TPtxPdfNav_Link have been separated from their former base class. Due to this separation: ATPtxPdf_Page now has the following lists:

• PtxPdf_Page_GetAnnotations
• PtxPdf_Page_GetLinks
• PtxPdf_Page_GetFormFieldWidgets

The following related functions of TPtxPdfAnnots_Annotation have been replicated for TPtxPdfForms_Widget and TPtxPdfNav_Link: ..._GetBoundingBox ..._GetHidden ..._GetNoPrint

The intermediate base classes TPdfPolyDrawingAnnotation and TPdfShapeDrawingAnnotation havebeen removed. All drawing annotations now directly extend the class TPtxPdfAnnots_DrawingAnnotation.Those drawing annotations that have a closed path (TPtxPdfAnnots_PolygonAnnotation,TPtxPdfAnnots_EllipseAnnotation,TPtxPdfAnnots_RectangleAnnotation) have related functions ...GetFill and ...SetFill.

Class hierarchy comparison

3-Heights® PDF Toolbox (left)	PDF Toolbox SDK (right)

MaxLength in text fields

In 3-Heights® PDF Toolbox API, the error behavior of the related function PdfTextFieldSetMaxLength depends on the actual underlying class: TPdfGeneralTextField allows NULL values, while TPdfCombTextField does not.

In the PDF Toolbox SDK, the related functions PdfTextFieldGetMaxLength and PdfTextFieldSetMaxLength havebeen removed and replicated in the derived classes TPtxPdfForms_CombTextField and TPtxPdfForms_GeneralTextField, in the latter as a nullable int*.

Unified paint creation

In 3-Heights® PDF Toolbox API, there exist three related functions for creating a `TPdfPaintobject: PdfDocumentCreateSolidPaint PdfDocumentCreateAlphaPaint PdfDocumentCreateBlendingPaint

In the PDF Toolbox SDK, these related functions have been replaced by a single related functionPtxPdfContent_Paint_Create.See also Creation and copying methods.

Separate inside rule from path

In 3-Heights® PDF Toolbox API, the related function PdfNewPath has an argument TPdfInsideRuleiRule. In the PDF Toolbox SDK, this argument is dropped. Instead, the TPdfInsideRule now is specified in a new member of TPtxPdfContent_Fill when painting the path with PtxPdfContent_ContentGenerator_PaintPath, or it is specified in a method argument when clipping with PtxPdfContent_ContentGenerator_ClipWithPath.This removes ambiguity and allows a separated treatment of the insiderule for path filling and path clipping.

Path and text clipping operations

In 3-Heights® PDF Toolbox API, the TPdfContentGenerator supports simultaneous clipping and painting operations.

In the PDF Toolbox SDK, path and text clipping operations have been separated from path and text painting operations as follows:

• The argument BOOL bIntersectClipPath has been removed from the related function PdfContentGeneratorPaintPath.
• The related function PdfTextGeneratorSetRendering has been removed (see also Text generator), and its argument BOOL bIntersectClipping has been dropped without a replacement.
• The new class TPtxPdfContent_ContentGenerator has two new methods for path and text clipping operations: PtxPdfContent_ContentGenerator_ClipWithPath PtxPdfContent_ContentGenerator_ClipWithText

To achieve the same effect of simultaneous clipping and painting, the painting operation has to precede the clipping operation.

Text generator

In the PDF Toolbox SDK, the related function PdfTextGeneratorSetRendering has been substituted by two separate related functions:

• Related function PtxPdfContent_TextGenerator_SetFill
• Related function PtxPdfContent_TextGenerator_SetStroke

Image size and image mask size

In 3-Heights® PDF Toolbox API, TPdfImage and TPdfImageMask have related functions ...GetWidth and ...GetHeight.

In the PDF Toolbox SDK, these are substituted by related functions PtxPdfContent_Image_GetSize and PtxPdfContent_ImageMask_GetSize, both of which have the new type TPtxGeomInt_Size.

---

Reference

For all changes in the C interface between 3-Heights® PDF Toolbox API and the PDF Toolbox SDK, see C Reference.