Pdflib-9.1.2-Tutorial.Pdf
Total Page:16
File Type:pdf, Size:1020Kb
ABC PDFlib, PDFlib+PDI, PPS A library for generating PDF on the fly PDFlib 9.1.2 Tutorial For use with C, C++, Cobol, COM, Java, .NET, Objective-C, Perl, PHP, Python, REALbasic/Xojo, RPG, Ruby Copyright © 1997–2018 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 fax +49 • 89 • 452 33 84-99 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. Adobe, Acrobat, PostScript, and XMP are trademarks of Adobe Systems Inc. AIX, IBM, OS/390, WebSphere, iSeries, and zSeries are trademarks of International Business Machines Corporation. ActiveX, Microsoft, OpenType, and Windows 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 regis- tered trademark 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-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-2016, Thomas G. Lane, Guido Vollbeding Cryptographic software, Copyright © 1998-2002 The OpenSSL Project (www.openssl.org) Expat XML parser, Copyright © 1998-2000 Thai Open Source Software Center Ltd and Clark Cooper; Copyright (c) 2001-2017 Expat maintainers ICU International Components for Unicode, Copyright © 1995-2012 International Business Machines Corpo- ration and others Reference sRGB ICC color profile data, Copyright (c) 1998 Hewlett-Packard Company PDFlib contains the RSA Security, Inc. MD5 message digest algorithm. 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 Features in PDFlib 22 1.6 Additional Features in PDFlib+PDI 25 1.7 Additional Features in PPS 26 1.8 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 35 2.4 Cobol Binding 40 2.5 Java Binding 41 2.6 .NET Binding 44 2.7 Objective-C Binding 47 2.8 Perl Binding 49 2.9 PHP Binding 51 2.10 Python Binding 53 2.11 REALbasic/Xojo Binding 54 2.12 RPG Binding 55 2.13 Ruby Binding 57 3 Creating PDF Documents 59 3.1 General PDFlib Programming Aspects 59 3.1.1 Exception Handling 59 3.1.2 Logging 61 3.1.3 The PDFlib Virtual File System (PVF) 61 3.1.4 Resource Configuration and File Search 63 3.1.5 Generating PDF Documents in Memory 68 3.1.6 Maximum Size of PDF Documents and other Limits 69 3.1.7 Multi-threaded Programming 70 3.1.8 Using PDFlib on EBCDIC-based Platforms 70 Contents 3 3.2 Page Descriptions 71 3.2.1 Coordinate Systems 71 3.2.2 Page Size 73 3.2.3 Direct Paths and Path Objects 74 3.2.4 Templates (Form XObjects) 76 3.2.5 Referenced Pages from an external PDF Document 77 3.3 PDF Password Security 79 3.3.1 Password Security in PDF 79 3.3.2 Password-Protecting PDF Documents with PDFlib 82 4 Color Spaces 85 4.1 Device Color Spaces 85 4.2 Color Management with ICC Profiles 87 4.3 Device-Independent CIE L*a*b* Color 91 4.4 Pantone, HKS, and custom Spot Colors 92 4.5 DeviceN Colors 96 4.6 Shadings and Shading Patterns 100 4.7 Tiling Patterns 102 4.8 Transparency Blend Modes 103 4.9 Changing the Color of Objects 106 4.9.1 Changing the Color with Blend Modes 106 4.9.2 Changing the Color with Soft Masks 107 4.10 Rendering Intents 109 4.11 Overprint Control 110 5 Unicode and Legacy Encodings 113 5.1 Important Unicode Concepts 113 5.2 Unicode-capable Language Bindings 115 5.2.1 Language Bindings with native Unicode Strings 115 5.2.2 Language Bindings with UTF-8 Support 115 5.3 Non-Unicode-capable Language Bindings 117 5.4 Single-Byte (8-Bit) Encodings 121 5.5 Chinese, Japanese, and Korean Encodings 124 5.6 Addressing Characters 127 5.6.1 Escape Sequences 127 5.6.2 Character References 128 6 Font Handling 131 6.1 Font Formats 131 6.1.1 TrueType Fonts 131 6.1.2 OpenType Fonts 131 6.1.3 WOFF Fonts 132 4 Contents 6.1.4 SVG Fonts 132 6.1.5 PostScript Type 1 Fonts 133 6.1.6 SING Fonts (Glyphlets) 133 6.1.7 CEF Fonts 134 6.1.8 Type 3 Fonts 134 6.2 Unicode Characters and Glyphs 136 6.2.1 Glyph IDs 136 6.2.2 Unicode Mappings for Glyphs 136 6.2.3 Unicode Control Characters 138 6.3 The Text Processing Pipeline 139 6.3.1 Normalizing Input Strings to Unicode 139 6.3.2 Converting Unicode Values to Glyph IDs 140 6.3.3 Transforming Glyph IDs 141 6.4 Loading Fonts 142 6.4.1 Selecting an Encoding for Text Fonts 142 6.4.2 Selecting an Encoding for symbolic Fonts 144 6.4.3 Example: Selecting a Glyph from the Wingdings Symbol Font 146 6.4.4 Searching for Fonts 149 6.4.5 Host Fonts on Windows and OS X/macOS 153 6.4.6 Fallback Fonts 155 6.5 Font Embedding and Subsetting 159 6.5.1 Font Embedding 159 6.5.2 Font Subsetting 160 6.6 Querying Font Information 162 6.6.1 Font-independent Encoding, Unicode, and Glyph Name Queries 162 6.6.2 Font-specific Encoding, Unicode, and Glyph Name Queries 163 6.6.3 Querying Codepage Coverage and Fallback Fonts 164 7 Text Output 167 7.1 Text Output Methods 167 7.2 Font Metrics and Text Variations 168 7.2.1 Font and Glyph Metrics 168 7.2.2 Kerning 169 7.2.3 Text Variations 170 7.3 OpenType Layout Features 172 7.3.1 Supported OpenType Layout Features 172 7.3.2 OpenType Layout Features with Textlines and Textflows 174 7.4 Complex Script Output 178 7.4.1 Complex Scripts 178 7.4.2 Script and Language 180 7.4.3 Complex Script Shaping 181 7.4.4 Bidirectional Formatting 182 7.4.5 Arabic Text Formatting 184 7.5 Chinese, Japanese, and Korean Text Output 186 7.5.1 Using TrueType and OpenType CJK Fonts 186 7.5.2 EUDC and SING Fonts for Gaiji Characters 187 Contents 5 7.5.3 OpenType Layout Features for advanced CJK Text Output 188 7.5.4 Unicode Variation Selectors and Variation Sequences 190 7.5.5 Standard CJK Fonts 191 8 Importing Images, SVG Graphics and PDF Pages 193 8.1 Raster Images 193 8.1.1 Basic Image Handling 193 8.1.2 Supported Image File Formats 195 8.1.3 Clipping Paths 198 8.1.4 Image Transparency with Alpha Channels and Stencil Masks 199 8.1.5 Colorize Images with Spot or DeviceN Color 201 8.2 SVG Graphics 203 8.2.1 Supported SVG Flavors 203 8.2.2 SVG Processing Considerations 203 8.2.3 Visible Size of SVG Graphics 204 8.2.4 Font Selection 205 8.2.5 Dealing with missing Fonts and missing Glyphs 207 8.2.6 SVG Color Extension 208 8.2.7 SVG Contents beyond Vector Graphics and Text 210 8.2.8 Unsupported SVG Features 211 8.3 Importing PDF Pages with PDI 214 8.3.1 PDI Features and Applications 214 8.3.2 Using PDFlib+PDI 214 8.3.3 Document and Page-related Checks 216 8.3.4 Specific Aspects of imported PDF Documents 216 8.4 Placing Images, Graphics, and imported PDF Pages 219 8.4.1 Simple Object Placement 219 8.4.2 Placing an Object at a Point or Line or in a Box 219 8.4.3 Orientating an Object 221 8.4.4 Rotating an Object 222 8.4.5 Adjusting the Page Size 223 8.4.6 Querying Information about placed Images and PDF Pages 224 9 Text and Table Formatting 227 9.1 Placing and Fitting Textlines 227 9.1.1 Simple Textline Placement 227 9.1.2 Positioning Text in a Box 228 9.1.3 Fitting Text into a Box 229 9.1.4 Aligning Text at a Character 231 9.1.5 Placing a Stamp 232 9.1.6 Using Leaders 232 9.1.7 Text on a Path 233 9.1.8 Shadowed Text 234 9.1.9