PDFlib GmbH München, Germany www.pdflib.com Reference Manual ® A library for generating PDF on the fly Version 6.0.1 General Edition for Cobol, C, C++, Java, Perl, PHP, Python, RPG, and Tcl Copyright © 1997–2004 PDFlib GmbH and Thomas Merz. All rights reserved. PDFlib GmbH Tal 40, 80331 München, Germany www.pdflib.com phone +49 • 89 • 29 16 46 87 fax +49 • 89 • 29 16 46 86 If you have questions check the PDFlib mailing list and archive at groups.yahoo.com/group/pdflib Licensing contact: [email protected] Support for commercial PDFlib licensees: [email protected] (please include your license number) This publication and the information herein is furnished as is, is subject to change without notice, and should not be construed as a commitment by PDFlib GmbH. PDFlib GmbH assumes no responsibility or lia- bility for any errors or inaccuracies, makes no warranty of any kind (express, implied or statutory) with re- spect to this publication, and expressly disclaims any and all warranties of merchantability, fitness for par- ticular purposes and noninfringement of third party rights. PDFlib and the PDFlib logo are registered trademarks of PDFlib GmbH. PDFlib licensees are granted the right to use the PDFlib name and logo in their product documentation. However, this is not required. Adobe, Acrobat, and PostScript are trademarks of Adobe Systems Inc. AIX, IBM, OS/390, WebSphere, iSeries, and zSeries are trademarks of International Business Machines Corporation. ActiveX, Microsoft, Windows, and Windows NT are trademarks of Microsoft Corporation. Apple, Macintosh and TrueType are trademarks of Apple Computer, Inc. Unicode and the Unicode logo are trademarks of Unicode, Inc. Unix is a trademark of The Open Group. Java and Solaris are trademarks of Sun Microsystems, Inc. HKS is a registered trade- mark of the HKS brand association: Hostmann-Steinberg, K+E Printing Inks, Schmincke. Other company product and service names may be trademarks or service marks of others. PANTONE® colors displayed in the software application or in the user documentation may not match PANTONE-identified standards. Consult current PANTONE Color Publications for accurate color. PANTONE® and other Pantone, Inc. trademarks are the property of Pantone, Inc. © Pantone, Inc., 2003. Pantone, Inc. is the copyright owner of color data and/or software which are licensed to PDFlib GmbH to distribute for use only in combination with PDFlib Software. PANTONE Color Data and/or Software shall not be copied onto another disk or into memory unless as part of the execution of PDFlib Software. PDFlib contains modified parts of the following third-party software: ICClib, Copyright © 1997-2002 Graeme W. Gill GIF image decoder, Copyright © 1990-1994 David Koblas PNG image reference library (libpng), Copyright © 1998-2004 Glenn Randers-Pehrson Zlib compression library, Copyright © 1995-2002 Jean-loup Gailly and Mark Adler TIFFlib image library, Copyright © 1988-1997 Sam Leffler, Copyright © 1991-1997 Silicon Graphics, Inc. Cryptographic software written by Eric Young, Copyright © 1995-1998 Eric Young ([email protected]) Independent JPEG Group’s JPEG software, Copyright © 1991-1998, Thomas G. Lane PDFlib contains the RSA Security, Inc. MD5 message digest algorithm. Viva Software GmbH contributed improvements to the font handling for Mac OS. Author: Thomas Merz Design and illustrations: Alessio Leonardi Quality control (manual): Katja Schnelle Romaus, Kurt Stützer Quality control (software): a cast of thousands Contents 0 Applying the PDFlib License Key 9 1 Introduction 11 1.1 PDFlib Programming 11 1.2 Major new Features in PDFlib 6 13 1.3 PDFlib Features 15 1.4 Availability of Features in different Products 17 2 PDFlib Language Bindings 19 2.1 Overview 19 2.2 Cobol Binding 20 2.2.1 Special Considerations for Cobol 20 2.2.2 The »Hello world« Example in Cobol 20 2.3 COM Binding 24 2.4 C Binding 24 2.4.1 Availability and Special Considerations for C 24 2.4.2 The »Hello world« Example in C 24 2.4.3 Using PDFlib as a DLL loaded at Runtime 25 2.4.4 Error Handling in C 26 2.4.5 Memory Management in C 27 2.4.6 Unicode in the C language binding 28 2.5 C++ Binding 28 2.5.1 Availability and Special Considerations for C++ 28 2.5.2 The »Hello world« Example in C++ 28 2.5.3 Error Handling in C++ 29 2.5.4 Memory Management in C++ 29 2.5.5 Unicode in the C++ language binding 29 2.6 Java Binding 30 2.6.1 Installing the PDFlib Java Edition 30 2.6.2 The »Hello world« Example in Java 31 2.6.3 Error Handling in Java 32 2.7 .NET Binding 33 2.8 Perl Binding 33 2.8.1 Installing the PDFlib Perl Edition 33 2.8.2 The »Hello world« Example in Perl 33 2.8.3 Error Handling in Perl 34 2.9 PHP Binding 34 2.9.1 Installing the PDFlib PHP Edition 34 2.9.2 The »Hello world« Example in PHP 35 Contents 3 2.9.3 Error Handling in PHP 37 2.10 Python Binding 38 2.10.1 Installing the PDFlib Python Edition 38 2.10.2 The »Hello world« Example in Python 38 2.10.3 Error Handling in Python 38 2.11 REALbasic Binding 39 2.12 RPG Binding 39 2.12.1 Compiling and Binding RPG Programs for PDFlib 39 2.12.2 The »Hello world« Example in RPG 39 2.12.3 Error Handling in RPG 41 2.13 Tcl Binding 43 2.13.1 Installing the PDFlib Tcl Edition 43 2.13.2 The »Hello world« Example in Tcl 43 2.13.3 Error Handling in Tcl 44 3 PDFlib Programming 45 3.1 General Programming 45 3.1.1 PDFlib Program Structure and Function Scopes 45 3.1.2 Parameters 45 3.1.3 Exception Handling 46 3.1.4 Option Lists 48 3.1.5 The PDFlib Virtual File System (PVF) 50 3.1.6 Resource Configuration and File Searching 51 3.1.7 Generating PDF Documents in Memory 55 3.1.8 Using PDFlib on EBCDIC-based Platforms 55 3.1.9 Large File Support 56 3.2 Page Descriptions 57 3.2.1 Coordinate Systems 57 3.2.2 Page Sizes and Coordinate Limits 59 3.2.3 Paths 60 3.2.4 Templates 61 3.3 Working with Color 63 3.3.1 Color and Color Spaces 63 3.3.2 Patterns and Smooth Shadings 63 3.3.3 Spot Colors 64 3.3.4 Color Management and ICC Profiles 67 3.4 Hypertext Elements 71 3.4.1 Examples for Creating Hypertext Elements 71 3.4.2 Formatting Options for Text Fields 74 4 Text Handling 77 4.1 Overview of Fonts and Encodings 77 4.1.1 Supported Font Formats 77 4.1.2 Encodings 78 4 Contents 4.1.3 Support for the Unicode Standard 79 4.2 Font Format Details 80 4.2.1 PostScript Fonts 80 4.2.2 TrueType and OpenType Fonts 81 4.2.3 User-Defined (Type 3) Fonts 83 4.3 Font Embedding and Subsetting 84 4.3.1 How PDFlib Searches for Fonts 84 4.3.2 Font Embedding 85 4.3.3 Font Subsetting 87 4.4 Encoding Details 89 4.4.1 8-Bit Encodings 89 4.4.2 Symbol Fonts and Font-specific Encodings 92 4.4.3 Glyph ID Addressing for TrueType and OpenType Fonts 93 4.4.4 The Euro Glyph 93 4.5 Unicode Support 95 4.5.1 Unicode for Page Content and Hypertext 95 4.5.2 Content Strings, Hypertext Strings, and Name Strings 96 4.5.3 String Handling in Unicode-capable Languages 97 4.5.4 String Handling in non-Unicode-capable Languages 98 4.5.5 Character References 100 4.5.6 Unicode-compatible Fonts 102 4.6 Text Metrics and Text Variations 104 4.6.1 Font and Character Metrics 104 4.6.2 Kerning 105 4.6.3 Text Variations 106 4.7 Chinese, Japanese, and Korean Text 108 4.7.1 CJK support in Acrobat and PDF 108 4.7.2 Standard CJK Fonts and CMaps 108 4.7.3 Custom CJK Fonts 112 4.7.4 Forcing monospaced Fonts 114 4.8 Placing and Fitting Single-Line Text 115 4.8.1 Simple Text Placement 115 4.8.2 Placing Text in a Box 116 4.8.3 Aligning Text 117 4.9 Multi-Line Textflows 118 4.9.1 Placing Textflows in the Fitbox 119 4.9.2 Paragraph Formatting Options 120 4.9.3 Inline Option Lists and Macros 121 4.9.4 Tab Stops 123 4.9.5 Numbered Lists 124 4.9.6 Control Characters, Character Mapping, and Symbol Fonts 125 4.9.7 Hyphenation 127 4.9.8 Controlling the Linebreak Algorithm 129 4.9.9 Formatting CJK Text with Textflow 132 Contents 5 5 Importing and Placing Objects 133 5.1 Importing Raster Images 133 5.1.1 Basic Image Handling 133 5.1.2 Supported Image File Formats 134 5.1.3 Image Masks and Transparency 136 5.1.4 Colorizing Images 138 5.1.5 Multi-Page Image Files 139 5.1.6 OPI Support 139 5.2 Importing PDF Pages with PDI (PDF Import Library) 140 5.2.1 PDI Features and Applications 140 5.2.2 Using PDI Functions with PDFlib 140 5.2.3 Acceptable PDF Documents 142 5.3 Placing Images and Imported PDF Pages 144 5.3.1 Scaling, Orientation, and Rotation 144 5.3.2 Adjusting the Page Size 146 6 Variable Data and Blocks 149 6.1 Installing the PDFlib Block Plugin 149 6.2 Overview of the PDFlib Block Concept 150 6.2.1 Complete Separation of Document Design and Program Code 150 6.2.2 Block Properties 151 6.2.3 Why not use PDF Form Fields? 152 6.3 Creating PDFlib Blocks 154 6.3.1 Creating Blocks interactively with the PDFlib Block Plugin 154 6.3.2 Editing Block Properties 156 6.3.3 Copying Blocks between Pages and Documents 157 6.3.4 Converting PDF Form Fields to PDFlib Blocks 159 6.4 Standard Properties for Automated Processing 161 6.4.1 General Properties 161 6.4.2 Text Properties 163 6.4.3 Image Properties 167 6.4.4 PDF Properties 167 6.4.5 Custom Properties 168 6.5 Querying Block Names and Properties 169 6.6 PDFlib Block Specification 171 6.6.1 PDF Object Structure for PDFlib Blocks 171 6.6.2 Generating PDFlib Blocks with pdfmarks 173 7 Generating various PDF Flavors 175 7.1 Acrobat and PDF Versions 175 7.2 Encrypted PDF 176 7.2.1 Strengths and Weaknesses of PDF Security 176 7.2.2 Protecting Documents with PDFlib 177 6 Contents 7.3 Web-Optimized (Linearized) PDF 179 7.4 PDF/X 180 7.4.1 The PDF/X Family of Standards 180 7.4.2 Generating PDF/X-conforming Output 181 7.4.3 Importing PDF/X