ABC PDFlib, PDFlib+PDI, PPS A library for generating PDF on the fly PDFlib 9.2.0 Tutorial For use with C, C++, COM, Java, .NET, Objective-C, Perl, PHP, Python, RPG, Ruby Copyright © 1997–2019 PDFlib GmbH and Thomas Merz. All rights reserved. PDFlib users are granted permission to reproduce printed or digital copies of this manual for internal use. PDFlib GmbH Franziska-Bilek-Weg 9, 80339 München, Germany www.pdflib.com phone +49 • 89 • 452 33 84-0 If you have questions check the PDFlib mailing list and archive at groups.yahoo.com/neo/groups/pdflib/info 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. 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-2002, 2004, 2006-2017 Glenn Randers-Pehrson Zlib compression library, Copyright © 1995-2017 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-2017, Thomas G. Lane, Guido Vollbeding Cryptographic software, Copyright © 1998-2002 The OpenSSL Project (www.openssl.org) Expat XML parser, Copyright © 2001-2017 Expat maintainers ICU International Components for Unicode, Copyright © 1995-2012 International Business Machines Corpo- ration and others PDFlib contains the RSA Data Security, Inc. MD5 Message Digest Algorithm. The PDFlib Block Plugin contains the following third-party software: wxWindows Cross-Platform GUI Library, Copyright © 2018 wxWidgets Contents 0 Applying the PDFlib License Key 11 1 Introduction 15 1.1 Roadmap to Documentation and Samples 15 1.2 PDFlib Programming 17 1.3 What’s new in PDFlib/PDFlib+PDI/PPS 9.0? 19 1.4 What’s new in PDFlib/PDFlib+PDI/PPS 9.1? 21 1.5 What’s new in PDFlib/PDFlib+PDI/PPS 9.2? 21 1.6 Features in PDFlib 22 1.7 Additional Features in PDFlib+PDI 25 1.8 Additional Features in PPS 26 1.9 Availability of Features in different Products 27 2 PDFlib Language Bindings 29 2.1 C Binding 29 2.2 C++ Binding 32 2.3 COM Binding 34 2.4 Java Binding 36 2.5 .NET Binding 39 2.5.1 .NET Binding Variants 39 2.5.2 .NET Core Binding 39 2.5.3 Classic .NET Binding 40 2.5.4 Using the .NET Binding in Applications 41 2.6 Objective-C Binding 42 2.7 Perl Binding 44 2.8 PHP Binding 46 2.9 Python Binding 48 2.10 RPG Binding 49 2.11 Ruby Binding 51 3 Creating PDF Documents 53 3.1 General PDFlib Programming Aspects 53 3.1.1 Exception Handling 53 3.1.2 Logging 55 3.1.3 The PDFlib Virtual File System (PVF) 55 3.1.4 Resource Configuration and File Search 57 3.1.5 Generating PDF Documents in Memory 62 3.1.6 Maximum Size of PDF Documents and other Limits 63 3.1.7 Multi-threaded Programming 64 Contents 3 3.1.8 Using PDFlib on EBCDIC-based Platforms 64 3.2 Page Descriptions 65 3.2.1 Coordinate Systems 65 3.2.2 Page Size 67 3.2.3 Direct Paths and Path Objects 68 3.2.4 Templates (Form XObjects) 70 3.2.5 Referenced Pages from an external PDF Document 71 3.3 PDF Password Security 73 3.3.1 Password Security in PDF 73 3.3.2 Password-Protecting PDF Documents with PDFlib 76 4 Color Spaces 79 4.1 Device Color Spaces 79 4.2 Color Management with ICC Profiles 81 4.3 Device-Independent CIE L*a*b* Color 85 4.4 Pantone, HKS, and custom Spot Colors 86 4.5 DeviceN Colors 90 4.6 Shadings and Shading Patterns 94 4.7 Tiling Patterns 96 4.8 Transparency Blend Modes 97 4.9 Changing the Color of Objects 100 4.9.1 Changing the Color with Blend Modes 100 4.9.2 Changing the Color with Soft Masks 101 4.10 Rendering Intents 103 4.11 Overprint Control 104 5 Unicode and Legacy Encodings 107 5.1 Important Unicode Concepts 107 5.2 Unicode-capable Language Bindings 109 5.2.1 Language Bindings with native Unicode Strings 109 5.2.2 Language Bindings with UTF-8 Support 109 5.3 Non-Unicode-capable Language Bindings 111 5.4 Single-Byte (8-Bit) Encodings 115 5.5 Chinese, Japanese, and Korean Encodings 118 5.6 Addressing Characters 121 5.6.1 Escape Sequences 121 5.6.2 Character References 122 6 Font Handling 125 6.1 Font Formats 125 6.1.1 TrueType Fonts 125 6.1.2 OpenType Fonts 125 4 Contents 6.1.3 WOFF Fonts 126 6.1.4 SVG Fonts 126 6.1.5 PostScript Type 1 Fonts 127 6.1.6 SING Fonts (Glyphlets) 127 6.1.7 CEF Fonts 128 6.1.8 Type 3 Fonts 128 6.2 Unicode Characters and Glyphs 130 6.2.1 Glyph IDs 130 6.2.2 Unicode Mappings for Glyphs 130 6.2.3 Unicode Control Characters 132 6.3 The Text Processing Pipeline 133 6.3.1 Normalizing Input Strings to Unicode 133 6.3.2 Converting Unicode Values to Glyph IDs 134 6.3.3 Transforming Glyph IDs 135 6.4 Loading Fonts 136 6.4.1 Selecting an Encoding for Text Fonts 136 6.4.2 Selecting an Encoding for symbolic Fonts 138 6.4.3 Example: Selecting a Glyph from the Wingdings Symbol Font 140 6.4.4 Searching for Fonts 143 6.4.5 Host Fonts on Windows and macOS 147 6.4.6 Fallback Fonts 149 6.5 Font Embedding and Subsetting 153 6.5.1 Font Embedding 153 6.5.2 Font Subsetting 154 6.6 Querying Font Information 156 6.6.1 Font-independent Encoding, Unicode, and Glyph Name Queries 156 6.6.2 Font-specific Encoding, Unicode, and Glyph Name Queries 157 6.6.3 Querying Codepage Coverage and Fallback Fonts 158 7 Text Output 161 7.1 Text Output Methods 161 7.2 Font Metrics and Text Variations 162 7.2.1 Font and Glyph Metrics 162 7.2.2 Kerning 163 7.2.3 Text Variations 164 7.3 OpenType Layout Features 166 7.3.1 Supported OpenType Layout Features 166 7.3.2 OpenType Layout Features with Textlines and Textflows 168 7.4 Complex Script Output 172 7.4.1 Complex Scripts 172 7.4.2 Script and Language 174 7.4.3 Complex Script Shaping 175 7.4.4 Bidirectional Formatting 176 7.4.5 Arabic Text Formatting 178 7.5 Chinese, Japanese, and Korean Text Output 179 7.5.1 Using TrueType and OpenType CJK Fonts 179 Contents 5 7.5.2 EUDC and SING Fonts for Gaiji Characters 180 7.5.3 OpenType Layout Features for advanced CJK Text Output 181 7.5.4 Unicode Variation Selectors and Variation Sequences 183 7.5.5 Standard CJK Fonts 184 8 Importing Images, SVG Graphics and PDF Pages 187 8.1 Raster Images 187 8.1.1 Basic Image Handling 187 8.1.2 Supported Image File Formats 188 8.1.3 Clipping Paths 192 8.1.4 Image Transparency 193 8.1.5 Colorize Images with Spot or DeviceN Color 196 8.1.6 Modifying Color Values with a Decode Array 197 8.2 SVG Graphics 199 8.2.1 Supported SVG Flavors 199 8.2.2 SVG Processing Considerations 199 8.2.3 Visible Size of SVG Graphics 201 8.2.4 Font Selection 201 8.2.5 Dealing with missing Fonts and missing Glyphs 203 8.2.6 SVG Color Extension 205 8.2.7 SVG Contents beyond Vector Graphics and Text 205 8.2.8 Unsupported SVG Features 207 8.3 Importing PDF Pages with PDI 209 8.3.1 PDI Features and Applications 209 8.3.2 Using PDFlib+PDI 209 8.3.3 Document and Page-related Checks 211 8.3.4 Specific Aspects of imported PDF Documents 211 8.4 Placing Images, Graphics, and imported PDF Pages 214 8.4.1 Simple Object Placement 214 8.4.2 Placing an Object at a Point or Line or in a Box 214 8.4.3 Orientating an Object 216 8.4.4 Rotating an Object 217 8.4.5 Adjusting the Page Size 218 8.4.6 Querying Information about placed Images and PDF Pages 219 9 Text and Table Formatting 221 9.1 Placing and Fitting Textlines 221 9.1.1 Simple Textline Placement 221 9.1.2 Positioning Text in a Box 222 9.1.3 Fitting Text into a Box 223 9.1.4 Aligning Text at a Character 225 9.1.5 Placing a Stamp 226 9.1.6 Using Leaders 226 9.1.7 Text on a Path 227 9.1.8 Shadowed Text 228 9.1.9 Watermarks which can be edited in Acrobat 229 6 Contents 9.2 Multi-Line Textflows 231 9.2.1 Placing Textflows in the Fitbox 232 9.2.2 Paragraph Formatting Options 234 9.2.3 Inline Option Lists and Macros 234 9.2.4 Tab Stops 237 9.2.5 Numbered Lists and Paragraph Spacing 238 9.2.6 Control Characters and Character Mapping 239 9.2.7 Hyphenation 242 9.2.8 Widow and Orphan Lines 243 9.2.9 Controlling the standard Linebreak Algorithm 243 9.2.10 Advanced script-specific Line Breaking 246 9.2.11 Wrapping Text around Paths and Images 247 9.3 Table Formatting 251 9.3.1 Placing a Simple Table 252 9.3.2 Contents of a Table Cell 255