PDFlib GmbH München, Germany Reference Manual ® A library for generating PDF on the fly Version 5.0.2 www.pdflib.com Copyright © 1997–2003 PDFlib GmbH and Thomas Merz. All rights reserved. PDFlib GmbH Tal 40, 80331 München, Germany http://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 http://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 PNG image reference library (libpng), Copyright © 1998-2002 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]) 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 Karsunke, Rainer Schaaf, 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 PDFlib Features 13 1.3 Availability of Features in different Products 15 1.4 Acrobat Versions and PDFlib Features 16 2 PDFlib Language Bindings 17 2.1 Overview 17 2.2 Cobol Binding 18 2.2.1 Special Considerations for Cobol 18 2.2.2 The »Hello world« Example in Cobol 18 2.3 COM Binding 21 2.4 C Binding 21 2.4.1 Availability and Special Considerations for C 21 2.4.2 The »Hello world« Example in C 21 2.4.3 Using PDFlib as a DLL loaded at Runtime 22 2.4.4 Error Handling in C 24 2.4.5 Memory Management in C 25 2.5 C++ Binding 25 2.5.1 Availability and Special Considerations for C++ 25 2.5.2 The »Hello world« Example in C++ 25 2.5.3 Error Handling in C++ 26 2.5.4 Memory Management in C++ 27 2.6 Java Binding 27 2.6.1 Installing the PDFlib Java Edition 27 2.6.2 The »Hello world« Example in Java 28 2.6.3 Error Handling in Java 29 2.7 .NET Binding 30 2.8 Perl Binding 30 2.8.1 Installing the PDFlib Perl Edition 30 2.8.2 The »Hello world« Example in Perl 31 2.8.3 Error Handling in Perl 31 2.9 PHP Binding 31 2.9.1 Installing the PDFlib PHP Edition 31 2.9.2 The »Hello world« Example in PHP 32 2.9.3 Error Handling in PHP 33 Contents 3 2.10 Python Binding 33 2.10.1 Installing the PDFlib Python Edition 33 2.10.2 The »Hello world« Example in Python 34 2.10.3 Error Handling in Python 34 2.11 RPG Binding 34 2.11.1 Compiling and Binding RPG Programs for PDFlib 34 2.11.2 The »Hello world« Example in RPG 35 2.11.3 Error Handling in RPG 37 2.12 Tcl Binding 38 2.12.1 Installing the PDFlib Tcl Edition 38 2.12.2 The »Hello world« Example in Tcl 39 2.12.3 Error Handling in Tcl 39 3 PDFlib Programming 41 3.1 General Programming 41 3.1.1 PDFlib Program Structure and Function Scopes 41 3.1.2 Parameters 41 3.1.3 Exception Handling 42 3.1.4 Option Lists 44 3.1.5 The PDFlib Virtual File System (PVF) 46 3.1.6 Resource Configuration and File Searching 47 3.1.7 Generating PDF Documents in Memory 50 3.1.8 Using PDFlib on EBCDIC-based Platforms 51 3.2 Page Descriptions 53 3.2.1 Coordinate Systems 53 3.2.2 Page Sizes and Coordinate Limits 55 3.2.3 Paths 56 3.2.4 Templates 57 3.3 Working with Color 59 3.3.1 Color and Color Spaces 59 3.3.2 Patterns and Smooth Shadings 59 3.3.3 Spot Colors 60 3.3.4 Color Management and ICC Profiles 63 3.3.5 Working with ICC Profiles 64 3.3.6 Device-Independent CIE L*a*b* Color 65 3.3.7 Rendering Intents 65 3.4 PDF/X Support 67 3.4.1 Generating PDF/X-conforming Output 67 3.4.2 Importing PDF/X Documents with PDI 69 3.5 Passwords and Permissions 71 3.5.1 Strengths and Weaknesses of PDF Security Features 71 3.5.2 Protecting Documents with PDFlib 72 4 Contents 4 Text Handling 73 4.1 Overview of Fonts and Encodings 73 4.1.1 Supported Font Formats 73 4.1.2 Encodings 74 4.1.3 Support for the Unicode Standard 75 4.2 Supported Font Formats 76 4.2.1 PostScript Fonts 76 4.2.2 TrueType and OpenType Fonts 77 4.2.3 User-Defined (Type 3) Fonts 78 4.3 Font Embedding and Subsetting 80 4.3.1 How PDFlib Searches for Fonts 80 4.3.2 Font Embedding 81 4.3.3 Font Subsetting 83 4.4 Encoding Details 84 4.4.1 8-Bit Encodings 84 4.4.2 Symbol Fonts and Font-specific Encodings 87 4.4.3 Glyph ID Addressing for TrueType and OpenType Fonts 88 4.4.4 The Euro Glyph 88 4.5 Unicode Support 90 4.5.1 Unicode for Page Descriptions 90 4.5.2 Unicode Text Formats 91 4.5.3 Unicode for Hypertext Elements 92 4.5.4 Unicode Support in PDFlib Language Bindings 94 4.6 Text Metrics, Text Variations, and Box Formatting 95 4.6.1 Font and Character Metrics 95 4.6.2 Kerning 96 4.6.3 Text Variations 97 4.6.4 Box Formatting 98 4.7 Chinese, Japanese, and Korean Text 100 4.7.1 CJK support in Acrobat and PDF 100 4.7.2 Standard CJK Fonts and CMaps 100 4.7.3 Custom CJK Fonts 104 4.7.4 Forcing monospaced Fonts 105 4.8 Placing and Fitting Text 106 4.8.1 Simple Text Placement 106 4.8.2 Placing Text in a Box 107 4.8.3 Aligning Text 108 5 Importing and Placing Objects 109 5.1 Importing Raster Images 109 5.1.1 Basic Image Handling 109 5.1.2 Supported Image File Formats 110 5.1.3 Image Masks and Transparency 112 5.1.4 Colorizing Images 114 Contents 5 5.1.5 Multi-Page Image Files 115 5.2 Importing PDF Pages with PDI (PDF Import Library) 116 5.2.1 PDI Features and Applications 116 5.2.2 Using PDI Functions with PDFlib 116 5.2.3 Acceptable PDF Documents 118 5.3 Placing Images and Imported PDF Pages 119 5.3.1 Scaling, Orientation, and Rotation 119 5.3.2 Adjusting the Page Size 121 6 Variable Data and Blocks 125 6.1 Overview of the PDFlib Block Concept 125 6.1.1 Complete Separation of Document Design and Program Code 125 6.1.2 Block Properties 126 6.1.3 Why not use PDF Form Fields? 127 6.2 Creating PDFlib Blocks 129 6.2.1 Installing the PDFlib Block Plugin 129 6.2.2 Creating Blocks interactively with the PDFlib Block Plugin 129 6.2.3 Editing Block Properties 132 6.2.4 Converting PDF Form Fields to PDFlib Blocks 133 6.3 Standard Properties for automated Processing 135 6.4 Querying Block Names and Properties 139 6.5 PDFlib Block Specification 140 6.5.1 PDF Object Structure for PDFlib Blocks 140 6.5.2 Generating PDFlib Blocks with pdfmarks 142 7 API Reference for PDFlib, PDI, and PPS 143 7.1 Data Types and Naming Conventions 143 7.2 General Functions 144 7.2.1 Setup 144 7.2.2 Document and Page 147 7.2.3 Parameter Handling 150 7.2.4 PDFlib Virtual File System (PVF) Functions 151 7.2.5 Exception Handling 153 7.3 Text Functions 155 7.3.1 Font Handling 155 7.3.2 User-defined (Type 3) Fonts 158 7.3.3 Encoding Definition 160 7.3.4 Text Output 160 7.4 Graphics Functions 168 7.4.1 Graphics State Functions 168 7.4.2 Saving and Restoring Graphics States 170 7.4.3 Coordinate System Transformation Functions 171 7.4.4 Explicit Graphics States 173 6 Contents 7.4.5 Path Construction 174 7.4.6 Path Painting and Clipping 177 7.5 Color Functions 179 7.5.1 Setting Color and Color Space 179 7.5.2 Patterns and Shadings 182 7.6 Image and Template Functions 185 7.6.1 Images 185 7.6.2 Templates 190 7.6.3 Deprecated Functions 190 7.7 PDF Import (PDI) Functions 192 7.7.1 Document and Page 192 7.7.2 Other PDI Processing 195 7.7.3 Parameter Handling 196 7.8 Block Filling Functions (PPS) 198 7.9 Hypertext Functions 201 7.9.1 Document Open Action and Open Mode 201 7.9.2 Viewer Preferences 201 7.9.3 Bookmarks 202 7.9.4 Document Information Fields 203 7.9.5 Page Transitions 204 7.9.6 File Attachments 204 7.9.7 Note Annotations 205 7.9.8 Link Annotations and Named Destinations 206 7.9.9 Thumbnails 210 8 References 213 A PDFlib Quick Reference 215 B Revision History 220 Index 221 Contents 7 0 Applying the PDFlib License Key All binary PDFlib and PDI versions supplied by PDFlib GmbH can be used as fully func- tional evaluation versions regardless of whether or not you obtained a commercial li- cense.