Pdflib Tutorial 9.0.1
Total Page:16
File Type:pdf, Size:1020Kb
ABC PDFlib, PDFlib+PDI, PPS A library for generating PDF on the fly PDFlib 9.0.1 Tutorial For use with C, C++, Cobol, COM, Java, .NET, Objective-C, Perl, PHP, Python, REALbasic/Xojo, RPG, Ruby Copyright © 1997–2013 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 tech.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, 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 Using PDFlib on EBCDIC-based Platforms 67 3.2 Page Descriptions 68 3.2.1 Coordinate Systems 68 3.2.2 Page Size 70 3.2.3 Direct Paths and Path Objects 71 Contents 3 3.2.4 Templates (Form XObjects) 73 3.2.5 Referenced Pages from an external PDF Document 74 3.3 Encrypted PDF 76 3.3.1 PDF Security Features 76 3.3.2 Applying PDF Security with PDFlib 79 3.4 Advanced Color Handling 81 3.4.1 Color Management with ICC Profiles 81 3.4.2 Pantone, HKS, and custom Spot Colors 84 3.4.3 Patterns and Smooth Shadings 87 4 Unicode and Legacy Encodings 89 4.1 Important Unicode Concepts 89 4.2 Unicode-capable Language Bindings 91 4.2.1 Language Bindings with native Unicode Strings 91 4.2.2 Language Bindings with UTF-8 Support 91 4.3 Non-Unicode-capable Language Bindings 93 4.4 Single-Byte (8-Bit) Encodings 97 4.5 Chinese, Japanese, and Korean Encodings 100 4.6 Addressing Characters 103 4.6.1 Escape Sequences 103 4.6.2 Character References 104 5 Font Handling 107 5.1 Font Formats 107 5.1.1 TrueType Fonts 107 5.1.2 OpenType Fonts 107 5.1.3 WOFF Fonts 108 5.1.4 SVG Fonts 108 5.1.5 PostScript Type 1 Fonts 108 5.1.6 SING Fonts (Glyphlets) 109 5.1.7 CEF Fonts 110 5.1.8 Type 3 Fonts 110 5.2 Unicode Characters and Glyphs 112 5.2.1 Glyph IDs 112 5.2.2 Unicode Mappings for Glyphs 112 5.2.3 Unicode Control Characters 114 5.3 The Text Processing Pipeline 115 5.3.1 Normalizing Input Strings to Unicode 115 5.3.2 Converting Unicode Values to Glyph IDs 116 5.3.3 Transforming Glyph IDs 117 5.4 Loading Fonts 118 5.4.1 Selecting an Encoding for Text Fonts 118 5.4.2 Selecting an Encoding for symbolic Fonts 120 5.4.3 Example: Selecting a Glyph from the Wingdings Symbol Font 122 5.4.4 Searching for Fonts 125 4 Contents 5.4.5 Host Fonts on Windows and OS X 129 5.4.6 Fallback Fonts 131 5.5 Font Embedding and Subsetting 135 5.5.1 Font Embedding 135 5.5.2 Font Subsetting 136 5.6 Querying Font Information 138 5.6.1 Font-independent Encoding, Unicode, and Glyph Name Queries 138 5.6.2 Font-specific Encoding, Unicode, and Glyph Name Queries 139 5.6.3 Querying Codepage Coverage and Fallback Fonts 140 6 Text Output 143 6.1 Text Output Methods 143 6.2 Font Metrics and Text Variations 144 6.2.1 Font and Glyph Metrics 144 6.2.2 Kerning 145 6.2.3 Text Variations 146 6.3 OpenType Layout Features 148 6.3.1 Supported OpenType Layout Features 148 6.3.2 OpenType Layout Features with Textlines and Textflows 150 6.4 Complex Script Output 154 6.4.1 Complex Scripts 154 6.4.2 Script and Language 156 6.4.3 Complex Script Shaping 157 6.4.4 Bidirectional Formatting 158 6.4.5 Arabic Text Formatting 160 6.5 Chinese, Japanese, and Korean Text Output 162 6.5.1 Using TrueType and OpenType CJK Fonts 162 6.5.2 EUDC and SING Fonts for Gaiji Characters 163 6.5.3 OpenType Layout Features for advanced CJK Text Output 164 6.5.4 Unicode Variation Selectors and Variation Sequences 166 6.5.5 Standard CJK Fonts 167 7 Importing Images, SVG Graphics and PDF Pages 169 7.1 Raster Images 169 7.1.1 Basic Image Handling 169 7.1.2 Supported Image File Formats 171 7.1.3 Clipping Paths 174 7.1.4 Image Masks and Transparency 175 7.1.5 Colorizing Images 177 7.2 SVG Graphics 179 7.2.1 Supported SVG Flavors 179 7.2.2 SVG Processing Considerations 179 7.2.3 Size of SVG Graphics 180 7.2.4 Font Selection 181 7.2.5 Dealing with missing Fonts and missing Glyphs 183 Contents 5 7.2.6 SVG Contents beyond Vector Graphics and Text 184 7.2.7 Unsupported SVG Features 185 7.3 Importing PDF Pages with PDI 187 7.3.1 PDI Features and Applications 187 7.3.2 Using PDFlib+PDI 187 7.3.3 Document and Page-related Checks 189 7.3.4 Specific Aspects of imported PDF Documents 189 7.4 Placing Images, Graphics, and imported PDF Pages 192 7.4.1 Simple Object Placement 192 7.4.2 Placing an Object at a Point or Line or in a Box 192 7.4.3 Orientating an Object 194 7.4.4 Rotating an Object 195 7.4.5 Adjusting the Page Size 196 7.4.6 Querying Information about placed Images and PDF Pages 197 8 Text and Table Formatting 199 8.1 Placing and Fitting Textlines 199 8.1.1 Simple Textline Placement 199 8.1.2 Positioning Text in a Box 200 8.1.3 Fitting Text into a Box 201 8.1.4 Aligning Text at a Character 203 8.1.5 Placing a Stamp 204 8.1.6 Using Leaders 204 8.1.7 Text on a Path 205 8.1.8 Shadowed Text 206 8.2 Multi-Line Textflows 207 8.2.1 Placing Textflows in the Fitbox 208 8.2.2 Paragraph Formatting Options 210 8.2.3 Inline Option Lists and Macros 210 8.2.4 Tab Stops 213 8.2.5 Numbered Lists and Paragraph Spacing 214 8.2.6 Control Characters and Character Mapping 215 8.2.7 Hyphenation 218 8.2.8 Controlling the standard Linebreak Algorithm 218 8.2.9 Advanced script-specific Line Breaking 222 8.2.10 Wrapping Text around Paths and Images 223 8.3 Table Formatting 227 8.3.1 Placing a Simple Table 228 8.3.2 Contents of a Table Cell 231 8.3.3 Table and Column Widths 233 8.3.4 Mixed Table Contents 234 8.3.5 Table Instances 237 8.3.6 Table Formatting