ABC PDFlib, PDFlib+PDI, PPS A library for generating PDF on the fly PDFlib 9.3.1 Tutorial For use with C, C++, Java, .NET, .NET Core, Objective-C, Perl, PHP, Python, RPG, Ruby Copyright © 1997–2021 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 [email protected] [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 the following third-party components: Adobe CMap resources, Copyright © 1990-2019 Adobe AES, Arcfour and SHA algorithms, Copyright © 1995-1998 Eric Young Expat XML parser, Copyright © 2001-2017 Expat maintainers ICClib, Copyright © 1997-2002 Graeme W. Gill ICU International Components for Unicode, Copyright © 1995-2012 IBM Koblas GIF image decoder, Copyright © 1990-1994 David Koblas libjpeg, Copyright © 1991-2019, Thomas G. Lane, Guido Vollbeding libpng, Copyright © 1998-2002, 2004, 2006-2017 Glenn Randers-Pehrson TIFFlib image library, Copyright © 1988-1997 Sam Leffler, Copyright © 1991-1997 Silicon Graphics, Inc. MD5 message digest, Copyright © 1991-2, RSA Data Security, Inc. sRGB ICC profile, Copyright © 1998 Hewlett-Packard Company Zlib compression library, Copyright © 1995-2017 Jean-loup Gailly and Mark Adler The PDFlib Block Plugin contains the following additional third-party component: wxWidgets Cross-Platform GUI Library, Copyright © 2018 © 1998 Julian Smart, © 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 What’s new in PDFlib/PDFlib+PDI/PPS 9.3? 21 1.7 Features in PDFlib 23 1.8 Additional Features in PDFlib+PDI 26 1.9 Additional Features in PPS 27 1.10 Availability of Features in different Products 28 2 PDFlib Language Bindings 29 2.1 C Binding 29 2.2 C++ Binding 32 2.3 Java Binding 34 2.4 .NET Binding 36 2.4.1 .NET Binding Variants 36 2.4.2 .NET Core Binding 36 2.4.3 Classic .NET Binding 37 2.4.4 Using the .NET Binding in Applications 38 2.5 Objective-C Binding 39 2.6 Perl Binding 41 2.7 PHP Binding 43 2.8 Python Binding 45 2.9 RPG Binding 46 2.10 Ruby Binding 48 3 Creating PDF Documents 51 3.1 General PDFlib Programming Aspects 51 3.1.1 Exception Handling 51 3.1.2 Logging 53 3.1.3 The PDFlib Virtual File System (PVF) 53 3.1.4 Resource Configuration and File Search 55 3.1.5 Generating PDF Documents in Memory 60 3.1.6 Maximum Size of PDF Documents and other Limits 61 3.1.7 Multi-threaded Programming 61 Contents 3 3.1.8 Using PDFlib on EBCDIC-based Platforms 62 3.2 Page Descriptions 63 3.2.1 Coordinate Systems 63 3.2.2 Page Size 65 3.2.3 Direct Paths and Path Objects 66 3.2.4 Templates (Form XObjects) 68 3.3 PDF Password Security 70 3.3.1 Password Security in PDF 70 3.3.2 Password-Protecting PDF Documents with PDFlib 73 4 Color Spaces 77 4.1 Device Color Spaces 77 4.2 Color Management with ICC Profiles 79 4.3 Device-Independent CIE L*a*b* Color 83 4.4 Pantone, HKS, and custom Spot Colors 84 4.5 DeviceN Colors 88 4.6 Shadings and Shading Patterns 92 4.7 Tiling Patterns 94 4.8 Transparency Blend Modes 95 4.9 Changing the Color of Objects 98 4.9.1 Changing the Color with Blend Modes 98 4.9.2 Changing the Color with Soft Masks 99 4.10 Rendering Intents 101 4.11 Overprint Control 102 5 Unicode and Legacy Encodings 105 5.1 Important Unicode Concepts 105 5.2 Unicode-capable Language Bindings 107 5.2.1 Language Bindings with native Unicode Strings 107 5.2.2 Language Bindings with UTF-8 Support 107 5.3 Non-Unicode-capable Language Bindings 109 5.4 Single-Byte (8-Bit) Encodings 113 5.5 Chinese, Japanese, and Korean CMaps 116 5.6 Addressing Characters 118 5.6.1 Escape Sequences 118 5.6.2 Character References 119 6 Font Handling 123 6.1 Font Formats 123 6.1.1 TrueType Fonts 123 6.1.2 OpenType Fonts 123 6.1.3 WOFF Fonts 124 4 Contents 6.1.4 PostScript Type 1 Fonts 124 6.1.5 SING Fonts (Glyphlets) 125 6.1.6 Type 3 Fonts 125 6.2 Unicode Characters and Glyphs 127 6.2.1 Glyph IDs 127 6.2.2 Unicode Mappings for Glyphs 127 6.2.3 Unicode Control Characters 129 6.3 The Text Processing Pipeline 130 6.3.1 Normalizing Input Strings to Unicode 130 6.3.2 Converting Unicode Values to Glyph IDs 131 6.3.3 Transforming Glyph IDs 132 6.4 Loading Fonts 133 6.4.1 Selecting an Encoding for Text Fonts 133 6.4.2 Selecting an Encoding for symbolic Fonts 135 6.4.3 Example: Selecting a Glyph from the Wingdings Symbol Font 137 6.4.4 Searching for Fonts 140 6.4.5 Host Fonts on Windows and macOS 144 6.4.6 Fallback Fonts 146 6.5 Font Embedding and Subsetting 149 6.5.1 Font Embedding 149 6.5.2 Font Subsetting 150 6.6 Querying Font Information 152 6.6.1 Font-independent Encoding, Unicode, and Glyph Name Queries 152 6.6.2 Font-specific Encoding, Unicode, and Glyph Name Queries 153 6.6.3 Querying Codepage Coverage and Fallback Fonts 154 7 Text Output 159 7.1 Text Output Methods 159 7.2 Font Metrics and Text Variations 160 7.2.1 Font and Glyph Metrics 160 7.2.2 Kerning 161 7.2.3 Text Variations 161 7.3 OpenType Layout Features 164 7.3.1 Supported OpenType Layout Features 164 7.3.2 OpenType Layout Features with Textlines and Textflows 166 7.4 Complex Script Output 170 7.4.1 Complex Scripts 170 7.4.2 Script and Language 172 7.4.3 Complex Script Shaping 173 7.4.4 Bidirectional Formatting 174 7.4.5 Arabic Text Formatting 176 7.5 Chinese, Japanese, and Korean Text Output 177 7.5.1 Using TrueType and OpenType CJK Fonts 177 7.5.2 Horizontal and Vertical Writing Mode 177 7.5.3 EUDC and SING Fonts for Gaiji Characters 178 7.5.4 OpenType Layout Features for advanced CJK Text Output 179 Contents 5 7.5.5 Unicode Variation Selectors and Variation Sequences 181 7.5.6 Standard CJK Fonts 182 8 Importing Images, SVG Graphics and PDF Pages 185 8.1 Raster Images 185 8.1.1 Basic Image Handling 185 8.1.2 Supported Image File Formats 186 8.1.3 Clipping Paths 190 8.1.4 Image Transparency 191 8.1.5 Colorize Images with Spot or DeviceN Color 194 8.1.6 Modifying Color Values with a Decode Array 195 8.2 SVG Graphics 197 8.2.1 Supported SVG Flavors 197 8.2.2 SVG Processing Considerations 197 8.2.3 Visible Size of SVG Graphics 199 8.2.4 Font Selection 199 8.2.5 Dealing with missing Fonts and missing Glyphs 202 8.2.6 SVG Color Extension 203 8.2.7 SVG Contents beyond Vector Graphics and Text 205 8.2.8 Unsupported SVG Features 206 8.3 Importing PDF Pages with PDI 208 8.3.1 PDI Features and Applications 208 8.3.2 Using PDFlib+PDI 208 8.3.3 Document and Page-related Checks 210 8.3.4 Specific Aspects of imported PDF Documents 210 8.4 Placing Images, Graphics, and imported PDF Pages 213 8.4.1 Simple Object Placement 213 8.4.2 Placing an Object at a Point or Line or in a Box 213 8.4.3 Orientating an Object 215 8.4.4 Rotating an Object 216 8.4.5 Adjusting the Page Size 217 8.4.6 Querying Information about placed Images and PDF Pages 218 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 9.2 Multi-Line Textflows 231 9.2.1 Placing Textflows in the Fitbox 232 6 Contents 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 9.3.3 Table and Column Widths 257 9.3.4 Mixed Table Contents 258 9.3.5 Table Instances 261 9.3.6 Table Formatting Algorithm 263 9.4 Matchboxes 267 9.4.1 Decorating a Textline 267 9.4.2 Using Matchboxes in a Textflow 268 9.4.3 Matchboxes and Images 269 10 Interactive Features 271 10.1 Links,