Pdflib Tutorial 9.0.7
Total Page:16
File Type:pdf, Size:1020Kb
ABC PDFlib, PDFlib+PDI, PPS A library for generating PDF on the fly PDFlib 9.0.7 Tutorial For use with C, C++, Cobol, COM, Java, .NET, Objective-C, Perl, PHP, Python, REALbasic/Xojo, RPG, Ruby Copyright © 1997–2016 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-2012 Glenn Randers-Pehrson Zlib compression library, Copyright © 1995-2012 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 Cryptographic software, Copyright © 1998-2002 The OpenSSL Project (www.openssl.org) Expat XML parser, Copyright © 1998, 1999, 2000 Thai Open Source Software Center Ltd 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? 19 1.4 Features in PDFlib 21 1.5 Additional Features in PDFlib+PDI 24 1.6 Additional Features in PPS 25 1.7 Availability of Features in different Products 26 2 PDFlib Language Bindings 27 2.1 C Binding 27 2.2 C++ Binding 30 2.3 COM Binding 33 2.4 Cobol Binding 38 2.5 Java Binding 39 2.6 .NET Binding 42 2.7 Objective-C Binding 45 2.8 Perl Binding 47 2.9 PHP Binding 49 2.10 Python Binding 51 2.11 REALbasic/Xojo Binding 52 2.12 RPG Binding 53 2.13 Ruby Binding 55 3 Creating PDF Documents 57 3.1 General PDFlib Programming Aspects 57 3.1.1 Exception Handling 57 3.1.2 The PDFlib Virtual File System (PVF) 59 3.1.3 Resource Configuration and File Search 60 3.1.4 Generating PDF Documents in Memory 65 3.1.5 Maximum Size of PDF Documents and other Limits 66 3.1.6 Multi-threaded Programming 67 3.1.7 Using PDFlib on EBCDIC-based Platforms 67 3.2 Page Descriptions 69 3.2.1 Coordinate Systems 69 3.2.2 Page Size 71 Contents 3 3.2.3 Direct Paths and Path Objects 72 3.2.4 Templates (Form XObjects) 74 3.2.5 Referenced Pages from an external PDF Document 75 3.3 PDF Password Security 77 3.3.1 Password Security in PDF 77 3.3.2 Password-Protecting PDF Documents with PDFlib 80 3.4 Advanced Color Handling 82 3.4.1 Color Management with ICC Profiles 82 3.4.2 Pantone, HKS, and custom Spot Colors 85 3.4.3 Patterns and Smooth Shadings 88 4 Unicode and Legacy Encodings 91 4.1 Important Unicode Concepts 91 4.2 Unicode-capable Language Bindings 93 4.2.1 Language Bindings with native Unicode Strings 93 4.2.2 Language Bindings with UTF-8 Support 93 4.3 Non-Unicode-capable Language Bindings 95 4.4 Single-Byte (8-Bit) Encodings 99 4.5 Chinese, Japanese, and Korean Encodings 102 4.6 Addressing Characters 105 4.6.1 Escape Sequences 105 4.6.2 Character References 106 5 Font Handling 109 5.1 Font Formats 109 5.1.1 TrueType Fonts 109 5.1.2 OpenType Fonts 109 5.1.3 WOFF Fonts 110 5.1.4 SVG Fonts 110 5.1.5 PostScript Type 1 Fonts 111 5.1.6 SING Fonts (Glyphlets) 111 5.1.7 CEF Fonts 112 5.1.8 Type 3 Fonts 112 5.2 Unicode Characters and Glyphs 114 5.2.1 Glyph IDs 114 5.2.2 Unicode Mappings for Glyphs 114 5.2.3 Unicode Control Characters 116 5.3 The Text Processing Pipeline 117 5.3.1 Normalizing Input Strings to Unicode 117 5.3.2 Converting Unicode Values to Glyph IDs 118 5.3.3 Transforming Glyph IDs 119 5.4 Loading Fonts 120 5.4.1 Selecting an Encoding for Text Fonts 120 5.4.2 Selecting an Encoding for symbolic Fonts 122 5.4.3 Example: Selecting a Glyph from the Wingdings Symbol Font 124 4 Contents 5.4.4 Searching for Fonts 127 5.4.5 Host Fonts on Windows and OS X/macOS 131 5.4.6 Fallback Fonts 133 5.5 Font Embedding and Subsetting 137 5.5.1 Font Embedding 137 5.5.2 Font Subsetting 138 5.6 Querying Font Information 140 5.6.1 Font-independent Encoding, Unicode, and Glyph Name Queries 140 5.6.2 Font-specific Encoding, Unicode, and Glyph Name Queries 141 5.6.3 Querying Codepage Coverage and Fallback Fonts 142 6 Text Output 145 6.1 Text Output Methods 145 6.2 Font Metrics and Text Variations 146 6.2.1 Font and Glyph Metrics 146 6.2.2 Kerning 147 6.2.3 Text Variations 148 6.3 OpenType Layout Features 150 6.3.1 Supported OpenType Layout Features 150 6.3.2 OpenType Layout Features with Textlines and Textflows 152 6.4 Complex Script Output 156 6.4.1 Complex Scripts 156 6.4.2 Script and Language 158 6.4.3 Complex Script Shaping 159 6.4.4 Bidirectional Formatting 160 6.4.5 Arabic Text Formatting 162 6.5 Chinese, Japanese, and Korean Text Output 164 6.5.1 Using TrueType and OpenType CJK Fonts 164 6.5.2 EUDC and SING Fonts for Gaiji Characters 165 6.5.3 OpenType Layout Features for advanced CJK Text Output 166 6.5.4 Unicode Variation Selectors and Variation Sequences 168 6.5.5 Standard CJK Fonts 169 7 Importing Images, SVG Graphics and PDF Pages 171 7.1 Raster Images 171 7.1.1 Basic Image Handling 171 7.1.2 Supported Image File Formats 173 7.1.3 Clipping Paths 176 7.1.4 Image Masks and Transparency 177 7.1.5 Colorizing Images 179 7.2 SVG Graphics 180 7.2.1 Supported SVG Flavors 180 7.2.2 SVG Processing Considerations 180 7.2.3 Size of SVG Graphics 181 7.2.4 Font Selection 182 Contents 5 7.2.5 Dealing with missing Fonts and missing Glyphs 184 7.2.6 SVG Contents beyond Vector Graphics and Text 185 7.2.7 Unsupported SVG Features 186 7.3 Importing PDF Pages with PDI 190 7.3.1 PDI Features and Applications 190 7.3.2 Using PDFlib+PDI 190 7.3.3 Document and Page-related Checks 192 7.3.4 Specific Aspects of imported PDF Documents 192 7.4 Placing Images, Graphics, and imported PDF Pages 195 7.4.1 Simple Object Placement 195 7.4.2 Placing an Object at a Point or Line or in a Box 195 7.4.3 Orientating an Object 197 7.4.4 Rotating an Object 198 7.4.5 Adjusting the Page Size 199 7.4.6 Querying Information about placed Images and PDF Pages 200 8 Text and Table Formatting 203 8.1 Placing and Fitting Textlines 203 8.1.1 Simple Textline Placement 203 8.1.2 Positioning Text in a Box 204 8.1.3 Fitting Text into a Box 205 8.1.4 Aligning Text at a Character 207 8.1.5 Placing a Stamp 208 8.1.6 Using Leaders 208 8.1.7 Text on a Path 209 8.1.8 Shadowed Text 210 8.1.9 Watermarks which can be edited in Acrobat 211 8.2 Multi-Line Textflows 213 8.2.1 Placing Textflows in the Fitbox 214 8.2.2 Paragraph Formatting Options 216 8.2.3 Inline Option Lists and Macros 216 8.2.4 Tab Stops 219 8.2.5 Numbered Lists and Paragraph Spacing 220 8.2.6 Control Characters and Character Mapping 221 8.2.7 Hyphenation 224 8.2.8 Widow and Orphan Lines 225 8.2.9 Controlling the standard Linebreak Algorithm 225 8.2.10 Advanced script-specific Line Breaking 228 8.2.11 Wrapping Text around Paths and Images 229 8.3 Table Formatting 233 8.3.1 Placing a Simple