API changes =========== This file documents those API changes which affect existing PDFlib client programs. Although we go to some efforts in maintaining the existing API functions, it is sometimes necessary to incorporate a few non-backward compatible changes in order to streamline the API and incorporate new or extended functions. PDFlib, PPS API, and Block plugin versions ========================================== PDFlib PPS API Block plugin ------------------------------------ 5.0.0 1 1.0.0 5.0.1+ 2 1.0.1, 1.1+ 6.0.0 3 2.0.0, 2.0.1 6.0.1 4 2.0.2 6.0.2 5 2.1.0 6.0.3 6 2.2 6.0.4 6 2.3 7.0.0 7 3.0 7.0.1 7 3.1 PDFlib 7.0.1 ============ The codepages cp932, cp936, cp949, and cp950 for CJK text no longer use Windows system codepages, but the standard CMaps. Therefore the CMaps must be configured in PDFlib when using one of these codepages on Windows (on other systems the CMaps were required in 7.0.0 already). XMP metadata for PDF/A: only the predefined PDF/A schemas are allowed, plus the four schemas required for defining extension schemas. This is incompatible with PDFlib 7.0.0 (which accepted arbitrary custom schemas), but the previous behavior can be considered a bug since it resulted in output which did not fully conform to the PDF/A standard. PDFlib 7.0.0 ============ Text output: the improved font engine in PDFlib 7 checks whether the glyphs required for creating text output are actually available in a given font. Characters in a text string for which the selected font does not contain the appropriate glyph will be replaced (for detailed control see the glyphchecking and replacementchar options), while the text strings were simply passed through by PDFlib 6 and earlier versions. Although this feature improves the accuracy of text output, it may be considered a small incompatibility (but only in situations which should be avoided anyway). Error handling: the new parameter "errorpolicy" allows for more consistent control of exceptions and error returns. The default setting is fully compatible with earlier versions, but we strongly recommend to use the new errorpolicy=return setting, and adjust your application (e.g. check the return value of PDF_load_font()). The default PDF version compatibility has been changed to PDF 1.6. If you need to create documents according to an older PDF version you must set the "compatibility" option in PDF_begin_document() appropriately. General functionality: Clipping paths in TIFF and JPEG images will now be honored, while up to PDFlib 6 they have been ignored. In order to restore the previous ("ignore path") behavior supply the option "honorclippingpath=false" to PDF_load_image(). PDF/X-1:2001 is considered deprecated, and no longer supported. PDF/X-1a:2001 and PDF/X-1a:2003 are still supported, though. PDF_info_textflow(): The values for the keywords leftlinex, leftliney, rightlinex, rightliney, minliney, maxliney are now interpreted in current user coordinates, while in PDFlib 6 they have been returned in user coordinates of PDF_fit_textflow(). The values for the keywords textendx, textendy are now interpreted in current user coordinates, while in PDFlib 6 they have been returned in user coordinates immediately after PDF_fit_textflow(). Required action if you are affected by this change: Avoid any change of the current transformation matrix (e.g. PDF_scale(), PDF_rotate(), PDF_translate()) between the calls to PDF_fit_textflow() and PDF_info_textflow(). Exception handling: The "warning" parameter is deprecated, and will be ignored. If you are interested in non-fatal problems which can be fixed by PDFlib internally enable logging with the "warning" class. Language bindings: Python: there is a new version of the Python wrapper with integrated Unicode support. An old-style Python wrapper without Unicode support is available for compatibility with existing applications. A new PDFlibException object is available in the PDFlib Python binding. Code which caught "except SystemError" (instead of the recommended "except:") must be changed to "except PDFlibException:". Deprecated functions: PDF_open_pdi() and PDF_close_pdi(): use PDF_open_pdi_document() and PDF_close_pdi_document() PDF_begin_template(): use PDF_begin_template_ext() PDF_get_pdi_value(): use PDF_pcos_get_number() PDF_get_pdi_parameter(): use PDF_pcos_get_string() (pCOS paths corresponding to the keys of the deprecated functions can be found in the PDFlib API manual). Deprecated parameters: Use PDF_info_font() instead of using the following deprecated parameters: monospace fontmaxcode ascender capheight xheight descender fontname fontencoding fontstyle ascenderfaked capheightfaked xheightfaked descenderfaked Use the PDF_load_font() option of the same name instead of the following deprecated parameters: autosubsetting autocidfont unicodemap subsetlimit subsetminsize Use the "logging" parameter instead of the following deprecated (unsupported) parameters: trace tracefile Deprecated PDF/X output intents: The following standard output intent names are deprecated, and should no longer be used: OF COM PO P1 F60, OF COM PO P2 F60, OF COM PO-P3 F60, OF COM PO P4 F60, OF COM NE P1 F60, OF COM NE P2 F60, OF COM NE P3 F60, OF COM NE P4 F60, SC GC2 CO F30, Ifra_NP_40lcm_neg+CTP_05.00 Configuration incompatibility: Using any of the predefined CMaps now requires the actual CMap file due to extended text processing features. The CMap files are available for download separately, and must be configured according to the documentation (e.g. using the SearchPath resource category). Deprecated options: PDF_fit_textline(): weblink, locallink; use the matchbox feature instead PDF_open_pdi_page(): infomode; use pCOS to query page properties without actually placing the page PDFlib Lite incompatibility: Glyph widths for standard CJK fonts with Unicode CMaps are no longer available due to the transition to external CMaps. PDF_stringwidth() will return 0 in this case. The resolution value is no longer read from JPEG images created with Photoshop. The following deprecated (as of PDFlib 6) functions have been removed from the manual: PDF_add_bookmark() PDF_add_bookmark2() PDF_add_note() PDF_add_note2() PDF_attach_file() PDF_attach_file2() PDF_add_pdflink() PDF_add_locallink() PDF_add_launchlink() PDF_add_weblink() PDF_set_border_style() PDF_set_border_color() PDF_set_border_dash() PDF_open_mem() PDF_open_file() PDF_close() PDF_begin_page() PDF_end_page() PDF_show_boxed() PDF_boot() and PDF_shutdown(): these have never been functional, and were only available in the C language binding. The following deprecated (as of PDFlib 6) parameters have been removed from the manual: compatibility pdfx flush openwarning pagewidth, pageheight (PDF_set_value()) ArtBox/*, BleedBox/*, CropBox/*, TrimBox/* userpassword masterpassword permissions defaultgray defaultrgb defaultcmyk pdiusebox openaction openmode hidetoolbar hidemenubar hidewindowui fitwindow centerwindow displaydoctitle nonfullscreenpagemode direction viewarea, viewclip printarea, printclip bookmarkdest transition duration base launchlink:parameters launchlink:operation launchlink:defaultdir The following unsupported functions have been removed (use PDF_info_font() instead): PDF_encoding_get_glyphname() PDF_encoding_get_unicode() PDF_get_glyphid() PHP binding: Parameter "imagewarning": the default has been "true" for historical reasons; in PDFlib 7 it has been changed to "false" for compatibility with all other language bindings. PDFlib 6.0.3 ============ - Textflow: if the box doesn't contain any text at all when processing is finished (e.g. because the width of the box is too small to hold any text), the return string "_boxfull" is misleading. Textflow will now return the string "_boxempty" in such situations. - New options: PDF_begin_item(): Scope attribute for TH items. PDF_begin/end_document(): moddate PDF_begin/end_document(): search - New parameters: nodemostamp xheight xheightfaked capheightfaked ascenderfaked descenderfaked - The block interface version number has been changed to 6; Block plugin 2.2 or above is required for use with PPS 6.0.3. - Deprecated options: PDF_create_action(), PDF_create_annotation(), PDF_create_bookmark(), and PDF_begin/end_document(): "name" option, "nameddest" suboption of the "type" option. PDFlib 6.0.2 ============ - New options: PDF_fit_textflow(): orientate PDF_create_annotation(): opacity, createdate, subject PDF_info_textflow(): leftlinex/y, rightlinex/y PDF_begin/end_page_ext(): metadata - In order to work around different behavior in Acrobat 5 and 6 regarding several form field options (e.g. the readonly option for radio buttons was not honored in Acrobat 6) the following restriction is now implemented: options "readonly", "unisonselect", "toggle", and "tooltip" for type= radiobutton are only allowed for PDF_create_fieldgroup(), but no longer for PDF_create_field(). Client code which used one of these options for PDF_create_field() created bad PDF output. Such code will now raise a warning unless fieldwarning=false, and thus should be changed to honor the new restrictions. - The leading handling in PDF_create_textflow()/PDF_fit_textflow() has changed. Previously the behavior for multiple leading instructions on a line was undefined, and didn't match the user expectation in certain cases. E.g. when leading was specified at the beginning of the text _and_ in the optlist parameter of PDF_create_textflow(), the leading value from the optlist parameter was used, and not the one from the inline option list. The new leading behavior is documented in the manual. In some situations it may cause different formatting results than with earlier versions, but the previous behavior is considered a bug. PDFlib 6.0.1 ============ - No changes which affect compatibility. PDFlib 6.0.0 ============ See the PDFlib manual for information about new functions and parameters which should be used instead of the deprecated ones. Deprecated functions: - PDF_show_boxed(), PDF_show_boxed2() - PDF_add_bookmark(), PDF_add_bookmark2() - PDF_attach_file(), PDF_attach_file2() - PDF_add_note(), PDF_add_note2() - PDF_add_pdflink() - PDF_add_locallink() - PDF_add_launchlink() - PDF_add_weblink() - PDF_set_border_style() - PDF_set_border_color() - PDF_set_border_dash() Deprecated options for particular functions: - reftype in PDF_load_image() Deprecated parameters: - userpassword, masterpassword, permissions, compatibility, flush, pdfx - openaction, base, launchlink:parameters, launchlink:operation, launchlink:defaultdir, transition, duration, openmode - hidetoolbar, hidemenubar, hidewindowui, fitwindow, centerwindow, displaydoctitle, nonfullscreenpagemode, direction, viewarea, viewclip, printarea, printclip - bookmarkdest - pagewidth, pageheight, artbox, bleedbox, cropbox, trimbox - pdiusebox - defaultrgb/rgb/cmyk Removed functions: The functions PDF_setgray*() and PDF_setrgbcolor*() are no longer available except in the C language. These functions have been deprecated since PDFlib 4. Workaround: use setcolor() instead. Changes in the Java binding: All float parameters have been changed to double, which may require appropriate adjustments to the data types used in client code. Deprecated in the C++ binding: - The overloaded open() calls are no longer available. - The unsupported method get_message() in the PDFlibException object has been replaced with get_errmsg(). Changes in the PHP binding: - Stricter parameter checking: detects bad data types - Optional parameters are no longer supported (all parameters dictated by the API must be provided in the PHP script). Changes related to encodings: The "host" encoding translates to "iso8859-1" on non-Windows platforms (except EBCDIC-based mainframes) instead of "winansi". It is still recommended to explicitly specify the required encoding instead of using "host". PDFlib 5.0.2 ============ - COM: - The functions PDF_setgray*() and PDF_setrgbcolor*() are no longer available in the COM wrapper. These functions have been deprecated since PDFlib 4. Workaround: use setcolor() instead. PDFlib 5.0.1 ============ - No changes which affect compatibility. PDFlib 5.0.0 ============ Deprecated functions: - PDF_findfont() - PDF_setpolydash() - PDF_open_image_file() - PDF_open_CCITT() - PDF_open_image() - PDF_place_pdi_page() - PDF_boot_dll() and PDF_shutdown_dll() Deprecated options for particular functions: - reftype option in PDF_load_image() Deprecated parameters: - prefix Other changes: - Several resource configuration mechanism are superseded by improved mechanisms. However, the previous configuration scheme is still supported. - Introduced a dedicated PDFlibException class for Java. This may require modifications to existing catch clauses. - The new C exception handling with PDF_TRY/PDF_CATCH makes old-style error handlers obsolete. However, PDF_new2() will still accept error handler callbacks. - The PDF_open_pdi_callback() has been slightly modified; this affects only PDFlib customers who used this feature in a preliminary release. - Changed the default value of the "inheritgstate" parameter to false. - By default, PDFlib generates PDF 1.4 (Acrobat 5) output. This can be modified with PDF_set_parameter(p, "compatibility", "1.3"); - The following features have been removed: PDF_set_parameter(p, "compatibility", "1.2"); Careful programming can still produce PDF 1.2 compatible documents, albeit with a PDF 1.3 header entry. - The following functions have been removed: PDF_open_pdi_mem() (only implemented in custom versions of PDFlib+PDI) Change existing calls to the following sequence: PDF_create_pvf(...); PDF_open_pdi(...); - C++ binding: Switches to new-style C++ exceptions by default (as opposed to installing an old-style client-supplied error handler callback function). - PHP binding: Those very old API functions have been removed from the wrapper which stemmed from the prehistoric era before PDFlib GmbH officially supported the PHP wrapper. These functions have never been documented in the PDFlib manual, but have been kept in the PHP wrapper for compatibility reasons. In order to facilitate maintenance we dropped these functions. The pdf_open_memory_image() API is not affected since it actually added new functionality. Although PDFlib GmbH does not support this function it still works. The virtual_dir support has also been dropped. This feature is rather confusing since it is not supported on all platforms and configurations. In addition, it conflicts with the new SearchPatch facility in PDFlib. Finally, it didn't work when generating PDF files with PDF_open_file().