PDFlib Manual D

PDFlib GmbH München
www.pdflib.com
Referenzhandbuch
®
Eine Bibliothek für dynamisches PDF

Version 6.0.3
Allgemeine Ausgabe für

Cobol, C, C++, Java, Perl,
PHP, Python, RPG, Ruby und Tcl
Copyright © 1997–2006 PDFlib GmbH und Thomas Merz. Alle Rechte vorbehalten.
PDFlib-Benutzer sind berechtigt, dieses Handbuch zu internen Zwecken gedruckt oder digital zu vervielfäl-
tigen.
PDFlib GmbH
Tal 40, 80331 München, Deutschland
www.pdflib.com
Tel. +49 • 89 • 29 16 46 87
Fax +49 • 89 • 29 16 46 86
Bei Fragen können Sie die PDFlib-Mailing-Liste abonnieren und sich deren Archiv ansehen unter:
groups.yahoo.com/group/pdflib.
Vertriebsinformationen: sales@pdflib.com
Support für Inhaber einer kommerziellen PDFlib-Lizenz: support@pdflib.com (geben Sie bitte immer Ihre
Lizenznummer an)
Der Inhalt dieser Dokumentation wurde mit größter Sorgfalt zusammengestellt. PDFlib GmbH gibt jedoch
keine Gewähr oder Garantie hinsichtlich der Richtigkeit oder Genauigkeit der Angaben in dieser Dokumen-
tation und übernimmt keinerlei juristische Verantwortung oder Haftung für Schäden, die durch Fehler in
dieser Dokumentation entstehen. Alle Warenbezeichnungen werden ohne Gewährleistung der freien Ver-
wendbarkeit benutzt und sind möglicherweise eingetragene Warenzeichen.
PDFlib und das PDFlib-Logo sind eingetragene Warenzeichen der PDFlib GmbH. PDFlib-Lizenznehmer sind
dazu berechtigt, den Namen PDFlib und das PDFlib-Logo in ihrer Produktdokumentation zu verwenden.
Dies ist jedoch nicht zwingend erforderlich.
Adobe, Acrobat und PostScript sind Warenzeichen von Adobe Systems Inc. AIX, IBM, OS/390, WebSphere,
iSeries und zSeries sind Warenzeichen von International Business Machines Corporation. ActiveX,
Microsoft, OpenType und Windows sind Warenzeichen von Microsoft Corporation. Apple, Macintosh und
TrueType sind Warenzeichen von Apple Computer, Inc. Unicode und das Unicode-Logo sind Warenzeichen
von Unicode, Inc. Unix ist ein Warenzeichen von The Open Group. Java und Solaris sind Warenzeichen von
Sun Microsystems, Inc. HKS ist eine eingetragene Marke des HKS Warenzeichenverbands e.V.: Hostmann-
Steinberg, K+E, Schmincke. Die Namen von anderen Produkten und Diensten können Warenzeichen von
Unternehmen oder Organisationen sein, die hier nicht angeführt sind.
Die in der Software oder Benutzerdokumentation angezeigten PANTONE®-Farben stimmen nicht unbe-
dingt mit den PANTONE-Standards überein. Die genaue Farbe können Sie in den PANTONE-Farbtafeln
nachschlagen. PANTONE® und andere Warenzeichen von Pantone, Inc. sind Eigentum von Pantone, Inc. ©
Pantone, Inc., 2003.
Pantone, Inc. ist Copyright-Inhaber der Farbdaten und/oder Software, die von PDFlib GmbH ausschließlich
zur Weitergabe und zum Gebrauch mit der PDFlib-Software lizenziert wurde. Die PANTONE-Farbdaten
und/oder -Software dürfen nur zur Ausführung der PDFlib-Software auf eine Festplatte oder in den Spei-
cher kopiert werden.
PDFlib enthält modifizierte Bestandteile folgender Software anderer Hersteller:
ICClib, Copyright © 1997-2002 Graeme W. Gill
PNG Image Reference Library (libpng), Copyright © 1998, 1999, 2000 Glenn Randers-Pehrson
Zlib Compression Library, Copyright © 1995-1998 Jean-loup Gailly und Mark Adler
TIFFlib Image Library, Copyright © 1988-1997 Sam Leffler, Copyright © 1991-1997 Silicon Graphics, Inc.
Kryptografische Software von Eric Young, Copyright © 1995-1998 Eric Young (eay@cryptsoft.com)
JPEG-Software der Indenpendent JPEG Group, Copyright © 1991-1998, Thomas G. Lane
PDFlib enthält den Message-Digest-Algorithmus MD5 von RSA Security, Inc.
Autor: Thomas Merz

Grafiken und Design: Alessio Leonardi
Deutsche Übersetzung: Katja Schnelle Romaus
Qualitätskontrolle (Handbuch): Katja Schnelle Romaus, Kurt Stützer
Qualitätskontrolle (Software): ein paar tausend Freiwillige
Inhaltsverzeichnis
0 Anwendung des PDFlib-Lizenzschlüssels 9
1 Einführung 13
1.1 Programmierung mit PDFlib 13
1.2 Die wichtigsten neuen Funktionen von PDFlib 6 15
1.3 Funktionalität von PDFlib 17
1.4 Verfügbarkeit der Funktionen in den Produkten 19
2 Sprachbindungen von PDFlib 21

2.1 Übersicht 21
2.2 Cobol-Sprachbindung 22
2.2.1 Besondere Hinweise für Cobol 22
2.2.2 Das Beispiel »Hello world« in Cobol 23
2.3 COM-Sprachbindung 26
2.4 C-Sprachbindung 26
2.4.1 Verfügbarkeit und besondere Hinweise zu C 26
2.4.2 Das Beispiel »Hello world« in C 26
2.4.3 Einsatz von PDFlib als DLL, die zur Laufzeit geladen wird 27
2.4.4 Fehlerbehandlung in C 28
2.4.5 Speicherverwaltung in C 29
2.4.6 Unicode in der C-Sprachbindung 30
2.5 C++-Sprachbindung 30
2.5.1 Verfügbarkeit und besondere Hinweise zu C++ 30
2.5.2 Das Beispiel »Hello world« in C++ 30
2.5.3 Fehlerbehandlung in C++ 31
2.5.4 Speicherverwaltung in C++ 32
2.5.5 Unicode in der C++-Sprachbindung 32
2.6 Java-Sprachbindung 32
2.6.1 Installation der Java-Edition von PDFlib 32
2.6.2 Das Beispiel »Hello world« in Java 34
2.6.3 Fehlerbehandlung in Java 35
2.7 .NET-Sprachbindung 35
2.8 Perl-Sprachbindung 35
2.8.1 Installation der PDFlib-Perl-Edition 35
2.8.2 Das Beispiel »Hello world« in Perl 36
2.8.3 Fehlerbehandlung in Perl 37
2.9 PHP-Sprachbindung 37
2.9.1 Installation der PDFlib-Edition für PHP 37
2.9.2 Das Beispiel »Hello world« in PHP 38
Inhaltsverzeichnis 3
2.9.3 Fehlerbehandlung in PHP 40
2.10 Python-Sprachbindung 41
2.10.1 Installation der Python-Edition von PDFlib 41
2.10.2 Das Beispiel »Hello world« in Python 41
2.10.3 Fehlerbehandlung in Python 41
2.11 REALbasic-Sprachbindung 42
2.12 RPG-Sprachbindung 42
2.12.1 Kompilieren und Binden von RPG-Programmen für PDFlib 42
2.12.2 Das Beispiel »Hello world« in RPG 43
2.12.3 Fehlerbehandlung in RPG 44
2.13 Ruby-Sprachbindung 46
2.13.1 Installation der Ruby-Edition von PDFlib 46
2.13.2 Das Beispiel »Hello world« in Ruby 46
2.13.3 Fehlerbehandlung in Ruby 47
2.13.4 Ruby on Rails 47
2.14 Tcl-Sprachbindung 48
2.14.1 Installation der PDFlib-Tcl-Edition 48
2.14.2 Das Beispiel »Hello world« in Tcl 48
2.14.3 Fehlerbehandlung in Tcl 49
3 PDFlib-Programmierung 51
3.1 Allgemeine Aspekte 51
3.1.1 PDFlib-Programmstruktur und Geltungsbereich von Funktionen 51
3.1.2 Parameter 51
3.1.3 Behandlung von Ausnahmen (Exceptions) 52
3.1.4 Das PDFlib Virtual File System (PVF) 55
3.1.5 Ressourcenkonfiguration und Dateisuche 56
3.1.6 Erzeugen von PDF-Dokumenten im Arbeitsspeicher 59
3.1.7 Einsatz von PDFlib auf EBCDIC-Systemen 60
3.1.8 Unterstützung für große Dateien 61
3.2 Seitenbeschreibungen 62
3.2.1 Koordinatensysteme 62
3.2.2 Höchstwerte für Seiten und Koordinaten 64
3.2.3 Pfade 66
3.2.4 Templates 67
3.3 Farbe 69
3.3.1 Farben und Farbräume 69
3.3.2 Füllmuster und Farbverläufe 69
3.3.3 Schmuckfarben 70
3.3.4 Colormanagement und ICC-Profile 73
3.4 Hypertext-Elemente 77
3.4.1 Beispiele zur Erstellung von Hypertext-Elementen 77
3.4.2 Formatierungsoptionen für Textfelder 80
4 Inhaltsverzeichnis
4 Textausgabe 83
4.1 Übersicht über Schriften und Zeichensätze 83
4.1.1 Unterstützte Fontformate 83
4.1.2 Zeichensätze 84
4.1.3 Unicode-Unterstützung 85
4.2 Fontformate im Detail 87
4.2.1 Unterstützung von Systemschriften auf Windows und Mac 87
4.2.2 PostScript-Fonts 88
4.2.3 TrueType- und OpenType-Fonts 89
4.2.4 Benutzerdefinierte Schriften (Type-3-Fonts) 91
4.3 Schrifteinbettung und Schriftuntergruppen 93
4.3.1 Wie PDFlib nach Fonts sucht 93
4.3.2 Schrifteinbettung 94
4.3.3 Bildung von Fontuntergruppen (Subsetting) 96
4.4 Zeichensätze 98
4.4.1 8-Bit-Zeichensätze 98
4.4.2 Symbolschriften und fontspezifische Zeichensätze 102
4.4.3 Glyph-ID-Adressierung für TrueType- und OpenType-Fonts 103
4.4.4 Das Eurozeichen 103
4.5 Unicode-Unterstützung 105
4.5.1 Unicode für Seitenbeschreibungen und Hypertext 105
4.5.2 Content-Strings, Hypertext-Strings und Name-Strings 106
4.5.3 Stringbehandlung in Unicode-fähigen Sprachen 107
4.5.4 String-Behandlung in nicht Unicode-fähigen Sprachen 108
4.5.5 Character-Referenzen 111
4.5.6 Unicode-kompatible Fonts 113
4.6 Textmetrik und Textvarianten 115
4.6.1 Font- und Zeichenmetriken 115
4.6.2 Kerning 116
4.6.3 Textvarianten 117
4.7 Chinesischer, japanischer und koreanischer Text 120
4.7.1 CJK-Unterstützung in Acrobat und PDF 120
4.7.2 Standard-CJK-Fonts und -CMaps 120
4.7.3 Benutzerspezifische CJK-Fonts 124
4.8 Platzieren und Einpassen von einzeiligem Text 128
4.8.1 Einfaches Platzieren von Text 128
4.8.2 Platzieren von Text in einer Box 129
4.8.3 Ausrichten von Text 130
4.9 Mehrzeilige Textflüsse 131
4.9.1 Platzierung eines Textflusses in der Fitbox 132
4.9.2 Optionen für die Absatzformatierung 133
4.9.3 Inline-Optionen und Makros 134
4.9.4 Tabulatoren 137
4.9.5 Nummerierte Listen 137
4.9.6 Steuerzeichen, Zeichenersetzung und Symbolfonts 139
4.9.7 Trennung 141
4.9.8 Steuerung des Algorithmus für den Zeilenumbruch 142
4.9.9 Formatierung von CJK-Text in Textflüssen 145
5 Import und Platzierung von Objekten 147

5.1 Import von Rasterbildern 147
5.1.1 Grundlegende Vorgehensweise 147
5.1.2 Unterstützte Rasterbildformate 148
5.1.3 Bildmasken und Transparenz 151
5.1.4 Einfärben von Bildern 153
5.1.5 Mehrseitige Bilddateien 154
5.1.6 OPI-Unterstützung 154
5.2 Import von PDF-Seiten mit PDI (PDF Import Library) 155
5.2.1 PDI-Funktionen und -Anwendungen 155
5.2.2 Einsatz von PDI-Funktionen mit PDFlib 155
5.2.3 Importierbare PDF-Dokumente 157
5.3 Platzieren von Bildern und importierten PDF-Seiten 159
5.3.1 Skalierung, Ausrichtung und Drehung 159
5.3.2 Anpassen der Seitengröße 161
6 Variable Daten und Blöcke 165

6.1 Installation des Block-Plugins 165
6.2 Überblick über das Blockkonzept von PDFlib 167
6.2.1 Vollständige Trennung von Dokumentdesign und Programmcode 167
6.2.2 Blockeigenschaften 168
6.2.3 Was spricht gegen PDF-Formularfelder? 169
6.3 Anlegen von PDFlib-Blöcken 171
6.3.1 Interaktive Blockerzeugung mit dem Block-Plugin 171
6.3.2 Bearbeiten von Blockeigenschaften 174
6.3.3 Kopieren von Blöcken zwischen Seiten und Dokumenten 175
6.3.4 Konvertieren von PDF-Formularfeldern in PDFlib-Blöcke 176
6.4 Standardeigenschaften zur automatischen Verarbeitung 180
6.4.1 Allgemeine Eigenschaften 180
6.4.2 Textspezifische Eigenschaften 182
6.4.3 Rasterbildspezifische Eigenschaften 187
6.4.4 PDF-spezifische Eigenschaften 187
6.4.5 Selbstdefinierte Eigenschaften 188
6.5 Abfragen von Blocknamen und -eigenschaften 189
6.6 Spezifikation für PDFlib-Blöcke 191
6.6.1 PDF-Objektstruktur für PDFlib-Blöcke 191
6.6.2 Erzeugen von PDFlib-Blöcken mit pdfmarks 193
7 Erstellung verschiedener PDF-Varianten 195
7.1 Acrobat und PDF-Versionen 195
7.2 Verschlüsseltes PDF 197
7.2.1 Stärken und Schwächen der Sicherheitsfunktionen von PDF 197
7.2.2 Schützen von Dokumenten mit PDFlib 198
7.3 Web-Optimiertes (Linearisiertes) PDF 200
7.4 PDF/X 201
7.4.1 PDF/X-Standards 201
7.4.2 Erzeugung PDF/X-kompatibler Ausgabe 202
7.4.3 Import von PDF/X-Dokumenten mit PDI 205
7.5 Tagged PDF 207
7.5.1 Erzeugung von Tagged PDF mit PDFlib 207
7.5.2 Erzeugung von Tagged-PDF-Textausgabe und -Textflüssen 209
7.5.3 Aktivierung von Elementen für komplexe Layouts 210
7.5.4 Verwendung von Tagged PDF in Acrobat 213
8 API-Referenz für PDFlib, PDI und PPS 217

8.1 Datentypen und Namenskonventionen 217
8.1.1 Datentypen in PDFlib 217
8.1.2 Optionslisten 218
8.2 Allgemeine Funktionen 222
8.2.1 Setup 222
8.2.2 Dokument und Seite 225
8.2.3 Parameterbehandlung 236
8.2.4 Virtuelles Dateisystem (PDFlib Virtual File System, PVF) 237
8.2.5 Ausnahmebehandlung 239
8.2.6 Hilfsfunktionen 240
8.3 Textfunktionen 242
8.3.1 Fontbehandlung 242
8.3.2 Benutzerdefinierte (Type 3) Schriften 246
8.3.3 Definition von Zeichensätzen (Encodings) 248
8.3.4 Einfache Textausgabe 249
8.3.5 Mehrzeilige Textausgabe mit Textflüssen 258
8.4 Grafikfunktionen 269
8.4.1 Funktionen für den Grafikzustand 269
8.4.2 Speichern und Wiederherstellen des Grafikzustands 272
8.4.3 Funktionen zur Transformation des Koordinatensystems 273
8.4.4 Explizite Grafikzustände 275
8.4.5 Pfadkonstruktion 276
8.4.6 Zeichnen und Beschneiden von Pfaden 280
8.4.7 Ebenenfunktionen 282
8.5 Farbfunktionen 286
8.5.1 Festlegen von Farbe und Farbraum 286
8.5.2 Füllmuster und Farbverläufe 290
8.6 Rasterbild- und Template-Funktionen 294
8.6.1 Rasterbilder 295
8.6.2 Templates 299
8.6.3 Piktogramme (Thumbnails) 302
8.7 Funktionen für den PDF-Import (PDI) 304
8.7.1 Dokument und Seite 304
8.7.2 Weitere Funktionen zur PDI-Verarbeitung 309
8.7.3 Parameterbehandlung 309
8.8 Blockfunktionen (PPS) 313
8.9 Hypertext-Funktionen 317
8.9.1 Aktionen 317
8.9.2 Benannte Ziele 321
8.9.3 Anmerkungen 323
8.9.4 Formularfelder 327
8.9.5 Lesezeichen 332
8.9.6 Dokumentinfofelder 334
8.9.7 Veraltete Hypertext-Parameter und Funktionen 335
8.10 Strukturfunktionen für Tagged PDF 338
A Literaturhinweise 341
B PDFlib-Kurzreferenz 343
C Änderungen an diesem Handbuch 348
Index 349
0 Anwendung des PDFlib-
Lizenzschlüssels
Alle Binärversionen von PDFlib, PDFlib+PDI und PPS, die von PDFlib GmbH angeboten
werden, sind als Evaluierungsversionen in vollem Funktionsumfang verwendbar, unab-
hängig davon, ob Sie eine kommerzielle Lizenz erworben haben oder nicht. Bei nicht li-
zenzierten Versionen wird jedoch quer über allen generierten Seiten der Demostempel
www.pdflib.com ausgegeben. Unternehmen, die an einer Lizenzierung von PDFlib inter-
essiert sind und den Demostempel in der Evaluierungsphase oder ersten Demos ver-
meiden möchten, können ihre Firmen- und Projektdaten mit einer kurzen Erläuterung
an sales@pdflib.com senden und einen temporären Lizenzschlüssel anfordern (wir be-
halten uns das Recht vor, einer Anforderung nicht nachzukommen, z.B. bei anonymen
Anfragen).
Nachdem Sie einen Lizenzschlüssel erworben haben, müssen Sie ihn anwenden,
damit der Demostempel auch tatsächlich unterdrückt wird. Sie können den Lizenz-
schlüssel zur Laufzeit mit einem PDFlib-Aufruf und einer vorbereiteten Lizenzdatei
oder (unter Windows) einem Registry-Schlüssel anwenden. Wenn Sie mit der Installati-
onsroutine von Windows arbeiten, können Sie bei der Produktinstallation einen (aber
nicht mehrere) Lizenzschlüssel eingeben.
Anwenden eines Lizenzschlüssels zur Laufzeit. Fügen Sie in Ihrem Skript oder Pro-
gramm eine Zeile ein, die den Lizenzschlüssel zur Laufzeit setzt. Der Parameter license
muss dabei unmittelbar nach der Instantiierung des PDFlib-Objekts gesetzt werden (das
heißt, nach PDF_new( ) oder einem entsprechenden Aufruf). Die Syntax hängt von der
jeweiligen Programmiersprache ab:
> In C und Python:
PDF_set_parameter(p, "license", "...Ihr Lizenzschlüssel...")
> In C++, Java, Ruby und PHP 5 mit objektorienterter Programmierschnittstelle:

p.set_parameter("license", "...Ihr Lizenzschlüssel...")
> In Perl, PHP 4 und PHP 5 mit prozeduraler Programmierschnittstelle:

PDF_set_parameter($p, "license", "...Ihr Lizenzschlüssel...")
> In RPG:
d licensekey s 20
d licenseval s 50
c eval licenseopt='license'+x'00'
c eval licenseval='...Ihr Lizenzschlüssel...'+x'00'
c callp PDF_set_parameter(p:licenseopt:licenseval)
> In Tcl:
PDF_set_parameter $p, "license", "...Ihr Lizenzschlüssel..."
9
Verwendung einer Lizenzdatei. Tragen Sie den oder die Lizenzschlüssel folgenderma-
ßen in eine Textdatei ein (alle PDFlib-Distributionen enthalten dafür die Vorlage
licensekeys.txt):
PDFlib license file 1.0
# Lizenzinformation für Produkte der PDFlib GmbH
PDFlib 6.0.3 ...Ihr Lizenzschlüssel...
Sie können Lizenzschlüssel für verschiedene Produkte der PDFlib GmbH in die Li-
zenzdatei aufnehmen, wobei jeder Schlüssel in einer eigenen Zeile stehen muss. Im
nächsten Schritt müssen Sie die Lizenzdatei bei PDFlib bekannt machen. Dazu gibt es
zwei Möglichkeiten: Entweder setzen Sie den Parameter licensefile unmittelbar nach
der Instantiierung des PDFlib-Objekts (das heißt, nach PDF_new( ) oder einem ent-
sprechenden Aufruf) mit einem Funktionsaufruf ähnlich dem folgenden:
> In C und Python:
PDF_set_parameter(p, "licensefile", "/path/to/licensekeys.txt")
> In C++, Java und PHP 5 mit objektorientierter Programmierschnittstelle:

p.set_parameter("licensefile", "/path/to/licensekeys.txt");
> In Perl, PHP 4 und PHP 5 mit prozeduraler Programmierschnittstelle :

PDF_set_parameter($p, "licensefile", "/path/to/licensekeys.txt");
> In Tcl:
PDF_set_parameter $p, "licensefile", "/path/to/licensekeys.txt"
Alternativ dazu setzen Sie die Umgebungsvariable PDFLIBLICENSEFILE auf Ihre Lizenzda-
tei. Unter Windows bewerkstelligen Sie dies in der Systemsteuerung. Unter Unix ver-
wenden Sie in etwa folgenden Befehl:
export PDFLIBLICENSEFILE=/path/to/license/file
Windows-Registry. Unter Windows können Sie den Namen der Lizenzdatei auch in fol-
genden Registry-Schlüssel eintragen:
HKLM\Software\PDFlib\PDFLIBLICENSEFILE
Beachten Sie, dass es sich bei PDFlib, PDFlib+PDI und PDFlib Personalization Server (PPS)
um verschiedene Produkte handelt, die unterschiedliche Lizenzschlüssel erfordern,
selbst wenn sie in einer einzigen Bibliothek/Komponente ausgeliefert werden. Die Seri-
ennummer von PPS gilt auch für PDFlib+PDI sowie PDFlib, die von PDFlib+PDI gilt auch
für PDFlib, aber nicht umgekehrt. Alle Lizenzschlüssel sind plattformabhängig und kön-
nen nur auf der Plattform eingesetzt werden, für die sie erworben wurden.
Eintragen mehrerer CPU-Schlüssel. Wenn Sie mehrere CPU-Lizenzen nicht in einer ein-
zigen, sondern in verschiedenen Bestellungen erworben haben, können Sie sie sukzessi-
ve in die Lizenzdatei eintragen. Auch die Funktion PDF_set_parameter( ) kann bei mehre-
ren Lizenzschlüsseln mehrmals aufgerufen werden. Über die Windows-Registry oder die
Windows-Installationsroutine lassen sich die Lizenzschlüssel dagegen nicht sukzessive
eintragen.
10 Kapitel 0: Anwendung des PDFlib-Lizenzschlüssels

Updates und Upgrades. Wenn Sie ein Update erworben haben, d.h. eine ältere durch
eine neuere Produktversion ersetzen, oder ein Upgrade durchführen, d.h. von PDFlib
auf PDFlib+PDI bzw. PPS oder von PDFlib+PDI auf PPS umsteigen, müssen Sie den neuen
Lizenzschlüssel anwenden, den Sie mit dem Update oder Upgrade erhalten haben. Der
alte Lizenzschlüssel darf dann nicht mehr zum Einsatz kommen.
Testen unlizenzierter Funktionen. Ohne Lizenzschlüssel lassen sich alle Funktionen

ohne Einschränkungen testen. Sobald Sie auf die Software einen für ein bestimmtes
Produkt gültigen Lizenzschlüssel anwenden, sind Funktionen höherer Kategorien nicht
mehr verfügbar. Nach der Installation eines gültigen PDFlib-Lizenzschlüssels beispiels-
weise stehen die PDI-Funktionen nicht mehr zum Test zur Verfügung. Genauso haben
Sie keinen Zugang zu den Personalisierungsfunktionen (Blockfunktionen), nachdem
der PDFlib+PDI-Lizenzschlüssel installiert ist.
Wurde bereits ein Lizenzschlüssel für ein Produkt installiert, können Sie ihn durch
den Pseudo-Lizenzstring "0" (null) ersetzen, um die Funktionalität einer höheren Pro-
duktkategorie zu testen. Damit werden alle deaktivierten Funktionen wieder aktiviert,
und der Demostempel erscheint wieder auf allen Seiten.
Lizenzvarianten. Es gibt verschiedene Lizenzierungsmöglichkeiten für die Verwen-

dung von PDFlib auf einem oder mehreren Servern und für die Weitergabe von PDFlib
in eigenen Produkten. Wir bieten außerdem Support- und Wartungsverträge. Einzelhei-
ten zur Lizenzierung und das PDFlib-Bestellformular finden Sie in der PDFlib-Distributi-
on. Bitte wenden Sie sich an uns, wenn Sie Fragen haben oder eine kommerzielle PDFlib-
Lizenz beziehen möchten:
PDFlib GmbH, Lizenzabteilung

Tal 40, D–80331 München
http://www.pdflib.com
Tel. +49 • 89 • 29 16 46 87
Fax +49 • 89 • 29 16 46 86
Bestellung: sales@pdflib.com
Support für PDFlib-Lizenznehmer: support@pdflib.com
11
1 Einführung
1.1 Programmierung mit PDFlib
Was ist PDFlib? PDFlib ist eine Bibliothek, mit der Sie Dateien im Portable Document
Format (PDF) von Adobe erstellen können. PDFlib fungiert als Backend für Ihre Pro-
gramme. Sie als Programmierer sind verantwortlich für die Verwaltung der zu verarbei-
tenden Daten, und PDFlib übernimmt die Generierung des PDF-Codes, der die Daten
grafisch darstellt. Die Formatierung und Anordnung der Text- und Grafikobjekte bleibt
dabei Ihre Aufgabe, Sie brauchen sich aber nicht um die Details des komplexen PDF-For-
mats zu kümmern.
> PDFlib bietet zahlreiche nützliche Funktionen zur Erstellung von Text, Vektorgrafik,
Rasterbildern und Hypertext-Elementen in PDF.
> PDFlib+PDI enthält neben allen PDFlib-Funktionen zusätzlich die PDF-Importbiblio-
thek PDI, mit der sich Seiten aus vorhandenen PDF-Dokumenten in die generierte
Ausgabe integrieren lassen.
> Der PDFlib Personalization Server (PPS) enthält neben PDFlib+PDI zusätzliche Funk-
tionen zum automatischen Füllen von PDFlib-Blöcken. Blöcke stellen Platzhalter auf
der Seite dar, die sich mit Text, Bildern oder PDF-Seiten füllen lassen. Sie können in-
teraktiv mit dem PDFlib-Block-Plugin für Adobe Acrobat (Mac oder Windows) er-
zeugt und automatisch mit PPS gefüllt werden. Das Plugin gehört zum Lieferumfang
von PPS.
Wie wird PDFlib eingesetzt? PDFlib ist auf verschiedensten Plattformen einsetzbar,
unter anderem auf Unix, Windows, Mac und EBCDIC-basierten Systemen wie IBM eSer-
ver iSeries und zSeries. PDFlib ist in der Programmiersprache C geschrieben, unterstützt
aber den Zugriff von verschiedensten anderen Programmiersprachen und -umgebun-
gen – den so genannten Sprachbindungen. Dazu gehören alle für eigenständige Appli-
kationen und Web-Anwendungen gängige Sprachen. Das Application Programming
Interface (API) ist einfach zu erlernen und für alle Sprachbindungen gleich. Derzeit wer-
den folgende Sprachbindungen unterstützt:
> COM für den Einsatz mit Visual Basic, Active Server Pages mit VBScript oder JScript,
Borland Delphi, Windows Script Host und anderen Umgebungen
> ANSI C
> ANSI C++
> Cobol (IBM eServer zSeries)
> Java inklusive Servlets
> .NET für den Einsatz mit C#, VB.NET, ASP.NET und anderen Umgebungen
> PHP
> Perl
> Python
> REALbasic
> RPG (IBM eServer iSeries)
> Ruby
> Tcl
1.1 Programmierung mit PDFlib 13

Wozu kann man PDFlib verwenden? PDFlib wird hauptsächlich dazu verwendet, im
World Wide Web aus eigener Software heraus dynamisch PDF zu generieren. Genauso
wie sich auf dem Web-Server dynamisch HTML-Seiten erzeugen lassen, können Sie ein
PDFlib-Programm schreiben, das dynamisch PDF erzeugt, zum Beispiel in Reaktion auf
Benutzereingaben oder auf Basis von Daten, die dynamisch aus der Datenbank des
Web-Servers abgerufen werden. Die Arbeitsweise von PDFlib bietet mehrere Vorteile:
> PDFlib kann unmittelbar in die Anwendung, die für die Datengenerierung zuständig
ist, integriert werden. Damit wird der umständliche Weg über »Anwendung – Post-
Script – Acrobat Distiller – PDF« überflüssig.
> Aufgrund dieser Vereinfachung bietet PDFlib die schnellstmögliche Methode zur Ge-
nerierung von PDF, die sich ideal für den Einsatz im Web eignet.
> Thread-Sicherheit, stabile Speicherverwaltung und Fehlerbehandlung erlauben die
Implementierung von Server-Anwendungen mit höchsten Performance-Anforde-
rungen.
> PDFlib ist für eine Vielzahl von Betriebssystemen und Entwicklungsumgebungen
verfügbar.
Anforderungen an den Einsatz von PDFlib. Mit PDFlib können Sie PDF generieren,
ohne sich vorher durch die PDF-Spezifikation zu quälen. Der Einsatz von PDFlib setzt
zwar kein Wissen über die technischen Einzelheiten des PDF-Formats voraus, ein allge-
meines Verständnis von PDF kann jedoch nicht schaden. Für einen optimalen Einsatz
von PDFlib sollte der Anwendungsprogrammierer mit dem Grafikmodell vertraut sein,
das PostScript (und damit auch PDF) zugrunde liegt. Aber auch ein Anwendungspro-
grammierer, der bereits mit einem Grafik-API für Bildschirmanzeige oder Ausdruck ge-
arbeitet hat, sollte sich anhand des vorliegenden Handbuchs ohne große Probleme auf
das PDFlib-API umstellen können.
Über dieses Handbuch. Das vorliegende Handbuch beschreibt das API von PDFlib. Es
beschreibt nicht, wie die Binärdateien für die Bibliothek erzeugt werden. Funktionen,
die hier nicht erwähnt werden, werden nicht unterstützt und sollten auch nicht ver-
wendet werden. In diesem Handbuch werden keine Acrobat-Funktionen erklärt. Diesbe-
zügliche Informationen finden Sie in der Literatur zu Acrobat und in den Literaturhin-
weisen am Ende dieses Handbuchs. Die PDFlib-Distribution enthält weitere Beispiele
zum Aufruf von PDFlib-Funktionen.
Beispielcode. Das vorliegende Handbuch enthält zahlreiche Codefragmente. PDFlib

unterstützt zwar ein breites Spektrum von Programmiersprachen, die Codebeispiele
werden aber nur in C gezeigt. Benutzer, die mit anderen Sprachen arbeiten, müssen sich
die Beispiele in ihre jeweilige Programmiersprache übersetzen.
14 Kapitel 1: Einführung
1.2 Die wichtigsten neuen Funktionen von PDFlib 6
Die folgende Liste gibt eine Übersicht über die wichtigsten neuen oder erweiterten
Funktionen von PDFlib 6.
Verbesserte Programmierung. Viele in früheren Versionen vorhandene Einschrän-

kungen sind aufgehoben. Zum Beispiel können Seiten jetzt in beliebiger Reihenfolge er-
stellt und neue Seiten zwischen vorhandenen eingefügt werden. Zu einer bereits vor-
handenen Seite kann weiterer Inhalt hinzugefügt werden.
Ebenen (Layer). Die in Acrobat 6 eingeführte Ebenenfunktion von PDF ist für CAD und
technische Anwendungen von Bedeutung, lässt sich aber auch für beeindruckende in-
teraktive Dokumente, mehrsprachige Dokumentation etc. nutzen. PDFlib unterstützt
alle in PDF 1.5 verfügbaren Ebenenfunktionen, auch solche, die in Acrobat nicht verfüg-
bar sind.
Unicode. PDFlib 6 bietet erweiterte Unicode-Unterstützung, so dass Unicode-Strings

nun in allen relevanten Bereichen zulässig sind. Dazu gehören Dateinamen, Seitenbe-
schreibungen, Hypertext, Formularfelder etc. Dies ist für Benutzer außerhalb Europas
und Nordamerikas von besonderem Interesse.
Textformatierung. Die neue Textflussformatierung bietet ein leistungsstarkes und

einfach zu bedienendes Mittel zur Formatierung von Text entsprechend zahlreicher
Optionen. Ob Unicode-Text, Flatter- und Blocksatz, beliebige Fontwechsel, mehrzeiliger
Hauptttext oder umfangreiche Tabellen in einer Rechnung – die neue Textflussfunk-
tion erledigt alle gängigen Formatierungsaufgaben.
Behandlung von Rasterbildern. Die Verarbeitung von TIFF-Bildern wurde um bislang

nicht unterstützte TIFF-Varianten erweitert, etwa JPEG-komprimierte TIFFs sowie die
Farbräume Lab und YCbCr. Da PDF 1.5 eine Farbtiefe von 16 Bit unterstützt, können TIFF-
und PNG-Bilder mit 16 Bit pro Farbkomponente nun auch mit 16-Bit-Farbe nach PDF
konvertiert werden. Ab PDFlib 6.0.2 werden JPEG2000-Bilder unterstützt.
Tagged PDF. Tagged PDF bildet eine entscheidende Voraussetzung, um die Barriere-
freiheit (Accessibility) von PDF gemäß Section 508 in den USA und ähnlichen Gesetzen
in anderen Ländern zu gewährleisten. In Deutschland gibt es diesbezüglich die »Verord-
nung zur Schaffung barrierefreier Informationstechnik nach dem Behindertengleich-
stellungsgesetz« (Barrierefreie Informationstechnik-Verordnung, BITV).
PDFlib ist die erste allgemein einsetzbare PDF-Bibliothek, die die Erzeugung von
Tagged PDF unterstützt. Mit den neuen Funktionen kann aus dynamischen Daten sehr
einfach Tagged PDF erzeugt werden. Alle Acrobat-Funktionen für Tagged PDF können
auf die generierte Ausgabe angewandt werden, zum Beispiel das Umfließen von Text,
die Sprachausgabe und der erweiterte Export in andere Formate wie RTF, HTML oder
XML. In Kombination mit der neuen Textflussformatierung lassen sich auch umfang-
reiche Texte schnell nach Tagged PDF übertragen. Es ist das erste Mal, dass dynamisch
auf dem Web-Server generiertes PDF den Vorschriften bezüglich Barrierefreiheit ge-
nügt.
1.2 Die wichtigsten neuen Funktionen von PDFlib 6 15

PDF/X für die Druckvorstufe. PDFlib 6 ist die erste Software auf dem Markt, die die Er-
zeugung und Verarbeitung von PDF-Dokumenten gemäß den aktuellen 2003 herausge-
gebenen PDF/X-Standards für die Druckvorstufe (PDF/X-1a:2003, PDF/X-2:2003 und
PDF/X-3:2003) unterstützt. PDF/X spielt beim Dateiaustausch in der Druckvorstufe eine
entscheidende Rolle. Weltweit führen immer mehr Verlage den PDF/X-Standard ein, um
einen zuverlässigen Datenaustausch in der grafischen Industrie zu gewährleisten. Die
neuen 2003 herausgegebenen Standards stellen eine Aktualisierung, Verbesserung und
Vereinheitlichung der vorhandenen PDF/X-Standards dar.
OPI für die Druckvorstufe. In manchen Arbeitsabläufen in der grafischen Industrie ist
noch der OPI-Standard aus der PostScript-Ära im Einsatz, bei dem OPI-Informationen in
PDF-Dokumente eingebettet werden. PDFlib 6 unterstützt dies durch Optionen zum
Hinzufügen von OPI-Informationen zu importierten Bildern.
Linearisiertes PDF. PDFlib 6 generiert linearisiertes PDF, das auch web-optimiertes PDF
genannt wird. Dies ermöglicht das seitenweise Herunterladen (auch Byteserving ge-
nannt) von PDF-Dokumenten im Webbrowser, so dass sie dem Benutzer unverzüglich
angezeigt werden.
PDFlib-Blöcke zur Verarbeitung variabler Daten. Die Benutzerschnittstelle des PDFlib-

Block-Plugins zur Erstellung von PDF-Templates wurde erweitert und vereinfacht. Mit
der neuen Textflussfunktion können Blöcke nun mit mehrzeiligem Text gefüllt werden.
Der PDFlib Personalization Server (PPS) ist damit nicht länger auf einfache Massenbrief-
anwendungen mit kurzen Textstücken beschränkt, sondern kann auch zu komplexen
Anwendungen mit anspruchsvoller Textformatierung herangezogen werden.
Formularfelder. Alle Typen von PDF-Formularfeldern können erstellt und mit Java-
Script oder anderen Aktionen versehen werden. Damit lassen sich PDF-Formulare dyna-
misch anhand von Benutzereingaben oder Datenbankinhalten erzeugen.
Hypertext. Die Hypertext-Funktionen von PDFlib wurden erweitert, so dass nun alle
PDF-Optionen für Lesezeichen, Aktionen und Anmerkungen unterstützt werden. Über
die Seitennummerierung können Seiten symbolische Namen oder römische Zahlen zu-
gewiesen werden, z.B. i, ii, iii... oder A-1, A-2 etc.
REALbasic. Als Neuzugang in der großen Familie unterstützter Programmierumge-

bungen präsentiert PDFlib 6 eine neue Sprachbindung für REALbasic (Mac und Win-
dows). REALbasic ist eine Sprache zur Entwicklung von plattformübergreifenden Appli-
kationen. PDFlib für REALbasic fügt sich nahtlos in das Objektmodell von RB ein,
unterstützt Unicode-Strings und bietet dem Entwickler innerhalb von REALbasic Zugriff
auf alle PDFlib-Funktionen.
1.3 Funktionalität von PDFlib
Tabelle 1.1 zeigt eine Liste der wichtigsten PDFlib-Funktionen zum Erstellen und Impor-
tieren von PDF. In PDFlib 6 neue oder erweiterte Funktionen sind gekennzeichnet.
Tabelle 1.1 Funktionen von PDFlib, PDFlib+PDI und PDFlib Personalization Server (PPS)
Kategorie Funktionalität
PDF-Ausgabe PDF-Dokumente beliebiger Länge, direkt im Arbeitsspeicher (für Web-Server) oder auf Festplatte
Kompression von Text, Vektorgrafik, Rasterbilddaten und Dateianlagen
Einfügen von Seiten1 und Unterbrechung/Wiederaufnahme1 der Seitenausgabe, um Seiten in
beliebiger Reihenfolge zu erzeugen
PDF-Varianten PDF 1.3, 1.4, 1.5 und 1.6 (Acrobat 4, 5, 6 und 7)
Linearisiertes (Web-optimiertes) PDF für Byteserving über das Web1
PDF-Import Import von Seiten aus vorhandenen PDF-Dokumenten (nur PDFlib+PDI und PPS)
Blöcke PDF-Personalisierung mit PDFlib-Blöcken für Text, Rasterbilder und PDF-Daten (nur PPS)
PDFlib-Block-Plugin für Acrobat zur Erstellung von PDFlib-Blöcken (nur PPS), neue Oberfläche1
Vektorgrafik Basisfunktionen für Vektorgrafik: Linienzüge, Kurvenzüge, Kreise, Rechtecke etc.
Farbverläufe, Füllen von Flächen und Durchziehen von Linien mit Mustern
effiziente Wiederverwendung von Text und Vektorgrafik durch Templates
Parameter für expliziten Grafikzustand zum Aussparen, Überdrucken von Text etc.
Transparenz und Farbmischmodus
Ebenen1 (Layer): optionaler Seiteninhalt, der selektiv aktiviert oder deaktiviert werden kann
Schriften TrueType- (ttf und ttc) und PostScript-Type-1-Schriften (pfb und pfa sowie lwfn auf dem Mac)
OpenType-Schriften (ttf, otf) mit PostScript- oder TrueType-Zeichenbeschreibungen
AFM- und PFM-Metrikdateien für PostScript-Schriften
Schrifteinbettung
Verwendung der im System installierten Schriften auf Mac und Windows
Untergruppenbildung (Subsetting) für TrueType- und OpenType-Schriften
benutzerdefinierte (Type 3) Schriften
Textausgabe Textausgabe in beliebigen Fonts; unterstrichener, überstrichener, durchgestrichener Text
Unterschneidung (Kerning) für PostScript-, TrueType- und OpenType-Fonts
TrueType- und OpenType-Glyph-ID-Adressierung für anspruchsvolle Typografie
proportionale Breite für Standard-CJK-Schriften
Internatio- Unicode für Seitenbeschreibungen, Hypertext1 und Dateinamen1; UTF-8- oder UCS-2-Kodierung,
nalisierung Little- oder Big-Endian
vollintegrierte Behandlung von Unicode-Strings in COM, Java, .NET, REALbasic, Tcl
Unterstützung zahlreicher Zeichensätzen (internationale Standards und herstellerspezifische
Codepages)
Abfragen von Codepages vom System (Windows, IBM eServer iSeries und zSeries)
Standard-CJK-Schriften und CMaps für Chinesisch, Japanisch und Koreanisch
benutzerspezifische CJK-Schriften im TrueType- oder OpenType-Format mit Unicode
Einbettung von Unicode-Informationen in PDF, um Text in Acrobat korrekt zu extrahieren
Rasterbilder Rasterbilder in den Formaten BMP, GIF, PNG, TIFF1, JPEG, JPEG2000 und CCITT
automatische Erkennung von Rasterbilddateiformaten
transparente (maskierte) Bilder und Transparenzmasken
Bildmasken (eingefärbte Bilder)
1.3 Funktionalität von PDFlib 17

Tabelle 1.1 Funktionen von PDFlib, PDFlib+PDI und PDFlib Personalization Server (PPS)
Kategorie Funktionalität
Einfärben von Bildern mit einer Schmuckfarbe
Bildinterpolation (Glättung von Bildern mit niedriger Auflösung)
Farbe Graustufen, RGB, CMYK und CIE L*a*b* Farbe
integrierte Schmuckfarbtabellen für PANTONE® und HKS®
benutzerdefinierte Schmuckfarben
Farbmana- ICC-basierte Farbe mit ICC-Farbprofilen: ins Bild eingebettete Profile werden berücksichtigt oder
gement externe Profile auf das Bild angewandt
Rendering Intent für Text, Vektorgrafik und Rasterbilder
Default-Farbräume zur Umsetzung geräteabhängiger Grau-, RGB- und CMYK-Farben
Druckvorstufe Generierung von zu PDF/X-1, PDF/X-1a, PDF/X-21 oder PDF/X-3 kompatibler Ausgabe inklusive der
2003-Varianten1
Einbettung eines ICC-Profils für die Druckausgabebedingung oder Angabe einer Standard-
Druckausgabebedingung
Kopieren der Druckausgabebedingung aus importierten PDF-Dokumenten (nur PDFlib+PDI und
PPS)
Erzeugen von OPI 1.3 und OPI 2.0 Informationen für importierte Bilder1
Separationsinformationen (PlateColor)1
Formatierung Textflussformatierung1: Formatierung von beliebigen Textmengen in ein oder mehrere recht-
eckige Bereiche unter Anwendung von Silbentrennung, Schrift- und Farbwechsel, verschiedenen
Ausrichtungsverfahren, Steueranweisungen
Platzierung und Formatierung von Textzeilen
flexible Platzierung und Formatierung von Rasterbildern
Sicherheit Generierung von Ausgabe mit 40- oder 128-Bit-Verschlüsselung
Generierung von Ausgabe mit Berechtigungseinstellungen
Import verschlüsselter Dokumente (Hauptkennwort erforderlich; nur PDFlib+PDI, PPS)
Hypertext Erzeugung von Formularfeldern1 mit allen Feldoptionen und JavaScript1
Erzeugung von Aktionen1 für Lesezeichen, Anmerkungen, Öffnen/Schließen der Seite und andere Ereignisse
Erzeugung von Lesezeichen1 mit einer Vielzahl von Optionen und Steuermöglichkeiten
Seitenübergänge für die Vollbildanzeige
Erzeugung aller PDF-Anmerkungstypen1 wie PDF-Verknüpfungen, Links auf andere Dokument-
typen und Weblinks
Dokumentinformation: Standardfelder (Titel, Thema, Autor, Schlüsselwörter) plus unbegrenzte
Anzahl benutzerdefinierter Infofelder
benannte Ziele für Verknüpfungen, Lesezeichen und Datei-Öffnen-Aktion
Viewer-Voreinstellungen (Menüleiste ausblenden etc.)1
Erzeugung symbolischer Namen für die Seiten (page labels)1
Tagged PDF Erzeugung von Tagged PDF1 und Strukturinformationen für Barrierefreiheit (Accessibility), Um-
fließen von Text und verbesserte Weiterverwendung des Seiteninhalts
einfache Formatierung großer Textmengen für Tagged PDF1
Program- Sprachbindungen für Cobol, COM, C, C++, Java, .NET, Perl, PHP1, Python, REALbasic1, RPG, Ruby,
mierung Tcl
Thread-Sicherheit und Robustheit für den Einsatz in »multi-threaded« Serveranwendungen
virtuelles Dateisystem zur Datenübergabe im Speicher, zum Beispiel für Bilder aus der Datenbank
1. In PDFlib 6 neu oder erheblich erweitert
1.4 Verfügbarkeit der Funktionen in den Produkten
Tabelle 1.2 zeigt die Verfügbarkeit von Funktionen in der Open-Source-Variante PDFlib
Lite und verschiedenen kommerziellen Produkten.
Tabelle 1.2 Verfügbarkeit von Funktionen in verschiedenen Produkten
PDFlib Personaliza-
tion Server (PPS)
(Open Source)
PDFlib+PDI
PDFlib Lite
PDFlib
Funktion API-Funktionen und Parameter
elementare PDF-Erstellung (alle außer den unten angeführten) X X X X
Sprachbindungen C, C++, Java, Perl, Tcl, PHP, Python X X X X
Sprachbindungen Cobol, COM, .NET, REALbasic, RPG, Ruby – X X X
funktioniert auf EBCDIC- – X X X
Systemen
Kennwortschutz und PDF_begin_document( ) mit Optionen – X X X
Berechtigungseinstellungen userpassword, masterpassword, permissions
linearisiertes PDF PDF_begin_document( ) mit Option linearize – X X X
Schriftuntergruppen (Subsets) PDF_load_font( ) mit Option subsetting – X X X
Unterschneiden (Kerning) PDF_load_font( ) mit Option kerning – X X X
Zugriff auf Mac- und PDF_load_font( ) – X X X
Windows-Systemschriften
Zugriff auf Systemzeichensätze PDF_load_font( ) – X X X
in Windows, iSeries und zSeries
Unicode-Zeichensatz und PDF_load_font( ) mit encoding = unicode, – X X X
ToUnicode- CMaps Parameter autocidfont und unicodemap
numerische und Entity- Option charref in PDF_fit_textline( ), Parameter – X X X
Referenzen charref
proportionale Zeichenbreiten PDF_load_font( ) mit UCS2-kompatibler CMap – X X X
für Standard-CJK-Fonts mit
Unicode-CMaps
Adressierung über Glyph-ID PDF_load_font( ) mit encoding = glyphid – X X X
erweiterte Zeichensätze für PDF_load_font( ) – X X X
OpenType-Fonts mit
PostScript-Outlines
Textfluss PDF_create_textflow( ), PDF_delete_textflow( ), – X X X
PDF_fit_textflow( ), PDF_info_textflow( )
Schmuckfarbe PDF_makespotcolor( ) – X X X
Farbseparation PDF_begin_page_ext( ) mit Option separationinfo – X X X
Formularfelder PDF_create_field( ), PDF_create_fieldgroup( ), PDF_ – X X X
create_action( ) mit type=SetOCGState
JavScript-Aktionen PDF_create_action( ) mit type=JavaScript – X X X
Ebenen PDF_define_layer( ), PDF_begin_layer( ), PDF_end_ – X X X
layer( ), PDF_set_layer_dependency( ), PDF_create_
action( ) mit type=SetOCGState
Tagged PDF PDF_begin_item( ), PDF_end_item( ), PDF_ – X X X
activate_item( ), PDF_begin_document( ) mit
Optionen tagged und lang
1.4 Verfügbarkeit der Funktionen in den Produkten 19

Tabelle 1.2 Verfügbarkeit von Funktionen in verschiedenen Produkten
PDFlib Personaliza-
tion Server (PPS)
(Open Source)
PDFlib+PDI
PDFlib Lite
PDFlib
Funktion API-Funktionen und Parameter
JPEG2000 PDF_load_image( ) mit imagetype=jpeg2000 X X X
PDF/X-Unterstützung PDF_process_pdi( ), PDF_begin_document( ) mit – X X X
Option pdfx
Unterstützung von PDF_load_iccprofile( ), PDF_setcolor( ) mit iccbasedgray/ – X X X
ICC-Profilen rgb/cmyk, PDF_load_image( ) mit Option honoriccprofile,
Parameter honoriccprofile, PDF_begin/end_page_ext( )
mit Option defaultgray/rgb/cmyk
CIE L*a*b*-Farbe PDF_setcolor( ) mit type = lab; Lab-TIFF-Bilder – X X X
OPI-Unterstützung PDF_load_image( ) mit Optionen OPI-1.3/OPI-2.0 – X X X
PDF-Import (PDI) PDF_open_pdi( ), PDF_open_pdi_callback( ), PDF_open_ – – X X
pdi_page( ), PDF_fit_pdi_page( ), PDF_process_pdi( )
Abfrage von Informationen PDF_get_pdi_value( ), – – X X
aus vorhandenen PDFs PDF_get_pdi_parameter( )
Verarbeitung variabler PDF_fill_textblock( ), – – – X
Daten und Personalisierung PDF_fill_imageblock( ),
mit Blöcken PDF_fill_pdfblock( )
Abfrage von Standard- und PDF_get_pdi_value( ), PDF_get_pdi_parameter( ) – – – X
kundenspezifischen Block- mit Schlüsseln vdp/Blocks
eigenschaften
PDFlib-Block-Plugin für interaktive Erstellung von PDFlib-Blöcken zur – – – X
Acrobat Verwendung mit PPS
2 Sprachbindungen von PDFlib
2.1 Übersicht
Verfügbarkeit und Plattformen. Die Funktionalität von PDFlib ist auf allen Plattfor-
men und in allen Sprachbindungen identisch (mit ein paar kleineren Ausnahmen, auf
die im Handbuch hingewiesen wird). Tabelle 2.1 zeigt die Kombinationen aus Sprache
und Plattform, die wir getestet haben.
Tabelle 2.1 Getestete Kombinationen von Sprachen und Plattformen

Unix (Linux, Solaris, HP-UX, Mac OS IBM eServer
Sprache X, AIX, IRIX u.a.) Windows NT4SP2 oder höher iSeries und zSeries
Cobol – – ILE Cobol
COM – ASP (PWS, IIS 4, 5, 6) –
WSH (VBScript 5, JScript 5)
Visual Basic 6.0, Borland Delphi 5 – 7
ISO/ANSI C gcc 3/4, HP C, IBM C 6, Sun Work- Microsoft Visual C++ 6, VS.NET IBM c89
shop 6 und andere ISO-C-Compiler Metrowerks CodeWarrior 8 SAS C für MVS
Borland C++ Builder 6
ISO C++ gcc 3/4 und andere ISO-C++- Microsoft Visual C++ 6, VS.NET IBM c89
Compiler Metrowerks CodeWarrior 8
Java JDK 1.1.8, 1.2.2, 1.3, 1.4 Sun JDK 1.1.8, 1.2.2, 1.3, 1.4 JDK 1.3.1
ColdFusion MX
.NET – .NET Framework 1.1: C#, VB.NET, –
ASP.NET, etc. (.NET Framework 2.0
mit Visual Studio 2005 Beta 2 wurde
ebenfalls getestet)
Perl Perl 5.6 – 5.8 Perl 5.6 – 5.8 –
PHP PHP 4.3.x, 4.4.x, 5.0.x PHP 4.3.x, 4.4.x, 5.0.x –
Python Python 1.6, 2.0 – 2.3 Python 1.6, 2.0 – 2.3 –
REALbasic REALbasic 5.5, 2005 oder höher für Mac OS Classic, Mac OS X und Windows –
RPG – – ILE RPG
Ruby Ruby 1.8 Ruby 1.8 –
Tcl Tcl 8.3.2 und 8.4.4 Tcl 8.3.2 und 8.4.4 –
PDFlib auf Embedded-Systemen. PDFlib kann auch auf Embedded-Systemen einge-

setzt werden. Die Bibliothek wurde auf die Systeme Windows CE, QNX und EPOC sowie
auf kundenspezifische Embedded-Systeme portiert. Zum Einsatz in eingeschränkten
Umgebungen sind bestimmte Eigenschaften konfigurierbar, um den Speicherbedarf
von PDFlib zu reduzieren. Wenn Sie an Einzelheiten interessiert sind, setzen Sie sich mit
uns über sales@pdflib.com in Verbindung.
2.1 Übersicht 21
2.2 Cobol-Sprachbindung
2.2.1 Besondere Hinweise für Cobol
Die PDFlib-API-Funktionen für Cobol sind nicht unter den in Kapitel 8 angegebenen Na-
men, sondern über spezielle Namenskürzel verfügbar. Diese Kürzel werden hier nicht
näher beschrieben, sondern in einer eigenen Umsetzungstabelle (xref.txt) aufgeführt. So
ist statt PDF_load_font( ) beispielsweise die abkürzende Schreibweise PDLODFNT zu ver-
wenden.
In Cobol programmierte PDFlib-Clients werden statisch mit dem PDFLBCOB-Objekt
gelinkt. Dieses lädt dynamisch das PDLBDLCB Load Module (DLL), welches beim ersten
Aufruf von PDNEW (entspricht PDF_new( )) wiederum das PDFlib Load Module (DLL) dy-
namisch lädt. Das Instanz-Handle der neu allozierten internen PDFlib-Struktur wird im
Parameter P gespeichert, der in allen folgenden Aufrufen übergeben werden muss.
Das PDLBDLCB Load Module liefert die Schnittstellen zwischen den 8-Zeichen-Cobol-
Funktionen und den PDFlib-Kernroutinen. Außerdem bildet es die asynchrone Ausnah-
mebehandlung von PDFlib auf das von Cobol erwartete, monolithische Verfahren ge-
mäß »prüfe den Rückgabewert jeder Funktion« ab.
Hinweis PDLBDLCB und PDFLIB müssen dem COBOL-Programm via STEPLIB verfügbar gemacht werden.
Datentypen. Die Datentypen, die in der vorliegenden PDFlib-Referenz für das API be-
nutzt werden, müssen wie in den folgenden Beispielen in Cobol-Datentypen umgesetzt
werden (aus dem Hello-Beispiel unten):
05 PDFLIB-A4-WIDTH USAGE COMP-1 VALUE 5.95E+2. // float
05 WS-INT PIC S9(9) BINARY. // int
05 WS-FLOAT COMP-1. // float
05 WS-STRING PIC X(128). // const char *
05 P PIC S9(9) BINARY. // long *
05 RETURN-RC PIC S9(9) BINARY. // int *
In allen an das PDFlib-API übergebenen Cobol-Strings sollte ein zusätzliches Byte zur
Speicherung des abschließenden Nullbytes (LOW-VALUES (NULL)) vorgesehen sein.
Rückgabewerte. Der Rückgabewert einer PDFlib-API-Funktion wird in einem zusätzli-

chen Parameter namens ret bereitgestellt, der per Referenz übergeben wird. Dieser wird
mit dem Ergebnis des jeweiligen Funktionsaufrufs gefüllt. Der Rückgabewert 0 besagt,
dass die Funktion erfolgreich ausgeführt wurde; alle anderen Werte weisen auf einen
Fehler hin, der zu einem Abbruch der PDF-Generierung führt.
Funktionen ohne Rückgabewert (C-Funktionen mit einem Ergebnis vom Typ void)
verwenden diesen zusätzlichen Parameter nicht.
Fehlerbehandlung. In der Cobol-Sprachbindung gibt es keine PDFlib-Ausnahmebe-

handlung. Stattdessen gibt es den zusätzlichen Parameter rc (zur Speicherung des
Return Code), der von allen API-Funktionen als Fehlerindikator unterstützt wird. Der Pa-
rameter rc wird per Referenz übergeben und zur Übermittlung von Problemen verwen-
det. Jeder Wert ungleich 0 weist auf ein Scheitern des Funktionsaufrufs hin.
22 Kapitel 2: Sprachbindungen von PDFlib

2.2.2 Das Beispiel »Hello world« in Cobol
Das folgende Beispiel zeigt ein einfaches Cobol-Programm, das mit PDFlib gebunden
wird. Es führt keine Fehlerüberprüfung durch:
IDENTIFICATION DIVISION.
PROGRAM-ID. HELLO.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 PDFLIB-PAGE-SIZE-CONSTANTS.
05 PDFLIB-A4-WIDTH USAGE COMP-1 VALUE 5.95E+2.
05 PDFLIB-A4-HEIGHT USAGE COMP-1 VALUE 8.42E+2.
01 PDFLIB-CALL-AREA.
05 P PIC S9(9) BINARY.
05 RC PIC S9(9) BINARY.
05 PDFLIB-RETURN-LONG PIC S9(9) BINARY.
05 PDFLIB-RETURN-CHAR PIC X(64) VALUE SPACES.
05 PDFLIB-ERR-STRING PIC X(128).
01 WS-WORK-FIELDS.
05 WS-INT PIC S9(9) BINARY.
05 WS-FONT PIC S9(9) BINARY.
05 WS-FLOAT COMP-1.
05 WS-FLOAT2 COMP-1.
05 WS-STRING PIC X(128).
05 WS-STRING2 PIC X(128).
05 WS-NULL PIC X(1) VALUE LOW-VALUES.
PROCEDURE DIVISION.
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* CREATE A PDF OBJECT *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
CALL "PDNEW" USING P,
RC.
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* OPEN NEW PDF DOCUMENT *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
MOVE 0 TO WS-INT.
STRING Z'HELLO.PDF'
DELIMITED BY SIZE INTO WS-STRING.
CALL "PDBEGDOC" USING P,

WS-STRING,
WS-INT,
WS-NULL,
PDFLIB-RETURN-LONG,
RC.
IF PDFLIB-RETURN-LONG = -1
CALL "PDERRMSG" USING P,
PDFLIB-ERR-STRING,
RC
DISPLAY PDFLIB-ERR-STRING
MOVE +8 TO RETURN-CODE
GOBACK.
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* SET PDF INFORMATION *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
STRING Z'Creator'
STRING Z'Hello.cbl'
DELIMITED BY SIZE INTO WS-STRING2.
CALL "PDSETINF" USING P,

WS-STRING,
WS-STRING2,
RC.
STRING Z'Author'
STRING Z'Thomas Merz'

WS-STRING
WS-STRING2,
RC.
STRING Z'Title'
STRING Z'Hello, world (COBOL)!'

WS-STRING
WS-STRING2,
RC.
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* BEGIN A NEW PAGE *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
CALL "PDBEGPAG" USING P,
PDFLIB-A4-WIDTH,
PDFLIB-A4-HEIGHT,
WS-NULL,
RC.
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* LOAD & SET THE CURRENT FONT *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
MOVE 0 TO WS-INT.
STRING Z'Helvetica-Bold'
STRING Z'ebcdic'
CALL "PDLODFNT" USING P,

WS-STRING
WS-INT,
WS-STRING2,
WS-NULL,

PDFLIB-RETURN-LONG,
RC.
MOVE PDFLIB-RETURN-LONG TO WS-FONT.
MOVE 24 TO WS-FLOAT.
CALL "PDSETFNT" USING P,

WS-FONT,
WS-FLOAT,
RC.
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* WRITE TO THE CURRENT PAGE OF THE PDF DOCUMENT *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
MOVE 50 TO WS-FLOAT.
MOVE 700 TO WS-FLOAT2.
CALL "PDSETTP" USING P,

WS-FLOAT,
WS-FLOAT2,
RC.
STRING Z'Hello, World!'

CALL "PDSHOW" USING P,

WS-STRING,
RC.
STRING Z'(says COBOL)'

CALL "PDCONT" USING P,

WS-STRING,
RC.
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* END THIS PAGE *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
CALL "PDENDPAG" USING P,
WS-NULL,
RC.
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* END THE PDF DOCUMENT *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
CALL "PDENDDOC" USING P,
WS-NULL,
RC.
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* DELETE THE PDF OBJECT *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
CALL "PDDELETE" USING P,
RC.
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* END THE PROGRAM *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
MOVE ZERO TO RETURN-CODE.
GOBACK.
END PROGRAM HELLO.
2.3 COM-Sprachbindung
(Dieser Abschnitt ist nur in der COM/.NET/REALbasic-Ausgabe des PDFlib-Referenz-
handbuchs enthalten.)
2.4 C-Sprachbindung
2.4.1 Verfügbarkeit und besondere Hinweise zu C
PDFlib ist in ANSI C geschrieben. Um die C-Sprachbindung von PDFlib zu nutzen, kön-
nen Sie eine statische oder eine dynamisch ladbare Bibliothek (DLL unter Windows und
MVS) verwenden. Außerdem benötigen Sie die zentrale PDFlib-Include-Datei pdflib.h zur
Einbindung in Ihre PDFlib-Client-Quellmodule. Alternativ dazu kann pdflibdl.h einge-
setzt werden, um die PDFlib-DLL zur Laufzeit dynamisch zu laden (siehe Abschnitt 2.4.3,
»Einsatz von PDFlib als DLL, die zur Laufzeit geladen wird«, Seite 27).
2.4.2 Das Beispiel »Hello world« in C

Das folgende Beispiel zeigt ein einfaches C-Programm, das mit einer statischen oder dy-
namischen PDFlib-Bibliothek gebunden wird.
#include <stdio.h>
#include <stdlib.h>
#include "pdflib.h"
int
main(void)
{
PDF *p;
int font;
if ((p = PDF_new()) == (PDF *) 0)

{
printf("Couldn't create PDFlib object (out of memory)!\n");
return(2);
}
PDF_TRY(p) {
if (PDF_begin_document(p, "hello.pdf", 0, "") == -1) {
printf("Error: %s\n", PDF_get_errmsg(p));
return(2);
}
PDF_set_info(p, "Creator", "hello.c");

PDF_set_info(p, "Author", "Thomas Merz");
PDF_set_info(p, "Title", "Hello, world (C)!");
PDF_begin_page_ext(p, a4_width, a4_height, "");
/* Change "host" encoding to "winansi" or whatever you need! */

font = PDF_load_font(p, "Helvetica-Bold", 0, "host", "");

PDF_setfont(p, font, 24);
PDF_set_text_pos(p, 50, 700);
PDF_show(p, "Hello, world!");
PDF_continue_text(p, "(says C)");
PDF_end_page_ext(p, "");
PDF_end_document(p, "");
}
PDF_CATCH(p) {
printf("PDFlib exception occurred in hello sample:\n");
printf("[%d] %s: %s\n",
PDF_get_errnum(p), PDF_get_apiname(p), PDF_get_errmsg(p));
PDF_delete(p);
return(2);
}
PDF_delete(p);
return 0;
}
2.4.3 Einsatz von PDFlib als DLL, die zur Laufzeit geladen wird
Die meisten Clients werden PDFlib als statisch gebundene oder dynamische Bibliothek
einsetzen, die beim Linken gebunden wird. Sie können die PDFlib-DLL aber auch zur
Laufzeit laden und sich dynamisch Zeiger auf alle API-Funktionen besorgen. Dies ist ins-
besondere unter MVS sinnvoll, wo es üblich ist, die Bibliothek als DLL zur Laufzeit zu la-
den, ohne die Applikation überhaupt mit der PDFlib-Bibliothek zu linken. Zur einfache-
ren Verwendung dieser Methode gehen Sie wie folgt vor:
> Inkludieren Sie pdflibdl.h statt pdflib.h.
> Verwenden Sie PDF_new_dl( ) und PDF_delete_dl( ) statt PDF_new( ) und PDF_delete( ).
> Verwenden Sie PDF_TRY_DL( ) und PDF_CATCH_DL( ) statt PDF_TRY( ) und PDF_CATCH( ).
> Arbeiten Sie bei allen anderen PDFlib-Aufrufen mit Funktionszeigern.
> PDF_get_opaque( ) darf nicht verwendet werden.
> Kompilieren Sie das Hilfsmodul pdflibdl.c und binden Sie es mit Ihrer Anwendung.
Hinweis Das Laden der PDFlib-DLL zur Laufzeit wird nicht auf allen Plattformen unterstützt.
Das folgende Beispiel lädt die PDFlib-DLL mit diesem Verfahren zur Laufzeit:
#include <stdio.h>
#include <stdlib.h>
#include "pdflibdl.h"
int
main(void)
{
PDF *p;
int font;
PDFlib_api *PDFlib;
/* PDFlib als dynamische Bibliothek laden und neues PDFlib-Objekt erzeugen */

if ((PDFlib = PDF_new_dl(&p)) == (PDFlib_api *) NULL)
{
printf("PDFlib-Objekt konnte nicht erzeugt werden (DLL nicht gefunden?)\n");
return(2);
}
PDF_TRY_DL(PDFlib, p) {
if (PDFlib->PDF_begin_document(p, "hellodl.pdf", 0, "") == -1) {
printf("Error: %s\n", PDFlib->PDF_get_errmsg(p));
return(2);
}
PDFlib->PDF_set_info(p, "Creator", "hello.c");

PDFlib->PDF_set_info(p, "Author", "Thomas Merz");
PDFlib->PDF_set_info(p, "Title", "Hello, world (C DLL)!");
PDFlib->PDF_begin_page_ext(p, a4_width, a4_height, "");
/* Ändere Zeichensatz "host" zu "winansi" oder anderem Zeichensatz */

font = PDFlib->PDF_load_font(p, "Helvetica-Bold", 0, "host", "");
PDFlib->PDF_setfont(p, font, 24);

PDFlib->PDF_set_text_pos(p, 50, 700);
PDFlib->PDF_show(p, "Hello, world!");
PDFlib->PDF_continue_text(p, "(says C DLL)");
PDFlib->PDF_end_page_ext(p, "");
PDFlib->PDF_end_document(p, "");
}
PDF_CATCH_DL(PDFlib, p) {
printf("PDFlib-Exception aufgetreten in Beispiel hellodl:\n");
PDFlib->PDF_get_errnum(p), PDFlib->PDF_get_apiname(p),
PDFlib->PDF_get_errmsg(p));
PDF_delete_dl(PDFlib, p);
return(2);
}
/* PDFlib-Objekt löschen und Library entfernen */

PDF_delete_dl(PDFlib, p);
return 0;
}
2.4.4 Fehlerbehandlung in C
PDFlib unterstützt die strukturierte Ausnahmebehandlung mit try/catch-Klauseln. Da-
mit können C- und C++-Clients von PDFlib ausgelöste Exceptions abfangen und ange-
messen reagieren. In der catch-Klausel hat der Client Zugriff auf einen String mit einer
exakten Problembeschreibung, einer eindeutigen Exception-Nummer und dem Namen
der PDFlib-API-Funktion, die die Ausnahme ausgelöst hat. Ein PDFlib-C-Clientpro-
gramm mit Ausnahmebehandlung besitzt in etwa folgenden Aufbau:
PDF_TRY(p)
{
...PDFlib-Anweisungen...
}
PDF_CATCH(p)

{
printf("PDFlib-Exception im hello Beispiel:\n");
PDF_get_errnum(p), PDF_get_apiname(p), PDF_get_errmsg(p));
PDF_delete(p);
return(2);
}
PDF_delete(p);
Hinweis PDF_TRY und PDF_CATCH sind recht trickreich als Präprozessor-Makros implementiert. Verges-
sen Sie eines davon, so erhalten Sie eine vermutlich schwierig zu verstehende Compiler-Fehler-
meldung. Benutzen Sie die Makros deshalb genau wie oben angegeben, ohne zusätzlichen
Code zwischen die TRY- und CATCH-Klauseln einzufügen (außer PDF_CATCH( )).
Wenn Sie die try-Klausel mittendrin verlassen möchten, müssen Sie den Exception-Me-
chanismus darüber zuerst mit dem Makro PDF_EXIT_TRY( ) informieren. Zwischen die-
sem Makro und dem Ende des try-Blocks darf dann keine andere PDFlib-Funktion mehr
aufgerufen werden.
Eine wesentliche Aufgabe der catch-Klausel besteht darin, das Innenleben von PDFlib
mit PDF_delete( ) und dem Zeiger auf das PDFlib-Objekt zu bereinigen. PDF_delete( )
schließt gegebenenfalls auch die Ausgabedatei. In benutzerdefinierten Error-Handlern
dürfen nur die PDFlib-Funktionen PDF_delete( ) und PDF_get_opaque( ) sowie die Aus-
nahmebehandlungsfunktionen PDF_get_errnum( ), PDF_get_apiname( ) und PDF_get_
errmsg( ) aufgerufen werden. Nach fatalen Exceptions ist das PDF-Dokument unbrauch-
bar und wird unvollständig und inkonsistent hinterlassen. Wie auf eine Exception zu
reagieren ist, hängt natürlich vollkommen von der jeweiligen Anwendung ab.
Bei C- und C++-Clients, die keine Exceptions abfangen, wird auf Exceptions standard-
mäßig mit einer entsprechenden Meldung auf die Standard-Fehlerausgabe sowie einem
Abbruch bei fatalen Fehlern reagiert. Beachten Sie, dass die PDF-Ausgabedatei dabei in
einem inkonsistenten Zustand hinterlassen wird! Da ein Programmabbruch für eine
Bibliotheksroutine nicht akzeptabel ist, sollten bei ernsthaften PDFlib-Projekten unbe-
dingt die Fehlerbehandlungsmöglichkeiten von PDFlib genutzt werden. Eine benutzer-
definierte catch-Klausel könnte die Fehlermeldung beispielsweise in einem GUI-Dialog-
feld präsentieren und danach nicht abbrechen, sondern auf andere Art fortfahren.
Error-Handler alten Typs. Neben der strukturierten Ausnahmebehandlung unter-

stützt PDFlib das Konzept der anwendungsspezifischen Callback-Routine, die beim Auf-
treten einer Exception aufgerufen wird. Diese Methode ist jedoch veraltet und wird nur
noch aus Kompatibilitätsgründen unterstützt. In PDF_TRY-Blöcken werden Error-Hand-
ler ignoriert.
2.4.5 Speicherverwaltung in C
Um maximale Flexibilität zu gewährleisten, können die PDFlib-internen Speicherver-
waltungsroutinen (die auf den Standard-C-Funktionen malloc und free basieren) durch
externe, vom Client übergebene Prozeduren ersetzt werden. Diese werden dann für jede
PDFlib-interne Speicherallozierung oder -freigabe benutzt. Sie werden mit PDF_new2( )
installiert und dann statt der internen PDFlib-Routinen verwendet. Beim Aufruf von
PDF_new2( ) müssen entweder alle oder keine der folgenden Routinen übergeben wer-
den:
> eine Routine zur Speicherallozierung
> eine Routine zur Speicherfreigabe
> eine Routine zur Neuallozierung, die Speicherblöcke vergrößert, die vorher mit der
Allozierungsroutine belegt wurden
Die Syntax der Speicherverwaltungsroutinen wird in Abschnitt 8.2, »Allgemeine Funkti-

onen«, Seite 222, beschrieben. Diese Routinen müssen sich an die Semantik der Stan-
dard-C-Funktionen malloc, free und realloc halten, können ansonsten aber beliebig im-
plementiert sein. Ihnen wird immer ein Zeiger auf das aufrufende PDFlib-Objekt
übergeben. Lediglich beim ersten Aufruf der Allozierungsroutine wird ein NULL-Zeiger
als PDF-Argument übergeben. Client-spezifische Allozierungsroutinen müssen daher
mit einem NULL-Zeiger umgehen können.
Mit der Funktion PDF_get_opaque( ) erhält man vom PDFlib-Objekt einen Zeiger auf
Benutzerdaten, sofern dieser vom Client zuvor im Aufruf von PDF_new2( ) übergeben
wurde. Ein solcher Zeiger kann in multi-threaded Anwendungen nützlich sein, um
thread- oder klassenspezifische Daten innerhalb des PDFlib-Objekts aufzubewahren
und dann in Speicherverwaltungs- oder Fehlerbehandlungsroutinen zu verwenden.
2.4.6 Unicode in der C-Sprachbindung

In der C-Sprachbindung dürfen Clients keine der Standardfunktionen zur Textausgabe
verwenden (PDF_show( ), PDF_show_xy( ) oder PDF_continue_text( )), wenn der Text einge-
bettete Nullzeichen enthalten kann. In diesen Fällen müssen die Alternativfunktionen
PDF_show2( ) etc. verwendet werden, wobei die Stringlänge getrennt zu übergeben ist.
Bei allen anderen Sprachbindungen spielt dieser Aspekt keine Rolle, da die PDFlib-
Sprachwrapper intern zuerst PDF_show2( ) etc. aufrufen.
2.5 C++-Sprachbindung
2.5.1 Verfügbarkeit und besondere Hinweise zu C++
Neben der C-Include-Datei pdflib.h wird für PDFlib-Clients ein Objekt-Wrapper für C++
mitgeliefert. Dieser erfordert die Include-Datei pdflib.hpp, die wiederum pdflib.h inklu-
diert, welche also ebenfalls vorhanden sein muss. Das zugehörige Modul pdflib.cpp muss
mit der Anwendung gebunden werden, die wiederum mit der generischen PDFlib-C-
Bibliothek zu binden ist.
Um den C++-Objekt-Wrapper effektiv einzusetzen, tritt an die Stelle des Präfix PDF_
in allen PDFlib-Funktionen ein stärker objektorientierter Ansatz mit einem PDFlib-
Objekt und zugehörigen Methoden. Beachten Sie diesen Unterschied, wenn Sie die PDF-
lib-API-Beschreibungen im Handbuch lesen, die in C-Syntax aufgelistet werden.
2.5.2 Das Beispiel »Hello world« in C++

#include <iostream>
#include "pdflib.hpp"
int
main(void)
{
try {

int font;
PDFlib p;
if (p.begin_document("hello.pdf", "") == -1) {

cerr << "Error: " << p.get_errmsg() << endl;
return 2;
}
p.set_info("Creator", "hello.cpp");
p.set_info("Author", "Thomas Merz");
p.set_info("Title", "Hello, world (C++)!");
p.begin_page_ext((float) a4_width, (float) a4_height, "");
// Change "host" encoding to "winansi" or whatever you need!

font = p.load_font("Helvetica-Bold", "host", "");
p.setfont(font, 24);
p.set_text_pos(50, 700);
p.show("Hello, world!");
p.continue_text("(says C++)");
p.end_page_ext("");
p.end_document("");
}
catch (PDFlib::Exception &ex) {

cerr << "PDFlib exception occurred in hello sample: " << endl;
cerr << "[" << ex.get_errnum() << "] " << ex.get_apiname()
<< ": " << ex.get_errmsg() << endl;
return 2;
}
return 0;
}
2.5.3 Fehlerbehandlung in C++

PDFlib-API-Funktionen lösen im Fehlerfall eine C++-Exception aus. Diese Exceptions
müssen im Clientcode mit den üblichen try/catch-Klauseln von C++ abgefangen werden.
Für ausführlichere Fehlerinformationen stellt die Klasse PDFlib die öffentliche (public)
Klasse PDFlib::Exception mit Methoden zur Verfügung, die die genaue Fehlermeldung,
die Exception-Nummer sowie den Namen der PDFlib-API-Funktion liefern, die die Ex-
ception ausgelöst hat.
Native C++-Exceptions, die durch PDFlib-Routinen ausgelöst wurden, verhalten sich
wie erwartet. Das folgende Codefragment fängt Exceptions ab, die von PDFlib ausgelöst
werden:
try {
catch (PDFlib::Exception &ex) {
cerr << "PDFlib-Exception im Hello-Beispiel: " << endl;
cerr << "[" << ex.get_errnum() << "] " << ex.get_apiname()
<< ": " << ex.get_errmsg() << endl;
return 2;
}
2.5 C++-Sprachbindung 31
2.5.4 Speicherverwaltung in C++
Vom Client übergebene Routinen zur Speicherverwaltung funktionieren in der C++-
Sprachbindung genauso wie in der C-Sprachbindung.
Dem PDFlib-Konstruktor können optional ein Error-Handler, Speicherverwaltungs-
routinen sowie ein Zeiger auf Benutzerdaten übergeben werden. In pdflib.hpp werden
standardmäßig NULL-Argumente übergeben, die eine Aktivierung der Fehler- und Spei-
cherverwaltungsroutinen von PDFlib bewirken. Sämtliche Speicherverwaltungsfunkti-
onen müssen C-Funktionen sein. Es dürfen keine C++-Methoden zum Einsatz kommen.
2.5.5 Unicode in der C++ -Sprachbindung

Der Compiler konvertiert literale Strings automatisch in den C++-Stringtyp, wie er von
den PDFlib-Funktionen erwartet wird. C++-Benutzer müssen sich der Tatsache bewusst
sein, dass bei der Konvertierung Nullzeichen nur unterstützt werden, wenn ein explizi-
ter Längenparameter übergeben wird. So funktioniert der folgende Aufruf zum Beispiel
nicht, da der String beim ersten Nullzeichen abgeschnitten wird:
p.show("\x00\x41\x96\x7B\x8C\xEA"); // Falsch!
Zur Vermeidung dieses Problems verwenden Sie den String-Konstruktor mit explizitem
Längenparameter:
p.show(string("\x00\x41\x96\x7B\x8C\xEA", 6)); // Richtig
2.6 Java-Sprachbindung
Java unterstützt ein portierbares Verfahren zum Anbinden von nativem Programm-
code an Java-Programme, nämlich das Java Native Interface (JNI). Das JNI bietet Pro-
grammierkonventionen, um native C- oder C++-Routinen aus Java-Code heraus aufzu-
rufen und umgekehrt. Um der Java-VM zugänglich zu sein, müssen alle C-Routinen in
geeignetem Wrapper-Code verpackt werden. Die daraus resultierende Bibliothek ist als
dynamisches Objekt zu generieren, damit sie von der Java-VM geladen werden kann.
Um von Java aus verwendbar zu sein, wird mit PDFlib JNI-Wrapper-Code mitgelie-
fert. Anhand des geschilderten Verfahrens kann PDFlib an Java angebunden werden, in-
dem die dynamische Bibliothek von der Java-VM geladen wird. Das eigentliche Laden
der Bibliothek erfolgt mittels einer statischen Member-Funktion der Java-Klasse pdflib.
Dadurch muss sich der Java-Client nicht mit den Einzelheiten zum Laden einer dynami-
schen Bibliothek auseinandersetzen.
Aufgrund der Stabilität und Robustheit von PDFlib wird die Stabilität und Sicherheit
der Java-Anwendung beim Anbinden der nativen PDFlib-Bibliothek an die Java-VM in
keinerlei Weise beeinträchtigt. Als Vorteil kann die höhere Geschwindigkeit einer nati-
ven Implementierung genutzt werden. Hinsichtlich der Portabilität ist zu bedenken,
dass PDFlib auf allen Plattformen verfügbar ist, auf denen eine Java-VM läuft!
2.6.1 Installation der Java-Edition von PDFlib

Damit die PDFlib-Anwendung funktioniert, benötigt die Java-VM Zugriff auf den
PDFlib-Java-Wrapper und das PDFlib-Java-Paket.

Das PDFlib-Java-Paket. PDFlib ist in einem Java-Package mit dem folgenden Package-
Namen enthalten:
com.pdflib.pdflib
Dieses Paket befindet sich in der Datei pdflib.jar und enthält eine einzige Klasse namens
pdflib. Anhand der Quelldateien in der PDF-Lite-Version können Sie mit dem Utility-Pro-
gramm javadoc eine gekürzte Fassung des (vorliegenden) PDFlib-Referenzhandbuchs er-
zeugen, da die PDFlib-Klasse die erforderlichen javadoc-Kommentare enthält. Textdatei-
en mit Anmerkungen und Einschränkungen zum Einsatz von PDFlib in verschiedenen
Java-Umgebungen sind ebenfalls vorhanden.
Um dieses Paket Ihrer Anwendung verfügbar zu machen, müssen Sie pdflib.jar an die
Umgebungsvariable CLASSPATH anfügen, die Option -classpath pdflib.jar in die Aufrufe
von Java-Compiler und Java-Laufzeitumgebung aufnehmen oder die entsprechenden
Schritte in Ihrer IDE durchführen. Im JDK können Sie die Java-VM so konfigurieren, dass
sie ein vorgegebenes Verzeichnis nach nativen Bibliotheken durchsucht. Dazu weisen
Sie der Property java.library.path den Namen des gewünschten Verzeichnisses zu, zum
Beispiel:
java -Djava.library.path=. pdfclock
Der Wert dieser Eigenschaft lässt sich wie folgt überprüfen:

System.out.println(System.getProperty("java.library.path"));
Außerdem sind die folgenden plattformabhängigen Schritte durchzuführen.
Unix. Unter Unix muss die Bibliothek libpdf_java.so (unter Mac OS X: libpdf_java.jnilib)
in eines der Standardverzeichnisse für dynamisch ladbare Bibliotheken oder in ein ent-
sprechend konfiguriertes Verzeichnis kopiert werden.
Windows. Unter Windows muss die Bibliothek pdf_java.dll ins Windows-Systemver-

zeichnis oder in ein Verzeichnis kopiert werden, das in der Umgebungsvariablen PATH
aufgeführt ist.
PDFlib-Servlets und Java-Applikationsserver. PDFlib eignet sich hervorragend für ser-

verseitige Java-Anwendungen, insbesondere für Servlets. Die PDFlib-Distribution ent-
hält Beispiele für PDFlib-Java-Servlets, die elementare Anwendungsfälle zeigen. Beim
Einsatz von PDFlib mit einer bestimmten Servlet-Engine sind folgende Konfigurations-
aspekte zu beachten:
> Das Verzeichnis, in dem die Servlet-Engine die nativen Bibliotheken erwartet, ist je
nach Anbieter unterschiedlich. Üblich sind Systemverzeichnisse, Verzeichnisse der
zugrunde liegenden Java-VM oder lokale Verzeichnisse der Servlet-Engine. Einzelhei-
ten hierzu finden Sie in der Dokumentation, die vom Hersteller der Servlet-Engine
bereitgestellt wird.
> Servlets werden oft von einem speziellen Klassenlader geladen, der möglicherweise
Einschränkungen unterliegt oder einen bestimmten Klassenpfad verwendet. Bei
manchen Servlet-Engines muss ein besonderer Engine-Klassenpfad festgelegt wer-
den, damit das PDFlib-Paket gefunden werden kann.
2.6 Java-Sprachbindung 33
Ausführlichere Hinweise zum Einsatz von PDFlib mit bestimmten Servlet-Engines und
Java-Applikationsservern finden Sie in weiteren Dokumentationsdateien der PDFlib-
Distribution.
Hinweis Da die Spezifikation der EJB (Enterprise Java Beans) den Gebrauch nativer Bibliotheken aus-
schließt, kann PDFlib nicht in EJBs eingesetzt werden.
2.6.2 Das Beispiel »Hello world« in Java

import java.io.*;
import com.pdflib.pdflib;
import com.pdflib.PDFlibException;
public class hello

{
public static void main (String argv[])
{
int font;
pdflib p = null;
try{
p = new pdflib();
if (p.begin_document("hello.pdf", "") == -1) {

throw new Exception("Error: " + p.get_errmsg());
}
p.set_info("Creator", "hello.java");
p.set_info("Author", "Thomas Merz");
p.set_info("Title", "Hello world (Java)!");
p.begin_page_ext(595, 842, "");
font = p.load_font("Helvetica-Bold", "unicode", "");
p.setfont(font, 18);
p.set_text_pos(50, 700);
p.show("Hello world!");
p.continue_text("(says Java)");
p.end_page_ext("");
p.end_document("");
} catch (PDFlibException e) {
System.err.print("PDFlib exception occurred in hello sample:\n");
System.err.print("[" + e.get_errnum() + "] " + e.get_apiname() +
": " + e.get_errmsg() + "\n");
} catch (Exception e) {
System.err.println(e.getMessage());
} finally {
if (p != null) {
p.delete();
}
}
}
}

2.6.3 Fehlerbehandlung in Java
Die Java-Sprachbindung installiert einen speziellen Error-Handler, der PDFlib-Fehler in
native Java-Exceptions übersetzt. Beim Auftreten einer Exception löst PDFlib eine nati-
ve Java-Exception der folgenden Klasse aus:
PDFlibException
Die Java-Exceptions können mit der üblichen Kombination aus try und catch behandelt
werden:
try {
} catch (PDFlibException e) {
System.err.print("PDFlib exception occurred in hello sample:\n");
System.err.print("[" + e.get_errnum() + "] " + e.get_apiname() +
": " + e.get_errmsg() + "\n");
} catch (Exception e) {
System.err.println(e.getMessage());
} finally {
if (p != null) {
p.delete(); /* PDFlib-Objekt löschen */
}
}
Da PDFlib passende throws-Klauseln deklariert, muss der Client-Code alle möglichen

PDFlib-Exceptions abfangen oder diese selbst deklarieren.
2.7 .NET-Sprachbindung
2.8 Perl-Sprachbindung
Perl1 unterstützt ein Verfahren zur Erweiterung des Sprachinterpreters durch native
C-Bibliotheken. Der PDFlib-Wrapper für Perl besteht aus einer C-Wrapperdatei und ei-
nem Perl-Paketmodul. Das C-Modul wird zum Aufbau einer dynamischen Bibliothek
verwendet, die vom Perl-Interpreter unter Zuhilfenahme der Paketdatei zur Laufzeit ge-
laden wird. Perl-Skripten referenzieren das Bibliotheksmodul mit einer use-Anweisung.
2.8.1 Installation der PDFlib-Perl-Edition

Das Erweiterungsverfahren von Perl lädt dynamische Bibliotheken zur Laufzeit mittels
des DynaLoader-Moduls. Perl selbst muss mit einer Option zur Unterstützung dynami-
scher Bibliotheken kompiliert worden sein (das ist bei den meisten Perl-Konfiguratio-
nen der Fall).
1. Siehe www.perl.com
2.7 .NET-Sprachbindung 35
Damit die PDFlib-Sprachbindung funktioniert, benötigt der Perl-Interpreter Zugriff
auf den PDFlib-Perl-Wrapper und die Moduldatei pdflib_pl.pm. Zusätzlich zu den unten
beschriebenen plattformspezifischen Methoden können Sie mit der Perl-Befehlszeilen-
option -I zum Modulsuchpfad @INC ein Verzeichnis hinzufügen, zum Beispiel:
perl -I/path/to/pdflib hello.pl
Unix. Perl sucht pdflib_pl.so (unter Mac OS X: pdflib_pl.dylib) und pdflib_pl.pm im aktuel-
len Verzeichnis oder in dem Verzeichnis, das mit folgendem Befehl ausgegeben wird:
perl -e 'use Config; print $Config{sitearchexp};'
Perl durchsucht außerdem das Unterverzeichnis auto/pdflib_pl. Der obige Befehl liefert
eine Ausgabe, die in etwa wie folgt aussieht:
/usr/lib/perl5/site_perl/5.8/i686-linux
Windows. PDFlib unterstützt den ActiveState-Port von Perl 5 für Windows namens Ac-
tivePerl.1 pdflib_pl.dll und pdflib_pl.pm werden im aktuellen Verzeichnis gesucht oder im
Verzeichnis, das mit folgendem Perl-Befehl ausgegeben wird:
perl -e "use Config; print $Config{sitearchexp};"
Der obige Befehl liefert eine Ausgabe, die in etwa wie folgt aussieht:
C:\Program Files\Perl5.8\site\lib
2.8.2 Das Beispiel »Hello world« in Perl

use pdflib_pl 6.0;
$p = PDF_new();
eval {
if (PDF_begin_document($p, "hello.pdf", "") == -1) {
printf("Error: %s\n", PDF_get_errmsg($p));
exit;
}
PDF_set_info($p, "Creator", "hello.pl");

PDF_set_info($p, "Author", "Thomas Merz");
PDF_set_info($p, "Title", "Hello world (Perl)!");
PDF_begin_page_ext($p, 595, 842, "");
$font = PDF_load_font($p, "Helvetica-Bold", "winansi", "");
PDF_setfont($p, $font, 24.0);

PDF_set_text_pos($p, 50, 700);
PDF_show($p, "Hello world!");
PDF_continue_text($p, "(says Perl)");
PDF_end_page_ext($p, "");
PDF_end_document($p, "");
1. Siehe www.activestate.com

};
if ($@) {
printf("hello: PDFlib Exception occurred:\n");
printf(" $@\n");
exit;
}
PDF_delete($p);
2.8.3 Fehlerbehandlung in Perl

Die Perl-Sprachbindung installiert einen speziellen Error-Handler, der PDFlib-Fehler in
native Perl-Exceptions übersetzt. Die Perl-Exceptions können durch geeignete Sprach-
elemente, die kritische Abschnitte klammern, verarbeitet werden, zum Beispiel:
eval {
};
die "Abgefangene Exception" if $@;
2.9 PHP-Sprachbindung
2.9.1 Installation der PDFlib-Edition für PHP
Ausführliche Informationen über die verschiedenen Möglichkeiten des Einsatzes von
PDFlib mit PHP 1 einschließlich einer Diskussion der Frage, ob ein ladbares PDFlib-Modul
für PHP zum Einsatz kommen kann oder nicht, finden Sie in der Datei PDFlib-in-PHP-
HowTo.pdf, die mitausgeliefert wird und auf der PDFlib-Web-Site verfügbar ist.
Sie müssen PHP per Konfiguration über die externe PDFlib-Bibliothek informieren.
Dazu gibt es zwei Möglichkeiten:
> Fügen Sie in eine der folgenden Zeilen in php.ini ein:
extension=libpdf_php.so ; für Unix
extension=libpdf_php.dll ; für Windows
PHP sucht die Bibliothek in dem Verzeichnis, das unter Unix in der Variablen
extension_dir in der Datei php.ini verzeichnet ist. Unter Windows werden außerdem
die Standardsystemverzeichnisse durchsucht. Mit dem folgenden einzeiligen PHP-
Skript können Sie ermitteln, welche Version der PDFlib-Sprachbindung für PHP Sie
installiert haben:
<?phpinfo()?>
Angezeigt wird eine lange Info-Seite über Ihre aktuelle PHP-Konfiguration. Suchen
Sie auf der Seite nach dem Abschnitt pdf. Wenn dieser Abschnitt PDFlib GmbH Binary
Version (sowie die PDFlib-Versionsnummer) enthält, dann verwenden Sie den unter-
stützten neuen PDFlib-Wrapper. Der nicht unterstützte alte Wrapper wird dagegen
als PDFlib GmbH Version angezeigt.
> Laden Sie PDFlib zur Laufzeit, wobei Sie eine der folgenden Zeilen an den Anfang
Ihres Skripts stellen:
1. Siehe www.php.net
dl("libpdf_php.so"); # für Unix
dl("libpdf_php.dll"); # für Windows
Neue Funktionen in PHP 5. PDFlib nutzt folgende neue Funktionen von PHP 5:
> Neues Objektmodell: Die PDFlib-Funktionen sind in ein PDFlib-Objekt gekapselt.
> Exceptions: PDFlib-Exceptions werden als PHP-5-Exceptions weitergeleitet und kön-
nen mit der üblichen Kombination aus try und catch abgefangen werden. Die neue
Ausnahmebehandlung kann sowohl mit dem neuen objektorientierten Konzept als
auch mit den alten API-Funktionen verwendet werden.
Details zu diesen PHP-5-Funktionen finden Sie weiter unten.
Modifizierte Fehlerrückgabe für PDFlib-Funktionen in PHP. Da PHP per Konvention

den Wert 0 (FALSE) zurückgibt, wenn in einer Funktion ein Fehler auftritt, wurden alle
PDFlib-Funktionen entsprechend angepasst und liefern im Fehlerfall 0 statt -1. Diese
Abweichung ist in den Funktionsbeschreibungen in Kapitel 8, vermerkt. Achten Sie je-
doch darauf, wenn Sie die Beispiel-Codefragmente in Kapitel 3, durchsehen, da dort ent-
sprechend der üblichen PDFlib-Konvention im Fehlerfall -1 zurückgegeben wird.
Behandlung von Dateinamen in PHP. Nicht qualifizierte Dateinamen (also solche

ohne jede Pfadangabe) sowie relative Dateinamen für PDF-, Rasterbild-, Font- und ande-
re Dateien auf dem Laufwerk werden in der Unix- und der Windows-Version von PHP
unterschiedlich behandelt:
> Auf Unix-Systemen sucht PHP Dateien ohne Pfadangabe in dem Verzeichnis, in dem
sich das Skript befindet.
> Unter Windows sucht PHP Dateien ohne Pfadangabe nur in dem Verzeichnis, in dem
sich die PHP-DLL befindet.
Um zu gewährleisten, dass Dateinamen unabhängig von der Plattform immer gleich be-
handelt werden, sollten Sie unbedingt die SearchPath-Funktion von PDFlib verwenden
(siehe Abschnitt 3.1.5, »Ressourcenkonfiguration und Dateisuche«, Seite 56).
2.9.2 Das Beispiel »Hello world« in PHP

Beispiel für PHP 4. Das folgende Codefragment zeigt ein Beispiel für PHP 4:
<?php
$p = PDF_new();
/* open new PDF file; insert a file name to create the PDF on disk */
if (PDF_begin_document($p, "", "") == 0) {
die("Error: " . PDF_get_errmsg($p));
}
PDF_set_info($p, "Creator", "hello.php");

PDF_set_info($p, "Author", "Rainer Schaaf");
PDF_set_info($p, "Title", "Hello world (PHP)!");
PDF_begin_page_ext($p, 595, 842, "");
$font = PDF_load_font($p, "Helvetica-Bold", "winansi", "");
PDF_setfont($p, $font, 24.0);

PDF_set_text_pos($p, 50, 700);

PDF_show($p, "Hello world!");
PDF_continue_text($p, "(says PHP)");
PDF_end_page_ext($p, "");
PDF_end_document($p, "");
$buf = PDF_get_buffer($p);
$len = strlen($buf);
header("Content-type: application/pdf");
header("Content-Length: $len");
header("Content-Disposition: inline; filename=hello.pdf");
print $buf;
PDF_delete($p);
?>
Beispiel für PHP 5. Das folgende Beispiel verwendet die neuen PHP-5-Funktionen zur
Ausnahmebehandlung und Objektkapselung:
<?php
try {
$p = new PDFlib();
/* open new PDF file; insert a file name to create the PDF on disk */
if ($p->begin_document("", "") == 0) {
die("Error: " . $p->get_errmsg());
}
$p->set_info("Creator", "hello.php");
$p->set_info("Author", "Rainer Schaaf");
$p->set_info("Title", "Hello world (PHP)!");
$p->begin_page_ext(595, 842, "");
$font = $p->load_font("Helvetica-Bold", "winansi", "");
$p->setfont($font, 24.0);
$p->set_text_pos(50, 700);
$p->show("Hello world!");
$p->continue_text("(says PHP)");
$p->end_page_ext("");
$p->end_document("");
$buf = $p->get_buffer();
$len = strlen($buf);
header("Content-type: application/pdf");
header("Content-Length: $len");
header("Content-Disposition: inline; filename=hello.pdf");
print $buf;
}
catch (PDFlibException $e) {
die("PDFlib exception occurred in hello sample:\n" .
"[" . $e->get_errnum() . "] " . $e->get_apiname() . ": " .
$e->get_errmsg() . "\n");
}
catch (Exception $e) {
die($e);
}
$p = 0;
?>
2.9.3 Fehlerbehandlung in PHP

Fehlerbehandlung in PHP 4. Tritt eine PDFlib-Exception auf, so wird eine PHP-Excepti-
on ausgelöst. Da PHP 4 keine strukturierte Ausnahmebehandlung unterstützt, gibt es
keine Möglichkeit, Exceptions abzufangen und angemessen zu verarbeiten. Deaktivie-
ren Sie PHP-Warnungen beim Einsatz von PDFlib keinesfalls, da Sie sonst in ernsthafte
Schwierigkeiten geraten.
PDFlib-Warnungen (nicht-fatale Fehler) werden auf PHP-Warnungen abgebildet, die
sich in php.ini deaktivieren lassen. Alternativ dazu können Warnungen wie in allen an-
deren Sprachbindungen auch zur Laufzeit mit einer PDFlib-Funktion deaktiviert wer-
den:
PDF_set_parameter($p, "warning", "false");
Ausnahmebehandlung in PHP 5. Da PHP 5 strukturierte Ausnahmebehandlung unter-

stützt, werden PDFlib-Exceptions als PHP-Exceptions weitergeleitet. PDFlib löst im Feh-
lerfall eine Ausnahme vom Typ PDFlib-Exception aus, die von der PHP-Standardklasse
Exception abgeleitet ist. PDFlib-Exceptions können also mit der üblichen Kombination
aus try und catch abgefangen werden:
try {
.. PDFlib-Anweisungen...
} catch (PDFlibException $e) {

print "PDFlib-Exception aufgetreten:\n";
print "[" . $e->get_errnum() . "] " . $e->get_apiname() . ": "
$e->get_errmsg() . "\n";
}
catch (Exception $e) {
print $e;
}
Beachten Sie, dass Sie die von PHP 5 unterstützte Ausnahmebehandlung sowohl mit der
alten funktionsorientierten, als auch mit der neuen objektorientierten PDFlib-Schnitt-
stelle verwenden können.

2.10 Python-Sprachbindung
2.10.1 Installation der Python-Edition von PDFlib
Der Erweiterungsmechanismus von Python1 lädt dynamische Bibliotheken zur Laufzeit.
Damit die PDFlib-Sprachbindung funktioniert, benötigt der Python-Interpreter Zugriff
auf den PDFlib-Python-Wrapper.
Unix. Die Bibliothek pdflib_py.so (unter Mac OS X: pdflib_py.dylib) wird in allen Ver-
zeichnissen gesucht, die in der Umgebungsvariablen PYTHONPATH festgelegt sind.
Windows. Die Bibliothek pdflib_py.dll wird in allen Verzeichnissen gesucht, die in der
Umgebungsvariablen PYTHONPATH festgelegt sind.
2.10.2 Das Beispiel »Hello world« in Python

from sys import *
from pdflib_py import *
p = PDF_new()
if PDF_begin_document(p, "hello.pdf", "") == -1:

print "Error: " + PDF_get_errmsg(p) + "\n"
exit(2)
PDF_set_info(p, "Author", "Thomas Merz")

PDF_set_info(p, "Creator", "hello.py")
PDF_set_info(p, "Title", "Hello world (Python)")
PDF_begin_page_ext(p, 595, 842, "")
font = PDF_load_font(p, "Helvetica-Bold", "winansi", "")
PDF_setfont(p, font, 24)

PDF_set_text_pos(p, 50, 700)
PDF_show(p, "Hello world!")
PDF_continue_text(p, "(says Python)")
PDF_end_page_ext(p, "")
PDF_end_document(p, "")
PDF_delete(p)
2.10.3 Fehlerbehandlung in Python

Die Python-Sprachbindung installiert einen speziellen Error-Handler, der PDFlib-Fehler
in native Python-Exceptions übersetzt. Die Python-Exceptions können mit der üblichen
Kombination aus try und catch behandelt werden, zum Beispiel:
try:
1. Siehe www.python.org
2.10 Python-Sprachbindung 41
except:
print 'Exception abgefangen!'
2.11 REALbasic-Sprachbindung1
2.12 RPG-Sprachbindung
PDFlib bietet ein /copy-Modul, das alle Prototypen sowie einige nützliche Konstanten
definiert, die zur Kompilierung von ILE-RPG-Programmen mit eingebetteten PDFlib-
Funktionen benötigt werden.
Da alle von PDFlib bereitgestellten Funktionen in der Sprache C implementiert sind,
müssen Sie am Ende jedes String-Wertes, der an eine PDFlib-Funktion übergeben wird,
x'00' anfügen. Alle von PDFlib zurückgegebenen Strings werden ebenfalls mit x'00' be-
endet.
2.12.1 Kompilieren und Binden von RPG-Programmen für PDFlib

Zum Einsatz von PDFlib-Funktionen mit RPG ist das kompilierte PDFlib-Servicepro-
gramm erforderlich. Um die PDFlib-Definitionen zur Kompilierzeit in Ihr ILE-RPG-Pro-
gramm einzufügen, müssen Sie diese in den D-Anweisungen per /COPY-Anweisung an-
geben:
d/copy QRPGLESRC,PDFLIB
Wenn die PDFlib-Quelldateibibliothek sich nicht am Anfang Ihrer Bibliotheksliste be-

findet, müssen Sie zudem die Bibliothek angeben:
d/copy PDFsrclib/QRPGLESRC,PDFLIB
Bevor Sie mit der Kompilierung des ILE-RPG-Programms beginnen, müssen Sie ein Bin-
dungsverzeichnis anlegen, das das mit PDFlib ausgelieferte PDFlib-Serviceprogramm
enthält. Das folgende Beispiel zeigt, wie Sie in der Bibliothek PDFLIB das Bindungsver-
zeichnis PDFLIB erstellen:
CRTBNDDIR BNDDIR(PDFLIB/PDFLIB) TEXT('PDFlib Binding Directory')
Nach dem Anlegen des Bindungsverzeichnisses müssen Sie das PDFLIB-Servicepro-

gramm zu Ihrem Bindungsverzeichnis hinzufügen. Das folgende Beispiel zeigt, wie Sie
das Serviceprogramm PDFLIB in der Bibliothek PDFLIB zum bereits erzeugten Bindungs-
verzeichnis hinzufügen:
ADDBNDDIRE BNDDIR(PDFLIB/PDFLIB) OBJ((PDFLIB/PDFLIB *SRVPGM))
Sie können Ihr Programm nun mit dem Befehl CRTBNDRPG (oder der Option 14 in PDM)
kompilieren:
1. Siehe www.realbasic.com

CRTBNDRPG PGM(PDFLIB/HELLO) SRCFILE(PDFLIB/QRPGLESRC) SRCMBR(*PGM) DFTACTGRP(*NO)
BNDDIR(PDFLIB/PDFLIB)
2.12.2 Das Beispiel »Hello world« in RPG

*****************************************************************************************
*****************************************************************************************
d p S *
d font s 10i 0
*
d error s 50
d errmsg_p s *
d errmsg s 200 based(errmsg_p)
*
d filename s 256
d fontname s 50
d fontenc s 50
d infokey s 50
d infoval s 200
d text s 200
d n s 1 inz(x'00')
d empty s 1 inz(x'00')
*****************************************************************************************
c clear error
*
* Init on PDFlib
c eval p=pdf_new
c if p=*null
c eval error='Couldn''t create PDFlib object '+
c '(out of memory)!'
c exsr exit
c endif
*
* Open new pdf file
c eval filename='hello.pdf'+x'00'
c if PDF_begin_document(p:filename:0:empty) = -1
c exsr geterrmsg
c exsr exit
c endif
* This is required to avoid problems on Japanese systems
c eval infokey='hypertextencoding'+x'00'
c eval infoval='ebcdic'+x'00'
c callp PDF_set_parameter(p:infokey:infoval)
* Set info "Creator"
c eval infokey='Creator'+x'00'
c eval infoval='hello.rpg'+x'00'
c callp PDF_set_info(p:infokey:infoval)
* Set info "Author"
c eval infokey='Author'+x'00'
c eval infoval='Thomas Merz'+x'00'
* Set info "Title"
c eval infokey='Title'+x'00'
c eval infoval='Hello, world (RPG)!'+x'00'
c callp PDF_begin_page_ext(p:a4_width:a4_height:
c empty)
*
c eval fontname='Helvetica-Bold'+x'00'
c eval fontenc='ebcdic'+x'00'
c eval font=PDF_load_font(p:fontname:0:fontenc:n)
*
c callp PDF_setfont(p:font:24)
c callp PDF_set_text_pos(p:50:700)
*
c eval text='Hello world!'+x'00'
c callp PDF_show(p:text)
c eval text='(says ILE RPG)'+x'00'
c callp PDF_continue_text(p:text)
c callp PDF_end_page_ext(p:empty)
c callp PDF_end_document(p:empty)
c callp PDF_delete(p)
*
c exsr exit
*****************************************************************************************
c geterrmsg begsr
c eval errmsg_p=PDF_get_errmsg(p)
c if errmsg_p<>*NULL
c eval error=%subst(errmsg:1:%scan(x'00':errmsg)-1)
c endif
c endsr
*****************************************************************************************
c exit begsr
c if error<>*blanks
c eval error='Error: '+error
c error dsply
c endif
c seton lr
c return
c endsr
Dieses Programm lässt sich wie folgt kompilieren:

CRTBNDDIR BNDDIR(PDFLIB/PDFLIB) TEXT('PDFlib Binding Directory')
ADDBNDDIRE BNDDIR(PDFLIB/PDFLIB) OBJ((PDFLIB/PDFLIB *SRVPGM))
CRTBNDRPG PGM(PDFLIB/HELLO) SRCFILE(PDFLIB/QRPGLESRC) SRCMBR(*PGM) DFTACTGRP(*NO) +
BNDDIR(PDFLIB/PDFLIB)
2.12.3 Fehlerbehandlung in RPG

In ILE-RPG geschriebene PDFlib-Clients können in PDFlib einen Error-Handler installie-
ren, der beim Auftreten einer Exception aktiviert wird. Da ILE-RPG die Namen von Pro-
zeduren prinzipiell in Großbuchstaben konvertiert, sollte der Name der Fehlerbehand-
lungsprozedur aus Großbuchstaben bestehen. Das folgende Fragment zeigt das
Verfahren:
*****************************************************************************************
*****************************************************************************************
d p S *
d font s 10i 0
*
d error s 50
*
d errhdl s * procptr

*
* Prototyp für Fehlerbehandlungsprozedur
*
d errhandler PR
d p * value
d type 10i 0 value
d shortmsg 2048
*****************************************************************************************
c clear error
*
* Prozedurzeiger auf Prozedur ERRHANDLER setzen.
*
c eval errhdl=%paddr('ERRHANDLER')
*
c eval p=pdf_new2(errhdl:*null:*null:*null:*null)
*
c exsr exit
*****************************************************************************************
c exit begsr
c if error<>*blanks
c error dsply
c endif
c seton lr
c return
c endsr
*****************************************************************************************
* Wenn eine der PDFlib-Funktionen eine Exception auslöst, wird zuerst der
* Error-Handler aufgerufen. Danach erhalten wir eine reguläre RPG-Exception.
c *pssr begsr
c exsr exit
c endsr
*****************************************************************************************
* Fehlerbehandlungsprozedur
* Diese Prozedur wird an PDFlib gebunden, indem der Prozedurzeiger an PDF_new2
* übergeben wird. Sie wird beim Auftreten einer PDFlib-Exception aufgerufen.
*
*****************************************************************************************
p errhandler B
d errhandler PI
d p * value
d type 10i 0 value
d c_message 2048
*
d length s 10i 0
*
* x'00' am Ende entfernen (wir werden von einem C-Programm aufgerufen)
* und Fehler-String (global) setzen
c clear error
c x'00' scan c_message length 50
c sub 1 length
c if *in50 and length>0
c if length>%size(error)
c eval error=c_message
c else
c eval error=%subst(c_message:1:length)
c endif
c endif
*
* Immer PDF_delete aufrufen, um PDFlib zu bereinigen
*
c return
*
p errhandler E
2.13 Ruby-Sprachbindung
2.13.1 Installation der Ruby-Edition von PDFlib
Der Erweiterungsmechanismus von Ruby1 lädt eine dynamische Bibliothek zur Lauf-
zeit. Damit die PDFlib-Sprachbindung funktioniert, benötigt der Ruby-Interpreter Zu-
griff auf die PDFlib-Erweiterungsbibliothek für Ruby. Diese Bibliothek (unter Windows/
Linux/Unix: PDFlib.so; auf Mac OS X: PDFlib.dylib) wird normalerweise im Unterverzeich-
nis site_ruby des lokalen Ruby-Installationsverzeichnisses installiert, das heißt in einem
Verzeichnis mit etwa folgendem Namen:
/usr/local/lib/ruby/site_ruby/<rubyversion>/
Ruby durchsucht aber auch andere Verzeichnisse nach Erweiterungen. Mit folgendem
Ruby-Aufruf erhalten Sie eine Liste dieser Verzeichnisse:
ruby -e "puts $:"
Diese Liste enthält in der Regel auch das aktuelle Verzeichnis, so dass Sie die PDFlib-Er-
weiterungsbibliothek und die Skripte zum Testen einfach ins gleiche Verzeichnis stel-
len können.
2.13.2 Das Beispiel »Hello world« in Ruby

require 'PDFlib'
begin
p = PDFlib.new
if (p.begin_document("hello.pdf", "") == -1)

raise "Error: " + p.get_errmsg
end
p.set_info("Creator", "hello.rb")
p.set_info("Author", "Thomas Merz")
p.set_info("Title", "Hello world (Ruby)!")
p.begin_page_ext(595, 842, "")
font = p.load_font("Helvetica-Bold", "winansi", "")
1. Siehe www.ruby-lang.org/en

p.setfont(font, 24)
p.set_text_pos(50, 700)
p.show("Hello world!")
p.continue_text("(says Ruby)")
p.end_page_ext("")
p.end_document("")
rescue PDFlibException => pe

print "PDFlib exception occurred in hello sample:\n"
print "[" + pe.get_errnum.to_s + "] " + pe.get_apiname + \
": " + pe.get_errmsg + "\n"
rescue Exception => e
print e.backtrace.join("\n") + "\n" + e.to_s
end
2.13.3 Fehlerbehandlung in Ruby

Die Ruby-Sprachbindung installiert einen speziellen Error-Handler, der PDFlib-Excepti-
ons in native Ruby-Exceptions übersetzt. Die Ruby-Exceptions können mit der üblichen
rescue-Technik behandelt werden:
begin
rescue PDFlibException => pe
print "PDFlib-Exception im Hello-Beispiel aufgetreten:\n"
print "[" + pe.get_errnum.to_s + "] " + pe.get_apiname + ": " + pe.get_errmsg + "\n"
2.13.4 Ruby on Rails

Ruby on Rails1 ist ein Open-Source-Framework, das die Web-Entwicklung mit Ruby er-
leichtert. Die PDFlib-Erweiterung für Ruby ist auch mit Ruby on Rails einsetzbar; ent-
sprechende Beispiele sind im Paket enthalten. Um die PDFlib-Beispiele für Ruby on Rails
auszuführen, gehen Sie wie folgt vor:
> Installieren Sie Ruby.
> Installieren Sie Ruby on Rails.
> Entpacken Sie das PDFlib-Paket für Ruby, das die Beispiele für Ruby on Rails enthält.
> Wechseln Sie ins Verzeichnis bind/ruby/RubyOnRails und starten Sie den Ruby-Web-
Server:
ruby script/server
> Geben Sie im Browser http://localhost:3000 ein.
Der Code für die PDFlib-Beispiele befindet sich in app/controllers/pdflib_controller.rb.
Lokale PDFlib-Installation. Wenn Sie PDFlib nur mit Ruby on Rails einsetzen möchten
und nicht global zum allgemeinen Einsatz mit Ruby installieren können, können Sie
PDFlib auch lokal im Verzeichnis vendors in der Rails-Hierarchie installieren. Dies ist ins-
besondere dann nützlich, wenn Sie nicht über die Berechtigung verfügen, allgemeine
Ruby-Erweiterungen zu installieren, aber in Rails mit PDFlib arbeiten möchten.
1. Siehe www.rubyonrails.org
2.13 Ruby-Sprachbindung 47
2.14 Tcl-Sprachbindung
2.14.1 Installation der PDFlib-Tcl-Edition
Der Erweiterungsmechanismus von Tcl 1 lädt dynamische Bibliotheken zur Laufzeit. Da-
mit die PDFlib-Bindung funktioniert, benötigt die Tcl-Shell Zugriff auf die dynamische
Bibliothek mit dem PDFlib-Wrapper für Tcl sowie auf die Paketindexdatei pkgIndex.tcl.
Um die Bibliothek von einem bestimmten Verzeichnis aus verfügbar zu machen, kön-
nen Sie in Ihrem Skript folgendes Idiom verwenden (dies mag sinnvoll sein, wenn Sie
PDFlib auf einem System ausführen, auf dem Sie keine Administrator-Berechtigung be-
sitzen und PDFlib somit nicht installieren können):
lappend auto_path /path/to/pdflib
Unix. Die Bibliothek pdflib_tcl.so (unter Mac OS X: pdflib_tcl.dylib) muss in eines der
Standardverzeichnisse für dynamische Bibliotheken kopiert werden oder in ein anderes
entsprechend konfiguriertes Verzeichnis. Die Dateien pkgIndex.tcl und pdflib_tcl.so wer-
den normalerweise in folgendes Verzeichnis gestellt:
/usr/lib/tcl8.3/pdflib
Windows. Die Dateien pkgIndex.tcl und pdflib_tcl.dll werden in folgenden Verzeichnis-

sen gesucht:
C:\Programme\Tcl\lib\pdflib
C:\Programme\Tcl\lib\tcl8.3\pdflib
2.14.2 Das Beispiel »Hello world« in Tcl

package require pdflib 6.0
set p [PDF_new]
if {[PDF_begin_document $p "hello.pdf" ""] == -1} {

puts stderr "Error: [PDF_get_errmsg $p]"
exit
}
PDF_set_info $p "Creator" "hello.tcl"

PDF_set_info $p "Author" "Thomas Merz"
PDF_set_info $p "Title" "Hello world (Tcl)"
PDF_begin_page_ext $p 595 842 ""
set font [PDF_load_font $p "Helvetica-Bold" "unicode" ""]
PDF_setfont $p $font 24.0

PDF_set_text_pos $p 50 700
PDF_show $p "Hello world!"
PDF_continue_text $p "(says Tcl)"
PDF_end_page_ext $p ""
1. Siehe dev.scriptics.com

PDF_end_document $p ""
PDF_delete $p
2.14.3 Fehlerbehandlung in Tcl

Die Tcl-Sprachbindung installiert einen speziellen Error-Handler, der PDFlib-Fehler in
native Tcl-Exceptions übersetzt. Die Tcl-Exceptions können mit der üblichen Kombina-
tion aus try und catch behandelt werden:
if [ catch { ...PDFlib-Anweisungen... } result ] {
puts stderr "Exception abgefangen!"
puts stderr $result
}
2.14 Tcl-Sprachbindung 49
3 PDFlib-Programmierung
3.1 Allgemeine Aspekte
3.1.1 PDFlib-Programmstruktur und Geltungsbereich von Funktionen
PDFlib-Anwendungen müssen sich an einige strukturelle Regeln halten, die sehr ein-
fach zu verstehen sind. Es ist sehr einfach, Anwendungen unter Einhaltung dieser Be-
dingungen zu schreiben. So wird man eine Seite zum Beispiel kaum schließen, bevor
man sie geöffnet hat. Da sich das PDFlib-API eng an die herkömmliche Auffassung eines
aus einzelnen Seiten bestehenden Dokuments anlehnt, erhält man in der Regel korrek-
te PDFlib-Clientprogramme, wenn man ein Dokument einfach auf ganz »natürliche«
Art und Weise anlegt.
PDFlib erzwingt die korrekte Reihenfolge von Funktionsaufrufen durch streng defi-
nierte Geltungsbereiche (so genannte scopes). Jede Funktionsbeschreibung enthält auch
Angaben über den jeweiligen Geltungsbereich. Der Aufruf einer Funktion in einem an-
deren Geltungsbereich löst eine PDFlib-Exception aus. PDFlib löst außerdem eine Ex-
ception aus, wenn die von einem Bibliotheksclient übergebenen Parameter nicht kor-
rekt sind.
In den Funktionsbeschreibungen in Kapitel 8 wird auch der jeweilige Geltungsbe-
reich angeführt. Tabelle 3.1 definiert die verschiedenen Geltungsbereiche, während Ab-
bildung 3.1 ihre Verschachtelung veranschaulicht. PDFlib löst eine Exception aus, wenn
eine Funktion außerhalb ihres zulässigen Geltungsbereichs aufgerufen wird. Der aktu-
elle Geltungsbereich kann mit dem Parameter scope abgefragt werden.
Tabelle 3.1 Geltungsbereiche für Funktionen

Name Definition
path beginnt mit PDF_moveto( ), PDF_circle( ), PDF_arc( ), PDF_arcn( ) oder PDF_rect( ) und endet mit
einer der Funktionen aus Abschnitt 8.4.6, »Zeichnen und Beschneiden von Pfaden«, Seite 280
page zwischen PDF_begin_page( ) und PDF_end_page( ), aber außerhalb von path
template zwischen PDF_begin_template( ) und PDF_end_template( ), aber außerhalb von path
pattern zwischen PDF_begin_pattern( ) und PDF_end_pattern( ), aber außerhalb von path
font zwischen PDF_begin_font( ) und PDF_end_font( ), aber außerhalb von glyph
glyph zwischen PDF_begin_glyph( ) und PDF_end_glyph( ), aber außerhalb von path
document zwischen PDF_begin_document( ) und PDF_end_document( ), aber außerhalb von page,
template, pattern und font
object in Java: solange ein pdflib-Objekt vorhanden ist, aber außerhalb von document;
in anderen Bindungen: zwischen PDF_new( ) und PDF_delete( ), aber außerhalb von document
null außerhalb von object
beliebig Wird in einer Funktionsbeschreibung als Geltungsbereich »beliebig« angeführt, ist damit jeder
Geltungsbereich außer null gemeint, da dort noch nicht einmal ein PDFlib-Objekt vorhanden ist.
3.1.2 Parameter
Die Arbeitsweise von PDFlib lässt sich durch zahlreiche globale Parameter steuern. Sie
behalten ihre Einstellungen während der gesamten Lebensdauer des PDFlib-Objekts bei,

null object document page page page page
path path ...
template pattern font

glyph glyph glyph
path path
document page page page page
path path ...
template pattern font

glyph
path path
Abb. 3.1
Verschachtelung der ...
Geltungsbereiche
sofern sie nicht explizit vom Client geändert werden. Zur Parameterbehandlung sind
folgende Funktionen vorgesehen:
> PDF_set_parameter( ) zum Setzen von Parametern vom Typ string.
> PDF_set_value( ) zum Setzen von Parametern mit numerischen Werten.
> PDF_get_parameter( ) zur Abfrage von Parametern vom Typ string.
> PDF_get_value( ) zur Abfrage der Werte numerischer Parameter.
Weitere Informationen über die Namen und Werte der einzelnen Parameter finden Sie
in Kapitel 8.
3.1.3 Behandlung von Ausnahmen (Exceptions)

Eine bestimmte Art von Fehlern wird in vielen Sprachen zurecht als Ausnahme
(Exception) bezeichnet – es handelt sich um bloße Ausnahmesituationen, die während
eines Programmlaufs nicht allzu häufig erwartet werden. Die generelle Strategie be-
steht darin, konventionelle Verfahren zur Fehlerbenachrichtigung (also besondere
Funktionsrückgabewerte) für solche Funktionsaufrufe zu verwenden, die häufig zu Feh-
lern führen. Besondere Verfahren zur Ausnahmebehandlung setzt man dagegen in sel-
ten zu erwartenden Fällen ein, wo man den Code nicht mit if-Abfragen zupflastern
möchte. Diese Methode wird auch von PDFlib verfolgt. So geht man bei manchen Opera-
tionen davon aus, dass sie relativ häufig schiefgehen, zum Beispiel:
> der Versuch, ohne geeignete Berechtigung eine Ausgabedatei zu öffnen
> der Versuch, eine Eingabe-PDF-Datei mit einem falschen Pfadnamen zu öffnen
> der Versuch, eine beschädigte Bilddatei zu öffnen
PDFlib zeigt solche Fehler durch die Rückgabe eines speziellen Wertes an (normalerwei-
se – 1, aber 0 in der PHP-Sprachbindung), der bei den einzelnen Funktionen in Kapitel 8
52 Kapitel 3: PDFlib-Programmierung
beschrieben wird. Andere Ereignisse können als schädlich angesehen werden, aber eher
selten auftreten, zum Beispiel:
> es ist kein Speicher mehr verfügbar
> Verletzungen des Geltungsbereichs (zum Beispiel das Schließen eines Dokuments
vor dem Öffnen)
> die Übergabe falscher Parameter an PDFlib-Funktionen (zum Beispiel der Versuch,
einen Kreis mit negativem Radius zu zeichnen)
Stößt PDFlib auf eine solche Ausnahmesituation, so wird eine Exception ausgelöst, um
auf die Situation zu reagieren, ohne dass spezielle Werte an die aufrufende Funktion zu-
rückgegeben werden. In der Programmiersprache C, die Exceptions nicht direkt unter-
stützt, kann der Client eine eigene Fehlerbehandlungsroutine (einen so genannten Er-
ror-Handler) installieren, die im Falle einer Exception aufgerufen wird. Es wird jedoch
empfohlen, mit PDF_TRY( )/PDF_CATCH( )-Blöcken zu arbeiten (siehe Abschnitt 2.4.4,
»Fehlerbehandlung in C«, Seite 28).
Es ist wichtig sich klarzumachen, dass die Generierung des PDF-Dokuments nicht ab-
geschlossen werden kann, wenn eine Exception auftritt. Die einzigen Methoden, die
nach einer Exception noch aufgerufen werden können, sind PDF_delete( ), PDF_get_
apiname( ), PDF_get_errnum( ) und PDF_get_errmsg( ). Alle anderen PDFlib-Methoden lie-
fern unzuverlässige Ergebnisse. Die Exception (oder die an den C-Error-Handler überge-
benen Daten) umfassen folgende Informationen:
> eine eindeutige Fehlernummer (siehe Tabelle 3.2)
> der Name der PDFlib-API-Funktion, die die Exception ausgelöst hat
> ein beschreibender Text mit detaillierten Angaben zum Problem
Tabelle 3.2 Nummernbereiche für PDFlib-Exceptions

Fehlernummern Auslöser
1000 – 1999 (PDCORE-Bibliothek): Speicher, Ein-/Ausgabe, Argumente, Parameter/Werte, Optionen
2000 – 2999 (PDFlib-Bibliothek): Konfiguration, Geltungsbereich, Grafik und Text, Farbe, Bilder,
Schriften, Zeichensätze, PDF/X, Hypertext, Tagged PDF, Ebenen
4000 – 4999 (PDF-Importbibliothek PDI): Konfiguration und Parameter, Fehler in der gesamten Datei,
einem einzelnen Objekt oder einem Datenstrom, wobei ein Datenstrom zum Beispiel eine
Seitenbeschreibung enthält
Deaktivieren von Exceptions. Manche Exceptions können deaktiviert werden. Diese

lassen sich in zwei Kategorien unterteilen: nicht-fatale Fehler (Warnungen) und Fehler,
die je nach Client eine Exception rechtfertigen mögen oder nicht. Warnungen weisen in
der Regel auf ein Problem in Ihrem PDFlib-Code hin, das Sie näher untersuchen sollten.
Die Verarbeitung kann nach nicht-fatalen Fehlern jedoch fortgeführt werden. Aus die-
sem Grund lassen sich Warnungen mit folgendem Funktionsaufruf unterbinden:
PDF_set_parameter(p, "warning", "false");
Neben dem globalen Parameter warning unterstützen manche Funktionen Optionen,

mit denen sich Warnungen für individuelle Funktionsaufrufe aktivieren oder deak-
tivieren lassen. Als Strategie ist zu empfehlen, Warnungen im Entwicklungsstadium zu
aktivieren (und genau zu untersuchen) und im laufenden Betrieb zu deaktivieren.
Ein und dieselbe Operation mag für manche Clients fatal sein, während andere adä-
quat auf die Situation reagieren. Das Verhalten der PDFlib-API-Funktionen kann durch
Parameter bestimmt werden, etwa beim Laden von Schriften, Bildern, PDF-Importdoku-

menten und ICC-Profilen. Kann eine Schrift zum Beispiel aufgrund von Konfigurations-
problemen nicht geladen werden, mag der eine Client daran scheitern, während ein an-
derer darauf mit der Auswahl einer Ersatzschrift reagiert. Ist der Parameter oder die
Option fontwarning auf true gesetzt, wird eine Exception ausgelöst, wenn das Laden der
Schrift fehlschlägt. Andernfalls gibt die Funktion stattdessen einen Fehlercode zurück.
Der Parameter kann wie folgt gesetzt werden:
PDF_set_parameter(p, "fontwarning", "false");
Abfragen der Ursache für einen gescheiterten Funktionsaufruf. Wie oben erwähnt,
muss die Generierung der PDF-Ausgabe beim Auftreten einer Exception auf jeden Fall
abgebrochen werden. Manche Clients mögen es aber vorziehen, durch Anpassung eini-
ger Parameter mit dem Dokument fortzufahren. Kann beispielsweise ein bestimmter
Font nicht geladen werden, brechen die meisten Clients die Dokumentgenerierung ab;
es mag aber auch Clients geben, die mit einem anderen Font fortfahren möchten. Eine
derartige Differenzierung lässt sich mit den Parametern fontwarning etc. erreichen. In
obigem Fall wäre es vielleicht wünschenswert, die Fehlermeldung zu erhalten, die Teil
der Exception ist. Dazu können direkt nach einem gescheiterten Funktionsaufruf , das
heißt, nach einem Funktionsaufruf, der den Fehlerwert -1 (in PHP: 0) liefert, die Funktio-
nen PDF_get_errnum( ), PDF_get_errmsg( ) und PDF_get_apiname( ) aufgerufen werden.
Die folgenden Codefragmente zeigen verschiedene Strategien in bezug auf die Aus-
nahmebehandlung. Die Beispiele versuchen, einen Font zu laden und einzubetten,
wobei davon ausgegangen wird, dass der Font nicht verfügbar ist.
Ist der Parameter oder die Option fontwarning gleich true (der Standardfall), muss die
Dokumentgenerierung abgebrochen werden:
font = PDF_load_font(p, "MeinFontName", 0, "winansi", "fontwarning=true");
/* wenn keine Exception ausgelöst wurde, ist das Font-Handle gültig;
* wurde eine Exception ausgelöst, kann die PDF-Ausgabe nicht fortgesetzt werden
*/
Ist der Parameter fontwarning gleich false, muss überprüft werden, ob der Rückgabewert
gültig ist:
font = PDF_load_font(p, "MeinFontName", 0, "winansi", "fontwarning=false";
if (font == -1) {
/* Font-Handle ist ungültig; Ursache herausfinden. */
errmsg = PDF_get_errmsg(p);
/* Fehlermeldung protokollieren */
/* Anderen Font probieren oder aufgeben */
...
}
/* Font-Handle ist gültig; weiter wie üblich */
Ist der Parameter fontwarning gleich false und weist der Rückgabewert auf einen Fehler
hin, kann die Fehlerursache abgefragt werden, um angemessen auf die Situation reagie-
ren zu können:
PDF_set_parameter(p, "fontwarning", "false");
font = PDF_load_font(p, "MeinFontName", 0, "winansi", "embed";
if (font == -1) {
/* Font-Handle ist ungültig; Ursache herausfinden. */
errmsg = PDF_get_errmsg(p);
/* Fehlermeldung protokollieren */
/* Anderen Font probieren oder aufgeben */
...
}
/* Font-Handle ist gültig; weiter wie üblich */
3.1.4 Das PDFlib Virtual File System (PVF)

Neben Dateien im Dateisystem gibt es eine Technik namens PDFlib Virtual File System
(PVF), die es Clients ermöglicht, Daten direkt im Speicher zu übergeben. Dies ist weitaus
schneller und kann zum Beispiel für Daten verwendet werden, die aus einer Datenbank
stammen und gar nicht einzeln als Datei existieren. Es sind ebenso Situationen denk-
bar, wo der Client die erforderlichen Daten als Ergebnis anderer Verarbeitungsschritte
bereits im Speicher zur Verfügung gestellt bekommt.
PVF basiert auf dem Konzept virtueller Read-Only-Dateien, deren Namen wie nor-
male Dateinamen in jeder API-Funktion verwendet werden können. Darüber hinaus
sind sie in UPR-Konfigurationsdateien einsetzbar. Die Namen für virtuelle Dateien kön-
nen vom Client auf beliebige Art erzeugt werden. Natürlich müssen sie so gewählt wer-
den, dass es keine Namenskonflikte mit regulären Dateien gibt. Deshalb sind für virtu-
elle Dateinamen folgende hierarchische Namenskonventionen empfehlenswert
(filename bezieht sich auf einen vom Client festgelegten Namen, der in der entsprechen-
den Kategorie eindeutig ist). Außerdem sollten übliche Namenssuffixe beibehalten
werden:
> Rasterbilddateien: /pvf/image/filename
> Font- und Metrikdateien (der tatsächliche Fontname sollte die Basis des Dateina-
mens bilden): /pvf/font/filename
> ICC-Profile: /pvf/iccprofile/filename
> Zeichensätze und Codepages: /pvf/codepage/filename
> PDF-Dokumente: /pvf/pdf/filename
Zum Auffinden einer Datei überprüft PDFlib zuerst, ob sich der Name auf eine virtuelle
Datei bezieht, und versucht dann, die Datei auf der Festplatte zu öffnen.
Lebensdauer virtueller Dateien. Manche Funktionen verwenden die in einer virtuel-

len Datei übergebenen Daten sofort, während andere einzelne Teile zu verschiedenen
Zeitpunkten lesen. Aus diesem Grund muss man die Lebensdauer virtueller Dateien be-
achten. PDFlib versieht jede virtuelle Datei mit einer internen Sperre, die erst wieder
entfernt wird, wenn der Dateiinhalt nicht mehr benötigt wird. Sofern der Client die Da-
ten (mit der Option copy in PDF_create_pvf( )) nicht sofort von PDFlib kopieren lässt, darf
er sie erst ändern, löschen oder freigeben, nachdem die Sperre von PDFlib aufgehoben
wurde. PDFlib löscht mit PDF_delete( ) automatisch auch alle virtuellen Dateien. Der ei-
gentliche Inhalt (die in der virtuellen Datei enthaltenen Daten) muss jedoch immer
vom Client freigegeben werden.
Verschiedene Strategien. Das PVF unterstützt verschiedene Ansätze im Hinblick auf

die für virtuelle Dateien erforderliche Speicherverwaltung. Diese sind darauf ausgerich-
tet, dass PDFlib nach dem API-Aufruf, der einen virtuellen Dateinamen verarbeitet hat,
unter Umständen Zugriff auf den Dateiinhalt benötigt, dass dies aber niemals nach
PDF_close( ) erforderlich ist. PDF_delete_pvf( ) gibt den eigentlichen Dateiinhalt nicht frei
(außer die Option copy wurde übergeben), sondern nur die für die PVF-Dateinamenver-
waltung verwendeten Datenstrukturen. Damit ergeben sich folgende Strategien:

> Minimieren des Speicherbedarfs: Es ist empfehlenswert, PDF_delete_pvf( ) unmittel-
bar nach dem API-Aufruf, der den virtuellen Dateinamen verarbeitet hat, auszufüh-
ren und ein weiteres Mal nach PDF_close( ). Der zweite Aufruf ist erforderlich, da
PDFlib unter Umständen noch Zugriff auf die Daten benötigt, so dass die Sperre auf
die virtuelle Datei eventuell beim ersten Aufruf nicht aufgehoben wird. Sicherlich
werden die Daten in einigen Fällen bereits beim ersten Aufruf freigegeben, aber der
zweite Aufruf richtet keinen Schaden an. Der Client kann den Dateiinhalt nur nach
erfolgreicher Ausführung von PDF_delete_pvf( ) freigeben.
> Optimieren der Geschwindigkeit durch mehrfache Verwendung virtueller Dateien:
Manche Clients möchten bestimmte Daten (zum Beispiel Fonts) vielleicht mehrmals
verwenden, etwa in verschiedenen Ausgabedokumenten, und sich eine Wiederho-
lung von create/delete-Zyklen für ein und denselben Dateiinhalt sparen. In diesem
Fall ist es empfehlenswert, PDF_delete_pvf( ) erst aufzurufen, wenn auf Basis der vir-
tuellen Datei keine weiteren PDF-Ausgabedokumente mehr generiert werden.
> Faule Programmierung: Ist der Speicherbedarf kein Thema, braucht der Client PDF_
delete_pvf( ) überhaupt nicht aufzurufen. In diesem Fall löscht PDFlib alle angelegten
virtuellen Dateien beim Aufruf von PDF_delete( ).
In allen Fällen darf der Client die entsprechenden Daten nur nach einem erfolgreichen
Aufruf von PDF_delete_pvf( ) oder nach PDF_delete( ) freigeben.
3.1.5 Ressourcenkonfiguration und Dateisuche

Bei den meisten komplexeren Anwendungen benötigt PDFlib Zugriff auf Ressourcen
wie Font- und Zeichensatzdateien, ICC-Farbprofile etc. Um die von PDFlib verarbeiteten
Ressourcen plattformunabhängig und benutzerdefinierbar zu machen, kann eine Kon-
figurationsdatei angegeben werden, in der die verfügbaren Ressourcen gemeinsam mit
ihren Dateinamen aufgeführt sind. Außerdem kann die Konfiguration dynamisch zur
Laufzeit durch Anfügen von Ressourcen mit PDF_set_parameter( ) erfolgen. Für die Kon-
figurationsdatei haben wir ein einfaches Textformat namens Unix PostScript Resource
(UPR) ausgegraben, das in der Ära von Display PostScript erfunden wurde und immer
noch auf diversen Systemen im Einsatz ist. Wir haben das ursprüngliche UPR-Format
für unsere Zwecke erweitert. Das von PDFlib verwendete UPR-Dateiformat wird unten
beschrieben. Es gibt zudem ein Hilfsprogramm namens makepsres (das oft mit dem X
Window System mitgeliefert wird), das aus PostScript-Font- und -Metrikdateien auto-
matisch UPR-Dateien generiert.
Unterstützte Ressourcenkategorien. Tabelle 3.3 führt die von PDFlib unterstützten

Ressourcenkategorien auf. Alle anderen Ressourcenkategorien werden ignoriert. Die
Werte werden als Name-Strings behandelt; sie können in ASCII oder UTF-8 mit einlei-
tendem BOM kodiert sein. Unicode-Werte können bei der Ressource HostFont bei lokali-
sierten Fontnamen nützlich sein.
Tabelle 3.3 In PDFlib unterstützte Ressourcenkategorien

Ressourcenkategoriename Erklärung
SearchPath Relativer oder absoluter Pfadname von Verzeichnissen mit Datenfiles
FontAFM PostScript-Fontmetrikdatei im AFM-Format
FontPFM PostScript-Fontmetrikdatei im PFM-Format
FontOutline PostScript-, TrueType- oder OpenType-Fontdatei
Tabelle 3.3 In PDFlib unterstützte Ressourcenkategorien
Ressourcenkategoriename Erklärung
Encoding Textdatei mit 8-Bit-Zeichensatz oder Codepagetabelle
HostFont Name einer im System installierten Schrift.
ICCProfile Name eines ICC-Farbprofils
StandardOutputIntent Name einer Standard-Druckausgabebedingung für PDF/X
Vermeiden Sie redundante Ressourceneinträge. Nehmen Sie zum Beispiel eine be-
stimmte Fontmetrikinformation nur einmal auf. Achten Sie zudem darauf, dass der
Schriftname in der UPR-Datei exakt mit dem tatsächlichen Schriftnamen überein-
stimmt (auch wenn PDFlib Abweichungen toleriert).
Auf Mac OS Classic muss der Doppelpunkt ’:’ als Trennzeichen in Verzeichnisanga-
ben verwendet werden. Die Schriftnamen der ressourcenbasierten PostScript-Type-1-
Schriften (LWFN-Fonts) müssen mit dem vollständigen Pfad einschließlich des Volume-
Namens angegeben werden:
Foo-Italic=Classic:Data:Fonts:FooIta
Das UPR-Dateiformat. UPR-Dateien liegen im Textformat vor und sind sehr einfach
aufgebaut, so dass sie problemlos manuell im Texteditor oder auch automatisch erstellt
werden können. Beginnen wir mit der Syntax:
> Eine Zeile besteht aus maximal 255 Zeichen.
> Ein Gegenschrägstrich ’\’ am Zeilenende bewirkt, dass die Zeile auch nach dem New-
line-Zeichen fortgeführt wird.
> Ein einzelner Punkt ’ . ’ dient als Abschnittsende.
> Es wird zwischen Groß- und Kleinschreibung unterschieden.
> Kommentare beginnen mit dem Prozentzeichen ’%’ und enden am Zeilenende.
> Leer- und Tabulatorzeichen werden ignoriert, außer in Ressourcen- und Datei-
namen.
UPR-Dateien bestehen aus folgenden Komponenten:

> Eine Kopfzeile zur Identifizierung der Datei, die folgendermaßen aussieht:
PS-Resources-1.0
> Ein optionaler Abschnitt, der alle Ressourcenkategorien auflistet, die in der Datei be-
schrieben werden. Jede Zeile beschreibt eine Kategorie. Die Liste wird mit einem
Punkt abgeschlossen. Die verfügbaren Ressourcenkategorien werden unten be-
schrieben.
> Ein Abschnitt für jede der Ressourcenkategorien, die am Dateianfang aufgeführt
wurden. Jeder Abschnitt beginnt mit einer Zeile für die Ressourcenkategorie, gefolgt
von einer beliebigen Anzahl von Zeilen, die die verfügbaren Ressourcen beschreiben.
Diese Liste wird durch eine Zeile mit einem einzelnen Punkt abgeschlossen. Jede Res-
sourcenzeile besteht aus dem Namen der Ressource (bei Gleichheitszeichen sind An-
führungszeichen erforderlich). Erfordert die Ressource einen Dateinamen, muss die-
ser nach einem Gleichheitszeichen angefügt werden. PDFlib berücksichtigt den
Parameter SearchPath (siehe unten) bei der Suche nach Dateien, deren Namen als
Ressourcen eingetragen sind.

Dateisuche und Ressourcenkategorie SearchPath. PDFlib liest verschiedenste Daten,
zum Beispiel Rasterbilder, Font- und Metrikdaten, Zeichensatzdefinitionen, PDF-Doku-
mente oder ICC-Farbprofile aus Dateien des Dateisystems. Neben relativen und absolu-
ten Pfadnamen können Sie Dateinamen auch ohne jede Pfadangabe verwenden. Dazu
definieren Sie mit der Ressourcenkategorie SearchPath eine Liste von Pfadnamen für die
Verzeichnisse, die die benötigten Dateien enthalten. Beim Öffnen einer Datei versucht
PDFlib zuerst, diese mit genau dem übergebenen Dateinamen zu öffnen. Schlägt dieser
Versuch fehl, sucht PDFlib nacheinander in den Verzeichnissen, die in der Ressourcen-
kategorie SearchPath aufgeführt sind. Aus den SearchPath-Einträgen wird eine Liste auf-
gebaut, die in umgekehrter Reihenfolge durchsucht wird (später hinzugefügte Pfade
werden also zuerst durchsucht). Mit diesem Verfahren sind PDFlib-Anwendungen nicht
mehr von plattformspezifischen Dateisystemkonventionen abhängig. Um diesen Such-
mechanismus zu unterbinden, geben Sie in den jeweiligen PDFlib-Funktionsaufrufen
vollständige Pfadnamen an. Beachten Sie die folgenden plattformabhängigen Eigen-
schaften der Ressourcenkategorie SearchPath:
> Unter Windows initialisiert PDFlib die Ressourcenkategorie SearchPath mit einem
Eintrag aus der Registry. Der folgende Registryeintrag kann eine Liste von Pfadna-
men enthalten, die durch Strichpunkte ’;’ getrennt sind:
HKLM\SOFTWARE\PDFlib\PDFlib\6.0.3\SearchPath
> Auf den Systemen IBM iSeries wird die Ressourcenkategorie SearchPath mit folgen-
den Werten initialisiert:
/pdflib/6.0.3/fonts
/pdflib/6.0.3/bind/data
> Auf den Systemen IBM zSeries mit MVS wird die SearchPath-Funktion nicht unter-
stützt.
> Auf OpenVMS-Systemen können logische Namen als SearchPath übergeben werden.
UPR-Beispieldatei. Das folgende Listing zeigt ein Beispiel für eine UPR-Konfigurati-
onsdatei:
PS-Resources-1.0
SearchPath
/usr/local/lib/fonts
C:/psfonts/pfm
C:/psfonts
/users/kurt/my_images
.
FontAFM
Code-128=Code_128.afm
.
FontPFM
Corporate-Bold=corpb___.pfm
.
Mistral=c:/psfonts/pfm/mist____.pfm
.
FontOutline
Code-128=Code_128.pfa
ArialMT=Arial.ttf
.
Encoding
myencoding=myencoding.enc
.
ICCProfile
highspeedprinter=cmykhighspeed.icc
.
Suchen der UPR-Ressourcendatei. Sollen nur in PDFlib integrierte Ressourcen (zum

Beispiel PDF-Standardschriften, Systemzeichensätze, ICC-Profil sRGB) oder Systemres-
sourcen (Systemschriften) verwendet werden, dann ist keine UPR-Konfigurationsdatei
erforderlich, da PDFlib selbst über alle notwendigen Ressourcen verfügt.
Sollen andere Ressourcen verwendet werden, so können Sie diese mit PDF_set_
parameter( ) (siehe unten) oder in einer UPR-Ressourcendatei festlegen. PDFlib liest diese
Datei automatisch, sobald die erste Ressource abgefragt wird. Im Einzelnen wird wie
folgt vorgegangen:
> Ist die Umgebungsvariable PDFLIBRESOURCE definiert, verwendet PDFlib deren Wert
als Name für die zu lesende UPR-Datei. Kann diese Datei nicht gelesen werden, wird
eine Exception ausgelöst.
> Ist die Umgebungsvariable PDFLIBRESOURCE nicht definiert, versucht PDFlib eine
Datei mit folgendem Namen zu öffnen:
upr (unter MVS; ein Dataset wird erwartet)
pdflib/<version>/fonts/pdflib.upr (auf IBM eServer iSeries)
pdflib.upr (auf Windows, Unix und allen anderen Systemen)
Kann diese Datei nicht gelesen werden, wird eine Exception ausgelöst.
> Unter Windows versucht PDFlib zudem, den Registry-Eintrag
HKLM\SOFTWARE\PDFlib\PDFlib\6.0.3\resourcefile
zu lesen. Der Wert dieses Eintrags (der bei der PDFlib-Installation erzeugt wird, aber
auch anders generiert werden kann) wird als Name der zu lesenden Ressourcendatei
verwendet. Kann diese Datei nicht gelesen werden, wird eine Exception ausgelöst.
> Durch explizites Setzen des Parameters resourcefile kann der Client PDFlib veranlas-
sen, eine Ressourcendatei zur Laufzeit einzulesen:
PDF_set_parameter(p, "resourcefile", "/path/to/pdflib.upr");
Dieser Aufruf kann beliebig oft wiederholt werden; die Ressourceneinträge werden
akkumuliert.
Konfiguration von Ressourcen zur Laufzeit. Statt mit einer UPR-Datei zu arbeiten, kön-
nen Sie einzelne Ressourcen auch direkt mit der Funktion PDF_set_parameter( ) im
Quellcode konfigurieren. Diese Funktion erhält einen Kategorienamen sowie den zuge-
hörenden Ressourceneintrag so, wie diese auch im entsprechenden Abschnitt in der
UPR-Datei erscheinen, zum Beispiel:
PDF_set_parameter(p, "FontAFM", "Foobar-Bold=foobb___.afm")
PDF_set_parameter(p, "FontOutline", "Foobar-Bold=foobb___.pfa")
3.1.6 Erzeugen von PDF-Dokumenten im Arbeitsspeicher

Neben der Generierung von PDF-Dokumentdateien kann PDFlib auch dazu veranlasst
werden, PDF-Dokumente direkt im Arbeitsspeicher zu erzeugen (in-core). Dieses Verfah-
ren ist schneller, da kein Schreiben auf die Festplatte erforderlich ist. Das PDF-Doku-
ment könnte dann zum Beispiel direkt via HTTP übertragen werden. Es dürfte insbeson-

dere Webmaster erfreuen zu hören, dass die Server nicht unbedingt mit temporären
PDF-Dateien überhäuft werden müssen.
Mit dieser Art der PDF-Generierung können Sie die Daten entweder stückweise verar-
beiten (zum Beispiel jedes Mal, wenn eine Seite komplett ist) oder das vollständige PDF-
Dokument am Ende in einem Stück (nach PDF_end_document( )) verwenden. Die stück-
weise Generierung und Weiterverarbeitung der PDF-Daten ist in mehrerer Hinsicht vor-
teilhaft. Erstens sinken die Speicheranforderungen, da die Daten nicht vollständig im
Speicher vorgehalten werden müssen. Außerdem lässt sich die Leistung erheblich stei-
gern, wenn das erste Stück bereits über eine langsame Verbindung gesendet werden
kann, während das nächste Stück gerade generiert wird. Die Gesamtgröße der Daten ist
aber erst nach Abschluss des letzten Stücks bekannt.
Aktive Schnittstelle zur PDF-Generierung im Arbeitsspeicher. Um PDF-Daten im Ar-

beitsspeicher zu generieren, übergeben Sie an PDF_begin_document( ) einfach einen lee-
ren Dateinamen und holen die Daten über PDF_get_buffer( ) ab:
PDF_begin_document(p, "", "")
...Dokument erzeugen...
PDF_close(p);
buf = PDF_get_buffer(p, &size);

... aus dem Puffer gelesene PDF-Daten verarbeiten ...
PDF_delete(p);
Hinweis Die PDF-Daten im Puffer müssen als Binärdaten behandelt werden.
Dies wird als »aktiver« Modus bezeichnet, da der Client aktiv entscheidet, wann der
Pufferinhalt abgeholt werden soll. Der aktive Modus ist in allen unterstützten Sprach-
bindungen verfügbar.
Hinweis C- und C++-Clients dürfen den zurückgegebenen Puffer nicht freigeben.
Passive Schnittstelle zur PDF-Generierung im Arbeitsspeicher. Im »passiven« Modus,

der nur in den Sprachbindungen für C und C++ verfügbar ist, installiert der Benutzer
(via PDF_open_document_callback( )) eine Callback-Funktion, die von PDFlib zu nicht de-
terminierten Zeitpunkten aufgerufen wird, sobald PDF-Daten zur Abholung bereitste-
hen. Um maximale Flexibilität zu gewährleisten, kann vom Client konfiguriert werden,
in welcher Art das Leeren des Puffers (Flushing) erfolgt, das heißt, mit welchem Timing
und welcher Puffergröße die PDF-Daten von der Bibliothek zum Client übertragen wer-
den. Abhängig von der jeweiligen Umgebung mag es von Vorteil sein, das PDF-Doku-
ment auf einmal, in mehreren Stücken oder in vielen kleinen Abschnitten abzuholen,
damit PDFlib den internen Dokumentpuffer nicht vergrößern muss. Die gewünschte
Flushing-Strategie kann mit der Option flush für PDF_open_document_callback( )) einge-
stellt werden.
3.1.7 Einsatz von PDFlib auf EBCDIC-Systemen

Die Operatoren und Strukturelemente des Dateiformats PDF basieren auf ASCII. Auf
EBCDIC-Systemen wie IBM eServer iSeries 400 und zSeries S/390 ist es daher schwierig,
Textausgabe und PDF-Operatoren zu kombinieren. Aus diesem Grund wurde eine spezi-
elle Mainframe-Variante von PDFlib entwickelt, mit der sich auf ASCII basierende PDF-
Operatoren und auf EBCDIC (oder anderen Zeichensätzen) basierende Textausgabe
kombinieren lassen. Die EBCDIC-Variante von PDFlib ist für verschiedene Betriebssyste-
me und Rechnerarchitekturen verfügbar.
Um PDFlib-Funktionen auf EBCDIC-Systemen zu nutzen, müssen folgende Elemente
im EBCDIC-Format übergeben werden (genauer gesagt, in Codepage 037 auf iSeries und
Codepage 1047 auf zSeries):
> PFA-Fontdateien, UPR-Konfigurationsdateien, AFM-Metrikdateien
> Zeichensatz- und Codepagedateien
> String-Parameter für PDFlib-Funktionen
> Namen von Eingabe- und Ausgabedateien
> Umgebungsvariablen (sofern von der Laufzeitumgebung unterstützt)
> PDFlib-Fehlermeldungen werden ebenfalls im EBCDIC-Format erzeugt (außer in
Java).
Um Eingabedateien im ASCII-Format (PFA, UPR, AFM, Zeichensätze) zu verwenden, set-
zen Sie den Parameter asciifile auf true (Standardwert ist false). PDFlib erwartet diese Da-
teien dann im ASCII-Format. String-Parameter müssen aber nach wie vor in EBCDIC ko-
diert sein.
Im Gegensatz dazu müssen folgende Elemente immer binär behandelt werden (das
heißt, dass keinerlei Konvertierung durchgeführt werden darf):
> PDF-Eingabe und -Ausgabe-Dateien
> PFB-Fontdateien und PFM-Metrikdateien
> TrueType- und OpenType-Fontdateien
> Rasterbilddateien und ICC-Profile
3.1.8 Unterstützung für große Dateien

Wir benutzen die Bezeichung »große Dateien« in diesem Abschnitt für Dateien mit ei-
ner Größe über 2 GB. Auf den ersten Blick mag es nicht sehr sinnvoll erscheinen, so gro-
ßen Dateien anzulegen, doch es gibt tatsächlich Business-Anwendungen, die solche Da-
teien erzeugen oder verarbeiten müssen. Denken Sie zum Beispiel an ein einzelnes PDF-
Dokument, das eine große Zahl von Rechnungen oder Kontoauszügen enthält. In sol-
chen Situationen kann die Dateigröße leicht die Grenze von 2 GB übersteigen.
PDFlib unterstützt die Erstellung großer Dateien, d.h. Sie können damit PDF-Ausgabe
mit mehr als 2 GB erstellen. Ebenso unterstützt PDI die Verarbeitung großer Eingabeda-
teien. Die Unterstützung für große Dateien steht allerdings nur auf solchen Plattformen
zur Verfügung, auf denen das zugrunde liegende Betriebssystem selbst auch große Da-
teien unterstützt. Selbstverständlich muss auch das benutzte Dateisystem große Datei-
en unterstützen. Beachten Sie, dass Acrobat 6 und ältere Versionen nicht in der Lage
sind, große Dateien zu verarbeiten. Mit Acrobat 7 ist dies jedoch möglich.
Hinweis Importierte Dateien anderer Typen als PDF, etwa Fonts und Bilder, können die Grenze von 2 GB
nicht übersteigen. PDF-Ausgabedaten, die über die Schnittstelle PDF_get_buffer( ) abgeholt
werden, sind ebenfalls durch dieses Limit begrenzt. Beachten Sie schließlich noch, dass PDF-
Dateien generell nicht die Grenze von 1010 Byte übersteigen können, was ca. 9.3 GB entspricht.

3.2 Seitenbeschreibungen
3.2.1 Koordinatensysteme
PDFlib arbeitet mit dem Standardkoordinatensystem von PDF, das seinen Ursprung in
der linken unteren Ecke der Seite hat und auf der Einheit Punkt basiert:
1 pt = 1/72 Zoll = 2,54/72 cm = 0,3528 mm
Die erste Koordinate läuft nach rechts, die zweite nach oben. Das Standardkoordinaten-
system kann von PDFlib-Clientprogrammen durch Rotieren, Skalieren, Verschieben
oder Scheren modifiziert werden, so dass sich neue benutzerspezifische Koordinaten er-
geben. Für diese Transformationen werden die Funktionen PDF_rotate( ), PDF_scale( ),
PDF_translate( ) und PDF_skew( ) verwendet. Nach der Transformation müssen alle Koor-
dinaten in Grafik- und Textfunktionen an das neue Koordinatensystem angepasst
übergeben werden. Zu Beginn einer neuen Seite wird wieder auf das Standardkoordina-
tensystem umgestellt.
Verwendung metrischer Koordinaten. Durch eine Skalierung des Koordinatensystems

können Sie problemlos auch metrische Koordinaten einsetzen. Der Skalierungsfaktor
ergibt sich aus der Definition der Einheit Punkt oben:
PDF_scale(p, 28.3465, 28.3465);
Nach diesem Aufruf interpretiert PDFlib alle Koordinaten (außer für Hypertext-Funkti-
onen, siehe unten) in Zentimeter, da 72/2.54 = 28.3465.
Koordinaten für Hypertext-Elemente. Bei Hypertext-Funktionen, zum Beispiel bei

den Rechtecken von Notizen, Verknüpfungen oder Dateianlagen, geht PDF immer von
Koordinaten im Standardkoordinatensystem aus und nicht von einem (möglicherweise
transformierten) Benutzerkoordinatensystem. Da dies recht mühselig werden kann,
bietet PDFlib die automatische Umsetzung von Benutzerkoordinaten in das von PDF er-
wartete Format. Die automatische Konvertierung wird aktiviert, indem Sie den Parame-
ter usercoordinates auf true setzen:
PDF_set_parameter(p, "usercoordinates", "true");
Da PDF nur Hypertextrechtecke unterstützt, deren Kanten parallel zum Seitenrand ver-
laufen, müssen die übergebenen Rechtecke modifiziert werden, wenn das Koordinaten-
system durch Skalierung, Rotation, Verschiebung oder Scherung transformiert wurde.
In diesem Fall berechnet PDFlib das kleinste umschließende Rechteck mit Kanten paral-
lel zum Seitenrand, transformiert es in Standardkoordinaten und verwendet das Ergeb-
nis statt der übergebenen Koordinaten.
Damit haben Sie die Möglichkeit, Seitenbeschreibungen sowie Hypertext-Elemente
in einem einzigen Koordinatensystem zu definieren, sofern Sie den Parameter
usercoordinates auf true gesetzt haben.
Koordinatenanzeige. Um PDFlib-Anwendern beim Arbeiten mit dem Koodinatensys-

tem von PDF behilflich zu sein, enthält die PDFlib-Distribution die PDF-Datei grid.pdf,
die die Koordinaten für gängige Seitenformate zeigt. Als nützliches Hilfsmittel zur
PDFlib-Entwicklung können Sie sich die Seite mit dem für Sie interessanten Format auf
eine durchsichtige Folie ausdrucken.
Acrobat 6/7 (nur die Vollversion, nicht der kostenlose Reader) verfügt ebenfalls über
ein nützliches Hilfsmittel. Mit dem Menübefehl Anzeige, Navigationsregisterkarten, Info
können Sie verschiedene Koordinaten anzeigen. Um die angezeigte Maßeinheit zu än-
dern, wählen Sie eine Einheit aus dem Menü Optionen. Alternativ dazu wählen Sie
Bearbeiten, Grundeinstellungen..., [Allgemein...], Einheiten und Hilfslinien, [oder Seiten-
einheiten] und selektieren Punkt, Millimeter, Zoll, Pica oder Zentimeter. Beachten Sie da-
bei, dass sich die angezeigten Koordinaten auf einen Ursprung in der linken oberen
Ecke der Seite beziehen und nicht, wie in PDF üblich, auf die linke untere Ecke.
Lassen Sie sich nicht von PDF-Ausdrucken mit scheinbar falschem Seitenformat irri-
tieren. Häufig hat das eine der folgenden Ursachen:
> Im Druckdialog von Acrobat wurde eine der Optionen Kleine Seiten auf Seitengröße
vergrößern oder Große Seiten auf Seitengröße verkleinern aktiviert, was zu einer Skalie-
rung des Ausdrucks führt.
> Nicht-PostScript-Druckertreiber können Objekte nicht immer in ihrer exakten Größe
drucken.
Drehen von Objekten. Es ist wichtig sich klarzumachen, dass Objekte nicht mehr ver-
ändert werden können, nachdem sie auf der Seite gezeichnet wurden. Es gibt zwar
PDFlib-Funktionen zum Drehen, Verschieben, Skalieren und Scheren des Koordinaten-
systems, diese wirken sich aber nicht auf bereits auf der Seite vorhandene Objekte aus,
sondern nur auf später gezeichnete. Mit der Option orientate für die Funktionen PDF_
fit_textline( ), PDF_fit_image( ) und PDF_fit_pdi_page( ) ist es problemlos möglich, Text,
Rasterbilder oder importierte PDF-Seiten um 90˚ oder ein Vielfaches davon zu drehen.
Drehungen um beliebige Winkel lassen sich mit den allgemeinen Funktionen zur
Koordinatentransformation bewerkstelligen. Das folgende Beispiel generiert erst ein
wenig horizontalen Text, dann wird das Koordinatensystem gedreht, um Text gedreht
auszugeben. Das Sichern und Wiederherstellen des Grafikkontexts (mit save/restore) er-
möglicht es, nach der Ausgabe des vertikalen Texts ohne weiteres wieder horizontalen
Text im ursprünglichen Koordinatensystem auszugeben:
PDF_show(p, "Dies ist horizontaler Text");
textx = PDF_get_value(p, "textx", 0); /* Textposition bestimmen */
texty = PDF_get_value(p, "texty", 0); /* Textposition bestimmen */
PDF_save(p);
PDF_translate(p, textx, texty); /* Ursprung an Textende verschieben */
PDF_rotate(p, 45); /* Koordinaten drehen */
PDF_set_text_pos(p, 18, 0); /* Abstand von horizontalem Text vorsehen */
PDF_show(p, "Gedrehter Text");
PDF_restore(p);
PDF_continue_text(p, "Weiterer horizontaler Text");
Top-Down-Koordinaten. Im Gegensatz zum Bottom-Up-Koordinatensystem von PDF

arbeiten manche grafischen Umgebungen mit Top-Down-Koordinaten, bei denen der
Ursprung des Systems links oben liegt und die y-Koordinaten nach unten wachsen.
Wenn Sie diese Art vorziehen, können Sie sich das entsprechende Koordinatensystem
problemlos mit den Transformationsfunktionen von PDFlib einrichten. Da die Trans-
formationen aber auch die Textausgabe beeinflussen, sind weitere Aufrufe erforderlich,
damit der Text nicht gespiegelt erscheint.
Um den Einsatz von Top-Down-Koordinaten zu erleichtern, unterstützt PDFlib einen
besonderen Modus, in dem alle relevanten Koordinaten entsprechend anders interpre-
tiert werden: Statt des PDF-Standardkoordinatensystems mit dem Ursprung (0, 0) in der
linken unteren Ecke der Seite, in dem die y-Koordinaten von unten nach oben wachsen,
wird ein Koordinatensystem verwendet, dessen Ursprung in der linken oberen Ecke
liegt, wobei die y-Koordinaten nach unten hin größer werden. Dieses Top-Down-Koordi-
natensystem kann mit dem Parameter topdown aktiviert werden:
PDF_set_parameter(p, "topdown", "true")
Für jede Seite kann ein eigenes Koordinatensystem eingerichtet werden. Der Parameter
topdown darf aber nicht innerhalb einer Seitenbeschreibung (sondern nur zwischen den
Seiten) gesetzt werden. Die topdown-Funktionalität soll es PDFlib-Benutzern ermögli-
chen, auf einfache Art in einem Top-Down-Koordinatensystem zu arbeiten. Der Voll-
ständigkeit halber folgt eine detaillierte Aufstellung aller Elemente, bei denen sich
durch die Einrichtung eines Top-Down-Koordinatensystems Änderungen ergeben.
»Absolute« Koordinaten werden im Benutzerkoordinatensystem wie üblich und un-
verändert interpretiert:
> Alle Funktionsparameter, die in Funktionsbeschreibungen als »Koordinaten« be-
zeichnet werden. Zum Beispiel: x, y in PDF_moveto( ); x, y in PDF_circle( ), x, y (aber
nicht width und height!) in PDF_rect( ); llx, lly, urx, ury in PDF_create_annotation( )).
»Relative« Koordinatenwerte werden durch interne Änderung an das Topdown-System

angepasst:
> Text (mit positiver Schriftgröße) wird zum oberen Seitenrand hin ausgerichtet.
> Wenn im Handbuch von der »linken unteren« Ecke eines Rechtecks oder einer Box
etc. die Rede ist, wird dies so interpretiert, wie Sie es auch auf der Seite sehen.
> Wird ein Drehwinkel festgelegt, bleibt das Rotationszentrum im Ursprung (0, 0) des
Benutzerkoordinatensystems. Eine Drehung im Uhrzeigersinn wird immer noch wie
eine solche wahrgenommen.
3.2.2 Höchstwerte für Seiten und Koordinaten

Übliche Seitenformate. Zum schnellen Nachschlagen enthält Tabelle 3.4 übliche Sei-
tenformate1. Für die Optionen width und height in PDF_begin/end_page_ext( ) können
symbolische Seitenformatnamen verwendet werden. Ihr Aufbau ist <format>.width und
1. Weitere Informationen über ISO-Formate, japanische Formate und US-Standardformate finden Sie unter folgenden URLs:
home.inter.net/eds/paper/papersize.html, www.cl.cam.ac.uk/~mgk25/iso-paper.html
<format>.height, wobei <format> eines der in Tabelle 3.4 aufgeführten Formate bezeich-
net (Beispiel in Kleinbuchstaben: a4.width)
Tabelle 3.4 Übliche Seitenmaße in Punkt

Format Breite Höhe Format Breite Höhe Format Breite Höhe
A0 2380 3368 A4 595 842 letter 612 792
A1 1684 2380 A5 421 595 legal 612 1008
A2 1190 1684 A6 297 421 ledger 1224 792
A3 842 1190 B5 501 709 11 x 17 792 1224
Seitengröße. Im Gegensatz zu PDF und PDFlib, die keinerlei Einschränkungen hin-

sichtlich der verwendbaren Seitengröße aufweisen, unterliegt Acrobat einigen Be-
schränkungen. Andere PDF-Interpreter können aber durchaus mit größeren oder klei-
neren Formaten umgehen. PDFlib gibt eine nicht-fatale Exception aus, wenn die für
Acrobat spezifischen Grenzen überschritten werden. Tabelle 3.5 zeigt die Einschränkun-
gen bezüglich der Seitengröße in Acrobat.
Tabelle 3.5 Minimale und maximale Seitengröße von Acrobat

PDF-Viewer Minimale Seitengröße Maximale Seitengröße
Acrobat 4 und höher 1/24" = 3 pt = 0.106 cm 200" = 14400 pt = 508 cm
Verschiedene Angaben für die Seitengröße. Während bei vielen PDFlib-Anwendungen

nur die Höhe und Breite der Seite festgelegt wird, können in speziellen Anwendungen
(insbesondere für die Druckvorstufe) zusätzliche Größenangaben wünschenswert sein.
PDFlib unterstützt alle in PDF möglichen Größenangaben. PDFlib-Clients können fol-
gende Größenangaben verwenden, die in unterschiedlichen Situationen sinnvoll sind:
> MediaBox: beschreibt die Größe des Ausgabemediums und entspricht unserer her-
kömmlichen Vorstellung von der Seitengröße.
> CropBox: gibt an, mit welcher Größe Acrobat die Seite anzeigt und druckt.
> TrimBox: beschreibt die Größe der (eventuell beschnittenen) Endseite.
> ArtBox: beschreibt den Teilbereich einer PDF-Seite, der für die Montage auf einer an-
deren Seite gedacht ist.
> BleedBox: gibt an, auf welche Größe die Seite in einer Produktionsumgebung be-
schnitten werden soll, und berücksichtigt eventuell benötigte Druckformaterweite-
rungen, die wegen Ungenauigkeiten im Produktionsprozess nötig sind.
PDFlib verwendet keinen dieser Werte intern, sondern schreibt sie lediglich in die Aus-
gabedatei. Standardmäßig wird eine MediaBox entsprechend der für die Seite festgeleg-
ten Höhe und Breite, aber keiner der anderen Einträge erzeugt. Das folgende Codefrag-
ment beginnt eine neue Seite und setzt die vier Werte für die CropBox:
/* neue Seite mit selbstdefinierter CropBox beginnen */
PDF_begin_page_ext(p, 595, 842, "cropbox {10 10 500 800}");
Anzahl der Seiten im Dokument. In PDFlib gibt es keine Begrenzung für die Anzahl der
Seiten in einem Dokument. PDFlib generiert PDF-Strukturen, anhand derer Acrobat
auch Dokumente mit hunderten oder tausenden von Seiten effizient anzeigen kann.
Ausgabegenauigkeit und Koordinatenbereich. Die Genauigkeit numerischer Werte in
der PDFlib-Ausgabe wurde sehr sorgsam danach bemessen, den Anforderungen von
PDF und der unterstützten Umgebungen zu genügen und dabei gleichzeitig eine mög-
lichst geringe Dateigröße zu erzeugen. Wie in Tabelle 3.6 ausgeführt, hängt die Genauig-
keit von PDFlib von den absoluten Koordinatenwerten ab. Dieser Aspekt kann zwar sehr
häufig ignoriert werden, bei manchen anspruchsvollen Anwendungen ist jedoch darauf
zu achten, bei Skalierungsoperationen die PDF-inhärenten Koordinatengrenzen nicht
zu überschreiten.
Tabelle 3.6 Ausgabegenauigkeit und Koordinatenbereich

Absoluter Wert Ausgabe
0 ... 0.000015 0
0.000015 ... 32767.999999 Rundung auf vier Dezimalstellen
32768 ... 231- 1 Rundung auf die nächste ganze Zahl (Integer)
>= 231 Auslösen einer Exception
3.2.3 Pfade
Ein Pfad ist eine Form, die aus einer beliebigen Anzahl von geraden Linien, Rechtecken
oder Kurven besteht. Er kann aus mehreren getrennten Abschnitten, so genannten Teil-
pfaden, bestehen. Auf einen Pfad können verschiedene Operationen angewandt werden
(siehe Abschnitt 8.4.6, »Zeichnen und Beschneiden von Pfaden«, Seite 280):
> Beim Stroking (Zeichnen) wird der Pfad selbst gezeichnet, wobei die vom Client über-
gebenen Zeichenparameter (etwa Farbe und Strichstärke) berücksichtigt werden.
> Beim Filling (Füllen) wird der gesamte vom Pfad eingeschlossene Bereich gezeichnet,
wobei die vom Client übergebenen Füllungsparameter berücksichtigt werden.
> Beim Clipping (Beschneiden) wird der Abbildungsbereich für nachfolgende Zeichen-
operationen verkleinert, indem der aktuelle Clipping-Bereich (standardmäßig die
ganze Seite) durch die Schnittmenge aus dem aktuellen Clipping-Bereich und dem
Pfad ersetzt wird.
> Wenn man den Pfad einfach beendet, ergibt das einen Pfad, der zwar in der PDF-
Datei vorhanden, aber unsichtbar ist. Dies wird aber nur selten genutzt.
Es führt zu einem Fehler, wenn Sie einen Pfad konstruieren, ohne eine der obigen Ope-
rationen auf ihn anzuwenden. Durch das System der Geltungsbereiche stellt PDFlib si-
cher, dass sich Clients an diese Einschränkung halten. Wenn Sie die Darstellungseigen-
schaften eines Pfades ändern möchten (zum Beispiel Farbe oder Strichstärke), so
müssen sie dies vor jeglichen Zeichenoperationen tun. Alle diesbezüglichen Regeln las-
sen sich zusammenfassen zu: »In einer Pfaddefinition darf die Darstellung nicht geän-
dert werden.«
Die bloße Konstruktion eines Pfads ist auf der Seite nicht wahrnehmbar; Sie müssen
den Pfad explizit zeichnen oder füllen, um sichtbare Ergebnisse zu erzielen:
PDF_moveto(p, 100, 100);
PDF_lineto(p, 200, 100);
PDF_stroke(p);
Die meisten Grafikfunktionen arbeiten mit dem Konzept eines aktuellen Punkts, den
man sich wie die momentane Stiftposition beim Zeichnen vorstellen kann.
3.2.4 Templates
Templates in PDF. PDFlib unterstützt ein PDF-Merkmal, das technisch »XObject vom
Typ Form« (form XObject) heißt. Da diese Bezeichnung jedoch leicht mit interaktiven
Formularen verwechselt werden kann, verwenden wir stattdessen die Bezeichnung
Templates. Ein PDFlib-Template kann man sich als Puffer außerhalb der Seite vorstellen,
in den Text, Vektorgrafiken und Rasterbilder umgelenkt werden (statt sich regulär auf
der Seite zu befinden). Nachdem das Template angelegt worden ist, kann es ähnlich ei-
nem Rasterbild verwendet und beliebig oft auf beliebigen Seiten platziert werden. Wie
Rasterbilder können Templates geometrisch transformiert, zum Beispiel skaliert oder
geschert werden. Wird ein Template auf mehreren Seiten (oder auf einer Seite mehr-
mals) verwendet, werden die PDF-Operatoren, die für die Konstruktion des Templates
zuständig sind, nur einmal in die PDF-Datei aufgenommen, was die Größe der Ausgabe-
datei entsprechend verringert. Templates eignen sich für Elemente, die wiederholt auf
mehreren Seiten auftreten, zum Beispiel ein feststehender Hintergrund, ein Firmenlo-
go oder grafische Elemente, die aus CAD-Software oder Software für Landkarten stam-
men. Templates werden zudem häufig für Schnitt- und Registermarken oder benutzer-
definierte asiatische Glyphen verwendet.
Einsatz von Templates mit PDFlib. Templates können nur außerhalb einer Seitenbe-
schreibung definiert, aber innerhalb einer Seitenbeschreibung verwendet werden. Temp-
lates können weitere Templates enthalten. Dabei gilt natürlich die Einschränkung, dass
ein Template nicht in seiner eigenen Definition verwendet werden darf. Um ein bereits
definiertes Template auf einer Seite zu referenzieren, verwenden Sie die Funktion PDF_
fit_image( ) genauso wie Sie Bilder auf der Seite platzieren (siehe Abschnitt 5.3, »Platzie-
ren von Bildern und importierten PDF-Seiten«, Seite 159). Das generelle Codefragment
hierfür sieht wie folgt aus:
/* Template definieren */
template = PDF_begin_template(p, template_width, template_height);
...mit Text-, Vektorgrafik- und Rasterbildfunktionen zeichnen...
PDF_end_template(p);
...
PDF_begin_page(p, page_width, page_height);
/* Template verwenden */
PDF_fit_image(p, template, (float) 0.0, (float) 0.0, "");
...weitere Zeichenoperationen...
PDF_end_page(p);
...
PDF_close_image(p, template);
Auf einem Template können alle Text-, Grafik- und Farbfunktionen benutzt werden.
Während der Konstruktion des Templates dürfen jedoch folgende Funktionen nicht
verwendet werden:
> Die Funktionen in Abschnitt 8.6, »Rasterbild- und Template-Funktionen«, Seite 294,
außer PDF_place_image( ), PDF_fit_image( ) und PDF_close_image( ). Dies stellt keine
große Einschränkung dar, da Rasterbilder außerhalb einer Template-Definition ge-
öffnet und innerhalb eines Templates frei verwendet (aber eben nicht geöffnet) wer-
den dürfen.
> Die Funktionen in Abschnitt 8.9, »Hypertext-Funktionen«, Seite 317. Hypertext-Ele-
mente müssen immer auf der Seite definiert werden, auf der sie im Dokument er-
scheinen sollen. Sie können nicht als Bestandteil eines Templates generiert werden.
Template-Unterstützung in Software von Drittanbietern. Templates (Form XObjects)

sind integraler Bestandteil der PDF-Spezifikation und können mit Acrobat problemlos
angezeigt und gedruckt werden. Da diese Art von PDF-Konstrukt von Acrobat Distiller
jedoch nur sehr selten generiert wird, können nicht alle PDF-Viewer damit umgehen.
Der PDF-Editor PitStop 5.0 ist zwar in der Lage, Templates zu verschieben, kann aber
nicht auf einzelne Elemente innerhalb eines Templates zugreifen. Adobe Illustrator 9
und 10 dagegen bieten vollständige Template-Unterstützung.
3.3 Farbe
3.3.1 Farben und Farbräume
PDFlib-Clients können die Farben festlegen, die zum Zeichnen und Füllen von Pfaden
und Buchstaben verwendet werden sollen. Farben können in mehreren Farbräumen de-
finiert werden:
> Graustufen zwischen 0=schwarz und 1=weiß
> RGB-Tripel, das heißt drei Werte zwischen 0 und 1, die den Anteil von Rot, Grün und
Blau festlegen: (0, 0, 0)=schwarz, (1, 1, 1)=weiß
> Vier CMYK-Werte für Cyan, Magenta, Yellow (Gelb) und Black (Schwarz), zwischen
0=keine Farbe und 1=volle Farbe; (0, 0, 0, 0)=weiß, (0, 0, 0, 1)=schwarz; beachten Sie
den Unterschied zur RGB-Definition.
> Geräteunabhängige Farben im Farbraum CIE L*a*b* werden über einen Helligkeits-
wert (luminance) zwischen 0 und 100 und zwei Farbwerte zwischen -127 und 128 fest-
gelegt (siehe Abschnitt 3.3.4, »Colormanagement und ICC-Profile«, Seite 73).
> ICC-basierte Farben werden mittels eines ICC-Profils definiert (siehe Abschnitt 3.3.4,
»Colormanagement und ICC-Profile«, Seite 73).
> Schmuckfarbe (Separation-Farbraum): eine vordefinierte oder eine selbstdefinierte
Farbe beliebigen Namens mit einer alternativen Darstellung in einem der oben er-
wähnten Farbräume; sie wird generell für die Erstellung von Dokumenten verwen-
det, die auf einer Druckmaschine mit einer oder mehreren kundenspezifischen Far-
ben gedruckt werden sollen. Der Farbauftrag liegt zwischen 0=keine Farbe und
1=maximale Intensität der Schmuckfarbe. Eine Liste der Schmuckfarbnamen finden
Sie in Abschnitt 3.3.3, »Schmuckfarben«, Seite 70.
> Füllmuster: Kachelung mit einem Objekt, das aus beliebigem Text, Vektorgrafiken
oder Rasterbildern besteht (siehe Abschnitt 3.3.2, »Füllmuster und Farbverläufe«, Sei-
te 69)
> Farbverläufe liefern einen kontinuierlichen Übergang zwischen zwei Farben und ba-
sieren auf einem anderen Farbraum (siehe Abschnitt 3.3.2, »Füllmuster und Farbver-
läufe«, Seite 69).
> Der Index-Farbraum stellt an sich keinen eigenen Farbraum dar, sondern dient zur
effizienten Kodierung eines anderen Farbraums. Er wird automatisch erzeugt, wenn
ein indiziertes (auf einer Farbpalette basierendes) Bild importiert wird.
Die Standardfarbe zum Zeichnen und Füllen ist schwarz.
3.3.2 Füllmuster und Farbverläufe

Alternativ zu flächigen Farben können Objekte mit besonderen Farbarten, und zwar
Füllmustern oder Farbverläufen gezeichnet oder gefüllt werden.
Füllmuster. Ein Füllmuster (Pattern) ist durch eine beliebige Anzahl von Operationen
zum Auftragen von Farbe definiert, die in einer einzigen Einheit zusammengefasst wer-
den. Diese Einheit kann auf ein beliebiges anderes Objekt angewandt werden, indem sie
wiederholt (oder gekachelt) über den gesamten zu füllenden Bereich oder zu zeichnen-
den Pfad aufgetragen wird. Die Arbeit mit Füllmustern umfasst folgende Schritte:
> Zuerst wird zwischen PDF_begin_pattern( ) und PDF_end_pattern( ) das Füllmuster de-
finiert. Dazu können die meisten Grafikoperatoren herangezogen werden.
3.3 Farbe 69
> Mit dem von PDF_begin_pattern( ) zurückgegebenen Füllmuster-Handle kann das
Füllmuster mit PDF_setcolor( ) zur aktuellen Farbe gemacht werden.
Abhängig vom Parameter painttype von PDF_begin_pattern( ) wird die Farbe des Füllmus-
ters festgelegt. Ist painttype gleich 1, muss die Füllmusterdefinition eine eigene Farbspe-
zifikation enthalten und sieht damit immer gleich aus; ist painttype gleich 2, darf die
Füllmusterdefinition keine eigene Farbspezifikation enthalten. Das Füllmuster wird
dann in der jeweils aktuellen Füll- oder Zeichenfarbe aufgetragen.
Hinweis Füllmuster können auch auf Basis eines Farbverlaufs definiert werden (siehe unten).
Farbverläufe. Farbverläufe (Blends oder Smooth Shadings) bilden einen kontinuierli-

chen Übergang zwischen zwei Farben. Die beiden Farben müssen im selben Farbraum
definiert sein. PDFlib unterstützt zwei geometrische Formen für Farbverläufe:
> axiale Verläufe verlaufen entlang einer Geraden;
> radiale Verläufe verlaufen zwischen zwei Kreisen.
Farbverläufe werden als Übergang zwischen zwei Farben definiert. Die erste Farbe ent-
spricht immer der aktuellen Füllfarbe; die zweite Farbe wird in den Parametern c1, c2, c3
und c4 von PDF_shading( ) übergeben. Diese numerischen Werte werden im Farbraum
der ersten Farbe gemäß der Beschreibung von PDF_setcolor( ) interpretiert.
PDF_shading( ) gibt ein Handle auf ein Farbverlaufsobjekt zurück, das zu zwei Zwe-
cken verwendet werden kann:
> Füllen einer Fläche mit PDF_shfill( ). Dieses Verfahren kann verwendet werden, wenn
die Geometrie des zu füllenden Objekts der Geometrie des Farbverlaufs entspricht.
Trotz ihres Namens füllt diese Funktion nicht nur das Innere des Objekts, sondern
wirkt sich auch auf den Außenbereich aus. Dieses Verhalten kann mit PDF_clip( ) ge-
ändert werden.
> Definition eines Pattern für einen Farbverlauf zum Füllen komplexerer Objekte.
Dazu muss zunächst mit PDF_shading_pattern( ) ein Pattern erzeugt werden, das auf
dem Farbverlauf basiert. Mit diesem Pattern können dann beliebige Objekte gefüllt
oder gezeichnet werden.
3.3.3 Schmuckfarben
PDFlib unterstützt Schmuckfarben (spot color, in der PDF-Fachsprache als Separation-
Farbraum bezeichnet, obwohl der Ausdruck Separation im Allgemeinen auch für Pro-
zessfarben verwendet wird). Diese können zur Ausgabe von benutzerdefinierten Farben
verwendet werden, die außerhalb des Bereichs von Farbe liegen, die aus Prozessfarben
gemischt werden können. Schmuckfarben sind durch ihren Namen definiert und treten
in PDF immer gemeinsam mit einer Alternativfarbe auf, die der Schmuckfarbe mög-
lichst ähnlich ist. Die Alternativfarbe wird in Acrobat zur Bildschirmanzeige und zur
Ausgabe auf Geräten verwendet, die keine Schmuckfarben unterstützen (zum Beispiel
Bürodrucker). Auf der Druckmaschine wird die geforderte Schmuckfarbe zusätzlich zu
den im Dokument benutzten Prozessfarben angewandt. Dazu müssen die PDF-Dateien
einen weiteren Prozessschritt durchlaufen, die so genannte Farbseparation.
Hinweis Wenn in Acrobat 5 die Überdruckenvorschau aktiviert ist, werden manche Schmuckfarben
nicht korrekt angezeigt. Sie lassen sich aber korrekt separieren und drucken.
In PDFlib sind verschiedene Schmuckfarbbibliotheken integriert. Außerdem werden be-

nutzerdefinierte Schmuckfarben unterstützt. Wird ein Schmuckfarbname mit PDF_
makespotcolor( ) angefordert, überprüft PDFlib zunächst, ob diese Schmuckfarbe in einer
der integrierten Bibliotheken verzeichnet ist. Ist dies der Fall, verwendet PDFlib inte-
grierte Werte für die Alternativfarbe. Anderenfalls wird von einer benutzerdefinierten
Schmuckfarbe ausgegangen und der Client muss geeignete Werte für die Alternativfar-
be liefern (über die aktuelle Farbe). Schmuckfarben können mit einem Farbauftrag, das
heißt mit einem Prozentwert zwischen 0 und 1 versehen werden.
Standardmäßig können integrierte Schmuckfarben nicht mit benutzerdefinierten
Alternativfarben umdefiniert werden. Dieses Verhalten lässt sich mit dem Parameter
spotcolorlookup ändern, etwa um die Kompatibilität zu älteren Anwendungen zu ge-
währleisten, die andere Farbdefinitionen verwenden, oder um Workflows zu unterstüt-
zen, die mit den von PDFlib erzeugten Lab-Alternativfarben für Pantone-Farben nicht
zurechtkommen.
PDFlib generiert für integrierte Schmuckfarben automatisch geeignete Alternativ-
farben, sofern eine der PDF/X-Kompatibilitätsstufen gewählt wurde (siehe Abschnitt
7.4, »PDF/X«, Seite 201). Bei benutzerdefinierten Schmuckfarben liegt es in der Verant-
wortung des Benutzers, zur gewählten PDF/X-Kompatibilitätsstufe passende Alterna-
tivfarben bereitzustellen.
Hinweis Die Daten für integrierte Schmuckfarben und die zugehörigen Markenzeichen wurden von den
jeweiligen Inhabern für den Einsatz in der PDFlib-Software lizenziert.
PANTONE®-Farben. PANTONE-Farben sind weit verbreitet und

weltweit im Einsatz. PDFlib bietet volle Unterstützung für das
PANTONE MATCHING SYSTEM®, das insgesamt etwa 20 000 Farb-
töne umfasst. Sie können alle Farbnamen aus den folgenden digi-
talen Farbbibliotheken verwenden (Beispielnamen werden in
Klammern angegeben):
> PANTONE solid coated (PANTONE 185 C)
> PANTONE solid uncoated (PANTONE 185 U)
> PANTONE solid matte (PANTONE 185 M)
> PANTONE process coated (PANTONE DS 35-1 C)
> PANTONE process uncoated (PANTONE DS 35-1 U)
> PANTONE process coated EURO (PANTONE DE 35-1 C)
> PANTONE pastel coated (PANTONE 9461 C)
> PANTONE pastel uncoated (PANTONE 9461 U)
> PANTONE metallic coated (PANTONE 871 C)
> PANTONE solid to process coated (PANTONE 185 PC)
> PANTONE solid to process coated EURO (PANTONE 185 EC)
> PANTONE hexachrome® coated (PANTONE H 305-1 C)
> PANTONE hexachrome® uncoated (PANTONE H 305-1 U)
> PANTONE solid in hexachrome coated (PANTONE 185 HC)
Inhaber kommerzieller PDFlib-Lizenzen erhalten von unserem Support auf Anfrage

eine Textdatei mit einer Liste aller Pantone-Schmuckfarbnamen.
Bei Schmuckfarbnamen wird zwischen Groß- und Kleinschreibung unterschieden;
schreiben Sie die Namen deshalb wie in den Beispielen in Großbuchstaben. Es werden
auch die alten Namenspräfixe CV, CVV, CVU, CVC und CVP akzeptiert. Wie die Beispiele
zeigen, beginnt der Farbname immer mit dem Präfix PANTONE. Generell müssen PANTO-
NE-Farbnamen nach folgendem Schema aufgebaut sein:
3.3 Farbe 71
PANTONE <Id> <Papiersorte>
wobei <Id> die Farbe (zum Beispiel 185) bezeichnet und <Papiersorte> die englische Ab-
kürzung für die verwendete Papiersorte ist (zum Beispiel C für coated, das heißt be-
schichtet). Die Namensbestandteile werden durch jeweils ein einzelnes Leerzeichen ge-
trennt. Wenn Sie eine Schmuckfarbe abrufen, deren Name zwar mit dem Präfix
PANTONE beginnt, aber keine existierende PANTONE-Farbe bezeichnet, so führt dies zu
einer nicht-fatalen Exception (Sie können dieses Verhalten deaktivieren, indem Sie den
Parameter warning auf false setzen). Das folgende Codefragment zeigt den Einsatz einer
PANTONE-Farbe mit einem Farbauftrag von 70 Prozent:
spot = PDF_makespotcolor(p, "PANTONE 281 U", 0);

PDF_setcolor(p, "fill", "spot", spot, 0.7, 0, 0);
Hinweis Die hier angezeigten PANTONE®-Farben stimmen nicht unbedingt mit den PANTONE-Stan-
dards überein. Die genaue Farbe können Sie in den PANTONE-Farbtafeln nachschlagen.
PANTONE® und andere Warenzeichen von Pantone, Inc. sind Eigentum von Pantone, Inc. ©
Pantone, Inc., 2003.
Hinweis PANTONE®-Farben werden gegenwärtig nicht in den Modi PDF/X-1:2001, PDF/X-1a:2001 und
PDF/X-1a:2003 unterstützt.
HKS®-Farben. Das HKS-Farbsystem ist in Deutschland und

anderen europäischen Ländern weit verbreitet. PDFlib bietet
volle Unterstützung für HKS-Farben. Sie können alle Farbna-
men aus den folgenden digitalen Farbbibliotheken (Farb-
fächer) verwenden (Beispielnamen werden in Klammern an-
gegeben):
> HKS K (Kunstdruckpapier), 88 Farben (HKS 43 K)
> HKS N (Naturpapier), 86 Farben (HKS 43 N)
> HKS E (Endlospapier) beschichtet, 88 Farben (HKS 43 E)
> HKS Z (Zeitungspapier), 50 Farben (HKS 43 Z)
Inhaber kommerzieller PDFlib-Lizenzen erhalten von unserem Support auf Anfrage

eine Textdatei mit einer Liste aller HKS-Schmuckfarbnamen.
Bei Schmuckfarbnamen wird zwischen Groß- und Kleinschreibung unterschieden;
schreiben Sie die Namen deshalb wie in den Beispielen in Großbuchstaben. Wie die Bei-
spiele zeigen, beginnt der Farbname immer mit dem Präfix HKS. Generell müssen HKS-
Farbnamen nach folgendem Schema aufgebaut sein:
HKS <Id> <Papiersorte>
wobei <Id> die Farbe (zum Beispiel 43) bezeichnet und <Papiersorte> die Abkürzung für
die verwendete Papiersorte ist (zum Beispiel N für Naturpapier). Die Namensbestandtei-
le HKS, <Id> und <Papiersorte> werden jeweils durch ein einzelnes Leerzeichen getrennt.
Wenn Sie eine Schmuckfarbe abrufen, deren Name zwar mit dem Präfix HKS beginnt,
aber keine existierende HKS-Farbe bezeichnet, so führt dies zu einer nicht-fatalen Ex-
ception (Sie können dieses Verhalten deaktivieren, indem Sie den Parameter warning
auf false setzen). Das folgende Codefragment zeigt den Einsatz einer HKS-Farbe mit ei-
nem Farbauftrag von 70 Prozent:
spot = PDF_makespotcolor(p, "HKS 38 E", 0);
PDF_setcolor(p, "fill", "spot", spot, 0.7, 0, 0);
Benutzerdefinierte Schmuckfarben. Neben den oben beschriebenen integrierten

Schmuckfarben unterstützt PDFlib benutzerdefinierte Schmuckfarben. Diese können
mit einem beliebigen Namen (der sich jedoch von den integrierten Namen unterschei-
den muss) sowie einer Alternativfarbe versehen sein, die zur Bildschirmausgabe sowie
für einfache Druckausgabe, nicht jedoch für hochqualitative Farbseparationen verwen-
det wird. Der Client ist dafür verantwortlich, geeignete Alternativfarben für benutzerde-
finierte Schmuckfarben anzugeben.
Zur Festlegung einer Alternativfarbe für eine neue Schmuckfarbe gibt es keine eige-
ne PDFlib-Funktion; stattdessen wird die aktuelle Füllfarbe verwendet. Außer einem zu-
sätzlichen Aufruf zur Festlegung der Alternativfarbe wird eine benutzerdefinierte
Schmuckfarbe im Prinzip wie eine integrierte Schmuckfarbe definiert und eingesetzt:
PDF_setcolor(p, "fill", "cmyk", 0.2, 1.0, 0.2, 0); /* CMYK-Alternativwerte setzen */
spot = PDF_makespotcolor(p, "CompanyLogo", 0); /* Schmuckfarbe ableiten */
PDF_setcolor(p, "fill", "spot", spot, 1, 0, 0); /* Schmuckfarbe setzen */
3.3.4 Colormanagement und ICC-Profile

PDFlib unterstützt verschiedene Konzepte zum Colormanagement wie etwa geräteun-
abhängige Farbe, Rendering-Intents und ICC-Profile.
Geräteunabhängige CIE L*a*b*-Farbe. Geräteunabhängige Farbwerte können im Farb-

raum CIE 1976 L*a*b* festgelegt werden, indem der Farbraumname lab an PDF_setcolor( )
übergeben wird. Farben werden im L*a*b* Farbraum durch einen Helligkeitswert zwi-
schen 0 und 100 sowie zwei Farbwerte zwischen -127 und 128 festgelegt. Die für den Far-
braum lab verwendete Lichtquelle ist vom Typ D50 (Tageslicht 5000 K, 2˚-Beobachter).
Rendering-Intents. Dass PDFlib-Clients geräteunabhängige Farbwerte festlegen kön-

nen, heißt nicht unbedingt, dass jedes Ausgabegerät in der Lage ist, die erforderlichen
Farben auch exakt zu reproduzieren. Es sind deshalb einige Kompromisse hinsichtlich
eines Prozesses namens Gamut-Mapping (Farbraumkompression) notwendig. Dabei
geht es darum, das Farbspektrum soweit zu verringern, dass es von einem Ausgabegerät
reproduziert werden kann. Zur Steuerung dieses Prozesses kann der Rendering-Intent
verwendet werden. Rendering-Intents können für einzelne Rasterbilder durch Übergabe
des Parameters oder der Option renderingintent an PDF_load_image( ) festgelegt werden.
Für Text und Vektorgrafik kann die Option renderingintent an PDF_create_gstate( ) über-
geben werden. Tabelle 3.7 zeigt die verfügbaren Rendering-Intents und ihre Bedeutung.
Tabelle 3.7 Rendering-Intents

Rendering-Intent Erklärung üblicher Einsatz
Auto In der PDF-Datei wird kein Rendering-Intent festgelegt. Es unbekannte oder unspezi-
soll der Standard-Rendering-Intent des Geräts verwendet fische Fälle
werden. Dies ist der Standardwert.
AbsoluteColorimetric Es wird keine Korrektur des Weißpunkts des Geräts (zum exakte Reproduktion von
Beispiel Papierweiß) vorgenommen. Farben außerhalb des Volltonfarbe; wird in ande-
Gamuts werden auf die nächstliegenden innerhalb des ren Fällen nicht empfohlen
Gamuts des Geräts abgebildet.
3.3 Farbe 73
Tabelle 3.7 Rendering-Intents
Rendering-Intent Erklärung üblicher Einsatz
RelativeColorimetric Die Farbdaten werden in den Gamut des Geräts (Farbum- Vektorgrafiken
fang) hineinskaliert, wobei die Weißpunkte aufeinander
abgebildet werden und sich die Farben leicht verschieben.
Saturation Die Farbsättigung bleibt erhalten, wobei sich die Farbwerte Geschäftsgrafiken
verschieben können.
Perceptual Die Farbverhältnisse bleiben erhalten, wobei sowohl die eingescannte Bilder
innerhalb als auch die außerhalb des Gamuts liegenden
Farben modifiziert werden, um ein gefälliges Aussehen zu
erzielen.
ICC-Profile. Das International Color Consortium (ICC)1 definierte ein Dateiformat zur
Festlegung von Farbeigenschaften von Eingabe- und Ausgabegeräten. Diese so genann-
ten ICC-Farbprofile gelten als Industriestandard und werden von allen wichtigen Her-
stellern von Colormanagementsystemen und -anwendungen unterstützt. PDFlib unter-
stützt Colormanagement mit ICC-Profilen in folgenden Bereichen:
> Definition von ICC-basierten Farbräumen für Text und Vektorgrafik auf der Seite
> Verarbeitung von ICC-Profilen, die in importierten Bilddateien eingebettet sind
> Anwendung eines ICC-Profils auf ein importiertes Bild (wobei ein in das Bild einge-
bettetes ICC-Profil unter Umständen überschrieben wird)
> Definition von Standardfarbräumen (default color space) zur Abbildung von Graustu-
fen-, RGB- oder CMYK-Daten auf ICC-basierte Farbräume
> Definition einer Druckausgabebedingung für PDF/X mittels eines externen ICC-
Profils.
Colormanagement ändert die Anzahl der Komponenten in einer Farbspezifikation
nicht (zum Beispiel von RGB nach CMYK).
Suche nach ICC-Profilen. PDFlib sucht ICC-Profile in folgenden Schritten, wobei der an
PDF_load_iccprofile( ) übergebene Parameter profilename benutzt wird:
> Ist profilename = sRGB, verwendet PDFlib das interne sRGB-Profil (siehe unten) und
beendet die Suche.
> Es wird überprüft, ob sich in der Ressourcenkategorie ICCProfile eine Ressource na-
mens profilename befindet. Ist dies der Fall, wird ihr Wert in den folgenden Schritten
als Dateiname verwendet. Ist diese Ressource nicht vorhanden, wird profilename
selbst als Dateiname verwendet.
> Anhand des im vorigen Schritt ermittelten Dateinamens wird auf der Festplatte
nach einer Datei gesucht, wobei nacheinander folgende Kombinationen durchpro-
biert werden:
<dateiname>
<dateiname>.icc
<dateiname>.icm
<colordir>/<dateiname>
<colordir>/<dateiname>.icc
<colordir>/<dateiname>.icm
1. Siehe www.color.org
Unter Windows 2000/XP bezeichnet colordir das Verzeichnis, in dem das Betriebssys-
tem gerätespezifische ICC-Profile ablegt (normalerweise C:\WINNT\system32\spool\
drivers\color). Auf Mac OS X werden für colordir folgende Pfade ausprobiert:
/System/Library/ColorSync/Profiles
/Library/ColorSync/Profiles
/Network/Library/ColorSync/Profiles
~/Library/ColorSync/Profiles
Auf anderen Systemen fallen die colordir betreffenden Schritte weg.
Verwendbare ICC-Profile. Welche ICC-Profile akzeptiert werden, hängt vom Parameter

usage ab, der an PDF_load_iccprofile( ) übergeben wird:
> Ist usage = outputintent, so werden nur Profile für Ausgabegeräte (Drucker) akzep-
tiert.
> Ist usage = iccbased, so werden Profile für Eingabe-, Anzeige- und Ausgabegeräte
(Scanner, Bildschirm und Drucker) sowie Profile zur Farbraumkonvertierung akzep-
tiert. Diese können in den Farbräumen Graustufen, RGB, CMYK oder Lab spezifiziert
sein.
Der Farbraum sRGB und das ICC-Profil sRGB. PDFlib unterstützt den zum Industrie-
standard gewordenen RGB-Farbraum sRGB (exakt ausgedrückt: IEC 61966-2-1). sRGB
wird von verschiedensten Software- und Hardware-Herstellern unterstützt und findet
breiten Einsatz bei einfachem Colormanagement für Endbenutzer-Geräte wie digitale
Kameras oder Bürogeräte wie Farbdrucker oder Bildschirme. PDFlib unterstützt den
Farbraum sRGB und hält die erforderlichen ICC-Profildaten intern vor. Das sRGB-Profil
steht damit ohne Zusatzkonfiguration immer zur Verfügung und muss deshalb nicht
explizit vom Client konfiguriert werden. Es kann mit PDF_load_iccprofile( ) und
profilename = sRGB angefordert werden.
Rasterbilder mit eingebettetem ICC-Profil. Rasterbilder können eingebettete ICC-Pro-

file enthalten, die die Art der Farbwerte des Bildes beschreiben. Ein eingebettetes ICC-
Profil könnte zum Beispiel die Farbeigenschaften des Scanners beschreiben, mit dem
die Bilddaten erzeugt wurden. PDFlib kann eingebettete ICC-Profile in den Bilddateifor-
maten PNG, JPEG und TIFF verarbeiten. Ist die Option oder der Parameter honoriccprofile
auf (den Standardwert) true gesetzt, wird das in ein Bild eingebettete ICC-Profil aus dem
Bild extrahiert und so in die PDF-Ausgabe einbettet, dass es von Acrobat auf das Bild an-
gewandt wird. Dieser Vorgang wird manchmal als »Taggen eines Bildes mit einem ICC-
Profil« genannt. Die Pixelwerte des Bildes werden von PDFlib dabei nicht verändert.
Mit dem Parameter image:iccprofile können Sie sich ein ICC-Profil-Handle für das in
ein Rasterbild eingebettete ICC-Profil besorgen. Dies ist dann nützlich, wenn dasselbe
Profil auf mehrere Bilder angewandt werden soll.
Mit dem Parameter icccomponents lässt sich die Anzahl der Farbkomponenten in ei-
nem unbekannten ICC-Profil abfragen.
Anwendung externer ICC-Profile auf Rasterbilder (Taggen). Neben den in Bilder einge-
betteten ICC-Profilen kann ein externes Profil auf ein Rasterbild angewandt werden, in-
dem ein Profil-Handle sowie die Option iccprofile an PDF_load_image( ) übergeben wird.
3.3 Farbe 75
ICC-basierte Farbräume für Seitenbeschreibungen. Die Farbwerte für Text und Vektor-
grafik können direkt in dem durch ein Profil definierten ICC-basierten Farbraum festge-
legt werden. Dazu wird zunächst der Farbraum spezifiziert, indem das ICC-Profil-Handle
einem der Parameter setcolor:iccprofilegray, setcolor:iccprofilergb oder setcolor:iccprofile-
cmyk als Wert zugewiesen wird. Dann können ICC-basierte Farbwerte gemeinsam mit ei-
nem der Farbraum-Schlüsselwörter iccbasedgray, iccbasedrgb und iccbasedcmyk an PDF_
setcolor( ) übergeben werden:
icchandle = PDF_load_iccprofile(...)
if (icchandle == -1) {
return;
}
PDF_set_value(p, "setcolor:iccprofilecmyk", icchandle);
PDF_setcolor(p, "fill", "iccbasedcmyk", 0, 1, 0, 0);
Abbildung von Gerätefarben auf ICC-basierte Standardfarbräume. PDF bietet eine Me-
thode, um in einer Seitenbeschreibung vorliegende geräteabhängige Graustufen-, RGB-
und CMYK-Farben auf geräteunabhängige Farben abzubilden. Damit lassen sich Farb-
werte, die sonst geräteabhängig wären, mit einer kolorimetrisch exakten Farbspezifika-
tion versehen. Eine solche Abbildung von Farbwerten wird durch Bereitstellung der
Farbraumdefinitionen DefaultGray, DefaultRGB und DefaultCMYK erreicht. In PDFlib wird
dazu einer der Parameter defaultgray, defaultrgb und defaultcmyk gesetzt und ihm als
Wert ein ICC-Profil-Handle zugewiesen. Die folgenden Beispiele definieren den Farb-
raum sRGB als RGB-Standardfarbraum für Text, Rasterbilder und Vektorgrafik:
icchandle = PDF_load_iccprofile(p, "sRGB", 0, "usage=iccbased");
if (icchandle == -1) {
return;
}
PDF_set_value(p, "defaultrgb", icchandle);
Definition von Druckausgabebedingungen für PDF/X. Das Profil eines Ausgabegeräts

(Drucker) kann zur Festlegung einer Druckausgabebedingung für PDF/X verwendet wer-
den. Dies wird mit usage = outputintent im Aufruf von PDF_load_iccprofile( ) bewerkstel-
ligt.
3.4 Hypertext-Elemente
3.4.1 Beispiele zur Erstellung von Hypertext-Elementen
Dieser Abschnitt zeigt die Vorgehensweise beim Erstellen von Hypertext-Elementen
wie Lesezeichen, Formularfelder oder Anmerkungen. Abbildung 3.2 zeigt das Ergebnis-
dokument mit allen Hypertext-Elementen, die wir in diesem Abschnitt erzeugen wer-
den. Das Dokument enthält folgende Hypertext-Elemente:
> Im Dokumentfenster rechts oben befindet sich über dem Text www.pdflib.com ein
unsichtbarer Weblink. Wenn Sie in diesen Bereich klicken, wird die zugehörige Web-
Seite geöffnet.
> Unmittelbar darunter liegt ein grau hinterlegtes Formular-Textfeld, das automa-
tisch (per JavaScript) mit dem aktuellen Datum gefüllt wird.
> Die rote Reißzwecke beinhaltet eine Anmerkung mit Dateianhang. Durch Anklicken
lässt sich die angehängte Datei öffnen.
> Unten links gibt es eine Formularfeld-Schaltfläche mit einem Druckersymbol. Wenn
Sie auf diese Schaltfläche klicken, wird der Acrobat-Menübefehl Datei, Drucken ausge-
führt.
> Im Navigationsfenster befindet sich das Lesezeichen »Our Paper Planes Catalog«.
Wenn Sie auf dieses Lesezeichen klicken, wird die Seite eines anderen PDF-Doku-
ments angezeigt.
Im Folgenden wird gezeigt, wie Sie diese Hypertext-Elemente mit PDFlib generieren.
Verknüpfung auf eine Web-Seite. Zunächst erzeugen wir eine Verknüpfung auf die
Web-Seite www.pdflib.com. Dies geschieht in zwei Schritten. Zuerst legen wir eine Aktion
vom Typ URI (in Acrobat: Web-Verknüpfung öffnen) an. Dabei wird ein Aktions-Handle er-
stellt, das wir im folgenden einem oder auch verschiedenen Hypertext-Elementen zu-
weisen können.
web_action = PDF_create_action(p, "URI", "url http://www.pdflib.com");
Im zweiten Schritt generieren wir die eigentliche Verknüpfung. Eine Verknüpfung ist in
PDF eine Anmerkung (Annotation) vom Typ Link. Dem Link übergeben wir in der Option
action das Ereignis activate, bei dem die Aktion ausgeführt werden soll, sowie unser
oben erstelltes Handle web_action für die auszuführende Aktion.
Abb. 3.2
Dokument mit Hypertext-
Elementen
sprintf(optlist, "linewidth=0 action {activate %d}", web_action);
PDF_create_annotation (p, left_x, left_y, right_x, right_y, "Link", optlist);
Um den Link wird standardmäßig ein schmaler schwarzer Rahmen gezogen. Das mag
am Anfang zur genauen Positionierung nützlich sein, wir blenden den Rand aber mit
linewidth=0 aus.
Alternativ dazu können Sie die Textausgabe und den Link in nur einem Aufruf von
PDF_fit_textline( ) mit der Option weblink wie folgt erzeugen:
PDF_fit_textline(p, "http://www.pdflib.com", x, y, "position=50 underline"
"weblink {linewidth=1 annotcolor={rgb 1 0 0 }} fillcolor={rgb 0 0 1}");
Lesezeichen mit Sprung in eine andere Datei. Nun werden wir das Lesezeichen »Our
Paper Planes Catalog« erstellen, das auf eine andere PDF-Datei verweist, und zwar auf
den Papierfliegerkatalog paper_planes_catalog.pdf. Wir erzeugen zunächst eine Aktion
vom Typ GoToR. In der Optionsliste zu dieser Aktion definieren wir mit filename den Na-
men des Zieldokuments und mit der Option destination, dass ein bestimmter Seitenaus-
schnitt deutlich vergrößert angezeigt wird. Genauer gesagt soll das Dokument auf der
zweiten Seite (page 2) in definierter Darstellung (type fixed) mit der Seitenmitte im sicht-
baren Bereich (left 50 top 200) und in einer Vergrößerung von 200% (zoom 2) angezeigt
werden.
char optlist[256] =
"filename paper_planes_catalog.pdf "
"destination {page 2 type fixed left 50 top 200 zoom 2}"
goto_action = PDF_create_action(p, "GoToR", optlist);
Im nächsten Schritt erstellen wir das eigentliche Lesezeichen (Bookmark). Dem Lesezei-
chen übergeben wir in der Option action das Ereignis activate, bei dem die Aktion ausge-
führt werden soll, sowie unser oben erstelltes Handle goto_action für die auszuführende
Aktion. Mit der Option fontstyle bold legen wir Fettschrift fest und mit textcolor {rgb 0 0 1}
färben wir das Lesezeichen blau ein. Als Funktionsparameter übergeben wir den anzu-
zeigenden Lesezeichentext »Our Paper Planes Catalog«.
sprintf(optlist, "action {activate %d} fontstyle bold textcolor {rgb 0 0 1}",
goto_action);
catalog_bookmark = PDF_create_bookmark(p, "Our Paper Planes Catalog", optlist);
Beim Anklicken des Lesezeichens wird der definierte Seitenausschnitt des Zieldoku-
ments angezeigt.
Anmerkung mit Dateianhang. Als nächstes Beispiel erstellen wir eine Anmerkung mit
einem Dateianhang. Dazu erzeugen wir eine Anmerkung vom Typ FileAttachment. Mit
der Option filename übergeben wir die anzuhängende Datei und sowie mit mimetype
image/gif den Typ der Datei (MIME ist eine verbreitete Konvention zur Typisierung von
Dateien). Die Anmerkung erscheint als Reißzwecke (iconname pushpin) in rot (annotcolor
{rgb 1 0 0}) und verfügt über einen Tooltip (contents {Get the Kraxi Paper Plane!}). Sie wird
nicht gedruckt (display noprint).
char optlist[256] =
"filename kraxi_logo.gif mimetype image/gif iconname pushpin "
"annotcolor {rgb 1 0 0} contents {Get the Kraxi Paper Plane!} display noprint"
PDF_create_annotation(p, left_x, left_y, right_x, right_y, "FileAttachment", optlist);
Beachten Sie dabei, dass die Größe des mit iconname definierten Symbols nicht variabel
ist. Es wird in seiner Standardgröße in die linke obere Ecke des übergebenen Rechtecks
platziert.
Formularschaltfläche zum Drucken. Das folgende Beispiel erstellt eine Formular-

schaltfläche zum Drucken des Dokuments. In der ersten Variante des Beispiels versehen
wir die Schaltfläche mit der Beschriftung Print, in der zweiten Version dann mit einem
Symbol. Dazu erzeugen wir zunächst eine Aktion vom Typ Named (in Acrobat: Menü-
befehl ausführen). Außerdem müssen wir die Schriftart für die Beschriftung festlegen:
print_action = PDF_create_action(p, "Named", "menuname Print");
button_font = PDF_load_font(p, "Helvetica-Bold", 0, "winansi", "");
Der Formularschaltfläche übergeben wir in der Option action das Ereignis up (in Acro-
bat: Maustaste loslassen), bei dem die Aktion ausgeführt werden soll, sowie unser oben
erstelltes Handle print_action für die auszuführende Aktion. Mit backgroundcolor {rgb 1 1
0} legen wir als Hintergrundfarbe Gelb fest und mit bordercolor {rgb 0 0 0} definieren wir
einen schwarzen Rand. Mit caption Print beschriften wir die Schaltfläche mit dem Text
Print, und mit tooltip {Print the document} legen wir einen Hilfstext fest. Mit font schließ-
lich legen wir die Schriftart anhand des oben erzeugten Handles button_font fest. Die
Größe der Beschriftung wird standardmäßig so angepasst, dass diese vollständig auf
der Schaltfläche Platz hat. Danach wird das eigentliche Feld mit seinen Koordinaten,
dem Namen print_button, dem Typ pushbutton sowie seinen Optionen erstellt.
sprintf(optlist, "action {up %d} backgroundcolor {rgb 1 1 0} bordercolor {rgb 0 0 0} "
"caption Print tooltip {Print the document} font %d",
print_action, button_font);
PDF_create_field(p, left_x, left_y, right_x, right_y, "print_button", 0,

"pushbutton", optlist);
Im Folgenden erweitern wir die erste Variante des Beispiels, indem wir den Text Print
auf der Schaltfläche durch ein Druckersymbol ersetzen. Dazu müssen wir die entspre-
chende Bilddatei print_icon.jpg bereits vor dem Anlegen der Seite als Template laden.
Mit der Option icon weisen wir der Schaltfläche das oben erstellte Template-Handle
print_icon zu. Dann erzeugen wir wie oben die Formularschaltfläche:
print_icon = PDF_load_image(p, "auto", "print_icon.jpg", "template");
if (print_icon == -1)
{
/* Fehlerbehandlung */
return;
}
PDF_begin_page_ext(p, pagewidth, pageheight, "");
...
sprintf(optlist, "action {up %d} icon %d tooltip {Print the document} font %d",
print_action, print_icon, button_font);
PDF_create_field(p, left_x, left_y, right_x, right_y, "print_button", 0,

"pushbutton", optlist);
Einfaches Formulartextfeld. Als nächstes steht die Erstellung des Textfelds an, das sich
in unserem Dokument rechts oben befindet und zur Datumseingabe dienen soll. Dazu
besorgen wir uns ein Font-Handle und legen dann das Formularfeld an. Es erhält den
Namen date, ist vom Typ textfield und wird grau hinterlegt.
textfield_font = PDF_load_font(p, "Helvetica-Bold", "winansi", "");
sprintf(optlist, "backgroundcolor {gray 0.8} font %d", textfield_font);
PDF_create_field(p, left_x, left_y, right_x, right_y, "date", 0, "textfield", optlist);
Die Schriftgröße eines Textfelds ist standardmäßig auf auto gesetzt. Wenn Sie Text ein-
geben, wird dieser zunächst in der Feldgröße angezeigt. Erreicht er das Feldende, wird er
automatisch verkleinert, so dass er immer vollständig im Feld sichtbar ist.
Formulartextfeld mit JavaScript. Um das obige Formulartextfeld eleganter zu gestal-

ten, soll es automatisch mit dem aktuellen Datum gefüllt werden, und zwar immer
beim Öffnen der Seite. Dazu erzeugen wir im ersten Schritt eine Aktion vom Typ Java-
Script (in Acrobat: JavaScript ausführen). In der Optionsliste zu dieser Aktion definieren
wir mit script ein JavaScript-Fragment, das das aktuelle Datum im Format Monat-Tag-
Jahr in das Textfeld date einträgt.
char optlist[256] =
"script {var d = util.printd('mmm dd yyyy', new Date()); "
"var date = this.getField('date'); date.value = d;}"
show_date = PDF_create_action(p, "JavaScript", optlist);
Im zweiten Schritt legen wir die Seite an. In der Optionsliste zu dieser Seite definieren
wir mit action, dass die oben definierte Aktion show_date durch das Ereignis open (in
Acrobat: Seite öffnen) ausgelöst wird.
sprintf(optlist, "action {open %d}", show_date);
PDF_begin_page_ext(p, pagewidth, pageheight, optlist);
Im letzten Schritt legen wir das Formular-Textfeld wie oben an. Das aktuelle Datum
wird dann bei jedem Öffnen der Seite automatisch in das Feld mit dem Namen date ein-
getragen:
textfield_font = PDF_load_font(p, "Helvetica-Bold", "winansi", "");
sprintf(optlist, "backgroundcolor {gray 0.8} font %d", textfield_font);
PDF_create_field(p, left_x, left_y, right_x, right_y, "date", 0, "textfield", optlist);
3.4.2 Formatierungsoptionen für Textfelder

Der Inhalt eines Textfeldes kann in Acrobat anhand verschiedener Optionen, etwa für
Zahlen, Prozentwerte oder Datumsangaben, formatiert werden. Diese Art der Formatie-
rung ist über benutzerdefinierten JavaScript-Code implementiert, der von Acrobat ver-
wendet wird. Von PDFlib werden diese Formatierungsfunktionen nicht direkt unter-
stützt, da sie in der PDF-Referenz festgelegt sind. Wir möchten Ihnen trotzdem einige
nützliche Hinweise geben, damit Sie eigene Formatierungsoptionen für Textfelder er-
stellen können, indem Sie einfache JavaScript-Codefragmente mit der Option action
von PDF_create_field( ) übergeben.
Um ein Textfeld zu formatieren, werden ihm JavaScript-Codefragemente als
keystroke- und format-Aktionen mitgegeben. Der JavaScript-Code ruft eine interne Acro-
bat-Funktion auf, deren Parameter die Formatierung im einzelnen steuern.
Das folgende Beispiel erstellt die beiden Aktionen keystroke und format und ordnet
sie einem Formularfeld zu. Der Feldinhalt wird dabei mit zwei Dezimalstellen und dem
Währungssymbol EUR formatiert:
keystroke_action = PDF_create_action(p, "JavaScript",
"script {AFNumber_Keystroke(2, 0, 3, 0, \"EUR \", true); }");
format_action = PDF_create_action(p, "JavaScript",

"script {AFNumber_Format(2, 0, 0, 0, \"EUR \", true); }");
sprintf(optlist, "font = %d action = {keystroke %d format %d}",

font, keystroke_action, format_action);
PDF_create_field(p, 50, 500, 250, 600, "price", 0, "textfield", optlist);
Um die in Acrobat unterstützten Formate festzulegen, müssen Sie im JavaScript-Code

die entsprechenden Funktionen angeben. Tabelle 3.8 zeigt die JavaScript-Funktionsna-
men für die Aktionen keystroke und format für alle unterstützten Formate; die Funkti-
onsparameter werden in Tabelle 3.9 beschrieben. Diese Funktionen werden so wie in
obigem Beispiel eingesetzt.
Tabelle 3.8 JavaScript-Formatierungsfunktionen für Textfelder

Format JavaScript-Funktionen zum Einsatz mit den Aktionen keystroke und format
Zahlen AFNumber_Keystroke(nDec, sepStyle, negStyle, currStyle, strCurrency, bCurrencyPrepend)
AFNumber_Format(nDec, sepStyle, negStyle, currStyle, strCurrency, bCurrencyPrepend)
Prozent AFPercent_Keystroke(nDec, sepStyle)
AFPercent_Format(nDec, sepStyle)
Datum AFDate_KeystrokeEx(cFormat)
AFDate_FormatEx(cFormat)
Zeit AFTime_Keystroke(tFormat)
AFTime_FormatEx(cFormat)
Speziell AFSpecial_Keystroke(psf)
AFSpecial_Format(psf)
Tabelle 3.9 Parameter für die JavaScript-Formatierungsfunktionen

Parameter Mögliche Werte
nDec Anzahl der Dezimalstellen
sepStyle Art der Dezimaltrennung:
0 1,234.56
1 1234.56
2 1.234,56
3 1234,56
negStyle Auszeichnung von negativen Zahlen:
0 Normal
1 Text in rot
2 Text in Klammern
3 Beides
strCurrency Währungsstring, zum Beispiel "\u20AC" für das Eurozeichen
bCurrency- false Währungssymbol nicht voranstellen
Prepend true Währungssymbol voranstellen
Tabelle 3.9 Parameter für die JavaScript-Formatierungsfunktionen
Parameter Mögliche Werte
cFormat Datumsformatstring. Er kann die folgenden Platzhalter sowie die für tFormat angeführten
Zeitformate enthalten:
d Tag des Monats
dd Tag des Monats mit führender Null
ddd Abkürzung für den Wochentag
m Monat als Zahl
mm Monat als Zahl mit führender Null
mmm Abkürzung für den Monatsnamen
mmmm vollständiger Monatsname
yyyy Jahr mit vier Ziffern
yy Jahr mit den beiden letzten Ziffern
tFormat Zeitformatstring. Er kann die folgenden Platzhalter enthalten:
h Stunde (0-12)
hh Stunde mit führender Null (0-12)
H Stunde (0-24)
HH Stunde mit führender Null (0-24)
M Minuten
MM Minuten mit führender Null
s Sekunden
ss Sekunden mit führender Null
t 'a' oder 'p'
tt 'am' oder 'pm'
psf Beschreibt weitere Formate:
0 Zipcode
1 Zipcode + 4
2 Telefonnummer
3 Sozialversicherungsnummer
Formularfelder aktivieren das Dirty-Flag des Dokuments. Beim Schließen eines PDF-
Dokuments mit Formularfeldern in Acrobat werden Sie gefragt, ob Sie die Datei spei-
chern möchten. Dies geschieht auch dann, wenn Sie keinerlei Änderungen vorgenom-
men haben. Technisch ausgedrückt wird beim Öffnen eines von PDFlib generierten
PDFs das Dirty-Flag des Dokuments gesetzt, so dass es von Acrobat als geändert angese-
hen wird. Dies spielt zwar meist keine Rolle, da das Formular ja in der Regel ausgefüllt
werden soll. Für Benutzer, die es trotzdem als störend empfinden, kann mit einem kur-
zen JavaScript Abhilfe geschaffen werden, das das Dirty-Flag des Dokuments nach dem
Laden der Datei zurücksetzt. Da zu verwenden Sie folgende Sequenz:
/* ...Formularfelder werden erstellt... */
PDF_create_field(p, "100, 500, 300, 600, "field1", "textfield", "..."
/* JavaScript-Aktion wird erstellt, die im Dokument ausgeführt wird */

action = PDF_create_action(p, "JavaScript", "script={this.dirty=false;}");
...
sprintf(optlist, "action={open %d}", action);
PDF_end_document(p, optlist);
4 Textausgabe
4.1 Übersicht über Schriften und Zeichensätze
Die Behandlung von Schriften ist einer der komplexesten Aspekte von Seitenbeschrei-
bungen und Dokumentformaten wie PDF. In diesem Kapitel fassen wir die wichtigsten
Merkmale der Schrift- und Zeichensatzbehandlung von PDFlib zusammen. Der Begriff
»Zeichensatz« bezieht sich dabei auf die Zuordnung von einzelnen Bytes oder Bytekom-
binationen zu den Zeichen, die sie tatsächlich darstellen. Sofern nicht anderweitig ange-
geben, unterstützt PDFlib die jeweils beschriebenen Fontformate auf allen Plattfor-
men.1
4.1.1 Unterstützte Fontformate

PDFlib unterstützt zahlreiche Fontformate, die im Folgenden mit ihren wichtigsten Ei-
genschaften kurz beschrieben werden.
PostScript-Type-1-Fonts. PostScript-Fonts können in verschiedenen Dateiformaten

vorliegen und werden in der Regel mit einer zusätzlichen Datei ausgeliefert, die Metrik-
daten und andere Begleitinformationen über die Schrift enthält. PDFlib unterstützt
Mac- und Windows-PostScript-Fonts sowie die üblichen Dateiformate für PostScript-
Zeichenbeschreibungs- und Metrikdaten.
TrueType-Fonts. PDFlib unterstützt vektorbasierte, aber keine auf Bitmaps basieren-

den TrueType-Fonts. Die TrueType-Fontdatei muss im TTF- oder TTC-Format von Win-
dows bereitgestellt werden oder auf dem Betriebssystem (Mac oder Windows) installiert
sein. Im Gegensatz zu PostScript-Type-1-Fonts benötigen TrueType- und OpenType-
Fonts keine zusätzliche Metrikdatei, da die Metrikinformationen in der Fontdatei ent-
halten sind.
OpenType-Fonts. OpenType ist ein modernes Fontformat, das PostScript- und TrueTy-
pe in sich vereint und außerdem plattformunabhängig ist. Es gibt zwei Varianten von
OpenType, die beide von PDFlib unterstützt werden:
> OpenType-Fonts mit TrueType-Zeichenbeschreibungen (*.ttf) werden wie gewöhnli-
che TrueType-Fonts behandelt.
> OpenType-Fonts mit PostScript-Zeichenbeschreibungen (*.otf) enthalten PostScript-
Daten in einem TrueType-ähnlichen Dateiformat. Diese Variante wird auch CFF
(Compact Font Format) genannt.
Chinesische, japanische und koreanische (CJK) Fonts. Neben den Acrobat-Standard-

CJK-Fonts (siehe Abschnitt 4.7, »Chinesischer, japanischer und koreanischer Text«, Seite
120) unterstützt PDFlib zusätzliche CJK-Fonts im TrueType- oder OpenType-Format. Im
Allgemeinen werden diese Schriften wie westliche Schriften behandelt. Es gibt jedoch
einige Einschränkungen.
1. Die Begriffe Schrift und Font sowie Zeichensatz und Encoding werden jeweils synonym verwendet.

Type-3-Fonts. Neben PostScript-, TrueType- und OpenType-Fonts unterstützt PDFlib
das Konzept benutzerdefinierter (Type 3) PDF-Fonts. Im Gegensatz zu den üblichen
Schriften in den Formaten PostScript Type 1 und TrueType werden benutzerdefinierte
Fonts nicht aus einer externen Quelle (über eine Fontdatei oder Betriebssystemdienste)
bezogen, sondern mit den PDFlib-Funktionen für Text, Vektorgrafik und Rasterbilder
definiert. Type-3-Fonts können zu folgenden Zwecken eingesetzt werden:
> Bitmap-Fonts
> Benutzerdefinierte Grafiken wie Logos können schnell mit einfachen Textoperato-
ren gedruckt werden
> Japanische Gaiji-Zeichen (benutzerdefinierte Zeichen), die in den vordefinierten
Fonts und Zeichensätzen nicht verfügbar sind
4.1.2 Zeichensätze
Ein Zeichensatz (Encoding) definiert, wie die in einem String enthaltenen Bytes von
PDFlib oder Acrobat interpretiert und in Text auf der Seite umgesetzt werden. PDFlib
unterstützt zahlreiche Encoding-Verfahren.
Alle unterstützten Zeichensätze lassen sich in einem Dokument beliebig kombinie-
ren. Im Prinzip können sogar verschiedene Zeichensätze für eine einzige Schrift ver-
wendet werden, was jedoch nur selten von Interesse sein dürfte.
Hinweis Für einen bestimmte Font können nicht unbedingt alle Zeichensätze verwendet werden. Der
Benutzer muss deshalb sicherstellen, dass der Font alle Zeichen enthält, die vom jeweiligen Zei-
chensatz benötigt werden. Dieses Problem kann auch bei den Acrobat-Standardfonts auftreten
(siehe Tabelle 4.2).
Auswählen von Glyphen. Es gibt drei grundsätzlich unterschiedliche Verfahren zur

Auswahl einer bestimmten in einer Schrift enthaltenen Glyphe (Form eines Zeichens):
> PostScript-Type-1-Fonts basieren auf dem Konzept der Glyphennamen: jede Glyphe
besitzt einen eindeutigen Namen, der zur Identifizierung des Zeichens herangezo-
gen werden kann. Anhand dieser Namen werden für die jeweilige Umgebung geeig-
nete Zeichenzuordnungen aufgebaut. Das Konzept der Glyphennamen war recht
lange zweckmäßig. Inzwischen weist es jedoch gravierende Mängel auf, da Glyphen-
namen viel Speicherplatz benötigen und außerdem den Anforderungen des interna-
tionalen Einsatzes nicht standhalten (insbesondere bei CJK-Fonts).
> TrueType- und OpenType-Fonts identifizieren Glyphen anhand ihrer Unicode-Wer-
te. Damit kann allen Glyphen in einem Textfont eine klare Bedeutung zugeordnet
werden. Es gibt in Unicode jedoch keine Standardbelegung für Pi- oder Symbolfonts.
Dies erschwert den Einsatz von Symbolfonts in einer Unicode-Umgebung.
> Chinesische, japanische und koreanische OpenType-Fonts basieren auf dem Kon-
zept der Character IDs (CIDs). Es handelt sich im Prinzip um Zahlen, die aus einem
Standard-Pool (dem Zeichenvorrat) für die jeweilige Sprache stammen.
Diese Konzepte treten durchaus auch kombiniert auf. So können TrueType-Fonts aus
Kompatibilitätsgründen eine Hilfstabelle mit PostScript-Glyphennamen enthalten. Au-
ßerdem bietet die Adobe Glyph List (AGL) Unicode-Werte für viele Standard-PostScript-
Glyphennamen. PDFlib unterstützt alle der drei oben genannten Verfahren (Glyphen-
namen, Unicode, CID).
84 Kapitel 4: Textausgabe
8-Bit-Zeichensätze. 8-Bit-Zeichensätze (auch Ein-Byte-Zeichensätze genannt) ordnen
jedes Byte eines Textstrings einem Zeichen zu und sind damit auf maximal 256 Zeichen
beschränkt. Die in PDFlib verwendeten 8-Bit-Zeichensätze basieren auf Glyphennamen
oder Unicode-Werten und können aus verschiedenen Quellen stammen:
> Vordefinierte Zeichensätze, von denen eine große Auswahl zur Verfügung steht (sie-
he Tabelle 4.2). Diese umfassen die wichtigsten Zeichensätze, die gegenwärtig auf
verschiedensten Systemen und in unterschiedlichsten Sprachräumen im Einsatz
sind.
> Benutzerdefinierte Zeichensätze, die in einer externen Datei bereitgestellt oder zur
Laufzeit dynamisch mit PDF_encoding_set_char( ) zusammengestellt werden. Diese
Zeichensätze können auf Glyphennamen oder Unicode-Werten basieren.
> Zeichensätze, die vom Betriebssystem bezogen werden. Diese so genannten System-
zeichensätze werden nur auf Windows und den Systemen IBM eServer iSeries und
zSeries unterstützt.
> Abgekürzte Unicode-Zeichensätze, die zur bequemen Adressierung eines beliebigen
Unicode-Bereichs von 256 aufeinanderfolgenden Zeichen mit 8-Bit-Werten verwen-
det werden kann.
> Zeichensätze, die sich auf eine spezielle Schrift beziehen. Diese werden auch schrift-
spezifische Zeichensätze oder builtin encodings genannt.
Leistungsfähigere Adressierungsmethoden. Neben den 8-Bit-Zeichensätzen werden

verschiedene andere Adressierungsmethoden unterstützt, die wesentlich leistungsfähi-
ger und nicht auf 256 Zeichen beschränkt sind.
> Ausschließlich auf Unicode basierende Adressierung über das Schlüsselwort unicode
für den Parameter encoding. In diesem Fall werden Unicode-Strings direkt vom Client
an PDFlib übergeben. Diese können nach verschiedenen Standardverfahren (zum
Beispiel UCS-16 oder UTF-8) und Bytereihenfolgen (»Little-Endian« oder »Big Endi-
an«) kodiert sein.
> Auf CMaps basierende Adressierung für verschiedene chinesische, japanische und
koreanische Standards. Zusammen mit den Standard-CJK-Fonts unterstützt PDFlib
alle von Acrobat unterstützten CMaps. Dazu gehören auch CMaps, die nicht auf Uni-
code basieren (siehe Abschnitt 4.7, »Chinesischer, japanischer und koreanischer
Text«, Seite 120).
> Adressierung über die »glyph ID« über das Schlüsselwort glyphid für den Parameter
encoding für TrueType- und OpenType-Fonts. Dies kann bei komplexerer Textbear-
beitung nützlich sein, wo auf einzelne Glyphen in einer Schrift ohne Zuhilfenahme
eines Zeichensatzes zugegriffen wird oder wo Glyphen adressiert werden, für die kei-
ne Unicode-Zuordnung existiert. Die Anzahl der gültigen Glyph-IDs in einem Font
lässt sich mit dem Parameter fontmaxcode abfragen.
4.1.3 Unicode-Unterstützung
Unicode stellt einen riesigen Zeichensatz dar, der alle gegenwärtigen und viele früher
gebräuchlichen Sprachen und Schriften der Welt abdeckt und in vielen Anwendungen,
Betriebssystemen und Programmiersprachen starke Unterstützung erfährt. PDFlib bie-
tet umfangreiche Unicode-Unterstützung. Dies bedeutet im Einzelnen:
> In Seitenbeschreibungen kann Unicode direkt übergeben werden.
> Unicode kann für verschiedene Hypertext-Elemente übergeben werden.

> Für Text oder Hypertext-Elemente können Unicode-Strings im UTF-8- oder UTF-16-
Format und in beliebiger Bytereihenfolge übergeben werden.
> PDFlib ergänzt die PDF-Ausgabe um Zusatzinformationen (eine ToUnicode CMap), die
von Acrobat zur korrekten Zuordnung von Unicode-Werten beim Textexport (zum
Beispiel über die Zwischenablage) und bei der Suche nach Unicode-Text herangezo-
gen wird.
4.2 Fontformate im Detail
4.2.1 Unterstützung von Systemschriften auf Windows und Mac
Auf Mac- und Windows-Systemen hat PDFlib Zugriff auf alle TrueType-, OpenType- und
PostScript-Schriften, die im Betriebssystem installiert sind. Wir bezeichnen solche
Schriften als Systemschriften (host fonts). Statt die Schriftdateien manuell zu konfigu-
rieren, werden sie einfach im System installiert (meist durch bloßes Kopieren in das
entsprechende Verzeichnis), und schon stehen sie PDFlib zur Verfügung.
Bei Systemschriften ist unbedingt auf den korrekten Schriftnamen einschließlich
Groß- und Kleinschreibung zu achten. Da die Namen von entscheidender Bedeutung
sind, werden im folgenden Methoden zur Ermittlung der richtigen Schriftnamen be-
schrieben. Weitere Informationen finden Sie in Abschnitt 4.2.2, »PostScript-Fonts«, Seite
88 und Abschnitt 4.2.3, »TrueType- und OpenType-Fonts«, Seite 89.
Ermitteln von Systemschriftnamen unter Windows. Um den Namen einer installierten

Schrift herauszufinden, doppelklicken Sie einfach auf die Fontdatei. Ein Fenster mit
Schriftinformationen erscheint. Verwenden Sie den Namen in der ersten Zeile. Manche
Schriftnamen sind vielleicht teilweise entsprechend der verwendeten Windows-Versi-
on lokalisiert. So könnte der gängige Bestandteil Bold auf einem deutschen System als
Fett erscheinen. Um die Schriftdaten vom Windows-System zu beziehen, müssen Sie in
PDFlib die übersetzte Variante des Fonts (e.g. Arial Fett) oder Fontstilnamen verwenden
(siehe Abschnitt , »Windows-Fontstilnamen für TrueType- und OpenType-Fonts«, Seite
90). Dagegen müssen Sie die generische (nicht lokalisierte) Variante des Schriftnamens
benutzen (e.g. Arial Bold), wenn Sie die Schriftdaten direkt aus der Fontdatei abrufen
möchten.
Zur genaueren Untersuchung von TrueType-Fonts können Sie sich die von Microsoft
kostenlos erhältliche Software »font properties extension«1 besorgen, die zahlreiche
Einträge der TrueType-Tabellen einer Schrift in lesbarer Form anzeigt.
Ermitteln von Systemschriftnamen auf dem Mac. Mit dem Hilfsprogramm Font Book,
das mit Mac OS X ausgeliefert wird, können Sie die Namen installierter Systemschriften
ermitteln. Es gibt jedoch Fälle, in denen Font Book nicht den korrekten QuickDraw-Na-
men anzeigt, so wie der von PDFlib benötigt wird. Wir empfehlen daher Apples frei ver-
fügbare Font Tools,2 eine Sammlung von Befehlszeilen-Programmen inklusive des Pro-
gramms ftxinstalledfonts zur Bestimmung der QuickDraw-Namen aller installierten
Fonts. Um den von PDFlib erwarteten Namen zu ermitteln, installieren Sie Font Tools
und führen in einem Terminalfenster den folgenden Befehl aus:
ftxinstalledfonts -q
Mögliche Probleme beim Zugriff auf Systemschriften unter Windows. Wir möchten
Anwender auf ein potentielles Problem bei der Fontinstallation auf Windows-Systemen
aufmerksam machen. Wenn Sie Schriften über den Menübefehl Datei, Neue Schriftart
installieren... installieren (statt sie direkt in das Windows-Fonts-Verzeichnis zu ziehen),
erscheint die Checkbox Schriftarten in den Ordner "Fonts" kopieren. Ist diese Box nicht se-
1. Siehe www.microsoft.com/typography/property/TrueTypeProperty21.mspx
2. Siehe developer.apple.com/fonts/OSXTools.html

lektiert, erzeugt Windows im Fonts-Verzeichnis nur eine Verknüpfung auf die originale
Fontdatei. In diesem Fall muss sich die Fontdatei in einem Verzeichnis befinden, auf das
die PDFlib benutzende Anwendung zugreifen kann. Dies betrifft insbesondere IIS mit
Standardsicherheitseinstellungen, bei denen auf Fontdateien außerhalb des Windows-
Fonts-Verzeichnisses unter Umständen nicht zugegriffen werden kann. Lösung: entwe-
der Sie kopieren die Fontdateien ins Fonts-Verzeichnis oder Sie legen die originale Font-
datei in ein Verzeichnis, auf das IIS Leserecht hat.
Ähnliche Probleme können beim Adobe Type Manager (ATM) auftreten, wenn bei
der Fontinstallation die Option Hinzufügen ohne Kopieren der Dateien selektiert ist.
Mögliche Probleme beim Zugriff auf Systemschriften auf dem Mac. Beim Testen ha-
ben wir festgestellt, dass neu installierte Schriften für GUI-lose Anwendungen wie PDF-
lib manchmal erst zugreifbar sind, wenn der Benutzer sichvom System ab- und wieder
anmeldet.
4.2.2 PostScript-Fonts
Formate für PostScript-Fontdateien. PostScript-Type-1-Fonts bestehen aus zwei Teilen:
der eigentlichen Zeichenbeschreibung und den Metrikdaten. PDFlib unterstützt auf al-
len Systemen folgende Formate für PostScript-Type-1-Zeichenbeschreibungen und -Me-
trikdaten:
> Das plattformunabhängige Format AFM (Adobe Font Metrics) und das Windows-spe-
zifische Format PFM (Printer Font Metrics) für Fontmetrikdaten.
Während sich auf AFM basierende Fontmetriken in jeden von der Schrift unterstütz-
ten Zeichensatz umsortieren lassen, können übliche PFM-Dateien für westliche
Fonts (Codepage 1252) nur mit folgenden Zeichensätzen verwendet werden: auto,
winansi, iso8859-1, unicode, ebcdic. PFM-Dateien für Symbolfonts sind mit dem Zei-
chensatz builtin einsetzbar. PFM-Dateien für andere Codepages lassen sich mit einem
Zeichensatz benutzen, der zur Codepage in der PFM (oder einer Teilmenge) passt, mit
dem Zeichensatz builtin zur Verwendung der PFM-internen Codepage oder mit
unicode. Die PFM für einen kyrillischen Font ist zum Beispiel mit den Zeichensätzen
cp1250, builtin und unicode einsetzbar.
> Das plattformunabhängige Format PFA (Printer Font ASCII) und das Windows-spezifi-
sche Format PFB (Printer Font Binary) für Zeichenbeschreibungen im PostScript-Type-
1-Format (manchmal auch »ATM-Fonts« genannt).
> Auf dem Mac werden auch ressourcenbasierte PostScript-Type-1-Fonts, zum Beispiel
LWFN-Fonts (LaserWriter Font), unterstützt. Diesen liegt ein Zeichensatzkoffer
(FOND-Ressource oder FFIL) mit Metrikdaten bei (sowie Bildschirmschriften, die von
PDFlib ignoriert werden). PostScript-Systemschriften sind mit folgenden Zeichen-
sätzen einsetzbar: auto, macroman, macroman_apple, unicode und builtin. Die Zeichen-
sätze macroman und macroman_apple werden bei manchen Schriften je nach enthal-
tenem Zeichensatz unter Umständen nicht akzeptiert.
Beim Arbeiten mit PostScript-Systemschriften muss die LWFN-Datei im selben Ord-
ner wie der Zeichensatzkoffer liegen, und entsprechend der 5+3+3-Regel benannt
sein. Beachten Sie, dass PostScript-Systemschriften in Classic-Versionen von PDFlib
(ohne Carbon-Bibliothek) nicht unterstützt werden.
> OpenType-Fonts mit PostScript-Zeichenbeschreibungen (*.otf).
PostScript-Fontnamen. Wenn Sie Fontdateien von der Festplatte einsetzen, können Sie
beliebige Alias-Namen verwenden (siehe Abschnitt 4.3.1, »Wie PDFlib nach Fonts sucht«,
Seite 93). Es gibt mehrere Möglichkeiten, den korrekten Namen für einen PostScript-
Font herauszufinden:
> Öffnen Sie die Zeichenbeschreibungsdatei (*.pfa oder *.pfb) und finden Sie den String
nach dem Eintrag /FontName. Entfernen Sie den Schrägstrich / am Anfang und ver-
wenden Sie den Rest als Schriftnamen.
> Wenn Sie mit Windows 2000/XP oder Mac OS X 10.4 arbeiten, können Sie auf die
Fontdatei doppelklicken, und ein Schriftbeispiel sowie der PostScript-Name der
Schrift werden angezeigt.
> Öffnen Sie die AFM-Metrikdatei und suchen Sie nach dem Eintrag FontName.
Hinweis Der PostScript-Fontname kann sich vom Windows-Namen der Schrift deutlich unterscheiden.
So erscheint die Schrift »AvantGarde-Demi« (PostScript-Name) im Windows-Fontmenü zum
Beispiel als »AvantGarde, Bold«. Genauso ist der Schriftname, der in den .inf-Dateien für Win-
dows erscheint, für den Einsatz mit PDF nicht relevant.
PostScript-Glyphennamen. Um einen eigenen Zeichensatz zu schreiben oder die rich-

tigen Schriften für einen bestimmten Zeichensatz zu finden, benötigen Sie eine exakte
Definition des von einem Zeichensatz benötigten Zeichenvorrats sowie die genauen
Glyphennamen, die in der Fontdatei verwendet werden. Sie müssen also sicherstellen,
dass die gewählte Schrift alle vom Zeichensatz benötigten Zeichen enthält. Die mit
Acrobat 4/5 gelieferten Standardschriften unterstützen zum Beispiel weder ISO 8859-2
(Latin 2) noch die Windows-Codepage 1250. Falls Sie den Fonteditor FontLab1 zur Hand
haben (der sich übrigens großartig für jede Art von Schrift- und Zeichensatzangelegen-
heiten eignet), können Sie die von einer Schrift unterstützten Zeichensätze ermitteln
(schlagen Sie in der FontLab-Dokumentation unter dem Stichwort »Codepages« nach).2
Als Hilfsmittel für PDFlib-Benutzer wird das PostScript-Programm print_glyphs.ps
mit PDFlib ausgeliefert, das die Namen aller in einem PostScript-Font vorhandenen Zei-
chen ermittelt. Dazu fügen Sie am Ende dieser Datei mit einem Texteditor den Namen
der fraglichen Schrift ein und senden die Datei (gemeinsam mit der Schrift) an einen
PostScript-Drucker, destillieren sie oder betrachten sie mit einem PostScript-Viewer.
Das Programm druckt alle in der Schrift vorhandenen Zeichen, und zwar alphabetisch
nach Glyphennamen sortiert.
Ist ein von einem benutzerdefinierten Zeichensatz benötigtes Zeichen in einer
Schrift nicht vorhanden, so fehlt es auch im PDF-Dokument.
4.2.3 TrueType- und OpenType-Fonts

Dateiformate für TrueType und OpenType. Die für einen TT- oder OT-Font erforderli-
chen Daten sind in einer einzigen Fontdatei enthalten. PDFlib unterstützt für TrueType-
und OpenType-Fonts folgende Dateiformate:
> Windows-TrueType-Fonts (*.ttf) inklusive CJK-Fonts
1. Siehe www.fontlab.com
2. Informationen über die in PostScript-Fonts verwendeten Glyphennamen finden Sie unter partners.adobe.com/asn/
developer/typeforum/unicodegn.html (Schriftanbieter müssen sich aber nicht an diese Empfehlungen für Glyphennamen
halten).

> Plattformunabhängige OpenType-Fonts mit Zeichenbeschreibungen gemäß True-
Type (*.ttf) oder PostScript (*.otf) inklusive CJK-Fonts
> TrueType Collections (*.ttc) mit mehreren Schriften in einer Datei (vorwiegend für
CJK-Fonts)
> Fonts mit benutzerspezifischen Zeichen (end-user defined characters, EUDC), die mit
dem Microsoft-Tool eudcedit.exe erstellt wurden (*.tte).
> Auf dem Mac kann jeder auf dem System installierte TrueType-Font (einschließlich
.dfont) auch in PDFlib verwendet werden.
TrueType- und OpenType-Fontnamen. Wenn Sie Fontdateien von der Festplatte einset-
zen, können Sie beliebige Alias-Namen verwenden (siehe Abschnitt 4.3.1, »Wie PDFlib
nach Fonts sucht«, Seite 93). Der Name eines TrueType-Fonts im generierten PDF-Doku-
ment kann von den in PDFlib (oder Windows) benutzten Namen abweichen. Das ist nor-
mal und liegt darin begründet, dass PDF den PostScript-Namen eines TrueType-Fonts
verwendet, der nicht unbedingt mit dem ursprünglichen TrueType-Namen überein-
stimmt (zum Beispiel TimesNewRomanPSMT bzw. Times New Roman).
Hinweis Im Gegensatz zu PostScript-Fonts können die Namen von TrueType- und OpenType-Fonts Leer-
zeichen enthalten.
Windows-Fontstilnamen für TrueType- und OpenType-Fonts. Beim Laden von System-

schriften unter Windows können PDFlib-Anwender eine Funktion nutzen, die vom
Schriftselektionsmechanismus von Windows zur Verfügung gestellt wird: Für das Ge-
wicht und die Neigung eines TrueType- oder OpenType-Fonts lässt sich ein Stilname
übergeben, zum Beispiel
Georgia,Bold
Windows wird damit angewiesen, nach einer bestimmten fetten, kursiven oder anderen
Variante der Basisschrift zu suchen. Je nach vorhandener Auswahl selektiert Windows
den Font, der dem angeforderten Stil am nächsten kommt (es wird keine neue Schrift-
variante erstellt). Der von Windows selektierte Font kann vom angeforderten Font ab-
weichen, der wiederum nicht mit dem Fontnamen im generierten PDF übereinstimmen
muss; PDFlib hat keinerlei Kontrolle über die Fontselektion von Windows. Stilnamen
für Fonts funktionieren außerdem nur bei TrueType- und OpenType-Systemschriften
und nicht bei PostScript-Systemschriften oder Schriften, die über eine Fontdatei auf der
Festplatte spezifiziertwerden.
Zur Festlegung des Schriftgewichts können folgende Schlüsselwörter an den an PDF_
load_font( ) zu übergebenden Basisnamen des Fonts angehängt werden (durch ein Kom-
ma vom Fontnamen getrennt):
none, thin, extralight, ultralight, light, normal, regular, medium,
semibold, demibold, bold, extrabold, ultrabold, heavy, black
Das folgende Schlüsselwort kann alternativ oder zusätzlich zu obigen Schlüsselwörtern

angehängt werden:
italic
Bei den Schlüsselwörtern wird zwischen Groß- und Kleinschreibung unterschieden.

Zwei Stilnamen werden durch Komma voneinander getrennt, zum Beispiel:
Georgia,Bold,Italic
Hinweis Windows-Stilnamen für Fonts sind nützlich, wenn Sie mit lokalisierten Schriftnamen zu tun
haben, da sie eine universelle Methode zum Zugriff auf Fontvariationen unabhängig von ihren
lokalisierten Namen bieten.
4.2.4 Benutzerdefinierte Schriften (Type-3-Fonts)

Type-3-Fonts stellen in PDF im Gegensatz zu PostScript-Type-3-Fonts kein Dateiformat
dar. Die Glyphen eines Type-3-Fonts müssen zur Laufzeit mit den Grafikfunktionen von
PDFlib definiert werden. Da alle PDF-Funktionen für Vektorgrafik, Rasterbilder und so-
gar Textausgabe in Type-3-Fontdefinitionen verwendet werden können, gibt es keiner-
lei Beschränkungen hinsichtlich der Zeicheninhalte in einem Type-3-Font. In Kombina-
tion mit der PDF-Importbibliothek PDI können Sie selbst komplexe Zeichnungen als
PDF-Seite importieren und dann zur Definition eines Zeichens in einem Type-3-Font
verwenden.
Hinweis PostScript-Type-3-Fonts werden nicht unterstützt.
Type-3-Fonts müssen vollständig außerhalb der Seite definiert werden (genauer gesagt
muss die Fontdefinition im Geltungsbereich document vorgenommen werden). Das fol-
gende Beispiel zeigt die Definition eines einfachen Type-3-Fonts:
PDF_begin_font(p, "Fuzzyfont", 0, 0.001, 0.0, 0.0, 0.001, 0.0, 0.0, "");
PDF_begin_glyph(p, "circle", 1000, 0, 0, 1000, 1000);

PDF_arc(p, 500, 500, 500, 0, 360);
PDF_fill(p);
PDF_end_glyph(p);
PDF_begin_glyph(p, "ring", 400, 0, 0, 400, 400);

PDF_arc(p, 200, 200, 200, 0, 360);
PDF_stroke(p);
PDF_end_glyph(p);
PDF_end_font(p);
Die Schrift wird in PDFlib registriert und ihr Name kann gemeinsam mit einem Zei-
chensatz, der die Namen der Glyphen in dem Type-3-Font enthält, an PDF_load_font( )
übergeben werden. Bei der Definition und Verwendung von Type-3-Fonts ist Folgendes
zu beachten:
> Ähnlich wie bei Füllmustern und Templates können Bilder nicht innerhalb einer
Glyphenbeschreibung geöffnet werden. Sie lassen sich jedoch davor öffnen und kön-
nen dann innerhalb der Glyphenbeschreibung platziert werden. Um diese Ein-
schränkung zu umgehen, können für kleine Bitmaps Inline-Bilder verwendet wer-
den.
> Aufgrund von Einschränkungen in PDF-Viewern müssen alle Zeichen, die in der
Textausgabe verwendet werden, auch tatsächlich in der Schrift definiert sein: Soll
Zeichencode x mit PDF_show( ) oder einer ähnlichen Funktion angezeigt werden und
enthält der Zeichensatz glyphname an Position x, dann muss glyphname über PDF_
begin_glyph( ) definiert worden sein. Diese Einschränkung bezieht sich nur auf Type-
3-Fonts. In PostScript-Type-1-, TrueType- oder OpenType-Fonts werden fehlende Gly-
phen dagegen einfach ignoriert.

> Manche PDF-Viewer (für Acrobat gilt das nicht) benötigen eine Glyphe namens
.notdef für Codes, für die im Font kein entsprechender Glyphenname definiert ist.
Die Glyphe .notdef muss zwar vorhanden sein, die zugehörende Glyphenbeschrei-
bung kann aber leer sein.
> Werden normale Rasterbilddaten zur Definition von Zeichen verwendet, dann wer-
den im Rasterbild nicht gesetzte Bildpunkte unabhängig vom Hintergrund weiß ge-
druckt. Um dies zu vermeiden und die ursprüngliche Hintergrundfarbe durchschei-
nen zu lassen, verwenden Sie den Parameter mask zur Konstruktion des Rasterbilds.
> Mit der Rasterbild-Option interpolate lässt sich das Aussehen von Type-3-Bitmap-
Fonts bei der Bildschirm- und Druckausgabe verbessern.
4.3 Schrifteinbettung und Schriftuntergruppen
4.3.1 Wie PDFlib nach Fonts sucht
Quellen für Fontdaten. PDFlib bezieht Fontdaten aus verschiedenen Quellen:
> Fontdateien im Dateisystem, die statisch über eine UPR-Konfigurationsdatei (siehe
Abschnitt 3.1.5, »Ressourcenkonfiguration und Dateisuche«, Seite 56) oder dyna-
misch über PDF_set_parameter( ) und die Ressourcenkategorie FontOutline konfigu-
riert wurden.
> Systemschriften (siehe Abschnitt 4.2.1, »Unterstützung von Systemschriften auf
Windows und Mac«, Seite 87) sind ohne jede Konfiguration einsetzbar. Um die Such-
reihenfolge zu definieren, sind sie über die UPR-Ressourcenkategorie HostFont aber
auch explizit konfigurierbar. Diese Möglichkeit kann zum Beispiel genutzt werden,
um bevorzugt Systemschriften statt der integrierten Standardschriften zu verwen-
den.
> Fontdaten, die vom Client mittels virtueller PVF-Dateien direkt in den Speicher über-
tragen werden. Dies ist bei komplexeren Anwendungen nützlich, bei denen die Font-
daten bereits im Speicher geladen und unnötige Festplattenzugriffe durch PDFlib zu
vermeiden sind. (Einzelheiten über virtuelle Dateien finden Sie in Abschnitt 3.1.4,
»Das PDFlib Virtual File System (PVF)«, Seite 55.)
Alias-Namen für Schriften. Da es nicht immer ganz einfach ist, den genauen internen
Namen einer Schrift zu ermitteln, unterstützt PDFlib Alias-Namen für PostScript-, True-
Type- und OpenType-Schriften. Der Alias-Name ist ein beliebiger selbst definierter
Name für eine Schrift, der in einer UPR-Datei oder zur Laufzeit als Ressource vom Typ
HostFont, FontOutline, FontAFM oder FontPFM angegeben werden kann. Das folgende Bei-
spiel definiert einen Alias-Namen für eine Schrift, die im Dateisystem gespeichert ist:
PDF_set_parameter(p, "FontOutline", "x=DFHSMincho-W3.ttf");
font = PDF_load_font(p, "x", 0, "winansi", "");
Schriftsuche. Der an PDF_load_font( ) übergebene Schriftname ist ein Name-String (sie-

he Abschnitt 4.5.2, »Content-Strings, Hypertext-Strings und Name-Strings«, Seite 106).
Es werden jedoch nicht alle Encodings für alle Quellen von Fontdaten unterstützt. Bei
der Schriftsuche wird wie folgt vorgegangen:
> Ist der Name ein Alias (festgelegt in einer UPR-Datei oder einem Aufruf von PDF_set_
parameter( )), kann er in ASCII oder UTF-8 kodiert sein. Mittels des Namens, auf den
sich der Alias bezieht, wird in den nächsten Schritten nach der Fontdatei (bei einer
Schrift im Dateisystem) oder nach der Systemschrift gesucht.
> Bezeichnet der Name eine Systemschrift, kann er in ASCII kodiert sein. Unter Win-
dows kann auch Unicode verwendet werden.
> Wurde die Schrift (auch als möglicherweise lokalisierte) Systemschrift nicht gefun-
den oder ist sie nicht in Unicode kodiert, wird durch Hinzufügen verschiedener Na-
menserweiterungen nach einer passenden Fontdatei gesucht (siehe unten).
> Bei TTC-Schriften (TrueType Collection) kann der Name in ASCII oder Unicode ko-
diert sein. Er wird mit allen Fontnamen in der TTC-Datei verglichen.
Suche mit Namenserweiterung für Fontdateien im Dateisystem. Wenn PDFlib nach

einer Font- oder Fontmetrikdatei im Dateisystem sucht (statt die Systemschrift direkt

vom Betriebssystem abzurufen), geschieht dies anhand des folgenden Suchalgorith-
mus, sofern der Fontname aus reinen ASCII-Zeichen besteht:
> Wurde die Schrift als eine der Ressourcen FontAFM, FontPFM oder FontOutline in einer
UPR-Datei oder zur Laufzeit konfiguriert, wird der konfigurierte Dateiname verwen-
det.
> Wurde keine entsprechende Datei gefunden, wird der Schriftname um die folgenden
Endungen ergänzt und mit jedem der resultierenden Namen die Suche nach der
Fontmetrikdatei (oder der Fontdatei im Falle von TrueType- und OpenType-Fonts)
erneut begonnen:
.ttf .otf .afm .pfm .ttc .tte
.TTF .OTF .AFM .PFM .TTC .TTE
> Soll eine PostScript-Schrift eingebettet werden, werden nacheinander die folgenden
Endungen an den Schriftnamen angefügt und es wird versucht, die Fontdatei zu er-
mitteln:
.pfa .pfb
.PFA .PFB
> Alle der oben beschriebenen Namen werden erst so wie sie konstruiert wurden und
dann mit vorangestellten Verzeichnisnamen, die der Ressourcekategorie SearchPath
entnommen werden, zur Suche herangezogen.
Damit findet PDFlib eine Schrift ohne jede manuelle Konfiguration, sofern die Font-
datei aus dem Schriftnamen sowie der dem Schrifttyp entsprechenden Standard-Datei-
namenerweiterung besteht und sich in einem der in SearchPath festgelegten Verzeich-
nisse befindet.
4.3.2 Schrifteinbettung
Die PDF-Standardschriften. PDF-Viewer unterstützen standardmäßig 14 Schriften, die
immer vorhanden sind. PDFlib enthält alle Metrikdaten für die Standardschriften, so
dass keine zusätzlichen Fontdateien erforderlich sind (es sei denn, der Font soll einge-
bettet werden). Die Standardschriften sind:
Courier, Courier-Bold, Courier-Oblique, Courier-BoldOblique,

Helvetica, Helvetica-Bold, Helvetica-Oblique, Helvetica-BoldOblique,
Times-Roman, Times-Bold, Times-Italic, Times-BoldItalic,
Symbol, ZapfDingbats
Hinweis PDFlib enthält derzeit nur die Metriken von Glyphen, die in den Standardschriften von Acrobat
4 und 5 enthalten sind. Seit Version 6 enthalten die Standardschriften von Acrobat weitere (z.B.
polnische) Zeichen, für die PDFlib jedoch keine korrekten Zeichenbreiten zur Verfügung stellt.
Um eine der Standardschriften durch eine auf dem System installierte Schrift (host font)
zu ersetzen, müssen Sie sie in der Ressourcenkategorie HostFont festlegen. Die folgende
Zeile gewährleistet zum Beispiel, dass die Schrift »Symbol« anstatt aus den integrierten
Standardfontdaten direkt vom System abgerufen wird:
PDF_set_parameter(p, "HostFont", "Symbol=Symbol");
PDF unterstützt Schriften jenseits der 14 Standardschriften auf verschiedene Art und
Weise. PDFlib kann Zeichenbeschreibungen in die generierte PDF-Ausgabe einbetten.
Die Schrifteinbettung wird über die Option embedding von PDF_load_font( ) gesteuert (in
manchen Situationen bettet PDFlib eine Schrift jedoch auf jeden Fall ein).
font = PDF_load_font(p, "WarnockPro", 0, "winansi", "embedding");
Alternativ dazu kann ein Fontdeskriptor eingebettet werden, der nur die Metrik der
Zeichen (ohne die eigentlichen Zeichenbeschreibungen) sowie allgemeine Schriftinfor-
mationen enthält. Wird eine Schrift nicht ins PDF-Dokument eingebettet, versucht
Acrobat, sie vom Zielsystem zu beziehen. Ist sie dort nicht vorhanden, wird gemäß den
Angaben des Fontdeskriptors eine Ersatzschrift konstruiert. Tabelle 4.1 zeigt die ver-
schiedenen Situationen bei der Schriftverwendung und die jeweils erforderlichen Font-
und Metrikdateien.
Wird eine Schrift mit fontspezifischem Zeichensatz (Symbolschrift) oder mit Gly-
phen verwendet, die nicht in Adobes Liste lateinischer Standardzeichen (Standard Latin
Character Set) verzeichnet sind, und ist diese Schrift nicht in die PDF-Ausgabe eingebet-
tet, so ist das PDF-Dokument unbrauchbar, sofern die Schrift nicht bereits auf dem Ziel-
system installiert ist (denn Acrobat kann nur lateinische Textschriften simulieren).
Solche PDF-Dokumente sind von Natur aus nicht portierbar, wenngleich sie in be-
schränktem Rahmen wie zum Beispiel beim innerbetrieblichen Dokumentenaustausch
sinnvoll sein können.
Tabelle 4.1 Verschiedene Situationen beim Schrifteinsatz und jeweils erforderliche Metrik- und
Fontdateien
Schrifteinsatz Muss Metrikdatei explizit Muss Fontdatei explizit
konfiguriert werden? konfiguriert werden?
Eine der 14 Standardschriften nein nur bei
Schrifteinbettung
TrueType-, OpenType- oder PostScript-Type-1-Systemschrift, nein nein
die auf Windows oder Mac installiert ist
PostScript-Nichtstandardschrift yes nur bei
Schrifteinbettung
TrueType-Fonts n/a yes
OpenType-Fonts einschließlich CJK-TrueType- und CJK- n/a yes
OpenType-Fonts
Standard-CJK-Fonts1 nein nein
1. Informationen über CJK-Fonts finden Sie in Abschnitt 4.7, »Chinesischer, japanischer und koreanischer Text«, Seite 120.
Erzwungene Schrifteinbettung. Bei bestimmten Kombinationen von Schrift und Zei-

chensatz muss eine Schrift in PDF eingebettet werden. In folgenden Fällen ignoriert
PDFlib deshalb die Benutzeroptionen und führt unabhängig von der Option embedding
immer eine Schrifteinbettung durch:
> Der Wert des encoding-Parameters ist glyphid oder unicode und es handelt sich um
einen TrueType-Font oder einen OpenType-Font mit TrueType-Zeichenbeschrei-
bungen.
> Der Wert des Parameters encoding ist nicht winansi, macroman oder ebcdic und es han-
delt sich um einen TrueType-Font oder einen OpenType-Font mit TrueType-
Zeichenbeschreibungen.
Beachten Sie dabei, dass die Einbettung bei OpenType-Fonts mit PostScript-Zeichenbe-
schreibungen nicht unbedingt erzwungen wird. Das liegt an der internen Konvertie-

rung in einen CID-Font, die deaktiviert werden kann, indem der Parameter autocidfont
auf false gesetzt wird. Damit wird auch die erzwungene Schrifteinbettung deaktiviert. In
diesem Fall sind aber nicht mehr alle lateinischen Zeichen verwendbar und Zeichen au-
ßerhalb der Adobe Glyph List (AGL) sind prinzipiell nicht einsetzbar.
Rechtliche Aspekte der Schrifteinbettung. Es ist wichtig anzumerken, dass der bloße
Besitz einer Fontdatei nicht unbedingt dazu berechtigt, die Schrift in ein PDF-Doku-
ment einzubetten, selbst wenn eine gültige Schriftlizenz vorhanden ist. Zahlreiche
Schriftanbieter lassen die Schrifteinbettung nur eingeschränkt zu, manche verbieten
die Einbettung von Schriften in PDF vollständig, und wieder andere offerieren besonde-
re Online- oder Einbettungslizenzen. Schließlich gibt es auch noch die Variante, die Ein-
bettung nur bei Verwendung von Untergruppen zu erlauben. Überprüfen Sie deshalb
die rechtlichen Aspekte, bevor Sie Schriften mit PDFlib einbetten. PDFlib hält sich an
Einbettungsbeschränkungen, falls diese in einem TrueType- oder OpenType-Font spezi-
fiziert sind. Dies wird über ein Einbettungsflag bewerkstelligt, das auf no embedding1 ge-
setzt sein kann. In diesem Fall kommt PDFlib der Aufforderung des Herstellers nach
und weist jeden Versuch zurück, die Schrift einzubetten.
4.3.3 Bildung von Fontuntergruppen (Subsetting)

Um die Größe der PDF-Ausgabe zu reduzieren, ist PDFlib in der Lage, lediglich diejenigen
Zeichen eines Fonts einzubetten, die im Dokument auch tatsächlich verwendet werden.
Dieser Vorgang wird »Bildung von Fontuntergruppen« genannt. Dabei wird eine neue
Schrift mit entsprechend weniger Glyphen als in der Originalschrift erzeugt, so dass alle
für die PDF-Anzeige überflüssigen Informationen weggelassen werden. Zu beachten ist
aber, dass sich das TouchUp-Textwerkzeug von Acrobat weigert, aus Schriftuntergrup-
pen bestehenden Text zu bearbeiten. Fontuntergruppen sind bei CJK-Fonts besonders
wichtig. PDFlib unterstützt Untergruppen für folgende Fontformate:
> TrueType-Fonts
> OpenType-Fonts mit PostScript- oder TrueType-Zeichenbeschreibungen
Wird ein Font, für den die Untergruppenbildung angefordert wurde, in einem Doku-
ment verwendet, so merkt sich PDFlib, welche Zeichen in der Textausgabe verwendet
wurden. Die Untergruppenbildung lässt sich auf verschiedene Art beeinflussen:
> Der Parameter autosubsetting bestimmt das Standardverhalten bezüglich Untergrup-
penbildung. Ist dieser Parameter gleich true, so wird die Untergruppenbildung für
alle Fonts aktiviert, für die eine Untergruppenbildung möglich ist. Der Standardwert
ist true.
> Wenn der Parameter autosubsetting gleich false ist, Untergruppen aber für einen be-
stimmten Font gebildet werden sollen, so muss PDF_load_font( ) mit der Option
subsetting aufgerufen werden:
font = PDF_load_font(p, "WarnockPro", 0, "winansi", "subsetting");
> Der Parameter subsetlimit enthält einen Prozentwert. Werden in einem Dokument
prozentual zur Gesamtzahl der Glyphen im Font mehr Glyphen verwendet, als durch
den Prozentsatz vorgegeben ist, wird die Untergruppenbildung für den Font deakti-
1. Genauer gesagt: wenn das Flag fsType in der OS/2-Tabelle der Schrift den Wert 2 hat.
viert und dieser komplett eingebettet. Dies spart Rechenzeit, die Ausgabe wird je-
doch etwas größer:
PDF_set_value(p, "subsetlimit", 75); /* Untergruppen-Limit auf 75% setzen */
Der Standardwert für subsetlimit beträgt 100 Prozent. Anders ausgedrückt: die Option
subsetting von PDF_load_font( ) wird immer berücksichtigt, außer der Client setzt das
Limit explizit auf weniger als 100 Prozent.
> Mit dem Parameter subsetminsize lässt sich die Untergruppenbildung für kleine Font-
dateien vollständig deaktivieren. Ist die ursprüngliche Fontdatei kleiner als der Wert
von subsetminsize in KB, wird die Untergruppenbildung für diesen Font deaktiviert.
Der Standardwert beträgt 100 KB.
Einbettung und Untergruppenbildung bei TrueType-Fonts. Die TrueType-Behandlung

ist wegen bestimmter durch PDF bedingter Anforderungen etwas verwirrend. Dieser
Absatz fasst deshalb alle diesbezüglichen Informationen zusammen.
Wird ein TrueType-Font mit einem von winansi und macroman verschiedenen Zei-
chensatz verwendet, wird sie für die PDF-Ausgabe standardmäßig in einen CID-Font
konvertiert. Bei Zeichensätzen, die nur Zeichen aus der Adobe Glyph List (AGL) enthal-
ten, lässt sich dieses Verhalten unterbinden, indem der Parameter autocidfont auf false
gesetzt wird. Wird die Schrift in einen CID-Font konvertiert, wird sie in jedem Fall auch
eingebettet. Standardmäßig werden Schriftuntergruppen gebildet, außer wenn der Pa-
rameter autosubsetting auf false gesetzt oder der Prozentsatz der verwendeten Glyphen
größer als der Parameter subsetlimit ist. Ferner werden keine Untergruppen gebildet bei
Schriften, deren Umfang (Fontdateigröße in KB) kleiner als der Wert des Parameters
subsetminsize ist.

4.4 Zeichensätze
4.4.1 8-Bit-Zeichensätze
Tabelle 4.2 enthält eine Liste aller in PDFlib vordefinierten Zeichensätze sowie Angaben
zu ihrem Einsatz mit wesentlichen Schriftkategorien. Dabei ist zu betonen, dass es
Schriften und Sprachen gibt, die mit gängigen Fonts nicht ausgegeben werden können.
So enthalten zum Beispiel die Standardschriften von Acrobat nicht alle für ISO 8859-2
(zum Beispiel Polnisch) benötigten Zeichen. Diese Anforderung wird von PostScript 3,
OpenType Pro und TrueType »Big Fonts« jedoch erfüllt.
Hinweis Mit PDFlib wird das Beispielprogramm chartab ausgeliefert, mit dem sich bequem Zeichen-
tabellen mit beliebigen Kombinationen aus Font und Zeichensatz ausdrucken lassen.
Hinweise zum Zeichensatz macroman. Dieser Zeichensatz enthält den Mac-OS-Zei-

chensatz mit folgenden Abweichungen: An Position 219 = 0xDB befindet sich das alte
Währungssymbol und nicht das Eurozeichen, wie es von Apple neu definiert wurde
(diese Inkompatibilität ist durch die PDF-Spezifikation bedingt). Der Zeichensatz
macroman_apple entspricht macroman mit folgenden Ausnahmen:
> An Position 219 = 0xDB befindet sich das Eurozeichen statt des Währungssymbols.
> Der Zeichensatz macroman_apple enthält die griechischen/mathematischen Symbo-
le, die im Mac-OS-Zeichensatz definiert sind. Die dazu erforderlichen Glyphen sind
aber nur in wenigen Schriften vorhanden.
Zeichensatz host. Der Zeichensatz host spielt eine Sonderrolle, da es sich um keinen
bestimmten Zeichensatz handelt. Je nach aktueller Plattform wird er auf einen speziel-
len 8-Bit-Zeichensatz abgebildet:
> Auf Mac OS Classic wird er auf macroman abgebildet.
> Auf IBM eServer zSeries mit MVS oder USS wird er auf ebcdic abgebildet.
> Auf IBM eServer iSeries wird er auf ebcdic_37 abgebildet.
> Auf Windows wird der auf winansi abgebildet.
> Auf allen anderen Systemen (einschließlich Mac OS X) wird er auf iso8859-1 abgebil-
det.
Der Zeichensatz host eignet sich insbesondere bei plattformunabhängigen Testpro-

grammen (zum Beispiel den mit PDFlib ausgelieferten oder anderen einfachen Anwen-
dungen). Es wird jedoch davon abgeraten, ihn im produktiven Einsatz zu verwenden;
stattdessen sollte der benötigte Zeichensatz immer explizit angegeben werden.
Automatische Auswahl des Zeichensatzes. PDFlib unterstützt ein Verfahren, mit dem
für bestimmte Umgebungen automatisch der jeweils am besten passende Zeichensatz
bestimmt wird. Das Schlüsselwort auto als Wert für den Parameter encoding legt einen
plattform- und umgebungsspezifischen 8-Bit-Zeichensatz wie folgt fest:
> Unter Windows: aktuelle Codepage des Systems (Einzelheiten siehe unten)
> Unter Unix und Mac OS X: iso8859-1 (mit Ausnahme von LWFN-PostScript-Schriften
auf dem Mac, für die auto auf macroman abgebildet wird)
> Auf Mac OS Classic: macroman
> Auf IBM eServer iSeries: Zeichensatz des aktuellen Jobs (IBMCCSID000000000000)
> Auf IBM eServer zSeries: ebcdic (entspricht Codepage 1047)
Tabelle 4.2 Verfügbarkeit von Glyphen für vordefinierte Zeichensätze in verschiedenen Schriftkategorien;
manche Sprachen sind mit Acrobat-Standardschriften nicht darstellbar.
Standardschriften
Acrobat 6/72
»Big Fonts«5
Acrobat 4/51
PS Level 1/2,
PostScript 3
Pro Fonts4
OpenType
TrueType
Fonts3
Codepage Unterstützte Sprachen
winansi Entspricht cp1252, einer Obermenge von ISO 8859-1 ja ja ja ja ja

macroman Mac Roman, der Standard-Macintosh-Zeichensatz ja ja ja ja ja
macroman_ Wie macroman, aber Euro- statt Währungszeichen – – – ja ja
apple sowie griechische/mathematische Symbole
ebcdic EBCDIC-Codepage 1047 ja ja ja ja ja
ebcdic_37 EBCDIC Codepage 037 ja ja ja ja ja
pdfdoc PDFDocEncoding ja ja ja ja ja
iso8859-1 (Latin-1) Westeuropäische Sprachen ja ja ja ja ja
iso8859-2 (Latin-2) Slawische Sprachen in Mitteleuropa – – ja ja ja
iso8859-3 (Latin-3) Esperanto, Maltesisch – – – ja ja
iso8859-4 (Latin-4) Estnisch, die baltischen Sprachen, – – – ja ja
Grönländisch
iso8859-5 Bulgarisch, Russisch und Serbisch – – – ja ja
iso8859-6 Arabisch – – – nein ja
iso8859-7 Modernes Griechisch – – – 1 Z. ja
fehlt
iso8859-8 Hebräisch und Jiddisch – – – – ja
iso8859-9 (Latin-5) Westeuropäisch, Türkisch 5 Z. 5 Z. ja ja ja
fehl. fehl.
iso8859-10 (Latin-6) Nordische Sprachen (Variation von Latin- – – – 1 Z. ja
4) fehlt
iso8859-13 (Latin-7) Baltische Sprachen – – ja ja ja
iso8859-14 (Latin-8) Keltisch – – – – –
iso8859-15 (Latin-9) Ergänzt Latin-1 um Euro- sowie Euro ja ja ja ja
französiche und finnische Zeichen fehlt
iso8859-16 (Latin-10) Ungarisch, Polnisch, Rumänisch, – – ja ja ja
Slowenisch
cp1250 Mitteleuropäisch – – ja ja ja
cp1251 Kyrillisch – – – ja ja
cp1252 Westeuropäisch (als winansi impl.) ja ja ja ja ja
cp1253 Griechisch – – – 1 Z. ja
fehlt
cp1254 Türkisch 5 Z. – ja ja ja
fehl.
cp1255 Hebräisch – – – – ja
cp1256 Arabisch – – – – 5 Z.
fehl.
cp1257 Baltisch – – ja ja ja
cp1258 Vietnamesisch – – – – ja
1. Ursprünglicher Adobe Latin Zeichensatz (Type-1-Fonts seit 1982)
2. Acrobat 6 verlässt sich auf die Fonts, die im System zur Anzeige von Times und Helvetica verfügbar sind. Die Ergebnisse
sind deswegen sehr unterschiedlich, je nachdem, wie viele und welche Fonts installiert sind. Die Systemschriften in Win-
dows XP enthalten zum Beispiel mehr Glyphen als die mit älteren Windows-Versionen ausgelieferten Schriften.
3. Erweiterter Adobe Latin Zeichensatz (CE-Fonts) (Type-1-Fonts seit PostScript 3)
4. Adobe OpenType Pro Fonts enthalten mehr Glyphen als reguläre OpenType-Schriften.
5. Windows-TrueType-Fonts, die zahlreiche Glyphen enthalten, zum Beispiel Tahoma
Bei Symbolschriften wird das Schlüsselwort auto auf den Zeichensatz builtin abgebildet.
Diese Art der automatischen Zeichensatzwahl mag in vielen Situationen bequem sein,
die Portabilität Ihrer PDFlib-Clientprogramme ist damit aber nicht mehr gewährleistet.
Abrufen von System-Codepages. PDFlib kann angewiesen werden, Codepage-Definiti-

onen vom System zu holen und diese zur internen Verwendung aufzubereiten. Dies ist
äußerst praktisch, da Sie die Codepage-Definition dann nicht selbst zu implementieren
brauchen. Statt an PDF_load_font( ) den Namen eines integrierten oder benutzerdefi-
nierten Zeichensatzes zu übergeben, verwenden Sie einfach einen dem System bekann-
ten Namen. Diese Funktion ist nur auf bestimmten Plattformen verfügbar. Die Syntax
des Strings für den Zeichensatznamen ist entsprechend plattformabhängig:
> Unter Windows lautet der Zeichensatzname cp<nummer>, wobei <nummer> der Num-
mer einer im System installierten Ein-Byte-Codepage entspricht (Informationen
über Multibyte-Codepages in Windows finden Sie in Abschnitt 4.7.3, »Benutzerspezi-
fische CJK-Fonts«, Seite 124):
PDF_load_font(p, "Helvetica", 0, "cp1250", "");
Ein-Byte-Codepages werden in einen internen 8-Bit-Zeichensatz umgewandelt, wäh-

rend Multibyte-Codepages immer auf unicode abgebildet werden. Text muss in ei-
nem Format übergeben werden, das zur gewählten Codepage kompatibel ist (zum
Beispiel SJIS für cp932).
> Auf IBM eServer iSeries kann ein beliebiger Coded Character Set Identifier (CCSID) ver-
wendet werden. Der CCSID ist als String zu übergeben, und PDFlib fügt das Präfix
IBMCCSID an die übergebene Codepage-Nummer an. PDFlib füllt die Nummer außer-
dem mit führenden Nullzeichen (0) auf, wenn diese über weniger als 5 Zeichen ver-
fügt. Wird 0 (Null) als Codepage-Nummer übergeben, so wird der Zeichensatz des ak-
tuellen Jobs verwendet:
PDF_load_font(p, "Helvetica", 0, "273", "");
> Auf IBM eServer zSeries mit USS oder MVS kann ein beliebiger Coded Character Set
Identifier (CCSID) verwendet werden. Der CCSID ist als String zu übergeben, und PDF-
lib leitet den übergebenen Codepagenamen unverändert ans System weiter:
PDF_load_font(p, "Helvetica", 0, "IBM-273", "");
Benutzerdefinierte 8-Bit-Zeichensätze. Neben vordefinierten Zeichensätzen unter-

stützt PDFlib benutzerdefinierte 8-Bit-Zeichensätze. Diese benötigen Sie, wenn Sie mit
einem Zeichensatz arbeiten, der in PDFlib intern nicht verfügbar ist, zum Beispiel eine
andere EBCDIC-Codepage, als die von PDFlib intern unterstützte. Zusätzlich zu Zeichen-
satztabellen mit PostScript-Glyphennamen akzeptiert PDFlib Unicode-basierte Codepa-
ge-Tabellen.
Folgende Schritte sind erforderlich, um einen benutzerdefinierten Zeichensatz in ei-
nem PDFlib-Programm zu verwenden (alternativ dazu lässt sich der Zeichensatz auch
zur Laufzeit mit PDF_encoding_set_char( ) aufbauen):

> Legen Sie eine Beschreibung des Zeichensatzes in einer einfachen Textdatei an.
> Konfigurieren Sie den Zeichensatz in der PDFlib-Ressourcendatei (siehe Abschnitt
3.1.5, »Ressourcenkonfiguration und Dateisuche«, Seite 56) oder über PDF_set_
parameter( ).
> Stellen Sie eine Schrift bereit (Metrik- und gegebenenfalls Fontdatei), die alle im Zei-
chensatz verwendeten Zeichen enthält.
In der Encoding-Datei werden einfach zeilenweise alle Glyphennamen und die dazuge-
hörigen Nummern aufgelistet. Das folgende Beispiel zeigt den Anfang einer Zeichen-
satz-Definition:
% Zeichensatz-Definition für PDFlib mittels Glyphennamen
% name code Unicode (optional)
space 32 0x0020
exclam 33 0x0021
...
Das folgende Beispiel zeigt einen Ausschnitt aus einer Unicode-Codepage:

% Codepage-Definition für PDFlib mittels Unicode-Werten
% Unicode code
0x0020 32
0x0021 33
...
Formal ausgedrückt ist der Inhalt einer Zeichensatz- oder Codepage-Datei nach folgen-
den Regeln aufgebaut:
> Kommentare beginnen mit einem Prozentzeichen ’%’ und enden am Zeilenende.
> Der erste Eintrag in einer Zeile ist entweder ein PostScript-Zeichenname oder ein
hexadezimaler Unicode-Wert, der sich aus dem Präfix 0x und vier hexadezimalen
Ziffern (in Groß- oder Kleinschreibung) zusammensetzt. Darauf folgen Leer- oder Ta-
bulatorzeichen sowie ein hexadezimaler (0x00–0xFF) oder dezimaler (0–255) Zei-
chencode. Encoding-Dateien mit Glyphennamen können optional eine dritte Spalte
mit dem entsprechenden Unicode-Wert enthalten.
> Zeichencodes, die in der Encoding-Datei nicht vorkommen, gelten als nicht definiert.
Alternativ dazu kann für nicht kodierte Zeichen der Unicode-Wert 0x0000 oder der
Zeichenname .notdef verwendet werden.
Per Konvention bezeichnen wir Tabellen mit Zeichennamen als Encoding-Dateien

(encoding files, *.enc) und Tabellen mit Unicode-Werten als Codepage-Dateien (*.cpg), ob-
wohl PDFlib beide auf dieselbe Art behandelt und sich nicht um Dateinamen kümmert.
PDFlib konvertiert automatisch zwischen Encoding-Dateien mit Glyphennamen und
Codepage-Dateien mit Unicode-Werten, sobald dies erforderlich ist. Diese Konvertie-
rung basiert auf Adobes Standardliste der PostScript-Glyphennamen (der Adobe Glyph
List oder AGL1). Es können aber auch Namen verwendet werden, die dort nicht verzeich-
net sind. PDFlib setzt dann für diese Nicht-AGL-Namen freie Unicode-Werte fest und
korrigiert diese beim Einlesen von OpenType-Fonts, in denen die Zuordnung zwischen
Glyphennamen und Unicode-Werten gespeichert ist.
Die AGL ist in PDFlib integriert und enthält mehr als 1000 Glyphennamen. Enco-
ding-Dateien sind bei PostScript-Fonts mit Glyphennamen erforderlich, die nicht dem
1. Die AGL kann unter partners.adobe.com/public/developer/en/opentype/glyphlist.txt abgerufen werden.

Standard entsprechen, während Codepages sich besser für den Umgang mit TrueType-
oder OpenType-Fonts eignen, die auf Unicode basieren.
4.4.2 Symbolschriften und fontspezifische Zeichensätze

Da Symbol- und Logo-Fonts (auch Pi-Fonts genannt) gewöhnlich keine Standardzeichen
enthalten, müssen Sie anders als Textschriften kodiert werden.
Der builtin-Zeichensatz für PostScript-Fonts. Der Name builtin bezieht sich nicht auf
eine bestimmte Anordnung der Zeichen, sondern bedeutet einfach »nimm die Schrift
wie sie ist und ändere den Zeichensatz nicht«. Dieses Konzept wird auch als schriftspezi-
fischer (fontspecific) Zeichensatz bezeichnet und spielt bei Logo- und Symbolfonts eine
entscheidende Rolle. Es ist ebenfalls (teilweise unangemessen) weit verbreitet bei nicht-
lateinischen Fonts (wie Griechisch oder Kyrillisch). Solche Fonts können nicht mithilfe
eines der unterstützten Zeichensätze umkodiert werden, da ihre Zeichennamen nicht
mit denen in den Zeichensätzen übereinstimmen. builtin muss deshalb für alle Symbol-
schriften oder Nicht-Text-PostScript-Schriften verwendet werden. Ob es sich um eine
Nicht-Text-Schrift handelt, lässt sich aus folgendem Eintrag in der AFM-Datei ermitteln:
EncodingScheme FontSpecific
Textfonts können umkodiert (das heißt an eine bestimmte Codepage oder einen be-
stimmten Zeichensatz angepasst) werden. Mit Symbolfonts ist dies nicht möglich, so
dass dort der Zeichensatz builtin verwendet werden muss. Die weit verbreiteten Schrif-
ten Symbol und ZapfDingbats lassen sich jedoch auch mit dem Zeichensatz unicode ver-
wenden.
Der Zeichensatz builtin kann nicht für benutzerdefinierte (Type-3-) Fonts verwendet
werden, da diese keinen Standardzeichensatz enthalten.
Hinweis Leider hat sich das Konzept der schriftspezifischen Zeichensätze bei Schriftentwicklern und
Schriftherstellern nicht vollständig durchgesetzt (dies mag an mangelhaften Entwicklungs-
tools liegen). So findet man viele lateinische Textfonts mit vorgeblich schriftspezifischem Zei-
chensatz und zahlreiche Symbolfonts, die fälschlicherweise als Textschriften gekennzeichnet
sind.
Zeichensatz builtin für TrueType-Fonts. TrueType-Fonts mit Symbolen wie Wingdings

müssen mit dem Zeichensatz builtin verwendet werden. Wenn ein Font den Zeichensatz
builtin voraussetzt, der Client aber einen anderen Zeichensatz gefordert hat, verwendet
PDFlib trotzdem in jedem Fall den Zeichensatz builtin.
Zeichensatz builtin für OpenType-Fonts mit PostScript-Definitionen (*.otf). OTF-Fonts

mit Symbolen sollten mit dem Zeichensatz builtin verwendet werden. Manche OTF-
Fonts enthalten intern einen Standardzeichensatz. PDFlib erkannt dies und konstruiert
dynamisch einen für die Schrift passenden Zeichensatz. Der Zeichensatzname builtin
wird dann zu builtin_<fontname> geändert. Der neue Zeichensatzname kann dann zwar
generell in Aufrufen von PDF_load_font( ) verwendet werden, er ist jedoch nur in Kombi-
nation mit derselben Schrift sinnvoll.

4.4.3 Glyph-ID-Adressierung für TrueType- und OpenType-Fonts
Neben 8-Bit-Zeichensätzen, Unicode und CMaps unterstützt PDFlib ein Verfahren
namens Glyph-ID-Adressierung, mit dem einzelne Zeichen einer Schrift adressiert wer-
den können. Um dieses Verfahren nutzen zu können, müssen folgende Voraussetzun-
gen erfüllt sein:
> Die Schrift ist im TrueType- oder OpenType-Format verfügbar.
> Die Schrift muss ins PDF-Dokument eingebettet werden (vollständig oder als Unter-
gruppe).
> Der Entwickler kennt die interne Nummerierung der in der Schrift vorkommenden
Glyphen.
Glyph-IDs (GIDs) werden in TrueType- und OpenType-Fonts intern verwendet. Sie stel-
len eine eindeutige Adressierung der Glyphen in einer Schrift dar. Die GID-Adressierung
befreit den Entwickler von jeder Encoding-bedingten Beschränkung und bietet Zugriff
auf alle Glyphen, die der Schriftentwickler in die Fontdatei aufgenommen hat. Es exis-
tiert aber keinerlei Beziehung zwischen GIDs und gängigeren Adressierungsverfahren
wie Windows-Zeichensatz oder Unicode. Die Konvertierung von anwendungsspezifi-
schen Codes zu GIDs obliegt damit dem PDFlib-Benutzer.
Die GID-Adressierung wird mit dem Schlüsselwort glyphid als encoding-Parameter für
PDF_load_font( ) aktiviert. GIDs werden von 0 bis zum letzten Glyph-ID-Wert, der mit
dem Parameter fontmaxcode abgefragt werden kann, fortlaufend durchnummeriert.
4.4.4 Das Eurozeichen

Um das Zeichen für die europäische Währung Euro sauber anzuzeigen
und zu drucken, müssen eine Reihe von Faktoren berücksichtigt werden.
Wir möchten hier deshalb einige Hinweise geben, die Ihnen im Umgang
mit dem Eurozeichen von Nutzen sein können.
Vor allem anderen müssen Sie einen Zeichensatz wählen, der das Euro-
zeichen enthält, und überprüfen, an welcher Position es sich befindet. Ei-
nige Beispiele:
> Im Zeichensatz unicode verwenden Sie das Zeichen U+20AC.
> Im Zeichensatz winansi befindet es sich an Position 0x80 (hexadezimal) oder 128 (de-
zimal).
> Der weit verbreitete Zeichensatz iso8859-1 enthält kein Eurozeichen. Der Zeichensatz
iso8859-15 stellt eine Erweiterung von iso8859-1 dar, in der das Eurozeichen an Posi-
tion 0xA4 (hexadezimal) oder 164 (dezimal) ergänzt wurde.
> Der ursprüngliche macroman-Zeichensatz enthält kein Eurozeichen. Apple modifi-
zierte diesen Zeichensatz und ersetzte an Position 0xDB (hexadezimal) bzw. 219 (de-
zimal) das alte Währungszeichen mit dem Eurozeichen. Um den modifizierten Mac-
Zeichensatz zu verwenden, wählen Sie macroman_apple statt macroman.
Außerdem müssen Sie eine Schrift wählen, die das Eurozeichen enthält. Dies ist bei vie-
len, aber durchaus nicht allen modernen Schriften der Fall. Auch hier einige Beispiele:
> Die in PostScript-Level-1- und Level-2-Geräten eingebauten Schriften enthalten kein
Eurozeichen, während PostScript-3-Geräte in der Regel über das Eurozeichen verfü-
gen.
> Enthält eine Schrift das Eurozeichen nicht, können Sie ersatzweise den Euro aus dem
Font »Symbol« verwenden, der sich dort an Position 0xA0 (hexadezimal) bzw. 160

(dezimal) befindet. Er ist in der Version des Symbol-Fonts, die ab Acrobat Version 4.0
ausgeliefert wird, sowie in dem in PostScript-3-Geräte eingebauten Symbol-Font ver-
fügbar.

4.5 Unicode-Unterstützung
PDFlib unterstützt den Unicode-Standard1, der im Wesentlichen ISO
10646 entspricht, in zahlreichen Funktionen für Seitenbeschreibun-
gen und Hypertext-Elemente.
4.5.1 Unicode für Seitenbeschreibungen und Hypertext

Unicode-Strings können in Seitenbeschreibungen direkt übergeben und mit folgenden
Fontformaten verwendet werden:
> PostScript-Fonts mit Encoding unicode. Es können maximal 255 verschiedene Uni-
code-Werte verwendet werden. Darüber hinausgehende Werte werden durch ein
Leerzeichen ersetzt. Der Zeichensatz unicode wird bei einer Schrift mit PFM-Metrikda-
tei immer auf winansi abgebildet, und bei PostScript-Systemschriften auf dem Mac
auf macroman.
> TrueType- und OpenType-Fonts mit Encoding unicode. TrueType- und OpenType-
Fonts werden dann in jedem Fall eingebettet.
> Standard-CJK-Fonts mit einer CMap mit Unicode-Werten. Unicode-kompatible
CMaps sind leicht am Namenspräfix Uni zu erkennen (siehe Tabelle 4.7).
> Benutzerspezifische CJK-Fonts mit Encoding unicode.
> Auf Windows-Systemen können Unicode-Dateinamen verwendet werden.
Neben dem unicode-Encoding unterstützt PDFlib mehrere andere Methoden zur Aus-
wahl von Unicode-Zeichen.
Unicode-Codepages für PostScript- und TrueType-Fonts. PDFlib unterstützt Unicode-

Adressierung für alle Zeichen in der Adobe Glyph List (AGL). Diese Art der Unicode-Un-
terstützung ist für TrueType-Fonts verfügbar, die auf Unicode-Werten basieren, sowie
für PostScript-Fonts mit Glyphennamen in der AGL.
Sie kann mittels einer der internen Codepages von PDFlib oder einer geeigneten be-
nutzerdefinierten Encoding- oder Codepage-Datei aktiviert werden (siehe Abschnitt
4.4.1, »8-Bit-Zeichensätze«, Seite 98).
8-Bit-Strings zur Adressierung von Unicode-Segmenten. PDFlib unterstützt ein Kurz-

format, das zur Adressierung von maximal 256 aufeinander folgenden Unicode-Zeichen
verwendet werden kann. Diese Folge von Zeichen kann an einem beliebigen Wert zwi-
schen U+0000 und U+FFFF beginnen. Damit kann ein kleiner Ausschnitt aus dem Uni-
code-Bereich genutzt und trotzdem mit 8-Bit-Zeichen gearbeitet werden.
Diese Funktion kann aktiviert werden, indem PDF_load_font( ) mit dem String
U+XXXX für den Parameter encoding aufgerufen wird, wobei XXXX einem hexadezimalen
Startwert entspricht. Der Wert eines 8-Bit-Zeichens wird zum übergebenen Startwert
addiert. Der Encoding
U+0400
selektiert zum Beispiel den kyrillischen Unicode-Abschnitt. 8-Bit-Strings, die an Text-

funktionen übergeben werden, benutzen dann die Unicode-Zeichen U+0400, U+0401
etc.
1. Siehe www.unicode.org

Korrekte Unicode-Werte bei Textextraktion und Suche. PDFlib ergänzt die PDF-Ausga-
be um Zusatzinformationen (eine ToUnicode CMap), die von Acrobat zur korrekten Zu-
ordnung von Unicode-Werten bei der Textextraktion (zum Beispiel über die Zwischen-
ablage) und bei der Textsuche herangezogen wird. Standardmäßig werden für alle
unterstützten Fontformate ToUnicode-CMaps generiert, die jedoch nur eingebettet
werden können, wenn Unicode-Informationen für die gegebene Font/Zeichensatz-
Kombination verfügbar ist. Dies ist zwar meist der Fall, benutzerdefinierte Type-3-Fonts
verfügen aber zum Beispiel nicht unbedingt über Unicode-Informationen. In solchen
Fällen kann PDFlib keine ToUnicode-CMap generieren, und eine Textextraktion oder
Suche ist in Acrobat nicht möglich.
Die Generierung einer ToUnicode-CMap kann global mit dem Parameter unicodemap
oder für eine Schrift mit PDF_load_font( ) und der Option unicodemap deaktiviert wer-
den. Standardmäßig ist dieser Parameter bzw. die Option auf true gesetzt. Wenn Sie den
Wert auf false setzen, reduzieren Sie zwar die Größe der Ausgabedatei, verhindern aber
unter Umständen die korrekte Textextraktion in Acrobat.
Unicode für Hypertext-Strings. Unicode kann für verschiedenste Hypertext-Elemente

übergeben werden, etwa Lesezeichen, Inhalt und Titel von Textanmerkungen bzw. Noti-
zen (siehe Abbildung 4.1), benutzerdefinierte oder Standard-Dokumentinfofelder, Be-
schreibung und Verfasser von Dateianlagen.
Während PDF für Hypertext-Elemente nur Unicode mit »Big-Endian«-Bytereihenfol-
ge und PDFDocEncoding als Obermenge von ISO 8859-1 unterstützt, erlaubt PDFlib alle
8-Bit- und auf Unicode basierenden Zeichensätze sowie im System installierte Codepa-
ges, die von PDF_load_font( ) akzeptiert werden, und führt automatisch alle erforderli-
chen Konvertierungen durch.
4.5.2 Content-Strings, Hypertext-Strings und Name-Strings

Abhängig vom Verwendungszweck wird in PDFlib zwischen folgenden Stringtypen un-
terschieden:
Abb. 4.1
Unicode-Lesezeichen (links) und Uni-
code-Textanmerkungen (rechts)

> Content-Strings: werden zur Erstellung von ursprünglichem Seiteninhalt (Seitenbe-
schreibungen) verwendet, wobei der Zeichensatz, der vom Benutzer für die jeweilige
Schrift gewählt wurde, zum Einsatz kommt. In diese Kategorie gehören alle Text-Pa-
rameter für Funktionen, die Seiteninhalte bearbeiten und in Abschnitt 8.3.4, »Einfa-
che Textausgabe«, Seite 249, sowie Abschnitt 8.3.5, »Mehrzeilige Textausgabe mit
Textflüssen«, Seite 258, beschrieben werden.
> Hypertext-Strings: werden vorwiegend für Hypertext-Funktionen wie Lesezeichen
und Anmerkungen verwendet und in den Funktionsbeschreibungen explizit als
Hypertext-String bezeichnet. Unter anderem gehören in diese Kategorie zahlreiche
Parameter und Optionen der Funktionen in Abschnitt 8.9, »Hypertext-Funktionen«,
Seite 317.
> Name-Strings: werden für externe Dateinamen, Fontnamen, Blocknamen etc. ver-
wendet und in den Funktionsbeschreibungen als Name-String bezeichnet. Sie unter-
scheiden sich geringfügig von Hypertext-Strings, jedoch nur in nicht Unicode-fähi-
gen Sprachen (siehe Abschnitt 4.5.4, »String-Behandlung in nicht Unicode-fähigen
Sprachen«, Seite 108).
Ersetzung von Unicode-Zeichen, für die es keine Glyphen gibt. Content-Strings wer-
den immer mit einem bestimmten Font auf der Seite dargestellt. Allerdings gibt es kei-
nen Font mit allen Zeichen des aktuellen Unicode-Standards. Während es Aufgabe des
PDFlib-Anwenders ist, geeignete Fonts zu beschaffen, verhindert PDFlib einige häufige
Probleme, indem bestimmte Zeichen durch grafisch gleichwertige ersetzt werden, falls
die ursprüngliche Glyphe nicht im Font vorhanden ist und die Option glyphwarning den
Wert false hat. The folgende (unvollständige) Liste enthält einige dieser Zeichenpaare.
Falls das erste Zeichen der Liste im Font nicht verfügbar ist, wird es automatisch durch
das zweite ersetzt:
U+00A0 (NO-BREAK SPACE) U+0020 (SPACE)
U+00AD (SOFT HYPHEN) U+002D (HYPHEN-MINUS)
U+2010 (HYPHEN) U+002D (HYPHEN-MINUS)
U+03BC (GREEK SMALL LETTER MU) U+00C5 (MICRO SIGN)
U+212B (ANGSTROM SIGN) U+00B5 (LATIN CAPITAL LETTER A WITH RING ABOVE Å)
U+220F (N-ARY PRODUCT) U+03A0 (GREEK CAPITAL LETTER PI)
U+2126 (OHM SIGN) U+03A9 (GREEK CAPITAL LETTER OMEGA)
Über diese eingebaute Tabelle hinaus werden die Fullwidth-Zeichen U+FF01 bis U+FF5E
durch die zugehörigen Zeichen aus ISO 8859-1 ersetzt (also U+0021 bis U+007E), falls die
Fullwidth-Varianten im Font nicht verfügbar sind.
4.5.3 Stringbehandlung in Unicode-fähigen Sprachen

Folgende PDFlib-Sprachbindungen sind Unicode-fähig:
> COM
> .NET
> Java
> REALbasic
> Tcl
In diesen Umgebungen ist die Stringbehandlung einfach: Alle Strings werden an den
PDFlib-Kern automatisch als Unicode-Strings im Format UTF-16 übergeben. Vom Client
übergebene Unicode-Strings werden von den Sprachwrappern korrekt verarbeitet, die

automatisch auch bestimmte PDFlib-Parameter setzen. Dies hat folgende Konsequen-
zen:
> Da die Parameter textformat, hypertextformat und hypertextencoding vom Sprach-
wrapper automatisch gesetzt werden, sind sie für den Client nicht verfügbar und
dürfen nicht verwendet werden. Der PDFlib-Sprachwrapper führt alle notwendigen
Konvertierungen durch, sodass vom Client übergebene Hypertext-Strings in PDFlib
immer im Format utf16 und im Zeichensatz unicode ankommen.
> Da die Sprachumgebung Strings prinzipiell in UTF-16 an PDFlib übergibt, ist UTF-8 in
Unicode-fähigen Sprachen nicht einsetzbar und muss erst mit den von der jeweili-
gen Umgebung angebotenen Methoden nach UTF-16 konvertiert werden.
> In Unicode-fähigen Sprachen lassen sich Zeichensätze für Seiteninhalte am ein-
fachsten mit dem Zeichensatz unicode bearbeiten.
> In Seitenbeschreibungen dürfen für Standard-CJK-Schriften nur auf Unicode basie-
rende CMaps verwendet werden, da der Wrapper immer Unicode an den PDFlib-Kern
übergibt.
Clients können also ohne zusätzliche Konfigurations- oder Parametereinstellung reine

Unicode-Strings an PDFlib-Funktionen übergeben.
4.5.4 String-Behandlung in nicht Unicode-fähigen Sprachen

Hinweis Dieser Abschnitt bezieht sich nicht auf die Unicode-fähigen Sprachen Java und Tcl.
Folgende PDFlib-Sprachbindungen sind nicht Unicode-fähig:

> C (kein integrierter String-Datentyp)
> C++
> Cobol (kein integrierter String-Datentyp)
> Perl
> PHP
> Python
> RPG (kein integrierter String-Datentyp)
> Ruby
In Sprachbindungen ohne integrierten String-Datentyp (z.B. C, Cobol, RPG), ist die Länge
von UTF-16-Strings in einem eigenen Parameter length zu übergeben. Unicode-Text
kann in diesen Sprachen zwar verwendet werden, die Behandlung der verschiedenen
Stringtypen ist aber etwas komplizierter:
> Content-Strings: sind Strings zur Erzeugung von echtem Seiteninhalt. Die Interpreta-
tion solcher Strings wird mit den Parametern textformat (siehe unten) und encoding
für PDF_load_font( ) gesteuert. Ist textformat gleich auto (Standardeinstellung), wird
für die Zeichensätze unicode und glyphid sowie für UCS-2-CMaps das Format utf16 ver-
wendet. Für alle anderen Zeichensätze kommt das Format bytes zum Einsatz. In Spra-
chen ohne integrierten String-Datentyp (siehe oben) ist die Länge der UTF-16-Strings
in einem eigenen Längenparameter zu übergeben.
> Hypertext-Strings: werden anhand der Parameter hypertextformat und hyper-
textencoding interpretiert (siehe unten). Ist hypertextformat gleich auto (Standardein-
stellung), wird das Format utf16 für hypertextencoding=unicode und sonst bytes ver-
wendet. In Sprachen ohne integrierten String-Datentyp (siehe oben), ist die Länge
von UTF-16-Strings in einem eigenen Längenparameter zu übergeben.

> Name-Strings: werden fast wie Strings für Seitenbeschreibungen interpretiert. Im all-
gemeinen werden Name-Strings im Zeichensatz host interpretiert (siehe Abschnitt
»Zeichensatz host«, Seite 98). Beginnt der Name-String jedoch mit einem UTF-8-
BOM, wird vom Format UTF-8 ausgegangen (bzw. vom Format EBCDIC UTF-8, wenn
der String mit einem EBCDIC UTF-8 BOM beginnt). In Sprachen ohne integrierten
String-Datentyp muss der Parameter length bei UTF-8-Strings gleich 0 sein. Ist er von
0 verschieden, wird der String als UTF-16 interpretiert. Bei Sprachen, die nicht Uni-
code-fähig sind, aber einen String-Datentyp besitzen, gibt es in den API-Funktionen
keinen Parameter length. Zur Erstellung von Unicode-Name-Strings können Sie in
diesem Fall die Hilfsfunktion PDF_utf16_to_utf8( ) verwenden, um UTF-8 zu erzeugen.
Strings in Optionslisten. Strings in Optionslisten erfordern besondere Berücksichti-

gung, da sie sich nicht als Unicode-Strings im Format UTF-16, sondern nur als Byte-
Strings ausdrücken lassen. Für Unicode-Optionen wird deshalb UTF-8 verwendet. PDFlib
interpretiert die Option abhängig davon, ob sich am Anfang ein BOM befindet. Anhand
des BOMs wird das Stringformat und anhand des Stringtyps (Content-, Hypertext- oder
Name-String) der passende Zeichensatz bestimmt. Im Einzelnen wird eine Stringoption
wie folgt interpretiert:
> Beginnt die Option mit einem UTF-8-BOM (\xEF\xBB\xBF), wird sie als String im For-
mat UTF-8 interpretiert. Beginnt sie mit einem EBCDIC UTF-8 BOM (\x57\x8B\xAB),
wird sie als String im Format EBCDIC UTF-8 interpretiert.
> Ist kein BOM vorhanden, wird der String mit dem Zeichensatz interpretiert, der im
Parameter bzw. der Option hypertextencoding festgelegt ist. Handelt es sich um einen
Name-String, wird er mit dem Zeichensatz host interpretiert.
Hinweis Mit der Hilfsfunktion PDF_utf16_to_utf8( ) können UTF-16-Strings in UTF-8-Strings konvertiert
werden. Dies ist zur Erzeugung von Optionslisten mit Unicode-Werten nützlich.
Textformate für Unicode-Strings. Der Unicode-Standard unterstützt mehrere Trans-

formationsformate, die die tatsächlich in einem Unicode-Strings enthaltenen Byte-
Werte speichern. Diese unterscheiden sich in der Anzahl der Bytes pro Zeichen sowie
der Bytereihenfolge innerhalb eines Zeichens. Unicode-Strings können in PDFlib in den
Formaten UTF-8 oder UTF-16 in beliebiger Bytereihenfolge übergeben werden. Dies lässt
sich für Text in Seitenbeschreibungen mit dem Parameter textformat und für Hyper-
text-Elemente mit dem Parameter hypertextformat steuern. Tabelle 4.3 zeigt, welche
Werte die beiden Parameter annehmen können.
Tabelle 4.3 Textformate

Textformat Erklärung
bytes Ein Byte im String entspricht einem Zeichen. Dies eignet sich in erster Linie für 8-Bit-Zeichensätze.
utf8 Strings werden im Format UTF-8 erwartet.
ebcdicutf8 Strings werden im Format UTF-8 in EBCDIC-Kodierung erwartet (nur auf iSeries und zSeries).
utf16 Strings werden im Format UTF-16 erwartet. Das Unicode Byte Order Mark (BOM) am Anfang des
Strings wird ausgewertet und dann entfernt. Ist das BOM nicht vorhanden, wird der String in der
Bytereihenfolge des Systems erwartet (auf Intel x86-Architekturen gilt »Little-Endian«-
Bytereihenfolge und auf Sparc- oder PowerPC-Systemen »Bid-Endian«).
utf16be Strings werden im UTF-16-Format in »Big-Endian«-Bytereihenfolge erwartet. Es findet keine
besondere Behandlung des Byte Order Mark statt.

Tabelle 4.3 Textformate
Textformat Erklärung
utf16le Strings werden im UTF-16-Format in »Little-Endian«-Bytereihenfolge erwartet. Es findet keine
besondere Behandlung des Byte Order Mark statt.
auto Entspricht bytes für 8-Bit-Zeichensätze und utf16 bei erweiterter Adressierung (unicode, glyphid,
oder UCS2- bzw. UTF16-CMap). In Umgebungen ohne native Unicode-Unterstützung wird Text
mittels dieser Einstellung in der Regel korrekt interpretiert.
Die Standardeinstellung für den Parameter textformat ist utf16 für Unicode-fähige
Sprachbindungen, andernfalls auto.
Die textformat-Einstellung bezieht sich zwar auf alle Zeichensätze, ist aber am nütz-
lichsten beim unicode-Encoding. Tabelle 4.4 zeigt die Interpretation von Text-Strings bei
verschiedenen Kombinationen von Encodings und textformat-Einstellungen.
Tabelle 4.4 Beziehung von Encoding und Textformat

Encoding textformat = bytes textformat = utf8, utf16, utf16be oder utf16le
8 Bit oder builtin-En- 8-Bit-Codes konvertiert Unicode-Werte in 8-Bit-Codes gemäß
coding für TTF/OTF des gewählten Encoding1
builtin-Encoding für 8-Bit-Codes nur in Unicode-fähigen Sprachen; PDFlib löst
PostScript andernfalls eine Exception aus
U+XXXX zur Unicode-Adressierung werden konvertiert Unicode-Werte in 8-Bit-Codes gemäß
8-Bit-Codes auf den Startwert XXXX des gewählten Unicode-Startwertes
addiert
glyphid 8-Bit-Codes adressieren Glyph-IDs Unicode-Werte werden als Glyph-IDs2 interpretiert
zwischen 0 und 255
unicode und UCS2- 8-Bit-Codes adressieren Unicode- beliebiger Unicode-Wert, gemäß des gewählten
bzw. UTF-16-CMaps Werte von U+0000 bis U+00FF Textformats1 kodiert
bel. andere (nicht beliebige Ein-Byte- oder Multibyte- nur in Unicode-fähigen Sprachen; PDFlib löst
unicode) CMap Codes gemäß der gewählten CMap andernfalls eine Exception aus
1. Ist das Unicode-Zeichen in der Schrift nicht verfügbar, wird es von PDFlib durch ein space-Zeichen ersetzt und eine Warnung aus-
gegeben (steuerbar über den Parameter glyphwarning).
2. Ist die Glyph-ID in der Schrift nicht verfügbar, wird sie durch die Glyph-ID 0 ersetzt und eine Warnung ausgegeben.
Hypertext-Zeichensatz. Der Parameter hypertextencoding entspricht dem encoding-Pa-

rameter für PDF_load_font( ). Er bestimmt die 8-Bit-Kodierung von Hypertextstrings
und enthält den Namen eines beliebigen, PDFlib bekannten 8-Bit-Zeichensatzes ein-
schließlich auto (siehe Abschnitt 4.4, »Zeichensätze«, Seite 98). Beachten Sie aber, dass
glyphid, builtin sowie CMap-Namen nicht erlaubt sind. Standardwert für den Parameter
hypertextencoding ist auto.
Hypertext-Format. Ähnlich dem Parameter textformat kann das Format von Hyper-
text-Strings mit dem Parameter hypertextformat bestimmt werden. Die Interpretation
der zulässigen Werte weicht jedoch etwas vom Parameter textformat ab. Die Kodierun-
gen utf8, utf16, utf16be und utf16le haben bei beiden Parametern dieselbe Bedeutung,
bytes und auto werden beim Parameter hypertextformat jedoch anders interpretiert:
> auto: UTF-16-Strings mit Big-Endian-BOM werden erkannt (in C müssen sie mit Dop-
pelnull abschließen) und Unicode-Ausgabe wird generiert. Beginnt der String nicht
mit einem Big-Endian-BOM, wird er als String mit 8-Bit-Kodierung gemäß dem Para-
meter hypertextencoding interpretiert (siehe oben). Falls er Zeichen enthält, die nicht

in PDFDocEncoding enthalten sind, wird er vollständig in einen String mit UTF-16-
Kodierung und Big-Endian-Bytereihenfolge konvertiert und als Unicode in die PDF-
Ausgabe geschrieben. Andernfalls wird er als 8-Bit-kodierter PDFDocEncoding-Text
ausgegeben.
> bytes: ein Byte im String entspricht einem Zeichen, und der String wird uninterpre-
tiert ausgegeben. Dies ist hauptsächlich bei 8-Bit-Zeichensätzen sinnvoll. UTF-16-
Strings mit Big-Endian-BOM werden erkannt. In C müssen diese Strings mit Doppel-
null abschließen, sofern die Länge in Bytes nicht explizit im entsprechenden Funkti-
onsaufruf übergeben wird.
Der Standardwert für den Parameter hypertextformat ist auto.
4.5.5 Character-Referenzen
In manchen Umgebungen dürfen Programmierer Sourcecode nur mit 8-Bit-Zeichensät-
zen (wie winansi, macroman oder ebcdic) schreiben. Es ist entsprechend mühsam, einzel-
ne Unicode-Zeichen in 8-Bit-Text aufzunehmen, ohne gleich alle Zeichen in Multibyte-
Kodierung umzusetzen. Um Entwicklern in dieser Situation unter die Arme zu greifen,
unterstützt PDFlib so genannte Character-Referenzen, ein Verfahren, das in Auszeich-
nungssprachen wie SGML und HTML gebräuchlich ist.
Character-Referenzen wie in HTML. PDFlib unterstützt alle numerischen Character-

und Entity-Referenzen, die in HTML 4.01 definiert sind. Bei numerischen Character-Re-
ferenzen kann der Unicode-Wert des Zeichens in Dezimal- oder Hexadezimalschreib-
weise angegeben sein.
Hinweis Die Codes 128-159 (dezimal) bzw. 0x80-0x9F (hexadezimal) beziehen sich nicht auf Winansi-
Zeichen. Der Unicode-Standard enthält an diesen Positionen keine druckbaren Zeichen, son-
dern nur Steuerzeichen.
Die folgenden Beispiele zeigen gültige Character-Referenzen und die zugehörigen Zei-
chen:
weiches Trennzeichen (soft hyphen)
å Buchstabe a mit kleinem Kreis darüber (dezimal)
å Buchstabe a mit kleinem Kreis darüber (hexadezimal, kleines x)
&#Xe5; Buchstabe a mit kleinem Kreis darüber (hexadezimal, großes X)
€ Eurozeichen (hexadezimal)
€ Eurozeichen (dezimal)
€ Eurozeichen (Entity-Name)
< ’kleiner’-Zeichen
> ’größer’-Zeichen
& kaufmännisches ’und’-Zeichen (ampersand)
Α Alpha-Zeichen
Character-Referenzen können in allen Content-, Hypertext- und Name-Strings verwen-

det werden, zum Beispiel in Text, der mit den Funktionen show oder textflow auf der Sei-
te platziert wird, oder in Text, der an Hypertext-Funktionen übergeben wird. In Opti-
onslisten werden Character-Referenzen jedoch nicht ersetzt.
1. Siehe www.w3.org/TR/REC-html40/charset.html#h-5.3

Character-Referenzen werden nicht standardmäßig umgewandelt; wenn Sie sie ge-
nerell in Content-Strings verwenden möchten, müssen Sie den Parameter charref expli-
zit auf true setzen:
PDF_set_parameter(p, "charref", "true");
Mit der Option charref (direkt oder als Inline-Option) für PDF_create_textflow( ), PDF_fit_
textline( ) oder PDF_fill_textblock( ) lassen sich Character-Referenzen auch für die Text-
flussverarbeitung aktivieren. Sie können dann numerische oder Entity-Referenzen in 8-
Bit-kodiertem Text übergeben:
PDF_set_parameter(p, "textformat", "bytes");
font = PDF_load_font(p, "Helvetica", 0, "unicode", "");
PDF_show_xy(p, "Price: 500€", 50, 500);
Hinweis Mit Character-Referenzen lassen sich zwar beliebige Unicode-Zeichen (wie griechische Buchsta-
ben oder mathematische Symbole) referenzieren, es findet aber kein automatischer Fontwech-
sel statt. Um diese Zeichen tatsächlich nutzen zu können, müssen Sie explizit einen geeigneten
Font auswählen, sofern der aktuell eingestellte die Zeichen nicht unterstützt.
Weitere Referenzen für Steuerzeichen in Textflüssen. Neben den Referenzen im

HTML-Stil unterstützt PDFlib benutzerdefinierte Entity-Referenzen, mit denen sich
Steuerzeichen für Textflüsse festlegen lassen. Diese werden in Tabelle 4.5 aufgeführt.
Tabelle 4.5 Steuerzeichen und ihre Bedeutung in Textflüssen

Äquivalente
Entity-Name Textfluss- Bedeutung in Textflüssen mit Unicode-
Unicode-Zeichen Option kompatiblen Schriften
U+0020 SP, space space Leerzeichen, wird zum Wortausgleich und Um-
brechen benutzt
U+00A0 NBSP, nbsp (keine) (no-break space) Umbruchgeschütztes Leerzeichen
U+0009 HT, hortab (keine) Horizontaler Tabulator: wird gemäß der Optionen
ruler, tabalignchar und tabalignment ausgewertet
U+002D HY, hyphen (keine) Trennzeichen bei Worttrennung
U+00AD SHY, shy (keine) (soft hyphen) Weiches Trennzeichen (mögliche
Trennstelle), nur sichtbar bei einer Umbruchstelle
U+000B VT, verttab nextline (next line) Erzwingt eine neue Zeile
U+2028 LS, linesep
U+000A LF, linefeed next- (next paragraph) Wie »nextline«; zusätzlich wirkt
U+000D CR, return paragraph die Option parindent auf die nächste Zeile
U+000D und CRLF
U+000A
U+0085 NEL, newline
U+2029 PS, parasep
U+000C FF, formfeed return PDF_fit_textflow( ) stoppt und gibt den String
_nextpage zurück.
Verwendung von Character-Referenzen. Character-Referenzen können in allen Con-

tent-, Hypertext- und Name-Strings vorkommen, z.B. in Text, der auf der Seite mit den
show- oder textflow-Funktionen platziert wird oder in Text, der an Hypertext-Funktio-

nen übergeben wird. Beachten Sie, dass Character-Referenzen in Text mit Zeichensatz
builtin nicht verarbeitet werden.
Character-Referenzen werden nicht standardmäßig konvertiert; um Sie in allen Con-
tent-Strings verwenden zu können, müssen Sie den Parameter charref explizit auf true
setzen:
Um Character-Referenzen in Textflüssen zu verarbeiten, kann die Option charref (direkt

oder als Inline-Option) an PDF_create_textflow( ), PDF_fit_textline( ) oder PDF_fill_
textblock( ) übergeben werden.
Ist die Verarbeitung von Character-Referenzen aktiviert, können Sie numerische
oder Entity-Referenzen in 8-Bit-Text übergeben:
PDF_set_parameter(p, "textformat", "bytes");
font = PDF_load_font(p, "Helvetica", 0, "unicode", "");
PDF_show_xy(p, "Preis: 500€", 50, 500);
Character-Referenzen werden in Optionslisten nicht ersetzt, aber in Optionen mit dem

Datentyp Unichar erkannt (siehe Abschnitt 8.1.2, »Optionslisten«, Seite 218). Diese Er-
kennung erfolgt immer und wird nicht durch den Parameter charref gesteuert.
Tritt das Zeichen »&« im Text auf, ohne eine numerische oder Character-Referenz
einzuleiten, wird eine Exception ausgelöst, sofern glyphwarning=true. Wenn Sie
glyphwarning auf false setzen, können Character-Referenzen sowie einzelne »&«-Zeichen
im selben Text verwendet werden.
4.5.6 Unicode-kompatible Fonts

Der präzise Umgang mit Unicode ist wichtig für die interne Verarbeitung durch PDFlib
und entscheidende Voraussetzung für eine einwandfreie Textextraktion aus dem PDF-
Dokument oder etwa die Umwandlung des Dokumentinhalts in ein anderes Format.
Insbesondere Tagged PDF stellt harte Anforderungen an die Unicode-Kompatibilität
(siehe Abschnitt 7.5.1, »Erzeugung von Tagged PDF mit PDFlib«, Seite 207). Auch bei der
Textflussfunktion spielt die Unicode-Kompatibilität eine Rolle.
Unicode-kompatible Schriften. Ein mit PDF_load_font( ) geladene Schrift – genauer:

eine Kombination aus Schrift und Zeichensatz – wird als zu Unicode kompatibel angese-
hen, wenn der zum Laden der Schrift verwendete Zeichensatz folgende Bedingungen er-
füllt:
> Der Zeichensatz builtin ist nur für die Schriften Symbol und ZapfDingbats und für auf
PostScript basierende OpenType-Schriften erlaubt.
> Der Zeichensatz ist nicht glyphid.
> Ist der Zeichensatz eine der in Tabelle 4.7 vordefinierten CMaps, muss er eine UCS2-
oder UTF16-CMap sein.
Unicode-kompatible Ausgabe. Zur Erzeugung von Tagged PDF und für die zuverlässi-
ge Extraktion von Text aus dem generierten PDF muss die Ausgabe zu Unicode kompa-
tibel sein. Mit PDFlib generierte PDF-Ausgabe ist zu Unicode kompatibel, sofern folgen-
de Bedingungen erfüllt sind:

> Alle im Dokument verwendeten Schriften müssen, wie oben definiert, zu Unicode
kompatibel sein oder eine der in Tabelle 4.7 vordefinierten CMaps verwenden.
> Wurde der Zeichensatz mit PDF_encoding_set_char( ) sowie Glyphennamen zusam-
mengestellt, die über keine entsprechenden Unicode-Werte verfügen oder aus einer
Encodingdatei geladen wurden, müssen diese in der Adobe Glyph List oder in der Lis-
te der Glyphennamen des Symbolfonts verzeichnet sein.
> Der Parameter oder die Option unicodemap ist gleich true.
> Alle Textstrings haben eine klar definierte Bedeutung gemäß des Unicode-Stan-
dards, das heißt, Zeichen aus der Private Use Area (PUA) sind nicht zulässig.
> Mit PDI importierte PDF-Seiten müssen zu Unicode kompatibel sein, da PDI die Uni-
code-Kompatibilitätsstufe importierter Seiten nicht verändert: Unicode-Informatio-
nen werden weder entfernt noch hinzugefügt.
Bei der Erzeugung von Tagged PDF können Textteile, die diese Regeln verletzen, Uni-
code-kompatibel gemacht werden, indem mit der Option ActualText in PDF_begin_item( )
korrekter Unicode-Text übergeben wird.

4.6 Textmetrik und Textvarianten
4.6.1 Font- und Zeichenmetriken
Textposition. PDFlib verwaltet eine aktuelle Textposition, die unabhängig von der ak-
tuellen Position beim Zeichnen von Grafik ist. Die aktuelle Textposition kann über die
Parameter textx/texty und der aktuelle Punkt über currentx/currenty abgefragt werden.
Zeichenmetrik. PDFlib verwendet dasselbe System für Zeichen- und Fontmetrik wie
PostScript und PDF. Es soll hier kurz beschrieben werden.
Die Schriftgröße, die von PDFlib-Anwendern angegeben werden muss, ist der Ab-
stand zwischen zwei aufeinander folgenden Textzeilen, der minimal erforderlich ist, da-
mit Zeichen nicht überlappen. Die Schriftgröße ist gewöhnlich höher als die einzelnen
Zeichen der Schrift, da sie auch Ober- und Unterlängen und möglicherweise einen Zwi-
schenraum zwischen den Zeilen umfasst.
Der Zeilenabstand (leading) bezeichnet den vertikalen Abstand zwischen den Grund-
linien benachbarter Textzeilen. Er wird standardmäßig auf den Wert der Schriftgröße
gesetzt. Die Versalhöhe (capheight) bezeichnet die Höhe von Großbuchstaben wie T oder
H in den meisten lateinischen Schriften. Die x-Höhe (xheight) bezeichnet die Höhe von
Kleinbuchstaben wie x in den meisten lateinischen Schriften. Die Oberlänge (ascender)
bezeichnet die Höhe von Kleinbuchstaben wie f oder d in den meisten lateinischen
Schriften. Die Unterlänge (descender) ist der Abstand von der Grundlinie zum unteren
Ende von Kleinbuchstaben wie j oder p in den meisten lateinischen Schriften. Sie ist in
der Regel negativ. Die Werte für x-Höhe, Versalhöhe, Oberlänge und Unterlänge werden
als Bruchteil der Schriftgröße gemessen und müssen deshalb vor der Verwendung mit
der nötigen Schriftgröße multipliziert werden.
PDFlib muss einen oder mehrere der Werte auch schätzen können, da sie in der Font-
oder Metrikdatei nicht zwangsläufig vorhanden sind. Um herauszufinden, ob tatsächli-
che oder geschätzte Werte verwendet werden, können Sie die Parameter xheightfaked
etc. abfragen. Die Zeichenmetriken für eine bestimmte Schrift können von PDFlib wie
folgt abgefragt werden:
float capheight, ascender, descender, fontsize;
...
font = PDF_load_font(p, "Times-Roman", 0, "winansi", "");
PDF_setfont(p, font, fontsize);
capheight = PDF_get_value(p, "capheight", font) * fontsize;
Abb. 4.2 Font- und Zeichenmetrik
Oberlänge
Versalhöhe (ascender)
(capheight)
Schriftgröße
Grundlinie
Unterlänge (descender)

ascender = PDF_get_value(p, "ascender", font) * fontsize;
descender = PDF_get_value(p, "descender", font) * fontsize;
Hinweis Position und Größe von hochgestellten und tiefgestellten Zeichen können von PDFlib nicht ab-
gefragt werden.
CPI-Berechnungen. Die meisten Schriften besitzen variable Zeichenbreiten, nur bei

den so genannten äquidistanten Schriften ist die Laufweite aller Zeichen gleich. Um die
PDF-Fontmetrik auf die Bemaßung Zeichen pro Zoll (characters per inch, CPI) abzubilden,
die häufig beim Hochleistungsdruck verwendet wird, mögen einige Rechenbeispiele für
die äquidistante Schrift Courier hilfreich sein. In Courier haben alle Zeichen eine Breite
von 600 Einheiten, bezogen auf den vollen Zeichenbereich von 1000 Einheiten pro
Punkt (dieser Wert lässt sich aus der entsprechenden AFM-Metrikdatei ermitteln). Bei
Text der Größe 12 Punkt haben zum Beispiel alle Zeichen eine absolute Breite von
12 Punkt * 600/1000 = 7,2 Punkt
bei einem optimalen Zeilenabstand von 12 Punkt. Da ein Zoll (inch) aus 72 Punkt be-
steht, passen genau 10 Zeichen von 12 Punkt Courier in einen Zoll. Mit anderen Worten
stellt 12 Punkt Courier eine 10-cpi-Schrift dar. Für 10 Punkt Text beträgt die Zeichenbrei-
te 6 Punkt, was eine 72/6 = 12 cpi Schrift ergibt; 8 Punkt Courier ergibt 15 cpi.
4.6.2 Kerning
Manche Zeichenkombinationen sehen unter Umständen nicht sehr gut aus. Beispiels-
weise sieht zweimal V hintereinander manchmal wie ein W aus. Ebenso muss der Ab-
stand zwischen T und e oft verringert werden, damit kein hässlicher Leerraum entsteht.
Dieses Ausgleichen wird als Unterschneidung oder Kerning bezeichnet. Viele Schriften
enthalten umfangreiche Kerning-Tabellen, die Abstandsausgleichswerte für zahlreiche
Buchstabenkombinationen enthalten. In PDFlib gibt es zwei Möglichkeiten zur Steue-
rung von Kerning:
Abb. 4.3 Kerning
Kein Kerning
Kerning
Zeichenversatz beim Kerning

> Beim Laden eines Fonts werden die Kerningdaten standardmäßig nicht ausgewertet.
Ist Kerning erwünscht, dann muss PDF_load_font( ) mit der Option kerning aufgeru-
fen werden. Damit wird PDFlib angewiesen, die Kerningdaten der Schrift einzulesen,
sofern diese vorhanden sind.
> Wird eine Schrift, für die Kerningdaten eingelesen wurden, mit einer Textausgabe-
funktion verwendet, werden die kerning-spezifischen Abstandsausgleichsdaten an-
gewandt. Das Kerning lässt sich aber auch deaktivieren, indem der Parameter kerning
auf false gesetzt wird:
PDF_set_parameter(p, "kerning", "false"); /* Kerning deaktivieren */
Eine temporäre Deaktivierung von Kerning kann zum Beispiel bei Zahlen in Tabel-
len sinnvoll sein, falls die Kerningdaten bestimmte Ziffernpaare enthalten, so dass
keine einheitliche Anordnung der Zahlen möglich ist.
Kerning erfolgt zusätzlich zu Zeichenabstand, Wortabstand und eventuell aktivierter
horizontaler Skalierung. In PDFlib gibt es keine Beschränkung für die Anzahl der Ker-
ning-Paare in einer Schrift.
4.6.3 Textvarianten
Künstliche Schriftstile. Fette und kursive Varianten einer Schrift sollten durch Aus-
wahl des passenden Fonts verwendet werden. PDFlib unterstützt aber auch künstliche
Schriftstile: auf Basis eines vorhandenen Schriftschnitts simuliert Acrobat fette, kursive
oder fett-kursive Zeichen durch künstliches Verbreitern oder Neigen. In ästhetischer
Hinsicht sind solche künstlichen Schriftstile qualitativ schlechter als echte kursive oder
fette Schriftschnitte, die vom Schriftdesigner sorgfältig gestaltet wurden. In Situatio-
nen aber, in denen ein bestimmter Schriftstil nicht direkt verfügbar ist, können künstli-
che Stile Abhilfe schaffen. Nützlich sind sie insbesondere bei Standard-CJK-Fonts, die
nur den Basisfont, aber keine fetten oder kursiven Varianten unterstützen.
Hinweis Künstliche Schriftstile sollten nur bei Standard-CJK-Schriften zum Einsatz kommen. Beachten
Sie zudem, dass künstliche Schriftstile von anderen PDF-Viewern als Adobe Acrobat unter Um-
ständen nicht angezeigt werden können.
Aufgrund verschiedener Einschränkungen in Adobe Acrobat können künstliche Schrift-

stile nur genutzt werden, wenn folgende Voraussetzungen erfüllt sind:
> Der Basisfont ist ein TrueType- oder OpenType-Font inklusive Standard- und benut-
zerspezifischer CJK-Fonts. Der Basisfont darf keine der PDF-Standardschriften sein
(siehe Abschnitt 4.3.2, »Schrifteinbettung«, Seite 94). Schriftstile können nicht auf
TrueType Collections (TTC) angewendet werden.
> Das Encoding ist winansi, macroman oder eine der vordefinierten CJK-CMaps, die in
Tabelle 4.7 aufgeführt werden (da PDFlib sonst die Schrifteinbettung erzwingt).
> Die Option embedding muss auf false gesetzt sein.
> Der Basisfont muss auf dem Zielsystem installiert sein, auf dem das PDF-Dokument
betrachtet wird.
PDFlib überprüft die ersten drei Punkte, die Erfüllung der letzten Bedingung ist jedoch
vom Benutzer sicherzustellen. Künstliche Schriftstile für fette, kursive und fett-kursive
Zeichen können mit den Schlüsselwörtern bold, italic und bolditalic der Option fontstyle
für PDF_load_font( ) angefordert werden:
PDF_load_font(p, "HeiseiKakuGo-W5", 0, "UniJIS-UCS2-H", "fontstyle bold");

Die fontstyle-Funktion ist nicht zu verwechseln mit dem ähnlichen Konzept der Schrift-
stilnamen in Windows. Während die fontstyle-Funktion nur unter den obigen Bedin-
gungen funktioniert und sich auf Acrobat zur Simulation künstlicher Schriftstile stützt,
basieren Windows-Stilnamen gänzlich auf dem Windows-Schriftselektionsmechanis-
mus und lassen sich nicht zur Simulation nicht-existenter Stile heranziehen.
Simulation kursiver Schriften. Wenn nur die reguläre Schrift verfügbar ist, lässt sich
alternativ eine kursive Schrift auch mit dem Parameter oder der Option italicangle statt
der fontstyle-Funktion simulieren. Dabei wird eine unechte kursive Schrift erzeugt, in-
dem die reguläre Schrift anhand eines vom Benutzer übergebenen Winkels geneigt
wird, wobei negative Werte den Text nach rechts neigen. Die Einschränkungen der
fontstyle-Funktion spielen hier keine Rolle. Es sei jedoch darauf hingewiesen, dass eine
echte kursive Schrift eine wesentlich gefälligere Ausgabe ergibt. Ist sie jedoch nicht vor-
handen, kann sie mit dem Parameter italicangle mühelos simuliert werden. Besonders
nützlich ist dies bei CJK-Fonts. Übliche Werte für den Parameter italicangle liegen zwi-
schen -12 und -15 Grad:
PDF_set_value(p, "italicangle", -12); /* unechte kursive Schrfit erzeugen */
Unterstreichen, Überstreichen und Durchstreichen von Text. PDFlib kann Linien unter,
über oder auf Text zeichnen. Die Breite des Strichs und sein Abstand zur Grundlinie
werden der Metrikdatei des Fonts entnommen. Außerdem fließen in die Berechnung
der Strichstärke die aktuellen Werte des horizontalen Skalierungsfaktors sowie der
Textmatrix ein. Mit PDF_set_parameter( ) lässt sich das Unter-, Über- oder Durchstrei-
chen wie folgt ein- und ausschalten:
PDF_set_parameter(p, "underline", "true"); /* Unterstreichen aktivieren */
Die Striche erhalten die aktuelle Zeichenfarbe; die aktuellen Parameter für Linienenden
und Strichmuster werden ignoriert. Warnung für Ästheten: In den meisten Schriften
werden beim Unterstreichen Unterlängen berührt und beim Überstreichen diakritische
Zeichen über den Oberlängen.
Hinweis Unter-, Über- und Durchstreichen wird für Standard-CJK-Fonts nur unterstützt, wenn eine Uni-
code-CMap verwendet wird.
Modi der Textdarstellung. PDFlib unterstützt mehrere Darstellungsmodi, die das Er-
scheinungsbild von Text beeinflussen. Dazu gehört Text, der durch Umrisslinien darge-
stellt wird, sowie die Möglichkeit, Text als Clipping-Pfad zu verwenden. Text lässt sich
auch unsichtbar darstellen. Dies kann zum Beispiel sinnvoll sein, um Text auf einge-
scannten Bildern zu platzieren, so dass er zwar indiziert und durchsucht werden kann,
aber nicht direkt sichtbar ist. Die Darstellungsmodi werden in Tabelle 8.18 beschrieben.
Sie können mit PDF_set_value( ) und dem Parameter textrendering gesetzt werden.
PDF_set_value(p, "textrendering", 1); /* Umrisslinien zeichnen */
Beim Zeichnen von Umrisslinien werden Grafikzustandsparameter wie linewidth oder

color auf die Glyphe angewandt. Der Darstellungsmodus hat keine Auswirkungen auf
Text in einem Type-3-Font.
Hinweis Darstellungsmodus 7 (verwende Text als Clipping-Pfad) hat keinen Effekt, wenn die Textausga-
be mit PDF_fit_textline( ) oder PDF_fit_textflow( ) erfolgt.

Textfarbe. Text wird gewöhnlich mit der aktuellen Füllfarbe dargestellt, die mit PDF_
setcolor( ) gesetzt werden kann. Bei einem von 0 verschiedenen Darstellungsmodus wer-
den je nach Modus die Linien- und die Füllfarbe verwendet.

4.7 Chinesischer, japanischer und koreanischer Text
4.7.1 CJK-Unterstützung in Acrobat und PDF
Acrobat/PDF unterstützen einen Satz von Standard-CJK-Fonts ohne Schrifteinbettung
sowie benutzerspezifische eingebettete CJK-Fonts. Eingebettete CJK-Fonts können in al-
len Acrobat-Versionen ohne weitere Vorkehrungen verwendet werden. Beim Einsatz
von Standard-CJK-Fonts in Acrobat ist einer der folgenden Schritte erforderlich1:
> Verwenden Sie eine lokalisierte CJK-Version von Acrobat.
> Wenn Sie eine Nicht-CJK-Version des Acrobat-Vollprodukts verwenden, wählen Sie
in der benutzerdefinierten Acrobat-Installation die Option »Unterstützung für asia-
tische Sprachen« (Windows) oder »Language Kit« (Mac). Die erforderlichen Hilfsda-
teien (Schriften und CMaps) werden dann von der Acrobat-CD installiert.
> Beim Acrobat Reader installieren Sie eines der asiatischen Fontpakete, die im Web
verfügbar sind.2
Drucken von PDF-Dokumenten mit CJK-Text. Das Drucken von CJK-Dokumenten wirft
eine Reihe von Fragen auf, deren Beantwortung über den Rahmen dieses Handbuchs hi-
naus ginge. Wir möchten jedoch einige Hinweise geben, die dem PDFlib-Benutzer nütz-
lich sein können. Wenn Sie beim Drucken von CJK-Dokumenten mit Acrobat Probleme
haben (insbesondere bei Dokumenten mit Standard-CJK-Fonts), sollten Sie folgende Ur-
sachen in Betracht ziehen:
> Aufgrund der immensen Anzahl von Zeichen benötigen CJK-Fonts enormen Dru-
ckerspeicher, wenn keine Schriftuntergruppen gebildet wurden. Nicht alle Drucker
verfügen jedoch über ausreichend Speicher zur Ausgabe solcher Schriften.
> Nicht-japanische PostScript-Drucker haben keine japanischen Schriften installiert.
Aus diesem Grund müssen Sie im Druckdialog von Acrobat die Option Asiatische
Schriften herunterladen aktivieren.
> Wenn der Ausdruck auch mit heruntergeladenen Schriften nicht funktioniert, akti-
vieren Sie die Option Als Bild drucken. Acrobat sendet dann eine Rasterbildversion der
Seite an den Drucker (allerdings mit 300 dpi).
4.7.2 Standard-CJK-Fonts und -CMaps

Von diversen Standardisierungsgremien, Firmen und anderen Organisationen wurde
über die Jahre hinweg ein breites Spektrum an CJK-Zeichensätzen entwickelt. Zum
Glück werden alle der vorherrschenden Zeichensätze standardmäßig auch von Acrobat
und PDF unterstützt. Da ein Zeichensatz für CJK-Text wesentlich komplizierter ist als
für lateinischen Text, reicht ein einfacher Zeichensatz mit 256 Einträgen nicht aus.
Stattdessen arbeiten PostScript und PDF mit dem Konzept der character collections und
character maps (CMaps) zur Anordnung der Zeichen in einer Schrift.
Acrobat unterstützt einen Satz von Standardschriften für CJK-Text. Diese Schriften
werden mit der Acrobat-Installation ausgeliefert (oder mit den asiatischen Fontpake-
ten) und müssen somit nicht in der PDF-Datei eingebettet sein (genauso wie die 14 Stan-
1. Bei dieser Gelegenheit soll das grundlegende Werk »CJKV information processing – Chinese, Japanese, Korean & Vietna-
mese Computing« (O’Reilly 1999, ISBN 1-56592-224-7) von Ken Lunde hervorgehoben werden sowie seine Arbeit bei Adobe,
wo er eine der treibenden Kräfte hinter der CJK-Unterstützung in PostScript und PDF ist.
2. Siehe www.adobe.com/products/acrobat/acrrasianfontpack.html

dardschriften für lateinischen Text). Diese Schriften enthalten alle Zeichen, die in den
gängigen Zeichensätzen vorkommen, und unterstützen sowohl horizontalen als auch
vertikalen Text. Tabelle 4.6 zeigt die Standardschriften und CMaps. Die Acrobat-4-Fonts
können auch mit Acrobat 5 verwendet werden, für Anzeige und Ausdruck werden je-
doch die entsprechenden Acrobat-5-Fonts benutzt, falls eine benötigte Schrift nicht auf
dem System installiert ist.
Hinweis Die Standard-CJK-Fonts umfassen keine kursiven oder fetten Fonts. Solche Fonts lassen sich mit
künstlichen Schriftstilen simulieren (siehe Abschnitt 4.6.3, »Textvarianten«, Seite 117).
Tabelle 4.6 Acrobats Standardschriften und CMaps (Zeichensätze) für Japanisch/Chinesisch/Koreanisch

Sprache Schriftname Beispiel Unterstützte CMaps (Zeichensätze)
Verein- STSong-Light1 GB-EUC-H, GB-EUC-V, GBpc-EUC-H, GBpc-EUC-V,
fachtes GBK-EUC-H, GBK-EUC-V, GBKp-EUC-H4 , GBKp-EUC-
Chinesisch STSongStd-Light-Acro2 V2, GBK2K-H2, GBK2K-V2, UniGB-UCS2-H, UniGB-
AdobeSongStd-Light-Acro3 UCS2-V, UniGB-UTF16-H5, UniGB-UTF16-V5
Traditio- MHei-Medium1 B5pc-H, B5pc-V, HKscs-B5-H4 , HKscs-B5-V4 , ETen-B5-
nelles H, ETen-B5-V, ETenms-B5-H, ETenms-B5-V, CNS-EUC-
Chinesisch MSung-Light1 H, CNS-EUC-V, UniCNS-UCS2-H, UniCNS-UCS2-V,
UniCNS-UTF16-H5, UniCNS-UTF16-V5
MSungStd-Light-Acro2
AdobeSungStd-Light-Acro3
Japanisch HeiseiKakuGo-W51 83pv-RKSJ-H, 90ms-RKSJ-H, 90ms-RKSJ-V, 90msp-
RKSJ-H, 90msp-RKSJ-V, 90pv-RKSJ-H, Add-RKSJ-H,
HeiseiMin-W31 Add-RKSJ-V, EUC-H, EUC-V, Ext-RKSJ-H, Ext-RKSJ-V,
H, V, UniJIS-UCS2-H, UniJIS-UCS2-V, UniJIS-UCS2-
KozMinPro-Regular-Acro2, 6 HW-H6, UniJIS-UCS2-HW-V 6, UniJIS-UTF16-H5,
KozGoPro-Medium-Acro3, 6 UniJIS-UTF16-V5
Koreanisch HYGoThic-Medium1 KSC-EUC-H, KSC-EUC-V, KSCms-UHC-H, KSCms-
UHC-V, KSCms-UHC-HW-H, KSCms-UHC-HW-V,
HYSMyeongJo-Medium1 KSCpc-EUC-H, UniKS-UCS2-H, UniKS-UCS2-V, UniKS-
UTF16-H5, UniKS-UTF16-V5
HYSMyeongJoStd-Medium-
Acro2
AdobeMyungjoStd-
Medium-Acro3
1. In Acrobat 4 verfügbar; in Acrobat 5 und 6 werden sie durch andere Schriften ersetzt.
2. Nur in Acrobat 5 verfügbar.
3. Nur in Acrobat 6 verfügbar.
4. Nur bei der Generierung von PDF ab Version 1.4 verfügbar.
5. Nur bei der Generierung von PDF ab Version 1.5 verfügbar.
6. Die HW-CMaps dürfen nicht mit den Schriften KozMinPro-Regular-Acro und KozGoPro-Medium-Acro verwendet werden, da diese
nur proportionale ASCII-Zeichen, aber keine Zeichen halber Breite enthalten.
Wie aus Tabelle 4.6 hervorgeht, unterstützen die standardmäßig vorhandenen CMaps
die meisten CJK-Zeichensätze, die auf Mac-, Windows- und Unix-Systemen verwendet
werden, sowie einige andere herstellerspezifische Zeichensätze. Dabei werden inbeson-
dere die wichtigen japanischen Zeichensätze Shift-JIS, EUC, ISO 2022 und Unicode
(UCS-2 und UTF-16) unterstützt. Tabellen mit allen unterstützten Zeichen sind bei Ado-
be1 erhältlich; CMap-Beschreibungen finden Sie in Tabelle 4.7.
1. Unter http://partners.adobe.com/asn/developer/typeforum/cidfonts.html finden Sie eine Fülle von Informationen zu

CID-Fonts inklusive Tabellen mit allen unterstützten Glyphen (suchen Sie nach »character collection«).

Hinweis Unicode-fähige Sprachbindungen dürfen nur Unicode-kompatible CMaps verwenden (UCS-2
oder UTF-16). Andere CMaps werden nicht unterstützt.
Horizontale und vertikale Schreibrichtung. PDFlib unterstützt sowohl horizontale als

auch vertikale Schreibrichtung für Standard-CJK-Fonts und CMaps. Der entsprechende
Modus wird über einen geeigneten CMap-Namen ausgewählt. Diese zeigen durch die
Endung -H bzw. -V an, dass sie horizontale bzw. vertikale Schreibrichtung bewirken.
Tabelle 4.7 Vordefinierte CMaps für japanisch/chinesisch/koreanisch (aus der »PDF Reference«)
Sprache CMap-Name Zeichensatz und Textformat
Vereinfachtes UniGB-UCS2-H Unicode-Encoding (UCS-2) für die Character Collection Adobe GB1
Chinesisch UniGB-UCS2-V
UniGB-UTF16-H Unicode-Encoding (UTF-16BE) für die Character Collection Adobe GB1.
UniGB-UTF16-V Enthält Zuordnungen für alle Zeichen des GB-18030-2000-Zeichensatzes.
GB-EUC-H Microsoft Codepage 936 (Charset 134), GB 2312-80-Zeichensatz, EUC-CN-
GB-EUC-V Encoding
GBpc-EUC-H Macintosh, GB-2312-80-Zeichensatz, EUC-CN-Encoding, Script Manager
GBpc-EUC-V Code 2
GBK-EUC-H, -V Microsoft Codepage 936 (Charset 134), GBK-Zeichensatz, GBK-Encoding
GBKp-EUC-H Wie GBK.EUC-H, ersetzt aber lateinische Zeichen halber Breite durch
GBKp-EUC-V proportionale Zeichen und ordnet dem Zeichencode 0x24 das
Dollarzeichen ($) statt des Yuan-Symbols (¥) zu.
GBK2K-H, -V GB-18030-2000-Zeichensatz, gemischtes 1-, 2- und 4-Byte-Encoding
Traditionelles UniCNS-UCS2-H Unicode-Encoding (UCS-2) für die Character Collection Adobe CNS1
Chinesisch UniCNS-UCS2-V
UniCNS-UTF16-H Unicode-Encoding (UTF-16BE) für die Character Collection Adobe CNS1.
UniCNS-UTF16-V Enthält Zuordnungen für alle HKSCS-2001 (2- und 4-Byte-Zeichencodes)
B5pc-H, -V Macintosh, Big-Five-Zeichensatz, Big-Five-Encoding, Script Manager Code 2
HKscs-B5-H Hong Kong SCS (Supplementary Character Set), eine Erweiterung von Big-
HKscs-B5-V Five-Zeichensatz und -Encoding
ETen-B5-H, -V Microsoft Codepage 950 (Charset 136), Big-Five mit ETen-Erweiterungen
ETenms-B5-H Wie ETen-B5-H, ersetzt aber lateinische Zeichen halber Breite durch
ETenms-B5-V proportionale Zeichen
CNS-EUC-H, -V CNS-11643-1992-Zeichensatz, EUC-TW-Encoding
Japanisch UniJIS-UCS2-H Unicode-Encoding (UCS-2) für die Character Collection Adobe Japan1
UniJIS-UCS2-V
UniJIS-UCS2-HW-H Wie UniJIS-UCS2-H, ersetzt aber proportionale lateinische Zeichen durch
UniJIS-UCS2-HW-V Zeichen halber Breite
UniJIS-UTF16-H Unicode-Encoding (UTF-16BE) für die Character Collection Adobe Japan1.
UniJIS-UTF16-V Enthält Zuordnungen für alle Zeichen im JIS-X-0213:1000-Zeichensatz.
83pv-RKSJ-H Mac, JIS-X-0208 mit KanjiTalk6-Erweiterungen, Shift-JIS, Script Manager Code 1
90ms-RKSJ-H Microsoft Codepage 932 (Charset 128), JIS-X-0208-Zeichensatz mit NEC-
90ms-RKSJ-V und IBM-Erweiterungen
90msp-RKSJ-H Wie 90ms-RKSJ-H, ersetzt aber lateinische Zeichen halber Breite durch
90msp-RKSJ-V proportionale Zeichen
90pv-RKSJ-H Mac, JIS-X-0208 mit KanjiTalk7-Erweiterungen, Shift-JIS, Script Manager Code 1
Add-RKSJ-H, -V JIS-X-0208-Zeichensatz mit Fujitsu FMR-Erweiterungen, Shift-JIS-Encoding
EUC-H, -V JIS-X-0208-Zeichensatz, EUC-JP-Encoding
Ext-RKSJ-H, -V JIS-C-6226-Zeichensatz (JIS78) mit NEC-Erweiterungen, Shift-JIS-Encoding

Tabelle 4.7 Vordefinierte CMaps für japanisch/chinesisch/koreanisch (aus der »PDF Reference«)
Sprache CMap-Name Zeichensatz und Textformat
H, V JIS-X-0208-Zeichensatz, ISO-2022-JP-Encoding
Koreanisch UniKS-UCS2-H, -V Unicode-Encoding (UCS-2) für die Character Collection Adobe Korea1
UniKS-UTF16-H, -V Unicode-Encoding (UTF-16BE) für die Character Collection Adobe Korea1
KSC-EUC-H, -V KS-X-1001:1992-Zeichensatz, EUC-KR-Encoding
KSCms-UHC-H Microsoft Codepage 949 (Charset 129), KS-X-1001:1992-Zeichensatz plus
KSCms-UHC-V 8822 zusätzliche Hangul-Zeichen, Unified-Hangul-Code-Encoding (UHC)
KSCms-UHC-HW-H Wie KSCms-UHC-H, ersetzt aber proportionale lateinische Zeichen durch
KSCms-UHC-HW-V Zeichen halber Breite
KSCpc-EUC-H Mac, KS-X-1001:1992 mit Mac-OS-KH-Erweiterungen, Script Manager Code 3
Hinweis Manche PDFlib-Funktionen ändern ihre Bedeutung mit der Schreibrichtung. Beispielsweise soll-
te PDF_continue_text( ) nicht bei vertikaler Schreibrichtung verwendet werden. Außerdem
muss der Zeichenabstand negativ sein, um die Zeichen bei vertikaler Schreibrichtung weiter
voneinander zu trennen. Einzelheiten hierzu finden Sie bei den jeweiligen Funktionsbeschrei-
bungen.
CJK-Textkodierung für Standard-CMaps. Text muss vom Client so übergeben werden,

dass die Zeichencodes der gewählten CMap entsprechen. PDFlib überprüft nicht, ob der
übergebene Text der geforderten CMap entspricht.
Bei Multibyte-Zeichensätzen muss das höchstwertige Byte am Anfang stehen. Die Byte-
reihenfolge und das Textformat können auch mit dem Parameter textformat festgelegt
werden (siehe Abschnitt 4.5.1, »Unicode für Seitenbeschreibungen und Hypertext«, Seite
105), falls eine Unicode-CMap (UCS-2 oder UTF-16) verwendet wird.
Da sich bei manchen der unterstützten Zeichensätze Nullzeichen in Textstrings er-
geben können, dürfen C-Entwickler in solchen Fällen nicht die Funktionen PDF_show( )
etc. verwenden, sondern müssen stattdessen die Funktionen PDF_show2( ) etc. einset-
zen, die für beliebige Binärstrings mit einem zusätzlichen Längen-Parameter vorgese-
hen sind. Bei allen anderen Bindungen unterstützen die Textfunktionen Binärstrings,
so dass PDF_show2( ) etc. nicht benötigt wird.
Einschränkungen bei Standard-CJK-Fonts und CMaps. Folgende Funktionen werden

für Standard-CJK-Fonts mit CMaps, die nicht auf Unicode basieren, nicht unterstützt
(Unicode-CMaps haben UCS2 oder UTF16 im Namen):
> Berechnung der Textlänge mit PDF_stringwidth( ) (siehe aber Abschnitt »Erzwingen
äquidistanter Schrift«, Seite 124)
> Verwendung von PDF_create_textflow( ) und verwandte Textflussfunktionen
> Aktivierung des Unterstreichen/Überstreichen/Durchstreichen-Modus
> Abfrage der textx/texty-Position
Diese Einschränkungen beziehen sich auf Standard-CJK-Fonts. Beachten Sie, dass die
Länge von CJK-Text zwar nicht abgefragt werden kann, in der PDF-Ausgabe aber trotz-
dem korrekt generiert wird. Für benutzerspezifische CJK-Fonts gelten diese Einschrän-
kungen nicht.
Hinweis Die CMaps UniJIS-UCS2-HW-H/V werden fälschlicherweise als äquidistant behandelt. Dieses
Problem wird in zukünftigen Versionen behoben sein.

Beispiel für einen Standard-CJK-Font. Standard-CJK-Fonts können mit der Funktion
PDF_load_font( ) ausgewählt werden, wobei der CMap-Name im Parameter encoding
übergeben wird. Außerdem ist zu berücksichtigen, dass ein CJK-Font nur eine bestimm-
te Menge von CMaps unterstützt (siehe Tabelle 4.6) und Unicode-fähige Sprachbindun-
gen nur UCS2-kompatible CMaps unterstützen. Das Beispiel für KozMinPro-Regular-Acro
in Tabelle 4.6 kann mit folgendem Code generiert werden:
font = PDF_load_font(p, "KozMinPro-Regular-Acro", 0, "UniJIS-UCS2-H", "");
/* Wir verwenden UTF-16-Format mit "Little Endian"-Bytereihenfolge */
PDF_set_parameter(p, "textformat", "utf16le");
PDF_show(p, "\xE5\x65\x2C\x67\x9E\x8A");
In obigem Codefragment wird eine der japanischen Standardschriften mit einer zu

Shift-JIS kompatiblen CMap (Ext-RKSJ) und horizontaler Schreibrichtung (H) gewählt.
Der Parameter fontname muss den genauen Schriftnamen enthalten, wobei kein Suffix
für den Zeichensatz oder die Schreibrichtung enthalten sein darf. Der Parameter
encoding enthält den Namen einer der unterstützten CMaps (die Auswahl ist abhängig
von der jeweiligen Schrift) und zeigt außerdem die Schreibrichtung an (siehe oben).
PDFlib unterstützt alle standardmäßig in Acrobat enthaltenen CMaps und beschwert
sich, wenn Schrift und CMap nicht zusammenpassen. So weigert sich PDFlib zum Bei-
spiel, eine koreanische Schrift mit einem japanischen Zeichensatz zu verwenden.
Erzwingen äquidistanter Schrift. Einige Anwendungen können nicht mit proportiona-

len CJK-Schriften umgehen und berechnen die Textbreite anhand einer konstanten Zei-
chenbreite und der Zeichenanzahl. PDFlib kann angewiesen werden, äquidistante Zei-
chen zu verwenden, selbst wenn es sich um eine Schrift mit unterschiedlich breiten
Zeichen handelt. Mit der Option monospace von PDF_load_font( ) legen Sie die für alle
Zeichen gewünschte Breite fest. Bei Standard-CJK-Schriften liefert der Wert 1000 an-
sprechende Ergebnisse:
font = PDF_load_font(p, "KozMinPro-Regular-Acro", 0, "UniJIS-UCS2-H", "monospace 1000");
Die Option monospace sollte nur bei Standard-CJK-Schriften zum Einsatz kommen.
4.7.3 Benutzerspezifische CJK-Fonts

Zusätzlich zu den Standard-CJK-Fonts von Acrobat unterstützt PDFlib benutzerspezifi-
sche CJK-Fonts (also Schriften, die in Tabelle 4.6 nicht verzeichnet sind) in den Formaten
TrueType (einschließlich TrueType Collections, TTC) und OpenType. Ein benutzerspezi-
fischer CJK-Font wird wie folgt verarbeitet:
> Die Schrift wird in einen CID-Font konvertiert und unabhängig von der vom Client
festgelegten Einstellung in jedem Fall in die PDF-Ausgabe eingebettet. Da PDFlib die
in einer Schrift eventuell vorhandenen Einbettungsbeschränkungen berücksichtigt,
können Schriften, die nicht eingebettet werden dürfen, auch nicht als benutzerspezi-
fischer CJK-Font verwendet werden.
> Standardmäßig werden benutzerspezifische CJK-Fonts als Untergruppen eingebet-
tet, falls sie nicht mit einer Standard-CMap genutzt werden. Dieses Verhalten lässt
sich über verschiedene Parameter steuern, siehe Abschnitt 4.3, »Schrifteinbettung
und Schriftuntergruppen«, Seite 93.

> Proportionale lateinische Zeichen sowie Zeichen halber Breite werden bei benutzer-
spezifischen CJK-Fonts vollständig unterstützt.
> Unter Windows können die Namen japanischer Systemschriften in UTF-8 mit einlei-
tendem BOM oder UCS-2 an PDF_load_font( ) übergeben werden. Auf dem Mac dage-
gen werden nur lateinische Systemschriftnamen unterstützt.
Hinweis Windows-EUDC-Fonts (end-user defined characters) werden unterstützt, einzelne benutzer-

spezifische Zeichen lassen sich aber nicht mit allen Fonts verknüpfen (siehe unten).
Hinweis Vertikale Schreibrichtung wird für benutzerspezifische CJK-Fonts im TrueType-Format nicht un-
terstützt.
Unterstützte Zeichensätze für benutzerspezifische CJK-Fonts. Benutzerspezifische

CJK-Fonts können mit folgenden Zeichensätzen verwendet werden:
> Unter Windows kann jede im System installierte Codepage verwendet werden. Die
Codepage-Nummer muss mit cp beginnen (siehe Beispiele in Tabelle 4.8). Der Para-
meter textformat muss auf auto gesetzt und der Text in einem Format übergeben
werden, der zur gewählten Codepage kompatibel ist.
> OpenType-CJK-Fonts mit PostScript-Outlines (CID-Fonts) können mit allen CMaps
für die jeweilige Locale genutzt werden (Japanische Fonts zum Beispiel nur mit Japa-
nischen CMaps).
> Unicode-Zeichensatz (unicode)
> Adressierung über die Glyph-ID (glyphid), siehe Abschnitt 4.2.3, »TrueType- und
OpenType-Fonts«, Seite 89
Für benutzerspezifische CJK-Fonts wird der Parameter textformat ausgewertet.
Tabelle 4.8 Beispiele für CJK-Codepages in Windows (muss mit textformat=auto verwendet werden)
Sprache Codepage Format Zeichensatz
Einfaches Chinesisch cp936 GBK GBK
Traditionelles cp950 Big Five Big Five mit Microsoft-Erweiterungen
Chinesisch
Japanisch cp932 Shift-JIS JIS X 0208:1997 mit Microsoft-Erweiterungen
Koreanisch cp949 UHC KS X 1001:1992, restliche 8822 Hangul als Erweiterung
cp1361 Johab Johab
Beispiel für einen benutzerspezifischen CJK-Font mit japanischem Shift-JIS-Text. Das

folgende Beispiel verwendet die Schrift MS Mincho zur Anzeige von japanischem Text,
der im Format Shift-JIS gemäß Windows-Codepage 932 übergeben wird:
font = PDF_load_font(p, "MS Mincho", 0, "cp932", "");

PDF_show2(p, "\x82\xA9\x82\xC8\x8A\xBF\x8E\x9A", 8);
Beispiel für einen benutzerspezifischen CJK-Font mit chinesischem Unicode-Text. Das

folgende Beispiel zeigt chinesischen Text in der Schrift ArialUnicodeMS an. Die Schrift
muss entweder auf dem System installiert oder entsprechend Abschnitt 4.3.1, »Wie PDF-
lib nach Fonts sucht«, Seite 93, konfiguriert sein.

/* Nicht erforderlich, wenn die Schrift auf dem System installiert ist */
PDF_set_parameter(p, "FontOutline", "Arial Unicode MS=ARIALUNI.TTF");
font = PDF_load_font(p, "Arial Unicode MS", 0, "unicode", "");

/* Wir verwenden UTF-16-Kodierung mit Bytereihenfolge Big-Endian (BE) */

PDF_set_parameter(p, "textformat", "utf16be");
PDF_show2(p, "\x4e\x00\x50\x0b\x4e\xba", 6);
Zugriff auf einzelne Schriften einer TrueType Collection (TTC). TTC-Dateien enthalten
viele einzelne Schriften. Auf jede Schrift können Sie über den korrekten Namen zugrei-
fen. Wenn Sie jedoch nicht wissen, welche Schriften in einer TTC-Datei enthalten sind,
können Sie diese numerisch adressieren, indem Sie einen Doppelpunkt sowie den Index
der Schrift in der TTC-Datei (beginnend bei 0) anhängen. Die TTC-Datei msgothic.ttc ent-
hält beispielsweise mehrere Schriften, die sich in PDF_load_font( ) wie folgt adressieren
lassen (alle Einträge in einer Zeile können äquivalent benutzt werden):
msgothic:0 MS Gothic msgothic:
msgothic:1 MS PGothic
msgothic:2 MS UI Gothic
Beachten Sie, dass msgothic (ohne Suffix) keinen Schriftnamen darstellt, da er die Schrift
nicht eindeutig bezeichnet. In Kombination mit TTC-Indizierung können Alias-Namen
für Schriften verwendet werden (siehe Abschnitt 4.3.1, »Wie PDFlib nach Fonts sucht«,
Seite 93). Ist eine Schrift mit dem angegebenen Index nicht auffindbar, wird eine Excep-
tion ausgelöst, sofern fontwarning=true.
Die TTC-Schriftdatei muss nur einmal konfiguriert werden; alle in der TTC-Datei in-
dizierten Schriften werden automatisch gefunden. Mit folgendem Code lassen sich alle
in msgothic.ttc indizierten Schriften konfigurieren:
PDF_set_parameter(p, "FontOutline", "msgothic=msgothic.ttc")
Benutzerspezifische Zeichen (EUDC, end-user defined characters). PDFlib unterstützt

keine Verknüpfung von benutzerspezifischen Zeichen mit Fonts, Sie können jedoch den
in Windows verfügbaren EUDC-Editor nutzen, um eigene Zeichen zu erstellen, die in
PDFlib einsetzbar sind. Dazu gehen Sie wie folgt vor:
> Erstellen Sie mit eudcedit.exe ein oder mehrere eigene Zeichen an den gewünschten
Unicodepositionen.
> Finden Sie die Datei EUDC.TTE im Verzeichnis \Windows\fonts und kopieren Sie sie in
ein anderes Verzeichnis. Da diese Datei im Windows Explorer nicht sichtbar ist, müs-
sen Sie die Befehle dir und copy in einem DOS-Fenster verwenden. Dann konfigurie-
ren Sie den Font zum Einsatz mit PDFlib, wobei Sie eines der Verfahren in Abschnitt
4.3.1, »Wie PDFlib nach Fonts sucht«, Seite 93, verwenden
PDF_set_parameter(p, "FontOutline", "EUDC=EUDC.TTE")
PDF_set_parameter(p, "SearchPath", "...Verzeichnisname...")
oder EUDC.TTE ins aktuelle Verzeichnis platzieren.

> Alternativ zum vorherigen Schritt können Sie folgende Funktion aufrufen, um die
Fontdatei direkt aus dem Windows-Verzeichnis heraus zu konfigurieren. Auf diese
Weise greifen Sie immer auf den in Windows aktuell verwendeten EUDC-Font zu:

PDF_set_parameter(p, "FontOutline", "EUDC=C:\Windows\fonts\EUDC.TTE")
> Zum Laden des Fonts verwenden Sie folgenden Aufruf:

font = PDF_load_font(p, "EUDC", 0, "unicode", "")
und übergeben die im ersten Schritt gewählten Unicode-Zeichencodes zur Zeichenaus-

gabe.

4.8 Platzieren und Einpassen von einzeiligem Text
Die Funktion PDF_fit_textline( ) zum Platzieren einer Textzeile auf der Seite bietet eine
Fülle von Optionen. Diese werden im Folgenden anhand einiger häufig vorkommender
Anwendungsbeispiele erläutert. Eine vollständige Auflistung aller Optionen finden Sie
in Tabelle 8.19. Viele der zu PDF_fit_textline( ) gehörenden Optionen sind mit denen für
PDF_fit_image( ) identisch. Wir werden hier nur textbezogene Beispiele anführen. Sie
sollten sich deshalb – vielleicht auch zur Einführung – die Beispiele in Abschnitt 5.3,
»Platzieren von Bildern und importierten PDF-Seiten«, Seite 159, ansehen.
Die folgenden Beispiele zeigen nur den jeweils passenden Aufruf der Funktion PDF_
fit_textline( ). Es wird vorausgesetzt, dass der gewünschte Font bereits geladen und in der
gewünschten Größe gesetzt wurde.
Um die Platzierung des Textes zu berechnen, verwendet PDF_fit_textline( ) die so ge-
nannte Textbox: Die Breite dieser Textbox entspricht der Länge des Schriftzugs und ihre
Höhe der Höhe eines Großbuchstabens des Fonts. Mit der Option margin kann die Text-
box links und rechts oder oben und unten erweitert werden. Dieser Rand wird mit dem
Schriftzug skaliert.
4.8.1 Einfaches Platzieren von Text

Platzieren in der Mitte unten. Wir platzieren Text am Referenzpunkt so, dass die Text-
box in der Mitte ihres unteren Randes auf dem Punkt zu liegen kommt (siehe Abbildung
4.4):
PDF_fit_textline(p, text, 297, 0, "position {50 0}");
Dieses Codefragment platziert die Textbox in der Mitte unten (position {50 0}) auf dem
Referenzpunkt (297, 0).
Platzieren rechts oben. Nun platzieren wir den Text am Referenzpunkt so, dass die
Textbox mit der oberen rechten Ecke auf dem Punkt zu liegen kommt (siehe Abbildung
4.5).
PDF_fit_textline(p, text, 595, 842, "position 100");
Abb. 4.4 Abb. 4.5

Platzierung von Text:
mittig unten Kraxi Platzierung von Text:
rechts oben
Kraxi
Dieses Codefragment platziert die Textbox mit der rechten oberen Ecke (position 100)
auf dem Punkt (595, 842).
Platzieren mit Rand. Wir können das vorige Beispiel erweitern und den Text zusätz-
lich in der Breite mit einem Rand versehen, um einen definierten Abstand nach rechts
zu gewährleisten. Dies kann sinnvoll sein, um Text in Tabellenspalten zu platzieren.
PDF_fit_textline(p, text, 595, 842, "position 100 margin {20 0}");
4.8.2 Platzieren von Text in einer Box

Mittiges Platzieren in einer Box. Wir definieren eine Box und platzieren den Text mit-
tig in der Box (siehe Abbildung 4.6):
PDF_fit_textline(p, text, 10, 200, "boxsize {500 220} position 50");
Dieses Codefragment platziert den Text mittig (position 50) in einer Box, die ihre linke
untere Ecke am Punkt (10, 200) hat und 500 Punkt breit und 220 Punkt hoch ist (boxsize
{500 220}).
Proportionales Einpassen in eine Box. Wir erweitern das vorige Beispiel und passen
den Text zusätzlich in die Box ein (siehe Abbildung 4.7):
PDF_fit_textline(p, text, 10, 200, "boxsize {500 220} position 50 fitmethod meet");
Beachten Sie, dass sich die Schriftgröße ändert, wenn Sie den Text mit fitmethod meet in
die Box einpassen. Um dies zu verhindern, können Sie auto statt meet verwenden.
Vollständiges Einpassen in eine Box. Das vorige Beispiel lässt sich etwas modifizieren,
indem der Text nicht proportional, sondern so in die Box eingepasst wird, dass er diese
vollständig ausfüllt. Da der Text dabei in der Regel seine Proportionen verliert, kommt
dieser Fall eher selten zur Anwendung (siehe Abbildung 4.8):
PDF_fit_textline(p, text, 10, 200, "boxsize {500 220} position 50 fitmethod entire");
Abb. 4.6 Abb. 4.7 Abb. 4.8

Mittiges Platzieren Proportionales Einpassen Vollständiges Einpassen
von Text in einer Box von Text in eine Box von Text in eine Box
Kraxi Kraxi Kraxi

4.8 Platzieren und Einpassen von einzeiligem Text 129
4.8.3 Ausrichten von Text
Einfache Ausrichtung. Text soll so gedreht werden, dass seine ursprünglich linke obere
Ecke auf einen definierten Referenzpunkt zu liegen kommt (siehe Abbildung 4.9). Dies
ist zum Beispiel sinnvoll, um eine gedrehte Spaltenbeschriftung in der Kopfzeile einer
Tabelle zu platzieren:
PDF_fit_textline(p, text, 5, 5, "orientate west");
Dieses Codefragment richtet den Text nach Westen aus (90 Grad gegen den Uhrzeiger-
sinn) und verschiebt dann die linke untere Ecke des gedrehten Texts auf den Referenz-
punkt (5, 5).
Ausrichtung an einer vertikalen Strecke. Ein extremer Fall, der aber durchaus sinnvoll
sein kann, besteht darin, den Text entlang einer Strecke zu positionieren (siehe Abbil-
dung 4.10):
PDF_fit_textline(p, text, 0, 0, "boxsize {0 600} position {0 50} orientate west");
Dieses Codefragment dreht den Text und platziert ihn an die Mitte der Strecke von (0, 0)
bis (0, 600).
Abb. 4.9 Abb. 4.10

Einfaches Ausrichten von Text
Ausrichten von Text an einer vertikalen Strecke
Kraxi
Kraxi

4.9 Mehrzeilige Textflüsse
PDFlib bietet unter der Bezeichnung Textfluss (textflow) die Möglichkeit, nicht nur ein-
zelne Zeilen, sondern einen beliebig langen zusammenhängenden Text auszugeben.
Der Text kann sich über beliebig viele Zeilen oder Seiten erstrecken und anhand vieler
Optionen formatiert werden. Zeicheneigenschaften wie Schriftart, Schriftgröße oder
Farbe sind auf beliebige Textabschnitte anwendbar. Textflusseigenschaften können
eingestellt werden, zum Beispiel Blocksatz oder Flattersatz, Einzüge und Tabulatorab-
stände. Trennstellen, die im Text durch weiche Trennzeichen (soft hyphen) gekennzeich-
net sind, werden berücksichtigt. Abbildung 4.11 und Abbildung 4.12 zeigen, wie verschie-
dene Elemente einer Rechnung als Textflüsse platziert ausgegeben werden. Die
einzelnen Optionen werden in den folgenden Abschnitten genauer erläutert.
Abb. 4.11
Formatierung von
Textflüssen
Kraxi Systems, Inc.
Paper Planes
17, Aviation Road
Paperfield
Phone 7079-4301
Fax 7079-4302
info@kraxi.com
Kraxi Systems, Inc. 17, Aviation Road Paperfield www.kraxi.com
John Q. Doe
255 Customer Lane
Suite B
12345 User Town
Everland
INVOICE 14.03.2004
hortabmethod ruler
tabalignment right left right right right
ruler 30 45 275 375 475
ITEM DESCRIPTION QUANTITY PRICE AMOUNT
1 Super Kite 2 20,00 40,00
2 Turbo Flyer 5 40,00 200,00
3 Giga Trash 1 180,00 180,00
4 Bare Bone Kit 3 50,00 150,00
5 Nitty Gritty 10 20,00 200,00
6 Pretty Dark Flyer 1 75,00 75,00
7 Free Gift 1 0,00 0,00
845,00
leftindent Terms of payment: 30 days net. 30 days warranty starting at the day of sale. This
warranty covers defects in workmanship only. Kraxi Systems, Inc., at its option, repairs or alignment
= 55 replaces the product under warranty. This warranty is not transferable. Returns or = left
exchanges are not possible for wet products.
Have a look at our new paper plane models!

parindent
Our paper planes are the ideal way of passing the time. We offer revolutionary
= 7%
new developments of the traditional common paper planes. If your lesson,
alignment
conference, or lecture turn out to be deadly boring, you can have a wonderful time
= justify
with our planes. All our models are folded from one paper sheet.
They are exclusively folded without using any adhesive. Several models are
leading equipped with a folded landing gear enabling a safe landing on the intended location
= 140 % provided that you have aimed well. Other models are able to fly loops or cover long
distances. Let them start from a vista point in the mountains and see where they
touch the ground.
leftindent = 75 rightindent
1. Long Distance Glider
= 60
With this paper rocket you can send all your messages even when
leftindent = 105 sitting in a hall or in the cinema pretty near the back.
2. Giant Wing minlinecount

An unbelievable sailplane! It is amazingly robust and can even do =2

fillcolor, charspacing,
fontsize, fontname
aerobatics. But it is best suited to gliding.
3. C one H e a d R oc ke t
This paper arrow can be thrown with big swing. We launched it from
the roof of a hotel. It stayed in the air a long time and covered a
considerable distance.
4. Super Dart
The super dart can fly giant loops with a radius of 4 or 5 meters and
cover very long distances. Its heavy cone point is slightly bowed
upwards to get the lift required for loops.
Abb. 4.12 5. German Bi-Plane

Brand-new and ready for take-off. If you have lessons in the history of
Formatierung von aviation you can show your interest by letting it land on your teacher's
Textflüssen desk.
Ein mehrzeiliger Textfluss wird in eines oder mehrere Rechtecke – die so genannte Fit-
box – auf einer oder mehreren Seiten platziert. Zur Platzierung des Textflusses sind fol-
gende Schritte erforderlich:
> Die Funktion PDF_create_textflow( ) analysiert den Text, erzeugt ein Textflussobjekt
und gibt ein Handle zurück. Dabei wird noch kein Text auf der Seite platziert.
> Die Funktion PDF_fit_textflow( ) platziert den Textfluss ganz oder teilweise in der
übergebenen Fitbox. Um den Textfluss vollständig zu platzieren, muss dieser Schritt
möglicherweise mehrmals wiederholt werden, wobei jeweils eine neue Fitbox – ent-
weder auf derselben oder einer neuen Seite – übergeben wird.
> Die Funktion PDF_delete_textflow( ) löscht das Textflussobjekt nach seiner vollständi-
gen Platzierung.
Die Funktion PDF_create_textflow( ) zur Erzeugung eines Textflusses bietet eine Fülle
von Optionen zur Steuerung der Formatierung. Diese können entweder in der Options-
liste übergeben oder aber als »Inline«-Optionen in den Text eingebettet werden. Die
Platzierung eines Textflusses wird im Folgenden anhand einiger häufig vorkommender
Anwendungsbeispiele erläutert. Eine vollständige Auflistung aller Optionen finden Sie
in Tabelle 8.24.
Viele der Optionen, die in PDF_create_textflow( ) genutzt werden können, sind mit de-
nen für PDF_fit_textline( ) identisch. Sie sollten sich deshalb bereits die Beispiele in Ab-
schnitt 4.8, »Platzieren und Einpassen von einzeiligem Text«, Seite 128, angesehen ha-
ben. Wir werden hier nur Optionen beschreiben, die sich auf mehrzeiligen Text
beziehen.
4.9.1 Platzierung eines Textflusses in der Fitbox

Platzierung in einer Fitbox. Beginnen wir mit einem einfachen Beispiel. Das folgende
Codefragment platziert einen Textfluss in einer Fitbox auf der Seite. Dabei wird vorwie-
gend mit Standardformatierungen gearbeitet. Schriftart, Schriftgröße und Encoding
wurden individuell festgelegt (das Ergebnis sehen Sie in Abbildung 4.13):
textflow =
PDF_create_textflow(p, text, 0, "fontname=Helvetica fontsize=9 encoding=winansi");
PDF_fit_textflow(p, textflow, left_x, left_y, right_x, right_y, "");
PDF_delete_textflow(p, textflow);

Erste Fitbox Zweite Fitbox
Terms of payment: 30 replaces the product

days net. 30 days under warranty. This
warranty starting at the warranty is not
day of sale. This transferable. Returns or
warranty covers defects exchanges are not
in workmanship only. possible for wet Abb. 4.14
Kraxi Systems, Inc., at products. Platzieren eines Textflus-
its option, repairs or ses in zwei Fitboxen
Platzierung in zwei Fitboxen. Passt ein mit PDF_fit_textflow( ) ausgegebener Textfluss

nicht vollständig in die Fitbox, wird die Ausgabe unterbrochen und der String _boxfull
zurückgegeben. PDFlib merkt sich die bereits ausgegebenen Zeichen und fährt beim
nächsten Aufruf von PDF_fit_textflow( ) an der abgebrochenen Stelle fort. Das folgende
Codefragment zeigt die Ausgabe des Textflusses in zwei Fitboxen (das Ergebnis sehen
Sie in Abbildung 4.14):
textflow =
PDF_create_textflow(p, text, 0, "fontname=Helvetica fontsize=9 encoding=winansi");
result = PDF_fit_textflow(p, textflow, left_x, left_y, right_x, right_y, "");
/* Passte der Textfluss nicht vollständig in die Fitbox? */
if (!strcmp(result, "_boxfull"))
PDF_fit_textflow(p, textflow, left_x + offset, left_y, right_x +offset, right_y, "");
Platzierung über mehrere Seiten. Passt ein mit PDF_fit_textflow( ) ausgegebener Text-
fluss nicht vollständig in die Fitbox, muss unter Umständen eine neue Seite erzeugt
werden. Ein Codefragement zur Platzierung eines Textflusses über mehrere Seiten hat
generell folgendes Aussehen:
textflow = PDF_create_textflow(p, text, 0, optlist);
do
{
PDF_begin_page_ext(p, pagewidth, pageheight, "");
result = PDF_fit_textflow(p, textflow, left_x, left_y, right_x, right_y, "");
} while (strcmp(result, "_stop"))
4.9.2 Optionen für die Absatzformatierung

Das obige Beispiel wurde mit Standardformatierungen ausgegeben. So ist die Ausrich-
tung (alignment) des Textes standardmäßig linksbündig, der Zeilenabstand (leading) ist
gleich 100% und entspricht damit der Fonthöhe.
Um die Absatzformatierung individuell zu gestalten, können wir die Funktion PDF_
create_textflow( ) mit weiteren Optionen aufrufen. Beispielsweise möchten wir den Text
links und rechts mit einem Einzug vom Seitenrand versehen, und zwar links um 15 und
Abb. 4.13 Terms of payment: 30 days net. 30 days warranty starting at the day of
Einfache Platzierung sale. This warranty covers defects in workmanship only. Kraxi Systems,
eines Textflusses Inc., at its option, repairs or replaces the product under warranty. This
warranty is not transferable. Returns or exchanges are not possible for
wet products.

Have a look at our new paper plane models! Our paper planes rightindent = 1 0
leftindent = 15 are the ideal way of passing the time. We offer revolutionary new
developments of the traditional common paper planes.
parindent = 2 0 If your lesson, conference, or lecture turn out to be deadly boring,
you can have a wonderful time with our planes. All our models are
folded from one paper sheet.
They are exclusively folded without using any adhesive. Several alignment =
models are equipped with a folded landing gear enabling a safe landing justify
leading = 140 % on the intended location provided that you have aimed well. Other
models are able to fly loops or cover long distances. Let them start
Abb. 4.15
from a vista point in the mountains and see where they touch the
Platzierung eines Textflusses
mit Aufruf-Optionen ground.
rechts um 10 Einheiten. Die erste Zeile jedes Absatzes soll zusätzlich um 20 Einheiten
eingerückt sein. Als Textausrichtung wählen wir Blocksatz, und den Abstand zwischen
den einzelnen Zeilen erhöhen wir auf 140%. Außerdem reduzieren wir die Schriftgröße
auf 8 Einheiten. Der erweitere Code mit Optionsliste lautet dann wie folgt (das Ergebnis
sehen Sie in Abbildung 4.15):
/* Stelle Optionsliste zusammen */
char optlist[256] =
"leftindent=15 rightindent=10 parindent=20 alignment=justify "
"leading=140% fontname=Helvetica fontsize=8 encoding=winansi"
/* Platziere Textfluss mittels Optionen in Fitbox */

4.9.3 Inline-Optionen und Makros

Der Text in Abbildung 4.15 ist noch nicht korrekt. Die Überschrift »Have a look at our
new paper plane models!« gehört in eine eigene Zeile. Außerdem soll sie in größerer
Schrift erscheinen und mittig ausgerichtet sein. Um dies zu bewerkstelligen, gibt es
mehrere Lösungen.
Bislang haben wir die Formatierungsoptionen im Funktionsaufruf übergeben. Um
mit dieser Technik fortzufahren, müssten wir den Text aufteilen und in zwei Aufrufen
platzieren – einen für die Überschrift und einen für die restlichen Absätze, was aber um-
ständlich wäre.
Aus diesem Grund bietet die Textflussfunktionalität so genannte Inline-Optionen.
Das bedeutet, dass die Optionen einfach in den Text eingebettet werden. Inline-Opti-
onslisten werden innerhalb des Textes übergeben und standardmäßig zwischen den
Zeichen »<« und »>« eingeschlossen. Wir integrieren also die Formatierungen für die
Überschrift und für die restlichen Absätze wie folgt in unseren Text (die Inline-
Optionslisten sind in allen folgenden Beispielen farblich hervorgehoben und Absatz-
endezeichen durch Pfeile angedeutet):
<leftindent=15 rightindent=10 alignment=center fontname=Helvetica fontsize=12
encoding=winansi>Have a look at our new paper plane models!
<alignment=justify fontname=Helvetica leading=140% fontsize=8 encoding=winansi>
Our paper planes are the ideal way of passing the time. We offer
revolutionary new developments of the traditional common paper planes.

H1 Have a look at our new paper plane models!
Body Our paper planes are the ideal way of passing the time. We offer
revolutionary new developments of the traditional common paper
planes.
Body_indented If your lesson, conference, or lecture turn out to be deadly boring,
you can have a wonderful time with our planes. All our models are
folded from one paper sheet.
They are exclusively folded without using any adhesive. Several
models are equipped with a folded landing gear enabling a safe landing
on the intended location provided that you have aimed well. Other
models are able to fly loops or cover long distances. Let them start Abb. 4.16
Zusammenfassung
from a vista point in the mountains and see where they touch the
von Inline-Optionen
ground. zu Makros
<parindent=20>If your lesson, conference, or lecture

turn out to be deadly boring, you can have a wonderful time
models are equipped with a folded landing gear enabling a safe
landing on the intended location provided that you have aimed well.
Other models are able to fly loops or cover long distances. Let them
start from a vista point in the mountains and see
where they touch the ground.
Die Zeichen zur Klammerung von Optionslisten können mit den Optionen begoptlist-
char und endoptlistchar umdefiniert werden (siehe Tabelle 8.24). Wenn Sie für die Option
begoptlistchar das Schlüsselwort none übergeben, wird die Ermittlung von Optionslisten
unterbunden. Dies ist zum Beispiel sinnvoll, wenn der Text keine Inline-Optionslisten
enthält und Sie gewährleisten möchten, dass »<« und »>« als normale Zeichen interpre-
tiert werden.
Makros. Wir haben es in obigem Text im Prinzip mit verschiedenen Absatztypen zu

tun, zum Beispiel Überschrift, Text ohne Einzug oder Text mit Einzug. Jeder dieser Ab-
satztypen ist individuell formatiert und tritt in längeren Texten mehrmals auf. Damit
wir einem Absatztyp nicht jedes Mal die zugehörigen Inline-Optionen voranstellen
müssen, können wir diese zu Makros zusammenfassen und in den Text einfach die
Makronamen einbetten. Wie Abbildung 4.16 zeigt, definieren wir für das obige Beispiel
die drei Makros H1 für die Formatierung der Überschrift, Body für Absätze ohne Einzug
und Body_indented für Absätze mit Einzug. Zur Verwendung eines Makros setzen wir das
Zeichen & vor den Namen und schreiben ihn in eine Optionsliste. Das folgende Code-
fragment definiert drei anhand der bereits verwendeten Inline-Optionen und setzt die-
se in den Text ein:
<macro {
H1 {leftindent=15 rightindent=10 alignment=center
fontname=Helvetica fontsize=12 encoding=winansi}
Body {leftindent=15 rightindent=10 alignment=justify leading=140%

fontname=Helvetica fontsize=8 encoding=winansi}
Body_indented {parindent=20 leftindent=15 rightindent=10 alignment=justify

leading=140% fontname=Helvetica fontsize=8 encoding=winansi}
}>
<&H1>Have a look at our new paper plane models!
<&Body>Our paper planes are the ideal way of passing the time. We offer
revolutionary new developments of the traditional common paper planes.
<&Body_indented>If your lesson, conference, or lecture
turn out to be deadly boring, you can have a wonderful time
models are equipped with a folded landing gear enabling a safe
landing on the intended location provided that you have aimed well.
Other models are able to fly loops or cover long distances. Let them
start from a vista point in the mountains and see
where they touch the ground.
Explizites Setzen von Optionen. Beachten Sie, dass alle Optionen, die in Makros nicht
gesetzt werden, ihren alten Wert beibehalten. Um Nebenwirkungen durch unerwünsch-
te »Vererbung« von Optionen zu vermeiden, sollten Sie daher alle gewünschten Einstel-
lungen explizit in Makros festlegen. Dadurch stellen Sie sicher, dass sich die Makros un-
abhängig von der Reihenfolge oder Kombination mit anderen Optionslisten immer
gleich verhalten.
Andererseits können Sie diese Eigenschaft auch für Makros nutzen, um bestimmte
Einstellungen bewusst aus dem jeweiligen Kontext übernehmen, anstatt sie explizit
festzulegen. So könnte ein Makro zum Beispiel die Schriftart festlegen, ohne die Option
fontsize anzugeben. Die Schriftgröße entspricht dann automatisch der des vorangehen-
den Textes.
Inline-Optionen oder Optionen als Funktionsparameter? Bei der Ausgabe von Text-
flüssen ist es wichtig zu unterscheiden, ob der Text im Programm selbst kodiert ist oder
aus einer externen Quelle stammt und ob die Formatierung und der Text getrennt ge-
halten werden. Der reine Textinhalt stammt in der Regel aus einer externen Quelle,
etwa einer Datenbank. In der Praxis sind also die folgenden Anwendungsfälle zu be-
rücksichtigen:
> Inhalt aus externer Quelle, Formatierungsoptionen im Programm: Aus einer exter-
nen Datenbank kommen kleinere Textfragmente, die im Programmcode zusam-
mengesetzt und erst zur Laufzeit mit Formatierungsoptionen (im Funktionsaufruf)
angereichert werden.
> Inhalt und Formatierungsoptionen aus externer Quelle: Größere Textmengen ein-
schließlich der Formatierungsoptionen kommen aus einer externen Quelle. Die For-
matierung wird dabei durch Inline-Optionen im Text bereitgestellt, die einfache Op-
tionen oder Makros sein können. Bei der Verwendung von Makros ist zwischen
Makrodefinitionen und Makroaufrufen zu trennen. Daraus ergibt sich eine interes-
sante Mischform. Der Inhalt kommt von einer externen Quelle mit Makroaufrufen
zur Formatierung; die Makrodefinitionen werden aber erst zur Laufzeit zugemischt.
Mischt man die Markodefinitionen erst zur Laufzeit hinzu, kann man die Formatie-
rung mit minimalem Aufwand beeinflussen, ohne dass der extern zugelieferte Text
geändert werden muss. Zum Erstellen von Grußkarten könnte man zum Beispiel
verschiedene Stile definieren (via Makros), die der Karte einen romantischen, nüch-
ternen oder anderen Touch geben.

4.9.4 Tabulatoren
Im Folgenden geht es um die Platzierung einer Tabelle mit links- und rechtsbündigen
Spalten unter Verwendung von Tabulatoren. Die Tabelle enthält folgende Zeilen, deren
Einträge durch Tabulatoren getrennt sind (die Tabulatorzeichen werden durch Pfeile
symbolisiert):
ITEM DESCRIPTION QUANTITY PRICE AMOUNT
1 Super Kite 2 20.00 40.00
2 Turbo Flyer 5 40.00 200.00
3 Giga Trash 1 180.00 180.00
TOTAL 420.00
Das folgende Codefragment platziert die Tabelle, und zwar anhand der Optionen ruler
zur Definition der Tabulatorabstände, tabalignment für die Tabulatorausrichtung und
hortabmethod für die Methode zum Umgang mit Tabulatoren (das Ergebnis sehen Sie in
Abbildung 4.17):
char optlist[256] =
"ruler {30 150 250 350} "
"tabalignment {left right right right} "
"hortabmethod ruler leading=120% fontname=Helvetica fontsize=9 encoding=winansi";
/* Platziere Tabelle in Fitbox */

textflow = PDF_create_textflow(p, table, 0, optlist);
4.9.5 Nummerierte Listen

Das folgende Beispiel zeigt, wie anhand der Inline-Option leftindent für den linken Ein-
zug eine nummerierte Liste formatiert wird (das Ergebnis sehen Sie in Abbildung 4.18):
1.<leftindent 10>Long Distance Glider: With this paper rocket you can send all
your messages even when sitting in a hall or in the cinema pretty near the back.
<leftindent 0>2.<leftindent 10>Giant Wing: An unbelievable sailplane! It is amazingly
robust and can even do aerobatics. But it is best suited to gliding.
<leftindent 0>3.<leftindent 10>Cone Head Rocket: This paper arrow can be thrown with big
swing. We launched it from the roof of a hotel. It stayed in the air a long time and
covered a considerable distance.
hortabmethod ruler
tabalignment left right right right
ruler 30 150 250 350
Abb. 4.17 ITEM DESCRIPTION QUANTITY PRICE AMOUNT

Platzierung von 1 Super Kite 2 20.00 40.00
Text als Tabelle 2 Turbo Flyer 5 40.00 200.00
3 Giga Trash 1 180.00 180.00
TOTAL 420.00

1. Long Distance Glider: With this paper rocket you can send all your
messages even when sitting in a hall or in the cinema pretty near the
back.
2. Giant Wing: An unbelievable sailplane! It is amazingly robust and can
even do aerobatics. But it is best suited to gliding.
3. Cone Head Rocket: This paper arrow can be thrown with big swing. We
launched it from the roof of a hotel. It stayed in the air a long time and Abb. 4.18
covered a considerable distance. Nummerierte Liste
Das Setzen und Zurücksetzen des Einzugs ist mühsam, zumal es in jedem Absatz erfor-
derlich ist. Die elegantere Variante arbeitet mit dem Makro list, das der Bequemlichkeit
halber das Makro indent verwendet, das als Konstante dient. Die Makros sind wie folgt
definiert:
<macro {
indent {25}
list {parindent=-&indent leftindent=&indent hortabsize=&indent

hortabmethod=ruler ruler={&indent}}
}>
<&list>1. Long Distance Glider: With this paper rocket you can send all your messages
even when sitting in a hall or in the cinema pretty near the back.
2. Giant Wing: An unbelievable sailplane! It is amazingly robust and can even do
aerobatics. But it is best suited to gliding.
3. Cone Head Rocket: This paper arrow can be thrown with big swing. We launched
it from the roof of a hotel. It stayed in the air a long time and covered a
considerable distance.
Mit der Option leftindent wird der linke Einzug festgelegt. Mit der Option parindent, die
genau dem negativen leftindent entspricht, wird der linke Einzug für die jeweils erste
Zeile eines Absatzes rückgängig gemacht. Mit den Optionen hortabsize, hortabmethod
und ruler wird der Tabulator festgelegt, der leftindent entspricht und bewirkt, dass der
Text nach der Nummer genau um leftindent eingerückt wird. Abbildung 4.19 zeigt die
Funktionsweise von parindent und leftindent.
leftindent = &indent
parindent = – &indent 1. Long Distance Glider: With this paper rocket you can send all your
messages even when sitting in a hall or in the cinema pretty near
the back.
2. Giant Wing: An unbelievable sailplane! It is amazingly robust and
can even do aerobatics. But it is best suited to gliding.
Abb. 4.19 3. Cone Head Rocket: This paper arrow can be thrown with big swing.
Nummerierte We launched it from the roof of a hotel. It stayed in the air a long
Liste mit Makros time and covered a considerable distance.

4.9.6 Steuerzeichen, Zeichenersetzung und Symbolfonts
Steuerzeichen in Textflüssen. Es gibt eine Reihe von Zeichen, die in Textflüssen beson-
ders behandelt werden. Außerdem unterstützt PDFlib symbolische Namen für die Opti-
on charmapping, die statt der Zeichencodes verwendet werden können. Tabelle 4.5 führt
alle ausgewerteten Steuerzeichen zusammen mit ihren symbolischen Namen auf und
erklärt ihre Bedeutung. Eine Option darf nur einmal pro Optionsliste angegeben wer-
den, allerdings können mehrere Optionslisten direkt aufeinander folgen. Die folgende
Sequenz erzeugt zum Beispiel eine Leerzeile:
<nextline><nextline>
Ersetzung von Zeichen oder gleichartigen Zeichenfolgen. Mit der Option charmapping
können die Zeichen eines Textes bei der Ausgabe durch andere Zeichen ersetzt werden.
Beginnen wir mit einem einfachen Fall, in dem wir alle Tabulatorzeichen durch Leerzei-
chen ersetzen. Die charmapping-Option hierfür lautet:
charmapping {hortab space}
Dabei sind hortab und space symbolische Namen. Eine Liste aller unterstützten symboli-
schen Namen finden Sie in Tabelle 4.5. Für mehrere Ersetzungen können wir folgende
Ergänzung vornehmen, die jeden Tabulator und Zeilenumbruch durch ein Leerzeichen
ersetzt:
charmapping {hortab space CRLF space LF space CR space}
Das folgende Beispiel entfernt alle weichen Trennstellen:

charmapping {shy {shy 0}}
Jedes Tabulator-Zeichen wird durch vier Leerzeichen ersetzt:

charmapping {hortab {space 4}}
Jede beliebig lange Folge von Linefeed-Zeichen wird auf ein einziges Linefeed-Zeichen
reduziert:
charmapping {linefeed {linefeed -1}}
Jede Folge von CRLF-Kombinationen wird durch ein einziges Leerzeichen ersetzt:
charmapping {CRLF {space -1}}
Führen wird das letzte Beispiel etwas genauer aus. Angenommen, man erhält einen
Text, dessen Zeilen von anderer Software durch feste Zeilenumbrüche getrennt wurden
und deswegen nicht mehr richtig umbrechen. Man möchte die Umbrüche durch Leer-
zeichen ersetzen, um wieder einen Umbruch am Rand der Fitbox zu erhalten. Dazu er-
setzen wir beliebig lange Folgen von Zeilenumbrüchen durch ein einziges Leerzeichen.
Der zu verbessernde Text lautet:
To fold the famous rocket looper proceed as follows:
Take a sheet of paper. Fold it
lengthwise in the middle.
Then, fold down the upper corners. Fold the

To fold the famous rocket looper proceed as follows:
Take a sheet of paper. Fold it
lengthwise in the middle.
Then, fold down the upper corners. Fold the Abb. 4.20
long sides inwards Oben: Text mit überflüssigen Um-
that the points A and B meet on the central fold. brüchen
To fold the famous rocket looper proceed as follows: Take a sheet of Unten: Umwandlung der Umbrü-
paper. Fold it lengthwise in the middle. Then, fold down the upper che mit der Option charmapping
corners. Fold the long sides inwards that the points A and B meet on
the central fold.
long sides inwards

that the points A and B meet on the central fold.
Das folgende Codefragment zeigt die Ersetzung der überflüssigen Umbrüche und For-
matierung des derart korrigierten Textes:
strcpy(optlist, "fontname=Helvetica fontsize=9 encoding=winansi alignment=justify ");
strcat(optlist, "charmapping {CRLF {space -1}}");
/* Platziere Textfluss in Fitbox */
Abbildung 4.20 zeigt die Ausgabe des unveränderten Textes und seine »Reparatur« mit
Hilfe der Option charmapping.
Symbolfonts in Textflüssen. Symbolfonts, genauer gesagt, Text in einer Schrift, die

nicht Unicode-kompatibel ist (siehe Abschnitt 4.5.6, »Unicode-kompatible Fonts«, Seite
113) muss in Textflüssen besonders behandelt werden:
> Die in Tabelle 4.5 angeführten Steuerzeichen erfahren keine Spezialbehandlung, d.h.
ihnen kommt keine Sonderbedeutung zu.
> Textflussoptionen wie tabalignchar werden ignoriert, da sie bei Symbolfonts keinen
Sinn haben. Tabelle 8.24 zeigt alle Optionen, die bei nicht Unicode-kompatiblen
Schriften ignoriert werden.
> Da Inline-Optionslisten in Textteilen mit Symbolfonts nicht verwendbar sind (da
Symbole keine immanente Bedeutung aufweisen, wären Optionslisten weder auf-
find- noch interpretierbar), muss die Länge von aus Symbolen bestehenden Texttei-
len explizit mit der Option textlen angegeben werden.
> Nach textlen Zeichen muss eine weitere Inline-Optionsliste im Text platziert werden,
die zu einer anderen Schrift/Zeichensatz-Kombination wechselt.
Der folgende Text enthält zwischen lateinischen Zeichen ein Zeichen aus der Schrift
Symbol:
<fontname=Helvetica fontsize=12 encoding=winansi>Der griechische Buchstabe
<fontname=Symbol encoding=builtin textlen=1>A
<fontname=Helvetica encoding=winansi> steht für den Anfang.

Abb. 4.21 Abb. 4.22
Blocksatz mit Standardeinstellungen in brei- Blocksatz mit Standardeinstellungen in
ter Fitbox und mit expliziten »weichen« breiter Fitbox ohne explizite Trennzeichen
Trennzeichen
Our paper planes are the ideal way of Our paper planes are the ideal way of
passing the time. We offer revolu- passing the time. We offer revolutionary
tionary brand new developments of the brand new developments of the
traditional common paper planes. If traditional common paper planes. If
your lesson, conference, or lecture turn your lesson, conference, or lecture turn
out to be deadly boring, you can have out to be deadly boring, you can have
a wonderful time with our planes. All a wonderful time with our planes. All
our models are folded from one paper our models are folded from one paper
sheet. They are exclusively folded sheet. They are exclusively folded
without using any adhesive. Several without using any adhesive. Several
models are equipped with a folded models are equipped with a folded
landing gear enabling a safe landing landing gear enabling a safe landing
on the intended location provided that on the intended location provided that
you have aimed well. Other models are you have aimed well. Other models are
able to fly loops or cover long dist- able to fly loops or cover long
ances. Let them start from a vista point distances. Let them start from a vista
in the mountains and see where they point in the mountains and see where
touch the ground. they touch the ground.
Fehlt die Option textlen bei Symbolsequenzen oder wird keine Inline-Optionsliste direkt
nach der Symbolsequenz übergeben, wird eine Exception ausgelöst.
4.9.7 Trennung
PDFlib trennt Text nicht automatisch, kann Wörter aber an Stellen trennen, die im Text
explizit mit weichen Trennzeichen (soft hyphen) markiert sind. Das weiche Trennzei-
chen befindet sich in Unicode an Position U+00AD. In von Unicode verschiedenen Um-
gebungen kann das weiche Trennzeichen unterschiedlich festgelegt werden:
> In den Zeichensätzen cp1250 – cp1258 (einschließlich winansi) und iso8859-1 – iso8859-
16 entspricht das weiche Trennzeichen dezimal 173, oktal 255 bzw. hexadezimal
0xAD.
> Im Zeichensatz ebcdic entspricht das weiche Trennzeichen dezimal 202, oktal 312 bzw.
hexadezimal 0xCA.
> Wenn ein Zeichensatz (z.B. macroman) über keine weichen Trennzeichen verfügt,
kann eine Entity-Referenz verwendet werden: (siehe Abschnitt 4.5.5, »Charac-
ter-Referenzen«, Seite 111)
Außer an den Trennstellen, die durch weiche Trennzeichen gekennzeichnet sind, müs-
sen Wörter manchmal gewaltsam getrennt werden, wenn andere Methoden der Anpas-
sung, etwa das Ändern des Wortabstands oder Stauchen des Textes, nicht durchführbar
sind.
Hinweis PDFlib berücksichtigt die Satzregeln für CJK-Zeichen.
Blocksatz mit und ohne Trennzeichen. Im ersten Beispiel soll der folgende Text, der be-
reits mit Softhyphens versehen ist, im Blocksatz ausgegeben werden (die Softhyphen-
Zeichen sind hier der Deutlichkeit halber als kleine Balken dargestellt):
Our paper planes are the ideal way of pas sing the time. We offer revolu tionary
brand new dev elop ments of the tradi tional common paper planes. If your lesson,

confe rence, or lecture turn out to be deadly boring, you can have a wonder ful time
with our planes. All our models are folded from one paper sheet. They are exclu sively
folded without using any adhe sive. Several models are equip ped with a folded
landing gear enab ling a safe landing on the intended loca tion provided that you
have aimed well. Other models are able to fly loops or cover long dist ances. Let them
start from a vista point in the mount ains and see where they touch the ground.
Abbildung 4.21 zeigt die Ausgabe des Textes mit Standardeinstellungen für den Block-
satz. Die Ausgabe ist tadellos, da die Voraussetzungen optimal sind: Die Fitbox ist breit
genug und es sind explizit im Text gesetzte Trennzeichen vorhanden. Wie Abbildung
4.22 zeigt, erhalten Sie in einer breiten Fitbox mit Standardeinstellungen auch dann
eine gute Ausgabe, wenn im Text keine expliziten Trennzeichen vorhanden sind. Die
Optionsliste lautet in beiden Fällen einfach:
fontname=Helvetica fontsize=9 encoding=winansi alignment=justify
4.9.8 Steuerung des Algorithmus für den Zeilenumbruch

PDFlib verfügt über einen ausgefeilten Algorithmus für den Zeilenumbruch von Text.1
Tabelle 4.9 zeigt die Textflow-Optionen zur Steuerung des Zeilenumbruchs.
Tabelle 4.9 Optionen zur Steuerung des Zeilenumbruchs

Option Typ Erklärung
adjust- Schlüsselwort Methode zur Berechnung der Zeilenumbrüche für Text, der nach Stauchen oder
method Dehnen der Wortabstände innerhalb der von minspacing und maxspacing ge-
setzten Grenzen nicht mehr vollständig in die Zeile passt. Standardwert: auto
auto Versuche nacheinander die Methoden shrink, spread, nofit, split
clip Wie nofit (siehe unten) mit dem Unterschied, dass lange Zeilen am
rechten Rand der Fitbox (abzüglich der Option rightindent) abge-
schnitten werden.
nofit Das letzte Wort wird in die nächste Zeile gestellt, sofern die vorige Zeile
dadurch nicht kürzer wird als der durch nofitlimit vorgegebene Pro-
zentsatz. Der Blocksatz »flattert« dann an dieser Stelle ein wenig.
shrink Passt ein Wort nicht mehr vollständig in die Zeile, wird versucht, den
Text in dieser Zeile unter Berücksichtigung von shrinklimit soweit zu
stauchen, bis das Wort doch noch hineinpasst. Falls der Text immer
noch nicht passt, wird die Methode nofit angewandt.
split Das letzte Wort wird nicht in die nächste Zeile gestellt, sondern
zwangsweise getrennt. Bei Textschriften wird ein Trennzeichen einge-
fügt, bei Symbolschriften dagegen nicht.
spread Das letzte Wort wird in die nächste Zeile gestellt und die verbleibende
kurze Zeile durch Sperren des Textes auf Blocksatz gebracht, sofern die
Option spreadlimit dies zulässt. Falls der Text immer noch nicht passt,
wird die Methode nofit angewandt.
avoidbreak Boolean Bei true findet solange kein Zeilenumbruch statt, bis avoidbreak wieder auf false
gesetzt wird. Standardwert: false
hyphenchar Integer Unicode-Wert des Zeichens, das ein weiches Trennzeichen beim Zeilenumbruch
ersetzt. Standardwert: U+00AD (SOFT HYPHEN) falls im Font enthalten, sonst
U+002D (HYPHEN-MINUS)
1. Für interessierte Leser sei darauf hingewiesen, dass sich PDFlib an die Empfehlungen in »Unicode Standard Annex #14:
Line Breaking Properties« anlehnt (siehe www.unicode.org/reports/tr14). PDFlib berücksichtigt keine combining marks.

Tabelle 4.9 Optionen zur Steuerung des Zeilenumbruchs
maxspacing Float oder Minimaler oder minimaler Abstand zwischen zwei Wörtern (in Benutzer-
minspacing Prozentwert koordinaten oder als Prozentwert der Breite eines Leerzeichens); der jeweils
berechnete Wortabstand wird zum Wert der Option wordspacing addiert.
Standardwerte: minspacing=50%, maxspacing=500%
nofitlimit Float oder Minimal erlaubte Länge einer Zeile bei der Methode nofit (in Benutzer-
Prozentwert koordinaten oder als Prozentwert der Breite der Fitbox). Standardwert: 75%
shrinklimit Prozentwert Untergrenze für das Stauchen des Textes bei der Methode shrink; der jeweils
berechnete Stauchungsfaktor wird mit dem Wert der Option horizscaling
multipliziert. Standardwert: 85%
spreadlimit Float oder Obergrenze für den Abstand zwischen zwei Zeichen bei der Methode spread; der
Prozentwert jeweils berechnete Zeichenabstand wird zum Wert der Option charspacing
addiert. Standardwert: 0
Umruchregeln. Wenn ein Wort bzw. eine andere Zeichenfolge zwischen zwei Leerzei-
chen nicht vollständig in die Zeile passt, muss es in die nächste Zeile umgebrochen wer-
den. Dabei entscheidet der Umbruchalgorithmus, nach welchen Zeichen innerhalb ei-
ner Zeilenfolge ein Umbruch möglich ist.
Eine Formel wie -12+235/8*45 wird zum Beispiel nie umgebrochen, während der
String PDF-345+LIBRARY nach dem Minuszeichen in die nächste Zeile gestellt werden
kann. Nach weichen Trennzeichen (soft hyphen), sofern sie im Text bereits vorhanden
sind, kann ebenfalls ein Umbruch erfolgen.
Bei Klammern wird zwischen schließender und öffnender Klammer unterschieden,
wobei auch Anführungszeichen wie Klammern behandelt werden. Nach einer öffnen-
den Klammer wie »(« wird nicht umgebrochen. Bei Anführungszeichen wird mittels Bi-
lanzierung ermittelt, ob es sich um ein öffnendes oder schließendes Zeichen handelt.
Unter einem potentiellen Zeilenumbruch verstehen wir eine Stelle im Text, an der
die Textflow-Engine bei Bedarf eine Zeile beenden und den nachfolgenden Text in die
nächste Zeile schieben kann. Leerzeichen zwischen Text stellen immer einen potentiel-
len Zeilenumbruch dar. Inline-Optionslisten stellen grundsätzlich keinen potentiellen
Zeilenumbruch dar (damit man Optionen auch innerhalb eines Worts ändern kann). Be-
finden sich jedoch vor und nach der Optionsliste Leerzeichen, kann zu Beginn der Opti-
onsliste ein Umbruch erfolgen. Wird vor der Optionsliste umgebrochen und ist
alignment=justify, werden Leerzeichen vor der Optionsliste entfernt. Leerzeichen nach
der Optionsliste bleiben erhalten und werden an den Anfang der nächsten Zeile positio-
niert.
Blocksatz in schmaler Fitbox. Mit den Optionen zur Steuerung des Blocksatzes müs-
sen Sie sich in der Regel um so mehr auseinander setzen, je schmaler die Fitbox ist. Ab-
bildung 4.23 illustriert an einer schmalen Fitbox, an welchen Stellen die Blocksatz-
Methoden und Optionen besondere Wirkung zeigen. In Abbildung 4.23 sind die Einstel-
lungen der drei Optionen an sich in Ordnung, lediglich maxspacing legt einen etwas
großzügigen maximalen Wortabstand fest. Dies sollte man bei sehr schmaler Fitbox je-
doch belassen, da sonst die hässliche (durch die Methode split verursachte) Zwangstren-
nung häufiger zur Anwendung kommt.
Ist die Fitbox so schmal, dass hin und wieder zwangsweise getrennt wird, sollten Sie
entweder das Einfügen expliziter »weicher« Trennzeichen erwägen oder die Blocksatz-
Optionen verändern.

Our paper planes
are the ideal way of
passing the time. We Verkleinern des Wortabstands (Standardmethode, Option minspacing)
offer revolutionary
brand new develop-
ments of the traditional Stauchen der Zeile (Methode shrink, Option shrinklimit)
common paper planes.
If your lesson, conf- Zwangstrennung (Methode split)
erence, or lecture
turn out to be deadly
boring, you can have
a wonderful time
with our planes. All
our models are Vergrößern des Wortabstands (Standardmethode, Option maxspacing)
folded from one
paper sheet. They
are exclusively folded Abb. 4.23
without using any Blocksatz mit Standardeinstellungen in schmaler Fitbox
Blocksatz-Option shrinklimit. Am unauffälligsten für das Auge ist es, die Option
shrinklimit zu verkleinern, die festlegt, auf wieviel Prozent seiner normalen Breite Text
durch die Methode shrink maximal gestaucht werden darf. Abbildung 4.24 zeigt, wie sich
Zwangstrennungen durch Stauchung auf bis zu 50% vermeiden lassen. Die Optionsliste
lautet:
fontname=Helvetica fontsize=9 encoding=winansi alignment=justify shrinklimit=50%
Blocksatz-Option spreadlimit. Das Sperren von Text, das mit der Methode spread be-
werkstelligt und durch die Option spreadlimit zum Ändern des Zeichenabstands kon-
trolliert wird, ist ein weiteres Verfahren zur Beeinflussung des Zeilenumbruchs. Dieses
optisch sehr auffällige Verfahren kommt aber nur selten zum Einsatz. Abbildung 4.25
zeigt einen der Deutlichkeit halber sehr auffälligen maximalen Zeichenabstand von 5
Einheiten. Die Optionsliste lautet:
fontname=Helvetica fontsize=9 encoding=winansi alignment=justify spreadlimit=5
Our paper planes

passing the time.We
offer revolutionary
brand new developments Stauchen der Zeile (Methode shrink, Option shrinklimit)
of the traditional
If your lesson, conference,
or lecture turn out to
be deadly boring,
you can have a
wonderful time with
our planes. All our
models are folded
from one paper
sheet. They are
exclusively folded without Abb. 4.24
using any adhesive. Stauchung auf bis zu 50% Breite

Our paper planes
passing the time. We
offer revolutionary
brand new develop-
ments of the traditional
If your lesson, Verkürzen der Zeile (Methode nofit, Option nofitlimit)
conference, or lecture
turn out to be deadly
boring, you can have
a wonderful time Abb. 4.26
with our planes. Blocksatz mit minimaler Textbreite von 50%
Blocksatz-Option nofitlimit. Mit der Option nofitlimit schließlich können Sie bestim-
men, wie kurz der Text in einer Zeile minimal werden darf, wenn die Methode nofit zur
Anwendung kommt. Eine Verkleinerung des Standardwertes von 75% ist bei sehr
schmalen Zeilen einer Zwangstrennung vorzuziehen. Abbildung 4.26 zeigt die Ausgabe
des Textes mit einer minimalen Textbreite von 50%. Die Optionsliste lautet:
fontname=Helvetica fontsize=9 encoding=winansi alignment=justify nofitlimit=50
4.9.9 Formatierung von CJK-Text in Textflüssen

Die Textflow-Implementierung ist auf CJK-Text vorbereitet und verarbeitet CJK-Zeichen
korrekt als ideografische Zeichen gemäß Unicode. Folglich kann bei CJK-Text auch keine
Trennung stattfinden. Zur besseren Formatierung von CJK-Text in Textflüssen sind fol-
gende Optionen zu empfehlen; sie deaktivieren die Trennung von eingeschobenem la-
teinischem Text und erzeugen eine Ausgabe mit gleichmäßigen Abständen:
hyphenchar=none
alignment=justify
shrinklimit=100%
spreadlimit=100%
Beachten Sie folgende Einschränkungen bei Textflüssen mit CJK-Text:

> Vertikale Schreibrichtung wird nicht unterstützt.
> Nur Unicode-kompatible Zeichensätze sind einsetzbar, d.h. unicode oder eine der
Unicode-kompatiblen, vordefinierten CMaps.
Our paper planes Abb. 4.25

are the ideal way of Blocksatz mit maximalem Zeichenabstand von 5 Einheiten
passing the time. We
offer revolutionary
b r a n d n e w Dehnen der Zeile (Methode spread, Option spreadlimit)
developments of the
traditional common
paper planes. If your
lesson, conference,
or lecture turn out to
be deadly boring,
you can have a
wonderful time with
our planes.

5 Import und Platzierung von
Objekten
PDFlib bietet eine Vielzahl von Funktionen, um Rasterbilder und Seiten aus vorhande-
nen PDF-Dokumenten zu importieren und auf der Seite zu platzieren. Dieses Kapitel be-
schreibt den Umgang mit Rasterbildern und den Import von Seiten aus vorhandenen
PDF-Dokumenten. Zudem wird anhand von Beispielen gezeigt, wie Bilder und PDF-
Seiten auf einer Ausgabeseite platziert werden.
5.1 Import von Rasterbildern

5.1.1 Grundlegende Vorgehensweise
Die Einbettung von Rasterbildern mit PDFlib ist einfach zu bewerkstelligen. Die Bildda-
tei muss zunächst mit einer PDFlib-Funktion geöffnet werden, die eine kurze Analyse
der Bildparameter durchführt. Die Funktion PDF_load_image( ) gibt ein Handle zurück,
das als Bilddeskriptor dient. Es kann zusammen mit Positionierungs- und Skalierungs-
parametern im Aufruf von PDF_fit_image( ) verwendet werden:
if ((image = PDF_load_image(p, "auto", "bild.jpg", 0, "")) == -1) {
fprintf(stderr,"Fehler: Bilddatei konnte nicht gelesen werden.\n");
} else {
PDF_fit_image(p, image, 0.0, 0.0, "");
PDF_close_image(p, image);
}
PDF_fit_image( ) erhält als letztes Argument eine Optionsliste mit verschiedenen Optio-
nen zur Positionierung, Skalierung und Rotation des Bildes. Weitere Informationen
hierzu finden Sie in Abschnitt 5.3, »Platzieren von Bildern und importierten PDF-Sei-
ten«, Seite 159.
Wiederverwendung von Bilddaten. Es ist hervorzuheben, dass PDFlib ein wichtiges

PDF-Verfahren zur Reduzierung der Dateigröße bei mehrfach vorkommenden Raster-
bildern unterstützt. Betrachten wir zum Beispiel ein Layout, bei dem sich ein bestimm-
tes Logo oder ein Hintergrund auf mehreren Seiten befindet. In solchen Fällen ist es
möglich, die Bilddaten in der PDF-Datei nur einmal zu speichern und auf jeder Seite nur
noch eine Referenz darauf anzulegen. Dazu öffnen Sie die Bilddatei und rufen einfach
PDF_fit_image( ) auf jeder Seite auf, auf der Sie das Logo oder den Hintergrund platzieren
möchten. Sie können das geöffnete Bild auf mehreren Seiten platzieren und dabei un-
terschiedliche Skalierungsfaktoren verwenden (solange es nicht wieder geschlossen
wird). Abhängig von der Bildgröße und der Häufigkeit des Auftretens kann dieses Ver-
fahren enorm viel Speicherplatz sparen.
Inline-Bilder. Im Gegensatz zu wiederverwendbaren Bildern, die als XObjects vom Typ

Image in die PDF-Ausgabe geschrieben werden, werden Inline-Bilder direkt in den ent-
sprechenden Content-Stream (Beschreibung von Seite, Pattern, Template oder Glyphe)
aufgenommen. Dies spart zwar Speicherplatz, nach einer Empfehlung in der PDF-Refe-

renz sollte dieses Verfahren aber nur bei geringer Bildgröße (maximal 4 KB) verwendet
werden. Inline-Bilder werden hauptsächlich für Bitmaps in Type-3-Schriften benutzt.
Inline-Bilder können mit der Schnittstelle PDF_load_image( ) und der Option inline
generiert werden. Sie sind nicht wiederverwendbar, das heißt, das zugehörige Handle
darf nicht an beliebige Funktionen, die Image-Handles akzeptieren, übergeben werden.
Deshalb führt die Funktion PDF_load_image( ), wenn sie mit der Option inline aufgerufen
wird, intern Operationen durch, die folgenden Anweisungen entsprechen:
PDF_fit_image(p, image, 0, 0, "");
Skalierung und dpi-Berechnung. PDFlib ändert die Pixelanzahl eines importierten Bil-
des nie. Beim Skalieren werden die Bildpunkte entweder vergrößert oder verkleinert, es
findet jedoch keinerlei Downsampling statt (die Pixelanzahl des Bildes bleibt immer
gleich). Der Skalierungsfaktor 1 bewirkt eine Pixelgröße von einer Einheit in benutzer-
spezifischen Koordinaten. Anders ausgedrückt: das Bild wird mit seiner Originalauflö-
sung (oder 72 dpi, falls das Bild keine Auflösungsangabe enthält) importiert, wenn das
benutzerspezifische Koordinatensystem nicht skaliert wurde (da ein Zoll 72 Punkt ent-
spricht).
Farbraum importierter Bilder. Außer beim Hinzufügen oder Entfernen von ICC-Profi-
len oder Anwenden einer Schmuckfarbe unter Verwendung der Optionen für PDF_load_
image( ), versucht PDFlib in der Regel, den Farbraum importierter Bilder zu erhalten.
Dies ist jedoch bei einigen seltenen Kombinationen nicht möglich, zum Beispiel bei
YCbCr in TIFF.
PDFlib führt keine Konvertierung zwischen RGB und CMYK durch. Wo dies erforder-
lich ist, muss die Konvertierung vor dem Laden des Bildes in PDFlib erfolgen.
5.1.2 Unterstützte Rasterbildformate

PDFlib verarbeitet alle Rasterbildformate, die unten beschrieben werden. Standardmä-
ßig reicht PDFlib die komprimierten Bilddaten, sofern dies möglich ist, unverändert an
die PDF-Ausgabe weiter, da PDF intern die meisten in Rasterbildformaten verwendeten
Kompressionsverfahren unterstützt. Diese Technik (in den folgenden Beschreibungen
Pass-Through-Modus genannt) bewirkt einen äußerst schnellen Bildimport, da die De-
kompression und die darauf folgende erneute Kompression der Bilddaten entfallen. In
diesem Modus kann PDFlib die Integrität der komprimierten Bilddaten nicht überprü-
fen. Unvollständige oder beschädigte Daten bewirken Fehler- oder Warnmeldungen,
wenn das PDF-Dokument in Acrobat angezeigt wird (zum Beispiel Nicht genügend Daten
für ein Bild). Der Pass-Through-Modus lässt sich mit der Option passthrough für PDF_
load_image( ) steuern.
Wenn eine Rasterbilddatei nicht erfolgreich importiert werden konnte, gibt PDF_
load_image( ) einen Fehlercode zurück. Um Einzelheiten über die Ursachen zu erfahren,
können Sie mit PDF_get_errmsg( ) eine detaillierte Fehlermeldung abrufen.
PNG-Bilder. PDFlib unterstützt alle Varianten von PNG-Bildern (ISO 15948). PNG-Bilder
werden meistens im Pass-Through-Modus verarbeitet. PNG-Bilder, die das Zeilen-
sprungverfahren (Interlacing) nutzen oder einen Alphakanal enthalten (der in jedem Fall
verlorengeht, siehe unten), müssen dekomprimiert werden, was bedeutend länger dau-
ert als der Pass-Through-Modus. Enthält ein PNG-Bild Transparenzinformationen, so
148 Kapitel 5: Import und Platzierung von Objekten

bleibt diese im generierten PDF erhalten (siehe Abschnitt 5.1.3, »Bildmasken und Trans-
parenz«, Seite 151). Alphakanäle werden von PDFlib nicht unterstützt.
JPEG-Bilder. JPEG-Bilder (ISO 10918-1) sind immer komprimiert, aber manche Varian-
ten müssen für die korrekte Anzeige in Acrobat transkodiert werden. Bei wichtigen Ty-
pen von JPEG-Bildern erfolgt die Transkodierung in PDFlib automatisch, sie kann aber
auch über die Option passthrough für PDF_load_image( ) gesteuert werden. PDFlib unter-
stützt folgende Varianten von JPEG-Bildern:
> Graustufen, RGB-Farbe (gewöhnlich als YCbCr kodiert) und CMYK-Farbe
> Baseline-Kompressionsmodus von JPEG, der in der überwiegenden Mehrheit der
JPEG-Bilder verwendet wird
> Progressive-Kompressionsmodus von JPEG
JPEG-Bilder können in unterschiedlichen Dateiformaten verpackt sein. PDFlib unter-

stützt alle gängigen JPEG-Dateiformate und ermittelt Auflösungswerte aus den folgen-
den Varianten:
> JFIF, das von einer Vielzahl von Anwendungen unterstützt wird
> JPEG-Dateien, die von Adobe Photoshop und anderen Adobe-Anwendungen erzeugt
werden. PDFlib wendet ein besonderes Verfahren an, um aus Photoshop generierte
JPEG-Dateien mit CMYK-Farben korrekt zu verarbeiten.
Hinweis PDFlib interpretiert keine Auflösungsinformationen von JPEG-Bildern im Dateiformat SPIFF

und keine Farbraumdaten von JPEG-Bildern im Dateiformat EXIF.
JPEG2000-Bilder. JPEG2000-Bilder (ISO 15444-2) erfordern PDF ab Version 1.5 und wer-
den immer im Pass-Through-Modus verarbeitet. PDFlib unterstützt JPEG2000-Bilder
wie folgt:
> Es werden JP2- und JPX-Baseline-Bilder (üblicherweise *.jp2 oder *.jpf) unterstützt,
wobei die Bedingungen bezüglich des Farbraums berücksichtigt werden (siehe un-
ten). Alle gültigen Werte für die Farbtiefe werden unterstützt.
> Es werden folgende Farbräume unterstützt: sRGB, sRGB-grey, ROMM-RGB, sYCC,
e-sRGB, e-sYCC, CIELab, ICC-basierte Farbräume (eingeschränktes und vollständiges
ICC-Profil) und CMYK. PDFlib verändert den ursprünglichen Farbraum der
JPEG2000-Bilddatei nicht.
> Auf Bilder, die eine Maske enthalten, kann die Option mask angewandt werden. Eine
derart vorbereitete Maske kann dann auf andere Bilder angewandt werden.
> Externe ICC-Profile können auf ein JPEG2000-Bild nicht angewendet werden, d.h. die
Option iccprofile darf nicht benutzt werden. In der JPEG2000-Bilddatei vorhandene
ICC-Profile bleiben immer erhalten, d.h. die Option honoriccprofile ist immer true.
> Die Option colorize wird für JPEG2000-Bilder nicht unterstützt.
Hinweis Reine JPEG2000-Codestreams ohne JPX-Wrapper (oft *.j2k) und JPM-Bilddateien gemäß
ISO 15444-6 (meist *.jpm) werden nicht unterstützt.
GIF-Bilder. PDFlib unterstützt alle GIF-Varianten (insbesondere GIF 87a und 89a) mit
interlaced und non-interlaced Pixeldaten sowie jede Palettengröße. GIF-Bilder werden im-
mer mit Flate-Kompression komprimiert.
TIFF-Bilder. PDFlib verarbeitet die meisten TIFF-Bilder im Pass-Through-Modus. PDFlib

unterstützt TIFF-Bilder folgender Varianten:

> Kompressionsverfahren: nicht komprimiert, CCITT (Gruppe 3, Gruppe 4 und RLE),
ZIP (=Flate) und PackBits (=RunLength). Diese Varianten werden im Pass-Through-
Modus verarbeitet; andere Varianten, so wie LZW und JPEG, werden dekomprimiert.
> Farbe: schwarzweiß, Graustufen, RGB, CMYK, CIELab und YCbCr; ein gegebenenfalls
in der Datei vorhandener Alphakanal oder eine Maske werden ignoriert.
> TIFF-Dateien, die aus mehreren Bildern bestehen (siehe Abschnitt 5.1.5, »Mehrseitige
Bilddateien«, Seite 154)
> Die Farbtiefe muss bei 1, 2, 4 oder 8 Bit pro Farbwert liegen. Im PDF-1.5-Modus bleibt
im Pass-Through-Modus eine Farbtiefe von 16 Bit meist erhalten, bei manchen Bild-
dateien (ZIP-Kompression mit »Little Endian«-Bytereihenfolge (Intel) und indizier-
ten 16-Bit-Bildern) wird sie aber auf 8 Bit reduziert.
TIFF-Bilder mit mehreren Streifen (multi-strip) werden zu mehreren Bildern in der PDF-
Datei konvertiert, die genau wie das Original aussehen, aber mit dem TouchUp-
Objektwerkzeug getrennt selektiert werden können. Diese Art von TIFF-Bildern lässt
sich mit dem Befehlszeilenprogramm tiffcp aus dem TIFFlib-Paket1 in Bilder mit einem
Streifen (»single-strip«) umwandeln. Das Tool ImageMagick2 erzeugt prinzipiell single-
strip TIFF-Bilder.
PDFlib interpretiert normalerweise das orientation-Tag, mit dem in TIFF-Dateien die
gewünschte Bildorientierung festgelegt wird. Durch Setzen der Option ignoreorientation
auf true kann PDFlib angewiesen werden, dieses Tag zu ignorieren (was in vielen An-
wendungen der Fall ist). Manche TIFF-Eigenschaften (zum Beispiel Schmuckfarbe) und
bestimmte Merkmalskombinationen (zum Beispiel CMYK-Bilder mit Maske) werden
nicht unterstützt. TIFF-Bilder mit JPEG-Kompression werden zwar generell unterstützt,
manche so genannte Old-Style-Varianten sind davon jedoch ausgenommen.
BMP-Bilder. BMP-Bilder können nicht im Pass-Through-Modus bearbeitet werden.

PDFlib unterstützt folgende Varianten von BMP-Bildern:
> BMP-Version 2 und 3
> Farbtiefe von 1, 4 und 8 Bit pro Komponente, einschließlich 3 x 8 = 24 Bit TrueColor.
16-Bit-Bilder werden als 5+5+5 behandelt (1 Bit wird nicht genutzt). 32-Bit-Bilder wer-
den als 3 x 8-Bit-Bilder behandelt (die übrigen 8 Bit werden ignoriert).
> schwarzweiß und RGB-Farbe (indiziert oder direkt)
> unkomprimiert sowie 4-Bit- und 8-Bit-RLE-Kompression
> PDFlib spiegelt keine Bilder, deren Pixel in »Bottom-Up«-Reihenfolge gespeichert
sind (dabei handelt es sich um eine in BMP selten genutzte Funktion, die von Anwen-
dungen nicht einheitlich interpretiert wird).
CCITT-Bilder. Mit Gruppe 3 oder Gruppe 4 komprimierte Bilddaten werden prinzipiell

im Pass-Through-Modus verarbeitet. Beachten Sie dabei, dass sich die Bezeichnung
CCITT-Bilder auf mit CCITT komprimierte Rohbilddaten bezieht und nicht auf TIFF-Datei-
en mit CCITT-Kompression. Mit CCITT komprimierte Rohbilddaten werden in Anwen-
dungen für Endbenutzer normalerweise nicht unterstützt und können nur mit Faxsoft-
ware generiert werden. Da PDFlib keine CCITT-Bilder analysieren kann, muss der Client
alle relevanten Bildparameter an PDF_load_image( ) übergeben.
1. Siehe www.libtiff.org
2. Siehe www.imagemagick.org

Rohdaten. Nicht komprimierte Bilddaten (Rohbilddaten) können in besonderen Fäl-
len sinnvoll sein. Die Art des Bildes leitet sich aus der Anzahl der Farbkomponenten ab:
Eine Komponente impliziert ein Graustufenbild, drei Komponenten ein RGB-Bild und
vier Komponenten ein CMYK-Bild.
5.1.3 Bildmasken und Transparenz

Transparenz in PDF. PDF unterstützt verschiedene Transparenzfunktionen, die auch in
PDFlib implementiert sind:
> Maskierung nach Position: Ein Bild kann die Information »drucke den Vordergrund,
aber nicht den Hintergrund« enthalten. Dieses Verfahren wird als 1-Bit-Bildmaske
realisiert und oft in Bildern für Kataloge verwendet.
> Maskierung nach Farbwert: Pixel einer bestimmten Farbe werden nicht gezeichnet,
stattdessen scheint der vorher gezeichnete Teil der Seite durch (»ignoriere alle blau-
en Bildpixel«). In der Fernseh- und Videotechnik wird die Farbmaskierung auch als
Bluescreen-Verfahren bezeichnet. Der bekannteste Einsatzzweck in diesem Bereich
ist die Einblendung der Wetterkarte hinter dem Fernsehmeteorologen.
> Seit PDF 1.4 gibt es Alpha-Kanäle oder Transparenzmasken. Diese können für einen
nahtlosen Übergang zwischen Vorder- und Hintergrund oder für halbtransparente
Objekte (»mische das Bild mit dem Hintergrund«) verwendet werden. Transparenz-
masken werden durch 1-Komponenten-Bilder mit 1 bis 8 Bit pro Pixel dargestellt.
PDFlib unterstützt drei Arten der Transparenzinformation: implizite Transparenz, ex-

plizite Transparenz und Bildmasken.
Hinweis Die Maske muss die selbe Ausrichtung wie das zugrundeliegende Bild haben; anderenfalls wird
sie zurückgewiesen. Da die Ausrichtung vom Dateiformat des Bildes sowie anderen Faktoren
abhängt, ist sie nicht einfach zu entdecken. Aus diesem Grund ist es empfehlenswert, die Maske
und das Bild mit derselben Software in demselben Dateiformat zu erstellen.
Implizite Transparenz. Im impliziten Fall wird die Transparenzinformation aus einer

externen Bilddatei berücksichtigt, sofern das Bilddateiformat Transparenz oder einen
Alphakanal unterstützt (was nicht auf alle Formate zutrifft). Transparenzinformationen
werden in folgenden Dateiformaten erkannt:
> GIF-Bilder können einen einzelnen transparenten Farbwert enthalten, der von
PDFlib berücksichtigt wird.
> PNG-Bilder können mehrere Varianten von Transparenzinformation oder einen
vollständigen Alphakanal enthalten. In PDFlib bleiben einzelne transparente Farb-
werte erhalten. Liegen mehrere Farbwerte in einem beigefügten Alphakanal vor,
wird nur der erste mit einem Alphawert unter 50 Prozent verwendet. Ein vollständi-
ger Alphakanal wird ignoriert.
Explizite Transparenz. Im expliziten Fall sind zwei Schritte erforderlich, die jeweils
auch Bildoperationen erfordern. Zuerst muss ein Bild zur späteren Verwendung als
Transparenzmaske vorbereitet werden. Dies lässt sich durch Öffnen des Bildes mit der
Option mask bewerkstelligen. In PDF 1.3, wo nur 1-Bit-Masken unterstützt werden, ist
diese Option zwingend erforderlich; in PDF 1.4 dagegen ist sie optional. Die folgende Art
von Bildern kann zum Anlegen einer Maske verwendet werden:
> PNG-Bilder
> TIFF-Bilder (nur single-strip)

> Bildrohdaten
Überall dort, wo sich in der Maske der Pixelwert o (null) befindet, wird der entsprechen-
de Bereich des maskierten Bildes gezeichnet, während der Wert 1 den Hintergrund
durchscheinen lässt. Sind mehr als 1 Bit pro Pixel vorhanden, mischen die zwischenlie-
genden Werte das Vordergrundbild mit dem Hintergrund und bewirken so einen Trans-
parenzeffekt. Im zweiten Schritt wird diese Maske auf ein anderes Bild angewandt, das
über eine der Bildfunktionen bezogen wurde:
mask = PDF_load_image(p, "png", maskfilename, 0, "mask");
if (mask == -1)
return;
sprintf(optlist, "masked %d", mask);
image = PDF_load_image(p, type, filename, optlist)
if (image == -1)
return;
PDF_fit_image(p, image, x, y, "");
Beachten Sie die unterschiedliche Verwendung der Optionsliste für PDF_load_image( ):

mask zur Maskendefinition und masked zur Anwendung einer Maske auf ein anderes
Bild.
Bild und Maske können unterschiedliche Pixelmaße aufweisen; die Maske wird auto-
matisch auf die Bildgröße skaliert.
Hinweis PDFlib konvertiert »multi-strip« TIFF-Bilder in mehrere PDF-Bilder, die dann einzeln maskiert
würden. Da dies in der Regel aber nicht beabsichtigt ist, wird diese Art von Bildern sowohl als
Maske als auch zur Maskierung abgelehnt. Außerdem ist es wichtig, implizite und explizite Fäl-
le nicht zu vermischen, das heißt keine Bilder mit transparenten Farbwerten als Maske zu ver-
wenden.
Bildmasken. Bildmasken sind Bilder mit einer Bittiefe von 1 (Bitmaps), in denen die
Bits mit dem Wert 0 als transparent behandelt werden: Der auf der Seite vorhandene In-
halt scheint durch die transparenten Bestandteile des Bildes hindurch. Pixel mit dem
Wert 1 dagegen werden mit der aktuellen Füllfarbe eingefärbt. Die folgenden Arten von
Bildern können als Bildmasken verwendet werden:
> PNG-Bilder
> TIFF-Bilder
> JPEG-Bilder (nur als Transparenzmasken, siehe unten)
> BMP; beachten Sie, dass Ausrichtung von BMP-Bildern anders als bei den übrigen
Bildtypen ist. BMP-Bilder müssen deshalb erst an der X-Achse gespiegelt werden, be-
vor Sie als Maske einsetzbar sind.
> Bildrohdaten
Bildmasken werden einfach mit der Option mask geöffnet und auf der Seite platziert,
nachdem die gewünschte Füllfarbe gesetzt wurde:
mask = PDF_load_image(p, "tiff", maskfilename, 0, "mask");
PDF_setcolor(p, "fill", "rgb", (float) 1, (float) 0, (float) 0, (float) 0);
if (mask != -1) {
PDF_fit_image(p, mask, x, y, "");
}

Wenn Sie eine Farbe auf ein Bild anwenden möchten, ohne die Bits mit dem Wert 0
transparent zu machen, müssen Sie die Funktion zum Einfärben verwenden (siehe Ab-
schnitt 5.1.4, »Einfärben von Bildern«, Seite 153).
Transparenzmasken. Transparenzmasken erweitern das Konzept der Bildmasken auf

Masken mit mehr als 1 Bit. Sie wurden in PDF 1.4 eingeführt und mischen ein Bild mit ei-
nem vorhandenen Hintergrund. PDFlib akzeptiert alle Arten von einkanaligen (Grau-
stufen-) Bildern als Transparenzmasken. Sie sind wie Bildmasken einsetzbar, sofern die
PDF-Ausgabe mindestens zu PDF 1.4 kompatibel ist.
Ignorieren von Transparenz. Manchmal ist es wünschenswert, alle Transparenzinfor-

mation in einer Bilddatei zu ignorieren. Die Antialiasing-Funktion von Acrobat zum
Beispiel (auch Glätten genannt) wird nicht auf 1-Bit-Bilder angewandt, die nur die Far-
ben schwarz und transparent besitzen. Aus diesem Grund können importierte Bilder
mit feinen Details (zum Beispiel gerasterter Text) hässlich aussehen, wenn die Transpa-
renzinformation ins generierte PDF übernommen wird. Um dieses Problem zu lösen,
kann die automatische Interpretation von Transparenzinformationen in PDFlib beim
Öffnen der Bilddatei mit der Option ignoremask deaktiviert werden:
image = PDF_load_image(p, "gif", filename, 0, "ignoremask");
5.1.4 Einfärben von Bildern

Ähnlich wie Bildmasken, wo eine Farbe auf die nicht-transparenten Bestandteile eines
Bildes angewandt wird, unterstützt PDFlib das Einfärben eines Bildes mit einer
Schmuckfarbe. Diese Funktion ist bei Schwarzweiß- oder Graustufenbildern in den fol-
genden Formaten möglich:
> BMP
> PNG
> JPEG
> TIFF
> GIF
Bei Bildern, die mit RGB-Farbpalette arbeiten, ist ein Einfärben nur sinnvoll, wenn die
Palette ausschließlich Graustufenwerte enthält und der Palettenindex dem Graustufen-
wert entspricht.
Um ein Bild mit einer Schmuckfarbe einzufärben, müssen Sie beim Laden des Bildes
den Parameter colorize und ein Handle für die gewünschte Schmuckfarbe übergeben,
welches von PDF_makespotcolor( ) zurückgegeben wurde:
PDF_setcolor(p, "both", "cmyk", 1, .79, 0, 0);
spot = PDF_makespotcolor(p, "PANTONE Reflex Blue CV", 0);
sprintf(optlist, "colorize %d", spot);
image = PDF_load_image(p, "tiff", "image.tif", 0, optlist)
if (image != -1) {
PDF_fit_image(p, image, x, y, "");
}

5.1.5 Mehrseitige Bilddateien
PDFlib unterstützt TIFF-Dateien, die aus mehr als einem Bild bestehen (so genannte
mehrseitige Dateien). Um mehrseitige TIFFs zu verwenden, wird PDF_load_image( ) mit
weiteren String- und numerischen Parametern aufgerufen:
image = PDF_load_image(p, "tiff", filename, 0, page 2");
Die Option page zeigt an, dass eine Datei mit mehreren Bildern verwendet werden soll.
Der letzte Parameter legt die Nummer des zu verwendenden Bildes fest, wobei das erste
Bild die Nummer 1 hat. Dieser Parameter kann so lange hochgesetzt werden, bis PDF_
load_image( ) den Wert -1 (bei imagewarning=false) zurückgibt, der anzeigt, dass keine
weiteren Bilder in der Datei vorhanden sind.
Mit einem Codefragment ähnlich dem Folgenden können Sie alle Bilder einer TIFF-
Datei in ein mehrseitiges PDF-Dokument konvertieren:
for (frame = 1; /* */ ; frame++) {
sprintf(optlist, "page %d", frame);
image = PDF_load_image(p, "tiff", filename, 0, optlist);
if (image == -1)
break;
PDF_begin_page(p, width, height);
PDF_fit_image(p, image, 0.0, 0.0, "");
PDF_end_page(p);
}
5.1.6 OPI-Unterstützung
Beim Laden eines Bildes können im Aufruf von PDF_load_image( ) weitere Informatio-
nen für OPI (Open Prepress Interface) Version 1.3 oder 2.0 übergeben werden. PDFlib ak-
zeptiert alle Standard-PostScript-Kommentare für OPI 1.3 und 2.0 als Optionen (nicht als
PDF-Schlüsselwörter!) und reicht die übergebenen OPI-Informationen unverändert an
die generierte PDF-Ausgabe weiter. Das folgende Beispiel ergänzt ein Bild um OPI-Infor-
mationen:
optlist13 =
"OPI-1.3 { ALDImageFilename grosse_datei.tif "
"ALDImageDimensions {400 561} "
"ALDImageCropRect {10 10 390 550} "
"ALDImagePosition {10 10 10 540 390 540 390 10} }";
image = PDF_load_image(p, "tiff", filename, 0, optlist13);
Hinweis Bei manchen OPI-Servern, wie zum Beispiel dem in Helios EtherShare, ist die OPI-Verarbeitung
für XObjects vom Typ Image, die PDFlib standardmäßig erzeugt, nicht sauber implementiert. In
solchen Fällen kann mit der Option template an PDF_load_image( ) die Generierung von XOb-
jects vom Typ Form erzwungen werden.

5.2 Import von PDF-Seiten mit PDI (PDF Import Library)
Hinweis Alle in diesem Abschnitt beschriebenen Funktionen setzen PDFlib+PDI voraus. Die PDF-Import-
bibliothek PDI ist nicht in PDFlib oder PDFlib Lite enthalten. PDI ist zwar in alle vorkompilierten
PDFlib-Editionen integriert, es ist aber ein eigener Lizenzschlüssel für PDI (oder für PPS, der PDI
enthält) erforderlich.
5.2.1 PDI-Funktionen und -Anwendungen

Wird PDFlib um die optionale PDF-Importbibliothek PDI ergänzt, können mit allen un-
terstützten Sprachbindungen auch Seiten vorhandener PDF-Dokumente verarbeitet
werden. Die PDI-Bibliothek enthält einen PDF-Parser und bereitet PDF-Seiten für einen
möglichst einfachen Einsatz mit PDFlib auf. Der Umgang mit importierten PDF-Seiten
unterscheidet sich vom Konzept her kaum von importierten Rasterbildern wie TIFF
oder PNG: Sie öffnen ein PDF-Dokument, wählen die zu importierende Seite und plat-
zieren sie auf einer Ausgabeseite. Dabei können Sie sie mit PDFlib-Transformations-
funktionen zum Verschieben, Skalieren, Drehen oder Scheren bearbeiten. Importierte
Seiten können anhand von PDFlib-Text- und Grafikfunktionen problemlos mit neuem
Inhalt kombiniert werden, nachdem sie auf der Ausgabeseite platziert wurden (man
kann sich die importierte Seite als Hintergrund für neuen Inhalt vorstellen). Mit PDFlib
und PDI lassen sich problemlos folgende Aufgaben erledigen:
> zwei oder mehr Seiten aus verschiedenen PDF-Dokumenten überlagern (um zum
Beispiel Briefpapier mit variablen Inhalten zu kombinieren)
> PDF-Kleinanzeigen in vorhandenen Dokumenten platzieren
> den sichtbaren Bereich einer PDF-Seite beschneiden, um unerwünschte Elemente
(zum Beispiel Schnittmarken) zu verbergen oder Seiten zu skalieren
> mehrere Seiten zum Druck auf einem Bogen montieren
> aus mehreren PDF/X-kompatiblen Dokumenten eine neue PDF/X-Datei erzeugen
> Text (zum Beispiel Kopfzeilen, Fußzeilen, Stempel oder Seitenzahlen) oder Bilder
(zum Beispiel ein Firmenlogo) zu vorhandenen PDF-Seiten hinzufügen
> alle Seiten von einem Eingabedokument in ein Ausgabedokument kopieren und
Barcodes auf den Seiten platzieren
Um eine PDF-Hintergrundseite zu platzieren und mit dynamisch generierten Daten zu

füllen (zum Beispiel Serienbriefe, personalisierte PDF-Dokumente im Web oder Ausfül-
len von Formularen), empfehlen wir den Einsatz von PDI in Kombination mit PDFlib-
Blöcken (siehe Kapitel 6).
5.2.2 Einsatz von PDI-Funktionen mit PDFlib

Allgemeine Hinweise. Sie müssen unbedingt beachten, dass PDI nur den eigentlichen
Seiteninhalt importiert und keinerlei gegebenenfalls im PDF-Dokument vorhandene
Hypertext-Elemente (wie zum Beispiel Sound, Movies, eingebettete Dateien, Hypertext-
verknüpfungen, Formularfelder, Lesezeichen, Piktogramme oder Notizen). Solche Hy-
pertext-Funktionen lassen sich mit den entsprechenden PDFlib-Funktionen generieren.
Außerdem werden PDFlib-Blöcke beim Importieren der Seite ignoriert.
Ferner können Sie einzelne Elemente der importierten Seite nicht in PDFlib-Funktio-
nen weiterverwenden. So lassen sich Schriften aus importierten Dokumenten nicht für
andere Inhalte benutzen, da alle benötigten Schriften in PDFlib konfiguriert sein müs-
sen. Enthalten mehrere importierte Dokumente eingebettete Fontdaten derselben
Schrift, so werden die mehrfach vorhandenen Fonts von PDI nicht entfernt. Fehlen die
Schriften dagegen in einem importierten PDF, dann fehlen sie auch in der generierten
PDF-Ausgabe. Zur Optimierung sollten Sie das importierte Dokument so lange offen
halten, wie Sie noch Seiten daraus benötigen, damit dieselben Schriften nicht mehrmals
im Ausgabedokument eingebettet werden.
PDI lässt Farbinformationen des importierten PDF-Dokuments unverändert. Enthält
das PDF zum Beispiel ICC-Farbprofile, so werden diese auch in das generierte Ausgabe-
dokument übernommen.
PDFlib platziert importierte PDF-Seiten auf der Ausgabeseite mittels der Template-
Funktion. Da einige PDF-Programme von Drittanbietern die Template-Funktion nicht
korrekt unterstützen, kann es in von Acrobat verschiedenen Umgebungen gewisse Ein-
schränkungen geben (siehe Abschnitt 3.2.4, »Templates«, Seite 67).
Von PDFlib generierte Ausgabe, die importierte Seiten aus anderen PDF-Dokumen-
ten enthält, kann auch ein weiteres Mal mit PDFlib/PDI bearbeitet werden. Aufgrund
von Einschränkungen beim PostScript-Druck sollte die Verschachtelung nicht über
mehr als zehn Ebenen gehen.
Codefragmente zum Importieren von PDF-Seiten. Der Umgang mit Seiten aus vorhan-
denen PDF-Dokumenten ist mit sehr einfach strukturiertem Code möglich. Das folgen-
de Fragment öffnet eine vorhandene Dokumentseite und kopiert den Seiteninhalt auf
eine neue Seite des PDF-Ausgabedokuments (das vorher geöffnet werden muss):
int doc, page, pageno = 1;
char *filename = "input.pdf";
...
doc = PDF_open_pdi(p, filename, "", 0);

if (doc == -1) {
printf("PDF-Eingabedatei '%s' kann nicht geöffnet werden\n", filename);
exit(1);
}
page = PDF_open_pdi_page(p, doc, pageno, "");
if (page == -1) {
printf("Seite %d der PDF-Datei '%s' ist nicht zu öffnen\n", pageno, filename);
exit(2);
}
/* Seitengröße irrelevant, wird mit der Option adjustpage geändert */

PDF_begin_page(p, 20, 20);
PDF_fit_pdi_page(p, page, 0, 0, "adjustpage");
PDF_close_pdi_page(p, page);
...mit PDFlib-Funktionen weiteren Seiteninhalt hinzufügen...
PDF_end_page(p);
PDF_fit_pdi_page( ) erhält als letztes Argument eine Optionsliste, die zahlreiche Optio-
nen zur Positionierung, Skalierung und Drehung der importierten Seite unterstützt.
Weitere Informationen hierzu finden Sie in Abschnitt 5.3, »Platzieren von Bildern und
importierten PDF-Seiten«, Seite 159.
Abmessungen importierter PDF-Seiten. Importierte PDF-Seiten werden im Prinzip wie

importierte Rasterbilder behandelt und können mit PDF_fit_pdi_page( ) auf der Ausga-

beseite platziert werden. Die PDI-Bibliothek importiert die Seite standardmäßig genau
so, wie sie in Acrobat angezeigt wird:
> Eine eventuelle Beschneidung der Seite bleibt erhalten (technisch ausgedrückt: Ist
eine Größenangabe für die CropBox vorhanden, dann zieht die PDI-Bibliothek diese
der MediaBox-Angabe vor; siehe Abschnitt 3.2.2, »Höchstwerte für Seiten und Koor-
dinaten«, Seite 64).
> Eine eventuell auf die Seite angewandte Drehung bleibt erhalten.
Alternativ dazu können Sie PDI mit der Option pdiusebox explizit anweisen, zur Ermitt-
lung der Größe der importierten Seite eine der Angaben MediaBox, CropBox, BleedBox,
TrimBox oder ArtBox zu verwenden, falls vorhanden (Einzelheiten hierzu finden Sie in
Tabelle 8.46).
Viele wichtige Eigenschaften, wie zum Beispiel die Seitengröße einer importierten
PDF-Seite, alle Box-Angaben oder die Anzahl der Seiten in einem Dokument können
über PDFlib-Parameter abgefragt werden. Alle relevanten Parameter sind in Tabelle 8.45
und Tabelle 8.46 aufgeführt. Diese Eigenschaften können bei Entscheidungen über die
Platzierung importierter PDF-Seiten auf der Ausgabeseite hilfreich sein. Auch die in Ab-
schnitt 5.3.1, »Skalierung, Ausrichtung und Drehung«, Seite 159, beschriebenen Funkti-
onsaufrufe können zur Skalierung importierter PDF-Seiten herangezogen werden.
Importierte PDF-Seiten mit Layern. In Acrobat 6 (PDF 1.5) wurde die Layer-Funktion
eingeführt (der technische Begriff ist optional content). PDI ignoriert alle in einer Datei
vorhandenen Layer-Informationen. Alle in der importierten Seite vorhandenen Layer
einschließlich der unsichtbaren sind in der generierten Ausgabe sichtbar.
Importiertes PDF mit OPI-Informationen. Im importierten PDF vorliegende OPI-Infor-

mationen werden unverändert in die Ausgabe übernommen.
5.2.3 Importierbare PDF-Dokumente

PDI verarbeitet in der Regel problemlos alle Arten von PDF-Dokumenten, die sich auch
in Acrobat öffnen lassen, unabhängig von der PDF-Versionsnummer oder den im Doku-
ment verwendeten Funktionen. Um Seiten aus verschlüsselten Dokumenten (die Be-
rechtigungseinstellungen oder Kennwort verwenden) zu importieren, muss das zuge-
hörige Hauptkennwort übergeben werden.
Nur selten tritt der Fall auf, dass PDI ein ganzes PDF-Dokument oder eine einzelne
Seite im Dokument zurückweist.
Scheitert der Versuch, ein PDF-Dokument oder eine Seite zu importieren, geben PDF_
open_pdi( ) und PDF_open_pdi_page( ) standardmäßig einen Fehlercode zurück. Mit PDF_
get_errmsg( ) können Sie genauere Informationen zur Fehlerursache abfragen. Alterna-
tiv dazu setzen Sie die Option oder den Parameter pdiwarning auf true. Dies führt zu ei-
ner Exception, wenn das Dokument nicht geöffnet werden kann:
PDF_set_parameter(p, "pdiwarning", "true"); /* PDI-Warnungen aktivieren */
PDF_open_pdi( ) und PDF_open_pdi_page( ) lösen dann eine Exception aus, wobei der Text
der Exception eine genauere Fehlerbeschreibung enthält. Folgende Arten von Doku-
menten können mit PDI nicht importiert werden:
> PDF-Dokumente, die eine höhere PDF-Versionsnummer aufweisen als die aktuell
generierte PDF-Ausgabe. Der Grund besteht darin, dass PDFlib nach dem Import
eines solchen Dokuments nicht mehr gewährleisten könnte, dass die Ausgabe auch
tasächlich der geforderten PDF-Version entspricht. Lösung: Setzen Sie die Version
der PDF-Ausgabe mit der Option compatibility in PDF_begin_document( ) entspre-
chend herauf.
> PDF-Dokumente mit einer PDF/X-Kompatibilitätsstufe, die nicht zum aktuellen
Ausgabedokument passt.
> Dateien mit beschädigter Querverweistabelle. Solche Dokumente erkennen Sie an
der Acrobat-Warnung Diese Datei ist beschädigt, wird jedoch repariert. Lösung: Öffnen
Sie die Datei in Acrobat und speichern Sie sie erneut.
Außerdem werden die folgenden Arten von PDF-Dokumenten abgelehnt; aus ihnen las-
sen sich keine Seiten importieren, mit der Option infomode gleich true können aber In-
formationen abgefragt werden:
> Verschlüsselte PDF-Dokumente ohne passendes Passwort.
> Tagged PDF, wenn die Option tagged in PDF_begin_document( ) gleich true ist.

5.3 Platzieren von Bildern und importierten PDF-Seiten
Die Funktion PDF_fit_image( ) zur Platzierung von Rasterbildern und Templates sowie
die Funktion PDF_fit_pdi_page( ) zur Platzierung importierter PDF-Seiten bieten eine
Fülle von Optionen zur Platzierung auf der Seite. Diese werden im Folgenden anhand ei-
niger häufig vorkommenden Anwendungsfälle erläutert. Eine vollständige Auflistung
aller Optionen finden Sie in Tabelle 8.41.
Die Einbettung von Rasterbildern mit PDFlib ist einfach zu bewerkstelligen. Die Bild-
datei muss zunächst mit PDF_load_image( ) geladen werden. Diese Funktion gibt ein
Image-Handle zurück, das zusammen mit Positionierungs- und Skalierungsangaben in
PDF_fit_image( ) verwendet werden kann.
Die Einbettung importierter PDF-Seiten erfolgt analog. Die PDF-Seite muss mit PDF_
open_pdi_page( ) geöffnet werden, um ein Seiten-Handle zu erhalten, das in PDF_fit_pdi_
page( ) verwendet werden kann. Dabei stehen dieselben Positionierungs- und Skalie-
rungsoptionen wie für Rasterbilder zur Verfügung.
Alle in diesem Abschnitt erläuterten Beispiele gelten gleichermaßen für Rasterbil-
der, Templates und importierte PDF-Seiten. Die Codebeispiele beziehen sich zwar aus-
schließlich auf Rasterbilder, unsere Beschreibung bezieht sich aber ganz generell auf die
Platzierung von Objekten. Beachten Sie, dass vor dem Aufruf einer fit-Funktion eine der
Funktionen PDF_load_image( ) oder PDF_open_pdi( ) und PDF_open_pdi_page( ) ausge-
führt werden muss. Der Einfachheit halber werden diese Aufrufe hier nicht wiederholt.
5.3.1 Skalierung, Ausrichtung und Drehung

Einfache Platzierung. Beginnen wir mit dem einfachsten Fall (siehe Abbildung 5.1). Ein
Objekt wird an einer bestimmten Position in Originalgröße platziert:
PDF_fit_image(p, image, 80, 100, "");
In diesem Codefragement wird das Objekt mit der linken unteren Ecke am Punkt (80,
100) des Benutzerkoordinatensystems platziert. Diesen Punkt bezeichnen wir als Refe-
renzpunkt. Die Optionsliste (der letzte Funktionsparameter) ist leer, das heißt das Ob-
jekt wird in Originalgröße am angegebenen Punkt positioniert.
Abb. 5.1 Abb. 5.2

Einfache Platzierung Platzierung mit Skalierung

Zentrieren eines Bildes in einem Rechteck. Um ein Bild in einem vordefinierten Recht-
eck zu zentrieren, brauchen Sie keinerlei Berechnungen durchzuführen, sondern ver-
wenden einfach folgende Optionen:
PDF_fit_image(p, image, 80, 100, "boxsize {200 100} position 50 fitmethod meet");
Platzierung mit Skalierung. Auch einfach verwendbar ist folgende Variation (siehe Ab-
bildung 5.2). Wir positionieren wie oben, variieren aber die Skalierung des Objekts:
PDF_fit_image(p, image, 80, 100, "scale 0.5");
Dieses Codefragment platziert das Objekt mit der linken unteren Ecke am Punkt (80,
100) des Benutzerkoordinatensystems. Das Objekt wird außerdem in x- und y-Richtung
um den Faktor 0,5 skaliert, das heißt auf 50% verkleinert.
Platzierung mit Ausrichtung. Im nächsten Codefragment richten wir obiges Objekt zu-
sätzlich nach Westen aus (siehe Abbildung 5.3).
PDF_fit_image(p, image, 80, 100, "scale 0.5 orientate west");
Dieses Codefragment richtet das Objekt nach Westen aus (90 Grad gegen den Uhrzeiger-
sinn) und verschiebt dann die linke untere Ecke des gedrehten Objekts auf den Refe-
renzpunkt (x, y). Das Objekt wird »in sich gedreht«.
Platzierung mit Drehung. Die Drehung eines Objekts (siehe Abbildung 5.4) vollzieht
sich ganz ähnlich wie die Ausrichtung. Sie wirkt sich aber nicht nur auf das platzierte
Objekt, sondern auf das ganze Koordinatensystem aus. Vor der Platzierung des Objekts
wird das Koordinatensystem im Referenzpunkt (x, y) um 90 Grad gegen den Uhrzeiger-
sinn gedreht. In (x, y) liegt dann die rechte untere Ecke des gedrehten Objekts (also die
linke untere Ecke des nicht gedrehten Objekts). Der Funktionsaufruf sieht in diesem Fall
wie folgt aus:
PDF_fit_image(p, image, 80, 100, "scale 0.5 rotate 90");
Da hier keine Verschiebung stattfindet, wird das Bild teilweise aus der Seite hinausge-
dreht.
Abb. 5.3 Abb. 5.4

Platzierung mit Platzierung
Ausrichtung mit Drehung

Vergleich zwischen Ausrichtung und Drehung. Ausrichtung und Drehung sind sich
zwar recht ähnlich, weisen aber dennoch einige Unterschiede auf, derer Sie sich bewusst
sein sollten. Abbildung 5.5 und Abbildung 5.6 zeigen den prinzipiellen Unterschied zwi-
schen den Optionen orientate und rotate.
> Bei der Option orientate wird das Objekt um den Referenzpunkt (x, y) herum gedreht
und dann verschoben. Diese Option unterstützt die Richtungsschlüsselwörter north,
east, west und south.
> Bei der Option rotate wird das Bild ohne jede Verschiebung um den Referenzpunkt
(x, y) herum gedreht. Diese Option unterstützt beliebige Drehwinkel. Diese müssen
numerisch in Grad angegeben werden (ein vollständiger Kreis hat 360 Grad).
5.3.2 Anpassen der Seitengröße

Im nächsten Beispiel (siehe Abbildung 5.7) passen wir die Seitengröße automatisch an
die Bildgröße an. Dies kann bei der Archivierung von Bildern im PDF-Format nützlich
sein. Der Referenzpunkt (x, y) wird verwendet, um festzulegen, ob die Seite exakt so groß
wie das Objekt oder etwas größer oder kleiner angelegt wird. Bei einer Vergrößerung der
Seite erhalten wir einen Rand um das Bild; ist die Seite kleiner als das Bild, reicht das
Bild über den Seitenrand hinaus, das heißt auf jeder Seite wird ein Teil des Bildes abge-
schnitten. Beginnen wir mit der exakten Größenanpassung:
PDF_fit_image(p, image, 0, 0, "adjustpage");
Das folgende Codefragment legt die Seite in x- und y-Richtung um 40 Punkt größer an
als das Objekt. Man erhält eine Umrandung um das Objekt:
PDF_fit_image(p, image, 40, 40, "adjustpage");
Das folgende Codefragment wiederum legt die Seite in x- und y-Richtung um 40 Punkt
kleiner an als das Objekt. Das Objekt wird an den Seitenrändern beschnitten. Innerhalb
des Bildes bleibt so ein Rand von 40 Punkt Breite unsichtbar:
PDF_fit_image(p, image, -40, -40, "adjustpage");
Abb. 5.5
Option orientate
Abb. 5.6
Option rotate

Neben der Platzierung mit Hilfe von x- und y-Koordinaten, die den Abstand des Objekts
vom Seitenrand oder im allgemeinen Fall die Koordinatenachsen definieren, kann zu-
sätzlich ein virtueller Rahmen (die so genannte Box) festgelegt werden, in die sich das
Objekt auf verschiedene Art einpassen lässt. Dazu stehen zusätzlich die Optionen
boxsize, fitmethod und position zur Verfügung.
Einpassen eines Objekts in eine Box. Betrachten wir zur Anwendung der Box zunächst
die Ausgabe eines Firmen-Logos auf der Seite rechts oben (siehe Abbildung 5.8). Die Ab-
messungen des Rechtecks, die das Logo ausfüllen soll, sind bekannt. Man weiß jedoch
nicht, wie das Logo skaliert werden muss, um das Rechteck unter Beibehaltung seiner
Proportionen möglichst gut auszufüllen (das Verhältnis von Breite zu Höhe soll nicht
verändert werden). Folgendes Fragment löst diese Aufgabe:
PDF_fit_image(p, image, 350, 700, "boxsize {200 100} position 0 fitmethod meet");
Dieses Codefragment platziert am Punkt (350, 700) die linke untere Ecke einer Box, die
200 Punkt breit und 100 Punkt hoch ist (boxsize {200 100}). Das Objekt wird mit der lin-
ken unteren Ecke in der Box links unten platziert (position 0) und so weit skaliert, bis es
in der Höhe und/oder der Breite exakt in die Box passt (fitmethod meet).
Dieses Konzept bietet ein breites Spektrum an Variationsmöglichkeiten. So kann mit
der Option position festgelegt werden, welcher Punkt innerhalb des Objekts als Refe-
renzpunkt (als prozentualer Anteil der Höhe bzw. der Breite) verwendet werden soll. Die
Option position legt auch den Referenzpunkt der Box fest. Sind die prozentualen Anga-
ben für Höhe und Breite gleich, so genügt es, nur einen Wert anzugeben. So kann mit
position 50 zum Beispiel der Mittelpunkt des Objekts sowie der Box als Referenzpunkt
für die Platzierung gewählt werden.
Beschneiden eines Objekts beim Einpassen in die Box. Durch zusätzliche Variation der
Option fitmethod können wir das Objekt so beschneiden, dass es genau in die Box passt
(siehe Abbildung 5.9). In diesem Fall findet keine Skalierung statt.
PDF_fit_image(p, image, 50, 80, "boxsize {100 400} position 50 fitmethod clip");
Dieses Codefragment platziert am Punkt (50, 80) eine Box, die 100 Punkt breit und 400
Punkt hoch ist (boxsize {100 400}). Das Objekt wird in der Box mittig (position 50) in Origi-
nalgröße platziert und beschnitten, wenn es über den Boxrand hinausreicht (fitmethod
clip).
Abb. 5.7
Anpassen der Seitengröße. Von links nach
rechts: exakt, vergrößert, verkleinert.

Abb. 5.9
Abb. 5.8 Beschneiden eines
Einpassen eines Objekts beim
Objekts in die Box Einpassen in die Box
Anpassen eines Objekts an die Seite. Ein Objekt lässt sich problemlos an eine vorgege-
bene Seitengröße anpassen, indem die Seite als Box zur Platzierung des Objekts verwen-
det wird. Das folgende Codefragment zeigt ein Beispiel für eine A4-Seite, deren Größe
595 x 842 Punkt beträgt:
PDF_fit_image(p, image, 0, 0, "boxsize {595 842} position 0 fitmethod slice");
In diesem Codefragment wird eine Box in der linken unteren Ecke platziert, die genau
die Größe einer A4-Seite besitzt. Das Objekt wird links unten in die Box gelegt und so
weit proportional skaliert, bis es die Box und somit die Seite komplett ausfüllt. Wo das
Objekt über die Ränder der Box hinausreicht, wird es beschnitten. Man beachte, dass
hier im Gegensatz zu fitmethod clip mit der Option fitmethod slice eine Skalierung des
Objekts durchgeführt wird. Natürlich ließen sich auch hier die Optionen position und
fitmethod variieren.
Einpassen eines Logos in die Seite. Wie erstellen wir das gedrehte Firmen-Logo in Ab-
bildung 5.10? Das Logo ist um 90 Grad gegen den Uhrzeigersinn gedreht, beginnt in der
linken unteren Ecke und deckt die volle Seitenhöhe ab:
PDF_fit_image(p, image, 0, 0, "boxsize {595 842} orientate west fitmethod meet");
Abb. 5.10
Einpassen eines
Objekts in die Seite

Der Referenzpunkt ist (0, 0) und die Drehoperation ist orientate west. Damit das gedreh-
te Logo die gesamte Seitenhöhe einnimmt, bemessen wir die Höhe der Box so groß wie
die Seitenhöhe (842) und definieren zudem eine zu große Breite (595). Die Proportionen
des Logos sollen sich beim Einpassen in die Box nicht verändern. Wir wählen also
fitmethod meet.

6 Variable Daten und Blöcke
PDFlib bietet einen PDF-Workflow zur Verarbeitung variabler Daten auf Basis von Tem-
plates. Mit Hilfe des Blockkonzepts können importierte Seiten mit variablen Mengen
von ein- oder mehrzeiligem Text, Rasterbildern oder PDF-Vektorgrafik angereichert
werden, die aus externen Quellen bezogen werden. Damit lassen sich problemlos An-
wendungen implementieren, die individualisierte PDF-Dokumente erfordern, zum Bei-
spiel:
> Serienbriefe
> flexible Erstellung personalisierter Massenbriefe
> Berichtswesen und Rechnungserstellung
> Personalisierung von Visitenkarten
Hinweis Zur Blockverarbeitung ist der PDFlib Personalization Server (PPS) erforderlich. PPS ist zwar in al-
len kommerziellen PDFlib-Paketen enthalten, Sie müssen dafür aber einen eigenen Lizenz-
schlüssel erwerben; ein Lizenzschlüssel für PDFlib oder PDFlib+PDI reicht nicht aus. Außerdem
ist das Block-Plugin für Adobe Acrobat erforderlich, um Blöcke in PDF-Templates interaktiv
anzulegen.
6.1 Installation des Block-Plugins

Das Block-Plugin sowie das Plugin zur Konvertierung von Formularfeldern funktionie-
ren nur mit der Vollversion von Acrobat 5, mit Acrobat 6/7 Standard und Acrobat 6/7
Professional unter Windows und auf dem Mac. Mit Acrobat 6/7 Elements und Acrobat
Reader/Adobe Reader sind sie nicht einsetzbar.
Hinweis Das Plugin enthält die Benutzeroberfläche in verschiedenen Sprachversionen und verwendet,
soweit möglich, dieselbe Sprache wie Acrobat selbst. Wird diese Sprache vom Plugin nicht un-
terstützt, verwendet es stattdessen Englisch.
Installation der Block-Plugins für Acrobat 5/6/7 unter Windows. Zur Installation des
Block-Plugins sowie des Plugins zur Konvertierung von PDF-Formularfeldern in Acrobat
5, 6 oder 7 kopieren Sie die Plugin-Dateien in ein Unterverzeichnis des Acrobat-Plugin-
Verzeichnisses. Dies wird von der Installationsroutine des Plugins automatisch durch-
geführt, kann aber auch manuell erfolgen. Unter Windows heißen die Dateien Block.api
und AcroFormConversion.api. Das Verzeichnis für die PDFlib-Plugins lautet üblicherweise
in etwa:
C:\Programme\Adobe\Acrobat 7.0\Acrobat\plug_ins\PDFlib Block Plugin
Installation der Block-Plugins für Acrobat 6/7 auf dem Mac. Bei Acrobat 6/7 ist der Plu-
gin-Ordner im Finder nicht sichtbar. Statt die Plugin-Dateien in den Plugin-Ordner zu
ziehen, gehen Sie wie folgt vor (beenden Sie Acrobat, falls geöffnet):
> Durch Doppelklick auf das Laufwerkssymbol extrahieren Sie die Plugin-Dateien in
einen Ordner.
> Suchen Sie im Finder nach dem Symbol für die Acrobat-Anwendung. Normalerweise
befindet es sich in einem Verzeichnis, das in etwa folgendermaßen lautet:
/Programme/Adobe Acrobat 7.0 Professional
6.1 Installation des Block-Plugins 165

> Nach einem Einfachklick auf das Symbol der Acrobat-Anwendung selektieren Sie
Datei, Info. Ein Fenster erscheint.
> Klicken Sie auf das Dreieck neben Plug-ins.
> Klicken Sie auf Hinzufügen... und selektieren Sie den Ordner PDFlib Block Plugin (in
Acrobat 7) bzw. den Ordner PDFlib Block Plugin Acro 5-6 (in Acrobat 6), der sich in dem
Ordner befindet, der im ersten Schritt angelegt wurde. Beachten Sie, dass dieser Ord-
ner nach der Installation nicht sofort in der Plugin-Liste erscheint. Er wird erst beim
nächsten Öffnen des Info-Fensters angezeigt.
Installation der Block-Plugins für Acrobat 5 auf dem Mac. Zur Installation der Plugins
für Acrobat 5 doppelklicken Sie auf das Laufwerkssymbol. Ziehen Sie den Ordner PDFlib
Block Plugin Acro 5-6 auf den Plugin-Ordner von Acrobat 5, der üblicherweise wie folgt
lautet:
/Programme/Acrobat 5.0/Plug-Ins
Fehlerbehebung. Falls das Block-Plugin nicht zu funktionieren scheint, stellen Sie si-
cher, dass unter Bearbeiten, Grundeinstellungen..., [Allgemein...], Programmstart (Acrobat 6/
7) bzw. Bearbeiten, Grundeinstellungen, Allgemein..., Optionen (Acrobat 5) das Kontrollkäst-
chen »Nur zertifizierte Zusatzmodule verwenden« deaktiviert ist. Die Plugins funktio-
nieren sonst nicht.
166 Kapitel 6: Variable Daten und Blöcke

6.2 Überblick über das Blockkonzept von PDFlib
6.2.1 Vollständige Trennung von Dokumentdesign und Programmcode
Mit PDFlib-Datenblöcken ist es problemlos möglich, variablen Text, Vektorgrafik oder
Rasterbilder über importierte Seiten zu platzieren. Im Gegensatz zu einfachen PDF-Sei-
ten enthalten Seiten mit Datenblöcken Informationen über die Art der Verarbeitung,
die später auf der Serverseite stattfindet. Das Blockkonzept von PDFlib trennt die fol-
genden Aufgaben vollständig voneinander:
> Ein Designer erstellt das Seitenlayout und legt dabei die Position von variablem Text
und Bildelementen sowie deren Eigenschaften wie Schriftgröße, Farbe oder Bildska-
lierung fest. Nach der Erstellung des Layouts als PDF-Dokument legt der Designer
mit dem Block-Plugin für Acrobat die variablen Datenblöcke und ihre Eigenschaften
fest.
> Ein Programmierer schreibt den Code, der die Informationen in den PDF-Blöcken auf
den importierten PDF-Seiten mit dynamischen Daten wie zum Beispiel Datenbank-
feldern verknüpft. Der Programmierer benötigt keine genaueren Kenntnisse über ei-
nen Block (ob dieser einen Namen oder eine Postleitzahl enthält, wo genau er sich
auf der Seite befindet oder wie er formatiert ist etc.). Er ist deshalb von Layoutände-
rungen unabhängig. PDFlib kümmert sich um alle blockspezifischen Details, die aus
den in der Datei abgelegten Blockeigenschaften ermittelt werden.
Anders ausgedrückt ist der vom Programmierer entwickelte Code »datenblind«, das
heißt, er ist generisch und hängt nicht von blockspezifischen Eigenschaften ab. Ange-
nommen, der Designer beschließt, in einem Serienbrief statt des Nachnamens den Vor-
namen des Empfängers zu verwenden. Der generische Code zur Blockverarbeitung
braucht dann nicht geändert zu werden. Die Ausgabe wird korrekt generiert, sobald der
Designer die Blockeigenschaften mit dem Acrobat-Plugin entsprechend geändert hat.
Beispiel: Hinzufügen von variablem Text zu einem Template. Eine häufige Aufgabe be-
steht darin, ein PDF-Template mit dynamischem Text anzureichern. Das folgende Code-
fragment öffnet eine Seite in einem Eingabe-Dokument (dem PDF-Template), platziert
diese auf der Ausgabeseite und füllt einen Textblock namens firstname mit variablem
Text:
doc = PDF_open_pdi(p, filename, "", 0);
if (doc == -1) {
printf("PDF-Template '%s' konnte nicht geöffnet werden\n", filename);
return (1);
}
page = PDF_open_pdi_page(p, doc, pageno, "");
if (page == -1) {
printf("Seite %d von PDF-Template '%s' konnte nicht geöffnet werden\n",
pageno, filename);
return (2);
}
PDF_begin_page_ext(p, width, height, "");

PDF_fit_pdi_page(p, page, 0.0, 0.0, "");
PDF_fill_textblock(p, page, "firstname", "Serge", 0, "encoding winansi");
PDF_close_pdi_page(p, page);

6.2.2 Blockeigenschaften
Das Verhalten von Blöcken lässt sich über die Blockeigenschaften steuern. Diese werden
einem Block mit dem Block-Plugin für Acrobat zugeordnet.
Standardblockeigenschaften. PDFlib-Blöcke sind als Rechtecke auf der Seite definiert,

denen ein Name, ein Typ und eine offene Menge von Eigenschaften zugewiesen sind,
die später auf der Serverseite verarbeitet werden. Der Name entspricht einem beliebi-
gen String zur Identifikation des Blocks, zum Beispiel firstname, lastname oder zipcode.
PDFlib unterstützt folgende Blocktypen:
> Blöcke vom Typ Text enthalten eine oder mehrere Zeilen mit Textdaten. Mehrzeiliger
Text wird mit der Textflussfunktion formatiert. Beachten Sie, dass sich Blöcke nicht
so verbinden lassen, dass Text von einem Block in den nächsten fließt.
> Blöcke vom Typ Image enthalten ein Rasterbild. Dies entspricht im Wesentlichen
dem Import eines TIFF- oder JPEG-Bildes in einer DTP-Anwendung.
> Blöcke vom Typ PDF enthalten beliebige PDF-Grafik, die aus einer Seite eines anderen
PDF-Dokuments importiert wurde. Dies entspricht im Wesentlichen dem Import ei-
ner EPS-Grafik in einer DTP-Anwendung.
Ein Block verfügt abhängig vom jeweiligen Typ über bestimmte Standardeigenschaften.
So kann für einen Textblock zum Beispiel die Schriftart und -größe des Texts und für ei-
nen Bild- oder PDF-Block der Skalierungsfaktor oder die Drehung festgelegt werden. Für
jeden Blocktyp bietet das PDFlib-API eine eigene Verarbeitungsfunktion. Anhand des
Blocknamens suchen die Funktionen in einer importierten PDF-Seite nach dem Block,
analysieren seine Eigenschaften und platzieren die vom Client übergebenen Daten
(Text, Rasterbild oder PDF-Seite) entsprechend der jeweiligen Blockeigenschaften auf
der neuen Seite.
Selbstdefinierte Blockeigenschaften. Die standardmäßig vorhandenen Blockeigen-

schaften ermöglichen eine schnelle Implementierung von Anwendungen zur Verarbei-
tung variabler Daten. Designer sind damit jedoch auf die Eigenschaften beschränkt, die
PDFlib intern kennt und automatisch verarbeitet. Um mehr Flexibilität zu bieten, wird
deshalb zusätzlich die Möglichkeit geboten, einen Block mit selbstdefinierten Eigen-
schaften zu versehen. Durch diese Erweiterung wird das Blockkonzept selbst Anwen-
dungen gerecht, die höchste Anforderungen an die Verarbeitung variabler Daten stel-
len.
Für selbstdefinierte Eigenschaften gibt es keinerlei Regeln, da sie von PDFlib in kei-
ner Weise verarbeitet, sondern lediglich dem Client verfügbar gemacht werden, der sie
inspizieren und auf geeignete Art darauf reagieren kann. Auf Basis der selbstdefinierten
Eigenschaften eines Blocks könnte zum Beispiel über Layout oder Datenerfassung ent-
schieden werden. So könnte für eine wissenschaftliche Anwendung festgelegt werden,
mit wie vielen Stellen eine Zahl ausgegeben wird, oder die Blockeigenschaft könnte den
Namen eines Datenbankfeldes definieren, dessen Inhalt dann zum Füllen des Blocks be-
nutzt wird.
Überschreiben von Blockeigenschaften. In manchen Situationen möchte der Program-

mierer nur gewisse Eigenschaften in einer Blockdefinition verwenden, andere dagegen
mit eigenen Werten überschreiben. Dies kann in verschiedenen Situationen nützlich
sein:

> Der Skalierungsfaktor für ein Bild oder eine PDF-Seite wird nicht der Blockdefinition
entnommen, sondern berechnet.
> Die Blockkoordinaten werden vom Programm angepasst, etwa um eine Rechnung
mit einer variablen Zahl von Einträgen zu erstellen.
> Im Programm werden individuelle Schmuckfarbnamen angegeben, um bei der Er-
stellung von Drucksachen den Anforderungen einzelner Kunden gerecht zu werden.
Blockeigenschaften können überschrieben werden, indem man den Namen der Block-
eigenschaft und die gewünschten Werte in der Optionsliste der PDF_fill_*block( )-Funk-
tionen wie folgt angibt:
PDF_fill_textblock(p, page, "firstname", "Serge", 0, "fontsize 12");
Diese Anweisung überschreibt die interne Eigenschaft fontsize des Blocks mit dem ange-
gebenen Wert 12. Fast alle Namen allgemeiner Blockeigenschaften können als Optionen
benutzt werden; außerdem die Eigenschaften für den jeweiligen Blocktyp. So ist zum
Beispiel die Option underline nur bei PDF_fill_textblock( ) erlaubt, während die Option
scale sowohl bei PDF_fill_imageblock( ) als auch bei PDF_fill_pdfblock( ) erlaubt ist, da scale
sowohl für Image- als auch PDF-Blöcke eine gültige Blockeigenschaft ist.
Das Überschreiben von Blockeigenschaften wirkt sich nur auf den jeweiligen Funk-
tionsaufruf aus. Die Änderung wird nicht in der Blockdefinition gespeichert.
Koordinatensysteme. Die Koordinaten für einen Block beziehen sich auf das Standard-
koordinatensystem von PDF. Wird die Seite, die den Block enthält, auf der Ausgabeseite
platziert, können an PDF_fit_pdi_page( ) verschiedene Optionen zur Positionierung und
Skalierung übergeben werden. Diese Parameter werden bei der Verarbeitung des Blocks
berücksichtigt. Damit wird es möglich, eine Template-Seite mehrfach auf der Ausgabe-
seite zu platzieren, wobei deren Blöcke jedes Mal mit Daten gefüllt werden. So könnte
das Template für eine Visitenkarte zum Beispiel vier Mal auf ein Blatt montiert werden.
Die Blockfunktionen kümmern sich um Transformationen des Koordinatensystems
und die korrekte Platzierung des Texts für alle Blöcke bei allen Aufrufen der Seite. Vor-
ausgesetzt wird hier lediglich, dass der Client die Seite platziert und alle Blöcke auf der
platzierten Seite verarbeitet. Die Seite kann dann auf der Ausgabeseite an anderer Stelle
erneut platziert werden, wobei weitere Blockverarbeitung an der neuen Position statt-
findet usw.
Hinweis Das Block-Plugin zeigt die Blockkoordinaten anders an, als sie intern in der PDF-Datei gespei-
chert werden. Während das Plugin mit der Acrobat-üblichen Notation arbeitet und den Koordi-
natenursprung in der linken oberen Ecke hat, beziehen sich die internen Koordinaten (die im
Block gespeichert werden) auf die PDF-Konvention und haben den Ursprung in der linken unte-
ren Ecke der Seite.
6.2.3 Was spricht gegen PDF-Formularfelder?

Der erfahrene Acrobat-Benutzer mag sich fragen, wozu für PDFlib ein neues Blockkon-
zept implementiert wird, statt die bewährten Formularfelder von PDF zu nutzen. Der
entscheidende Unterschied besteht darin, dass PDF-Formularfelder in erster Linie dafür
konzipiert wurden, vom Benutzer ausgefüllt zu werden, während PDFlib-Blöcke auto-
matisch ausgefüllt werden. Für Anwendungen, die sowohl interaktives als auch auto-
matisches Ausfüllen benötigen, bietet das Block-Plugin eine Funktion, die Formularfel-

der automatisch in Blöcke konvertiert (siehe Abschnitt 6.3.4, »Konvertieren von PDF-
Formularfeldern in PDFlib-Blöcke«, Seite 176).
Wenngleich die beiden Konzepte in vielen Punkten übereinstimmen, bieten PDFlib-
Blöcke gegenüber PDF-Formularfeldern doch einige Vorteile. Diese werden in Tabelle 6.1
aufgezeigt.
Tabelle 6.1 Vergleich zwischen PDF-Formularfeldern und PDFlib-Blöcken

Funktion PDF-Formularfelder PDFlib-Blöcke
Konzeption für interaktiven für automatisches Ausfüllen
Gebrauch
typographische Funktionen (neben – Unterschneiden, Wort- und Zeichenabstand,
Schriftart und -größe) Unterstreichen/Überstreichen/Durchstreichen
Schriftbehandlung Schrifteinbettung Schrifteinbettung, Einbettung von Untergruppen,
Zeichensatz
Textformatierung linksbündig, rechts- linksbündig, rechtsbündig, mittig, Blocksatz;
bündig, mittig verschiedene Formatierungsalgorithmen und
Steuermöglichkeiten; Inline-Optionen können zur
Steuerung der Textdarstellung verwendet werden
Wechsel der Schrift und anderer – ja
Textattribute innerhalb des Texts
kombiniertes Ergebnis ist Bestand- – ja
teil der PDF-Seitenbeschreibung
Benutzer können kombinierte ja nein
Feldinhalte editieren
Funktionalität erweiterbar – ja (selbstdefinierte Blockeigenschaften)
Verwendung von Bilddateien zum – BMP, CCITT, GIF, PNG, JPEG, JPEG2000, TIFF
Füllen
Farbunterstützung RGB Graustufen, RGB, CMYK, Schmuckfarbe, Lab
PDF/X-Kompatibilität – ja (sowohl Template mit Blöcken als auch kombi-
niertes Ergebnis)
Eigenschaften von Text und Grafik – ja
können beim Füllen geändert
werden

6.3 Anlegen von PDFlib-Blöcken
6.3.1 Interaktive Blockerzeugung mit dem Block-Plugin
Einsatz des PDFlib-Blockwerkzeugs. Das Block-Plugin zur Erzeugung von PDFlib-Blö-
cken ist dem Acrobat-Formularwerkzeug recht ähnlich. Solange das Blockwerkzeug aus-
gewählt ist, sind alle Blöcke auf der Seite sichtbar. Wenn Sie ein anderes Acrobat-Werk-
zeug auswählen, werden die Blöcke ausgeblendet, sind aber nach wie vor vorhanden. Es
gibt verschiedene Arten, das Blockwerkzeug auszuwählen:
> Sie klicken auf das Blocksymbol in der Werkzeugleiste Erweiterte Bearbeitung (in
Acrobat 5: Werkzeugleiste Bearbeiten).
> Sie wählen den Menübefehl PDFlib Block, PDFlib Block-Werkzeug.
> Sie drücken das Tastaturkürzel P. Stellen Sie sicher, dass unter Bearbeiten,
Grundeinstellungen..., [Allgemein...], Allgemein das Kontrollkästchen »Zugriffstasten zum
Zugreifen auf Werkzeuge verwenden« aktiviert ist, was standardmäßig nicht der Fall ist
(in Acrobat 5 nicht erforderlich).
Anlegen und Ändern von Blöcken. Nach der Auswahl des Blockwerkzeugs legen Sie ei-
nen Block an, indem Sie mit dem Fadenkreuz-Zeiger einfach an der gewünschten Positi-
on auf der Seite ein Rechteck geeigneter Größe aufziehen. Blöcke sind immer Rechtecke,
deren Kanten parallel zu den Seitenrändern verlaufen. Bei der Erstellung eines neuen
Blocks erscheint das Dialogfeld PDFlib-Blockeigenschaften, in dem Sie verschiedene Ein-
stellungen vornehmen können (siehe Abschnitt 6.3.2, »Bearbeiten von Blockeigenschaf-
ten«, Seite 174). Der Blockname wird automatisch angelegt, kann aber nachträglich ge-
ändert werden. Er muss innerhalb einer Seite eindeutig sein. Im oberen Bereich legen
Sie den Blocktyp auf Text, Image oder PDF fest. Die Registerkarten Allgemein und Spezial
sind immer verfügbar. Die Registerkarten Text, Image und PDF werden nur bei Auswahl
des entsprechenden Blocktyps eingeblendet. Die Registerkarte Textflow wird nur bei Blö-
cken vom Typ Text angezeigt, sofern die Eigenschaft textflow auf true gesetzt ist. Die Re-
gisterkarte Tabs (Tabulatorpositionen) ist nur verfügbar, wenn die Eigenschaft
hortabmethod auf der Registerkarte Textflow auf ruler gesetzt ist.
Hinweis Benutzen Sie nach dem Hinzufügen neuer Blöcke oder Bearbeiten existierender Blöcke den
Acrobat-Befehl »Speichern unter« (und nicht »Speichern«), um die Dateigröße zu minimieren.
Hinweis Wenn Sie mit dem Acrobat-Plugin Enfocus PitStop Dokumente bearbeiten, die PDFlib-Blöcke
enthalten, erhalten Sie unter Umständen die Meldung »Dieses Dokument enthält anwen-
dungsspezifische Informationen von PDFlib. Klicken Sie auf ’OK’ zum Fortfahren oder ’Abbre-
chen’ zum Beenden.« Sie brauchen dieser Meldung keine weitere Beachtung zu schenken und
können problemlos OK drücken.
Selektieren von Blöcken. Blockoperationen wie Kopieren oder Verschieben beziehen

sich auf alle selektierten Blöcke. Mit dem Blockwerkzeug lassen sich ein oder mehrere
Blöcke wie folgt auswählen:
> Um einen einzelnen Block auszuwählen, klicken Sie ihn einfach mit der Maus an.
> Um die Selektion zu erweitern, klicken Sie bei gedrückter Umschalttaste auf einen
weiteren Block.
> Um alle Blöcke auf der Seite auszuwählen, drücken Sie Strg-A (Windows) bzw. Cmd-A
(Mac) oder Bearbeiten, Alles auswählen.

Das Kontextmenü. Sind einer oder mehrere Blöcke selektiert, können Sie das Kontext-
menü zum schnellen Zugriff auf blockspezifische Funktionen nutzen (die sich auch im
Menü PDFlib Block befinden). Zum Öffnen des Kontextmenüs klicken Sie mit der rech-
ten Maustaste (Windows) oder klicken bei gedrückter Strg-Taste (Mac) auf den oder die
selektierten Blöcke.
Um einen Block zu löschen, selektieren Sie ihn mit dem Blockwerkzeug und drücken
die Entf-Taste. Alternativ dazu wählen Sie den Befehl Ändern, Löschen im Kontextmenü.
Einstellen von Blockgröße und -position. Mit dem Blockwerkzeug können Sie einen
oder mehrere Blöcke an eine andere Position bewegen. Wenn Sie die Umschalttaste
(Shift) während des Ziehens gedrückt halten, sind nur horizontale und vertikale Bewe-
gungen möglich, was die exakte Ausrichtung von Blöcken erleichtert. Wenn Sie den Zei-
ger in die Nähe einer Blockecke bewegen, verwandelt er sich in einen Pfeil, mit dem Sie
die Blockgröße ändern können. Um die Position oder Größe mehrerer Blöcke anzupas-
sen, wählen Sie diese aus und wählen im Menü PDFlib Block oder im Kontextmenü die
Befehle aus den Untermenüs Ausrichten, Zentrieren, Verteilen und Skalieren. Die Position
eines oder mehrerer Blöcke lässt sich auch mit den Pfeiltasten ändern.
Alternativ dazu können Sie im Eigenschaftendialog numerische Blockkoordinaten
eingeben. Der Ursprung des Koordinatensystems liegt in der linken oberen Ecke der Sei-
te. Die Koordinaten werden in der Einheit angezeigt, die in Acrobat gerade eingestellt
ist. Zum Ändern der Einheit gehen Sie wie folgt vor:
> In Acrobat 6/7 wählen Sie Bearbeiten, Grundeinstellungen..., [Allgemein...], Einheiten und
Hilfslinien, [oder Seiteneinheiten] und selektieren Punkt, Millimeter, Zoll, Pica oder Zen-
timeter. Sie können auch Anzeige, Navigationsregisterkarten, Info wählen und eine Ein-
heit aus dem Menü Optionen selektieren.
> In Acrobat 5 wählen Sie Bearbeiten, Grundeinstellungen, Allgemein..., Anzeigen,
Seiteneinheiten und selektieren Punkt, Millimeter oder Zoll. Sie können auch Fenster,
Info wählen und eine Einheit aus dem Menü Info selektieren.
Beachten Sie, dass die gewählte Einheit ausschließlich auf die Eigenschaft Rect und
sonst keine numerische Eigenschaft angewandt wird.
Anlegen von Blöcken durch Auswahl eines Rasterbildes oder einer Vektorgrafik. Statt
das Rechteck für einen Block manuell aufzuziehen, können Sie die Blockgröße auch an-
hand von vorhandenem Seiteninhalt definieren. Dazu müssen Sie zunächst sicherstel-
len, dass der Menüpunkt PDFlib Block, Zur Blockdefinition Objekt anklicken aktiv ist. Wenn
Sie nun mit dem Blockwerkzeug auf ein Rasterbild auf der Seite klicken, wird ein Block
in der Größe dieses Bildes erzeugt. Sie können ebenso auf andere grafische Objekte kli-
cken. Das Blockwerkzeug versucht, die umgebende Grafik (zum Beispiel ein Logo) zu se-
lektieren. Diese Objekt-Klick-Funktion ist als Hilfsmittel zur Definition von Blöcken ge-
dacht. Sie können einen Block auch nachträglich ohne Einschränkungen verschieben
oder in der Größe verändern. Der Block ist nicht an das Rasterbild oder das grafische Ob-
jekt gebunden, das als Hilfsmittel verwendet wurde.
Die Objekt-Klick-Funktion versucht zu erkennen, welche Vektorgrafiken oder Raster-
bilder ein logisch zusammengehörendes Element auf der Seite bilden. Wenn Sie auf ei-
nen Seiteninhalt klicken, so wird dessen Boundingbox (das umschließende Rechteck)
ermittelt und selektiert, sofern das Objekt nicht weiß oder sehr groß ist. Im nächsten
Schritt werden weitere Objekte, die sich teilweise im ermittelten Rechteck befinden,

Abb. 6.1
Einstellung der Blockeigenschaften; die
Registerkarte Textflow erscheint nur bei
textflow=true; die Registerkarte Tabs ist
nur bei hortabmethod=ruler sichtbar
zum selektierten Bereich hinzugenommen und so weiter. Auf der Grundlage des end-
gültigen Bereichs wird das Blockrechteck generiert. Die Objekt-Klick-Funktion versucht
letztendlich, vollständige Grafiken und nicht nur einzelne Linien zu selektieren.
Die Funktion ist aber nicht perfekt und selektiert unter Umständen (je nach Seiten-
inhalt) nicht immer das Gewünschte. Schließlich ist sie nur als Hilfsmittel zur schnellen
Platzierung und Bemaßung von Rechtecken gedacht.
Automatische Erkennung von Fonteigenschaften. Das Block-Plugin ist in der Lage, den
Font zu analysieren, der sich an der Stelle befindet, an der der Block positioniert wird.
Darauf aufbauend kann es die folgenden entsprechenden Blockeigenschaften automa-
tisch füllen:
fontname, fontsize, fillcolor, charspacing, horizscaling, wordspacing,
textrendering, textrise
Da die automatische Erkennung von Fonteigenschaften zu unerwünschten Ergebnissen

führen kann, wenn der Hintergrund ignoriert werden soll, kann diese Funktion mit
PDFlib Block, Automatische Font- und Farberkennung aktiviert oder deaktiviert werden.
Standardmäßig ist die Funktion deaktiviert.
Sperren von Blöcken. Blöcke können gegen versehentliches Bewegen, Verkleinern/

Vergrößern oder Löschen gesperrt werden. Dazu wählen Sie das Blockwerkzeug, selek-
tieren den gewünschten Block und wählen Sperren aus dem Kontextmenü. Ist ein Block
gesperrt, lässt er sich weder bewegen, in der Größe ändern oder löschen noch können
seine Eigenschaften angezeigt werden.
Einsatz von Blöcken mit PDF/X. Im Gegensatz zu PDF-Formularfeldern sind PDFlib-

Blöcke kompatibel zu PDF/X. Sowohl das Eingabedokument, das Blöcke enthält, als auch
die generierte PDF-Ausgabe lassen sich zu PDF/X kompatibel machen. Bei der Vorberei-
tung von Blockdateien für einen PDF/X-Workflow kann jedoch folgender Konflikt auf-
treten:

> PDF/X-1:2001, PDF/X-1a:2001 und PDF/X-3:2002 basieren auf Acrobat 4/PDF 1.3, so
dass keine Acrobat-5-Dateien unterstützt werden;
> Das Block-Plugin setzt Acrobat 5 oder höher voraus.
Dieses Problem lässt sich beheben, indem die Dateien mit Acrobat in die erforderliche
PDF-Version konvertiert werden. Weitere Informationen hierzu finden Sie im Abschnitt
»Ändern der PDF-Version eines Dokuments«, Seite 196.
6.3.2 Bearbeiten von Blockeigenschaften

Beim Anlegen eines neuen Blocks, beim Doppelklick auf einen vorhandenen Block oder
bei der Selektion von Eigenschaften im Kontextmenü des Blocks erscheint der Dialog
PDFlib Blockeigenschaften, in dem Sie die Eigenschaften des selektierten Blocks einstellen
können (siehe Abbildung 6.1). Wie in Abschnitt 6.4, »Standardeigenschaften zur auto-
matischen Verarbeitung«, Seite 180, beschrieben, gibt es mehrere Arten von Eigenschaf-
ten:
> Blockname, Typ und Beschreibung sowie die Eigenschaften auf der Registerkarte
Allgemein beziehen sich auf alle Blöcke.
> Die Eigenschaften auf den Registerkarten Text, Image und PDF beziehen sich nur auf
den jeweiligen Blocktyp. Es wird immer nur die dem Blocktyp entsprechende Regis-
terkarte eingeblendet, die anderen beiden Registerkarten sind inaktiv.
> Ist bei einem Textblock die Eigenschaft textflow auf true gesetzt, erscheint eine weite-
re Registerkarte namens Textflow, die textfluss-spezifische Einstellungen enthält.
> Ist bei einem Textblock die Eigenschaft textflow auf true und die Eigenschaft hortab-
method auf der Registerkarte Textflow auf ruler gesetzt, erscheint noch zusätzlich die
Registerkarte Tabs, auf der sich die Tabulatoren einstellen lassen.
> Die Eigenschaften auf der Registerkarte Spezial können vom Benutzer definiert wer-
den und beziehen sich auf einen beliebigen Blocktyp.
Um den Wert einer Eigenschaft zu ändern, geben Sie die gewünschte Zahl oder den ge-
wünschten String in das Eingabefeld der Eigenschaft ein (z.B. bei linewidth), selektieren
den Wert aus einer Dropdown-Liste (z.B. bei fontname, fitmethod) oder selektieren mit
dem »...«-Button rechts einen Farbwert oder Dateinamen (z.B. bei backgroundcolor). Bei
der Eigenschaft fontname können Sie die Schrift aus einer Liste mit allen im System in-
stallierten Schriften auswählen oder einen Schriftnamen eingeben. Unabhängig von
der Auswahlmethode muss der gewählte Font auf dem System vorhanden sein, auf dem
die Blöcke mit dem PDFlib Personalization Server gefüllt werden.
Nachdem Sie die gewünschten Einstellungen vorgenommen haben, schließen Sie
den Eigenschaften-Dialog durch Klicken auf OK. Die soeben definierten Eigenschaften
werden als Bestandteil der Blockdefinition in der PDF-Datei gespeichert.
Übereinander liegende Blöcke. Überlappende Blöcke lassen sich oft nur schwer selek-
tieren, da beim Klicken in einen Bereich nur der oberste Block selektiert wird. In solchen
Fällen kann der Befehl Block auswählen im Kontextmenü genutzt werden, um einen der
Blöcke anhand seines Namens zu selektieren. Die nächste Aktion, die im Bereich des se-
lektierten Blocks durchgeführt wird (z.B. ein Doppelklick), bezieht sich dann nur auf die-
sen Block. Auf diese Weise lassen sich Blöcke problemlos bearbeiten, selbst wenn sie teil-
weise oder vollständig von anderen Blöcken verdeckt werden.

Verwendung und Wiederherstellung von Standardwerten. Um sich Tipp- und Klick-
aufwand zu ersparen, merkt sich das Blockwerkzeug die Werte, die im Eigenschaften-Dia-
log für den zuletzt definierten Block eingegeben wurden. Diese werden beim Anlegen
eines neuen Blocks wiederverwendet. Natürlich können Sie diese Werte jederzeit umde-
finieren.
Mit dem Button Alle rücksetzen im Fenster PDFlib Blockeigenschaften werden die meis-
ten Eigenschaften auf ihre Standardwerte zurückgesetzt. Folgende Eigenschaften blei-
ben unverändert:
> Die Eigenschaften Blockname, Typ, Beschreibung und Rect.
> Alle selbstdefinierten Eigenschaften auf der Registerkarte Spezial.
Gemeinsame Eigenschaften. Mit dem Blockwerkzeug können Sie bei gedrückter Um-
schalttaste mehrere Blöcke auf der Seite selektieren. Wenn Sie dann auf einen der Blö-
cke doppelklicken oder die Eingabetaste drücken, öffnet sich der Eigenschaften-Dialog,
der sich jetzt auf alle selektierten Blöcke bezieht. Es können jedoch nur solche Eigen-
schaften editiert werden, die auf alle selektierten Blöcke anwendbar sind. Abschnitt 6.4,
»Standardeigenschaften zur automatischen Verarbeitung«, Seite 180, beschreibt, wel-
che Eigenschaften mehreren Blöcken gemeinsam sein können. Selbstdefinierte Eigen-
schaften können nicht gemeinsam genutzt werden.
6.3.3 Kopieren von Blöcken zwischen Seiten und Dokumenten

Das Block-Plugin bietet mehrere Methoden zum Verschieben oder Kopieren von Blö-
cken auf der aktuellen Seite, innerhalb des aktuellen Dokuments oder zwischen Doku-
menten:
> Blöcke können durch Ziehen mit der Maus oder durch Einfügen auf einer anderen
Seite oder in ein anderes offenes Dokument verschoben oder kopiert werden.
> Blöcke können auf eine oder mehrere Seiten desselben Dokuments dupliziert wer-
den.
> Blöcke können in eine neue Datei (mit leeren Seiten) oder in ein vorhandenes Doku-
ment (auf die vorhandenen Seiten) exportiert werden.
> Blöcke können aus anderen Dokumenten importiert werden.
Um den Seiteninhalt unter Beibehaltung der Blockdefinitionen zu aktualisieren, kön-

nen Sie die zugrunde liegenden Seiten ohne Veränderung der Blöcke ersetzen. Dazu ver-
wenden Sie Dokument, Seiten ersetzen... (Acrobat 5 und 7) oder Dokument, Seiten, Ersetzen
(Acrobat 6).
Verschieben und Kopieren von Blöcken. Sie können Blöcke verschieben oder kopieren,
indem Sie einen oder mehrere Blöcke selektieren und bei gedrückter Strg-Taste (Win-
dows) bzw. Alt-Taste (Mac) an eine neue Position ziehen. So lange die Taste gedrückt ist,
nimmt der Mauszeiger eine andere Form an. Ein kopierter Block hat die gleichen Eigen-
schaften wie der ursprüngliche Block mit Ausnahme des Namens, der automatisch ge-
ändert wird.
Ebenso können Sie Blöcke mit Copy&Paste an eine andere Position auf der selben
Seite, auf einer anderen Seite des selben Dokuments oder eines anderen in Acrobat ge-
öffneten Dokuments kopieren:
> Wählen Sie das Blockwerkzeug und selektieren Sie die zu kopierenden Blöcke.
> Kopieren Sie die selektierten Blöcke mit Strg-C (Windows) bzw. Cmd-C (Mac) oder
Bearbeiten, Kopieren in die Zwischenablage.

> Fügen Sie mit Strg-V (Windows) bzw. Cmd-V (Mac) oder Bearbeiten, Einfügen die Blö-
cke aus der Zwischenablage ein.
Duplizieren von Blöcken auf andere Seiten. Sie können einen oder mehrere Blöcke
gleichzeitig auf eine beliebige Anzahl von Seiten im Dokument duplizieren:
> Wählen Sie das Blockwerkzeug und selektieren Sie die zu duplizierenden Blöcke.
> Wählen Sie Import und Export, Duplizieren... im Menü PDFlib Block oder im Kontext-
menü.
> Wählen Sie aus, ob nur die selektierten oder alle Blöcke auf der Seite und auf welchen
Seitenbereich die Blöcke dupliziert werden sollen.
Import und Export von Blöcken. Mit den Funktionen zum Import und Export von Blö-
cken können alle Blockdefinitionen auf der Seite oder in einem Dokument über mehre-
re PDF-Dateien verteilt werden. Dies ist zum Beispiel bei der Aktualisierung des Seiten-
inhalts sinnvoll, wenn vorhandene Blockdefinitionen erhalten bleiben sollen. Um die
Blockdefinitionen in eine eigene Datei zu exportieren, gehen Sie wie folgt vor:
> Wählen Sie das Blockwerkzeug und selektieren Sie die zu exportierenden Blöcke.
> Wählen Sie den Befehl Import und Export, Export... im Menü PDFlib Block oder im Kon-
textmenü.
> Geben Sie den Seitenbereich sowie einen Namen für die Datei ein, die die Blockdefi-
nitionen enthalten soll.
Mit dem Befehl Import und Export, Import... im Menü PDFlib Block oder im Kontextmenü
importieren Sie Blockdefinitionen. Dabei können Sie auswählen, ob die importierten
Blöcke auf alle Seiten oder nur einen Seitenbereich im Dokument platziert werden. Bei
mehreren selektierten Seiten werden die Blockdefinitionen unverändert auf diese ko-
piert. Enthält der Seitenbereich des Zieldokuments mehr Seiten als die Datei mit den zu
importierenden Blockdefinitionen, können Sie die Checkbox Vorlage wiederholen selek-
tieren. Die Blöcke in der zu importierenden Datei werden dann so lange wiederholt auf
das Zieldokument übertragen, bis das Dokumentende erreicht ist.
Kopieren von Blöcken in ein anderes Dokument beim Export. Beim Exportieren von
Blöcken können Sie diese unmittelbar auf die Seiten eines anderen Dokuments übertra-
gen. Dazu wählen Sie ein bereits existierendes Dokument als Exportdatei. Wenn Sie die
Checkbox Vorhandene Blöcke löschen selektieren, werden alle im Zieldokument bereits
vorhandenen Blöcke gelöscht, bevor die neuen Blöcke in das Dokument kopiert werden.
6.3.4 Konvertieren von PDF-Formularfeldern in PDFlib-Blöcke

Statt PDFlib-Blöcke manuell zu erstellen, können Sie PDF-Formularfelder auch automa-
tisch in PDFlib-Blöcke konvertieren. Dies ist insbesondere dann von Vorteil, wenn Sie
bereits über komplexe PDF-Formulare mit zahlreichen Feldern verfügen, die in Zukunft
automatisch mit dem PDFlib Personalization Server gefüllt werden sollen oder eine gro-
ße Anzahl vorhandener PDF-Formulare umwandeln müssen, damit sie automatisch
ausfüllbar sind. Um alle Formularfelder auf einer Seite in PDFlib-Blöcke zu konvertie-
ren, wählen Sie PDFlib Block, Formularfelder konvertieren, Aktuelle Seite. Um alle Formular-
felder in einem Dokument zu konvertieren, verwenden Sie stattdessen Alle Seiten. Um
nur die selektierten Formularfelder (zur Selektion wählen Sie das Formular-Werkzeug
oder das Objektauswahl-Werkzeug von Acrobat) zu konvertieren, verwenden Sie
Ausgewählte Formularfelder.

Konvertierung einzelner Eigenschaften. Bei der automatischen Konvertierung von
Formularfeldern werden Formularfelder der im Dialogfeld PDFlib Block, Formularfelder
konvertieren, Konvertierungseinstellungen... in Blöcke vom Typ Text umgewandelt. Stan-
dardmäßig werden alle Formularfeldtypen konvertiert. Die Eigenschaften der Formu-
larfelder werden gemäß Tabelle 6.2 in entsprechende Blockeigenschaften umgewan-
delt.
Tabelle 6.2 Konvertierung von PDF-Formularfeldern in PDFlib-Blöcke

PDF-Formularfeldeigenschaft... ...wird konvertiert in PDFlib-Blockeigenschaft
Alle Felder
Position Allgemein, Rect
Name Allgemein, Name
Tooltip Allgemein, Description
Darstellung, Text, Schrift Text, fontname
Darstellung, Text, Schriftgröße Text, fontsize; die Schriftgröße »auto« wird in eine feste Größe von
2/3 der Blockhöhe konvertiert, außerdem wird für die Eigenschaft
fitmethod der Wert »auto« eingetragen. Bei mehrzeiligen Feldern/
Blöcken ergibt diese Kombination eine passende Schriftgröße, die
kleiner als der Anfangswert von 2/3 der Blockhöhe sein kann.
Darstellung, Text, Farbe Text, strokecolor; Text, fillcolor
Darstellung, Umrandung und Farbe, Allgemein, bordercolor
Umrandungsfarbe
Darstellung, Umrandung und Farbe, Allgemein, backgroundcolor
Füllfarbe
Darstellung, Umrandung und Farbe, Allgemein, linewidth: Thin=1, Medium=2, Thick=3
Linienstärke
Allgemein, Allgemeine Eigenschaften, Allgemein, Status: Sichtbar=active; Unsichtbar=ignore; Sichtbar,
Formularfeld aber Drucken nicht möglich=ignore; Unsichtbar, aber Drucken ist
möglich=active
Allgemein, Allgemeine Eigenschaften, Allgemein, orientate:
Ausrichtung 0=north, 90=west, 180=south, 270=east
Textfelder
Optionen, Standardwert Text, defaulttext
Optionen, Ausrichtung Allgemein, position: Links={left center}, Zentriert={center center},
Rechts={right center}
Optionen, Mehrere Zeilen Text, textflow: aktiviert=true, nicht aktiviert=false
Optionsfelder und Kontrollkästchen
Falls »Schaltfläche ist standardmäßig Text, defaulttext: Häkchen=4, Kreis=l, Kreuz=8, Karo=u,
aktiviert« angeklickt ist: Quadrat=n, Stern=H (diese Zeichen stellen die jeweiligen Symbole
Optionen, Schaltfächenstil bzw. Optionen, im Font ZapfDingbats dar)
Kontrollkästchenstil
Kombinationsfelder und Listenfelder
Optionen, ausgewähltes Standardelement Text, defaulttext
Schaltflächen
Optionen, Symbol und Beschriftung, Text, defaulttext
Beschriftung

Formularfelder mit gleichen Namen. Gleichnamige Formularfelder auf der Seite sind
erlaubt, Blocknamen dagegen müssen auf einer Seite eindeutig sein. Bei der Formular-
konvertierung werden deshalb der Eindeutigkeit halber Zahlen an die generierten
Blocknamen angehängt (siehe auch »Zu welchem Formularfeld gehört ein Block?«, Seite
178).
Beachten Sie, dass aufgrund eines Fehlers in Acrobat die Attribute von Formularfel-
dern gleichen Namens nicht korrekt wiedergegeben werden. Haben mehrere Felder
denselben Namen, aber unterschiedliche Attribute, werden diese Unterschiede nicht
korrekt in die generierten Blöcken übernommen. Bei der Konvertierung erscheint in
solchen Fällen eine Warnung mit den Namen der betroffenen Formularfelder. Sie soll-
ten die Eigenschaften in den generierten Blöcken dann genau überprüfen.
Zu welchem Formularfeld gehört ein Block? Da die Formularfeldnamen nicht unver-

ändert übernommen werden, wenn mehrere Felder gleichen Namens konvertiert wer-
den (zum Beispiel bei Radiobuttons), lässt sich schwer nachvollziehen, welcher Block ei-
gentlich zu welchem Formularfeld gehört. Dies wäre aber insbesondere dann wichtig,
wenn die Blöcke aus einer FDF- oder XFDF-Datei gefüllt werden, und das Ergebnis auch
wie das ausgefüllte Formular aussehen soll.
Zur Lösung dieses Problems speichert das AcroFormConversion-Plugin bei der Erstel-
lung des Blocks detaillierte Informationen über das zugrunde liegende Formularfeld in
selbstdefinierten Eigenschaften. Tabelle 6.3 zeigt alle selbstdefinierten Eigenschaften,
die zur zuverlässigen Ermittlung eines Blocks verwendet werden können; alle Eigen-
schaften haben den Typ string.
Tabelle 6.3 Selbstdefinierte Eigenschaften zur Identifizierung des einem Block zugrunde liegenden
Formularfelds
Selbstdefinierte Eigenschaft Bedeutung
PDFlib:field:name Vollständig qualifizierter Name des Formularfelds.
PDFlib:field:pagenumber Nummer der Seite (als String) im Originaldokument, auf der sich das Formularfeld
befand.
PDFlib:field:type Typ des Formularfelds; mögliche Werte sind pushbutton, checkbox, radiobutton,
listbox, combobox, textfield, signature.
PDFlib:field:value (Nur für type=checkbox) Exportwert des Formularfelds.
Binden von Blöcken an zugehörige Formularfelder. Um PDF-Formularfelder und die

daraus generierten PDFlib-Blöcke aufeinander abgestimmt zu halten, können die gene-
rierten Blöcke an die entsprechenden Formularfelder gebunden werden. Das Block-
werkzeug erhält dann die Beziehung zwischen Formularfeldern und Blöcken aufrecht.
Wird der Konvertierungsprozess erneut durchgeführt, so wird ein gebundener Block ge-
mäß der Eigenschaften des zugehörenden PDF-Formularfeldes aktualisiert. Gebundene
Blöcke verhindern, dass dieselbe Arbeit doppelt erledigt werden muss: Bei der Aktuali-
sierung eines Formulars zur interaktiven Verwendung kann der entsprechende Block
automatisch mit aktualisiert werden.
Wenn Sie die Formularfelder nach der Konvertierung nicht mehr benötigen, wählen
Sie im Dialogfeld PDFlib Block, Formularfelder konvertieren, Konvertierungseinstellungen...
die Option Konvertierte Formularfelder löschen. Bei dieser Option werden die Formularfel-
der nach der Konvertierung gelöscht. Alle Aktionen (zum Beispiel JavaScript), die den
betroffenen Feldern zugeordnet sind, werden ebenfalls aus dem Dokument entfernt.

Stapelkonvertierung. Wenn Sie die Formularfelder vieler PDF-Dokumente in PDFlib-
Blöcke konvertieren möchten, können Sie die Stapelkonvertierung nutzen, die automa-
tisch eine beliebige Anzahl von Dokumenten verarbeitet. Der Dialog zur Stapelverarbei-
tung kann über PDFlib Block, Formularfelder konvertieren, Stapelkonvertierung... geöffnet
werden:
> Es können einzelne Dateien oder der vollständige Inhalt eines Verzeichnisses zur
Verarbeitung ausgewählt werden.
> Die Ausgabedateien können im Verzeichnis der Eingabedateien oder in einem ande-
ren Verzeichnis abgelegt werden. Sie können mit einem Präfix versehen werden, um
sie von den Eingabedateien zu unterscheiden.
> Bei der Verarbeitung sehr vieler Dokumente sollte eine Log-Datei angegeben werden.
In dieser werden alle verarbeiteten Dateien aufgelistet und zu jeder Datei Einzelhei-
ten zur Konvertierung einschließlich eventueller Fehlermeldungen protokolliert.
Während der Konvertierung sind die PDF-Dokumente in Acrobat sichtbar, es können

aber keinerlei Acrobat-Menüfunktionen oder Werkzeuge verwendet werden.

6.4 Standardeigenschaften zur automatischen
Verarbeitung
PDFlib bietet einige allgemeine Eigenschaften (»Properties«), die jedem Blocktyp zuge-
ordnet werden können. Daneben gibt es für den jeweiligen Blocktyp Text, Image und PDF
spezifische Eigenschaften. Manche Eigenschaften können gemeinsam genutzt werden,
das heißt, dass sie mit dem Block-Plugin mehreren Blöcken auf einmal zugeordnet wer-
den können.
Eigenschaften unterstützen dieselben Datentypen wie Optionslisten (siehe Ab-
schnitt 8.1.2, »Optionslisten«, Seite 218) mit Ausnahme von Handles und Aktionslisten.
Viele Blockeigenschaften heißen wie die Optionen für PDF_fit_image( ) und andere
Funktionen (zum Beispiel fitmethod) oder wie PDFlib-Parameter (zum Beispiel
charspacing). In solchen Fällen verhält sich die Eigenschaft genau so wie die gleichnami-
ge Option bzw. der Parameter.
Verarbeitung von Eigenschaften in PDFlib. Die PDFlib-Blockfunktionen PDF_fill_

*block( ) verarbeiten Blockeigenschaften in der folgenden Reihenfolge:
> Ist die Eigenschaft backgroundcolor vorhanden, wird das Blockrechteck mit der fest-
gelegten Farbe gefüllt.
> Alle anderen Eigenschaften mit Ausnahme von bordercolor und linewidth werden ver-
arbeitet.
> Ist die Eigenschaft bordercolor vorhanden, wird das Blockrechteck mit der festgeleg-
ten Farbe und Linienstärke gezeichnet.
> Wird weder Text noch Standardtext übergeben, gibt es keinerlei Ausgabe, auch nicht
für die Hintergrundfarbe oder die Blockränder.
Es wird nichts beschnitten; um sicherzustellen, dass der Blockinhalt nicht über das
Blockrechteck hinausreicht, wählen Sie fitmethod nofit.
Wird in einer Blockeigenschaft eine Schmuckfarbe verwendet, muss der definierte
Schmuckfarbname entweder PDFlib-intern bekannt sein (siehe Abschnitt 3.3.3,
»Schmuckfarben«, Seite 70) oder er muss im PDFlib-Clientprogramm bereits früher mit
PDF_makespotcolor( ) festgelegt worden sein. Andernfalls scheitern die Blockfunktionen.
6.4.1 Allgemeine Eigenschaften

Allgemeine Eigenschaften beziehen sich auf alle Arten von Blöcken (Text, Image, PDF). Sie
sind zur Blockverwaltung erforderlich, beschreiben das Aussehen des Blockrechtecks
und legen fest, wie der Inhalt im Block platziert wird. Alle erforderlichen Einträge wer-
den vom Block-Plugin automatisch generiert. Tabelle 6.4 gibt eine Übersicht über die
allgemeinen Eigenschaften.

Tabelle 6.4 Allgemeine Blockeigenschaften
Schlüsselwort Typ Mögliche Werte und Erklärung
Blockverwaltung
Name String (Erforderlich) Name des Blocks. Blocknamen müssen auf der Seite, aber nicht
innerhalb des Dokuments eindeutig sein. Die drei Zeichen [ ] / sind in
Blocknamen nicht erlaubt. Blocknamen dürfen maximal 127 Zeichen lang sein.
Description String Vom Benutzer lesbare Beschreibung der Funktion des Blocks, die in PDFDocEn-
coding oder Unicode kodiert ist (und im letzteren Fall mit einem BOM beginnt).
Diese Eigenschaft dient nur zur Information des Benutzers und wird bei der
Blockverarbeitung ignoriert.
Locked Boolean (Gemeinsam nutzbar) Ist diese Eigenschaft gleich true, lassen sich der Block und
seine Eigenschaften nicht mit dem Block-Plugin bearbeiten. Diese Eigenschaft
wird bei der Blockverarbeitung ignoriert. Standardwert: false
Rect Float-Liste (Erforderlich) Blockkoordinaten. Der Ursprung des Koordinatensystems liegt in der
linken unteren Ecke der Seite. Das Block-Plugin zeigt die Koordinaten aber in der
Notation von Acrobat an, das heißt, mit dem Ursprung in der linken oberen Ecke
der Seite. Die Koordinaten werden in der Einheit angezeigt, die in Acrobat gerade
ausgewählt ist. In der PDF-Datei werden sie immer in Punkt gespeichert.
Status Schlüsselwort Schlüsselwort, das beschreibt, wie der Block verarbeitet wird. Standardwert: active
active Der Block wird entsprechend seiner Eigenschaften komplett
verarbeitet.
ignore Der Block wird ignoriert.
static Es wird kein variabler Inhalt platziert, sondern der Standardblock-
inhalt in Form von Text, Image oder PDF-Inhalt verwendet, sofern
vorhanden.
Subtype Schlüsselwort (Erforderlich) Je nach Blocktyp entweder Text, Image oder PDF
Type Schlüsselwort (Erforderlich) Immer Block
Blockdarstellung
background- Color (Gemeinsam nutzbar) Ist diese Eigenschaft vorhanden und enthält sie ein von
color None verschiedenes Schlüsselwort zur Festlegung des Farbraums, wird ein
Rechteck gezeichnet und mit der angegebenen Farbe gefüllt. Dies kann nützlich
sein, um vorhandenen Seiteninhalt zu verdecken. Standardwert: None.
bordercolor Color (Gemeinsam nutzbar) Ist diese Eigenschaft vorhanden und enthält sie ein von
None verschiedenes Schlüsselwort zur Festlegung des Farbraums, wird ein
Rechteck mit einem Rand in der angegebenen Farbe gezeichnet. Standardwert:
None
linewidth Float (Gemeinsam nutzbar, muss größer 0 sein) Breite der Linie, mit der das
Blockrechteck gezeichnet wird; wird nur verwendet, wenn bordercolor gesetzt ist.
Standardwert: 1
Platzierung des Inhalts
fitmethod Schlüsselwort (Gemeinsam nutzbar) Strategie für den Fall, dass der übergebene Inhalt nicht in
die Box passt. Mögliche Werte sind auto, nofit, clip, meet1, slice1 und entire1. Für
einfache Blöcke vom Typ text, image oder PDF wird diese Eigenschaft gemäß
Tabelle 8.19 und Tabelle 8.41 interpretiert. Standardwert: auto. Für Textfluss-
blöcke, die zu schmal für den Text sind, lautet die Interpretation wie folgt:
auto fontsize und leading werden so lange reduziert, bis der Text passt.
nofit Der Text läuft aus dem unteren Blockrand hinaus.
clip Der Text wird am Blockrand abgeschnitten.

Tabelle 6.4 Allgemeine Blockeigenschaften
orientate Schlüsselwort (Gemeinsam nutzbar) Legt fest, in welcher Ausrichtung der Inhalt platziert wird
(siehe Tabelle 8.41). Mögliche Werte sind north, east, south, west. Standardwert:
north
position1 Float- oder (Gemeinsam nutzbar) Ein oder zwei Werte, die die Position des Referenzpunkts
Schlüsselwort- innerhalb des Inhalts festlegen (siehe Tabelle 8.19 für text und Tabelle 8.41 für
Liste image/PDF). Die Position wird als Prozentwert innerhalb des Blocks angegeben.
Standardwert: {0 0}, d.h. die linke untere Ecke
rotate Float (Gemeinsam nutzbar) Drehwinkel in Grad, um den der Block gegen den Uhrzeiger-
sinn gedreht wird, bevor die Verarbeitung beginnt. Das Rotationszentrum ist der
Referenzpunkt. Standardwert: 0
1. Dieses Schlüsselwort bzw. diese Eigenschaft wird für Textflussblöcke (Blöcke vom Typ Text mit textflow=true) nicht unterstützt.
6.4.2 Textspezifische Eigenschaften

Für Blöcke vom Typ Text können neben den allgemeinen Eigenschaften einige textspezi-
fische Eigenschaften definiert werden. Alle textspezifischen Eigenschaften lassen sich
gemeinsam nutzen.
Generelle Eigenschaften für Textblöcke. Textblöcke können abhängig von der Eigen-
schaft textflow aus einer oder mehreren Zeilen bestehen. Tabelle 6.5 zeigt alle Eigen-
schaften, die sich generell auf beide Textblockarten anwenden lassen.
Tabelle 6.5 Textspezifische Blockeigenschaften

charspacing Float oder Zeichenabstand (siehe Tabelle 8.18). Prozentangaben beziehen sich auf fontsize.
Prozentwert Standardwert: 0
defaulttext String Text, der verwendet wird, wenn vom Client kein Ersatztext übergeben wird1
fillcolor Color Füllfarbe des Texts. Standardwert: gray 0 (=schwarz)
fontname2 String Name der Schrift, so wie bei PDF_load_font( ) erforderlich. Das Block-Plugin zeigt
alle installierten Systemschriften in einer Liste an. Beachten Sie jedoch, dass diese
Fontnamen nicht unbedingt zwischen Mac, Windows und Unix portierbar sind.
Der Encoding für den Text muss beim Füllen der Blöcke als Option für PDF_fill_
textblock( ) angegeben werden, es sei denn, die Option font wurde benutzt.
fontsize2 Float Schriftgröße in Punkt
fontstyle Schlüsselwort Schriftstil; mögliche Schlüsselwörter sind normal, bold, italic oder bolditalic (siehe
Tabelle 8.16)
horizscaling Float oder Horizontale Skalierung von Text (siehe Tabelle 8.18). Standardwert: 100%
Prozentwert
italicangle Float Neigungswinkel von kursivem Text in Grad (siehe Tabelle 8.18). Standardwert: 0
kerning Boolean Unterschneidung (siehe Tabelle 8.18). Standardwert: false
margin Float-Liste 1 oder 2 Float-Werte für eine zusätzliche horizontale und vertikale Ausdehnung
der Textbox (siehe Tabelle 8.19). Standardwert: 0
monospace Integer Alle Glyphen des Fonts werden in äquidistanter Breite geschrieben (siehe Tabelle
1...2048 8.16). Standardwert: nicht vorhanden (es werden die Metrikdaten der Schrift
verwendet)
overline Boolean Modus für Überstreichen (siehe Tabelle 8.18). Standardwert: false
strikeout Boolean Modus für Durchstreichen (siehe Tabelle 8.18). Standardwert: false

Tabelle 6.5 Textspezifische Blockeigenschaften
strokecolor Color Farbe, in der Text gezeichnet wird. Standardwert: gray 0 (= schwarz)
textflow Boolean Steuert die ein- oder mehrzeilige Verarbeitung (Standardwert: false):
false Text muss einzeilig sein und wird mit PDF_fit_text( ) verarbeitet.
true Text kann mehrzeilig sein und wird mit PDF_fit_textflow( ) verarbeitet.
Die allgemeine Eigenschaft position wird ignoriert. Neben den
Standardeigenschaften für Text können alle Textflow-spezifischen
Eigenschaften festgelegt werden (siehe Tabelle 6.6).
textrendering Integer Darstellungsmodus für Text (siehe Tabelle 8.18). Standardwert: 0
textrise Float oder Modus für den vertikalen Textversatz (siehe Tabelle 8.18). Prozentwerte beziehen
Prozentwert sich auf fontsize. Standardwert: 0
underline Boolean Modus für Unterstreichen (siehe Tabelle 8.18). Standardwert: false
underline- Float, Pro- Position der Linie für unterstrichenen Text, relativ zur Grundlinie (siehe Tabelle
position zentwert o. 8.20). Prozentwerte beziehen sich auf fontsize. Standardwert: auto
Schlüsselwort
underline- Float, Pro- Stärke der Linie für unterstrichenen Text (siehe Tabelle 8.20). Prozentwerte be-
width zentwert o. ziehen sich auf fontsize. Standardwert: auto
Schlüsselwort
wordspacing Float oder Wortabstand (siehe Tabelle 8.18). Prozentwerte beziehen sich auf fontsize.
Prozentwert Standardwert: 0
1. Text wird im Zeichensatz winansi oder Unicode interpretiert.
2. Diese Eigenschaft muss für einen Textblock definiert sein; sie wird vom PDFlib Block-Plugin automatisch gesetzt.
Eigenschaften für Textflussblöcke. Textfluss-spezifische Eigenschaften beziehen sich

auf Blöcke vom Typ Text, bei denen die Eigenschaft textflow den Wert true hat. Anhand
der text-spezifischen Eigenschaften wird die anfängliche Optionsliste zur Textflow-Ver-
arbeitung zusammengestellt (entsprechend dem Parameter optlist für PDF_create_
textflow( )). Mit dem Block-Plugin können keine Inline-Optionslisten festgelegt werden.
Diese lassen sich jedoch auf dem Server als Bestandteil des Textinhalts übergeben,
wenn der Block mit PDF_fill_textblock( ) gefüllt wird. Alle textfluss-spezifischen Eigen-
schaften lassen sich gemeinsam nutzen. Tabelle 6.6 gibt eine Übersicht.
Tabelle 6.6 Textfluss-spezifische Blockeigenschaften

Optionen zur Textinterpretation
tabalignchar Integer Unicode-Wert des Zeichens, an dem dezimale Tabulatoren ausgerichtet werden.
Standardwert: das Zeichen ’.’ (U+002E)
Optionen zur Steuerung der Textformatierung
alignment Schlüsselwort Legt die Formatierung für die Zeilen eines Absatzes fest. Standardwert: left.
left linksbündig, beginnend bei leftindent
center mittig zwischen leftindent und rightindent
right rechtsbündig, bei rightindent endend
justify links- und rechtsbündig (Blocksatz)

firstlinedist Float, Pro- Abstand zwischen dem oberen Rand der Fitbox und der Grundlinie der ersten
zentwert o. Textzeile. Angegeben wird er in Benutzerkoordinaten, als Prozentsatz der
Schlüsselwort Schriftgröße (der Größe der ersten in der Zeile auftretenden Schrift, wenn
fixedleading=true, oder der maximal auftretenden Schriftgröße andernfalls) oder
als Schlüsselwort. Standardwert: leading.
leading Für die erste Zeile ermittelter Zeilenabstand; diakritische Zeichen wie À
berühren den oberen Rand der Fitbox.
ascender Für die erste Zeile ermittelte Oberlänge; Zeichen mit großer Oberlänge
wie d oder h berühren den oberen Rand der Fitbox.
capheight Für die erste Zeile ermittelte Versalhöhe; hohe Großbuchstaben wie H
berühren den oberen Rand der Fitbox.
xheight Für die erste Zeile ermittelte x-Höhe; Kleinbuchstaben wie x berühren
den oberen Rand der Fitbox.
Ist fixedleading=false, wird der größte Wert verwendet, der für Zeilenabstand,
Oberlänge, x-Höhe und Versalhöhe in der ersten Zeile ermittelt wurde.
fixedleading Boolean Ist fixedleading gleich true, wird der beim ersten Zeichen geltende Zeilenabstand
verwendet. Andernfalls wird der größte Zeilenabstand verwendet. Standardwert:
false.
hortabsize Float oder Legt die Breite eines horizontalen Tabulators fest1. Die Interpretation wird von der
Prozentwert Option hortabmethod beeinflusst. Standardwert: 7.5%.
hortab- Schlüsselwort Legt die Interpretation von horizontalen Tabulatoren im Text fest. Liegt die
method berechnete Position links der aktuellen Textposition, so wird der Tabulator
ignoriert. Standardwert: relative.
relative Die Position wird um den in hortabsize festgelegten Betrag vorgerückt.
typewriter Die Position wird auf das nächste Vielfache von hortabsize vorgerückt.
ruler Die Position wird auf den n-ten in der Option ruler verfügbaren Tabu-
latorwert gesetzt, wobei n die Anzahl der bislang in der Textzeile
vorgekommenen Tabs bezeichnet. Ist n größer als die Anzahl der in
ruler verfügbaren Tabulatorpositionen, kommt die Methode relative
zum Einsatz.
lastalignment Schlüsselwort Bestimmt die Formatierung der letzten Zeile eines Absatzes. Neben allen Schlüs-
selwörtern der Option alignment gibt es folgende Schlüsselwörter. Standardwert:
auto.
auto Es wird der Wert der Option alignment verwendet. Nur bei justify wird
left verwendet.
lastlinedist Float, Pro- (Wird ignoriert bei fitmethod=nofit) Der kleineste Abstand zwischen der Grund-
zentwert o. line der letzten Textzeile und dem unteren Rand der Fitbox. Angegeben wird er in
Schlüsselwort Benutzerkoordinaten, als Prozentsatz der Schriftgröße (der ersten in der Zeile auf-
tretenden Schriftgröße, wenn fixedleading=true oder der maximal in der Zeile
auftretenden Schriftgröße andernfalls) oder als Schlüsselwort. Standardwert: 0,
d.h. der untere Rand der Fitbox wird als Grundlinie verwendet und die üblichen
Unterlängen reichen aus der Fitbox hinaus.
descender Für die letzte Zeile ermittelte Unterlänge; Zeichen mit Unterlängen
wie g oder j berühren dabei den unteren Rand der Fitbox.
Ist fixedleading=false wird der größte Wert verwendet, der in der letzten Zeile für
die Unterlänge ermittelt wurde.
leading Float oder Zeilenabstand in Benutzerkoordinaten oder als prozentualer Anteil der
Prozentwert Schriftgröße. Standardwert: 100%.
parindent Float oder Legt den linken Einzug der ersten Zeile eines Absatzes fest1. Der Wert wird zu
Prozentwert leftindent addiert. Wird diese Option innerhalb der Zeile angegeben, so wirkt sie
wie ein Tabulator. Standardwert: 0.

rightindent Float oder Bestimmt den rechten bzw. linken Einzug aller Textzeilen1. Wird leftindent inner-
leftindent Prozentwert halb der Zeile angegeben und befindet sich die definierte Position links der aktuel-
len Textposition, so wird die Option für die aktuelle Zeile ignoriert. Standardwert:
0.
rotate Float Dreht das Koordinatensystem, mit der linken unteren Ecke der Fitbox als Mittel-
punkt. Der übergebene Wert legt den Drehwinkel in Grad fest. Text und Box
werden gedreht. Die Drehung wird zurückgesetzt, nachdem der Text platziert
wurde. Standardwert: 0
ruler2 Liste aus Liste der absoluten Tabulatorpositionen für hortabmethod=ruler1. Die Liste darf
Floats oder maximal 32 nicht-negative Einträge in aufsteigender Reihenfolge enthalten.
Prozentwerten Standardwert: Vielfache von hortabsize als Integers.
tabalignment Liste aus Ausrichtung für Tabulatoren. Jeder Listeneintrag definiert die Ausrichtung des
Schlüssel- entsprechenden Eintrags in der Option ruler. Standardwert: left.
wörtern center Text wird mittig an der Tabulatorposition ausgerichtet.
decimal Das erste tabalignchar-Zeichen wird linksbündig an der Tabulator-
position ausgerichtet. Ist kein tabalignchar-Zeichen vorhanden, wird
rechtsbündig ausgerichtet.
left Text wird linksbündig an der Tabulatorposition ausgerichtet.
right Text wird rechtsbündig an der Tabulatorposition ausgerichtet.
verticalalign Schlüsselwort Vertikale Ausrichtung des Texts in der Fitbox; die Optionen firstlinedist und
lastlinedist werden entsprechend berücksichtigt. Standardwert: top.
top Die Formatierung beginnt in der ersten Zeile und setzt sich nach unten
fort. Füllt der Text die Fitbox nicht vollständig aus, bleibt Weißraum
unter dem Text.
center Der Text wird vertikal in der Fitbox zentriert. Füllt der Text die Fitbox
nicht vollständig aus, bleibt Weißraum über und unter dem Text.
bottom Die Formatierung beginnt in der letzten Zeile und setzt sich nach oben
über dem Text.
justify Der Text wird am oberen und unteren Rand der Fitbox ausgerichtet.
Dazu wird der Zeilenabstand bis zur durch linespreadlimit festgelegten
Grenze erhöht. Die Höhe der ersten Zeile wird nur bei
firstlinedist=leading vergrößert.

Optionen zur Steuerung des Algorithmus für den Zeilenumbruch
adjust- Schlüsselwort Methode zur Anpassung von Textteilen, die nach einer Vergrößerung oder Ver-
method kleinerung des Wortabstandes, der den in den Optionen minspacing und max-
spacing definierten Grenzwerten unterliegt, nicht mehr in die Zeile passen.
Standardwert: auto.
auto Folgende Methoden werden in der angeführten Reihenfolge ange-
wandt: shrink, spread, nofit, split.
clip Wie nofit, nur dass der längere Teil am rechten Rand der Fitbox (unter
Berücksichtigung der Option rightindent) abgeschnitten wird.
nofit Das letzte Wort wird in die nächste Zeile verschoben, sofern die verblei-
bende (kurze) Zeile nicht kürzer als der in der Option nofitlimit fest-
gelegte Prozentwert ist. Auch Absätze im Blocksatz sehen bei dieser
Methode leicht ausgefranst aus.
shrink Passt ein Wort nicht in die Zeile, wird der Text so lange gestaucht, bis
das Wort hineinpasst, sofern die Option shrinklimit dies zulässt.
Anderenfalls kommt die Methode nofit zum Einsatz.
split Das letzte Wort wird nicht in die nächste Zeile verschoben, sondern
zwangsweise getrennt. Bei Textfonts (aber nicht bei Symbolfonts) wird
ein Trennzeichen eingefügt.
spread Das letzte Wort wird in die nächste Zeile verschoben. Der Rest der (kur-
zen) Zeile wird im Blocksatz ausgerichtet, indem der Zeichenabstand
innerhalb der Wörter vergrößert wird, sofern die Option spreadlimit
dies zulässt. Kann kein Blocksatz erreicht werden, kommt die Methode
nofit zum Einsatz.
linespreadlimit Float oder (Nur für verticalalign=justify) Größter Wert in Benutzerkoordinaten oder als
Prozentwert Prozentsatz des Zeilenabstands, um den der Zeilenabstand bei vertikaler
Ausrichtung erhöht wird. Standardwert: 200%.
maxlines Integer oder Maximale Anzahl der Zeilen in der Fitbox oder das Schlüsselwort auto, bei dem
Schlüsselwort möglichst viele Zeilen in der Fitbox platziert werden. Nach der Platzierung der
maximalen Anzahl von Zeilen gibt PDF_fit_textflow( ) den String _boxfull zurück.
maxspacing Float oder Bestimmt den maximalen bzw. minimalen Abstand zwischen Wörtern (in Benut-
minspacing Prozentwert zerkoordinaten oder als prozentualer Anteil der Breite eines Leerzeichens). Der
berechnete Wortabstand wird durch hier übergebenen Werten begrenzt, aber der
Wert der Option wordspacing wird noch addiert. Standardwerte: minspacing=
50%, maxspacing=500%.
nofitlimit Float oder Minimale Zeilenlänge bei der Methode nofit (in Benutzerkoordinaten oder als pro-
Prozentwert zentualer Anteil der Fitboxbreite). Standardwert: 75%.
shrinklimit Prozentwert Untere Grenze für das Stauchen von Text mit der Methode shrink. Der berechnete
Stauchungsfaktor wird durch den hier übergebenen Wert begrenzt, aber noch mit
dem Wert der Option horizscaling multipliziert. Standardwert: 85%.
spreadlimit Float oder Obere Grenze für den Abstand zwischen zwei Zeichen bei der Methode spread (in
Prozentwert Benutzerkoordinaten oder als prozentualer Anteil der Schriftgröße); der berech-
nete Zeichenabstand wird durch den hier übergebenen Wert begrenzt, aber der
Wert der Option charspacing wird noch addiert. Standardwert: 0.
1. In Benutzerkoordinaten oder als prozentualer Anteil an der Breite der Fitbox
2. Die Tabulatorpositionen werden auf der Registerkarte »Tabs« im Blockeigenschaften-Dialog festgelegt.

6.4.3 Rasterbildspezifische Eigenschaften
Für Blöcke vom Typ Image können neben den allgemeinen Eigenschaften einige raster-
bildspezifische Eigenschaften definiert werden. Alle rasterbildspezifischen Eigenschaf-
ten lassen sich gemeinsam nutzen. Tabelle 6.7 gibt eine Übersicht.
Tabelle 6.7 Rasterbildspezifische Blockeigenschaften

defaultimage String Pfadname des Bildes, das verwendet wird, wenn vom Client kein Ersatzbild über-
geben wird. Dateinamen sollten ohne absolute Pfadangabe verwendet werden
und in der PPS-Client-Anwendung sollte mit der SearchPath-Funktionalität gear-
beitet werden. Dies macht die Blockverarbeitung unabhängig von der Plattform
und dateisystem-spezifischen Eigenheiten.
dpi Float-Liste Einer oder zwei Werte, die die gewünschte Bildauflösung in Pixel pro Zoll in hori-
zontaler und vertikaler Richtung angeben. Ist der Wert gleich o, wird die interne
Bildauflösung verwendet. Ist diese nicht vorhanden, werden 72 dpi benutzt. Diese
Eigenschaft wird ignoriert, wenn die Eigenschaft fitmethod mit einem der Schlüs-
selwörter auto, meet, slice oder entire übergeben wurde. Standardwert: 0.
scale Float-Liste Einer oder zwei Werte, die den oder die gewünschten Skalierungsfaktoren in
horizontaler und vertikaler Richtung festlegen. Diese Eigenschaft wird ignoriert,
wenn die Eigenschaft fitmethod mit einem der Schlüsselwörter auto, meet, slice
oder entire übergeben wurde. Standardwert: 1.
6.4.4 PDF-spezifische Eigenschaften

Für Blöcke vom Typ PDF können neben den allgemeinen Eigenschaften einige PDF-spe-
zifische Eigenschaften definiert werden. Alle PDF-spezifischen Eigenschaften lassen
sich gemeinsam nutzen. Tabelle 6.8 gibt eine Übersicht.
Tabelle 6.8 PDF-spezifische Blockeigenschaften

defaultpdf String Pfadname des PDF-Dokuments, das verwendet wird, wenn vom Client kein Ersatz-
dokument übergeben wird. Dateinamen sollten ohne absolute Pfadangabe ver-
wendet werden und in der PPS-Client-Anwendung sollte mit der SearchPath-
Funktionalität gearbeitet werden. Dies macht die Blockverarbeitung unabhängig
von der Plattform und dateisystem-spezifischen Eigenheiten.
default- Float Nummer der Seite im Standard-PDF-Dokument. Standardwert: 1.
pdfpage
scale Float-Liste Einer oder zwei Werte, die den oder die gewünschten Skalierungsfaktoren in hori-
zontaler und vertikaler Richtung festlegen. Diese Eigenschaft wird ignoriert, wenn
die Eigenschaft fitmethod mit einem der Schlüsselwörter auto, meet, slice oder
entire übergeben wurde. Standardwert: 1.
pdiusebox Schlüsselwort (Mögliche Werte: media, crop, bleed, trim, art) Verwendet die MediaBox, CropBox,
BleedBox, TrimBox oder ArtBox der platzierten Seite, um deren Größe zu bestim-
men (siehe Tabelle 8.46). Standardwert: crop.

6.4.5 Selbstdefinierte Eigenschaften
Selbstdefinierte Eigenschaften können zusätzlich zu den allgemeinen und typspezifi-
schen Eigenschaften für Blöcke beliebigen Typs definiert werden. Selbstdefinierte Ei-
genschaften sind optional und lassen sich nicht gemeinsam nutzen.Tabelle 6.9 gibt
eine Übersicht über die Namensregeln für selbstdefinierte Eigenschaften.
Table 6.9 Selbstdefinierte Blockeigenschaften

beliebiger Name, der String, Die Interpretation der Werte selbstdefinierter Eigenschaften liegt voll-
die drei Zeichen [ ] / Name, ständig bei der Client-Applikation.
nicht enthalten darf Float,
Float-Liste

6.5 Abfragen von Blocknamen und -eigenschaften
Neben automatischer Blockverarbeitung unterstützt PDFlib einige Funktionen, mit de-
nen sich Blocknamen auflisten sowie Standard- und selbstdefinierte Eigenschaften ab-
fragen lassen.
Ermitteln der Anzahl und Namen von Blöcken. Die Namen und die Anzahl der Blöcke
auf einer importierten Seite brauchen dem Clientcode nicht bekannt zu sein, da sie ab-
gefragt werden können. Die folgende Anweisung gibt die Anzahl der Blöcke auf der Seite
zurück:
blockcount = PDF_get_pdi_value(p, "vdp/blockcount", doc, page, 0);
Die folgende Anweisung gibt den Namen von Block Nummer 5 auf der Seite (die Zäh-
lung beginnt bei 0) oder einen Leerstring zurück, wenn kein entsprechender Block exis-
tiert (hat der Parameter oder die Option pdiwarning den Wert true, wird jedoch eine Ex-
ception ausgelöst):
blockname = PDF_get_pdi_parameter(p, "vdp/Blocks[5]/Name", doc, page, 0, &len);
Der zurückgegebene Blockname kann im weiteren Verlauf zur Abfrage von Blockeigen-
schaften oder zum Füllen des Blocks mit Text, Bildern oder PDF-Inhalt verwendet wer-
den.
In der Syntax für den Pfad zur Adressierung der Blockeigenschaft sind folgende Aus-
drücke gleichbedeutend, wobei davon ausgegangen wird, dass der Block mit der Num-
mer <nummer> seine Eigenschaft Name auf <blockname> gesetzt hat:
Blocks[<nummer>]/
Blocks/<blockname>/
Ermitteln von Blockkoordinaten. Die beiden Koordinatenpaare (llx, lly) und (urx, ury),
die die linke untere und die rechte obere Ecke eines Blocks namens foo beschreiben, las-
sen sich wie folgt abfragen:
llx = PDF_get_pdi_value(p, "vdp/Blocks/foo/Rect[0]", doc, page, 0);
lly = PDF_get_pdi_value(p, "vdp/Blocks/foo/Rect[1]", doc, page, 0);
urx = PDF_get_pdi_value(p, "vdp/Blocks/foo/Rect[2]", doc, page, 0);
ury = PDF_get_pdi_value(p, "vdp/Blocks/foo/Rect[3]", doc, page, 0);
Beachten Sie, dass diese Koordinaten im Standard-Benutzerkoordinatensystem (mit

dem Ursprung in der linken unteren Ecke, eventuell modifiziert durch die CropBox der
Seite) übergeben werden, wohingegen das Block-Plugin die Koordinaten gemäß des Ko-
ordinatensystems der Acrobat-Benutzeroberfläche mit dem Ursprung in der linken
oberen Ecke der Seite anzeigt.
Beachten Sie zudem, dass der Parameter topdown bei der Abfrage der Blockkoordina-
ten nicht berücksichtigt wird.
Nicht vorhandene Blockeigenschaften und Standardwerte. Aufgrund eingeschränkter

API-Funktionalität lässt sich mit der Schnittstelle PDF_get_pdi_value( ) nicht ermitteln,
ob eine Blockeigenschaft vorhanden ist und den Wert 0 besitzt, oder ob sie im Doku-
ment fehlt, so dass ihr Standardwert verwendet wird.
6.5 Abfragen von Blocknamen und -eigenschaften 189

Fehlt eine Eigenschaft vom Typ »String«, gibt PDF_get_pdi_parameter( ) einen leeren
String zurück. Fehlt eine numerische Eigenschaft (so dass ihr Standardwert zum Einsatz
kommt), gibt PDF_get_pdi_value( ) den Wert 0 (null) zurück. Da die meisten numerischen
Eigenschaften sowieso den Standardwert 0 haben, ist in solchen Fällen keine Spezialbe-
handlung erforderlich. Sie sollten sich jedoch bewusst sein, dass manche numerischen
Eigenschaften wie linewidth, horizscaling, leading und scale einen von 0 verschiedenen
Standardwert besitzen (und 0 hier auch keinen Sinn ergibt). In diesen Fällen müssen Sie
speziellen Code vorsehen, der den von PDF_get_pdi_value( ) zurückgegebenen Wert 0 in
den Standardwert der jeweiligen Eigenschaft umsetzt.
Hinweis Mit unserem Produkt PDFlib pCOS können Sie beliebige Informationen aus einem PDF abfra-
gen, unter anderem auch Blockeigenschaften.
Abfrage von selbstdefinierten Eigenschaften. Selbstdefinierte Eigenschaften lassen

sich wie in folgendem Beispiel abfragen, in dem die Eigenschaft zipcode von einem
Block namens b1 abgefragt wird.
zip = PDF_get_pdi_parameter(p, "vdp/Blocks/b1/Custom/zipcode", doc, page, 0, &len);
Wenn Sie nicht wissen, welche selbstdefinierten Eigenschaften in einem Block eigent-
lich vorhanden sind, können Sie deren Namen zur Laufzeit abfragen. Mit folgendem Co-
defragment ermitteln Sie zum Beispiel den Namen der ersten selbstdefinierten Eigen-
schaft des Blocks b1:
propname = PDF_get_pdi_parameter(p, "vdp/Blocks/b1/Custom[0].key", doc, page, 0, &len);
Wenn Sie den Index 0 erhöhen, erhalten Sie sukzessive die Namen aller weiteren benut-
zerdefinierten Eigenschaften. Wird ein leerer String zurückgegeben, sind keine benut-
zerdefinierten Eigenschaften mehr vorhanden.
Namensraum für selbstdefinierte Eigenschaften. Zur Vermeidung von Namenskon-

flikten beim Austausch von PDF-Dokumenten aus verschiedenen Quellen sollten die
Namen selbstdefinierter Eigenschaften aus einem firmeneigenen Präfix, gefolgt von
einem Strichpunkt ’:’ und dem eigentlichen Eigenschaftsnamen, bestehen. Als firmen-
spezifisches Präfix empfehlen wir den jeweiligen Internet-Domainnamen. Die Proper-
ty-Namen des Unternehmens ACME sähen dann zum Beispiel wie folgt aus:
acme.com:digits
acme.com:refnumber
Da Standard- und selbstdefinierte Eigenschaften im Block unterschiedlich gespeichert

werden, können Standardnamen (wie in Abschnitt 6.4, »Standardeigenschaften zur au-
tomatischen Verarbeitung«, Seite 180, definiert) nicht mit selbstdefinierten Namen in
Konflikt geraten.

6.6 Spezifikation für PDFlib-Blöcke
Die Syntax für PDFlib-Blöcke ist vollständig kompatibel zur PDF-Referenz, die einen Er-
weiterungsmechanismus definiert, mit dem eine Applikation private Daten als Anhang
an die Datenstrukturen einer PDF-Seite speichern kann. Der folgende Abschnitt be-
schreibt die Syntax der PDFlib-Blöcke im Detail. Dies kann für solche Anwender von
Nutzen sein, die PDFlib-Blöcke nicht mit dem Block-Plugin, sondern auf andere Art er-
zeugen wollen. Anwender, die mit dem Plugin arbeiten, können diesen Abschnitt ge-
trost überspringen.
6.6.1 PDF-Objektstruktur für PDFlib-Blöcke

Das Page-Dictionary enthält einen Eintrag /PieceInfo, der als Wert ein weiteres Dictiona-
ry enthält. Dieses Dictionary enthält den Key /PDFlib, der als Wert wiederum ein Dictio-
nary mit Applikationsdaten enthält. Das Applikationsdaten-Dictionary enthält die bei-
den in Tabelle 6.10 aufgeführten Standardkeys.
Tabelle 6.10 Einträge in einem PDFlib-Applikationsdaten-Dictionary

Key Typ Wert
LastModified Datum (Erforderlich) Datum und Zeit der Erstellung oder letzten Änderung der Blöcke auf
der Seite.
Private Dictionary (Erfoderlich) Blockliste gemäß Tabelle 6.11
Eine Blockliste ist ein Dictionary mit allgemeinen Information zur Blockverarbeitung
sowie einer Liste aller Blöcke auf der Seite. Tabelle 6.11 enthält alle Keys in einem Block-
listen-Dictionary.
Tabelle 6.11 Einträge in einem Blocklisten-Dictionary

Key Typ Wert
Version Zahl (Erforderlich) Die Versionsnummer der Blockspezifikation, gemäß der die Datei
erstellt wurde. Dieses Dokument beschreibt Version 6 der Blockspezifikation.
Blocks Dictionary (Erforderlich) Jeder Schlüssel ist ein Namensobjekt mit dem Namen eines Blocks;
der zugehörige Wert ist das Block-Dictionary des Blocks (siehe Tabelle 6.13). Der
Schlüssel /Name im Block-Dictionary muss identisch zum Namen des Blocks in
diesem Dictionary sein.
PluginVersion String (Erforderlich, falls der Schlüssel pdfmark nicht vorhanden ist1) Ein String, der die
Versionsnummer des PDFlib Block-Plugins enthält, mit dem die Blöcke erstellt
wurden.
pdfmark Boolean (Erforderlich, falls der SchlüsselPluginVersion nicht vorhanden ist1) Muss den Wert
true haben, falls die Blockliste mit Hilfe von pdfmarks erstellt wurde.
1. Genau einer der Keys PluginVersion und pdfmark muss vorhanden sein.
Datentypen von Blockeigenschaften. Für Blockeigenschaften werden mit Ausnahme

von Handles und Aktionslisten dieselben Datentypen wie für Optionslisten unterstützt
(siehe Abschnitt 8.1.2, »Optionslisten«, Seite 218). Tabelle 6.12 zeigt, wie diese Typen auf
PDF-Datentypen abgebildet werden.

Tabelle 6.12 Datentypen für Blockeigenschaften
Blocktyp PDF-Typ Anmerkung
Boolean Boolean
String String
Schlüsselwort String Schlüsselwörter dürfen nur in der Liste der Schlüsselwörter, die von einer
bestimmten Eigenschaft unterstützt werden, übergeben werden. Ande-
renfalls führt dies zu einem Fehler.
Float, Integer Boolean Optionslisten akzeptieren Punkt und Komma als Dezimalzeichen, bei PDF-
Zahlen dagegen ist nur ein Punkt erlaubt.
Prozentwert Array mit zwei Das erste Arrayelement enthält die Zahl, das zweite Element einen String
Elementen mit dem Prozentzeichen.
Farbe Array mit zwei Das erste Arrayelement legt einen Farbraum fest und das zweite einen
Elementen Farbwert. Für das erste Arrayelement werden folgende Einträge
unterstützt:
/DeviceGray
Das zweite Element ist ein einzelner Graustufenwert.
/DeviceRGB
Das zweite Element ist ein Array mit drei RGB-Werten.
/DeviceCMYK
Das zweite Element ist ein Array mit vier CMYK-Werten.
[/Separation/spotname]
Das erste Element ist ein Array mit dem Schlüsselwort
/Separation und dem Farbnamen. Das zweite Element ist ein
Wert für den Farbauftrag.
[/Lab] Das erste Element ist ein Array mit dem Schlüsselwort /Lab.
Das zweite Element ist ein Array aus drei Lab-Werten.
Um keine Farbe festzulegen, muss die entsprechende Eigenschaft wegge-
lassen werden.
Schlüssel in Block-Dictionaries. Block-Dictionaries können die Schlüssel in Tabelle 6.13

enthalten. Abhängig vom Wert des Keys /Subtype dürfen nur Keys aus einer der Grup-
pen Text, Image oder PDF vorhanden sein (siehe Tabelle 6.4).
Tabelle 6.13 Einträge in einem Block-Dictionary

Key Typ Wert
Allgemeine Eigenschaften (Manche Keys sind erforderlich) Allgemeine Blockeigenschaften gemäß Tabelle 6.4
Text-Eigenschaften (Optional) Text- und textfluss-spezifische Blockeigenschaften gemäß Tabelle 6.5
und Tabelle 6.6
Image-Eigenschaften (Optional) Rasterbildspezifische Blockeigenschaften gemäß Tabelle 6.7
PDF-Eigenschaften (Optional) PDF-spezifische Blockeigenschaften gemäß Tabelle 6.8
Custom Dictionary (Optional) Dictionary mit Schlüssel/Wert-Paaren für selbstdefinierte Eigen-
schaften gemäß Tabelle 6.9
Internal Dictionary (Optional) Dieser Schlüssel ist für internen Gebrauch reserviert; Anwendungen
sollten keinerlei Annahmen über sein Vorhandensein oder bestimmte Inhalte
machen. Derzeit wird dieser Schlüssel zur Verwaltung der Beziehung zwischen
konvertierten Formularfeldern und den zugehörigen Blöcken genutzt.
Beispiel. Das folgende Fragment zeigt den PDF-Code für zwei Blöcke, einen Textblock
namens job_title und einen Image-Block namens logo. Der Textblock enthält eine selbst-
definierte Eigenschaft namens format:

<<
/Contents 12 0 R
/Type /Page
/Parent 1 0 R
/MediaBox [ 0 0 595 842 ]
/PieceInfo << /PDFlib 13 0 R >>
>>
13 0 obj
<<
/Private <<
/Blocks <<
/job_title 14 0 R
/logo 15 0 R
>>
/Version 6
/PluginVersion (2.2.0)
>>
/LastModified (D:20050813200730)
>>
endobj
14 0 obj
<<
/Type /Block
/Rect [ 70 740 200 800 ]
/Name /job_title
/Subtype /Text
/fitmethod /auto
/fontname (Helvetica)
/fontsize 12
/Custom << /format 5 >>
>>
endobj
15 0 obj
<<
/Type /Block
/Rect [ 250 700 400 800 ]
/Name /logo
/Subtype /Image
/fitmethod /auto
>>
6.6.2 Erzeugen von PDFlib-Blöcken mit pdfmarks

Alternativ zur Erzeugung von PDFlib-Blöcken mit dem Plugin können Sie Blöcke auch
durch Einfügen von pdfmark-Anweisungen in einen PostScript-Datenstrom und an-
schließendes Destillieren erzeugen. Einzelheiten zum pdfmark-Operator werden in der
Acrobat-Dokumentation beschrieben. Das folgende Fragment zeigt pdfmark-Operato-
ren, die die Blockdefinition im vorhergehenden Abschnitt erzeugen:
% ---------- Vorbereitung für die Blöcke der Seite ----------
[/_objdef {B1} /type /dict /OBJ pdfmark % Blocks-Dictionary
[{ThisPage} <<
/PieceInfo <<
/PDFlib <<

/LastModified (D:20050813200730)
/Private <<
/Version 6
/pdfmark true
/Blocks {B1}
>>
>>
>>
>> /PUT pdfmark
% ---------- Textblock ----------

[{B1} <<
/job_title <<
/Type /Block
/Name /job_title
/Subtype /Text
/Rect [ 70 740 200 800 ]
/fitmethod /auto
/fontsize 12
/fontname (Helvetica)
/Custom << /format 5 >>
>>
>> /PUT pdfmark
% ---------- Image-Block ----------

[{B1} <<
/logo <<
/Type /Block
/Name /logo
/Subtype /Image
/Rect [ 250 700 400 800 ]
/fitmethod /auto
>>
>> /PUT pdfmark

7 Erstellung verschiedener
PDF-Varianten
7.1 Acrobat und PDF-Versionen
PDFlib generiert optional Ausgabe, die zu PDF 1.3 (Acrobat 4), PDF 1.4 (Acrobat 5), PDF 1.5
(Acrobat 6) oder PDF 1.6 (Acrobat 7) kompatibel ist. Dies lässt sich mit der Option compa-
tibility in PDF_begin_document( ) steuern.
PDFlib-Ausgabefunktionen für PDF ab Version 1.4. Im Kompatibilitätsmodus zu

PDF 1.3 sind die in Tabelle 7.1 für PDF 1.4 und in Tabelle 7.2 für PDF 1.5 aufgeführten Funk-
tionen nicht verfügbar. Ihr Einsatz löst im Kompatibilitätsmodus zu PDF 1.3 eine Excep-
tion aus.
Tabelle 7.1 PDFlib-Funktionen für PDF 1.4, die im Kompatibilitätsmodus zu PDF 1.3 nicht verfügbar sind
Eigenschaft PDFlib-API-Funktionen und Parameter
Farbverläufe PDF_shading_pattern( ), PDF_shfill( ), PDF_shading( )
Transparenzmasken PDF_load_image( ), wenn die Option masked auf ein Bild mit mehr als 1
Bit Pixeltiefe verweist
128-Bit-Verschlüsselung PDF_begin_document( ) mit den Optionen userpassword, masterpassword
und permissions
erweiterte Berechtigungen PDF_begin_document( ) mit der Option permissions, siehe Tabelle 7.3
einige CMaps für CJK-Schriften PDF_load_font( ), siehe Tabelle 4.7
Transparenz und andere Optionen PDF_create_gstate( ) mit den Optionen alphaisshape, blendmode,
für den Grafikzustand opacityfill, opacitystroke, textknockout
einige Optionen für Aktionen PDF_create_action( ), siehe Tabelle 8.49
einige Optionen für Anmerkungen PDF_create_annotation( ), siehe Tabelle 8.51
einige Feldoptionen PDF_create_field( ) und PDF_create_fieldgroup( ), siehe Tabelle 8.52
Tagged PDF Option tagged in PDF_begin_document( )
PDFlib-Ausgabefunktionen für PDF ab Version 1.5. In den Kompatibilitätsmodi zu

PDF 1.3 und 1.4 sind die in Tabelle 7.2 angeführten PDFlib-Funktionen nicht verfügbar.
Ihr Einsatz löst im Kompatibilitätsmodus zu PDF 1.3 oder 1.4 eine Exception aus.
Tabelle 7.2 In den Kompatibiltätsmodi zu PDF 1.3 und 1.4 nicht verfügbare PDFlib-Funktionen für PDF 1.5
Eigenschaft PDFlib-API-Funktionen und Parameter
einige Feldoptionen PDF_create_field( ) und PDF_create_fieldgroup( ), siehe Tabelle 8.52
einige Anmerkungsoptionen PDF_create_annotation( ) siehe Tabelle 8.51
erweiterte Berechtigungen permissions=plainmetadata in PDF_begin_document( ), siehe Tabelle 7.3
einige CMaps für CJK-Schriften PDF_load_font( ), siehe Tabelle 4.7
Tagged PDF einige Optionen für PDF_begin_item( ), siehe Tabelle 8.57 und Tabelle 8.58
Ebenen PDF_define_layer( ), PDF_begin_layer( ), PDF_end_layer( ), PDF_layer_
dependency( )
JPEG2000-Bilder imagetype=jpeg2000 in PDF_load_image( )
7.1 Acrobat und PDF-Versionen 195

PDF-Version von mit PDI importierten Dokumenten. In allen Kompatibilitätsmodi
können mit PDI nur PDF-Dokumente mit derselben oder einer niedrigeren Kompatibili-
tätsstufe importiert werden. Soll ein PDF mit einer aktuelleren Kompatibilitätsstufe
importiert werden, müssen Sie die Option compatibility entsprechend setzen (siehe Ab-
schnitt 5.2.3, »Importierbare PDF-Dokumente«, Seite 157).
Ändern der PDF-Version eines Dokuments. Wenn Sie Ausgabe in einer bestimmten
PDF-Version zu erstellen und dazu PDFs in einer höheren Version zu importieren ha-
ben, müssen Sie die Dokumente vor dem PDI-Import in die niedrigere PDF-Version kon-
vertieren. Dies lässt sich in Acrobat bewerkstelligen, die genaue Vorgehensweise ist aber
von der jeweiligen Acrobat-Version abhängig:
> Acrobat 7: Mit Erweitert, PDF Optimierung..., Kompatibel mit können Sie die Datei in den
Formaten PDF 1.3 - PDF 1.6 speichern.
> Acrobat 6: Mit Datei, Dateigröße verringern... können Sie die Datei in den Formaten
PDF 1.3 - PDF 1.5 speichern.
> Acrobat 5: Zur Konvertierung eines Dokuments nach PDF 1.3 können Sie das Plugin
pdfSaveAs1.3 von callas software einsetzen. Voll funktionsfähige Demoversionen sind
auf der Web-Site von callas1 verfügbar. Dieses Konvertierungs-Plugin kann insbeson-
dere beim Umgang von Blöcken mit PDF/X nützlich sein, da PDF 1.3 von manchen
PDF/X-Versionen gefordert wird (siehe »Einsatz von Blöcken mit PDF/X«, Seite 173,
und Abschnitt 7.4.2, »Erzeugung PDF/X-kompatibler Ausgabe«, Seite 202).
1. Siehe www.callassoftware.com
196 Kapitel 7: Erstellung verschiedener PDF-Varianten

7.2 Verschlüsseltes PDF
7.2.1 Stärken und Schwächen der Sicherheitsfunktionen von PDF
PDF unterstützt verschiedene Sicherheitsmerkmale, die zum Schutz von Dokumentin-
halten dienen. Sie basieren auf der Acrobat-Standardsicherheit, die mit symmetrischer
Verschlüsselung arbeitet. Sowohl Acrobat Reader als auch die Acrobat-Vollversion un-
terstützen folgende Sicherheitsfunktionen:
> Berechtigungen beschränken die mit dem PDF-Dokument erlaubten Aktionen, wie
zum Beispiel das Drucken oder das Extrahieren von Text.
> Das Benutzerkennwort ist zum Öffnen der Datei erforderlich.
> Das Hauptkennwort ist zum Ändern von Sicherheitseinstellungen wie Berechtigun-
gen, Benutzer- oder Hauptkennwort erforderlich. Eine Datei mit Benutzer- und
Hauptkennwort kann wahlweise mit einem der beiden geöffnet werden.
Verfügt eine Datei über ein Benutzer- oder Hauptkennwort oder irgendwelche Sicher-
heitseinstellungen, so wird sie verschlüsselt.
Knacken geschützter PDF-Dokumente. Die Länge der zum Schutz von Dokumenten
verwendeten Chiffrierschlüssel hängt von dem PDF-Kompatibilitätslevel ab, der vom
Client gewählt wurde:
> Bei PDF-Versionen bis einschließlich 1.3 (das heißt Acrobat 4) beträgt die Schlüssel-
länge 40 Bit.
> Ab PDF-Version 1.4 beträgt die Schlüssellänge 128 Bit. Dies erfordert Acrobat ab Versi-
on 5. Bei PDF 1.5 beträgt die Schlüssellänge ebenfalls 128 Bit, das Verschlüsselungsver-
fahren unterscheidet sich jedoch ein wenig, was den Einsatz von Acrobat 6 erforder-
lich macht.
Bekanntermaßen ist eine Schlüssellänge von 40 Bit bei symmetrischer Verschlüsselung

(die in PDF verwendet wird) nicht sicher. Mit kommerzieller Cracker-Software können
40-Bit-Sicherheitseinstellungen in PDF mittels eines Brute-Force-Angriffs innerhalb
von Tagen oder Wochen (je nach Länge und Qualität des Kennworts) außer Kraft gesetzt
werden. Um höchstmögliche Sicherheit zu gewährleisten, ist Folgendes zu empfehlen:
> Verwenden Sie nach Möglichkeit 128-Bit-Verschlüsselung (d.h. Kompatibilität zu PDF
1.4). Dazu müssen alle Benutzer des Dokuments mit Acrobat 5 oder höher arbeiten.
> Kennwörter sollten mindestens sechs Zeichen lang sein und auch Zeichen außerhalb
des Alphabets enthalten. Sie sollten auf keinen Fall den Namen Ihres Gatten, Ihrer
Gattin oder Ihres Haustiers, Ihren Geburtstag oder Ähnliches enthalten, um so ge-
nannte Wörterbuch-Angriffe oder das Erraten/Ausprobieren von Kennwörtern zu
vereiteln. Beachten Sie außerdem, dass kurze Kennwörter selbst bei 128-Bit-Ver-
schlüsselung innerhalb von Minuten geknackt werden können.
Zugriffsbeschränkungen. Bei einer Zugriffsbeschränkung, zum Beispiel mit der Ein-

stellung Drucken unzulässig, deaktiviert Acrobat die zugehörige Funktion. Dies gilt je-
doch nicht unbedingt für PDF-Viewer oder andere Software von Drittherstellern. Es ist
Sache der jeweiligen Tool-Entwickler, ob sie die definierten Zugriffsberechtigungen be-
rücksichtigen oder nicht. Es gibt einige PDF-Tools, die Berechtigungseinstellungen voll-
ständig ignorieren; außerdem können Zugriffsbeschränkungen mit kommerziellen
Cracker-Tools außer Kraft gesetzt werden. Dies ist jedoch vom Schlüsselknacken zu un-
terscheiden; es gibt einfach keine Möglichkeit, das Drucken einer PDF-Datei zuverlässig

zu unterbinden, wenn sie am Bildschirm anzeigbar sein soll. Dies wird sogar in der PDF-
Referenz von Adobe dokumentiert:
Die PDF-Verschlüsselung enthält keine Mechanismen, die eine Durchsetzung der im
Encryption-Dictionary festgelegten Dokumentberechtigungen erzwingen. Es liegt in der Hand
der jeweiligen PDF-Viewer-Entwickler, die Absichten des Dokumenterstellers zu respektieren
und den Benutzerzugriff auf eine verschlüsselte PDF-Datei entsprechend der in der Datei fest-
gelegten Berechtigungen zu beschränken.
7.2.2 Schützen von Dokumenten mit PDFlib

Kennwörter. Kennwörter können mit den Parametern userpassword und
masterpassword gesetzt werden. PDFlib verarbeitet die mit den vom Client übergebenen
Kennwörtern wie folgt:
> Wenn ein Benutzerkennwort oder Berechtigungen (siehe unten), aber kein Haupt-
kennwort angegeben wurde, könnte ein normaler Benutzer die Sicherheitseinstel-
lungen ändern. Aus diesem Grund behandelt PDFlib diese Situation als Fehler.
> Sind Benutzer- und Hauptkennwort identisch, wäre keine Unterscheidung zwischen
Benutzer und Eigentümer der Datei mehr möglich, was einem effektiven Schutz zu-
widerläuft. PDFlib behandelt diese Situation als Fehler.
> Benutzer- und Hauptkennwörter können bis zu 32 Zeichen lang sein. Weitere Zei-
chen werden ignoriert und haben keinen Einfluss auf die Verschlüsselung. Leere
Kennwörter sind unzulässig.
Die übergebenen Kennwörter werden für alle nachfolgend generierten Dokumente ver-
wendet.
Nicht-ASCII-Zeichen in Kennwörtern. Besondere Aufmerksamkeit ist erforderlich,

wenn in Kennwörtern Zeichen außerhalb des konventionellen ASCII-Zeichensatzes zwi-
schen 0x20 und 0x7E verwendet werden. Angenommen, das Zeichen Ä wird in einem
Kennwort verwendet. Auf dem Mac hat das Zeichen den Code 0x80, wohingegen es in
Windows mit 0xC4 kodiert ist. Da die Datei auch mit Ä im Kennwort auf jeder Plattform
zu öffnen sein muss, konvertiert Acrobat das übergebene Kennwort vor seiner Anwen-
dung in den internen Zeichensatz PDFDocEncoding. Ist ein Zeichen dort nicht vorhan-
den, wird es als Leerzeichen umgesetzt. PDFDocEncoding enthält alle auf dem Mac und
in Windows verfügbaren Zeichen, wobei manche konvertiert werden. Würde die Datei
mit dem Kennwort Ä auf dem Mac verschlüsselt, wäre sie mit dem unveränderten Code
für Ä von PDI nicht dechiffrierbar. Deswegen muss, damit mit Acrobat verschlüsselte
Dateien sowohl auf dem Mac als auch in Windows erfolgreich entschlüsselbar sind, PDI
die selbe Kennwortkonvertierung wie Acrobat durchführen. Bei der Entschlüsselung er-
mittelt PDI automatisch die Art der erforderlichen Konvertierung:
> Konvertierung von WinAnsi nach PDFDocEncoding, wenn das Dokument mit der
Windows-Version von Acrobat oder mit PDFlib PLOP ab 2.1 verschlüsselt wurde;
> Konvertierung von MacRoman nach PDFDocEncoding, wenn das Dokument mit der
Mac-Version von Acrobat verschlüsselt wurde;
> Keine Konvertierung, wenn das Dokument mit anderer Software inklusive PDFlib
PLOP bis 2.0 verschlüsselt wurde.
Beim Verschlüsseln von Dateien interpretiert PDFlib entsprechend der Windows-Versi-

on von Acrobat die übergebenen Kennwörter im WinAnsi-Zeichensatz, d.h. Benutzer-

und Hauptkennwort werden von WinAnsi nach PDFDocEncoding konvertiert; auf EBC-
DIC-Systemen erfolgt zuvor eine Konvertierung von EBCDIC nach WinAnsi.
Berechtigungen. Zugriffsberechtigungen können mit der Option permissions in PDF_

begin_document( ) gesetzt werden. Mit der Option permissions müssen Sie die Option
masterpassword verwenden, da Acrobat-Benutzer die festgelegten Berechtigungen sonst
einfach wieder entfernen könnten. Standardmäßig sind alle Aktionen zulässig. Bei Fest-
legung einer Zugriffsbeschränkung wird die zugehörige Funktion in Acrobat deakti-
viert. Zugriffsbeschränkungen können ohne Benutzerkennwort angewandt werden. Es
können mehrere durch Leerzeichen getrennte Schlüsselwörter angegeben werden:
PDF_begin_document(p, filename, 0, "masterpassword=abc123 permissions {noprint nocopy}");
Tabelle 7.3 zeigt alle für Zugriffsberechtigungen unterstützten Schlüsselwörter. Wie in

der Tabelle angeführt, ist für einige Schlüsselwörter Kompatibilität zu PDF ab Version
1.4 erforderlich. Sie werden abgelehnt, falls die PDF-Ausgabeversion zu niedrig ist.
Tabelle 7.3 Schlüsselwörter für Berechtigungen für die Option permissions in PDF_begin_document( )
Schlüsselwort Erklärung
noprint Acrobat verhindert das Drucken der Datei.
nomodify Acrobat verhindert, dass Benutzer Formularfelder hinzufügen oder irgendwelche anderen
Änderungen vornehmen.
nocopy Acrobat verhindert, dass Text oder Grafik kopiert oder extrahiert wird und deaktiviert außerdem
die Accessibility-Schnittstelle (zur Gewährleistung von Barrierefreiheit).
noannots Acrobat verhindert das Hinzufügen oder Ändern von Kommentaren oder Formularfeldern.
noforms (PDF 1.4) Acrobat verhindert das Ausfüllen von Formularfeldern, auch wenn noannots nicht
angegeben wurde.
noaccessible (PDF 1.4) Acrobat verhindert die Extraktion von Text oder Grafik im Rahmen der Accessibility (zum
Beispiel für Screenreader-Programme)
noassemble (PDF 1.4) Acrobat verhindert das Einfügen, Löschen oder Drehen von Seiten und die Erstellung von
Lesezeichen und Piktogrammen, auch wenn nomodify nicht angegeben wurde.
nohiresprint (PDF 1.4) Acrobat verhindert den Ausdruck mit hoher Auflösung. Wurde noprint nicht angegeben,
wird der Ausdruck mit der Option »Als Bild drucken« durchgeführt und die Seite in niedriger
Auflösung ausgegeben.
plain- (PDF 1.5) Die Metadaten des Dokuments bleiben auch bei verschlüsselten Dokumenten
metadata unverschlüsselt. Dieses Schlüsselwort bezieht sich nur auf XMP-Metadaten und nicht auf
Dokumentinfofelder.
Hinweis Wenn PDFs über das WEb bereitsgestellt werden, können Clients mit dem Browser immer eine
lokale Kopie des Dokuments erstellen. Es gibt keine Möglichkeit für das PDF zu verhindern, dass
Benutzer eine lokale Kopie speichern.

7.3 Web-Optimiertes (Linearisiertes) PDF
PDFlib ist in der Lage, PDF-Dokumente zu linearisieren (linearisiertes PDF heißt in Acro-
bat 4 Optimiert und ab Acrobat 5 Schnelle Web-Anzeige). Bei der Linearisierung werden die
Objekte in der PDF-Datei umgeordnet und Informationen hinzugefügt, die dem schnel-
leren Zugriff dienen.
Während nicht-linearisierte PDFs vollständig zum Client übertragen werden müs-
sen, kann ein Web-Server linearisierte PDF-Dokumente seitenweise mit einem Verfah-
ren names Byteserving transferieren. Damit kann Acrobat (als Browser-Plugin) ein PDF-
Dokument auch teilweise abrufen. Die erste Dokumentseite wird dem Benutzer dann
unverzüglich angezeigt, ohne dass er erst auf die vollständige Übertragung des Doku-
ments vom Server warten muss. Damit kann der Benutzer sofort mit dem Lesen des
Dokuments beginnen.
Beachten Sie, dass nicht PDFlib, sondern der Web-Server die PDF-Daten an den Brow-
ser übergibt. PDFlib bereitet die PDF-Dateien lediglich zum Byteserving vor. Zum Byte-
serving von PDFs sind folgende Voraussetzungen zu erfüllen:
> Das PDF-Dokument muss linearisiert werden. Dies lässt sich mit der Option linearize
in PDF_begin_document( ) bewerkstelligen. In Acrobat können Sie in den Dokument-
eigenschaften nachsehen, ob eine Datei linearisiert ist (»Schnelle Web-Anzeige: ja«).
> Der Web-Server muss Byteserving unterstützen. Das zugrunde liegende Byterange-
Protokoll ist Bestandteil von HTTP 1.1 und somit in allen üblichen Web-Servern im-
plementiert. Byteserving wird zum Beispiel von folgenden Web-Servern unterstützt:
Microsoft Internet Information Server (IIS) 3.0 und höher
Apache 1.2.1 und höher; Apache 1.3.14 (aber nur diese Version) hat einen Fehler, der
Byteserving unmöglich macht
> Der Benutzer muss Acrobat als Browser-Plugin installiert und in Acrobat seitenwei-
ses Herunterladen aktiviert haben. Dies ist standardmäßig der Fall (Acrobat 6:
Bearbeiten, Grundeinstellungen..., [Allgemein...,] Internet, Schnelle Web-Anzeige zulassen;
Acrobat 5: Bearbeiten, Grundeinstellungen, Allgemein..., Optionen, Schnelle Web-Anzeige
zulassen).
Je größer eine PDF-Datei (in Seiten oder MB gemessen) ist, desto mehr wird sie bei der
Übertragung über das Web von der Linearisierung profitieren.
Hinweis Die Linearisierung eines PDF-Dokuments vergrößert die Datei geringfügig, da spezielle Lineari-
sierungsinformationen hinzugefügt werden.
Temporärer Speicher für die Linearisierung. PDFlib muss das Dokument erst vollstän-
dig erstellen, bevor es in einem nachfolgenden eigenen Verarbeitungsschritt linearisi-
ert wird. Dafür benötigt PDFlib temporär zusätzlichen Speicher, der in etwa der Größe
des generierten Dokuments (ohne Linearisierung) entspricht. Je nach Einstellung der
Option inmemory für PDF_begin_document( ) speichert PDFlib die für die Linearisierung
erforderlichen Daten entweder im Speicher oder in einer temporären Datei auf der Fest-
platte.

7.4 PDF/X
7.4.1 PDF/X-Standards
Die in ISO 15930 definierten PDF/X-Standards wurden entwickelt mit dem Ziel, eine
konsistente und stabile Untermenge von PDF bereitzustellen, die sich zur Anlieferung
von Daten zu einer Druckerei eignet1. PDFlib ist zur Generierung von Ausgabe und Ver-
arbeitung von Eingabe in der Lage, die kompatibel zu folgenden PDF/X-Varianten ist:
PDF/X-1:2001 und PDF/X-1a:2001, definiert in ISO 15930-1. Diese Standards für den
»blinden Datenaustausch« (Austausch von Druckdaten ohne vorherige technische Ab-
sprache) basieren auf PDF 1.3 und unterstützen CMYK- und Schmuckfarben. RGB und
geräteabhängige Farben (ICC-basiert, Lab) sind explizit ausgeschlossen. PDF/X-1:2001
unterstützt ein Verfahren zur Integration von veralteten Dateiformaten (zum Beispiel
TIFF/IT) in einem PDF-Workflow und gilt als veraltet. PDF/X-1a:2001 enthält keine derar-
tige Unterstützung und ist (insbesondere in Nordamerika) ein gängiger Standard für
den Austausch von Zeitschriftenanzeigen und andere Anwendungen.
PDF/X-1a:2003, definiert in ISO 15930-4. Dieser Standard ist der Nachfolger von PDF/
X-1a:2001. Er basiert auf PDF 1.4, wobei einige Funktionen (zum Beispiel Transparenz)
unzulässig sind. PDF/X-1a:2003 ist eine Teilmenge von PDF/X-3:2003, unterstützt
CMYK- und Schmuckfarbe sowie CMYK-Ausgabegeräte.
PDF/X-2:2003, definiert in ISO 15930-5. Dieser Standard zielt auf einen »abgesproche-
nen Datenaustausch« ab, bei dem sich Lieferant und Empfänger einer Datei absprechen
müssen. PDF-Dokumente, die diesem Standard entsprechen, können auf externe Ele-
mente (andere PDF-Seiten außerhalb des aktuellen Dokuments) verweisen. PDF/X-
2:2003 basiert auf PDF 1.4. Als Obermenge von PDF/X-3:2003 unterstützt er geräteunab-
hängige Farben.
PDF/X-3:2002, definiert in ISO 15930-3. Dieser Standard basiert auf PDF 1.3 und unter-
stützt moderne Workflows mit geräteunabhängigen Farben, Graustufen, CMYK und
Schmuckfarben. Er ist insbesondere in Europa verbreitet. Zulässig sind Monochrom-,
RGB- und CMYK-Ausgabegeräte.
PDF/X-3:2003, definiert in ISO 15930-6. Dieser Standard ist der Nachfolger von PDF/X-
3:2002. Er basiert auf PDF 1.4, wobei einige Funktionen (zum Beispiel Transparenz) un-
zulässig sind.
Wird ein PDF/X-Standard im Folgenden ohne das Standardisierungsjahr erwähnt, dann

sind alle passenden Versionen des Standards gemeint. So bedeutet PDF/X-3 zum Beispiel
PDF/X-3:2002 und PDF-X/3:2003.
Hinweis PANTONE®-Farben werden gegenwärtig nicht in den Modi PDF/X-1:2001, PDF/X-1a:2001 und
PDF/X-1a:2003 unterstützt.
1. Siehe www.pdfx3.org und www.pdf-x.com
7.4 PDF/X 201

7.4.2 Erzeugung PDF/X-kompatibler Ausgabe
Mit PDFlib kann auf Basis folgender Mechanismen eine PDF/X-kompatible Ausgabe ge-
neriert werden:
> PDFlib kümmert sich automatisch um verschiedene formale Einstellungen für
PDF/X, zum Beispiel die PDF-Versionsnummer und die PDF/X-Kompatibilitäts-
schlüssel.
> Der PDFlib-Client muss explizit bestimmte Funktionsaufrufe und Parametereinstel-
lungen verwenden (siehe Tabelle 7.4).
> Der PDFlib-Client darf bestimmte Funktionsaufrufe und Parametereinstellungen
nicht verwenden (siehe Tabelle 7.5).
> Beim Importieren von Seiten aus vorhandenen PDF/X-kompatiblen Dokumenten
müssen weitere Regeln beachtet werden (siehe Abschnitt 7.4.3, »Import von PDF/X-
Dokumenten mit PDI«, Seite 205).
Zwingend erforderliche Operationen. Tabelle 7.4 zeigt alle Operationen, die zur Gene-
rierung PDF/X-kompatibler Ausgabe erforderlich sind. Die angeführten Punkte bezie-
hen sich auf alle PDF/X-Kompatibilitätsstufen, sofern es nicht anderweitig angemerkt
ist. Fehlt im PDF/X-Modus ein erforderlicher Funktionsaufruf, wird eine Exception aus-
gelöst.
Tabelle 7.4 Operationen, die zur PDF/X-Kompatibilität anzuwenden sind

Kriterium Für PDF/X-Kompatibilität erforderliche PDFlib-Funktionen und -Parameter
Kompatibilitätsstufe Der Parameter pdfx muss vor dem Aufruf von PDF_begin_document( ) auf die
erforderliche PDF/X-Kompatibilitätsstufe gesetzt werden.
Druckausgabe- PDF_load_iccprofile( ) mit usage = outputintent oder PDF_process_pdi( ) mit
bedingung action=copyoutputintent muss unmittelbar nach PDF_begin_document( ) aufgerufen
(output intent) werden. Werden HKS-Schmuckfarben, Pantone-Schmuckfarben, ICC-basierte oder Lab-
Farben verwendet, muss ein ICC-Profil für die Druckausgabebedingung eingebettet
werden; eine Standard-Druckausgabebedingung ist in solchen Fällen nicht zulässig.
PDF/X-1 und PDF/X-1a: Das Ausgabegerät muss ein Monochrom- oder CMYK-Gerät sein;
PDF/X-3: Das Ausgabegerät muss ein Monochrom-, RGB- oder CMYK-Gerät sein.
Fonteinbettung Um die Fonteinbettung zu aktivieren, muss die Option embedding von PDF_load_font( )
auf true gesetzt werden.
Seitengrößen Die jeweiligen Seitenangaben, die mit den Parametern CropBox, BleedBox, TrimBox und
ArtBox gesetzt werden können, müssen folgende Anforderungen erfüllen:
> Es muss entweder die TrimBox oder die ArtBox festgelegt werden, aber nicht beide. Ist
keine von beiden vorhanden, verwendet PDFlib die CropBox (sofern vorhanden) als
TrimBox bzw. die MediaBox, wenn auch die CropBox nicht vorhanden ist.
> Die BleedBox, sofern vorhanden, muss in der ArtBox oder der TrimBox enthalten sein.
> Die CropBox, sofern vorhanden, muss in der ArtBox oder der TrimBox enthalten sein.
Graustufen PDF/X-3: In PDF_begin_page_ext( ) muss die Option defaultgray gesetzt werden, wenn
Graustufen-Bilder oder PDF_setcolor( ) mit einem Graustufen-Farbraum verwendet
werden und das in der PDF/X-Druckausgabebedingung festgelegte Gerät nicht mit CMYK
oder Graustufen arbeitet.
RGB-Farbe PDF/X-3: In PDF_begin_page_ext( ) muss die Option defaultrgb gesetzt werden, wenn
RGB-Bilder oder PDF_setcolor( ) mit einem RGB-Farbraum verwendet werden und das in
der PDF/X-Druckausgabebedingung festgelegte Gerät nicht mit RGB arbeitet.

Tabelle 7.4 Operationen, die zur PDF/X-Kompatibilität anzuwenden sind
Kriterium Für PDF/X-Kompatibilität erforderliche PDFlib-Funktionen und -Parameter
CMYK-Farbe PDF/X-3: In PDF_begin_page_ext( ) die Option defaultcmyk muss gesetzt werden, wenn
CMYK-Bilder oder PDF_setcolor( ) mit einem CMYK-Farbraum verwendet werden und das
in der PDF/X-Druckausgabebedingung festgelegte Gerät nicht mit CMYK arbeitet.
Dokumentinfo- Die Infoeinträge für Creator und Title müssen mit PDF_set_info( ) gesetzt werden.
einträge
Unzulässige Operationen. Tabelle 7.5 führt alle Operationen auf, die bei der Erzeugung
von PDF/X-kompatibler Ausgabe untersagt sind. Die angeführten Punkte beziehen sich
auf alle PDF/X-Kompatibilitätsstufen, sofern es nicht anderweitig angemerkt ist. Der
Aufruf einer im PDF/X-Modus unzulässigen Funktion löst eine Exception aus. Unzuläs-
sige Bilder lösen abhängig vom Parameter imagewarning keine Exception aus. Wenn
eine importierte PDF-Seite nicht der aktuellen PDF/X-Kompatibilitätsstufe entspricht,
scheitert der betreffende PDI-Aufruf, ohne eine Exception auszulösen (abhängig vom
Parameter pdiwarning).
Tabelle 7.5 Operationen, die für PDF/X-Kompatibilität unzulässig sind

Kriterium Für PDF/X-Kompatibilität unzulässige PDFlib-Funktionen und -Parameter
Graustufen PDF/X-1 und PDF/X-1a: In PDF_begin_page_ext( ) ist die Option defaultgray unzulässig.
RGB-Farbe PDF/X-1 und PDF/X-1a: RGB-Bilder und die Option defaultrgb in PDF_begin_page_ext( )
sind unzulässig.
CMYK-Farbe PDF/X-1 und PDF/X-1a: In PDF_begin_page_ext( ) ist die Option defaultcmyk unzulässig.
ICC-basierte Farbe PDF/X-1 und PDF/X-1a: Der Farbraum iccbasedgray/rgb/cmyk in PDF_setcolor( ) und die
Parameter setcolor:iccprofilegray/rgb/cmyk sind unzulässig.
Lab-Farbe PDF/X-1 und PDF/X-1a: Der Farbraum Lab in PDF_setcolor( ) ist unzulässig.
Anmerkungen und Anmerkungen innerhalb der BleedBox (oder TrimBox/ArtBox, falls keine BleedBox
Formularfelder vorhanden) sind unzulässig: PDF_create_annotation( ), PDF_create_field( ) und die
entsprechenden veralteten Funktionen.
Aktionen und Alle Aktionen inklusive JavaScript sind unzulässig: PDF_create_action( ) und die
JavaScript entsprechenden veralteten Funktionen.
Rasterbilder PDF/X-1 und PDF/X-1a: Bilder in RGB-, ICC-basierter, YCbCr- oder Lab-Farbe sind
unzulässig. Bei Bildern, die mit der Option colorize eingefärbt wurden, muss die
Alternativfarbe der benutzten Schmuckfarbe denselben Bedingungen genügen.
In PDF_load_image( ) sind die Optionen OPI-1.3 und OPI-2.0 unzulässig.
Transparenz Für Rasterbilder sind Transparenzmasken unzulässig: in PDF_load_image( ) ist die Option
mask unzulässig, sofern sie sich nicht auf ein 1-Bit-Bild bezieht.
In PDF_create_gstate( ) sind die Optionen opacityfill und opacitystroke unzulässig, sofern
sie nicht den Wert 1 besitzen.
Viewer-Voreinstel- In PDF_set_parameter( ) dürfen die Schlüssel viewarea, viewclip, printarea und printclip
lungen/Anzeige- nur mit den Werten media und bleed verwendet werden.
und Druckbereiche
Dokumentinfo- Der Infoschlüssel Trapped darf nur mit den Werten True oder False an PDF_set_info( )
Schlüssel übergeben werden.
Sicherheit PDF/X-1 außer PDF/X-1a: In PDF_begin_document( ) sind die Option userpassword sowie
der Wert noprint für die Option permissions unzulässig;
PDF/X-1a und PDF/X-3: In PDF_begin_document( ) sind die Optionen userpassword,
masterpassword und permissions unzulässig.
7.4 PDF/X 203

Tabelle 7.5 Operationen, die für PDF/X-Kompatibilität unzulässig sind
Kriterium Für PDF/X-Kompatibilität unzulässige PDFlib-Funktionen und -Parameter
PDF-Version/ In PDF_begin_document( ) darf die Option compatibility nicht gesetzt werden, da dies von
Kompatibilität PDFlib automatisch erledigt wird (Einzelheiten zu Funktionen in den verschiedenen PDF-
Versionen finden Sie in Tabelle 7.1 und Tabelle 7.2)
PDF/X-1:2001, PDF/X-1a:2001 und PDF/X-3:2002 basieren auf PDF 1.3. Alle Operationen,
die PDF 1.4 oder höher benötigen (wie Transparenz oder Transparenzmasken) sind
unzulässig.
PDF/X-1a:2003, PDF/X-2:2003 und PDF/X-3:2003 basieren auf PDF 1.4. Alle Operationen,
die PDF 1.5 benötigen (zum Beispiel Ebenen) sind unzulässig.
PDF-Import (PDI) Importierte Dokumente müssen derselben PDF/X-Kompatibilitätsstufe wie das Ausgabe-
dokument genügen und für dieselbe Druckausgabebedingung erstellt worden sein.
Standard-Druckausgabebedingungen. Die Druckausgabebedingung definiert das be-

absichtigte Zielgerät, was insbesondere für zuverlässige Proofs sinnvoll ist. Sie kann
entweder durch ein ICC-Profil oder durch den Namen einer Standard-Druckausgabebe-
dingung festgelegt werden. Tabelle 7.6 führt die Namen der in PDFlib bekannten Stan-
dard-Druckausgabebedingungen auf. Weitere Standard-Druckausgabebedingungen
können über die Ressourcenkategorie StandardOutputIntent definiert werden (siehe Ab-
schnitt 3.1.5, »Ressourcenkonfiguration und Dateisuche«, Seite 56). Der Benutzer muss
sicherstellen, dass nur Namen als Standard-Druckausgabebedingungen eingetragen
werden, die von PDF/X verarbeitender Software erkannt werden. Standard-Druckausga-
bebedingungen lassen sich wie folgt referenzieren:
PDF_load_iccprofile(p, "CGATS TR 001", 0, "usage outputintent");
Bei PDF/X-3-Ausgabe mit HKS-, Pantone-, ICC-basierten oder Lab-Farben dürfen Sie kei-
ne Standard-Druckausgabebedingungen verwenden, sondern müssen stattdessen ein
ICC-Profil des Ausgabegeräts einbetten.
Tabelle 7.6 Standard-Druckausgabebedingungen für PDF/X

OutputIntent Beschreibung
CGATS TR 001 der U.S.-amerikanische SWOP-Druckstandard
OF COM PO P1 F60 ISO 12647-2, Positivkopie, Papiertyp 1 (glänzend gestrichen)
OF COM PO P2 F60 ISO 12647-2, Positivkopie, Papiertyp 2 (matt gestrichen)
OF COM PO-P3 F601 ISO 12647-2, Positivkopie, Papiertyp 3 (glatt gestrichen Rolle)
OF COM PO P4 F60 ISO 12647-2, Positivkopie, Papiertyp 4 (ungestrichen Offset weiß)
OF COM NE P1 F60 ISO 12647-2, Negativkopie, Papiertyp 1 (glänzend gestrichen)
OF COM NE P2 F60 ISO 12647-2, Negativkopie, Papiertyp 2 (matt gestrichen)
OF COM NE P3 F60 ISO 12647-2, Negativkopie, Papiertyp 3 (glatt gestrichen Rolle)
OF COM NE P4 F60 ISO 12647-2, Negativkopie, Papiertyp 4 (ungestrichen Offset weiß)
SC GC2 CO F30 ISO 12647-5, Farbumfang Klasse 2, UV- oder wasserbasiert, lufttrocknend
Ifra_NP_40lcm_neg+CTP_05.00 Coldset-Offset (Computer to Plate)
1. Das Minuszeichen zwischen P0 und P3 sieht zwar unpassend aus, es wird jedoch vom Standard gefordert.

7.4.3 Import von PDF/X-Dokumenten mit PDI
Wenn Seiten eines vorhandenen PDF-Dokuments in ein PDF/X-kompatibles Ausgabe-
dokument importiert werden, gelten spezielle Regeln (die PDF-Importbibliothek PDI
wird in Abschnitt 5.2, »Import von PDF-Seiten mit PDI (PDF Import Library)«, Seite 155,
beschrieben). Alle importierten Dokumente müssen derselben PDF/X-Kompatibilitäts-
stufe genügen wie das generierte Ausgabedokument (siehe Tabelle 7.7). Generell sind
alle Eingabedokumente zulässig, die derselben PDF/X-Kompatibilitätsstufe wie das ge-
nerierte Ausgabedokument oder einer älteren Version derselben Stufe genügen. Darü-
ber hinaus sind einige andere Kombinationen erlaubt. Wird in PDFlib eine bestimmte
PDF/X-Kompatibilitätsstufe eingestellt und genügen die importierten Dokumente die-
ser Einstellung, dann gilt dies garantiert auch für die erzeugte Ausgabe. Importierte Do-
kumente, die der eingestellten PDF/X-Kompatibilitätsstufe nicht genügen, werden ab-
gelehnt.
Tabelle 7.7 Zulässige PDF/X-Eingabestufen für verschiedene PDF/X-Ausgabestufen; andere Kombinationen sind
unzulässig.
PDF/X-Kompatibilitätsstufe für das importierte Dokument
PDF/X-Ausgabestufe PDF/X-1:2001 PDF/X-1a:2001 PDF/X-1a:2003 PDF/X-2:2003 PDF/X-3:2002 PDF/X-3:2003
PDF/X-1:2001 zulässig zulässig
PDF/X-1a:2001 zulässig
PDF/X-1a:2003 zulässig zulässig
PDF/X-2:2003 zulässig zulässig zulässig zulässig zulässig
PDF/X-3:2002 zulässig zulässig
PDF/X-3:2003 zulässig zulässig zulässig zulässig
Werden mehrere PDF/X-Dokumente importiert, müssen alle für dieselbe Druckausga-

bebedingung erzeugt worden sein. PDFlib kann bestimmte Punkte zwar korrigieren, ist
aber nicht für die Überprüfung und Durchsetzung vollständiger PDF/X-Kompatibilität
importierter Dokumente gedacht. PDFlib bettet in importierten PDF-Seiten zum Bei-
spiel keine fehlenden Schriften ein und nimmt auch keine Farbkorrekturen vor.
Um importierte PDF-Seiten zu einem Ausgabedokument zusammenzustellen, das
derselben PDF/X-Kompatibilitätsstufe und Druckausgabebedingung wie die Eingabedo-
kumente genügt, können Sie den PDF/X-Status eines importierten PDFs wie folgt abfra-
gen:
pdfxlevel = PDF_get_pdi_parameter(p, "pdfx", doc, -1, 0, &len);
Diese Anweisung gibt einen String zurück, der die PDF/X-Kompatibilitätsstufe des im-
portierten Dokuments bezeichnet, sofern diese einem PDF/X-Level entspricht, anderen-
falls none. Mit dem zurückgegebenen String kann mit der Option pdfx in PDF_begin_
document( ) die entsprechende PDF/X-Kompatibilitätsstufe für das Ausgabedokument
gesetzt werden.
Neben der Abfrage der PDF/X-Kompatibilitätsstufe können Sie die PDF/X-Druckaus-
gabebedingung wie folgt aus einem importierten Dokument kopieren:
doc = PDF_process_pdi(p, doc, -1, "action copyoutputintent");
7.4 PDF/X 205

Diese Methode kann als Alternative zur Festlegung der Druckausgabebedingung mit
PDF_load_iccprofile( ) verwendet werden. Hierbei wird die Druckausgabebedingung des
importierten Dokuments in das generierte Ausgabedokument kopiert, unabhängig da-
von, ob sie über einen Standardnamen oder ein ICC-Profil definiert wurde. Sie darf ge-
nau einmal festgelegt werden, entweder durch Kopieren aus dem importierten Doku-
ment oder durch explizites Setzen mit PDF_load_iccprofile( ) und der Option usage gleich
outputintent.

7.5 Tagged PDF
Bei Tagged PDF handelt es sich um eine PDF-Erweiterung, auf deren Basis verschiedene
Zusatzfunktionen in PDF-Viewern implementiert wurden. Dazu gehören zum Beispiel
Accessibility (Barrierefreiheit), Umfließen von Text sowie zuverlässige Textextraktion
und -konvertierung in andere Dokumentformate wie RTF oder XML.
PDFlib unterstützt die Erzeugung von Tagged PDF. Dies ist jedoch nur möglich, wenn
der Client Informationen über die interne Dokumentstruktur liefert und sich bei der
Generierung der PDF-Ausgabe an bestimmte Regeln hält.
Hinweis PDFlib unterstützt gegenwärtig keine selbstdefinierten Typen für Strukturelemente (das heißt,
es können nur die in PDF definierten Standardtypen für Strukturelemente verwendet werden),
Rollenzuordnungen (role maps) und Strukturelementattribute.
7.5.1 Erzeugung von Tagged PDF mit PDFlib

Erforderliche Operationen. Tabelle 7.8 zeigt alle Operationen, die zur Generierung von
Tagged-PDF-Ausgabe erforderlich sind. Fehlt im Tagged-PDF-Modus eine dieser Operati-
onen, wird eine Exception ausgelöst.
Tabelle 7.8 Operationen, die zur Generierung von Tagged-PDF-Ausgabe erforderlich sind
Thema Für Tagged-PDF-Kompatibilität erforderliche PDFlib-Funktionen und -Parameter
Tagged-PDF-Ausgabe In PDF_begin_document( ) muss die Option tagged auf true gesetzt sein.
Dokumentsprache In PDF_begin_document( ) muss mit der Option lang die Dokumentsprache gesetzt
werden. Diese muss anfangs für das Gesamtdokument festgelegt werden, lässt sich aber
später für einzelne Elemente in beliebigen Strukturebenen ändern.
Strukturinformation Strukturinformationen und Artefakte müssen als solche erkennbar sein. Alle API-
Funktionen, die Inhalte erzeugen, sollten in PDF_begin_item( ) und PDF_end_item( )
eingeschlossen werden.
Unicode-kompatible Textausgabe. Bei der Erzeugung von Tagged PDF, dürfen bei der
Textausgabe nur Unicode-kompatible Schriften verwendet werden (siehe Abschnitt
4.5.6, »Unicode-kompatible Fonts«, Seite 113). Das bedeutet, dass alle Zeichen der benutz-
ten Fonts Unicode-Werten zugeordnet sein müssen. Nicht Unicode-kompatible Fonts
sind nur zulässig, wenn in PDF_begin_item( ) mit den Optionen ActualText oder Alt alter-
nativer Textinhalt angegeben wird. PDFlib löst eine Exception aus, wenn bei der Gene-
rierung von Tagged PDF Text ohne korrektes Unicode-Mapping verwendet wird.
Hinweis Manchmal erkennt PDFlib Probleme mit falsch kodierten Schriften nicht, zum Beispiel bei Sym-
bolfonts, die als Textfonts kodiert sind. Auch PostScript-Schriften mit bestimmten typografi-
schen Eigenheiten (zum Beispiel Expert-Fonts) werden aufgrund historisch bedingter Probleme
aller Wahrscheinlichkeit nach nicht akzeptiert.
Anordnung des Seiteninhalts. Die Reihenfolge der Text-, Vektorgrafik- und Rasterbild-
Operatoren, die den Seiteninhalt definieren, wird als physische Anordnung der Inhalte
bezeichnet; die durch den logischen Strukturbaum definierte Reihenfolge wird logische
Anordnung genannt. Bei der Generierung von Tagged PDF muss der Client bestimmte
Regeln bezüglich der Anordnung der Inhalte beachten.
7.5 Tagged PDF 207

Empfehlenswert ist die nahe liegende Methode, erst nacheinander alle Bestandteile
eines Strukturelements zu erzeugen und dann mit dem nächsten Element fortzufah-
ren. Technisch ausgedrückt sollte der Strukturbaum während eines einzigen »Depth-
First«-Durchlaufs generiert werden.
Eine andere, jedoch nicht ratsame Methode besteht darin, erst einige Bestandteile
des ersten Elements auszugeben, dann Teile des nächsten Elements, danach wieder zum
ersten Element zurückzukehren etc. Bei dieser Variante wird der Strukturbaum in meh-
reren Durchläufen angelegt, wobei bei jedem Durchlauf immer nur einige Teile eines
Elements erzeugt werden.
Importieren von Seiten mit PDI. Seiten aus Tagged-PDF- oder PDF-Dokumenten mit
Strukturinformationen können im Tagged-PDF-Modus nicht importiert werden, da die
importierte Dokumentstruktur und die generierte Struktur nicht zusammenpassen.
Seiten aus nicht strukturierten Dokumenten lassen sich dagegen importieren. Be-
achten Sie, dass diese von der Zugriffsfunktion von Acrobat »wörtlich« genommen wer-
den, sofern sie nicht mit passendem ActualText versehen sind.
Artefakte. Grafik- oder Textobjekte, die nicht zum vom Autor selbst verfassten Inhalt
gehören, werden Artefakte genannt. Artefakte sollten mit dem Pseudo-Tag Artifact als
solche gekennzeichnet und in eine der folgenden Kategorien eingeordnet werden:
> Pagination: Eigenschaften wie laufende Kopfzeile oder Seitenzahlen
> Layout: typografische oder Designelemente wie Linien oder Tabellenschattierungen
> Page: Produktionshilfen wie Beschnittmarken oder Farbauszüge
Die Kennzeichnung von Artefakten ist zwar nicht zwingend notwendig, aber doch rat-
sam, da sie beim Umfließen von Text und zur Barrierefreiheit (Accessibility) hilfreich
ist.
Inline-Elemente. PDF definiert Block-Level-Strukturelemente (BLSE) und Inline-Level-

Strukturelemente (ILSE); eine genaue Definition finden Sie in Tabelle 8.57. BLSEs können
weitere BLSEs oder tatsächlichen Inhalt enthalten, während ILSEs stets Inhalt enthalten.
Außerdem gibt es in PDFlib die in Tabelle 7.9 aufgeführten Unterschiede.
Tabelle 7.9 Reguläre und Inline-Elemente

Reguläre Elemente Inline-Elemente
betroffene Elemente alle Gruppierungselemente alle ILSEs und Nicht-Struktur-Tags
und BLSEs (Pseudo-Tags)
Status regulär/inline änderbar nein nur für ASpan-Elemente
Teil des Dokumentstrukturbaums ja nein
kann über die Seite hinausreichen ja nein
von anderen Elementen unterbrechbar ja nein
deaktivier- und aktivierbar ja nein
beliebig verschachtelbar ja nur mit anderen Inline-Elementen
Mit der Option inline in PDF_begin_item( ) entscheidet der Client, ob ASpan-Elemente re-
gulär oder inline sind. Ein Accessilibility-Span sollte zum Beispiel regulär (inline=false)
sein, wenn ein Absatz, der sich über mehrere Seiten erstreckt, verschiedene Sprachen
enthält. Alternativ dazu könnte das Element beendet und auf der nächsten Seite ein

neues Element begonnen werden. Inline-Elemente müssen auf der Seite, auf der sie be-
gonnen wurden, auch geschlossen werden.
Optionale Operationen. Tabelle 7.10 zeigt alle Operationen, die bei Bedarf zur Generie-
rung von Tagged-PDF-Ausgabe verwendet werden können. Diese Funktionen sind nicht
unbedingt erforderlich, aber empfehlenswert, da sie die Qualität der generierten
Tagged-PDF-Ausgabe erhöhen.
Tabelle 7.10 Bei der Erzeugung von Tagged PDF optionale Operationen
Thema Für Tagged-PDF-Kompatibilität optionale PDFlib-Funktionen und -Parameter
Trennung Wortumbrüche (Aufspaltung eines Wortes in zwei Teile am Zeilenende) sollten durch ein
weiches Trennzeichen (soft hyphen, U+00A0) und nicht durch ein hartes Trennzeichen
(U+002D) dargestellt werden.
Wortgrenzen Wörter sollten durch Leerzeichen (U+0020) getrennt werden, auch wenn dies zur
Positionierung nicht unbedingt erforderlich ist. Mit dem Parameter autospace können
nach jedem Aufruf einer der show-Funktionen automatisch Leerzeichen erzeugt werden.
Artefakte Um tatsächlichen Inhalt von Seitenartefakten zu unterscheiden, sollten Artefakte auch
als solche gekennzeichnet werden, und zwar mit PDF_begin_item( ) und tag=Artifact.
Unzulässige Operationen. Tabelle 7.11 zeigt alle Operationen, die bei der Generierung
von Tagged-PDF-Ausgabe unzulässig sind. Beim Aufruf einer unzulässigen Funktion im
Tagged-PDF-Modus wird eine Exception ausgelöst.
Tabelle 7.11 Bei der Generierung von Tagged PDF unzulässige Operationen
Thema Für Tagged-PDF-Kompatibilität unzulässige PDFlib-Funktionen und -Parameter
nicht Unicode- Schriften, die nicht Unicode-kompatibel sind gemäß Abschnitt 4.5.6, »Unicode-kom-
kompatible Schriften patible Fonts«, Seite 113, dürfen nicht verwendet werden.
PDF-Import Seiten aus PDF-Dokumenten, die Strukturinformationen enthalten (speziell Tagged-PDF-
Dokumente), dürfen nicht importiert werden.
7.5.2 Erzeugung von Tagged-PDF-Textausgabe und -Textflüssen

Primitives Tagged-PDF-Beispiel. Der folgende Beispielcode erzeugt ein recht primiti-
ves Tagged-PDF-Dokument, dessen Strukturbaum lediglich das Element P enthält. Mit-
hilfe der autospace-Funktion werden automatisch Leerzeichen zwischen einzelnen Text-
fragmenten erzeugt:
if (PDF_begin_document(p, "hello-tagged.pdf", 0, "tagged=true lang=en") == -1)
{
printf("Error: %s\n", PDF_get_errmsg(p));
return(2);
}
/* zwischen Textteilen automatisch Leerzeichen erzeugen */

PDF_set_parameter(p, "autospace", "true");
/* erstes Strukturelement als Kind der Dokumentstrukturwurzel öffnen (=0) */

id = PDF_begin_item(p, "P", "Title = {Simple Paragraph}");
PDF_begin_page_ext(p, 0, 0, "width=a4.width height=a4.height");

font = PDF_load_font(p, "Helvetica-Bold", 0, "host", "");
7.5 Tagged PDF 209

PDF_show_xy(p, "Hello, Tagged PDF!", 50, 700);
PDF_continue_text(p, "This PDF has a very simple");
PDF_continue_text(p, "document structure.");
PDF_end_item(p, id);
PDF_end_document(p, "");
Erzeugung von Tagged PDF mit Textflüssen. Textflüsse (siehe Abschnitt 4.9, »Mehrzei-
lige Textflüsse«, Seite 131) bietet leistungsfähige Funktionen zur Textformatierung. Da
sich einzelne Textfragmente nicht mehr unter Clientkontrolle befinden, sondern auto-
matisch von PDFlib formatiert werden, muss bei der Generierung von Tagged PDF mit
Textflüssen besondere Sorgfalt aufgewendet werden:
> Textflüsse können keine einzelnen Strukturelemente enthalten, aber ein Textfluss
kann in einem Strukturelement enthalten sein.
> Alle Teile eines Textflusses (alle Aufrufe von PDF_fit_textflow( ) mit einem bestimm-
ten Textfluss-Handle) sollten sich innerhalb desselben Strukturelements befinden.
> Da sich ein Textfluss über mehrere Seiten erstrecken kann, die unterschiedliche
Strukturelemente enthalten, sollte das Elternelement mit Bedacht gewählt und
nicht einfach der Parameterwert -1 verwendet werden, der auf das falsche Elternele-
ment verweisen könnte.
7.5.3 Aktivierung von Elementen für komplexe Layouts

Um die Erstellung von Strukturinformationen bei komplexen nicht-linearen Seitenlay-
outs zu erleichtern, unterstützt PDFlib ein Verfahren namens Elementaktivierung. Da-
mit lässt sich ein bereits erzeugtes Strukturelement nachträglich aktivieren. Dies ist in
Situationen sinnvoll, wo der Entwickler den Überblick über mehrere Strukturbäume be-
halten muss, die sich jeweils über eine oder mehrere Seiten erstrecken. Von Vorteil ist
dieses Verfahren zum Beispiel in folgenden Fällen:
> Die Seite besteht aus mehreren Spalten.
> Der Haupttext ist unterbrochen, z.B. durch Kurzübersichten oder Einschübe.
> Tabellen und Abbildungen sind zwischen die Spalten platziert.
Das Aktivierungsverfahren bietet dafür eine verbesserte Technik zur Generierung des
Seiteninhalts, indem zwischen den logischen Zweige des Baumes hin- und hergeschal-
tet wird. Dies ist um einiges effizienter als erst einen Baum komplett abzuarbeiten, be-
vor mit dem nächsten begonnen wird. Betrachten Sie zur Veranschaulichung des Akti-
vierungsverfahrens Abbildung 7.1. Sie enthält zweispaltigen Haupttext, der durch eine
Tabelle und eingeschobene Anmerkungen in einem Kasten (mit dunklem Hintergrund)
unterbrochen wird. Außerdem gibt es eine Kopf- und eine Fußzeile.
Erzeugung von Seiteninhalt in logischer Reihenfolge. Von der logischen Struktur her
sollte der Seiteninhalt in folgender Reihenfolge erzeugt werden: linke Spalte, rechte
Spalte (auf der Seite unten rechts), Tabelle, Einschub, Kopfzeile und Fußzeile. Der fol-
gende Pseudo-Code implementiert diese Anordnung:
/* Seitenlayout in logischer Reihenfolge erzeugen */
id_art = PDF_begin_item(p, "Art", "Title = Article");

id_sect1 = PDF_begin_item(p, "Sect", "Title = {First Section}");
/* 1 oberen Teil der linken Spalte erzeugen */
PDF_set_text_pos(p, x1_left, y1_left_top);
...
/* 2 unteren Teil der linken Spalte erzeugen */
PDF_set_text_pos(p, x1_left, y1_left_bottom);
...
/* 3 oberen Teil der rechten Spalte erzeugen */
PDF_set_text_pos(p, x1_right, y1_right_top);
...
PDF_end_item(p, id_sect1);
id_sect2 = PDF_begin_item(p, "Sect", "Title = {Second Section}");

/* 4 unteren Teil der rechten Spalte erzeugen */
PDF_set_text_pos(p, x2_right, y2_right);
...
/* zweiter Abschnitt kann sich über die nächste(n) Seite(n) erstrecken */
sprintf(optlist, "Title=Table parent=%d", id_art);

id_table = PDF_begin_item(p, "Table", optlist);
/* 5 Tabellenstruktur und -inhalt erzeugen */
PDF_set_text_pos(p, x_start_table, y_start_table);
...
PDF_end_item(p, id_table);
sprintf(optlist, "Title=Insert parent=%d", id_art);

id_insert = PDF_begin_item(p, "P", optlist);
/* 6 Einschubstruktur und -inhalt erzeugen */
...
PDF_end_item(p, id_insert);
id_artifact = PDF_begin_item(p, "Artifact", "");

/* 7+8 Kopf- und Fußzeile erzeugen */
PDF_set_text_pos(p, x_header, y_header);
...
PDF_set_text_pos(p, x_footer, y_footer);
...
PDF_end_item(p, id_artifact);
/* Artikel kann sich über die nächste(n) Seite(n) erstrecken */

...
PDF_end_item(p, id_art);
7.5 Tagged PDF 211

7 1
1 2
Abb. 7.1
6 5
Erzeugung eines komple-
xen Seitenlayouts in logi-
5 3
scher (links) sowie in visu-
eller Reihenfolge der
Strukturelemente (rechts).
Die rechte Variante arbei-
tet mit Elementaktivie-
2 3 4 6
rung für den ersten Ab-
schnitt, bevor mit den
4 7
Fragmenten 4 und 6 fort-
gefahren wird. 8 8
Erzeugung von Seiteninhalt in visueller Reihenfolge. Bei der Methode mit »logischer
Reihenfolge« muss der Ersteller die Seiteninhalte auch dann in logischer Anordnung
aufbauen, wenn die visuelle Reihenfolge einfacher zu erzeugen wäre: Kopfzeile, linke
Spalte oberer Teil, Tabelle, linke Spalte unterer Teil, Einschub, rechte Spalte, Fußzeile.
Mit PDF_activate_item( ) lässt sich diese Anordnung wie folgt implementieren:
/* Seitenlayout in visueller Anordnung erzeugen */
id_header = PDF_begin_item(p, "Artifact", "");

/* 1 Kopfzeile erzeugen */
PDF_set_text_pos(p, x_header, y_header);
...
PDF_end_item(p, id_header);
id_art = PDF_begin_item(p, "Art", "Title = Article");
id_sect1 = PDF_begin_item(p, "Sect", "Title = {First Section}");

/* 2 oberen Teil der linken Spalte erzeugen */
PDF_set_text_pos(p, x1_left, y1_left_top);
...
sprintf(optlist, "Title=Table parent=%d", id_art);

id_table = PDF_begin_item(p, "Table", optlist);
/* 3 Tabellenstruktur und -inhalt erzeugen */
...
PDF_end_item(p, id_table);
/* continue with first section */

PDF_activate_item(p, id_sect1);
/* 4 unteren Teil der linken Spalte erzeugen */
PDF_set_text_pos(p, x1_left, y1_left_bottom);
...
sprintf(optlist, "Title=Insert parent=%d", id_art);

id_insert = PDF_begin_item(p, "P", optlist);
/* 5 Einschubstruktur und -inhalt erzeugen */
...
PDF_end_item(p, id_insert);
/* weitere Inhalte für den ersten Abschnitt */

PDF_activate_item(p, id_sect1);
/* 6 oberen Teil der rechten Spalte erzeugen */
PDF_set_text_pos(p, x1_right, y1_right_top);
...
id_sect2 = PDF_begin_item(p, "Sect", "Title = {Second Section}");

/* 7 unteren Teil der rechten Spalte erzeugen */
PDF_set_text_pos(p, x2_right, y2_right);
...
/* zweiter Abschnitt kann sich über die nächste(n) Seite(n) erstrecken */
id_footer = PDF_begin_item(p, "Artifact", "");

/* 8 Fußzeile erzeugen */
PDF_set_text_pos(p, x_footer, y_footer);
...
PDF_end_item(p, id_footer);
/* Artikel kann sich über die nächste(n) Seite(n) erstrecken */

...
PDF_end_item(p, id_art);
Bei dieser Reihenfolge der Strukturelemente wird der Haupttext (der sich über andert-
halb Spalten erstreckt) zweimal unterbrochen, einmal durch die Tabelle und einmal
durch den Einschub. Deswegen muss er auch zweimal mit PDF_activate_item( ) aktiviert
werden.
Dasselbe Verfahren kommt zum Einsatz, wenn sich der Inhalt über mehrere Seiten
erstreckt. In diesem Fall können die Kopfzeile und andere Einschübe zuerst erzeugt und
dann das Inhaltselement der Hauptseite erneut aktiviert werden.
7.5.4 Verwendung von Tagged PDF in Acrobat

In diesem Abschnitt schildern wir unsere Beobachtungen beim Testen von Tagged-PDF-
Ausgabe in Adobe Acrobat 6.0. Es handelt sich meist um fehlerhaftes oder inkonsisten-
tes Verhalten von Acrobat. Wo wir Abhilfe schaffen konnten, ist dies angemerkt.
Umfließen von Text in Acrobat. Acrobat ermöglicht in Tagged-PDF-Dokumenten das

Umfließen von Text, das heißt, die Anpassung des Seiteninhalts an die aktuelle Fenster-
größe. Beim Testen von Tagged PDF fiel uns Folgendes im Hinblick auf die Umfließen-
Funktion auf:
> Die Reihenfolge des Inhalts auf der Seite sollte der gewünschten Umfließen-Reihen-
folge entsprechen.
> Symbol-Schriften (nicht Unicode-Fonts) können die Umfließen-Funktion von Acro-
bat zum Absturz bringen. Aus diesem Grund sollte man den Text in ein Figure-Ele-
ment packen.
7.5 Tagged PDF 213

> BLSEs können sowohl Kind-Strukturelemente als auch direkte Inhaltselemente ent-
halten. Damit die Umfließen-Funktion (sowie Zugriffsprüfung und Sprachausgabe)
funktionieren, sollten die direkten Elemente vor das erste Kindelement platziert
werden.
> Für Tabellen und Abbildungen sollte die Option BBox übergeben werden. Die BBox
sollte exakt sein, wobei bei Tabellen nur die untere linke Ecke exakt gesetzt werden
muss. Als Alternative zur Übergabe eines BBox-Eintrags können Grafiken auch mit
einem BLSE-Tag wie P, H etc. erzeugt werden. Vektorgrafiken werden jedoch nicht an-
gezeigt, wenn Umfließen aktiviert ist. Wird die Option BBox vom Client nicht unter-
stützt (sondern automatische BBox-Generierung verwendet), müssen grafische Ta-
bellenkomponenten wie die Zellenränder außerhalb des Tabellenelements
gezeichnet werden.
> Tabellenelemente sollten als Kindelemente nur tabellenspezifische Elemente (TR,
TD, TH, THead, TBody, etc.) enthalten. Ein Caption-Element in einer Tabelle kann bei-
spielsweise zu Problemen beim Umfließen führen, obwohl es sich um korrektes
Tagged PDF handelt.
> Inhalte, die durch das Private-Tag abgedeckt sind, lassen sich nicht in andere Formate
exportieren. Sie werden jedoch beim Umfließen und der Sprachausgabe berücksich-
tigt. Abbildungen innerhalb des Private-Tags müssen deshalb über Alternativtext
verfügen.
> Importierte Bilder sollten durch ein Figure-Element abgedeckt sein, und importierte
PDF-Seiten durch ein Form-Element. Der Elementtyp Formula macht beim Umfließen
Probleme und sollte deshalb vermieden werden.
> Außerdem scheint es Probleme mit PDF-Dokumenten zu geben, die mit der Option
topdown erstellt wurden.
> Strukturelemente mit verschiedenen Typen von Kindelementen (das heißt sowohl
Folgen von Seiteninhalt als auch Nicht-Inline-Strukturelemente) sollten nicht ver-
wendet werden, da sie beim Umfließen unter Umständen fehlerhaft behandelt wer-
den.
> Enthält ein aktiviertes Element nur Inhalte, aber keine Kind-Strukturelemente,
scheitert das Umfließen möglicherweise. Dies ist insbesondere dann der Fall, wenn
das Element auf einer anderen Seite aktiviert wurde. Das Problem lässt sich umge-
hen, indem das aktivierte Element nicht inline mit einem Span-Tag umgeben wird.
Zugriffsprüfung von Acrobat. Mit der Zugriffsprüfung von Acrobat lässt sich feststel-
len, ob Tagged-PDF-Dokumente für den Einsatz mit Hilfsmitteln wie Sprachausgabe-
geräte geeignet sind.
> Elemente, die ein importiertes Bild enthalten, sollten die Eigenschaft Alt verwenden.
Die Eigenschaft ActualText kann die Zugriffsprüfung zum Absturz bringen. Ein weite-
rer Vorteil von Alt gegenüber ActualText ist, dass die Sprachausgabe den tatsächli-
chen Text erhält.
> Ist das erste Element auf der Seite ein Form-Tag für eine importierte PDF-Seite, kann
dies zu Problemen bei der Zugriffsprüfung führen.
> Ist das Lbl-Tag innerhalb des TOCI-Tags gesetzt (so wie in der PDF-Referenz beschrie-
ben), gibt die Zugriffsprüfung eine Warnung darüber aus, dass das Lbl-Tag nicht in-
nerhalb eines LI-Tags gesetzt wurde.
Export in andere Formate mit Acrobat. Mit Tagged PDF werden PDF-Dokumente in
Acrobat erheblich besser in andere Formate exportiert.

> Enthält eine importierte PDF-Seite das Form-Tag, wird in Acrobat der mit der Option
ActualText übergebene Text in andere Formate exportiert, der mit dem Alt-Tag über-
gebene Text dagegen ignoriert. Die Sprachausgabe berücksichtigt jedoch beide Opti-
onen.
> Elemente, die eine importierte Seite enthalten, sollten die Eigenschaft Alt anstelle
von ActualText verwenden, damit beim Exportieren auch der tatsächliche Text ver-
wendet wird.
> Der Inhalt eines NonStruct-Tags wird nicht nach HTML 4.01 CSS 1.0 exportiert (wird
aber beim HTML 3.2-Export verwendet).
> Für ILSEs (wie Code, Quote oder Reference) sollte ein Alternativtext übergeben werden.
Wird die Option Alt verwendet, liest die Sprachausgabe zwar den übergebenen Text,
es wird aber der tatsächliche Inhalt in andere Formate exportiert. Wird die Option
ActualText verwendet, wird der übergebene Text sowohl bei der Sprachausgabe als
auch beim Export verwendet.
Sprachausgabe von Acrobat. Tagged PDF ermöglicht eine verbesserte Sprachausgabe

in Acrobat.
> Bei der Verwendung von Alt oder ActualText sollte man am Textanfang ein Leerzei-
chen einfügen, damit die Sprachausgabe den Text vom vorangehenden Satz abgren-
zen kann. Aus demselben Grund ist es sinnvoll, am Ende einen Punkt ’.’ anzufügen,
da die Sprachausgabe das letzte Wort des vorangehenden Satzes sonst in Verbindung
mit dem ersten Wort des Alternativtextes liest.
7.5 Tagged PDF 215

8 API-Referenz für PDFlib, PDI und PPS
In der PDFlib-API-Referenz werden alle unterstützten Funktionen von PDFlib, PDI (PDF
Import Library) und PPS (PDFlib Personalization Server) beschrieben.
8.1 Datentypen und Namenskonventionen

8.1.1 Datentypen in PDFlib
Welche genaue Syntax für eine bestimmte Sprachbindung zu verwenden ist, kann im
Einzelfall geringfügig von der in dieser Referenz beschriebenen C-Syntax abweichen.
Dies gilt insbesondere für den PDF-Dokumentparameter (PDF * in der PDFlib-Referenz),
der bei fast allen PDFlib-Funktionen in der C-Sprachbindung als erstes Argument über-
geben werden muss. Dies trifft aber nicht auf Sprachbindungen zu, die den PDF-Doku-
mentparameter in einem vom Sprachwrapper erzeugten Objekt verbergen.
Tabelle 8.1 zeigt den Einsatz des PDF-Dokumenttyps und des String-Datentyps in al-
len Sprachbindungen. Die Datentypen integer, long und float werden hier nicht erwähnt,
da sie in allen Sprachbindungen auf die nahe liegenden Entsprechungen abgebildet
werden. Sprachspezifische Einzelheiten finden Sie in den Abschnitten mit den sprachli-
chen Eigenheiten sowie in den Beispielen in Kapitel 2.
Tabelle 8.1 Datentypen in den verschiedenen Sprachbindungen

Sprachbindung p-Parameter? Präfix PDF_? String-Datentyp Binärdatentyp
1
C (wird hier in der ja ja const char * const char *
Referenz verwendet)
C++ nein nein string2 char *
3 4
Cobol ja nein STRING STRING
Java nein nein String byte[ ]
.NET nein nein String byte[ ]
Perl ja ja string string
PHP ja ja string string
PHP 5 (objekt- nein nein string string
orientiert)
Python ja ja string string
RPG ja ja string, aber x’00’ muss data
angehängt werden
Ruby nein nein string string
Tcl ja ja string Byte-Array
1. In der C-Bindung werden NULL-Strings und leere Strings als gleich angesehen.
2. NULL-Strings dürfen in der C++-Bindung nicht verwendet werden.
3. Weitere Hinweise zu Datentypen in Cobol finden Sie in Abschnitt 2.2.1, »Besondere Hinweise für Cobol«, Seite 22.
4. Cobol-Programme müssen Kurznamen für die PDFlib-Funktionen verwenden.
Unicode-Strings. PDFlib akzeptiert Unicode-Strings in allen relevanten Bereichen, wo-

bei verschiedene Unicode-Formate und -Einstellungen unterstützt werden. Einzelhei-
ten hierzu finden Sie in Abschnitt 4.5.2, »Content-Strings, Hypertext-Strings und Name-
Strings«, Seite 106. Achten Sie in diesem Zusammenhang auf folgende String-Typen:

> Content-Strings
> Hypertext-Strings
> Name-Strings
Namenskonventionen für PDFlib-Funktionen. In der C-Bindung befinden sich alle

PDFlib-Funktionen in einem globalen Namensraum, in dem ihre Namen zur Vermei-
dung von Namenskonflikten prinzipiell mit PDF_ beginnen. In verschiedenen anderen
Sprachbindungen wird der PDF-Dokumentparameter in einem vom Sprachwrapper er-
zeugten Objekt verborgen. In diesem Fall müssen Sie den in dieser Referenz angegebe-
nen Funktionsnamen schematisch anpassen, indem Sie das Präfix PDF_ entfernen. Au-
ßerdem lassen Sie den Parameter PDF * als erstes Argument weg. Eine Funktion wird
zum Beispiel in C-Manier beschrieben als:
PDF *p;
PDF_begin_document(PDF *p, const char *filename, const char *optlist);
Wird dieselbe Funktion jedoch von Java aus verwendet, dann sieht der Aufruf folgen-
dermaßen aus:
pdflib p;
p.begin_document(String filename, String optlist);
8.1.2 Optionslisten
Optionslisten bieten einen ebenso leistungsfähigen wie einfachen Mechanismus,
um PDFlib-Operationen zu steuern. Sie werden von vielen PDFlib-API-Methoden unter-
stützt, damit man es sich ersparen kann, unzählige Funktionsparameter zu übergeben.
Optionslisten (optlists) sind Strings, die beliebig viele Optionen enthalten können. Da sie
von links nach rechts ausgewertet werden, kann eine Option in der Liste mehrmals auf-
treten; in solchen Fällen wird der zuletzt eingestellte Wert genommen. Optionslisten
unterstützen verschiedene Datentypen und zusammengesetzte Datenstrukturen wie
Arrays. In den meisten Sprachen lassen sich Optionslisten problemlos durch Konkate-
nieren der erforderlichen Schlüsselwörter und Werte bilden. C-Programmierer können
dazu die Funktion sprintf( ) nutzen.
Eine Optionsliste ist ein String, der ein oder mehrere Paare folgender Form enthält:
name wert
Name und Wert sowie Name-Wert-Paare können durch Leerzeichen, Tabulator, Carriage
Return oder Newline getrennt werden. Ein Wert wiederum kann aus mehreren Werten
bestehen. Sie können zwischen Name und Wert auch ein Gleichheitszeichen ’=’ setzen.
name=wert
Besteht der Wert aus einem String mit Leer- oder Gleichheitszeichen, muss der String in
geschweifte Klammern eingeschlossen werden:
key={mehrere Wörter}
key={wert=enthält=Gleichheitszeichen}
Optionslisten, die Listen aus Suboptionen enthalten, benötigen ein zusätzliches Paar
geschweifter Klammern, auch wenn die innere Liste nur aus einem einzigen Element
besteht:
218 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

key={{wert}}
Da Optionslisten von links nach rechts ausgewertet werden, kann eine Option in der
Liste mehrfach übergeben werden. In diesem Fall hat das letzte Auftreten der Option
Vorrang vor früheren Auftritten. Im folgenden Beispiel wird die erste Wertzuweisung
an die Option key durch die zweite überschrieben, und key besitzt nach Verarbeitung der
Optionsliste den Wert 2:
key=1 key=2
Optionslisten unterstützen die Datentypen in Tabelle 8.2. Die Datentypen werden aus-
führlich weiter unten erläutert.
Table 8.2 Datentypen in Optionslisten

Kategorie Datentypen
einfach Boolean, String, Content-/Hypertext-/Name-String, Unichar, Schlüsselwort, Float, Integer,
Handle
komplex Listenwerte, Rechtecke, Aktionslisten, Farbe
Einfache Werte. Bei einfachen Werten sind folgende Datentypen möglich:

> Boolean: true oder false; wird bei einer Option Booleschen Typs kein Wert angegeben,
wird von true ausgegangen. Als abkürzende Schreibweise kann noname statt
name=false verwendet werden.
> String: reine ASCII-Strings, wie sie im Allgemeinen für nicht lokalisierbare Schlüssel-
wörter verwendet werden. Strings, die Leer- oder Gleichheitszeichen (=) enthalten,
müssen mit { und } geklammert werden. Ein leerer String lässt sich durch { } darstel-
len. Vor den Zeichen {, } und \ muss ein Gegenschrägstrich \ stehen, wenn sie zum
String gehören sollen.
> Content-Strings, Hypertext-Strings und Name-Strings: können Unicode-Inhalt in
verschiedenen Formaten enthalten; Einzelheiten über diese String-Typen finden Sie
in Abschnitt 4.5, »Unicode-Unterstützung«, Seite 105.
> Unichar: einzelne Unicode-Zeichen, wobei mehrere syntaktische Varianten unter-
stützt werden: Dezimalzahlen (z.B. 173), Hexadezimalzahlen, die mit x, X, 0x, 0X oder
U+ beginnen (xAD, 0xAD, U+00AD), numerische oder Character-Referenzen entspre-
chend Abschnitt 4.5.5, »Character-Referenzen«, Seite 111, aber ohne Auszeichnung
durch ’&’ oder ’;’ (shy, #xAD, #173). Unichars müssen im Bereich 0-65535 (0-xFFFF) lie-
gen.
> Schlüsselwort: ein fester Wert aus einer vordefinierten Schlüsselwortliste
> Float und Integer: dezimale Gleitkomma- oder Ganzzahlen; zur Trennung von Vor-
und Nachkommastellen sind Punkt und Komma zulässig. Um Hexadezimalzahlen
zu speichern, können Integer-Werte mit x, X, 0x oder 0X beginnen. Manche Optionen
(wenn entsprechend erwähnt) unterstützen Prozentangaben durch Anfügen eines
Prozentzeichens % direkt nach dem Wert.
> Handle: mehrere PDFlib-interne Objekt-Handles, zum Beispiel Font-, Image- oder Ac-
tion-Handles. Rein technisch gesehen handelt es sich dabei immer um Integer-Zah-
len.
Abhängig vom Typ und von der Interpretation kann eine Option weiteren Einschrän-
kungen unterliegen. Optionen vom Typ Integer oder Float sind manchmal auf be-

stimmte Wertebereiche beschränkt; Handles gelten nur für den entsprechenden Ob-
jekttyp etc. Wenn Optionen besonderen Bedingungen unterliegen, so wird dies in der
jeweiligen Beschreibung erwähnt. Beispiele für einfache Werte sind (die erste Zeile zeigt
einen Passwort-String mit einem Leerzeichen):
PDF_open_pdi( ): password {secret string}
PDF_create_gstate( ): linewidth 0.5 blendmode overlay opacityfill 0.75
PDF_load_font( ): embedding=true subsetting=true subsetlimit=50 kerning=false
PDF_load_font( ): embedding subsetting subsetlimit=50 nokerning
PDF_create_textflow( ) leading=150%
PDF_create_textflow( ) charmapping={ 0x0A 0x20 }
Listenwerte. Listenwerte bestehen aus mehreren Werten, die einfache Werte oder wie-
derum Listenwerte sein können. Listen werden mit { und } geklammert. Beispiele für Lis-
tenwerte sind:
PDF_fit_image( ): boxsize {500 600} position {50 0}
PDF_create_gstate( ): dasharray {11 22 33}
PDF_create_annotation( ): polylinelist={{10 20 30 40}}
Rechtecke. Ein Rechteck besteht aus einer Liste von vier Float-Werten, die die Koordi-
naten der linken unteren und der rechten oberen Ecke des Rechtecks festlegen. Das Ko-
ordinatensystem zur Interpretation der Rechteckskoordinaten (Standard- oder Benut-
zerkoordinatensystem) kann je nach Option unterschiedlich sein und wird deswegen
bei der jeweiligen Option beschrieben. Beispiel:
PDF_begin_document( ): cropbox {0 0 500 600}
Aktionslisten. Eine Aktionsliste legt eine oder mehrere Aktionen fest. Jeder Listenein-
trag besteht aus einem Ereignis-Schlüsselwort (Auslöser) und einer Liste von Action-
Handles, die mit PDF_create_action( ) zurückgegeben wurden. Aktionen werden in der
genannten Reihenfolge ausgeführt. Die Menge zulässiger Ereignisse (zum Beispiel
docopen) und der Aktionstyp (zum Beispiel JavaScript) werden bei der jeweiligen Option
beschrieben. Beispiele (unter der Annahme, dass die Werte 0, 1 und 2 von vorangehen-
den Aufrufen von PDF_create_action( ) zurückgegeben wurden:
PDF_begin_document( ): action {open 0}
PDF_create_bookmark( ): action {activate {0 1 2}}
PDF_create_field( ): action {keystroke 0 format 1 validate 2}
Farbe. Eine Farboption besteht aus einer Liste, die ein Farbraum-Schlüsselwort sowie
eine Liste aus Float-Werten enthalten, deren Anzahl vom jeweiligen Farbraum abhängt.
Farbraum-Schlüsselwörter werden dabei wie in PDF_setcolor( ) festgelegt (siehe Ab-
schnitt 8.5.1, »Festlegen von Farbe und Farbraum«, Seite 286), mögliche Werte werden in
Abschnitt 3.3.1, »Farben und Farbräume«, Seite 69, beschrieben:
> Die Farbraum-Schlüsselwörter gray, rgb und cmyk können mit einem, drei oder vier
Float-Werten angegeben werden.
> Das Farbraum-Schlüsselwort lab kann mit drei Float-Werten angegeben werden.
> Das Farbraum-Schlüsselwort spot kann mit einem Schmuckfarben-Handle und ei-
nem Wert für den Farbauftrag angegeben werden. Alternativ dazu kann das Far-
braum-Schlüsselwort spotname mit einem Schmuckfarbnamen und einem Float-
Wert für den Farbauftrag angegeben werden.

> Die Farbraum-Schlüsselwörter iccbasedgray, iccbasedrgb und iccbasedcmyk können
mit einem, drei oder vier Float-Werten angegeben werden.
> Das Farbraum-Schlüsselwort pattern kann mit einem Pattern-Handle angegeben
werden.
> Das Farbraum-Schlüsselwort none kann angegeben werden, um festzulegen, dass
keine Farbe vorhanden ist.
Wie bei den jeweiligen Funktionen in Kapitel 8 beschrieben, enthält eine Optionsliste
immer nur eine Teilmenge der oben dargestellten Schlüsselwörter. Beispiele für Farb-
werte sind:
PDF_fill_textblock( ): strokecolor={ rgb 1 0 0 }
PDF_fill_textblock( ): bordercolor=none
PDF_fill_textblock( ): fillcolor={ spotname {PANTONE 281 U} 0.5 }
PDF_fill_textblock( ): fillcolor={ spotname 1 0.8 }

8.2 Allgemeine Funktionen
8.2.1 Setup
Tabelle 8.3 enthält eine Übersicht aller für diesen Abschnitt relevanten Parameter und
Werte.
Tabelle 8.3 Parameter und Werte für Setup-Funktionen

Funktion Schlüssel Erklärung
set_parameter compatibility Veraltet. Verwenden Sie stattdessen die Option compatibility für PDF_begin_
document( ).
set_ pdfx Veraltet. Verwenden Sie stattdessen die Option pdfx für PDF_begin_document( ).
parameter
set_parameter flush Veraltet. Verwenden Sie stattdessen die Option flush für PDF_begin_document_
callback( ).
set_parameter SearchPath (In MVS nicht unterstützt) Relativer oder absoluter Pfadname eines Verzeichnisses,
das die einzulesenden Dateien enthält. SearchPath kann mehrfach gesetzt
werden; die Einträge werden in einer Liste zusammengefasst, die von hinten nach
vorne abgearbeitet wird (siehe Abschnitt 3.1.5, »Ressourcenkonfiguration und
Dateisuche«, Seite 56). Geltungsbereich: beliebig.
set_parameter prefix (Veraltet) Namenspräfix für die Ressourcendatei in einer UPR-Datei. Das Präfix
kann mehrfach gesetzt werden. Es enthält einen Schrägstrich sowie einen
Pfadnamen, der wiederum mit einem Schrägstrich beginnen kann. Geltungs-
bereich: beliebig.
set_parameter resourcefile Relativer oder absoluter Name der von PDFlib verwendeten UPR-Ressourcendatei.
Diese wird sofort geladen. Bereits vorhandene Ressourcen bleiben erhalten. Ihre
Werte werden gegebenenfalls von den neuen Werten überschrieben. Geltungs-
bereich: beliebig.
set_ asciifile (Nur auf iSeries und zSeries verfügbar.) Es werden Textdateien (PFA, AFM, UPR,
parameter Zeichensätze) in ASCII-Format erwartet. Standardwert: true auf iSeries; false auf
zSeries. Geltungsbereich: beliebig.
set_ license Setzt den Lizenzschlüssel für PDFlib, PDFlib+PDI oder PPS. Der Lizenzschlüssel kann
parameter (auch mehrfach) vor dem ersten Aufruf von PDF_begin_page( ) gesetzt werden.
Geltungsbereich: object.
set_ licensefile Setzt den Namen der Datei mit dem Lizenzschlüssel. Dieser kann nur einmal vor
parameter dem ersten Aufruf von PDF_begin_page_ext( ) festgelegt werden.
Geltungsbereich: object.
set_parameter nodemostamp Bei true wird eine Exception ausgelöst, falls kein gültiger Lizenzschlüssel gefunden
wurde; bei false wird auf allen Seiten ein Demostempel erzeugt. Diese Option
muss vor dem ersten Aufruf von PDF_begin_document( ) gesetzt werden.
Standardwert: false. Geltungsbereich: object
set_value compress Setzt den Kompressionsparameter. Dieser Parameter hat keinen Einfluss auf
vorkomprimierte Rasterbilddaten, die im Pass-Through-Modus bearbeitet
werden. Standardwert: 6. Geltungsbereich: page, document.
0 keine Kompression
1 maximale Geschwindigkeit
9 maximale Kompression
get_value major Gibt die Major-Versionsnummer, die Minor-Versionsnummer oder die
minor Revisionsnummer von PDFlib zurück. Geltungsbereich: beliebig, null1.
revision

Tabelle 8.3 Parameter und Werte für Setup-Funktionen
get_parameter version Gibt den vollständigen PDFlib-Versionsstring im Format
<major>.<minor>.<revision> zurück, an den ggf. noch weitere Kennungen (etwa
Beta, rc etc.) angefügt sind. Geltungsbereich: beliebig, null1.
get_parameter scope Gibt den Namen des aktuellen Geltungsbereichs zurück (siehe Tabelle 3.1).
Geltungsbereich: beliebig.
set_parameter trace (Nicht unterstützt) Wenn auf true gesetzt, werden alle API-Funktionen
protokolliert. Der Inhalt der Logdatei kann bei der Fehlersuche hilfreich sein oder
vom PDFlib-Support angefordert werden. Geltungsbereich: beliebig.
Standardwert: false.
set_parameter tracefile (Nicht unterstützt) Definiert den Namen der Trace-Datei. Geltungsbereich:
beliebig, aber bevor Tracing aktiviert wird. Standardwert: PDFlib.trace.
set_parameter logmsg (Nicht unterstützt) Ist Tracing aktiviert, wird der übergebene Nachrichtentext
zusätzlich zu den API-Aufrufen in die Logdatei geschrieben. Dies kann bei der
Fehlersuche im Clientcode sinnvoll sein. Geltungsbereich: beliebig.
1. Kann mit NULL oder 0 als PDF * Argument aufgerufen werden.
C void PDF_boot(void)
void PDF_shutdown(void)
Initialisiert bzw. beendet PDFlib.
Gültigkeit null
Bindungen C: Wird für die C-Sprachbindung empfohlen, wenngleich gegenwärtig nicht unbedingt
erforderlich.
Andere: Bei allen anderen Sprachbindungen wird das Starten und Beenden automatisch
vom Wrappercode durchgeführt. Daher sind diese Funktionen nicht verfügbar.
Perl PHP resource PDF_new( )

C PDF *PDF_new(void)
Erzeugt ein neues PDFlib-Objekt mit Standardeinstellungen.
Details Diese Funktion erzeugt ein neues PDFlib-Objekt, wobei es die PDFlib-internen Standard-
routinen zur Fehlerbehandlung und Speicherallozierung verwendet.
Rückgabe Handle auf ein PDFlib-Objekt, das dann in nachfolgenden PDFlib-Aufrufen verwendet
werden kann. Schlägt diese Funktion aufgrund von mangelndem Speicher fehl, wird
NULL (in C) zurückgegeben oder eine PDFlib-Exception ausgelöst.
Gültigkeit null; mit dieser Funktion beginnt der Geltungsbereich object, der immer mit einem
entsprechenden Aufruf von PDF_delete( ) beendet werden muss.
Bindungen Der Datentyp für das PDFlib-Objekt-Handle ist von der jeweiligen Sprachbindung ab-
hängig und für PDFlib-Clients an sich nicht weiter interessant, da diese das PDF-Handle
einfach unbesehen an alle Funktionen als erstes Argument weiterreichen.
C: Wenn Sie die PDFlib-DLL dynamisch zur Laufzeit laden möchten, verwenden Sie PDF_
new_dl( ) (siehe Abschnitt 2.4.3, »Einsatz von PDFlib als DLL, die zur Laufzeit geladen
wird«, Seite 27). PDF_new_dl( ) gibt einen Zeiger auf eine PDFlib_api-Struktur zurück, die

Zeiger auf alle PDFlib-API-Funktionen enthält. Wenn die DLL nicht geladen werden kann
oder Major- bzw. Minor-Versionsnummer nicht passen, wird NULL zurückgegeben.
C++, Java, PHP 5: Diese Funktion ist nicht verfügbar, da sie im PDFlib-Konstruktor ver-
borgen ist.
C PDF *PDF_new2(void (*errorhandler)(PDF *p, int errortype, const char *msg),

void* (*allocproc)(PDF *p, size_t size, const char *caller),
void* (*reallocproc)(PDF *p, void *mem, size_t size, const char *caller),
void (*freeproc)(PDF *p, void *mem),
void *opaque)
Erzeugt ein neues PDFlib-Objekt mit benutzerdefinierten Routinen zur Fehlerbehand-

lung und Speicherverwaltung.
errorhandler Zeiger auf eine benutzerdefinierte Fehlerbehandlungsfunktion. Die Feh-

lerbehandlungsfunktion wird in PDF_TRY/PDF_CATCH-Blöcken ignoriert.
allocproc Zeiger auf eine benutzerdefinierte Speicherallozierungsfunktion.
reallocproc Zeiger auf eine benutzerdefinierte Speicherreallozierungsfunktion.
freeproc Zeiger auf eine benutzerdefinierte Speicherfreigabefunktion.
opaque Zeiger auf Benutzerdaten, der mit PDF_get_opaque( ) abgefragt werden kann.
Rückgabe Handle auf ein PDFlib-Objekt, das dann in nachfolgenden PDFlib-Aufrufen verwendet
werden kann. Schlägt diese Funktion aufgrund von mangelndem Speicher fehl, wird
NULL (in C) zurückgegeben oder eine PDFlib-Exception ausgelöst.
Details Diese Funktion erzeugt ein neues PDFlib-Objekt mit benutzerdefinierten Funktionen
zur Fehlerbehandlung und Speicherverwaltung. Im Gegensatz zu PDF_new( ) kann der
Aufrufer bei Bedarf eigene Prozeduren zur Fehlerbehandlung und Speicherverwaltung
übergeben. Die Funktionszeiger für den Error-Handler oder die Speicherverwaltungs-
routinen können NULL sein. Es werden dann die PDFlib-Standardroutinen verwendet.
Es müssen entweder alle drei oder es darf keine Speicherverwaltungsroutine übergeben
werden.
Gültigkeit null; mit dieser Funktion beginnt der Geltungsbereich object, der immer mit einem
entsprechenden Aufruf von PDF_delete( ) beendet werden muss. Nach Aufruf dieser
Funktion darf keine andere PDFlib-Funktion mit demselben PDFlib-Objekt aufgerufen
werden.
Bindungen Diese Funktion ist nur in C und C++ verfügbar.

C++: Diese Funktion ist indirekt über den PDFlib-Konstruktor verfügbar. Fehlt ein Funk-
tionsargument, wird als Standardwert NULL übergeben. Alle übergebenen Funktionen
müssen C-Funktionen sein (C++-Methoden sind nicht erlaubt).

Perl PHP PDF_delete(resource p)
C void PDF_delete(PDF *p)
Löscht ein PDF-Objekt und gibt alle zugehörenden internen Ressourcen frei.
Details Diese Funktion löscht ein PDF-Objekt und gibt alle zum Dokument gehörenden PDFlib-
internen Ressourcen frei. Wenngleich es zur Generierung einzelner Dokumente nicht
erforderlich ist, sollte das PDF-Objekt jedoch in allen Serveranwendungen nach abge-
schlossener PDF-Erstellung unbedingt gelöscht werden. Diese Funktion darf für ein
PDF-Objekt nur einmal aufgerufen werden. PDF_delete( ) sollte außerdem zur Bereini-
gung nach einer Exception aufgerufen werden. PDF_delete( ) selbst löst unter keinen
Umständen eine Exception aus. Bei der Generierung mehrerer PDF-Dokumente muss
PDF_delete( ) nicht nach jedem einzelnen Dokument aufgerufen werden, sondern dies
kann auch nach der Generierung aller PDF-Dokumente erfolgen.
Gültigkeit beliebig; mit dieser Funktion beginnt der Geltungsbereich null, das heißt, es sind keine
weiteren Aufrufe von API-Funktionen mehr erlaubt.
Bindungen C: Wurde die PDFlib-DLL mit PDF_new_dl( ) dynamisch zur Laufzeit geladen, so ver-
wenden Sie PDF_delete_dl( ) zum Löschen des PDFlib-Objekts.
C++: Diese Funktion ist indirekt über den PDFlib-Destruktor verfügbar.
Java: Diese Funktion wird automatisch vom Wrappercode aufgerufen. Um Unzuläng-
lichkeiten im Finalizer-System von Java zu umgehen, kann sie jedoch auch explizit aus
dem Clientcode heraus aufgerufen werden.
PHP: diese Funktion wird automatisch für die objektorientierte PHP-5-Schnittstelle auf-
gerufen, wenn das PDFlib-Objekt den Geltungsbereich verlässt.
8.2.2 Dokument und Seite

Werte.
Tabelle 8.4 Parameter und Werte für Dokument- und Seitenfunktionen

set_ openwarning Veraltet. Um herauszufinden, warum das Öffnen eines Dokuments scheitert,
parameter verwenden Sie PDF_get_errmsg( ).
set_value pagewidth Veraltet. Verwenden Sie stattdessen die Parameter width und height für PDF_
pageheight begin_page_ext( ) oder die Option mediabox für PDF_begin_page_ext( ) bzw.
PDF_end_page_ext( ).
set_ topdown Ist topdown gleich true, wird zu Beginn einer Seite, eines Füllmusters oder eines
parameter Templates der Ursprung des Koordinatensystems in die linke obere Ecke der Seite
gelegt, und die y-Koordinaten wachsen nach unten hin; andernfalls wird das
Standardkoordinatensystem verwendet (siehe Abschnitt 3.2.1, »Koordinaten-
systeme«, Seite 62). Geltungsbereich: document. Standardwert: false.
get_value pagewidth Ermittelt die Größe der aktuellen Seite (Größe der MediaBox). Geltungsbereich:
pageheight page, path.

Tabelle 8.4 Parameter und Werte für Dokument- und Seitenfunktionen
set_value CropBox, Veraltet. Verwenden Sie stattdessen die Optionen artbox, bleedbox, cropbox bzw.
BleedBox, trimbox für PDF_begin_page_ext( ) bzw. PDF_end_page_ext( ).
ArtBox,
TrimBox
set_parameter userpassword Veraltet. Verwenden Sie stattdessen die Option userpassword für PDF_begin_
document( ).
set_parameter master- Veraltet. Verwenden Sie stattdessen die Option masterpassword für PDF_begin_
password document( ).
set_parameter permissions Veraltet. Verwenden Sie stattdessen die Option permissions für PDF_begin_
document( ).
C++ Java int begin_document(String filename, String optlist)

Perl PHP int PDF_begin_document(resource p, string filename, string optlist)
C int PDF_begin_document(PDF *p, const char *filename, int len, const char *optlist)
C++ void begin_document_callback(size_t (*writeproc) (PDF *p, void *data, size_t size),
string optlist)
C void PDF_begin_document_callback(PDF *p,
size_t (*writeproc) (PDF *p, void *data, size_t size), const char *optlist)
Erstellt anhand verschiedener Optionen eine neue PDF-Datei.
filename (Name-String, wobei Unicode-Dateinamen nur unter Windows unterstützt

werden) Absoluter oder relativer Name der zu generierenden PDF-Ausgabedatei. Ist
filename leer, wird das PDF-Dokument direkt im Arbeitsspeicher und nicht in einer Da-
tei erzeugt. In diesem Fall müssen die generierten PDF-Daten vom Client mit der Funkti-
on PDF_get_buffer( ) abgeholt werden. Mit dem besonderen Dateinamen »–« kann die
PDF-Ausgabe nach stdout gelenkt werden. Unter Windows können UNC-Pfade oder Netz-
werkfreigaben verwendet werden.
len (Nur C-Sprachbindung) Länge von filename (in Bytes) für UTF-16-Strings. Ist len
gleich 0, muss ein null-terminierter String übergeben werden.
writeproc (Nur C und C++) C-Callback-Funktion, die von PDFlib aufgerufen wird, um
die generierten PDF-Daten vollständig oder teilweise zu übertragen.
optlist Optionsliste mit Dokumentoptionen gemäß Tabelle 8.5 oder Tabelle 8.7. Optio-
nen, die für PDF_end_document( ) festgelegt werden, haben Vorrang vor gleichnamigen
Optionen in PDF_begin_document( ).
Rückgabe -1 (in PHP: 0) im Fehlerfall, sonst 1. Ist filename leer, ist die Funktion in jedem Fall erfolg-
reich und gibt nie den Fehlercode -1 (in PHP: 0) zurück.
Details Diese Funktion erzeugt eine neue PDF-Datei mit dem Namen filename. PDFlib versucht,
eine Datei mit dem übergebenen Namen zu öffnen und schließt die Datei, sobald das
PDF-Dokument fertig ist.
PDF_begin_document_callback( ) öffnet ein neues PDF-Dokument direkt im Speicher,
ohne dabei in eine Datei zu schreiben. Die in writeproc übergebene Callback-Funktion

muss die Anzahl der geschriebenen Bytes zurückgeben. Entspricht der Rückgabewert
nicht dem Argument size von PDFlib, wird eine Exception ausgelöst. Die Frequenz der
writeproc-Aufrufe lässt sich mit der Option flush einstellen.
Gültigkeit object; mit dieser Funktion beginnt der Geltungsbereich document, sofern die Datei
erfolgreich geöffnet werden konnte. Diese Funktion muss immer paarweise mit PDF_
end_document( ) auftreten.
Bindungen C, C++, Java, JScript: Achten Sie darauf, die Sonderbedeutung des Gegenschrägstrichs im
Pfadseparator korrekt aufzuheben. Folgendes Beispiel bezeichnet eine Datei auf einem
Netzlaufwerk: \\\\malik\\rp\\foo.pdf.
PDF_begin_document_callback( ) ist nur in C und C++ verfügbar. Die mit writeproc überge-
bene Funktion darf keine C++-Methode, sondern muss eine C-Funktion sein.
Tabelle 8.5 Dokumentoptionen für PDF_begin_document( ) und PDF_begin_document_callback( )

Option Typ Beschreibung
compatibility Schlüsselwort Setzt die PDF-Version des Dokuments auf einen der Strings »1.3«, »1.4«, »1.5« oder
»1.6« für Acrobat 4, 5, 6 oder 7. Weitere Informationen hierzu finden Sie in
Abschnitt 7.1, »Acrobat und PDF-Versionen«, Seite 195. Der String wird ignoriert,
falls pdfx verwendet wird. Standardwert: »1.5«.
flush Schlüsselwort (Nur für PDF_begin_document_callback( )) Setzt die Flushing-Strategie.
Einzelheiten hierzu finden Sie in Abschnitt 3.1.6, »Erzeugen von PDF-Dokumenten
im Arbeitsspeicher«, Seite 59. Standardwert: page.
none flusht nur ein Mal am Dokumentende
page flusht an jedem Seitenende
content flusht nach allen Fonts, Rasterbildern, Dateianhängen und Seiten
heavy flusht, sobald der interne 64 KB große Dokumentpuffer voll ist
groups String-Liste Definiert die Namen und die Reihenfolge der in einem Dokument verwendeten
Seitengruppen.
inmemory Boolean (Nur für PDF_begin_document( )) Sind inmemory sowie die Option linearize gleich
true, erzeugt PDFlib bei der Linearisierung keine temporären Dateien, sondern
verarbeitet das Dokument direkt im Speicher. Auf manchen Systemen
(insbesondere MVS) lässt sich die Leistung damit erheblich steigern. Es ist jedoch
Speicher in der doppelten Dokumentgröße erforderlich. Ist inmemory gleich false,
wird bei der Linearisierung eine temporäre Datei angelegt. Standardwert: false
lang String (Erforderlich, wenn tagged=true) Setzt die Sprache des Dokuments als Sprachcode
aus zwei Zeichen gemäß ISO 639 (Beispiele sind: DE, EN, FR, JA). Optional kann ein
Minuszeichen und ein zwei Zeichen langer Ländercode gemäß ISO 3166 folgen
(Beispiele sind: EN-US, EN-GB, ES-MX). Es wird nicht zwischen Groß- und Klein-
schreibung unterschieden.
Die Sprache kann für einzelne Einheiten auf allen Ebenen des Strukturbaums ge-
ändert werden, muss aber anfangs für das Gesamtdokument gesetzt werden.
linearize Boolean Ist linearize gleich true, wird das Ausgabedokument linearisiert (=web-optimiert
oder schnelle Web-Anzeige, siehe Abschnitt 7.3, »Web-Optimiertes (Linearisiertes)
PDF«, Seite 200). Auf MVS-Systemen kann diese Option nicht mit der direkten
Generierung im Speicher kombiniert werden (d.h. einem leeren Dateinamen).
master- String Hauptkennwort des Dokuments. Ist es leer, so wird kein Hauptkennwort
password angewandt. Standardwert: nicht vorhanden.
permissions Schlüssel- Liste der Zugriffsberechtigungen für das Ausgabedokument aus einem oder
wortliste mehreren der Schlüsselwörter noprint, nomodify, nocopy, noannots, noassemble,
noforms, noaccessible, nohiresprint und plainmetadata (siehe Tabelle 7.3).
Standardwert: nicht vorhanden.

Tabelle 8.5 Dokumentoptionen für PDF_begin_document( ) und PDF_begin_document_callback( )
pdfx Schlüsselwort Setzt die PDF/X-Konformität auf »PDF/X-1:2001« , »PDF/X-1a:2001«, »PDF/
X-1a:2003«, »PDF/X-2:2003«, »PDF/X-3:2002«, »PDF/X-3:2003« oder »none«
(siehe Abschnitt 7.4, »PDF/X«, Seite 201). Standardwert: none.
recordsize Integer (Nur MVS) Die Record-Größe für die Ausgabedatei. Standardwert: 0 (Ausgabe
ohne fixe Blöckgröße).
tagged Boolean (ab PDF 1.4) Ist tagged gleich true, wird die Ausgabe als Tagged PDF generiert.
Vom Client müssen im Tagged-PDF-Modus korrekte Strukturinformationen
übergeben werden (siehe Abschnitt 8.10, »Strukturfunktionen für Tagged PDF«,
Seite 338). Standardwert: false.
tempdirname String (Only for PDF_begin_document( )) Name des Verzeichnisses, in dem temporäre
Dateien gespeichert werden, die PDFlib zur internen Verarbeitung benötigt. Ist
tempdirname leer, werden temporäre Dateien im aktuellen Verzeichnis abgelegt.
Ist die Option tempfilenames vorhanden, wird tempdirname ignoriert.
tempfilenames Liste mit (Nur MVS) Vollständige Namen zweier temporärer Dateien, die PDFlib zur
zwei Strings internen Verarbeitung benötigt. Ist tempfilenames leer, generiert PDFlib selbst
eindeutige Namen. Die temporären Dateien müssen nach Aufruf von PDF_end_
document( ) explizit gelöscht werden. Wird diese Option übergeben, darf der
Parameter filename nicht leer sein. Standardwert: nicht vorhanden.
user- String Benutzerkennwort für das Dokument. Ist userpassword leer, wird kein
password Benutzerkennwort verwendet. Standardwert: nicht vorhanden.
C++ Java void end_document(String optlist)

Perl PHP PDF_end_document(resource p, string optlist)
C void PDF_end_document(PDF *p, const char *optlist)
Schließt das generierte PDF-Dokument unter Anwendung verschiedener Optionen.
optlist Liste mit Dokumentoptionen gemäß Tabelle 8.6. Optionen, die für PDF_end_
document( ) festgelegt werden, haben Vorrang vor gleichnamigen Optionen in PDF_
begin_document( ).
Details Diese Funktion beendet die Generierung des PDF-Dokuments, gibt alle dokumentspezi-
fischen Ressourcen frei und schließt die Ausgabedatei, sofern das PDF-Dokument mit
PDF_begin_document( ) geöffnet wurde. PDF_end_document( ) muss nach abgeschlossener
Seitengenerierung durch den Client auf jeden Fall aufgerufen werden, unabhängig da-
von, auf welche Art das PDF-Dokument geöffnet wurde.
Wurde das Dokument direkt im Speicher und nicht in einer Datei generiert, bleibt
der Dokumentpuffer auch nach PDF_end_document( ) erhalten, so dass er mit PDF_get_
buffer( ) ausgelesen werden kann. Er wird freigegeben, sobald PDF_begin_document( ) er-
neut aufgerufen wird oder das PDFlib-Objekt mit PDF_delete( ) seine Gültigkeit verliert.

Gültigkeit document; mit dieser Funktion wird der Geltungsbereich document beendet; diese
Funktion muss immer paarweise mit einer der Funktionen PDF_begin_document( ) oder
PDF_begin_document_callback( ) auftreten.
Tabelle 8.7 Unteroptionen für die Option viewerpreferences für PDF_begin_document( ) und PDF_end_
document( )
centerwindow Boolean Legt fest, ob das Dokumentfenster am Bildschirm zentriert wird. Standardwert:
false.
direction Schlüsselwort Leserichtung des Dokuments, die sich auf das Blättern in der Doppelseitenansicht
auswirkt. Standardwert: l2r).
l2r Von links nach rechts
r2l Von rechts nach links (einschließlich der Schriftsysteme mit vertikaler
Laufrichtung)
displaydoctitle Boolean Legt fest, ob in der Titelleiste von Acrobat das Dokumentinfofeld »Titel« (true)
oder der Dateiname (false) angezeigt wird. Standardwert: false.
fitwindow Boolean Legt fest, ob das Dokumentfenster an die Größe der ersten Seite angepasst wird.
hidemenubar Boolean Legt fest, ob die Menüleiste von Acrobat ausgeblendet wird. Standardwert: false.
hidetoolbar Boolean Legt fest, ob die Werkzeugleisten von Acrobat ausgeblendet werden. Acrobat 5
ignoriert diese Einstellung bei der Anzeige von PDFs im Browser. Standardwert:
false.
hidewindowui Boolean Legt fest, ob die Fenstersteuerelemente von Acrobat ausgeblendet werden.
nonfullscreen- Schlüsselwort (Nur relevant, wenn die Option openmode auf fullscreen gesetzt ist) Legt fest, wie
pagemode das Dokument beim Beenden des Vollbildmodus angezeigt wird. Default:
usenone.
bookmarks Lesezeichen-Fenster anzeigen
thumbnails Seiten-Fenster anzeigen
layers Ebenen-Fenster anzeigen
none Nur Dokumentfenster anzeigen
viewarea Schlüsselwort Schlüsselwort zur Auswahl einer Seitengrößenangabe (Box), die den Seitenbereich
viewclip beschreibt, der beim Betrachten des Dokuments am Bildschirm oder beim Drucken
printarea angezeigt oder beschnitten wird. Acrobat ignoriert diese Einstellung zwar, sie
printclip kann aber für andere Anwendungen sinnvoll sein. Standardwert: crop.
art ArtBox wird verwendet.
bleed BleedBox wird verwendet.
crop CropBox wird verwendet.
media MediaBox wird verwendet.
trim TrimBox wird verwendet.
PDF/X: Es sind nur media und bleed zulässig.
C++ const char *get_buffer(long *size)

Java byte[] get_buffer( )
Perl PHP string PDF_get_buffer(resource p)
C const char * PDF_get_buffer(PDF *p, long *size)
Holt den Inhalt des PDF-Ausgabepuffers.
size (Nur C- und C++-Sprachbindung) C-Zeiger auf eine Speicherstelle, an der die Länge
der zurückgegebenen Daten in Bytes abgelegt wird.

Tabelle 8.6 Dokumentoptionen für PDF_begin_document( ) und PDF_end_document( )
action Aktionsliste (Da Aktionen erst nach PDF_begin_document( ) erstellt werden können, ist diese
Option nur bei PDF_end_document( ) möglich). Liste aus Dokumentaktionen für
eines oder mehrere der folgenden Ereignisse (Standardwert: leere Liste):
open (PDF 1.3) Aktionen beim Öffnen des Dokuments. Beachten Sie, dass
wegen der Ausführungsreihenfolge in Acrobat für open-Aktionen kein
JavaScript auf Dokumentebene zulässig ist.
didprint (PDF 1.4) JavaScript-Aktionen nach dem Drucken des Dokuments.
didsave (PDF 1.4) JavaScript-Aktionen nach dem Speichern des Dokuments.
willclose (PDF 1.4) JavaScript-Aktionen vor dem Schließen des Dokuments.
willprint (PDF 1.4) JavaScript-Aktionen vor dem Drucken des Dokuments.
willsave (PDF 1.4) JavaScript-Aktionen vor dem Speichern des Dokuments.
destination Optionsliste (Wird ignoriert, wenn eine open-Aktion angegeben ist) Optionsliste zur
Festlegung der Aktion beim Dokumentöffnen gemäß Tabelle 8.50.
destname Hypertext- (Wird ignoriert, wenn eine open-Aktion angegeben ist; da benannte Ziele erst
String nach PDF_begin_document( ) erstellt werden können, ist diese Option nur bei
PDF_end_document( ) möglich) Name eines Ziels, das mit PDF_add_nameddest( )
definiert wurde und als Aktion beim Dokumentöffnen verwendet wird.
hypertext- Schlüsselwort Legt den Zeichensatz für die Option destname fest (siehe »String-Behandlung in
encoding nicht Unicode-fähigen Sprachen«, Seite 108). Ein leerer String entspricht unicode.
Standardwert: Wert des globalen Parameters hypertextencoding.
labels Liste von Liste aus einer oder mehreren Optionslisten gemäß Tabelle 8.8, die symbolische
Optionslisten Seitennamen festlegen. Diese Namen werden als Seitenbezeichnungen (statt der
Seitennummer) in der Statusleiste von Acrobat angezeigt. Die Kombination der
Werte style/prefix/start muss innerhalb eines Dokuments eindeutig sein.
Standardwert: none.
moddate Boolean Falls true, wird der Dokumentinfofeld ModDate (modification date) erzeugt, was
bei der Arbeit mit bestimmten Preflight-Tools nützlich sein kann. Standardwert:
false
openmode Schlüsselwort Legt das Aussehen des Dokuments beim Öffnen fest. Standardwert: bookmarks,
sofern das Dokument Lesezeichen enthält, sonst none.
none Nur Dokumentfenster anzeigen
bookmarks Lesezeichen-Fenster anzeigen
thumbnails Seiten-Fenster anzeigen
fullscreen Im Vollbildmodus öffnen (funktioniert im Browser nicht)
layers (PDF 1.5) Ebenen-Fenster anzeigen.
pagelayout Schlüsselwort Seitenlayout beim Öffnen des Dokuments. Standardwert: default.
default Standardeinstellung von Acrobat.
singlepage Nur einzelne Seiten anzeigen.
onecolumn Seiten fortlaufend anzeigen.
twocolumnleft Doppelseiten anzeigen, ungerade Seiten links.
twocolumnright Doppelseiten anzeigen, ungerade Seiten rechts.
search Optionsliste Mit dieser Option wird Acrobat veranlasst, beim Öffnen des Dokuments einen
Suchindex anzufügen. Folgende Suboptionen werden unterstützt:
filename (Name-String; erforderlich) Dateiname des Suchindex. Dieser kann
relativ zum Dokument angegeben werden, der Benutzer muss aber
dafür sorgen, dass der übergebene Indexdateiname korrekt ist.
indextype (Name-String) Typ des Index; muss PDX sein bei Acrobat.
Standardwert: PDX.
uri String Setzt den Basis-URL des Dokuments. Dies kann nützlich sein, wenn ein Dokument
mit relativen Web-Verknüpfungen auf andere Dokumente an einen neuen Ort
verschoben wird. Wird der Basis-URL auf den »alten« Platz gesetzt, funktionieren
relative Verknüpfungen weiter. Standardwert: none.

Tabelle 8.6 Dokumentoptionen für PDF_begin_document( ) und PDF_end_document( )
viewer- Optionsliste Optionsliste mit verschiedenen Viewer-Voreinstellungen gemäß Tabelle 8.7.
preferences Standardwert: nicht vorhanden.
metadata Optionsliste (PDF 1.4) Übergibt Metadaten für das Dokument. PDFlib synchronisiert Metadaten
und Dokumentinfofelder nicht. Folgende Optionen werden unterstützt:
inputencoding (Schlüsselwort)
Zeichensatz zur Interpretation der übergebenen Daten. Standardwert:
unicode.
inputformat (Schlüsselwort)
Format für die übergebenen Daten. Standardwert: utf8 (ebcdicutf8
auf EBCDIC-basierten Systemen), aber bytes wenn inputencoding ein
8-Bit-Zeichensatz ist.
filename (Name-String, erforderlich)
Name der Datei im Dateisystem oder der virtuellen Datei, die die
Metadaten enthält. Die Datei muss korrekte XMP-Metadaten
enthalten, die unkomprimiert in die Ausgabe kopiert werden. PDFlib
generiert automatisch XDP-Paketheader und -trailer.
outputformat (Schlüsselwort)
Format, in dem die Daten in die PDF-Ausgabe geschrieben werden (der
Zeichensatz der Ausgabe ist immer unicode). Mögliche Werte sind
utf8, utf16be, utf16le. Standardwert: utf8, wenn inputformat=bytes,
sonst inputformat
Tabelle 8.8 Unteroptionen für die Option labels in PDF_begin/end_document( ) und die Option label in PDF_
begin/end_page_ext( )
group String (Nur für PDF_begin_document( ); erforderlich, wenn das Dokument Seitengrup-
pen verwendet und sonst nicht zulässig) Das Label wird auf die Seiten der fest-
gelegten sowie aller nachfolgenden Gruppen angewandt, bis ein neues Label zum
Einsatz kommt.
hypertext- Schlüsselwort Legt den Zeichensatz für die Option prefix fest (siehe Abschnitt 4.5.4, »String-
encoding Behandlung in nicht Unicode-fähigen Sprachen«, Seite 108). Ein leerer String wird
als unicode interpretiert. Standardwert: Wert des globalen Parameters
hypertextencoding.
pagenumber Integer (Nur für PDF_end_document( ); erforderlich, wenn das Dokument keine Seitengru-
ppen verwendet und sonst nicht zulässig) Das Label wird auf die festgelegte sowie
solange auf alle nachfolgenden Seiten angewandt, bis ein neues Label zum Ein-
satz kommt.
prefix Hypertext- Das Präfix für alle Labels des Bereichs. Standardwert: none.
string
start Integer >= 1 Numerischer Wert für das erste Label des Bereichs. Nachfolgende Seiten des
Bereichs werden sequentiell ab diesem Wert durchnummeriert. Standardwert: 1.
style Schlüsselwort Der zu verwendende Nummerierungsstil. Standardwert: none.
none keine Seitennummern; Labels bestehen nur aus dem Präfix.
D Dezimale arabische Ziffern (1, 2, 3, ...)
R Große römische Zahlen (I, II, III, ...)
r Kleine römische Zahlen (i, ii, iii, ...)
A Großbuchstaben (A, B, C, ..., AA, BB, CC, ...)
a Kleinbuchstaben (a, b, c, ..., aa, bb, cc, ...)
Rückgabe Ein Puffer mit binären PDF-Daten zur Weiterverarbeitung durch den Client. Es wird ei-
ner der in Tabelle 8.1 aufgeführten sprachspezifischen Datentypen für Binärdaten zu-

rückgegeben. Der zurückgegebene Puffer muss vom Client vor dem Aufruf anderer PDF-
lib-Funktionen verwendet werden. Vergessen Sie nicht, die Daten zu kopieren, sofern
Sie sie für weitere Funktionen verwenden möchten (insbesondere vor dem Aufruf von
PDF_create_pvf( ) zur Erzeugung einer PVF-Datei mit diesen Daten).
Details Diese Funktion holt den gesamten Puffer mit den PDF-Daten oder einen Teil davon.
Wird diese Funktion zwischen Seitenbeschreibungen aufgerufen, gibt sie die bislang ge-
nerierten PDF-Daten zurück. Werden die PDF-Daten direkt im Speicher erzeugt, muss
sie mindestens nach PDF_end_document( ) aufgerufen werden und gibt dann den Rest
des PDF-Dokuments zurück. Sie kann aber auch früher aufgerufen werden, um nur ei-
nen Teil der Daten abzuholen. Wird diese Funktion nur ein einziges Mal, und zwar nach
PDF_end_document( ) aufgerufen, enthält der Rückgabepuffer garantiert das vollständi-
ge PDF-Dokument in einem Stück.
Da die PDF-Ausgabe binäre Zeichen enthält, muss die Client-Software auf nicht
druckbare Zeichen inklusive Null vorbereitet sein.
Gültigkeit object, document (mit anderen Worten: nach PDF_end_page_ext( ) und vor PDF_begin_
page_ext( ) oder nach PDF_end_document( ) und vor PDF_delete( ). Diese Funktion darf nur
verwendet werden, wenn ein leerer Dateiname an PDF_begin_document( ) übergeben
wurde.
Wurde die Option linearize in PDF_begin_document( ) auf true gesetzt, beschränkt sich der
Geltungsbereich auf object, das heißt, dass diese Funktion nur nach PDF_end_
document( ) aufgerufen werden kann.
Bindungen C und C++: Der size-Parameter wird nur von C- und C++-Clients verwendet.
Andere: Ein Objekt passender Länge wird zurückgegeben, und der size-Parameter muss
weggelassen werden.
C++ Java void begin_page_ext(double width, double height, String optlist)

Perl PHP PDF_begin_page_ext(resource p, float width, float height, string optlist)
C void PDF_begin_page_ext(PDF *p, double width, double height, const char *optlist)
Fügt unter Anwendung verschiedener Optionen eine neue Seite zum Dokument hinzu.
width, height Die Parameter width und height geben die Größe der neuen Seite in
Punkt an. Sie können von den gleichnamigen Optionen überschrieben werden (in die-
sem Fall kann für diese Parameter der Dummy-Wert 0 verwendet werden). Eine Liste
häufig benutzter Seitenformate finden Sie in Tabelle 3.4. Einzelheiten hierzu finden Sie
in Tabelle 8.10 bei den Optionen width und height.
optlist Optionsliste gemäß Tabelle 8.9 und Tabelle 8.10. Diese Optionen haben niedri-
gere Prioriät als die Optionen in PDF_end_page_ext( ).
Details Diese Funktion setzt für die neue Seite alle Parameter für Text, Grafik und Farbzustand
auf die Standardwerte zurück.
Gültigkeit document; mit dieser Funktion beginnt der Geltungsbereich page; diese Funktion muss
immer paarweise mit PDF_end_page_ext( ) auftreten.
Parameter Folgende Parameter sind veraltet und werden in dieser Funktion ignoriert: pagewidth,
pageheight, ArtBox, BleedBox, CropBox, TrimBox

Tabelle 8.9 Optionen für PDF_begin_page_ext( )
group String (Erforderlich, wenn das Dokument Seitengruppen enthält, und sonst nicht
zulässig) Name der Seitengruppe zu der die Seite gehören soll. Dieser Name kann
verwendet werden, um Seiten in einer Gruppe zusammenzufassen oder sie mit
PDF_resume_page( ) zu adressieren.
pagenumber Integer Ist diese Option auf den Wert n gesetzt, so wird die Seite vor der bereits
vorhandenen Seite n in der mit der Option group festgelegten Seitengruppe
eingefügt (oder im Dokument, wenn keine Seitengruppen existieren). Ist diese
Option nicht angegeben, wird die Seite am Ende der Gruppe eingefügt.
separation- Optionsliste Optionsliste mit Angaben zur Farbseparation der aktuellen Seite. Diese Angaben
info werden von Acrobat ignoriert, sind aber in Fremdsoftware unter Umständen
nützlich, um separierte Seiten in einem Workflow mit Vorabseparation zu
erkennen und korrekt anzuzeigen
pages (Integer; erforderlich für die erste von mehreren separierten Seiten
eines Satzes, aber nicht zulässig auf den Folgeseiten) Anzahl der
Seiten, die zu einem Satz von separierten Seiten gehören, der die
Farbdaten einer Farbseite enthält. Alle Seiten des Satzes müssen in der
Datei aufeinanderfolgen.
spotname (String; erforderlich, sofern nicht spotcolor übergeben wurde) Name
der Farbe für die aktuelle Seite.
spotcolor (Schmuckfarben-Handle) Farben-Handle für die Farbe der aktuellen
Seite.
topdown Boolean Ist topdown gleich true, wird zu Beginn einer Seite der Ursprung des
Koordinatensystems in die linke obere Ecke der Seite gelegt, und die y-
Koordinaten wachsen nach unten hin; andernfalls wird das
Standardkoordinatensystem verwendet (siehe Abschnitt 3.2.1, »Koordinaten-
systeme«, Seite 62). Standardwert: false.
C++ Java void end_page_ext(String optlist)

Perl PHP PDF_end_page_ext(resource p, string optlist)
C void PDF_end_page_ext(PDF *p, const char *optlist)
Beendet eine Seite unter Anwendung verschiedener Optionen.
optlist Optionsliste gemäß Tabelle 8.10. Die Optionen in PDF_end_page_ext( ) haben

Vorrang vor den gleichnamigen Optionen in PDF_begin_page_ext( ).
Gültigkeit page; mit dieser Funktion endet der Geltungsbereich page; diese Funktion muss immer
paarweise mit PDF_begin_page_ext( ) auftreten.
Tabelle 8.10 Optionen für PDF_begin_page_ext( ) und PDF_end_page_ext( )

action Aktionsliste Liste aus Seitenaktionen für ein oder mehrere Ereignisse (Standardwert: leere
Liste):
open Aktionen beim Öffnen der Seite
close Aktionen beim Schließen der Seite
artbox Rechteck Ändert die Größenangabenparameter der aktuellen Seite. Die Koordinaten
bleedbox werden im Standardkoordinatensystem festgelegt (siehe Abschnitt 3.2.2,
cropbox »Höchstwerte für Seiten und Koordinaten«, Seite 64). Standardmäßig wird nur die
mediabox MediaBox angelegt, und zwar anhand der Parameter width und height. Diese
trimbox werden allerdings von der Option mediabox überschrieben, sofern vorhanden.

Tabelle 8.10 Optionen für PDF_begin_page_ext( ) und PDF_end_page_ext( )
defaultgray ICC-Handle Setzt anhand des übergebenen Profil-Handles einen Standardfarbraum für
defaultrgb Graustufen, RGB oder CMYK.
defaultcmyk
duration Float Setzt für die aktuelle Seite deren Anzeigedauer in Sekunden. Standardwert: 1.
label Optionsliste Optionsliste gemäß Tabelle 8.8 zur Festlegung von symbolischen Seitennamen.
Der Seitenname wird als Seitenbezeichnung in der Statusleiste von Acrobat
angezeigt. Das festgelegte Nummerierungsschema wird für die aktuelle und alle
nachfolgenden Seiten verwendet, bis es explizit geändert wird. Die Kombination
aus style/prefix/start-Werten muss innerhalb des Dokuments eindeutig sein.
metadata Optionsliste (PDF 1.4) Liefert Metadaten über die Seite. Einzelheiten hierzu finden Sie bei der
Beschreibung der Option metadata in Tabelle 8.9.
rotate Integer Legt die Seitendrehung fest. Die Drehung wirkt sich auf die Anzeige der Seite aus,
lässt aber das Koordinatensystem unverändert. Mögliche Werte sind 0, 90, 180,
270. Standardwert: 0.
transition Schlüsselwort Bestimmt für die aktuelle Seite den Seitenübergang, der für Präsentationen als
Spezialeffekt bei der Anzeige des PDFs im Vollbildmodus von Acrobat verwendet
werden kann. Standardwert: replace.
split Die Seite wird wie ein Vorhang aufgezogen und gibt die nächste frei.
blinds Split-Effekt mit mehreren Linien, die den Eindruck einer Jalousie
erwecken
box Ein Rechteck vergrößert sich und legt die neue Seite frei.
wipe Eine einzelne Linie wischt über die alte Seite und legt dabei die neue
frei.
dissolve Die alte Seite löst sich mosaikartig auf und legt dabei die neue frei.
glitter Wie bei dissolve, nur sind die Mosaiksteinchen nicht gleichmäßig
verteilt, sondern bewegen sich von einer Bildschirmseite zur
gegenüberliegenden.
replace Die neue Seite ersetzt die alte ohne Übergangseffekt.
fly (PDF 1.5) Die neue Seite fliegt in die alte hinein.
push (PDF 1.5) Die neue Seite schiebt die alte hinaus.
cover (PDF 1.5) Die neue Seite gleitet in den Bildschirm hinein und bedeckt die
alte Seite.
uncover (PDF 1.5) Die alte Seite gleitet aus dem Bildschirm heraus und deckt die
neue Seite auf.
fade (PDF 1.5) Die alte Seite verblasst und gibt die Sicht auf die neue Seite
frei.
width Float oder (Nicht zulässig, wenn der Parameter oder die Option topdown gleich true ist) Die
height Schlüsselwort Größe der neuen Seite in Punkt. Diesbezügliche Einschränkungen von Acrobat
werden in Abschnitt 3.2.2, »Höchstwerte für Seiten und Koordinaten«, Seite 64
beschrieben. Für Seiten im Querformat setzen Sie width > height oder verwenden
die Option rotate. PDFlib erzeugt anhand von width und height die MediaBox, die
auch explizit mit der Option mediabox gesetzt werden kann. Die Optionen width
und height überschreiben die gleichnamigen Parameter.
Folgende symbolische Seitenformatnamen können durch Anfügen von .width
oder .height als Schlüsselwörter verwendet werden (zum Beispiel a4.width oder
a4.height):
a0, a1, a2, a3, a4, a5, a6, b5, letter, legal, ledger, 11x17
Die zugehörenden numerischen Werte finden Sie in Tabelle 3.4.

C++ Java void suspend_page(String optlist)
Perl PHP PDF_suspend_page(resource p, string optlist)
C void PDF_suspend_page(PDF *p, const char *optlist)
Unterbricht die Ausgabe der aktuellen Seite. Sie kann später wieder aufgenommen wer-
den.
optlist Optionsliste für zukünftige Verwendung.
Details Die aktuelle Seite wird mit all ihren Zuständen (Grafik, Farbe, Text etc.) intern gespei-
chert. Soll mit der Ausgabe fortgefahren werden, kann sie mit PDF_resume_page( ) wie-
der aufgenommen werden. Wurde die Ausgabe einer Seite unterbrochen, muss sie erst
wieder aufgenommen werden, um die Seite zu schließen.
Gültigkeit page; mit dieser Funktion beginnt der Geltungsbereich document. Diese Funktion muss
immer paarweise mit PDF_resume_page( ) auftreten. Sie darf nicht im Tagged-PDF-
Modus verwendet werden.
C++ Java void resume_page(String optlist)

Perl PHP PDF_resume_page(resource p, string optlist)
C void PDF_resume_page(PDF *p, const char *optlist)
Nimmt eine unterbrochene Seitenausgabe wieder auf, um weiteren Inhalt hinzuzufü-

gen.
optlist Optionsliste gemäß Tabelle 8.11.
Details Die Seitenausgabe muss mit PDF_suspend_page( ) unterbrochen worden sein. Die Ausga-
be wird wieder aufgenommen, um weitere Inhalte anzufügen. Wurde die Ausgabe einer
Seite unterbrochen, muss sie erst wieder aufgenommen werden, um die Seite schließen
zu können, auch wenn keine weiteren Inhalte hinzukommen.
Gültigkeit document; mit dieser Funktion beginnt der Geltungsbereich page; diese Funktion muss
immer paarweise mit PDF_suspend_page( ) auftreten.
Tabelle 8.11 Optionen für PDF_resume_page( )

group String (Erforderlich, wenn das Dokument Seitengruppen enthält, sonst nicht zulässig)
Name der Seitengruppe der wieder aufgenommenen Seite. Der Gruppenname
muss mit der Option groups in PDF_begin_document( ) definiert worden sein.
pagenumber Integer Nummer der Seite in der Seitengruppe, die mit der Option group festgelegt wurde
(oder Nummer der Seite im Dokument, wenn keine Seitengruppen vorhanden
sind), die wieder aufgenommen wird.Fehlt diese Option, wird die letzte Seite der
Gruppe wieder aufgenommen.

void PDF_open_mem(PDF *p, size_t (*writeproc)(PDF *p, void *data, size_t size))
Veraltet. Verwenden Sie stattdessen PDF_begin_document_callback( ).
int PDF_open_file(PDF *p, const char *filename)

void PDF_close(PDF *p)
Veraltet. Verwenden Sie stattdessen PDF_begin_document( ) und PDF_end_document( ).
void PDF_begin_page(PDF *p, float width, float height)

void PDF_end_page(PDF *p)
Veraltet, verwenden Sie stattdessen PDF_begin_page_ext( ) und PDF_end_page_ext( ).
8.2.3 Parameterbehandlung
PDFlib verwaltet eine Reihe interner Parameter, mit denen sich das Verhalten von
PDFlib bzw. das Aussehen der PDF-Ausgabe steuern lässt. Zum Einstellen und Abfragen
numerischer und String-Parameter stehen vier Funktionen bereit. Bei allen Parametern
(Schlüssel wie Werte) wird zwischen Groß- und Kleinschreibung unterschieden. Bei je-
der Kategorie von Funktionen in diesem Kapitel werden auch die jeweils relevanten Pa-
rameter beschrieben.
C++ Java double get_value(String key, double modifier)

Perl PHP float PDF_get_value(resource p, string key, float modifier)
C double PDF_get_value(PDF *p, const char *key, double modifier)
Ermittelt den Wert eines numerischen PDFlib-Parameters.
key Name des abzufragenden Parameters.
modifier Optionaler Modifizierer, der auf den Parameter anzuwenden ist. Ob ein Mo-
difizierer erforderlich ist und worauf er sich gegebenenfalls bezieht, wird in den ver-
schiedenen Parametertabellen erläutert. Wird kein Modifizierer benötigt, muss er auf 0
gesetzt werden.
Rückgabe Numerischer Wert des Parameters.
Gültigkeit Hängt vom Schlüssel ab.
Siehe auch PDF_get_pdi_value( )
C++ Java void set_value(String key, double value)

Perl PHP PDF_set_value(resource p, string key, float value)
C void PDF_set_value(PDF *p, const char *key, double value)
Setzt den Wert eines numerischen PDFlib-Parameters.
key Name des zu setzenden Parameters.
value Neuer Wert des zu setzenden Parameters.

C++ Java String get_parameter(String key, double modifier)

Perl PHP string PDF_get_parameter(resource p, string key, float modifier)
C const char * PDF_get_parameter(PDF *p, const char *key, double modifier)
Ermittelt den Inhalt eines PDFlib-Parameters vom Typ String.
key Name des abzufragenden Parameters.
modifier Optionaler Modifizierer, der auf den Parameter anzuwenden ist. Ob ein Mo-
difizierer erforderlich ist und worauf er sich gegebenenfalls bezieht, wird in den ver-
schiedenen Parametertabellen erläutert. Wird kein Modifizierer benötigt, muss er auf 0
gesetzt werden.
Rückgabe String-Wert des Parameters. Der zurückgegebene String kann bis zum Ende des umge-
benden Geltungsbereichs document verwendet werden. Ist keine Information verfüg-
bar, wird ein Leerstring zurückgegeben.
Bindungen C und C++: C- und C++-Clients dürfen den zurückgegebenen String nicht freigeben, da
PDFlib alle String-Ressourcen intern verwaltet.
Siehe auch PDF_get_pdi_parameter( )
C++ Java void set_parameter(String key, String value)

Perl PHP PDF_set_parameter(resource p, string key, string value)
C void PDF_set_parameter(PDF *p, const char *key, const char *value)
Setzt einen PDFlib-Parameter vom Typ String.
key Name des zu setzenden Parameters.
value (Name-String) Neuer Wert des zu setzenden Parameters.
8.2.4 Virtuelles Dateisystem (PDFlib Virtual File System, PVF)
C++ void create_pvf(string filename, const void *data, size_t size, string optlist)
Java void create_pvf(String filename, byte[] data, String optlist)
Perl PHP PDF_create_pvf(resource p, string filename, string data, string optlist)
C void PDF_create_pvf(PDF *p,
const char *filename, int len, const void *data, size_t size, const char *optlist)
Erzeugt eine benannte schreibgeschützte (read-only) Datei aus Daten im Speicher.
filename (Name-String) Name der virtuellen Datei; dies ist ein beliebiger String, der in
weiteren PDFlib-Aufrufen zum Referenzieren der virtuellen Datei verwendet werden
kann.

len (Nur C-Sprachbindung) Länge von filename (in Bytes) für Strings, die Null-Zeichen
enthalten können. Ist len gleich 0, muss ein null-terminierter String übergeben werden.
data Verweis auf die Daten, die den Inhalt der virtuellen Datei bilden sollen. In C und
C++ handelt es sich um einen Zeiger auf einen Speicherpuffer. In Java ist es ein Byte-Ar-
ray. In Perl und PHP ist es ein String.
size (Nur C- und C++-Sprachbindung) Länge des Speicherblocks mit den Daten in
Bytes.
optlist Optionsliste entsprechend Tabelle 8.12.
Details Der Name der virtuellen Datei kann an alle API-Funktionen übergeben werden, die Ein-
gabedateien verarbeiten (die generierte PDF-Ausgabe kann nicht in eine virtuelle Datei
geschrieben werden; um das zu erreichen, benutzen Sie in PDF_begin_document( ) einen
leeren Dateinamen). Manche Funktionen sperren die virtuelle Datei, solange die Daten
verwendet werden. Virtuelle Dateien werden solange im Speicher gehalten, bis sie mit
PDF_delete_pvf( ) explizit oder durch PDF_delete( ) automatisch gelöscht werden.
PVF-Dateien werden für jedes PDFlib-Objekt getrennt gespeichert. Sie lassen sich
nicht von verschiedenen PDFlib-Objekten gemeinsam nutzen, können aber zur Erstel-
lung mehrerer Dokumente mit demselben PDFlib-Objekt verwendet werden. Arbeiten
Threads mit verschiedenen PDFlib-Objekten, brauchen sie den PVF-Gebrauch nicht zu
synchronisieren. Verweist filename auf eine bereits existierende virtuelle Datei, wird
eine Exception ausgelöst. Diese Funktion überprüft nicht, ob filename bereits für eine
normale auf der Festplatte liegende Datei verwendet wird.
Wird die Option copy nicht angegeben, darf der Aufrufer die übergebenen Daten erst
nach dem erfolgreichen Aufruf von PDF_delete_pvf( ) ändern oder freigeben (löschen).
Bei Nichtbeachtung dieser Regel gibt es aller Wahrscheinlichkeit nach einen Absturz.
Gültigkeit beliebig
Tabelle 8.12 Optionen für PDF_create_pvf( )

copy Boolean PDFlib erzeugt sofort eine interne Kopie der übergebenen Daten. Damit kann der
Aufrufer die übergebenen Daten unmittelbar nach dem Aufruf löschen. Die
Option copy ist in den Sprachbindungen für COM, .NET und Java automatisch auf
true gesetzt (der Standardwert für andere Bindungen ist false). In anderen
Sprachbindungen werden die Daten nur kopiert, wenn die Option copy explizit
übergeben wird.
C++ Java int delete_pvf(String filename)

Perl PHP int PDF_delete_pvf(resource p, string filename)
C int PDF_delete_pvf(PDF *p, const char *filename, int len)
Löscht eine benannte virtuelle Datei und gibt die zugehörigen Datenstrukturen (nicht
jedoch den eigentlichen Inhalt) frei.
filename Name der virtuellen Datei, der in PDF_create_pvf( ) übergeben wurde.
len (Nur C-Sprachbindung) Länge von filename (in Bytes) für Strings, die Null-Zeichen

Rückgabe -1 (in PHP: 0), falls die zugehörige virtuelle Datei existiert und gesperrt ist, sonst 1.
Details Ist die Datei nicht gesperrt, werden die zu filename gehörigen Datenstrukturen sofort
von PDFlib gelöscht. Verweist filename nicht auf eine virtuelle Datei, beendet sich diese
Funktion kommentarlos. Nach einem erfolgreichen Aufruf kann filename wieder ver-
wendet werden. Virtuelle Dateien werden durch PDF_delete( ) automatisch gelöscht.
Das genaue Verhalten hängt davon ab, ob das zugehörige PDF_create_pvf( ) mit der
Option copy aufgerufen wurde: Ist dies der Fall, werden sowohl die administrativen Da-
tenstrukturen der Datei als auch die eigentlichen Daten freigegeben; andernfalls wird
die Freigabe des Inhalts dem Client überlassen.
8.2.5 Ausnahmebehandlung
Werte.
Tabelle 8.13 Parameter und Werte zur Ausnahmebehandlung

set_parameter warning Aktiviert oder deaktiviert Warnungen (nicht-fatale Exceptions). Mögliche Werte
sind true und false. Standardwert: true. Geltungsbereich: beliebig.
C++ Java int get_errnum( )

Perl PHP int PDF_get_errnum(resource p)
C int PDF_get_errnum(PDF *p)
Ermittelt die Nummer der zuletzt ausgelösten Exception oder die Ursache für einen ge-
scheiterten Funktionsaufruf.
Rückgabe Die Nummer der letzten vom PDFlib-Objekt ausgelösten Exception oder der Code für
die Fehlerursache des Funktionsaufrufs, der zuletzt mit einem Fehlercode scheiterte.
Gültigkeit Zwischen einer von PDFlib ausgelösten Exception und dem Ende der Lebensdauer eines
PDFlib-Objekts. Alternativ dazu kann diese Funktion aufgerufen werden, nachdem eine
Funktion den Fehlercode -1 (in PHP: 0) zurückgegeben hat, aber noch bevor eine
Funktion aufgerufen wird, die nicht in diesem Abschnitt aufgeführt ist.
Bindungen In C++, Java, und PHP 5 ist diese Funktion auch als Methode get_errnum( ) im Objekt
PDFlibException verfügbar.
C++ Java String get_errmsg( )

Perl PHP string PDF_get_errmsg(resource p)
C const char *PDF_get_errmsg(PDF *p)
Ermittelt den beschreibenden Text der zuletzt ausgelösten Exception oder die Ursache
eines gescheiterten Funktionsaufrufs.
Rückgabe Text der letzten vom PDFlib-Objekt ausgelösten Exception oder Code für die Fehlerursa-
che des Funktionsaufrufs, der zuletzt mit einem Fehlercode scheiterte.

Bindungen In C++, Java, und PHP 5 ist diese Funktion auch als Methode get_errmsg( ) im Objekt
C++ Java String get_apiname( )

Perl PHP string PDF_get_apiname(resource p)
C const char *PDF_get_apiname(PDF *p)
Ermittelt den Namen der API-Funktion, die die letzte Exception ausgelöste oder schei-
terte.
Rückgabe Name der Funktion, die die letzte Exception ausgelöst hat oder zuletzt mit einem Feh-
lercode gescheitert ist.
Bindungen In C++, Java, und PHP 5 ist diese Funktion auch als Methode get_apiname( ) im Objekt
C++ void *get_opaque( )

C void *PDF_get_opaque(PDF *p)
Holt den Zeiger auf Benutzerdaten, der in PDFlib abgelegt wurde.
Details Diese Funktion gibt den Zeiger auf Benutzerdaten zurück, der im Aufruf von PDF_
new2( ) übergeben und in PDFlib gespeichert wurde. PDFlib reicht den Zeiger ohne jegli-
che Bearbeitung an den Client weiter. Dieser Zeiger kann zum Beispiel in multi-threa-
ded Anwendungen verwendet werden, um private thread-spezifische Daten innerhalb
des PDFlib-Objekts zu speichern. Er ist insbesondere bei thread-spezifischer Ausnahme-
behandlung nützlich.
Bindungen Nur in der C- und der C++-Sprachbindung verfügbar.
8.2.6 Hilfsfunktionen
Die folgenden Funktion können in Umgebungen hilfreich sein, in denen die entspre-
chende Funktionalität nicht vorhanden ist.

C++ string utf16_to_utf8(string utf16string)
Perl PHP string PDF_utf16_to_utf8(resource p, string utf16string)
C const char *PDF_utf16_to_utf8(PDF *p, const char *utf16string, int len, int *size)
Konvertiert einen String vom Format UTF-16 nach UTF-8.
utf16string Zu konvertierender String. Ein eventuell vorhandenes BOM (Byte Order

Mark) wird ausgewertet. Fehlt es, so wird von der systemspezifischen Bytereihenfolge
ausgegangen.
len (Nur C-Sprachbindung) Länge von utf16string in Bytes.
size (Nur C-Sprachbindung) C-Zeiger auf eine Speicherstelle, an der die Länge des zu-
rückgegebenen Strings in Bytes abgelegt wird.
Rückgabe Der nach UTF-8 konvertierte String, der mit einem BOM (\xEF\xBB\xBF) beginnt. Auf
EBCDIC-Systemen wird das Ergebnis nach EBCDIC konvertiert, außer in der Java-Sprach-
bindung. Der zurückgegebene String ist so lange gültig, bis eine von PDF_utf16_to_utf8( )
oder PDF_utf8_to_utf16( ) verschiedene PDFlib-Funktion aufgerufen oder eine Exception
ausgelöst wird. Benötigen Clients den String länger, müssen sie ihn kopieren. Der für
den konvertierten String verwendete Speicher wird von PDFlib verwaltet.
C++ string utf8_to_utf16(string utf8string, string ordering)

Perl PHP string PDF_utf8_to_utf16(resource p, string utf8string, string ordering)
C const char * PDF_utf8_to_utf16(PDF *p,
const char *utf8string, const char *ordering, int *size)
Konvertiert einen String vom Format UTF-8 nach UTF-16.
utf8string Zu konvertierender String, der eine gültige UTF-8-Sequenz enthalten muss.

Ist ein BOM (Byte Order Mark) vorhanden, so wird es entfernt.
ordering Bestimmt die Bytereihenfolge des Ergebnisstrings:

> utf16 oder ein leerer String: Der konvertierte String erhält kein BOM und wird mit der
systemspezifischen Bytereihenfolge gespeichert.
> utf16le: Der konvertierte String wird mit »Little Endian«-Bytereihenfolge gespeichert
und erhält das LE BOM (\xFF\xFE) als Präfix.
> utf16be: Der konvertierte String wird mit »Big Endian«-Bytereihenfolge gespeichert
und erhält das BE BOM (\xFE\xFF) als Präfix.
size (Nur C-Sprachbindung) C-Zeiger auf eine Speicherstelle, an der die Länge des zu-
rückgegebenen Strings in Bytes abgelegt wird.
Rückgabe Der nach UTF-16 konvertierte String. Der zurückgegebene String ist so lange gültig, bis
eine von PDF_utf16_to_utf8( ) oder PDF_utf8_to_utf16( ) verschiedene PDFlib-Funktion
aufgerufen oder eine Exception ausgelöst wird. Benötigen Clients den String länger,
müssen sie ihn kopieren. Der für den konvertierten String verwendete Speicher wird
von PDFlib verwaltet.

8.3 Textfunktionen
8.3.1 Fontbehandlung
Werte.
Tabelle 8.14 Parameter und Werte für Fontfunktionen (siehe Abschnitt 8.2.3, »Parameterbehandlung«, Seite 236)
set_parameter FontAFM Wie die jeweilige Zeile in der entsprechenden Kategorie der UPR-Ressourcendatei
FontPFM (siehe Abschnitt 3.1.5, »Ressourcenkonfiguration und Dateisuche«, Seite 56). Durch
FontOutline mehrere Aufrufe erhält die interne Liste neue Einträge (siehe auch resourcefile in
Encoding Tabelle 8.3). Geltungsbereich: beliebig.
HostFont
ICCProfile
SearchPath
Standard-
OutputIntent
get_value font Gibt den Identifier des aktuellen mit PDF_setfont( ) gesetzten Fonts zurück oder -1
(in PHP: 0), falls kein Font gesetzt wurde. Geltungsbereich: page, pattern,
template, glyph.
get_value fontmaxcode Gibt die größte Zeichencodenummer des durch den Modifizierer bezeichneten
Font zurück. Bei encoding=glyphid entspricht das der Anzahl der Glyph-IDs.
get_parameter fontname Name des aktuellen Fonts, der mit PDF_setfont( ) gesetzt worden sein muss.
Geltungsbereich: page, pattern, template, glyph.
get_parameter fontencoding Name des Zeichensatzes oder der CMap, die für die aktuelle Schrift verwendet
wird. Der Font muss mit PDF_setfont( ) gesetzt worden sein. Geltungsbereich:
page, pattern, template, glyph.
get_value fontsize Gibt die Größe des aktuellen Fonts zurück, der mit PDF_setfont( ) gesetzt worden
sein muss. Geltungsbereich: page, pattern, template, glyph.
get_parameter fontstyle Stil des aktuellen Fonts, der im Wesentlichen der Option fontstyle entspricht
(normal, bold, italic oder bolditalic). Geltungsbereich: page, pattern, template,
glyph.
get_value capheight Gibt Metrikdaten für den durch den Modifizierer bezeichneten Font zurück.
ascender Weitere Informationen finden Sie in Abschnitt 4.6, »Textmetrik und Text-
descender varianten«, Seite 115. Die Werte werden anteilig zur Schriftgröße angegeben und
müssen daher mit der gewünschten Schriftgröße multipliziert werden.
set_parameter fontwarning Wenn false, gibt PDF_load_font( ) -1 (in PHP: 0) zurück (statt eine Exception
auszulösen), wenn die Font/Zeichensatz-Kombination nicht geladen werden
kann. Standardwert: true. Geltungsbereich: beliebig.
get_value monospace Gibt für den aktuellen Font den Wert der Option monospace zurück, sofern diese
gesetzt wurde, andernfalls 0. Geltungsbereich: page, pattern, template, glyph.
set_value subsetlimit Deaktiviert die Bildung von Fontuntergruppen, wenn das Dokument mehr als den
gegebenen Prozentsatz an Zeichen des Fonts verwendet. Standardwert: 100
Prozent. Geltungsbereich: beliebig.
set_value subsetminsize Fontuntergruppen werden nur bei Fonts gebildet, die größer als die angegebene
Zahl in Kilobyte sind (siehe Abschnitt 4.3, »Schrifteinbettung und
Schriftuntergruppen«, Seite 93). Standardwert: 100 KB. Geltungsbereich: beliebig.

Tabelle 8.14 Parameter und Werte für Fontfunktionen (siehe Abschnitt 8.2.3, »Parameterbehandlung«, Seite 236)
set_parameter auto- Steuert die automatische Aktivierung der Fontuntergruppenbildung für
subsetting TrueType- und OpenType-Fonts (siehe Abschnitt 4.3, »Schrifteinbettung und
Schriftuntergruppen«, Seite 93). Standardwert: true. Geltungsbereich: beliebig.
set_parameter autocidfont Steuert die automatische Konvertierung von TrueType-Schriften mit von
macroman und winansi verschiedenen Zeichensätzen in CID-Schriften (siehe
Abschnitt 4.3, »Schrifteinbettung und Schriftuntergruppen«, Seite 93).
Standardwert: true. Geltungsbereich: beliebig.
set_parameter unicodemap Steuert die Erzeugung von ToUnicode-CMaps (siehe Abschnitt 4.5.1, »Unicode für
Seitenbeschreibungen und Hypertext«, Seite 105). Dieser Parameter wird im
Tagged-PDF-Modus ignoriert. Standardwert: true. Geltungsbereich: beliebig.
C++ Java int load_font(String fontname, String encoding, String optlist)

Perl PHP int PDF_load_font(resource p, string fontname, string encoding, string optlist)
C int PDF_load_font(PDF *p,
const char *fontname, int len, const char *encoding, const char *optlist)
Sucht nach einer Schrift und bereitet sie zur späteren Verwendung vor.
fontname (Name-String) Der tatsächliche oder der Alias-Name der Schrift. Er wird bei
der Suche nach den Fontdaten verwendet (siehe Abschnitt 4.3.1, »Wie PDFlib nach Fonts
sucht«, Seite 93). Es wird zwischen Groß- und Kleinschreibung unterschieden.
len (Nur C-Sprachbindung) Länge von fontname (in Bytes) bei UTF-16-Strings. Ist len
encoding Zeichensatz, der mit der Schrift verwendet werden soll (es wird zwischen
Groß- und Kleinschreibung unterschieden). Dabei stehen folgende Zeichensätze zur
Auswahl (weitere Informationen finden Sie in Abschnitt 4.4, »Zeichensätze«, Seite 98):
> einer der vordefinierten 8-Bit-Zeichensätze winansi, macroman, macroman_apple,
ebcdic, pdfdoc, iso8859-X, cpXXXX und U+XXXX
> host oder auto für einen automatisch selektierten Zeichensatz
> Name eines benutzerdefinierten Zeichensatzes, der aus einer Datei geladen oder mit
PDF_encoding_set_char( ) definiert wurde
> unicode für auf Unicode basierende Adressierung
> cpXXXX für CJK-Codepages (siehe Tabelle 4.8)
> glyphid für Adressung via Glyphen-ID
> builtin zur Selektion des internen Zeichensatzes der Schrift
> Name einer Standard-CMap (siehe Abschnitt 4.7, »Chinesischer, japanischer und ko-
reanischer Text«, Seite 120)
> ein dem Betriebssystem bekannter Zeichensatzname (nicht auf allen Plattformen
verfügbar)
Der gewählte Zeichensatz muss zur Schrift kompatibel sein. Tabelle 8.16 listet die zuläs-
sigen Kombinationen von Encodings und Fontformaten auf.
Rückgabe Font-Handle zur späteren Verwendung in PDF_setfont( ). Das Verhalten dieser Funktion
ändert sich, wenn der Parameter oder die Option fontwarning auf false gesetzt ist. In die-
sem Fall gibt die Funktion den Fehlercode -1 (in PHP: 0) zurück, statt eine Exception aus-

Tabelle 8.15 Verhältnis von Encodings und Fontformaten
8-Bit- unicode, Unicode- andere
Fontformat Encodings builtin glyphid cp9361 etc. CMaps CMaps
PostScript Type 1 ja ja2 – ja3 – –
Type 3 ja – – – – –
TrueType und OpenType mit ja nur Symbol- ja5 ja5 – –
TrueType-Outlines4 Fonts
Westliche OpenType-Fonts mit ja ja ja5 ja5 – –
PostScript-Outlines (SID)4
CJK OpenType mit – – ja ja ja ja6, 7
PostScript-Outlines (CID)
Standard-CJK-Fonts (ohne – – – – ja ja7
Einbettung)
1. Derzeit nur auf Windows-Systemen.
2. Nicht für die PDF-Corefonts außer Symbol und ZapfDingbats.
3. Maximal 256 Zeichen können addressiert werden.
4. Wird als CID-Font eingebettet, es sei denn, es wird builtin-Encoding benutzt oder ein 8-Bit-Encoding der ausschließlich Zeichen aus
aus Adobe Standard Latin enthält. Die Erzeugung von CID-Fonts kann für 8-Bit-Encoding mit Hilfe der Option autocidfont=false un-
terdrückt werden.
5. Der Font muss Einbettung zulassen.
6. Subsetting wird nicht unterstützt.
7. Es steht keine Fontmetrik zur Verfügung, d.h. PDF_stringwidth( ), Kerning, Textflow, overline/underline/strikeout und textx/texty
werden nicht unterstützt.
zulösen, wenn die angeforderte Font/Zeichensatz-Kombination nicht geladen werden

kann. Bei nicht korrekten Parametern wird weiterhin eine Exception ausgelöst.
Der zurückgegebene Wert – das Font-Handle – hat für den Benutzer keinerlei inhalt-
liche Bedeutung. Er dient lediglich als Argument für PDF_setfont( ) und verwandte Funk-
tionen. Insbesondere können beim Anfordern der gleichen Font/Encoding-Kombinati-
on in verschiedenen Dokumenten unterschiedliche Font-Handles zurückgegeben
werden.
Ein erneuter Aufruf dieser Funktion mit demselben Fontnamen liefert das Font-
Handle des ersten Aufrufs zurück, es sei denn, es wurde ein anderer Wert für den Para-
meter encoding oder die Option fontstyle angegeben.
Widersprüchliche Optionen: wird ein Font ohne Einbettung, Unterschneidung oder
Untergruppen mit PDF_load_font( ) geladen oder mit PDF_fill_textblock( ) angefordert
und später erneut geladen, so werden diesbezügliche Optionen ignoriert.
Details Diese Funktion bereitet eine Schrift zur späteren Verwendung in PDF_setfont( ) vor. Die
Metrikdaten werden aus dem Arbeitsspeicher oder aus einer (virtuellen oder auf der
Festplatte liegenden) Metrikdatei geladen. Ist der Parameter fontwarning auf true ge-
setzt, wird eine Exception ausgelöst, wenn die angeforderte Font/Zeichensatz-Kombina-
tion aufgrund von Konfigurationsproblemen nicht verwendet werden konnte (zum
Beispiel, wenn ein Font, Metrikdaten oder eine Encoding-Datei nicht gefunden werden
konnte oder die gefundenen Informationen nicht zusammenpassen). Andernfalls kann
der von dieser Funktion zurückgegebene Wert als Fontargument in weiteren Funktio-
nen zur Schriftbehandlung verwendet werden.
Gültigkeit document, page, pattern, template, glyph
Parameter Siehe Tabelle 8.14.
PDF/X Die Option embedding muss auf true gesetzt sein.

Tabelle 8.16 Optionen für PDF_load_font( )
auto- Boolean Entscheidet dynamisch, ob Fontuntergruppen auf Basis der Parameter subsetlimit
subsetting und subsetminsize sowie der tatsächlich genutzten Zeichen gebildet werden.
Diese Option wird ignoriert, wenn die Option subsetting übergeben wird.
Standardwert: Wert des globalen Parameters autosubsetting.
autocidfont Boolean TrueType-Schriften mit 8-Bit-Zeichensätzen außer winansi, macroman und
builtin sowie OpenType-Schriften ohne Glyphennamen werden automatisch als
CID-Fonts gespeichert. Damit werden Probleme mit bestimmten nicht-
zugreifbaren Glyphen außerhalb des winansi-Zeichensatzes umgangen.
Standardwert: Wert des globalen Parameters autocidfont.
embedding Boolean Steuert, ob die Schrift eingebettet wird. Diese Option hat keine Auswirkungen auf
Type-3-Schriften. Soll eine Schrift eingebettet werden, muss neben den Metrik-
daten auch die Zeichenbeschreibungsdatei vorhanden sein (dies gilt nicht für
TrueType- und OpenType-Schriften). Die tatsächlichen Zeichenbeschreibungen
werden dann in die PDF-Ausgabe aufgenommen. Wird eine Schrift nicht
eingebettet, werden nur allgemeine Schriftinformationen in die PDF-Ausgabe
aufgenommen. Standardwert: false.
fontstyle Schlüsselwort Steuert die Erzeugung von unechten Schriftstilen. Diese können nur für TrueType-
(keine TTC) und OpenType-Schriften genutzt werden, die nicht eingebettet sind
(siehe Abschnitt 4.6.3, »Textvarianten«, Seite 117). Mögliche Schlüsselwörter sind
normal, bold, italic, bolditalic. Standardwert: normal.
fontwarning Boolean Ist diese Option gleich true, wird eine Exception ausgelöst, wenn die angeforderte
Font/Zeichensatz-Kombination nicht geladen werden kann; bei false wird ein
Fehlercode zurückgegeben. (Bei der Suche nach Zeichensätzen wird zwar der
Parameter fontwarning, aber nicht die Option fontwarning berücksichtigt.)
Standardwert: Wert des globalen Parameters fontwarning.
kerning Boolean Steuert, ob Kerning-Daten aus den Schriftinformationen eingelesen werden (siehe
Abschnitt 4.6, »Textmetrik und Textvarianten«, Seite 115). Standardwert: false.
monospace Integer Alle Glyphen des Fonts werden äquidistant in der Breite geschrieben, die durch
1...2048 den Integer-Wert gegeben ist (gemessen im Koordinatensystem des Fonts: 1000
Einheiten entsprechen der Schriftgröße). Bei Type-3-Fonts werden alle von 0
verschiedenen Glyphenbreiten geändert. Diese Option ist nur für Standard-CJK-
Fonts empfehlenswert und wird für PDF-Standardschriften nicht unterstützt; sie
wird ignoriert, wenn der Font eingebettet ist. Standardwert: Ist kein Wert
gegeben, werden die Metrikdaten der Schrift verwendet.
subsetlimit Float Deaktiviert die Bildung von Fontuntergruppen, wenn der prozentuale Anteil der
im Dokument verwendeten Zeichen an der Gesamtzahl der im Font vorhandenen
Zeichen den gegebenen Prozentsatz übersteigt. Standardwert: Wert des globalen
Parameters subsetlimit.
subsetminsize Float Deaktiviert die Bildung von Fontuntergruppen, wenn die originale Fontdatei
kleiner als der angegebene Wert in KB ist. Standardwert: Wert des globalen
Parameters subsetminsize.
subsetting Boolean Steuert, ob Fontuntergruppen gemäß der Optionen subsetlimit und subsetminsize
sowie der Gesamtzahl der im Dokument benutzten Zeichen gebildet werden
(siehe Abschnitt 4.3, »Schrifteinbettung und Schriftuntergruppen«, Seite 93).
unicodemap Boolean Steuert die Generierung von ToUnicode-CMaps (siehe Abschnitt 4.5.1, »Unicode für
Seitenbeschreibungen und Hypertext«, Seite 105). Diese Option wird im Tagged-
PDF-Modus ignoriert. Standardwert: true.

C++ Java void PDF_setfont(int font, double fontsize)
Perl PHP PDF_setfont(resource p, int font, float fontsize)
C void PDF_setfont(PDF *p, int font, double fontsize)
Setzt die aktuelle Schrift in der angegebenen Größe.
font Font-Handle, das von PDF_load_font( ) zurückgegeben wurde.
fontsize Größe der Schrift, gemessen in Einheiten des aktuellen benutzerdefinierten

Koordinatensystems. Die Schriftgröße darf nicht gleich 0 sein; bei negativen Werten er-
scheint der Text gespiegelt bezogen auf die aktuelle Transformationsmatrix.
Details Die Schrift muss auf jeder Seite erneut gesetzt werden, und zwar vor jeglicher Textaus-
gabe. Die Schrifteinstellungen gelten immer nur für die aktuelle Seite. Die aktuelle
Schrift kann auf einer Seite beliebig oft geändert werden.
Gültigkeit page, pattern, template, glyph
Parameter Siehe Tabelle 8.14. Die Funktion setzt den Parameter leading automatisch auf fontsize.
8.3.2 Benutzerdefinierte (Type 3) Schriften
C++ Java void begin_font(String fontname,

double a, double b, double c, double d, double e, double f, String optlist)
Perl PHP PDF_begin_font(resource p, string fontname,
float a, float b, float c, float d, float e, float f, string optlist)
C void PDF_begin_font(PDF *p, char *fontname, int reserved,
double a, double b, double c, double d, double e, double f, const char *optlist)
Beginnt die Definition einer Type-3-Schrift.
fontname (Name-String) Name, unter dem die Schrift registriert und später in PDF_
load_font( ) verwendet werden kann.
reserved (Nur C-Sprachbindung) Reserviert, muss gleich 0 sein.
a, b, c, d, e, f Die Elemente der Fontmatrix, die das Koordinatensystem definiert, in

dem die Glyphen gezeichnet werden. Die sechs Werte ergeben eine Matrix wie in Post-
Script und PDF. Um entartete Transformationen zu vermeiden, darf a*d nicht gleich b*c
sein. Eine gängige Fontmatrix für ein 1000 x 1000 Koordinatensystem ist [0.001, 0, 0,
0.001, 0, 0].
Details Diese Funktion setzt alle Text-, Grafik- und Farbzustandsparameter auf ihre Standard-
werte zurück. Die Schrift kann eine beliebige Anzahl von Glyphendefinitionen enthal-
ten, aber über einen Zeichensatz kann nur auf 256 Glyphen zugegriffen werden. Die de-
finierte Schrift gilt bis zum Ende des aktuellen Geltungsbereichs document.
Gültigkeit document, page; mit dieser Funktion beginnt der Geltungsbereich font; diese Funktion
muss immer paarweise mit PDF_end_font( ) auftreten.

Tabelle 8.17 Optionen für PDF_begin_font( )
colorized Boolean Ist colorized gleich true, so kann die Schrift Informationen enthalten, um die Farbe
einzelner Zeichen explizit zu definieren. Bei false werden alle Zeichen in der (zum
Zeitpunkt der Fontverwendung) aktuellen Farbe gezeichnet. Außerdem dürfen die
Glyphendefinitionen keinerlei Farboperatoren oder von Masken verschiedene
Bilder enthalten. Standardwert: false.
C++ Java void end_font( )

Perl PHP PDF_end_font(resource p)
C void PDF_end_font(PDF *p)
Beendet eine Type-3-Schriftdefinition.
Gültigkeit font; mit dieser Funktion endet der Geltungsbereich font; diese Funktion muss immer
paarweise mit PDF_begin_font( ) auftreten.
C++ Java void begin_glyph(String glyphname,

double wx, double llx, double lly, double urx, double ury)
Perl PHP PDF_begin_glyph(resource p, string glyphname,
float wx, float llx, float lly, float urx, float ury)
C void PDF_begin_glyph(PDF *p,
char *glyphname, double wx, double llx, double lly, double urx, double ury)
Beginnt eine Type-3-Glyphendefinition.
glyphname Name der Glyphe. Unter diesem Namen muss die Glyphe in allen Enco-
dings, die mit der Schrift verwendet werden, verzeichnet sein. Glyphennamen müssen
innerhalb einer Schrift eindeutig sein.
wx Laufweite des Zeichens im Glyphenkoordinatensystem, das durch die Fontmatrix

vorgegeben ist.
llx, lly, urx, ury Ist die Option colorized der Schrift gleich false (der Standardwert), be-
zeichnen diese vier Parameter die Koordinaten der linken unteren und der rechten obe-
ren Ecke der Boundingbox der Glyphe. Die Boundingbox-Werte müssen korrekt gesetzt
sein, um Probleme beim PostScript-Druck zu vermeiden. Ist die Option colorized der
Schrift gleich true, müssen alle vier Werte gleich 0 sein.
Details Die Glyphen einer Schrift können mittels Text-, Vektorgrafik- und Rasterbild-Funktio-
nen definiert werden. Rasterbilder dürfen aber nur eingesetzt werden, wenn die Option
colorized der Schrift auf true gesetzt ist, oder sie mit der Option mask geöffnet wurden.
Zur Definition von Bitmaps in Type-3-Schriften sollte mit Inline-Bildern gearbeitet wer-
den (siehe Abschnitt 5.1.1, »Grundlegende Vorgehensweise«, Seite 147).
Da der Grafikzustand der Seite beim Zeichnen der Glyphe vollständig übernommen
wird, sofern die Option colorize auf true gesetzt ist, sollten in der Glyphendefinition alle
relevanten Aspekte des Grafikzustands (zum Beispiel die Strichstärke) explizit einge-
stellt werden.
Gültigkeit page, font; mit dieser Funktion beginnt der Geltungsbereich glyph; diese Funktion muss
immer paarweise mit PDF_end_glyph( ) auftreten.

C++ Java void end_glyph( )
Perl PHP PDF_end_glyph(resource p)
C void PDF_end_glyph(PDF *p)
Beendet eine Type-3-Glyphendefinition.
Gültigkeit glyph; mit dieser Funktion endet der Geltungsbereich glyph; diese Funktion muss
immer paarweise mit PDF_begin_glyph( ) auftreten.
8.3.3 Definition von Zeichensätzen (Encodings)
C++ Java void encoding_set_char(String encoding, int slot, String glyphname, int uv)
Perl PHP PDF_encoding_set_char(resource p, string encoding, int slot, string glyphname, int uv)
C void PDF_encoding_set_char(PDF *p,
const char *encoding, int slot, const char *glyphname, int uv)
Fügt einen Glyphennamen und/oder Unicode-Wert zu einem benutzerdefinierten Zei-

chensatz hinzu.
encoding Name des Zeichensatzes. Dieser Name muss in PDF_load_font( ) verwendet

werden. Er darf weder einen integrierten noch einen bereits verwendeten Zeichensatz
bezeichnen.
slot Position des zu definierenden Zeichens, wobei 0 <= slot <= 255 gilt. Jede Position
darf innerhalb eines bestimmten Zeichensatzes nur einmal belegt werden.
glyphname Name des Zeichens.
uv Unicode-Wert des Zeichens.
Details Diese Funktion kann mehrfach aufgerufen werden. Es können maximal 256 Zeichenpo-
sitionen in einem Zeichensatz definiert werden. Dies ist schrittweise möglich, solange
der Zeichensatz nicht verwendet wird. Danach jedoch wird beim Versuch, weitere Zei-
chen hinzuzufügen, eine Exception ausgelöst. Es müssen nicht alle Zeichenpositionen
festgelegt werden; nicht definierte Positionen werden mit .notdef belegt.
Es sind drei verschiedene Kombinationen aus Glyphenname und Unicode-Wert
möglich:
> glyphname wird übergeben, uv = 0: dies entspricht einer Encoding-Datei ohne Uni-
code-Werte
> uv wird übergeben, glyphname jedoch nicht: dies entspricht einer Codepage-Datei
> glyphname und uv werden übergeben: dies entspricht einer Encoding-Datei mit Uni-
code-Werten
Der definierte Zeichensatz kann bis zum Ende des aktuellen Geltungsbereichs object
verwendet werden.
Gültigkeit object, document, page, pattern, template, path, font, glyph

8.3.4 Einfache Textausgabe
Hinweis Jeder Text, der an die in diesem Abschnitt beschriebenen Funktionen übergeben wird, muss zu
dem Zeichensatz passen, der mit PDF_load_font( ) selektiert wurde. Dies gilt für 8-Bit-Text
ebenso wie für Unicode oder über eine CMap festgelegte Zeichensätze. Aufgrund von Beschrän-
kungen in Acrobat dürfen Textstrings nicht länger als 32 KB sein.
Werte.
Tabelle 8.18 Parameter und Werte für Textfunktionen

set_ autospace Ist autospace gleich true und ist der aktuelle Font Unicode-kompatibel, fügt
parameter PDFlib am Ende eines mit einer show-Operation ausgegebenen Texts automatisch
ein Leerzeichen (0x20) an. Dies kann bei der Generierung von Tagged-PDF nützlich
sein (siehe Abschnitt 7.5, »Tagged PDF«, Seite 207). Beachten Sie, dass sich beim
Anfügen eines Leerzeichens die nach der show-Operation aktuelle Textposition
ändert. Standardwert: false. Geltungsbereich: beliebig.
set_ charref Ist charref gleich true, werden numerische Referenzen und Entity-Referenzen
parameter ersetzt (siehe Abschnitt 4.5.5, »Character-Referenzen«, Seite 111). Standardwert:
false.
set_value charspacing Setzt oder ermittelt den Zeichenabstand, das heißt wie stark sich die aktuelle
get_value Position nach der Platzierung eines einzelnen Zeichens in einem String ändert. Der
Zeichenabstand wird in Einheiten des aktuellen Benutzerkoordinatensystems
angegeben. Am Anfang und am Ende jeder Seite wird er auf den Standardwert 0
zurückgesetzt. Um einen größeren Zeichenabstand zu erreichen, verwenden Sie
positive Werte im horizontalen Ausgabemodus und negative Werte im vertikalen
Ausgabemodus. Geltungsbereich: page, pattern, template, glyph, document.
set_parameter glyphwarning Ist glyphwarning gleich true, so wird eine Exception ausgelöst, falls eine Glyphe
nicht ausgegeben werden kann, weil der Font die zugehörige Zeichenbeschrei-
bung nicht enthält. Bei false werden fehlende Zeichen durch ein Leerzeichen oder
Glyph-ID 0 ersetzt. Standardwert: false. Geltungsbereich: beliebig.
set_value horizscaling Setzt oder ermittelt die Skalierung von Text. Dieser Parameter legt anhand eines
get_value Prozentwertes fest, ob und wie stark der Text gestaucht oder gestreckt wird. Am
Anfang und am Ende jeder Seite wird er auf den Standardwert 100 gesetzt. Die
Textskalierung bezieht sich immer auf die horizontale Koordinate.
Geltungsbereich: page, pattern, template, glyph, document.
set_value italicangle Bestimmt den Neigungswinkel von kursivem Text in Grad (von -90° bis 90°).
get_value Negative Werte können zur Simulation von kursivem Text verwendet werden,
wenn nur der reguläre Font verfügbar ist. Dies lässt sich insbesondere bei CJK-
Schriften nutzen (siehe Abschnitt 4.6.3, »Textvarianten«, Seite 117). Standardwert:
0 (dieser Parameter wird am Anfang und am Ende jeder Seite zurückgesetzt).
Geltungsbereich: page, pattern, template, glyph, document
set_parameter kerning Ist dieser Parameter auf true gesetzt, wird die Unterschneidung (Kerning) für
Schriften aktiviert, die mit der Kerning-Option geöffnet wurden; bei false ist sie
deaktiviert (siehe Abschnitt 4.6, »Textmetrik und Textvarianten«, Seite 115).
Standardwert: true. Geltungsbereich: beliebig.
set_value leading Setzt oder ermittelt den Zeilenabstand, der als Abstand zwischen den Grundlinien
get_value aufeinander folgender Textzeilen definiert ist. Der Zeilenabstand wird in PDF_
continue_text( ) verwendet und auf die Schriftgröße gesetzt, wenn eine neue
Schrift mit PDF_setfont( ) festgelegt wird. Wird der Zeilenabstand mit der Schrift-
größe gleichgesetzt, stoßen die Zeilen fast aneinander. Ober- und Unterlängen
aufeinander folgender Zeilen überlappen aber in der Regel nicht. Geltungsbereich:
page, pattern, template, glyph.

Tabelle 8.18 Parameter und Werte für Textfunktionen
set_parameter textformat Legt fest, in welchem Format Strings an die Textausgabefunktionen übergeben
get_parameter werden sollen. Mögliche Werte sind bytes, utf8, utf16, utf16le, utf16be, und auto
(siehe Abschnitt 4.5.2, »Content-Strings, Hypertext-Strings und Name-Strings«,
Seite 106). Standardwert: auto. Geltungsbereich: beliebig.
set_value textrendering Setzt oder ermittelt den aktuellen Darstellungsmodus für Text. Am Anfang jeder
get_value Seite wird er auf den Standardwert 0 gesetzt. Geltungsbereich: page, pattern,
template, glyph.
0 Umrisslinien füllen (normaler Text)
1 Umrisslinien zeichnen
2 Umrisslinien sowohl füllen als auch zeichnen
3 unsichtbarer Text
4 Umrisslinien füllen und zum Clipping-Pfad hinzufügen
5 Umrisslinien zeichnen und zum Clipping-Pfad hinzufügen
6 Umrisslinien sowohl zeichnen als auch füllen und zum Clipping-Pfad
hinzufügen
7 Umrisslinien zum Clipping-Pfad hinzufügen
set_value textrise Setzt oder ermittelt den Parameter für den vertikalen Textversatz. Dieser legt den
get_value Abstand zwischen der gewünschten Textposition und der Standardgrundlinie fest.
Positive Werte verschieben den Text nach oben. Der Textversatz bezieht sich
immer auf die vertikale Koordinate. Dies kann zum Hoch- und Tiefstellen nützlich
sein. Am Anfang jeder Seite wird der Textversatz auf den Standardwert 0 gesetzt.
Geltungsbereich: page, pattern, template, glyph.
get_value textx Ermittelt die x- bzw. y-Koordinate der aktuellen Textposition. Geltungsbereich:
texty page, pattern, template, glyph.
set_ underline Setzt oder ermittelt den aktuellen Modus für Unterstreichen, Überstreichen bzw.
parameter overline Durchstreichen, der bis zu einer expliziten Änderung beibehalten wird. Diese Modi
get_parameter strikeout können unabhängig voneinander eingestellt werden. Am Anfang jeder Seite
werden sie auf false zurückgesetzt (siehe Abschnitt 4.6, »Textmetrik und Text-
varianten«, Seite 115). Geltungsbereich: page, pattern, template, glyph.
true Text unterstreichen/überstreichen/durchstreichen
false Text nicht unterstreichen/überstreichen/durchstreichen
set_value underline- Position der gezeichneten Linie für unterstrichenen Text relativ zur Grundlinie (als
get_value position Bruchteil der Schriftgröße). Der Wert 1000000 kann verwendet werden, um den
für den jeweiligen Font spezifischen Wert aus der Fontmetrik- oder Fontdatei zu
setzen. Standardwert: 1000000.
set_value underline- Strichstärke für unterstrichenen Text. Der Wert 0 kann verwendet werden, um
get_value width den für den jeweiligen Font spezifischen Wert aus der Fontmetrik- oder Fontdatei
abzurufen. Standardwert: 0.
set_value wordspacing Setzt oder ermittelt den Wortabstand, der angibt, wie stark sich die aktuelle Posi-
get_value tion nach der Platzierung eines Wortes in einer Textzeile ändert. Anders ausge-
drückt wird die aktuelle Position nach jedem ASCII-Leerzeichen (0x20) horizontal
verschoben. Der Abstandswert wird in Einheiten des Textkoordinatensystems
angegeben. Am Anfang und am Ende jeder Seite wird er auf den Standardwert 0
zurückgesetzt. Geltungsbereich: page, pattern, template, glyph, document.

C++ Java void set_text_pos(double x, double y)
Perl PHP PDF_set_text_pos(resource p, float x, float y)
C void PDF_set_text_pos(PDF *p, double x, double y)
Setzt die aktuelle Position für die Textausgabe auf der Seite.
x, y Aktuelle Textposition, die gesetzt werden soll.
Details Zu Beginn jeder Seite wird die Textposition auf den Standardwert (0, 0) gesetzt. Der ak-
tuelle Punkt für die Grafikausgabe und die aktuelle Textposition werden getrennt ver-
waltet.
C++ Java void show(String text)

Perl PHP PDF_show(resource p, string text)
C void PDF_show(PDF *p, const char *text)
C void PDF_show2(PDF *p, const char *text, int len)
Gibt Text in der aktuellen Schrift und Größe an der aktuellen Textposition aus.
text (Content-String) Auszugebender Text. In C darf text in PDF_show( ) keine Nullzei-

chen enthalten, da ein null-terminierter String erwartet wird; für Strings, die Nullzei-
chen enthalten können, verwenden Sie PDF_show2( ).
len (Nur für PDF_show2( )) Länge von text (in Bytes) für UCS-2-Strings, die Nullzeichen
Details Der Font muss zuvor mit PDF_setfont( ) gesetzt worden sein. Die aktuelle Textposition
wird ans Ende des ausgegebenen Texts verschoben.
Bindungen PDF_show2( ) ist nur in C verfügbar, da in allen anderen Sprachbindungen Strings belie-
bigen Inhalts an PDF_show( ) übergeben werden können.
C++ void xshow(String text, const double *xadvancelist)

C void PDF_xshow(PDF *p, const char *text, int len, const double *xadvancelist)
Gibt Text in der aktuellen Schrift und Schriftgröße aus, aber mit individueller horizon-
taler Positionierung.
text (Content-String) Auszugebender Text.
len (Nur C-Sprachbindung) Länge von text (in Bytes) für UCS-2-Strings. Ist len gleich 0,
muss ein null-terminierter String übergeben werden.
xadvancelist Array aus horizontalen Versatzwerten für die Glyphen im Text. Jeder
Wert gibt (in Benutzerkoordinaten) den relativen horizontalen Versatz zur Position an,
die nach der Ausgabe der vorangehenden Glyphe erreicht ist. Die Länge des Arrays ent-

spricht der Anzahl der Glyphen im Text. (Beachten Sie, dass diese nicht unbedingt mit
len, der Anzahl der Bytes, identisch ist!)
Details Die Schrift muss bereits mit PDF_setfont( ) gesetzt worden sein.
Bindungen Nur in der C- und C++-Sprachbindung verfügbar. Andere Bindungen können für diesel-
be Funktionalität PDF_fit_textline( ) mit der Option xadvancelist verwenden.
C++ Java void show_xy(String text, double x, double y)

Perl PHP PDF_show_xy(resource p, string text, float x, float y)
C void PDF_show_xy(PDF *p, const char *text, double x, double y)
C void PDF_show_xy2(PDF *p, const char *text, int len, double x, double y)
Gibt text mit der aktuellen Schrift aus.
text (Content-String) Auszugebender Text. In C darf text in PDF_show_xy( ) keine Null-

zeichen enthalten, da ein null-terminierter String erwartet wird; für Strings, die Nullzei-
chen enthalten können, verwenden Sie PDF_show_xy2( ).
x,y Position im benutzerdefinierten Koordinatensystem, in dem der Text ausgegeben

wird.
len (Nur für PDF_show_xy2( )) Länge von text (in Bytes) für UCS-2-Strings, die Null-
zeichen enthalten können. Ist len gleich 0, muss ein null-terminierter String übergeben
werden.
Details Der Font muss zuvor mit PDF_setfont( ) eingestellt worden sein. Die aktuelle Textpositi-
on wird ans Ende des ausgegebenen Texts bewegt.
Bindungen PDF_show_xy2( ) ist nur in C verfügbar, da in allen anderen Sprachbindungen Strings be-
liebigen Inhalts an PDF_show_xy( ) übergeben werden können
C++ Java void continue_text(String text)

Perl PHP PDF_continue_text(resource p, string text)
C void PDF_continue_text(PDF *p, const char *text)
C void PDF_continue_text2(PDF *p, const char *text, int len)
Gibt Text in der nächsten Zeile aus.
text (Content-String) Auszugebender Text. Wird ein Leerstring übergeben, wird die
Textposition in die nächste Zeile bewegt. In C darf text in PDF_continue_text( ) keine Null-
zeichen enthalten, da ein null-terminierter String erwartet wird; für Strings, die Nullzei-
chen enthalten können, verwenden Sie PDF_continue_text2( ).

len (Nur für PDF_continue_text2( )) Länge von text (in Bytes) für UCS-2-Strings, die Null-
zeichen enthalten können. Ist len gleich 0, muss ein null-terminierter String wie in PDF_
continue_text( ) übergeben werden.
Details Die Textpositionierung (x- und y-Position) und der Zeilenabstand werden durch den Pa-
rameter leading sowie den letzten Aufruf von PDF_fit_textline( ), PDF_show_xy( ) oder
PDF_set_text_pos( ) bestimmt. Die aktuelle Position wird ans Ende des auszugebenden
Texts bewegt; die x-Position wird für nachfolgende Aufrufe dieser Funktion nicht geän-
dert.
Gültigkeit page, pattern, template, glyph; diese Funktion sollte im vertikalen Textausgabemodus
nicht verwendet werden.
Bindungen PDF_continue_text2( ) ist nur in C verfügbar, da in allen anderen Sprachbindungen

Strings beliebigen Inhalts an PDF_continue_text( ) übergeben werden können.
C++ Java void fit_textline(String text, double x, double y, String optlist)

Perl PHP PDF_fit_textline(resource p, string text, float x, float y, string optlist)
C void PDF_fit_textline(PDF *p, const char *text, int len, double x, double y,
const char *optlist)
Platziert eine einzelne Textzeile unter Berücksichtigung verschiedener Optionen am

Referenzpunkt (x, y).
text (Content-String) Auszugebender Text.
len (Nur C-Sprachbindung) Länge von text (in Bytes) für UCS-2-Strings, die Null-Zei-
chen enthalten können. Ist len gleich 0, muss ein null-terminierter String übergeben
werden.
x, y Koordinaten des Referenzpunkts im Benutzerkoordinatensystem, an dem der

Text platziert wird. Die Platzierung kann durch verschiedene Optionen genauer gesteu-
ert werden.
optlist Optionsliste mit Optionen zur Formatierung gemäß Tabelle 8.19 und zur Dar-
stellung gemäß Tabelle 8.20.
Details Der aktuelle Grafikzustand ändert sich durch diese Funktion nicht. Insbesondere die ak-
tuelle Textposition sowie der aktuelle Font bleiben unbeeinflusst.
Das Aussehen der Textausgabe wird anhand der aktuellen Text- und Grafikzustandspa-
rameter festgelegt, sofern diese nicht explizit durch entsprechende Optionen über-
schrieben wurden. Der aktuelle Grafikzustand ändert sich durch diese Funktion aber
nicht (insbesondere der aktuelle Font bleibt unbeeinflusst). Die aktuelle Textposition
dagegen wird ans Ende der generierten Textausgabe verschoben.
Diese Funktion generiert bei Standard-CJK-Schriften mit CMaps, die nicht auf Unicode
basieren, keinerlei Ausgabe (siehe »Einschränkungen bei Standard-CJK-Fonts und
CMaps«, Seite 123).
Gültigkeit page, pattern, template, glyph; diese Funktion sollte nicht im vertikalen Textausgabe-
modus verwendet werden.

Tabelle 8.19 Formatierungsoptionen für PDF_fit_textline( )
Schlüssel Typ Erklärung
boxsize Float-Liste Zwei Werte, die die Breite und Höhe einer Box festlegen, relativ zu der der Text
platziert und gegebenenfalls skaliert wird. Die linke untere Ecke der Box kommt
auf dem Referenzpunkt (x, y) zu liegen. Die Platzierung des Texts und das
Einpassen in die Box werden durch die Optionen position und fitmethod
gesteuert. Ist width = 0, wird nur die Breite berücksichtigt. Ist height = 0, wird nur
die Höhe berücksichtigt. Der Text wird dann relativ zur senkrechten Strecke von y
nach y+height bzw. zur waagrechten Strecke von x nach x+width platziert.
Standardwert: {0 0}.
fitmethod Schlüsselwort Legt fest, auf welche Art der Text in die definierte Box eingepasst wird. Diese
Option wird ignoriert, wenn keine Box angegeben wurde. Standardwert: nofit
nofit Positioniert den Text lediglich, ohne ihn zu skalieren oder zu
beschneiden.
clip Positioniert den Text und beschneidet ihn an den Rändern der Box.
meet Positioniert den Text gemäß der Option position und skaliert ihn so,
dass er unter Beibehaltung seiner Proportionen vollständig in die Box
hineinpasst. Dabei kommen mindestens zwei Ränder des Texts genau
auf den Rändern der Box zu liegen.
auto Diese Methode versucht, den Text automatisch in die Box einzu-
passen. Genauer: Falls der Text in die Box passt, wird die Methode
nofit angewandt. Andernfalls wird ein Skalierungsfaktor berechnet, so
dass das Objekt in die Box passt. Ist dieser Faktor größer als 0,75 so wird
der Text geringfügig verzerrt in die Box eingepasst, andernfalls
kommt die Methode meet zum Tragen.
slice Positioniert den Text gemäß der Option position und skaliert ihn so,
dass er die Box unter Beibehaltung seiner Proportionen vollständig
ausfüllt, wobei gewährleistet ist, dass der Text in mindestens einer
Dimension vollständig in der Box enthalten ist. In der Regel ragt der
Text in der anderen Dimension teilweise aus der Box hinaus und wird
deshalb beschnitten.
entire Positioniert den Text gemäß der Option position und skaliert ihn so,
dass er die Box vollständig ausfüllt. In der Regel wird der Text durch
dieses Verfahren verzerrt. Die Option scale wird ignoriert.
locallink Optionsliste Wird diese Option übergeben, wird aus dem Text eine lokale Verknüpfung erzeugt,
das heißt eine Anmerkung mit type=Link. Die Option destname wird dabei auf
den Textparameter gesetzt. Dieser Text muss dem Namen eines benannten Ziels
entsprechen, das mit PDF_add_nameddest( ) erzeugt wurde. Folgende Optionen
können übergeben werden (siehe auch Tabelle 8.51): annotcolor, borderstyle,
dasharray, highlight (die Optionen action und usercoordinates werden
automatisch gesetzt).
margin Float-Liste Ein oder zwei Float-Werte für einen zusätzlichen horizontalen und vertikalen
Rand um die Textbox. Standardwert: 0
orientate Schlüsselwort Ausrichtung des Texts bei der Platzierung. Standardwert: north
north nach oben
east nach rechts
south nach unten
west nach links

Tabelle 8.19 Formatierungsoptionen für PDF_fit_textline( )
position Float- oder (Ausrichtungssteuerung) Ein oder zwei Werte, die die Position des Referenzpunkts
Schlüsselwort- (x, y) innerhalb der Textbox festlegen. {0 0} bezeichnet dabei die linke untere Ecke
Liste der Textbox und {100 100} die rechte obere Ecke. Wurde die Option boxsize
übergeben, bestimmt die Option position auch die Platzierung dieser Box. Die
Werte werden in Prozent der Textbreite und -höhe angegeben. Sind die beiden
Prozentwerte gleich, so genügt die Angabe eines einzigen Float-Wertes.
Statt der Werte 0, 50 und 100 können dementsprechend die Schlüsselwörter left,
center, und right (in x-Richtung) oder bottom, center und top (in y-Richtung)
verwendet werden. Wird nur ein einziges Schlüsselwort angegeben, wird für die
andere Richtung das dementsprechende Schlüsselwort verwendet. Beispiele:
{0 50} oder {left center} ergibt linksbündig ausgerichteten Text
{50 50} oder {center} ergibt mittig ausgerichteten Text
{100 50} oder {right center} ergibt rechtsbündig ausgerichteten Text
Standardwert: 0 (linke untere Ecke).
rotate Float Dreht das Koordinatensystem, wobei der Referenzpunkt als Mittelpunkt und der
übergebene Wert als Drehwinkel in Grad angesehen wird. Dabei werden die Box
und der Text gedreht. Die Drehung wird zurückgenommen, sobald Text platziert
wurde. Standardwert: 0
weblink Optionsliste Wird diese Option übergeben, wird aus dem Text ein Weblink generiert, d.h. es
wird eine Anmerkung des Typs »Link« mit Standard- oder in der Optionsliste
übergebenen Optionen erzeugt. Folgende Optionen können übergeben werden
(Einzelheiten hierzu finden Sie in Tabelle 8.51): annotcolor, borderstyle, dasharray,
highlight, linewidth (die Optionen action und usercoordinates werden
automatisch gesetzt). Der übergebene Text muss einen gültigen URL enthalten.
xadvancelist Float-Liste Legt den horizontalen Versatz aller Glyphen im Text in Benutzerkoordinaten fest.
Die Länge der Liste muss kleiner oder gleich der Anzahl der Glyphen im Text sein.
Ist die Länge kleiner als die Anzahl der Glyphen, so wird eine Exception ausgelöst,
sofern glyphwarning auf true gesetzt ist. Die in xadvancelist definierten Werte
werden statt der Standardglyphenbreiten verwendet. Andere Einstellungen wie
die Unterschneidung oder der Zeichenabstand werden nicht beeinflusst.
Tabelle 8.20 Darstellungsoptionen für PDF_fit_textline( ) und direkte oder Inline-Optionen für PDF_
create_textflow( )
charref Boolean Falls true, werden numerische Referenzen und Entity-Referenzen ersetzt (siehe
Abschnitt 4.5.5, »Character-Referenzen«, Seite 111). Standardwert: Wert des
globalen Parameters charref.
charspacing Float oder Zeichenabstand (siehe Tabelle 8.18). Prozentangaben beziehen sich auf fontsize.
Prozentwert Standardwert1 für PDF_create_textflow( ): 0.
dasharray Liste aus Länge der Striche und Zwischenräume zum Zeichnen von Text und
zwei Floats Textauszeichnung. Standardwert1 für PDF_create_textflow( ): {0 0} (d.h. eine
durchgezogene Linie)
fillcolor Farbe Füllfarbe des Texts. Standardwert1 für PDF_create_textflow( ): {gray 0}.
font Font-Handle Font-Handle, das von PDF_load_font( ) zurückgegeben wurde. Standardwert: der
aktuelle Font.
fontsize Float (Für die Option font erforderlich) Schriftgröße in Einheiten des Benutzerkoordi-
natensystems. Standardwert: die aktuelle Schriftgröße.

Tabelle 8.20 Darstellungsoptionen für PDF_fit_textline( ) und direkte oder Inline-Optionen für PDF_
create_textflow( )
glyphwarning Boolean Ist glyphwarning gleich true, so wird eine Exception ausgelöst, falls eine Glyphe
nicht ausgegeben werden kann, weil der Font die zugehörige Zeichenbeschrei-
bung nicht enthält. Bei false werden fehlende Zeichen durch ein Leerzeichen oder
Glyph-ID 0 ersetzt. Standardwert: falls angegeben, die Option textwarning, sonst
Wert des globalen Parameters glyphwarning.
horizscaling Float oder Skalierung von Text (siehe Tabelle 8.18). Standardwert1 für PDF_create_textflow( ):
Prozentwert 100.
italicangle Float Bestimmt den Neigungswinkel von kursivem Text in Grad (siehe Abschnitt 4.6.3,
»Textvarianten«, Seite 117). Standardwert1 für PDF_create_textflow( ): 0.
kerning Boolean Verhalten in bezug auf Kerning (siehe Tabelle 8.18). Standardwert: Wert des
globalen Parameters kerning.
overline Boolean Modus für Überstreichen (siehe Tabelle 8.18). Standardwert1 für PDF_create_
textflow( ): false.
shrinklimit Float oder Untere Grenze, bis zu der Text beim Einpassen maximal gestaucht werden darf.
Prozentwert Standardwert: 0.75.
strikeout Boolean Modus für Durchstreichen (siehe Tabelle 8.18). Standardwert1 für PDF_create_
textflow( ): false.
strokecolor Farbe Farbe zum Zeichnen von Text. Standardwert1 für PDF_create_textflow( ): {gray 0}.
strokewidth Float, Prozent- Strichstärke zum Zeichnen von Text (absoluter Wert oder Wert relativ zur
wert oder Schriftgröße). Das Schlüsselwort auto legt den Wert von underlinewidth für den
Schlüsselwort Font fest. Standardwert: auto.
textformat Schlüsselwort Format, das zur Interpretation des übergebenen Texts verwendet wird (siehe
Abschnitt 4.5.2, »Content-Strings, Hypertext-Strings und Name-Strings«, Seite
106). Standardwert: Wert des globalen Parameters textformat.
textrendering Integer Darstellungsmodus für Text (siehe Tabelle 8.18). Standardwert1 für PDF_create_
textflow( ): 0.
textrise Float oder Modus für den vertikalen Textversatz (siehe Tabelle 8.18). Prozentangaben
Prozentwert beziehen sich auf fontsize. Standardwert1 für PDF_create_textflow( ): 0.
underline Boolean Modus für Unterstreichen (siehe Tabelle 8.18). Standardwert1 für PDF_create_
textflow( ): false.
underline- Float, Prozent- Position der gezeichneten Linie für unterstrichenen Text relativ zur Grundlinie
position wert oder (absolute Werte oder Werte relativ zur Schriftgröße; üblich ist ein Wert von -10%).
Schlüsselwort Das Schlüsselwort auto kann verwendet werden, um den für den jeweiligen Font
spezifischen Wert aus der Fontmetrik- oder Fontdatei zu setzen. Standardwert:
auto.
underline- Float, Prozent- Strichstärke für unterstrichenen Text (absolute Werte oder Werte relativ zur
width wert oder Schriftgröße; üblich ist ein Wert von 5%). Das Schlüsselwort auto oder der Wert 0
Schlüsselwort legen einen für den jeweiligen Font spezifischen Wert fest, der aus der Fontmetrik-
oder Fontdatei abgerufen wird. Standardwert: auto.
wordspacing Float oder Wortabstand (siehe Tabelle 8.18). Prozentangaben beziehen sich auf fontsize.
Prozentwert Standardwert1 für PDF_create_textflow( ): 0.
1. Standardwert für PDF_fit_textline( ): aktueller Wert des entsprechenden Parameters im aktuellen Grafikzustand.

C++ Java double stringwidth(String text, int font, double fontsize)
Perl PHP float PDF_stringwidth(resource p, string text, int font, float fontsize)
C double PDF_stringwidth(PDF *p, const char *text, int font, double fontsize)
C double PDF_stringwidth2(PDF *p, const char *text, int len, int font, double fontsize)
Gibt die Breite von text in einem beliebigen Font zurück.
text (Content-String) Text, dessen Breite abgefragt werden soll. In C darf text in PDF_
stringwidth( ) keine Nullzeichen enthalten, da ein null-terminierter String erwartet wird;
für Strings, die Nullzeichen enthalten können, verwenden Sie PDF_stringwidth2( ).
len (Nur für PDF_stringwidth2( )) Länge von text (in Bytes) für UCS-2-Strings, die Null-
zeichen enthalten können. Ist len gleich 0, muss ein null-terminierter String übergeben
werden.
font Font-Handle, das von PDF_load_font( ) zurückgegeben wurde. Fontmetriken sind

nur für Standard-CJK-Schriften mit CMaps, die auf Unicode basieren, verfügbar. Bezieht
sich font auf eine solche Schrift, gibt diese Funktion unabhängig von den Parametern
text und fontsize immer 0 zurück (sofern beim Laden des Fonts nicht die Option
monospace übergeben wurde).
fontsize Schriftgröße, gemessen in Einheiten des Benutzerkoordinatensystems (siehe

PDF_setfont( )).
Rückgabe Breite von text in einer beliebigen mit PDF_load_font( ) gewählten Schrift sowie der in
fontsize übergebenen Schriftgröße. Der Wert, der für die Breite zurückgegeben wird,
kann negativ sein (zum Beispiel, wenn eine negative horizontale Skalierung eingestellt
wurde).
Details Bei der Berechnung der Textbreite werden die aktuellen Werte folgender Textparameter
herangezogen: horizontale Skalierung, Kerning, Zeichenabstand und Wortabstand.
Gültigkeit page, pattern, template, path, glyph, document
Bindungen PDF_stringwidth2( ) ist nur in C verfügbar, da in allen anderen Sprachbindungen Strings

beliebigen Inhalts an PDF_stringwidth( ) übergeben werden können.
int PDF_show_boxed(PDF *p, const char *text, double x, double y,

double width, double height, const char *mode, const char *feature)
Veraltet. Verwenden Sie PDF_fit_textline( ) für einzelne Zeilen und für mehrzeilige Aus-
gaben die Funktionen PDF_*_textflow( ). In zweiterem Fall erhalten Sie mit
minspacing=100%, maxspacing=10000%, nofitlimit=100% und shrinklimit=100% in etwa
das selbe Ergebnis wie mit PDF_show_boxed( ). Die Anzahl der Zeichen, die nach der For-

matierung noch übrig sind (also der Rückgabewert von PDF_show_boxed( )) lässt sich mit
PDF_info_textflow( ) und der Option remainchars abfragen.
8.3.5 Mehrzeilige Textausgabe mit Textflüssen
C++ Java int create_textflow(String text, String optlist)

Perl PHP int PDF_create_textflow(resource p, string text, string optlist)
C int PDF_create_textflow(PDF *p, const char *text, int len, const char *optlist)
Bereitet den Text zur späteren Formatierung vor und erzeugt ein Textflussobjekt.
text (Content-String) Inhalt des Textflusses, der Text in verschiedenen Zeichensätzen

und Inline-Optionslisten gemäß Tabelle 8.21 und Tabelle 8.24 enthalten kann (siehe
auch »Inline-Optionslisten für Textflüsse«, Seite 263) und Makros (siehe »Makros für
Textflussoptionen«, Seite 263). Auch wenn text ein leerer String ist, wird ein gültiges
Textfluss-Handle zurückgegeben.
len (Nur C-Sprachbindung) Länge des Texts in Bytes oder 0 für null-terminierte
Strings.
optlist Optionsliste mit Textflussoptionen gemäß Tabelle 8.21 und Tabelle 8.24. Die
Optionen in optlist werden vor den Inline-Optionslisten in text ausgewertet. Inline-Op-
tionen haben somit Vorrang vor den Optionen, die in optlist übergeben werden.
Rückgabe Textfluss-Handle, das in Aufrufen von PDF_fit_textflow( ), PDF_info_textflow( ) und PDF_

delete_textflow( ) verwendet werden kann. Das Handle ist bis zum Ende des zugehören-
den Geltungsbereichs document gültig oder bis zum Aufruf von PDF_delete_textflow( )
mit dem Handle. Im Fehlerfall gibt die Funktion den Fehlercode -1 (in PHP: 0) zurück, so-
fern der Parameter oder die Option textwarning auf false gesetzt sind. Bei true löst die
Funktion im Fehlerfall eine Exception aus.
Details Diese Funktion analysiert den übergebenen Text und erzeugt daraus eine interne Da-
tenstruktur. Sie bestimmt Textabschnitte (zum Beispiel Wörter), die später bei der For-
matierung berücksichtigt werden, verarbeitet Inline-Optionslisten, konvertiert den
Text nach Möglichkeit nach Unicode, ermittelt mögliche Zeilenumbrüche und berech-
net die Breite von Textabschnitten anhand von Schrift- und Textoptionen. Die Ermitt-
lung von Inline-Optionslisten kann für einzelne Textabschnitte oder den gesamten
Text deaktiviert werden, indem die Option textlen im Parameter optlist übergeben wird
(siehe »Inline-Optionslisten für Textflüsse«, Seite 263).
Diese Funktion bereitet den Text nur vor und gibt ihn nicht in das generierte PDF-
Dokument aus. Die tatsächliche Textausgabe erfolgt dann mit PDF_fit_textflow( ) und
dem Handle auf den vorbereiteten Textfluss.
Standardmäßig bewirken die Zeichen VT, LS, LF, CR, CRLF, NEL, PS und FF eine neue
Zeile (eine Beschreibung dieser Zeichen finden Sie in Tabelle 4.5). Diese Zeichen, mit
Ausnahme von VT und LS, veranlassen zugleich die Erzeugung eines neuen Absatzes, so
dass die Option parindent zur Anwendung kommt. FF bewirkt die sofortige Unterbre-
chung der Textplatzierung in die Fitbox (die Funktion PDF_fit_textflow( ) beendet sich
mit dem Rückgabestring _nextpage).

Ein horizontaler Tabulator (HT) verändert die Startposition für nachfolgenden Text.
Mit den Optionen hortabmethod und hortabsize wird diese Änderung im Detail gesteu-
ert.
Weiche Trennzeichen (soft hyphen, SHY) werden bei einem Zeilenumbruch durch das
in der Option hyphenchar festgelegte Zeichen ersetzt. Weitere Informationen hierzu fin-
den Sie in Abschnitt 4.9.8, »Steuerung des Algorithmus für den Zeilenumbruch«, Seite
142.
Vertikale Schreibrichtung wird nicht unterstützt.
Gültigkeit beliebig außer object
Tabelle 8.21 Optionen für PDF_create_textflow( )

textwarning Boolean Falls true, wird bei einem Fehler in einer Optionsliste oder in PDF_load_font( ) eine
Exception ausgelöst (PDF_load_font( ) wird intern aufgerufen, falls die Option
fontname übergeben wird). Die Option textwarning setzt den Standardwert für
die Optionen fontwarning und glyphwarning. Bei false gibt PDF_create_
textflow( ) den Fehlercode -1 (in PHP: 0) zurück. Standardwert: true.
fixedtext- Boolean (Wird in den Unicode-fähigen Sprachen Java und Tcl ignoriert) Ist fixedtextformat
format gleich true, verwenden alle Textfragmente und Inline-Optionslisten dasselbe
Textformat. Zur Auswahl stehen utf8, utf16, utf16be oder utf16le.
Bei false müssen Inline-Optionslisten einschließlich der Trennzeichen in winansi
kodiert sein (bzw. ebcdic auf EBCDIC-Systemen). Ausgenommen ist folgender Fall:
begoptlistchar muss im Zeichensatz des vorangehenden Textfragments kodiert
sein, wenn dieses Fragment einen Unicode-kompatiblen 8-Bit-Zeichensatz
verwendet und die Option textlen nicht übergeben wurde.
C++ Java String fit_textflow(int textflow,

double llx, double lly, double urx, double ury, String optlist)
Perl PHP string PDF_fit_textflow(resource p,
int textflow, float llx, float lly, float urx, float ury, string optlist)
C const char *PDF_fit_textflow(PDF *p,
int textflow, double llx, double lly, double urx, double ury, const char *optlist)
Gibt den nächsten Abschnitt eines Textflusses in einen rechteckigen Bereich aus.
textflow Textfluss-Handle, das von PDF_create_textflow( ) zurückgegeben wurde.
llx, lly, urx, ury x- und y-Koordinaten der linken unteren und rechten oberen Ecke des
Ausgaberechtecks (Fitbox) in Benutzerkoordinaten. Die Ecken können auch in umge-
kehrter Reihenfolge festgelegt werden.
optlist Optionsliste mit Verarbeitungsoptionen gemäß Tabelle 8.22.
Rückgabe String mit der Ursache für das Beenden der Funktion:
> _stop: der Textfluss wurde vollständig verarbeitet.
> _nextpage: die nächste Seite wird erwartet (verursacht durch das formfeed-Zeichen
U+000C). Zur Platzierung des restlichen Texts ist ein weiterer Aufruf von PDF_fit_
textflow( ) erforderlich.

> _boxfull: die Fitbox ist voll oder die maximale mit der Option maxlines festgelegte
Zeilenanzahl ist erreicht. Zur Platzierung des restlichen Texts ist ein weiterer Aufruf
von PDF_fit_textflow( ) erforderlich.
> _boxempty: die Box enthält nach der Bearbeitung keinerlei Text. Dies kann passieren,
wenn die Box so klein ist, dass kein Text hineinpasst. Um Endlosschleifen zu vermei-
den, sollten keine weiteren Aufrufe von PDF_fit_textflow( ) mit derselben Fitbox er-
folgen.
> Sonst: der vom Befehl return in einer Inline-Optionsliste übergebene String.
Gibt es mehrere Gründe für das Beenden der Funktion, so wird derjenige gewählt, der in
obiger Liste zuerst aufgeführt ist. Der Rückgabestring ist bis zum nächsten Aufruf der
Funktion gültig.
Details Anders als bei PDF_fit_textline( ) wird die von dieser Funktion erzeugte Textausgabe vom
aktuellen Text- und Grafikzustand nicht beeinflusst. Die Textdarstellung lässt sich mit
fillcolor, strokecolor und anderen Darstellungsoptionen für PDF_create_textflow( ) steu-
ern. Nach der Rückkehr von dieser Funktion ist der Textzustand unverändert. Die aktu-
elle Textposition wird jedoch ans Ende des generierten Ausgabetextes gestellt (sofern
die Option blind nicht auf true gesetzt wurde).
Tabelle 8.22 Optionen für PDF_fit_textflow( )

blind Boolean Es wird zwar keine Ausgabe generiert, aber alle Berechnungen werden
durchgeführt, so dass die Formatierungsergebnisse mit PDF_info_textflow( )
betrachtet werden können. Standardwert: false.
firstlinedist Float, Abstand zwischen dem oberen Rand der Fitbox und der Grundlinie der ersten
Prozentwert Textzeile. Angegeben wird er in Benutzerkoordinaten, als Schlüsselwort oder als
oder Prozentsatz der Schriftgröße (der Größe der ersten in der Zeile auftretenden
Schlüsselwort Schrift, wenn fixedleading=true, oder der maximal auftretenden Schriftgröße
andernfalls). Standardwert: leading.
leading Für die erste Zeile ermittelter Zeilenabstand; diakritische Zeichen wie À
berühren dabei den oberen Rand der Fitbox.
ascender Für die erste Zeile ermittelte Oberlänge; Zeichen mit großer Oberlänge
wie d oder h berühren dabei den oberen Rand der Fitbox.
capheight Für die erste Zeile ermittelte Versalhöhe; hohe Großbuchstaben wie H
berühren dabei den oberen Rand der Fitbox.
xheight Für die erste Zeile ermittelte x-Höhe; Kleinbuchstaben wie x berühren
dabei den oberen Rand der Fitbox.
Ist fixedleading=false, wird der größte Wert verwendet, der für Zeilenabstand,
Oberlänge, x-Höhe und Versalhöhe in der ersten Zeile ermittelt wurde.
fitmethod Schlüsselwort Bestimmt die Methode zum Einpassen des Textes in die Fitbox. Standardwert: clip
auto PDF_fit_textflow( ) wird solange im blind-Modus und jeweils
reduzierter Schriftgröße aufgerufen, bis der Text in die Fitbox passt.
Dabei werden noch weitere font-spezifische Optionen angewandt
(siehe fontscale).
clip Der Text wird am unteren Rand der Fitbox beschnitten.
nofit Der Text darf über den unteren Rand der Fitbox hinausreichen.
fontscale Float Der Wert von fontsize sowie die Absolutwerte (nicht die Prozentwerte) von
leading, minspacing, maxspacing, spreadlimit und space werden mit dem
übergebenen Skalierungsfaktor multipliziert. Standardwert: 1 wenn rewind=0,
sonst der Wert, der mit dem entsprechenden Aufruf von PDF_fit_textflow( )
übergeben wird.

Tabelle 8.22 Optionen für PDF_fit_textflow( )
lastlinedist Float, (Wird ignoriert bei fitmethod=nofit) Der kleinste Abstand zwischen der Grundline
Prozentwert der letzten Textzeile und dem unteren Rand der Fitbox. Angegeben wird er in
oder Benutzerkoordinaten, als Schlüsselwort oder als Prozentsatz der Schriftgröße (der
Schlüsselwort ersten in der Zeile auftretenden Schriftgröße, wenn fixedleading=true oder der
maximal in der Zeile auftretenden Schriftgröße andernfalls). Standardwert: 0,
d.h. der untere Rand der Fitbox wird als Grundlinie verwendet und die üblichen
Unterlängen reichen aus der Fitbox hinaus.
descender Für die letzte Zeile ermittelte Unterlänge; Zeichen mit Unterlängen
wie g oder j berühren dabei den unteren Rand der Fitbox.
Ist fixedleading=false wird der größte Wert verwendet, der in der letzten Zeile für
die Unterlänge ermittelt wurde.
linespreadlimit Float oder (Nur für verticalalign=justify) Größter Wert in Benutzerkoordinaten oder als
Prozentwert Prozentsatz des Zeilenabstands, um den der Zeilenabstand bei vertikaler
Ausrichtung erhöht wird. Standardwert: 200%.
maxlines Integer oder Maximale Anzahl der Zeilen in der Fitbox oder das Schlüsselwort auto, bei dem
Schlüsselwort möglichst viele Zeilen in der Fitbox platziert werden. Nach der Platzierung der
maximalen Anzahl von Zeilen gibt PDF_fit_textflow( ) den String _boxfull zurück.
Standardwert: auto.
orientate Schlüsselwort Ausrichtung des Texts bei der Platzierung. Standardwert: north
north nach oben
east nach rechts
south nach unten
west nach links
rewind Integer: Der Zustand des übergebenen Texflusses wird auf den Zustand vor einem
-2, -1, 0 oder 1 bestimmten Aufruf von PDF_fit_textflow( ) zurückgesetzt. Gegenwärtig werden
folgende Werte unterstützt. Standardwert: 0.
1 Zustand vor dem ersten Aufruf von PDF_fit_textflow( )
0 Kein Zurücksetzen
-1 Zustand vor dem letzten Aufruf von PDF_fit_textflow( )
-2 Zustand vor dem vorletzten Aufruf von PDF_fit_textflow( )
übergebene Wert als Drehwinkel in Grad angesehen wird. Dabei werden die Box
und der Text gedreht. Die Drehung wird zurückgenommen, sobald Text platziert
wurde. Standardwert: 0.
showborder Boolean Ist showborder gleich true, wird ein Rahmen um die Fitbox gezeichnet (unter
Anwendung des aktuellen Grafikzustands). Dies kann im Entwicklungsstadium
und bei der Fehlersuche nützlich sein. Standardwert: false.
verticalalign Schlüsselwort Vertikale Ausrichtung des Texts in der Fitbox; die Optionen firstlinedist und
lastlinedist werden entsprechend berücksichtigt. Standardwert: top.
top Die Formatierung beginnt in der ersten Zeile und setzt sich nach unten
unter dem Text.
center Der Text wird vertikal in der Fitbox zentriert. Füllt der Text die Fitbox
nicht vollständig aus, bleibt Weißraum über und unter dem Text.
bottom Die Formatierung beginnt in der letzten Zeile und setzt sich nach oben
über dem Text.
justify Der Text wird am oberen und unteren Rand der Fitbox ausgerichtet.
Dazu wird der Zeilenabstand bis zur durch linespreadlimit
festgelegten Grenze erhöht. Die Höhe der ersten Zeile wird nur bei
firstlinedist=leading vergrößert.

C++ Java double info_textflow(int textflow, String keyword)
Perl PHP float PDF_info_textflow(resource p, int textflow, string keyword)
C double PDF_info_textflow(PDF *p, int textflow, const char *keyword)
Ermittelt den aktuellen Zustand eines Textflusses.
textflow Textfluss-Handle, das von PDF_create_textflow( ) zurückgegeben wurde.
keyword Schlüsselwort für die abzufragende Information gemäß Tabelle 8.23.
Rückgabe Der Wert des mit keyword abgefragten Textflussparameters. Im Gegensatz zu den Para-
metern textx und texty gibt diese Funktion gibt auch im Blind-Modus korrekte geomet-
rische Informationen zurück .
Parameter textx, texty
Tabelle 8.23 Schlüsselwörter für PDF_info_textflow( )

Schlüsselwort Beschreibung
boxlinecount Anzahl der Zeilen in der letzten Fitbox.
firstparalinecount Anzahl der Zeilen im ersten Absatz der Fitbox.
lastmark Nummer der letzten Marke im letzten Textflussabschnitt, der in der letzten Fitbox
platziert wurde. Marken lassen sich mit der Option mark setzen.
leading Aktueller Wert der Option leading, der sich durch den Text und die Optionen im Textfluss
ergibt.
lastparalinecount Anzahl der Zeilen im letzten Absatz der Fitbox.
leftlinex, leftliney, x- und y-Koordinaten der Zeile in der letzten Fitbox, die am weitesten links beginnt, bzw.
rightlinex, rightliney am weitesten rechts endet.
minlinelength, Länge der kürzesten bzw. längsten Textzeile in der zuletzt gefüllten Fitbox.
maxlinelength
minliney y-Koordinate der kürzesten bzw. längsten Textzeile in der zuletzt gefüllten Fitbox.
maxliney
remainchars (Veraltet) Anzahl der noch nicht verarbeiteten Zeichen. Davon ausgeschlossen sind
Zeichen in Inline-Optionslisten und Character-Referenzen. Der Wert ist nicht unbedingt
zuverlässig, da er durch verschiedene Textersetzungen verfälscht werden kann (z.B. bei
CR/NL-Kombinationen).
textendx, textendy x- bzw. y-Koordinate der aktuellen Position nach Platzierung des Texts.
used Prozentualer Anteil (0...100) des bereits platzierten Texts.
C++ Java void delete_textflow(int textflow)

Perl PHP PDF_delete_textflow(resource p, int textflow)
C void PDF_delete_textflow(PDF *p, int textflow)
Löscht einen Textfluss und die damit verbundenen Datenstrukturen.
textflow Textflow-Handle, das von PDF_create_textflow( ) zurückgegeben wurde.

Am Ende des umschließenden Geltungsbereichs document werden alle nicht mit die-
ser Funktion gelöschten Textflüsse automatisch entfernt.

Inline-Optionslisten für Textflüsse. Der im Parameter text für PDF_create_textflow( )
übergebene Text kann eine beliebige Anzahl von Optionslisten (Inline-Optionen) mit
Textflusseinstellungen gemäß Tabelle 8.24 enthalten. All diese Optionen können auch
im Parameter optlist von PDF_create_textflow( ) übergeben werden. Ein und dieselbe Op-
tion kann in einer Optionsliste mehrmals vorkommen; gültig ist dann nur der zuletzt
eingestellte Wert.
Inline-Optionslisten sind im Zeichensatz winansi (auf EBCDIC-Systemen: ebcdic) oder
im selektierten Unicode-Format zu kodieren, falls fixedtextformat=true. Außerdem müs-
sen sie in die Zeichen eingeschlossen sein, die in den Optionen begoptlistchar und
endoptlistchar festgelegt werden (standardmäßig die Zeichen < und >).
Es kann problematisch werden, wenn das Zeichen, das eine Inline-Optionsliste ein-
leitet, auch im Text verwendet werden soll. Zur Behebung dieses Problems gibt es ver-
schiedene Möglichkeiten, deren Einsatz davon abhängt, ob der Text Inline-Optionslis-
ten enthält oder nicht.
Enthält der Text keine Inline-Optionslisten, können Sie die Interpretation von Inli-
ne-Optionslisten auf eine der folgenden Arten vollständig deaktivieren:
> Setzen Sie im Parameter optlist für PDF_create_textflow( ) die Option begoptlistchar auf
none.
> Setzen Sie im Parameter optlist für PDF_create_textflow( ) die Option textlen auf die
Textlänge.
Enthält der Text Inline-Optionslisten, können Sie den Konflikt zwischen tatsächlichem
Textinhalt und dem mit begoptlistchar definierten Zeichen zur Einleitung einer Inline-
Optionsliste auf eine der folgenden Arten vermeiden:
> Ersetzen Sie das Zeichen < überall im eigentlichen Text durch die entsprechende nu-
merische oder Entity-Referenz (< oder <) und lassen Sie nur Inline-Options-
listen mit dem Zeichen < beginnen.
> Legen Sie mit der Option begoptlistchar im Parameter optlist für PDF_create_textflow( )
ein Zeichen fest, das im Text nicht verwendet wird und starten Sie Inline-Optionslis-
ten mit diesem Zeichen.
> Legen Sie in jeder Inline-Optionsliste mit der Option textlen die Länge des nächsten
Textfragments fest (bis zum Anfang der nächsten Inline-Optionsliste). Dies ist in
manchen Situationen erforderlich, zum Beispiel wenn ein Textfragment zwischen
Inline-Optionslisten nicht in Unicode interpretiert werden kann (Einzelheiten hier-
zu finden Sie in Tabelle 8.24 und Abschnitt 4.9.6, »Steuerzeichen, Zeichenersetzung
und Symbolfonts«, Seite 139).
Hinweis Schließt eine Inline-Optionsliste unmittelbar an die vorangehende Optionsliste an, wird davon
ausgegangen, dass sie ein Textfragment der Länge 0 enthalten. Dies ist von Bedeutung, wenn
in der ersten Optionsliste die Option textlen übergeben wird.
Makros für Textflussoptionen. Optionslisten für Textflüsse (entweder inline im Text

oder direkt im Aufruf von PDF_create_textflow( )) können Makrodefinitionen oder -auf-
rufe gemäß Tabelle 8.25 enthalten. Makros sind unter Umständen nützlich, um mehr-
fach auftretende Optionen, zum Beispiel für Fontnamen oder Absatzeinrückung, ein-
mal an zentraler Stelle zu definieren. Vor dem Parsen einer Optionsliste wird jedes
enthaltene Makro durch die in der Makrodefinition festgelegte Optionsliste ersetzt. Die
daraus resultierende Optionsliste wird dann geparst. Das folgende Beispiel zeigt eine
Makrodefinition für zwei Makros:

Tabelle 8.24 Optionen für den Parameter optlist von PDF_create_textflow( ) und für Inline-Optionslisten
im Text
Alle Optionen und Parameter für PDF_load_font( ) (siehe Tabelle 8.16)
encoding String (Ist für die Option fontname erforderlich) Name des Zeichensatzes.
fontname String (Ist für die Option encoding erforderlich) Fontname. Fontnamen mit Leerzeichen
müssen in { } eingeschlossen werden.
autocidfont Diese Optionen werden nur in Kombination mit den Optionen fontname und
autosubsetting encoding berücksichtigt. Anmerkung:
embedding fontwarning Wird mit dem Wert der Option textwarning initialisiert.
fontstyle
fontwarning
monospace
subsetlimit
subsetminsize
subsetting
unicodemap
Alle Darstellungsoptionen für PDF_fit_textline( ) (siehe Tabelle 8.20)
charref font Wird ignoriert, wenn fontname und encoding angegeben sind.
charspacing fontsize Diese Option ist immer erforderlich.
dasharray
fillcolor
font
fontsize
glyphwarning
horizscaling
italicangle
kerning
overline
strikeout
strokecolor
strokewidth
textformat
textrendering
textrise
underline
underline-
position
underline-
width
wordspacing
Optionen zur Verarbeitung von Optionslisten
begoptlistchar Unichar oder Zeichen, mit dem Inline-Optionslisten beginnen. Das standardmäßig definierte
Schlüsselwort Zeichen muss unter Umständen umdefiniert werden, wenn es in seiner
ursprünglichen Bedeutung im Text enthalten ist (siehe »Inline-Optionslisten für
Textflüsse«, Seite 263). Mit dem Schlüsselwort none kann die Interpretation von
Optionslisten vollständig deaktiviert werden. Standardwert: U+003C (<).
endoptlistchar Unichar Unicode-Wert des Zeichens, mit dem Inline-Optionslisten beendet werden. Das
Zeichen U+007D (}) ist nicht zulässig. Standardwert: U+003F (>).

im Text
textlen Integer oder (Erforderlich bei Text, der nicht zu Unicode kompatible Schriften enthält, oder bei
Schlüsselwort Textteilen mit fixedtextformat=false und textformat=utf16xx in Sprachen, die
nicht Unicode-fähig sind) Länge eines nachfolgenden Textabschnitts in Bytes oder
(in Unicode-fähigen Sprachen) in Zeichen, der nicht nach Inline-Optionslisten
durchsucht wird (siehe auch »Inline-Optionslisten für Textflüsse«, Seite 263). Die
Zeichen werden gezählt, bevor Character-Referenzen aufgelöst werden, zum
Beispiel <textlen=8>①<...>. Standardwert: 0.
Optionen zur Textinterpretation
charmapping1 Liste mit Mit dieser Option lassen sich einzelne Zeichen durch andere Zeichen in beliebiger
Paaren aus Wiederholung ersetzen. Die Optionsliste enthält eines oder mehrere Paare von
zwei Unichars Unichars, wobei das erste Zeichen eines Paares durch das zweite ersetzt wird. Das
oder einem zweite Element eines Paares kann auch eine Optionsliste sein, die aus einem
Unichar und Unichar und einem Zähler besteht:
einer Integer Zähler > 0 Das Ersatzzeichen wird die angegebenen Male wiederholt.
Zähler < 0 Ein mehrfach auftretender Code wird auf den Absolutwert der
angegebenen Anzahl reduziert.
Zähler = 0 Das Zeichen wird gelöscht.
hyphenchar1 Unichar oder Das Zeichen, das ein weiches Trennzeichen bei Zeilenumbrüchen ersetzt. Durch
Schlüsselwort den Wert 0 bzw. das Schlüsselwort none werden Trennzeichen generell
unterbunden. Standardwert: U+00AD (soft hyphen), sofern im Font verfügbar,
andernfalls U+002D (hyphen-minus).
tabalignchar1 Unichar Das Zeichen, an dem dezimale Tabulatoren ausgerichtet werden. Standardwert:
U+002E (.)
Optionen zur Steuerung der Textformatierung
alignment Schlüsselwort Legt die Formatierung für die Zeilen eines Absatzes fest. Standardwert: left.
left linksbündig, beginnend bei leftindent
center mittig zwischen leftindent und rightindent
right rechtsbündig, bei rightindent endend
justify links- und rechtsbündig (Blocksatz)
avoid- Boolean Ist avoidemptybegin gleich true, werden Leerzeilen am Anfang einer Fitbox
emptybegin gelöscht. Standardwert: false.
fixedleading Boolean Ist fixedleading gleich true, wird der beim ersten Zeichen geltende Zeilenabstand
verwendet. Andernfalls wird der größte Zeilenabstand verwendet. Standardwert:
false.
hortabsize1 Float oder Legt die Breite eines horizontalen Tabulators fest2. Die Interpretation wird von der
Prozentwert Option hortabmethod beeinflusst. Standardwert: 7.5%.
hortab- Schlüsselwort Legt die Interpretation von horizontalen Tabulatoren im Text fest. Liegt die
method1 berechnete Position links der aktuellen Textposition, so wird der Tabulator
ignoriert. Standardwert: relative.
relative Die Position wird um den in hortabsize festgelegten Betrag vorgerückt.
typewriter Die Position wird auf das nächste Vielfache von hortabsize vorgerückt.
ruler Die Position wird auf den n-ten in der Option ruler verfügbaren
Tabulatorwert gesetzt, wobei n die Anzahl der bislang in der Textzeile
vorgekommenen Tabs bezeichnet. Ist n größer als die Anzahl der in
ruler verfügbaren Tabulatorpositionen, kommt die Methode relative
zum Einsatz.
lastalignment Schlüsselwort Bestimmt die Formatierung der letzten Zeile eines Absatzes. Neben allen
Schlüsselwörtern der Option alignment gibt es folgende Schlüsselwörter.
Standardwert: auto.
auto Es wird der Wert der Option alignment verwendet. Nur bei justify wird
left verwendet.

im Text
leading Float oder Zeilenabstand3. Der Wert wird wie folgt ermittelt: Befinden sich am Zeilenanfang
Prozentwert Optionslisten, ergibt sich der Zeilenabstand aus der letzten relevanten Option
(font, fontsize, leading, etc.). Befinden sich weitere Optionslisten in der Zeile,
werden diese nur bei fixedleading=false berücksichtigt. Befinden sich keine
Optionslisten in der Zeile, wird der leading-Wert herangezogen. Standardwert:
100%.
minlinecount Integer Minimale Zeilenanzahl im letzten Absatz der Fitbox. Passen so viele Zeilen nicht
mehr vollständig in die Fitbox, so werden sie zur Platzierung in der nächsten
Fitbox einbehalten. Mit dem Wert 2 lassen sich einzelne »verwaiste« Absatzzeilen
am Ende der Fitbox verhindern. Standardwert: 1.
parindent Float oder Legt den linken Einzug der ersten Zeile eines Absatzes fest2. Der Wert wird zu
Prozentwert leftindent addiert. Wird diese Option innerhalb der Zeile angegeben, so wirkt sie
wie ein Tabulator. Standardwert: 0.
rightindent Float oder Bestimmt den rechten bzw. linken Einzug aller Textzeilen2. Wird leftindent
leftindent Prozentwert innerhalb der Zeile angegeben und befindet sich die definierte Position links der
aktuellen Textposition, so wird die Option für die aktuelle Zeile ignoriert.
Standardwert: 0.
ruler1 Liste aus Liste der absoluten Tabulatorpositionen für hortabmethod=ruler1. Die Liste darf
Floats oder maximal 32 nicht-negative Einträge in aufsteigender Reihenfolge enthalten.
Prozentwerten Standardwert: Vielfache von hortabsize als Integers.
tabalignment1 Schlüsselwort- Ausrichtung für Tabulatoren. Jeder Listeneintrag definiert die Ausrichtung des
Liste entsprechenden Eintrags in der Option ruler. Standardwert: left.
center Text wird mittig an der Tabulatorposition ausgerichtet.
decimal Das erste tabalignchar-Zeichen wird linksbündig an der
Tabulatorposition ausgerichtet. Ist kein tabalignchar-Zeichen
vorhanden, wird rechtsbündig ausgerichtet.
left Text wird linksbündig an der Tabulatorposition ausgerichtet.
right Text wird rechtsbündig an der Tabulatorposition ausgerichtet.
Optionen zur Steuerung des Algorithmus für den Zeilenumbruch
adjust- Schlüsselwort Methode zur Anpassung von Textteilen, die nach einer Vergrößerung oder
method Verkleinerung des Wortabstandes, der den in den Optionen minspacing und
maxspacing definierten Grenzwerten unterliegt, nicht mehr in die Zeile passen.
Standardwert: auto.
auto Folgende Methoden werden in der angeführten Reihenfolge ange-
wandt: shrink, spread, nofit, split.
clip Wie nofit, nur dass der längere Teil am rechten Rand der Fitbox (unter
Berücksichtigung der Option rightindent) abgeschnitten wird.
nofit Das letzte Wort wird in die nächste Zeile verschoben, sofern die
verbleibende (kurze) Zeile nicht kürzer als der in der Option nofitlimit
festgelegte Prozentwert ist. Auch Absätze im Blocksatz sehen bei
dieser Methode leicht ausgefranst aus.
shrink Passt ein Wort nicht in die Zeile, wird der Text so lange gestaucht, bis
das Wort hineinpasst, sofern die Option shrinklimit dies zulässt.
Andernfalls kommt die Methode nofit zum Einsatz.
split Das letzte Wort wird nicht in die nächste Zeile verschoben, sondern
zwangsweise getrennt. Bei Textfonts (aber nicht bei Symbolfonts)
wird ein Trennzeichen eingefügt.
spread Das letzte Wort wird in die nächste Zeile verschoben. Der Rest der (kur-
zen) Zeile wird im Blocksatz ausgerichtet, indem der Zeichenabstand
innerhalb der Wörter vergrößert wird, sofern die Option spreadlimit
dies zulässt. Kann kein Blocksatz erreicht werden, kommt die Methode
nofit zum Einsatz.

im Text
avoidbreak1 Boolean Ist avoidbreak gleich true, wird jeder Zeilenumbruch nach Möglichkeit vermieden,
bis avoidbreak auf false zurückgesetzt wird. Standardwert: false.
maxspacing1 Float oder Bestimmt den maximalen bzw. minimalen Abstand zwischen Wörtern (in
minspacing1 Prozentwert Benutzerkoordinaten oder als prozentualer Anteil der Breite eines Leerzeichens).
Der berechnete Wortabstand wird durch hier übergebenen Werten begrenzt, aber
der Wert der Option wordspacing wird noch addiert. Standardwerte:
minspacing=50%, maxspacing=500%.
nofitlimit Float oder Minimale Zeilenlänge bei der Methode nofit2. Standardwert: 75%.
Prozentwert
shrinklimit Prozentwert Untere Grenze für das Stauchen von Text mit der Methode shrink. Der berechnete
Stauchungsfaktor wird durch den hier übergebenen Wert begrenzt, aber noch mit
dem Wert der Option horizscaling multipliziert. Standardwert: 85%.
spreadlimit1 Float oder Obere Grenze für den Abstand zwischen zwei Zeichen bei der Methode spread3;
Prozentwert der berechnete Abstand wird durch den hier übergebenen Wert begrenzt, aber der
Wert der Option charspacing wird noch addiert. Standardwert: 0.
Optionen, die sich wie Befehle verhalten
comment String Beliebiger Text, der ignoriert wird; nützlich zur Kommentierung von Optionslisten
oder Makros.
mark Integer Speichert die übergebene Zahl intern als Marke. Die zuletzt gespeicherte Marke
lässt sich dann mit PDF_info_textflow( ) abfragen. Dies kann nützlich sein, um zu
ermitteln, welche Textabschnitte bereits auf der Seite platziert wurden.
nextline Boolean Erzeugt eine neue Zeile oder einen neuen Absatz; dies geschieht auch bei nicht
nextparagraph Unicode-kompatiblen Fonts.
resetfont Boolean Setzt die Optionen font und fontsize auf ihre früheren Werte zurück. Dies kann
zum Beispiel nach dem Einfügen von kursivem Text sinnvoll sein. Die Option font
hat Vorrang vor dieser Option. Diese Option ist erst nach dem zweitmaligen
Einstellen eines font-spezifischen Parameters sinnvoll und wird sonst ignoriert.
return String Beendet PDF_create_textflow( ) mit dem übergebenen String als Rückgabewert.
Der String darf nicht mit einem Unterstrich _ beginnen.
space Float oder Die Textposition wird um den angegebenen Wert3 vorgerückt. Dies geschieht
Prozentwert auch in Fonts, die nicht Unicode-kompatibel sind.
1. Diese Option hat keine Auswirkung auf Text mit Schriften, die nicht Unicode-kompatibel sind (siehe Abschnitt 4.5.6, »Unicode-
kompatible Fonts«, Seite 113).
2. In Benutzerkoordinaten oder als prozentualer Anteil der Fitbox-Breite
3. In Benutzerkoordinaten oder als prozentualer Anteil der Schriftgröße
<macro {
comment { Die folgenden Makros werden als Absatzformate verwendet }
Ü1 {fontname=Helvetica-Bold encoding=winansi fontsize=14 }
Text {fontname=Helvetica encoding=winansi fontsize=12 }
}>
Diese Makros könnten wie folgt in einer Optionsliste verwendet werden:

<&Ü1>Kapitel 1
<&Text>Dieses Kapitel beschäftigt sich mit ...
Für die Definition und Verwendung von Makros gelten folgenden Regeln:
> Makros können beliebig verschachtelt werden (d.h. in Makrodefinitionen können
andere Makros aufgerufen werden).

> Makros dürfen nicht in der Optionsliste vorkommen, in der sie definiert werden.
Nach der Optionsliste, in der das Makro definiert ist, kann jedoch unmittelbar eine
weitere Optionsliste folgen, in der das Makro verwendet wird.
> Bei Makronamen wird nicht zwischen Groß- und Kleinschreibung unterschieden.
> Nicht definierte Makros lösen eine Exception aus.
> Makros können jederzeit umdefiniert werden.
Table 8.25 Makrodefinitionen und -aufrufe in Optionslisten für PDF_fit_textflow( )

macro Liste aus Jedes Paar beschreibt den Namen und die Definition eines Makros wie folgt:
Paaren name (String) Name des Makros, der später in Makroaufrufen verwendet
werden kann. Bereits definierte Makros können umdefiniert werden.
Der Sondername »comment« wird ignoriert.
suboptlist Optionsliste, durch die Makroname beim Aufruf des Makros
wortwörtlich ersetzt wird. Führende und schließende Leerzeichen
werden ignoriert.
&name – Das Makro mit dem angegebenen Namen wird expandiert, und der Makroname
(einschließlich des Zeichens &) durch den Inhalt des Makros ersetzt, also durch die
für das Makro definierte suboptlist (ohne die umgebenden Klammern). Da der
Makroname durch ein Leerzeichen, {, }, = oder & begrenzt ist, dürfen diese Zeichen
nicht Bestandteil des Makronamens sein.
Verschachtelte Makros werden ohne Einschränkung expandiert. Makros, die in
Stringoptionen enthalten sind, werden ebenfalls expandiert. Aus der
Makroexpansion muss sich eine gültige Optionsliste ergeben.
comment String Beliebiger Text, der ignoriert wird; nützlich zur Kommentierung von Makros.

8.4 Grafikfunktionen
8.4.1 Funktionen für den Grafikzustand
Alle Parameter, die sich auf den Grafikzustand beziehen, werden am Anfang einer Seite
wieder auf ihre Standardwerte zurückgesetzt. Die Standardwerte sind bei den jeweiligen
Funktionsbeschreibungen angegeben. Funktionen, die sich auf den Textzustand bezie-
hen, werden in Abschnitt 8.3, »Textfunktionen«, Seite 242, beschrieben.
Hinweis Keine der Funktionen für den Grafikzustand darf im Geltungsbereich path verwendet werden
(siehe Abschnitt 3.2, »Seitenbeschreibungen«, Seite 62).
C++ Java void setdash(double b, double w)

Perl PHP PDF_setdash(resource p, float b, float w)
C void PDF_setdash(PDF *p, double b, double w)
Setzt das aktuelle Strichmuster.
b, w Anzahl der sich abwechselnden schwarzen bzw. weißen Einheiten. b und w müs-
sen positive Zahlen sein.
Details Um eine durchgezogene Linie zu erreichen, setzen Sie b = w = 0. Am Anfang jeder Seite
wird das Strichmuster auf diese Standardwerte zurückgesetzt.
C++ Java void setdashpattern(String optlist)

Perl PHP PDF_setdashpattern(resource p, string optlist)
C void PDF_setdashpattern(PDF *p, const char *optlist)
Setzt ein Strichmuster, das über eine Optionsliste definiert ist.
optlist Optionsliste entsprechend Tabelle 8.26. Ist optlist leer, wird eine durchgezoge-
ne Linie generiert.
Tabelle 8.26 Optionen für PDF_setdashpattern( )

dasharray Float-Liste Liste aus 2 bis 8 alternierenden Werten für Strichlängen und Zwischen-
räume einer gestrichelten Linie zum Zeichnen von Pfaden (gemessen im
Benutzerkoordinatensystem). Die Array-Werte müssen größer 0 (null)
sein. Sie werden zyklisch wieder verwendet, bis der Pfad vollständig
gezeichnet ist.
dashphase Float Abstand vom Rand, ab dem der erste Strich beginnt. Standardwert: 0
Details Am Anfang jeder Seite wird der Strichmuster-Parameter auf eine durchgezogene Linie
gesetzt.

C++ Java void setflat(double flatness)
Perl PHP PDF_setflat(resource p, float flatness)
C void PDF_setflat(PDF *p, double flatness)
Setzt den Flatness-Parameter.
flatness Positive Zahl, die den maximalen Abstand (in Gerätepixeln) zwischen dem
Pfad und einer Näherung aus geraden Liniensegmenten beschreibt.
Details Am Anfang jeder Seite wird der Flatness-Parameter auf den Standardwert 1 gesetzt.
C++ Java void setlinejoin(int linejoin)

Perl PHP PDF_setlinejoin(resource p, int linejoin)
C void PDF_setlinejoin(PDF *p, int linejoin)
Legt die Verbindungsart von Linien (linejoin-Parameter) fest.
linejoin Legt die Form der Ecken in zu zeichnenden Pfaden fest (siehe Tabelle 8.27).
Details Am Anfang jeder Seite wird der linejoin-Parameter auf den Standardwert 0 gesetzt.
Tabelle 8.27 Werte für den linejoin-Parameter

Wert Beschreibung (aus der PDF-Referenz) Beispiele
0 Spitze Verbindungen (miter joins): Die beiden Pfadsegemente werden
durchgezogen, bis die äußeren Ecken sich berühren. Steht die resultierende Spitze
zu weit hervor, was durch den miterlimit-Parameter festgelegt ist, wird
stattdessen eine abgeschnittene Verbindung verwendet.
1 Abgerundete Verbindungen (round joins): Ein gefüllter Kreis mit einem der
Strichstärke entsprechenden Durchmesser wird um den Punkt gezeichnet, in dem
sich die Liniensegmente treffen. Das Ergebnis ist eine abgerundete Ecke.
2 Stumpfe Verbindungen (bevel joins): Die beiden Pfadsegmente werden nur
durchgezogen, bis die inneren Ecken sich berühren (siehe Beschreibung des
linecap-Parameters). Die verbleibende Aussparung wird mit einem Dreieck gefüllt.
C++ Java void setlinecap(int linecap)

Perl PHP PDF_setlinecap(resource p, int linecap)
C void PDF_setlinecap(PDF *p, int linecap)
Legt die Art der Linienenden (linecap-Parameter) fest.
linecap Steuert die Art der Linienenden beim Zeichnen eines Pfads (siehe Tabelle 8.28).
Details Am Anfang jeder Seite wird der linecap-Parameter auf den Standardwert 0 gesetzt.

Tabelle 8.28 Werte für den linecap-Parameter
Wert Beschreibung (aus der PDF-Referenz) Beispiele
0 Abgeschnittene Linienenden: Die Linie wird am Endpunkt des Pfads
rechtwinklig abgeschnitten.
1 Abgerundete Linienenden: Ein Halbkreis mit einem der Strichstärke

entsprechenden Durchmesser wird um den Endpunkt gezeichnet und
gefüllt.
2 Hervorstehende rechtwinklige Linienenden: Das Linienende wird um die
halbe Strichstärke verlängert und rechtwinklig abgeschnitten.
C++ Java void setmiterlimit(double miter)

Perl PHP PDF_setmiterlimit(resource p, float miter)
C void PDF_setmiterlimit(PDF *p, double miter)
Legt den Grenzwert für das Abschneiden spitzer Linien-

segmente fest (miterlimit).
Miter
miter Ein Wert größer oder gleich 1, der festlegt, wie die length
Spitze gezeichnet wird, die sich bei spitzen Verbindungen
(miter joins) ergibt.
Details Ist der linejoin-Parameter auf 0 gesetzt (für eine spitze Ver- Line width
bindung), ergibt sich eine sehr dünne Spitze, wenn die bei-
den Liniensegmente in einem schmalen Winkel zusammenlaufen. Diese Spitze wird ab-
geschnitten (das heißt die spitze Verbindung wird durch eine stumpfe ersetzt), wenn
das Verhältnis zwischen Spitzenbreite und Strichstärke den Wert des miterlimit-Parame-
ters übersteigt. Am Anfang jeder Seite wird miterlimit auf den Standardwert 10 gesetzt.
Dies entspricht einem Winkel von etwa 10,5 Grad.
C++ Java void setlinewidth(double width)

Perl PHP PDF_setlinewidth(resource p, float width)
C void PDF_setlinewidth(PDF *p, double width)
Setzt die aktuelle Strichstärke.
width Die Strichstärke in Einheiten des Benutzerkoordinatensystems.
Details Am Anfang jeder Seite wird der Parameter width auf den Standardwert 1 gesetzt.

C++ Java void initgraphics( )
Perl PHP PDF_initgraphics(resource p)
C void PDF_initgraphics(PDF *p)
Setzt alle Parameter, die sich auf Farbe und Grafikzustand beziehen, auf ihre Standard-
werte zurück.
Details Die Parameter für Farbe (color), Strichstärke (linewidth), Linienende (linecap), Verbin-
dungsart (linejoin), Grenzwert für spitze Verbindungen (miterlimit) und Strichmuster
(dash) sowie die aktuelle Transformationsmatrix (aber nicht die Parameter für den Text-
zustand) werden auf ihre jeweiligen Standardwerte zurückgesetzt. Der aktuelle Clip-
ping-Pfad ist davon nicht betroffen.
Diese Funktion kann in Situationen nützlich sein, wo der Programmablauf keine ein-
fache Verwendung von PDF_save( )/PDF_restore( ) erlaubt.
8.4.2 Speichern und Wiederherstellen des Grafikzustands
C++ Java void save( )

Perl PHP PDF_save(resource p)
C void PDF_save(PDF *p)
Speichert den aktuellen Grafikzustand in einem Stack.
Details Der Grafikzustand umfasst Parameter, die alle Arten von Grafikobjekten betreffen. Ein
Speichern des Grafikzustands wird von PDF nicht gefordert; dies ist nur notwendig,
wenn die Anwendung später wieder auf einen definierten Zustand zurückgreifen möch-
te (zum Beispiel auf ein benutzerdefiniertes Koordinatensystem), ohne erneut explizit
alle relevanten Parameter einstellen zu müssen. Beim Speichern und Wiederherstellen
des Grafikzustands werden folgende Parameter berücksichtigt:
> Grafikparameter, die mit entsprechenden Funktionen gesetzt wurden: Clipping-
Pfad, Koordinatensystem, aktuelle Position, Flatness, Linienendenstil (linecap),
Strichmuster (dash), Art der Verbindungslinien (linejoin), Strichstärke (line width),
Grenzwert für das Abschneiden spitzer Liniensegmente (miter limit)
> Farbparameter: Linien- und Füllfarben
> Grafikparameter, die mit PDF_set_gstate( ) gesetzt wurden, sowie explizite Grafikzu-
stände (siehe Abschnitt 8.4.4, »Explizite Grafikzustände«, Seite 275)
> Textposition und die meisten anderen auf Text bezogenen Parameter (siehe Liste
unten)
> einige PDFlib-Parameter (siehe Liste unten)
Paare aus PDF_save( ) und PDF_restore( ) können verschachtelt werden. Obwohl es für die-
se Art der Verschachtelung keinen durch die PDF-Spezifikation bedingten Grenzwert
gibt, dürfen Anwendungen nicht mehr als 25 Verschachtelungsebenen nutzen. Andern-
falls können Probleme beim Drucken auftreten, die sich aus Einschränkungen bei der
von PDF-Viewern erzeugten PostScript-Ausgabe ergeben. Außerdem sind einige Ver-
schachtelungsebenen für den internen Gebrauch durch PDFlib reserviert.

Gültigkeit page, pattern, template, glyph; diese Funktion muss immer paarweise mit PDF_restore( )
auftreten. Genauer gesagt müssen PDF_save( ) und PDF_restore( ) paarweise innerhalb
der Seite, des Musters, des Templates oder der Glyphendefinition auftreten.
Parameter Der save/restore-Mechanismus bezieht folgende Parameter ein: charspacing, wordspacing,

horizscaling, italicangle, leading, font, fontsize, textrendering, textrise.
Die folgenden Parameter werden nicht berücksichtigt: fillrule, kerning, underline, overline
und strikeout.
C++ Java void restore( )

Perl PHP PDF_restore(resource p)
C void PDF_restore(PDF *p)
Stellt den zuletzt im Stack gespeicherten Grafikzustand wieder her.
Details Der entsprechende Grafikzustand muss innerhalb derselben Seite, desselben Musters,
desselben Templates oder derselben Glyphendefinition gespeichert worden sein.
Gültigkeit page, pattern, template, glyph; diese Funktion muss immer paarweise mit PDF_save( )
auftreten. Genauer gesagt müssen PDF_save( ) und PDF_restore( ) paarweise innerhalb
der Seite, des Musters, des Templates oder der Glyphendefinition auftreten.
8.4.3 Funktionen zur Transformation des Koordinatensystems

Alle Transformationsfunktionen (PDF_translate( ), PDF_scale( ), PDF_rotate( ), PDF_skew( ),
PDF_concat( ), PDF_setmatrix( ) und PDF_initgraphics( )) ändern das Koordinatensystem,
das beim Zeichnen nachfolgender Objekte verwendet wird. Sie haben keinerlei Einfluss
auf bereits auf der Seite vorhandene Objekte.
C++ Java void translate(double tx, double ty)

Perl PHP PDF_translate(resource p, float tx, float ty)
C void PDF_translate(PDF *p, double tx, double ty)
Verschiebt den Ursprung des Koordinatensystems.
tx, ty Der neue Ursprung des Koordinatensystems liegt im Punkt (tx, ty), wobei sich
dessen Werte auf das alte Koordinatensystem beziehen.
C++ Java void scale(double sx, double sy)

Perl PHP PDF_scale(resource p, float sx, float sy)
C void PDF_scale(PDF *p, double sx, double sy)
Skaliert das Koordinatensystem.
sx, sy Skalierungsfaktor in x- und y-Richtung.
Details Diese Funktion skaliert das Koordinatensystem um die Faktoren sx und sy. Ein negati-
ver Skalierungsfaktor bewirkt eine Spiegelung. Eine Einheit in x-Richtung im neuen Ko-

ordinatensystem entspricht sx Einheiten in x-Richtung im alten Koordinatensystem;
Entsprechendes gilt für die y-Koordinaten.
C++ Java void rotate(double phi)

Perl PHP PDF_rotate(resource p, float phi)
C void PDF_rotate(PDF *p, double phi)
Dreht das Koordinatensystem.
phi Rotationswinkel in Grad.
Details Die Winkelmessung beginnt auf der positiven x-Achse des aktuellen Koordinatensys-
tems und erfolgt gegen den Uhrzeigersinn. Die neuen Koordinatenachsen ergeben sich
aus einer Drehung der alten Koordinatenachsen um phi Grad.
C++ Java void skew(double alpha, double beta)

Perl PHP PDF_skew(resource p, float alpha, float beta)
C void PDF_skew(PDF *p, double alpha, double beta)
Schert das Koordinatensystem.
alpha, beta Scherungswinkel in x- und y-Richtung in Grad.
Details Bei der Scherung wird das Koordinatensystem in x- und y-Richtung um die angegebe-
nen Winkel geneigt. alpha wird dabei von der positiven x-Achse des aktuellen Koordina-
tensystems ausgehend gegen den Uhrzeigersinn gemessen, und beta von der positiven
y-Achse ausgehend im Uhrzeigersinn. Beide Winkel müssen im Bereich -360˚ < alpha,
beta < 360˚ liegen und dürfen nicht -270˚, -90˚, 90˚ oder 270˚ sein.
C++ Java void concat(double a, double b, double c, double d, double e, double f)

Perl PHP PDF_concat(resource p, float a, float b, float c, float d, float e, float f)
C void PDF_concat(PDF *p, double a, double b, double c, double d, double e, double f)
Konkateniert eine Matrix zur aktuellen Transformationsmatrix.
a, b, c, d, e, f Elemente einer Transformationsmatrix. Die sechs Werte bilden eine Ma-

trix wie in PostScript oder PDF. Um entartete Transformationen zu vermeiden, darf a*d
nicht gleich b*c sein.
Details Diese Funktion konkateniert eine Matrix zur aktuellen Transformationsmatrix (CTM)
für Text und Grafik. Sie erlaubt die allgemeinste Art von Transformationen. Wenn Sie
mit dieser Art von Transformationen keine Erfahrung haben, sollten Sie stattdessen
PDF_translate( ), PDF_scale( ), PDF_rotate( ) und PDF_skew( ) verwenden. Am Anfang jeder
Seite wird die CTM auf die Einheitsmatrix [1, 0, 0, 1, 0, 0] zurückgesetzt.

C++ Java void setmatrix(double a, double b, double c, double d, double e, double f)
Perl PHP PDF_setmatrix(resource p, float a, float b, float c, float d, float e, float f)
C void PDF_setmatrix(PDF *p, double a, double b, double c, double d, double e, double f)
Setzt die aktuelle Transformationsmatrix explizit.
a, b, c, d, e, f Siehe PDF_concat( ).
Details Diese Funktion entspricht im Wesentlichen PDF_concat( ) mit dem Unterschied, dass sie
die aktuelle Transformationsmatrix verwirft und vollständig durch eine neue Matrix
ersetzt.
8.4.4 Explizite Grafikzustände
C++ Java int create_gstate(String optlist)

Perl PHP int PDF_create_gstate(resource p, string optlist)
C int PDF_create_gstate(PDF *p, const char *optlist)
Erzeugt die Definition eines Grafikzustandsobjekts.
optlist Optionsliste mit Grafikzustandsoptionen entsprechend Tabelle 8.29.
Rückgabe gstate-Handle, das in späteren Aufrufen von PDF_set_gstate( ) innerhalb des umgeben-
den Geltungsbereichs document verwendet werden kann.
Details Die Optionsliste kann beliebig viele Optionen für den expliziten Grafikzustand enthal-
ten. Manche Optionen sind jedoch nicht in allen PDF-Versionen zulässig. In der Tabelle
wird die niedrigste erforderliche PDF-Version aufgeführt.
Parameter Die Optionen opacityfill und opacitystroke dürfen nur mit dem Wert 1 verwendet werden.
Tabelle 8.29 Optionen für PDF_create_gstate( )

Option Typ Erklärung und mögliche Werte
alphaisshape Boolean (PDF 1.4) Alpha-Quellen werden als Shape (true) oder Durchlässigkeit
(false) verwendet. Standardwert: false.
blendmode Schlüssel- (PDF 1.4) Name des Farbmischmodus. Es können mehrere Farbmischmodi
wortliste festgelegt werden. Mögliche Werte: None, Normal, Multiply, Screen,
Overlay, Darken, Lighten, ColorDodge, ColorBurn, HardLight, SoftLight,
Difference, Exclusion, Hue, Saturation, Color, Luminosity. Standardwert:
None.
flatness Float Maximaler Abstand zwischen einem Pfad und seiner Annäherung (siehe
PDF_setflat( )); muss > 0 sein.
linecap Integer oder Art der Linienenden eines Pfads (siehe PDF_setlinecap( )); muss 0, 1 oder 2
Schlüsselwort sein.
linejoin Integer oder Verbindungsart von Linien eines Pfads (siehe PDF_setlinejoin( )); muss 0, 1
Schlüsselwort oder 2 sein.
linewidth Float Strichstärke (siehe PDF_setlinewidth( )); muss > 0 sein.

Tabelle 8.29 Optionen für PDF_create_gstate( )
Option Typ Erklärung und mögliche Werte
miterlimit Float Grenzwert für das Abschneiden spitzer Liniensegmente (siehe PDF_
setmiterlimit( )); muss >= 1 sein.
opacityfill Float (PDF 1.4) Konstanter Alphawert für Fülloperationen; muss >= 0 und <= 1
sein.
opacitystroke Float (PDF 1.4) Konstanter Alphawert für Zeichnen-Operationen; muss >=0 und
<=1 sein.
overprintfill Boolean Overprint (Überdrucken) für vom Zeichnen verschiedene Operationen.
overprintmode Integer Overprint-Modus. Der Modus 0 (Standardwert) bedeutet, dass jede
Farbkomponente vorhandene Seiteninhalte ersetzt; der Modus 1 (in
Acrobat »Überdruckenstandard ist nicht Null« genannt)bedeutet, dass die
Farbkomponente 0 die entsprechende Komponente unverändert lässt.
overprintstroke Boolean Overprint (Überdrucken) für Zeichnen-Operationen. Standardwert: false.
renderingintent Schlüsselwort Beim Gamut-Mapping verwendeter Rendering-Intent; mögliche
Schlüsselwörter sind: Auto, AbsoluteColorimetric, RelativeColorimetric,
Saturation, Perceptual.
smoothness Float Maximaler Fehler einer linearen Interpolation für einen Farbverlauf; muss
>= 0 und <= 1 sein.
strokeadjust Boolean Automatische Anpassung der Strichstärke. Standardwert: false.
textknockout Boolean (PDF 1.4) Beim Überblenden werden die Zeichen in einem Textobjekt als
getrennte Objekte (false) oder als ein einziges Objekt (true) angesehen.
Standardwert: true.
C++ Java void set_gstate(int gstate)

Perl PHP PDF_set_gstate(resource p, int gstate)
C void PDF_set_gstate(PDF *p, int gstate)
Aktiviert ein Grafikzustandsobjekt.
gstate Handle für ein Grafikzustandsobjekt, das von PDF_create_gstate( ) zurückgege-

ben wurde.
Details Es werden alle im Grafikzustandsobjekt enthaltenen Optionen eingestellt. Wird diese

Funktion mehrfach aufgerufen, so werden die neuen Optionen für den Grafikzustand
zu den aktuellen hinzugefügt. Nicht explizit neu gesetzte Optionen behalten ihre aktu-
ellen Werte bei. Am Anfang jeder Seite werden alle Grafikzustandsoptionen auf ihre
Standardwerte zurückgesetzt.
8.4.5 Pfadkonstruktion
Werte.
Hinweis Achten Sie darauf, immer eine der Funktionen aus Abschnitt 8.4.6, »Zeichnen und Beschneiden
von Pfaden«, Seite 280, aufzurufen, nachdem Sie die Funktionen im vorliegenden Abschnitt
verwendet haben. Sonst hat der konstruierte Pfad keinerlei Auswirkungen, und nachfolgende
Operationen führen unter Umständen zu einer PDFlib-Exception.

Tabelle 8.30 Parameter und Werte für Pfadsegmentfunktionen (siehe Abschnitt 8.2.3,
»Parameterbehandlung«, Seite 236)
get_value currentx x- bzw. y-Koordinate (in Einheiten des aktuellen Koordinatensystems) der
currenty aktuellen Position. Geltungsbereich: page, pattern, template, path.
get_value ctm_a Komponenten der aktuellen Transformationsmatrix (CTM) für Vektorgrafiken.
ctm_b Geltungsbereich: page, pattern, template, path.
ctm_c
ctm_d
ctm_e
ctm_f
C++ Java void moveto(double x, double y)

Perl PHP PDF_moveto(resource p, float x, float y)
C void PDF_moveto(PDF *p, double x, double y)
Setzt die aktuelle Position für Grafikausgabe.
x, y Koordinaten der neuen aktuellen Position.
Details Am Anfang jeder Seite wird die aktuelle Position auf den Standardwert undefined ge-
setzt. Die aktuelle Grafikposition sowie die aktuelle Textposition werden getrennt ver-
waltet.
Gültigkeit page, pattern, template, path, glyph; mit dieser Funktion beginnt der Geltungsbereich
path.
Parameter currentx, currenty
C++ Java void lineto(double x, double y)

Perl PHP PDF_lineto(resource p, float x, float y)
C void PDF_lineto(PDF *p, double x, double y)
Zeichnet eine Linie zwischen dem aktuellen und einem anderen Punkt.
x, y Koordinaten des zweiten Linienendpunkts.
Details Diese Funktion ergänzt den aktuellen Pfad um eine Linie zwischen der aktuellen Positi-
on und (x, y). Die aktuelle Position muss zuvor gesetzt worden sein. Der Punkt (x, y) wird
zur neuen aktuellen Position.
Die Linie wird um die »ideale« Linie herum zentriert, das heißt dass auf jeder Seite
der die beiden Endpunkte verbindenden Linie die halbe Strichstärke (die durch den
linewidth-Parameter vorgegeben ist) gezeichnet wird. Das Verhalten an den Endpunkten
hängt von der Einstellung des linecap-Parameters ab.
Gültigkeit path

C++ Java void curveto(double x1, double y1, double x2, double y2, double x3, double y3)
Perl PHP PDF_curveto(resource p, float x1, float y1, float x2, float y2, float x3, float y3)
C void PDF_curveto(PDF *p, double x1, double y1, double x2, double y2, double x3, double y3)
Zeichnet eine Bézier-Kurve ausgehend von der aktuellen Position, wobei drei Kontroll-
punkte benutzt werden.
x1, y1, x2, y2, x3, y3 Koordinaten der drei Kontrollpunkte.
Details Der aktuelle Pfad wird um eine Bézier-Kurve zwischen der aktuellen Position und (x3,
y3) ergänzt, wobei (x1, y1) und (x2, y2) als Kontrollpunkte dienen. Die aktuelle Position
muss zuvor gesetzt worden sein. Der Endpunkt der Kurve wird zur neuen aktuellen Po-
sition.
Gültigkeit path
C++ Java void circle(double x, double y, double r)

Perl PHP PDF_circle(resource p, float x, float y, float r)
C void PDF_circle(PDF *p, double x, double y, double r)
Zeichnet einen Kreis.
x, y Koordinaten des Kreismittelpunkts.
r Kreisradius.
Details Diese Funktion ergänzt den aktuellen Pfad um einen Kreis, der einen vollständigen Teil-
pfad darstellt. Der Punkt (x + r, y) wird zur neuen aktuellen Position. Die resultierende Fi-
gur ist in Benutzerkoordinaten kreisförmig. Wurde das Koordinatensystem in x- und y-
Richtung unterschiedlich skaliert, ist die resultierende Kurve eine Ellipse.
path.
C++ Java void arc(double x, double y, double r, double alpha, double beta)
Perl PHP PDF_arc(resource p, float x, float y, float r, float alpha, float beta)
C void PDF_arc(PDF *p, double x, double y, double r, double alpha, double beta)
Zeichnet ein Kreissegment gegen den Uhrzeigersinn.
x, y Koordinaten des Mittelpunkts des Kreissegments.
r Radius des Kreissegments. r darf nicht negativ sein.
alpha, beta Anfangs- und Endwinkel des Kreissegments in Grad.
Details Diese Funktion ergänzt den aktuellen Pfad um ein gegen den Uhrzeigersinn gezeichne-
tes Kreissegment, das bei alpha Grad beginnt und bei beta Grad endet. Sowohl bei PDF_
arc( ) als auch bei PDF_arcn( ) werden die Winkel gegen den Uhrzeigersinn gemessen, und
zwar ausgehend von der positiven x-Achse des aktuellen Koordinatensystems. Ist der

aktuelle Punkt gesetzt, dann wird von dort eine weitere gerade Linie zum Startpunkt
des Kreissegments gezeichnet. Der Endpunkt des Kreissegments wird zur neuen aktuel-
len Position.
Die Figur ist in Benutzerkoordinaten kreisförmig. Wurde das Koordinatensystem in
x- und y-Richtung unterschiedlich skaliert, hat die resultierende Kurve eine elliptische
Form.
path.
C++ Java void arcn(double x, double y, double r, double alpha, double beta)
Perl PHP PDF_arcn(resource p, float x, float y, float r, float alpha, float beta)
C void PDF_arcn(PDF *p, double x, double y, double r, double alpha, double beta)
Wie PDF_arc( ), nur dass das Kreissegment im Uhrzeigersinn gezeichnet wird.
Details Mit Ausnahme der Zeichenrichtung verhält sich diese Funktion genau wie PDF_arc( ).
Beachten Sie, dass dies auch impliziert, dass die Winkel ausgehend von der positiven x-
Achse gegen den Uhrzeigersinn gemessen werden.
C++ Java void rect(double x, double y, double width, double height)

Perl PHP PDF_rect(resource p, float x, float y, float width, float height)
C void PDF_rect(PDF *p, double x, double y, double width, double height)
Zeichnet ein Rechteck.
x, y Koordinaten der linken unteren Ecke des Rechtecks.
width, height Breite und Höhe des Rechtecks.
Details Diese Funktion ergänzt den aktuellen Pfad um ein Rechteck, das einen vollständigen
Teilpfad bildet. Die aktuelle Position muss zuvor nicht gesetzt worden sein. Der Punkt
(x, y) wird zur neuen aktuellen Position. Die Linie wird um die »ideale« Linie herum zen-
triert, das heißt dass auf jeder Seite der die beiden Endpunkte verbindenden Linie die
halbe Strichstärke (die durch den linewidth-Parameter vorgegeben ist) gezeichnet wird.
path.

C++ Java void closepath( )
Perl PHP PDF_closepath(resource p)
C void PDF_closepath(PDF *p)
Schließt den aktuellen Pfad.
Details Diese Funktion schließt den aktuellen Teilpfad, das heißt sie zeichnet eine Linie zwi-
schen der aktuellen Position und dem Startpunkt des Teilpfads.
Gültigkeit path
8.4.6 Zeichnen und Beschneiden von Pfaden

Werte.
Tabelle 8.31 Parameter und Werte für Funktionen zum Zeichnen und Beschneiden von Pfaden (siehe Abschnitt
8.2.3, »Parameterbehandlung«, Seite 236)
set_parameter fillrule Setzt die aktuelle Füllregel auf winding oder evenodd. Anhand der Füllregel legen
PDF-Viewer das Innere von Formen zum Füllen oder Beschneiden fest. Da die
beiden Algorithmen bei einfachen Formen die selben Ergebnisse liefern, muss die
Füllregel meist nicht geändert werden. Am Anfang jeder Seite wird sie auf den
Standardwert winding gesetzt. Geltungsbereich: page, pattern, template, glyph.
Hinweis Die meisten in diesem Abschnitt beschriebenen Funktionen leeren den Pfad und lassen die ak-
tuelle Position undefiniert. Auf diese Funktionen folgende Zeichenoperationen müssen die ak-
tuelle Position daher explizit setzen (zum Beispiel mit PDF_moveto( )).
C++ Java void stroke( )

Perl PHP PDF_stroke(resource p)
C void PDF_stroke(PDF *p)
Zeichnet den Pfad mit der aktuellen Strichstärke und Linienfarbe und leert ihn.
Gültigkeit path; mit dieser Funktion endet der Geltungsbereich path.
C++ Java void closepath_stroke( )

Perl PHP PDF_closepath_stroke(resource p)
C void PDF_closepath_stroke(PDF *p)
Schließt den Pfad und zeichnet ihn.
Details Diese Funktion schließt den aktuellen Teilpfad (ergänzt um eine gerade Linie zwischen
der aktuellen Position und der Startposition des Pfads) und zeichnet den kompletten
aktuellen Pfad mit der aktuellen Strichstärke und Linienfarbe.

C++ Java void fill( )
Perl PHP PDF_fill(resource p)
C void PDF_fill(PDF *p)
Füllt das Pfadinnere mit der aktuellen Füllfarbe.
Details Diese Funktion füllt das Innere des aktuellen Pfads mit der aktuellen Füllfarbe. Das In-
nere des Pfads wird durch einen von zwei Algorithmen bestimmt (siehe Parameter
fillrule). Offene Pfade werden vor dem Füllen geschlossen.
Parameter fillrule
C++ Java void fill_stroke( )

Perl PHP PDF_fill_stroke(resource p)
C void PDF_fill_stroke(PDF *p)
Zeichnet und füllt den Pfad mit der aktuellen Zeichen- und der aktuellen Füllfarbe.
Parameter fillrule
C++ Java void closepath_fill_stroke( )

Perl PHP PDF_closepath_fill_stroke(resource p)
C void PDF_closepath_fill_stroke(PDF *p)
Schließt, zeichnet und füllt den Pfad.
Details Diese Funktion schließt den aktuellen Teilpfad (ergänzt um eine gerade Linie zwischen
der aktuellen Position und dem Startpunkt des Pfads) und zeichnet und füllt den kom-
pletten aktuellen Pfad.
Parameter fillrule
C++ Java void clip( )

Perl PHP PDF_clip(resource p)
C void PDF_clip(PDF *p)
Verwendet den aktuellen Pfad als Clipping-Pfad und schließt ihn.
Details Diese Funktion verwendet den Durchschnitt des aktuellen Pfades und des aktuellen
Clipping-Pfads als Clipping-Pfad für weitere Operationen. Am Anfang jeder Seite wird
dieser auf den Standardwert gesetzt, nämlich die Seitengröße. Der Clipping-Pfad wird
vom PDF_save( )/PDF_restore( )-Mechanismus berücksichtigt. Er kann nur mittels PDF_
save( )/PDF_restore( ) vergrößert werden.

C++ Java void endpath( )
Perl PHP PDF_endpath(resource p)
C void PDF_endpath(PDF *p)
Beendet den aktuellen Pfad, ohne ihn zu zeichnen oder zu füllen.
Details Diese Funktion hat keine sichtbaren Auswirkungen auf die Seite. Sie generiert einen un-
sichtbaren Pfad auf der Seite.
8.4.7 Ebenenfunktionen
C++ Java int define_layer(String name, String optlist)

Perl PHP int PDF_define_layer(resource p, string name, string optlist)
C int PDF_define_layer(PDF *p, const char *name, int len, const char *optlist)
Erzeugt eine neue Ebenendefinition (ab PDF 1.5).
name (Unicode-String) Name der Ebene.
len (Nur C-Bindung) Länge von name (in Bytes) für UCS-2-Strings. Ist len gleich 0, muss
ein null-terminierter String übergeben werden.
optlist Optionsliste mit Ebeneneinstellungen gemäß Tabelle 8.32.
Rückgabe Ein Ebenen-Handle, das in Aufrufen von PDF_begin_layer( ) und PDF_set_layer_

dependency( ) innerhalb des umschließenden Geltungsbereichs document verwendet
werden kann.
Details PDFlib gibt eine Warnung aus, wenn eine Ebene zwar definiert, aber im Dokument nicht
benutzt wurde.
Gültigkeit document, page
Tabelle 8.32 Optionen für PDF_define_layer( )

creatorinfo Optionsliste Optionsliste, die den Inhalt und die zu dessen Erstellung benutzte Anwendung
beschreibt. Zur Verwendung dieser Option sind die beiden folgenden Einträge
erforderlich:
creator (Unicode-String) Name der zur Ebenenerstellung benutzten
Anwendung
subtype (String) Art des Inhalts, zum Beispiel »Illustration« oder »Technische
Zeichnung«
defaultstate Boolean Standardwert: true.
hypertext- Schlüsselwort Legt den Zeichensatz für den Parameter name und die Option creator fest (siehe
encoding Abschnitt 4.5.4, »String-Behandlung in nicht Unicode-fähigen Sprachen«, Seite
108). Ein leerer String entspricht unicode. Standardwert: Wert des globalen
Parameters hypertextencoding.
hypertext- Schlüsselwort Bestimmt das Format des Parameters name. Zulässige Werte sind bytes, utf8,
format utf16, utf16le, utf16be und auto. Standardwert: Wert des Parameters
hypertextformat.

Tabelle 8.32 Optionen für PDF_define_layer( )
initial- Boolean Legt den für die Ebene empfohlenen Exportzustand fest. Ist initialexportstate
exportstate gleich true, bezieht Acrobat die Ebene in die Konvertierung oder den Export in
ältere PDF-Versionen oder andere Dokumentformate mit ein. Standardwert: true.
initial- Boolean Legt den für die Ebene empfohlenen Druckzustand fest. Ist initialprintstate gleich
printstate true, bezieht Acrobat die Ebene in das Drucken des Dokuments mit ein.
Standardwert: true.
initial- Boolean Legt den für die Ebene empfohlenen Anzeigezustand fest. Ist initialviewstate
viewstate gleich true, zeigt Acrobat die Ebene beim Öffnen des Dokuments mit an.
Standardwert: true.
intent Schlüsselwort View oder Design
language Optionsliste Legt die Sprache für die Ebene fest:
lang (String; erforderlich) Sprache und eventuell Ländercode im Format, das
für die Option lang in Tabelle 8.5 beschrieben wurde
preferred (Boolean) Bei true wird diese Ebene auch verwendet, wenn ihre
Spracheinstellung nur teilweise zur Systemsprache passt. Default:
false
onpanel Boolean Ist onpanel gleich false, ist der Ebenenname im Ebenen-Fenster von Acrobat nicht
sichtbar und kann somit vom Benutzer nicht verändert werden. Standardwert:
true.
pageelement Schlüsselwort Gibt an, dass der Ebeneninhalt von der Seiteneinteilung/Paginierung abhängt: HF
für Header/Footer (Kopf-/Fusszeile), FG für Foreground Graphic
(Vordergrundbild), BG für Background Graphic (Hintergrundbild) und L für Logo.
printsubtype Optionsliste Legt fest, ob die Ebene zum Druck vorgesehen ist:
subtype (Schlüsselwort) Art des Ebeneninhalts: Trapping, PrintersMarks oder
Watermark.
printstate (Boolean) Bei true aktiviert Acrobat den Ebeneninhalt beim Drucken.
zoom Liste aus Ein oder zwei Werte, die die Sichtbarkeit der Ebene abhängig vom Zoomfaktor
Float- oder festlegen (1.0 entspricht einem Zoomfaktor von 100 Prozent). Ein einzelner Wert
Prozent- wird als der maximale Zoomfaktor angesehen, bei dem die Ebene noch angezeigt
werten wird; zwei Werte legen den minimalen und maximalen Zoomfaktor für die
Ebenenanzeige fest. Mit dem Schlüsselwort maxzoom kann der größtmögliche
Zoomfaktor angegeben werden.
C++ Java void set_layer_dependency(String type, String optlist)

Perl PHP PDF_set_layer_dependency(resource p, string type, string optlist)
C void PDF_set_layer_dependency(PDF *p, const char *type, const char *optlist)
Definiert hierarchische und Gruppenbeziehungen zwischen Ebenen (ab PDF 1.5).
type Art der Beziehung, wobei folgende Werte zulässig sind:

> GroupAllOn: Die Ebene in der Option depend wird eingeblendet, wenn alle Ebenen in
der Option group sichtbar sind.
> GroupAnyOn: Die Ebene in der Option depend wird eingeblendet, wenn irgendeine
der Ebenen in der Option group sichtbar sind.
> GroupAllOff: Die Ebene in der Option depend wird eingeblendet, wenn alle Ebenen in
der Option group ausgeblendet sind.
> GroupAnyOff: Die Ebene in der Option depend wird eingeblendet, wenn irgendeine
Ebene in der Option group ausgeblendet ist.

> Parent: Definiert eine hierarchische Beziehung zwischen der Ebene in der Option
parent und den Ebenen in der Option children. Jede Ebene darf höchstens eine parent-
Ebene haben.
> Radiobtn: Legt eine Beziehung in der Art eines Radiobuttons zwischen den Ebenen in
der Option group fest. Das bedeutet, dass jeweils höchstens eine Ebene der Gruppe
eingeblendet ist; dies ist insbesondere bei mehrsprachigen Ebenen nützlich.
> Title: Das Ebenen-Handle in der Option parent dient nicht zur unmittelbaren Steue-
rung des Seiteninhalts, sondern als als parent-Knoten für die Ebenen in der Option
children.
optlist Optionsliste für die Beziehungen zwischen Ebenen gemäß Tabelle 8.33.
Tabelle 8.33 Optionen für PDF_set_layer_dependency( )

parent Ebenen- (Nur bei type = Parent oder Title) Die Ebene, die die Mutter der Ebenen in der
Handle Option children ist.
children Liste aus (Nur bei type = Parent oder Title) Eine oder mehrere Ebenen-Handles, die die der
Ebenen- parent-Ebene untergeordneten Ebenen festlegen.
Handles
depend Ebenen- (Nur bei type = GroupAllOn, GroupAnyOn, GroupAllOff oder GroupAnyOff) Ebene,
Handle die von den Ebenen in der Option group gesteuert wird.
group Liste aus (Nur bei type = GroupAllOn, GroupAnyOn, GroupAllOff, GroupAnyOff oder
Ebenen- Radiobtn) Eines oder mehrere Ebenen-Handles, die eine Gruppe bilden.
Handles
C++ Java void begin_layer(int layer)

Perl PHP PDF_begin_layer(resource p, int layer)
C void PDF_begin_layer(PDF *p, int layer)
Beginnt eine Ebene für die nachfolgende Ausgabe auf der Seite (ab PDF 1.5).
layer Ebenen-Handle, das von PDF_define_layer( ) zurückgegeben wurde.
Details Alle Inhalte, die nach diesem Aufruf und vor einem Aufruf von PDF_begin_layer( ) oder
PDF_end_layer( ) auf der Seite ausgegeben werden, gehören zur angegebenen Ebene. Die
Sichtbarkeit der Inhalte hängt von den Ebeneneinstellungen ab.
Diese Funktion aktiviert die übergebene Ebene und deaktiviert dabei ggf. eine andere
aktive Ebene.
Gültigkeit page

C++ Java void end_layer( )
Perl PHP PDF_end_layer(resource p)
C void PDF_end_layer(PDF *p)
Deaktiviert alle aktiven Layer (ab PDF 1.5).
Details Inhalte, die nach diesem Aufruf auf der Seite ausgegeben werden, gehören keiner spezi-
ellen Ebene mehr an. Alle Ebenen müssen am Seitenende geschlossen werden.
Um von Ebene A nach Ebene B zu wechseln, reicht ein Aufruf von PDF_begin_layer( )
aus; Ebene A braucht nicht explizit mit PDF_end_layer( ) geschlossen zu werden. PDF_
end_layer( ) ist nur notwendig, um unbedingte Inhalte (die stets sichtbar sind) zu er-
stellen und alle Ebenen am Seitenende zu schließen.
Gültigkeit page

8.5 Farbfunktionen
8.5.1 Festlegen von Farbe und Farbraum
Tabelle 8.34 gibt eine Übersicht über alle in diesem Abschnitt relevanten Parameter und
Werte.
Tabelle 8.34 Parameter für Farbfunktionen

Funktion Schlüssel Beschreibung
set_parameter preserveold- Ist reserveoldpantonenames gleich false, werden die alten Name der Pantone-
pantone- Schmuckfarben in die entsprechenden neuen Farbnamen konvertiert. Bei true
names bleiben sie unverändert. Standardwert: false. Geltungsbereich: beliebig.
set_parameter spotcolor- Ist spotcolorlookup gleich false, ermittelt PDFlib Schmuckfarbnamen nicht aus der
lookup internen Datenbank. Dies kann als Behelfslösung sinnvoll sein, damit die
übergebenen kundenspezifischen Definitionen bekannter Schmuckfarbnamen
mit den von anderen Anwendungen verwendeten Definitionen übereinstimmen.
Diese Funktionalität sollte nach Möglichkeit nicht oder nur mit Vorsicht
verwendet werden. Standardwert: true. Geltungsbereich: beliebig.
C++ Java void setcolor(String fstype, String colorspace, double c1, double c2, double c3, double c4)
Perl PHP PDF_setcolor(resource p,
string fstype, string colorspace, float c1, float c2, float c3, float c4)
C void PDF_setcolor(PDF *p,
const char *fstype, const char *colorspace, double c1, double c2, double c3, double c4)
Setzt den aktuellen Farbraum und die aktuelle Farbe.
fstype Einer der Werte fill, stroke oder fillstroke, die festlegen, ob die Farbe zum Zeich-
nen, Füllen oder für beides festgelegt wird. Der veraltete Wert both entspricht dem Wert
fillstroke.
colorspace Festlegung des Farbraums durch einen der Werte gray, rgb, cmyk, spot,
pattern, iccbasedgray, iccbasedrgb, iccbasedcmyk oder lab.
c1, c2, c3, c4 Farbkomponenten für den ausgewählten Farbraum (siehe Abschnitt 3.3,
»Farbe«, Seite 69):
> Ist colorspace gleich gray, legt c1 einen Graustufenwert fest.
> Ist colorspace gleich rgb, legen c1, c2, c3 die Werte für Rot, Grün und Blau fest.
> Ist colorspace gleich cmyk, legen c1, c2, c3, c4 die Werte für Cyan, Magenta, Gelb und
Schwarz fest.
> Ist colorspace gleich spot, enthält c1 das Handle für eine Schmuckfarbe, das von PDF_
makespotcolor( ) erzeugt wurde, und c2 legt den Farbauftrag mit einem Wert zwischen
0 und 1 fest.
> Ist colorspace gleich pattern, enthält c1 das Handle für ein Füllmuster, das von PDF_
begin_pattern( ) oder PDF_shading_pattern( ) zurückgegeben wurde.
> Ist colorspace gleich iccbasedgray, legt c1 einen Graustufenwert fest.
> Ist colorspace gleich iccbasedrgb, legen c1, c2, c3 die Werte für Rot, Grün und Blau fest.
> Ist colorspace gleich iccbasedcmyk, legen c1, c2, c3, c4 die Werte für Cyan, Magenta, Gelb
und Schwarz fest.

> Ist colorspace gleich lab, legen c1, c2 und c3 Farbwerte im Farbraum CIE L*a*b* fest, wo-
bei von einer Lichtquelle vom Typ D50 ausgegangen wird. c1 definiert die Helligkeit
L* (luminance) als Wert zwischen 0 und 100; c2 und c3 legen a* und b* (Buntwerte) als
Werte zwischen -127 und 128 fest.
Details Alle Farbwerte für die Farbräume gray, rgb und cmyk sowie für den Farbauftrag des Farb-
raums spot müssen Zahlen zwischen 0 (inklusive) und 1 (inklusive) sein. Nicht verwen-
dete Parameter sollten auf 0 gesetzt werden.
Graustufenwerte, RGB-Werte und der Farbauftrag für Schmuckfarben werden ge-
mäß additiver Farbmischung interpretiert, das heißt 0 bedeutet »keine Farbe« und 1 be-
deutet »volle Intensität«. Demnach ergeben der Graustufenwert 0 sowie die RGB-Werte
(r, g, b) = (0, 0, 0) schwarz; der Graustufenwert 1 sowie die RGB-Werte (r, g, b) = (1, 1, 1) erge-
ben weiß. CMYK-Werte dagegen werden gemäß subtraktiver Farbmischung interpre-
tiert, das heißt (c, m, y, k) = (0, 0, 0, 0) bedeutet weiß und (c, m, y, k) = (0, 0, 0, 1) bedeutet
schwarz. Farbwerte zwischen 0 und 255 müssen mittels Division durch 255 in den Be-
reich zwischen 0 und 1 skaliert werden.
Am Anfang jeder Seite werden die Zeichen- und Füllfarbenwerte für die Farbräume
gray, rgb und cmyk auf den Standardwert schwarz gesetzt. Für Schmuck- und Füllmus-
terfarbe gibt es keine Standardwerte.
Beim Einsatz der Farbräume iccbasedgray/rgb/cmyk muss das zugehörige ICC-Profil
gesetzt worden sein, bevor die Parameter setcolor:iccprofilegray/rgb/cmyk verwendet
werden können (siehe Tabelle 8.36).
Gültigkeit page, pattern (nur wenn der PaintType des Füllmusters gleich 1 ist), template, glyph (nur
wenn die Option colorized der Type-3-Schrift gleich true ist), document; eine Füllmuster-
farbe kann nicht innerhalb ihrer eigenen Definition verwendet werden. Die Farbe im
Geltungsbereich document einzustellen, kann zur Definition von Schmuckfarben mit
PDF_makespotcolor( ) sinnvoll sein.
PDF/X PDF/X-1 und PDF/X-1a: colorspace = rgb, iccbasedgray/rgb/cmyk und lab sind nicht
zulässig.
PDF/X-3: colorspace = gray setzt voraus, dass die Option defaultgray in PDF_begin_
page_ext( ) gesetzt wurde, sofern das in der PDF/X-Druckausgabebedingung (Output In-
tent) festgelegte Gerät nicht mit Graustufen oder CMYK arbeitet. Bei colorspace = rgb
muss die Option defaultrgb in PDF_begin_page_ext( ) gesetzt worden sein, sofern das Ge-
rät in der PDF/X-Druckausgabebedingung nicht mit RGB arbeitet. Bei colorspace = cmyk
muss die Option defaultcmyk PDF_begin_page_ext( ) gesetzt worden sein, sofern das Ge-
rät in der PDF/X-Druckausgabebedingung nicht mit CMYK arbeitet. Bei iccbasedgray/
rgb/cmyk und lab-Farbe muss in der Ausgabebedingung ein ICC-Profil angegeben sein
(ein Standardname reicht in diesem Fall nicht aus).
Parameter setcolor:iccprofilegray/rgb/cmyk

C++ Java int makespotcolor(String spotname)
Perl PHP int PDF_makespotcolor(resource p, String spotname)
C int PDF_makespotcolor(PDF *p, const char *spotname, int reserved)
Ermittelt den Namen einer integrierten Schmuckfarbe oder erzeugt aus der aktuellen
Füllfarbe eine Schmuckfarbe mit Namen.
spotname Name einer integrierten Schmuckfarbe oder beliebiger Name für die zu de-
finierende Schmuckfarbe. Dieser Name ist auf eine Länge von maximal 126 Byte be-
schränkt. Der Name darf nur 8-Bit-Zeichen enthalten. Unicode und eingebettete Null-
zeichen werden nicht unterstützt.
reserved (Nur C-Sprachbindung) Reserviert, muss gleich 0 sein.
Rückgabe Ein Farben-Handle, das in nachfolgenden Aufrufen von PDF_setcolor( ) im ganzen Doku-
ment verwendet werden kann. Schmuckfarben-Handles können seitenübergreifend
verwendet werden, aber nicht in anderen Dokumenten. Die Anzahl der Schmuckfarben
in einem Dokument ist nicht begrenzt.
Details spotname wird verwendet, sofern er in den internen Farbtabellen gefunden wurde und
der Parameter spotcolorlookup gleich true ist (Standardeinstellung). Andernfalls werden
die Farbwerte (CMYK oder andere) der aktuellen Füllfarbe für das Aussehen einer neuen
Schmuckfarbe benutzt. Diese Alternativwerte werden nur zur Bildschirmanzeige oder
für den Low-End-Druck verwendet. Zur Erstellung von Farbseparationen wird statt der
Alternativwerte der übergebene Schmuckfarbenname verwendet.
Wurde spotname bereits in einem früheren Aufruf von PDF_makespotcolor( ) verwen-
det, ist der Rückgabewert wieder derselbe und gibt somit nicht die aktuelle Farbe wie-
der.
Der spezielle Schmuckfarbenname All kann verwendet werden, um eine Farbe in al-
len Farbseparationen zu verwenden. Dies kann zum Beispiel bei Schnittmarken sinn-
voll sein. Der Schmuckfarbenname None produziert eine Ausgabe, die auf keinem Aus-
zug sichtbar ist.
Gültigkeit page, pattern, template, glyph (nur wenn die Option colorized der Type-3-Schrift gleich
true ist), document; die aktuelle Füllfarbe darf keine Schmuckfarbe und kein Füllmuster
sein, falls eine benutzerdefinierte Schmuckfarbe angelegt wird.
PDF/X PANTONE®-Farben werden gegenwärtig nicht in den Modi PDF/X-1 und PDF/X-1a
unterstützt.
Parameter spotcolorlookup, preserveoldpantonenames
C++ Java int load_iccprofile(String profilename, String optlist)

Perl PHP int PDF_load_iccprofile(resource p, string profilename, string optlist)
C int PDF_load_iccprofile(PDF *p, const char *profilename, int len, const char *optlist)
Sucht nach einem ICC-Profil und bereitet es zur späteren Verwendung vor.
profilename (Name-String) Name einer ICCProfile-Ressource (von der Festplatte oder

einer virtuellen Datei) oder der Name einer Standardausgabebedingung für PDF/X. Letz-
terer ist nur erlaubt, wenn die Option usage auf outputintent gesetzt ist.

len (Nur C-Sprachbindung) Länge von profilename (in Bytes) für UTF-16-Strings. Ist len
gleich 0 , muss ein null-terminierter String übergeben werden.
optlist Optionsliste mit Eigenschaften zur Profilbehandlung entsprechend Tabelle

8.35.
Tabelle 8.35 Optionen für PDF_load_iccprofile( )

Schlüssel Typ Erklärung und mögliche Werte
usage Schlüsselwort Beschreibt, wie das ICC-Profil verwendet werden soll (Standardwert:
iccbased).
iccbased das ICC-Profil wird zur Definition eines ICC-basierten
Farbraums verwendet oder auf ein Bild angewandt.
outputintent
das ICC-Profil wird zur Definition einer Druckausgabe-
bedingung für PDF/X verwendet.
description String Wird nur bei usage = outputintent verwendet. Diese Option enthält eine
Klartextbeschreibung des ICC-Profils, die gemeinsam mit der
Druckausgabebedingung für PDF/X verwendet wird. Standardwert:
bezieht sich profilename auf eine Standardausgabebedingung, wird die
Beschreibung einer internen Liste entnommen; andernfalls liegt keine
Beschreibung vor.
embedprofile Boolean Wird nur bei usage = outputintent verwendet. Diese Option erzwingt die
Verwendung eines eingebetteten ICC-Profils selbst dann, wenn als
Profilname eine Standard-Druckausgabebedingung übergeben wurde.
Rückgabe Ein Profil-Handle, das in nachfolgenden Aufrufen von PDF_load_image( ) oder zum Ein-
stellen von profilspezifischen Parametern verwendet werden kann. Der Rückgabewert
muss auf den Wert -1 (in PHP: 0) überprüft werden, der einen Fehler anzeigt. Um genau-
ere Informationen über die Art eines profilspezifischen Problems (Datei nicht gefun-
den, Format nicht unterstützt etc.) zu erhalten, setzen Sie den Parameter iccwarning auf
true. Das zurückgegebene Profil-Handle kann nicht über mehrere PDF-Dokumente hin-
weg eingesetzt werden. Auch ist es nicht auf ein Rasterbild anwendbar, wenn die Option
usage gleich outputintent ist. Es gibt keine Obergrenze für die Anzahl der in einem Doku-
ment enthaltenen ICC-Profile.
Details Ist usage = iccbased, wird das benannte Profil gemäß der in Abschnitt 3.3.4, »Colorma-
nagement und ICC-Profile«, Seite 73, beschriebenen Suchstrategie ermittelt. Wurde das
Profil gefunden, wird es auf seine Eignung hin überprüft (zum Beispiel bezüglich der
Anzahl der Farbkomponenten). Das sRGB-Profil ist in jedem Fall intern verfügbar und
darf nicht gesondert definiert werden.
Ist die Option usage auf outputintent gesetzt, wird der übergebene Name zunächst in
einer intern gehaltenen Liste von Standarddruckausgabebedingungen gesucht. Schlägt
dieser Versuch fehl, wird der Name in der Liste der benutzerdefinierten Druckausgabe-
bedingungen gesucht. Ist der übergebene Name als Standarddruckausgabebedingung
in der internen oder der benutzerdefinierten Liste verzeichnet, wird kein entsprechen-
des ICC-Profil gesucht, sondern der mit der Option description übergebene Name in die
PDF-Ausgabe als Druckausgabebedingung für PDF/X eingebettet. Ist der Name nicht in
den beiden Listen verzeichnet, wird er als Profilname interpretiert und das entspre-
chende ICC-Profil als Druckausgabebedingung für PDF/X in das PDF eingebettet.

Gültigkeit document; ist usage = iccbased, sind auch die folgenden Geltungsbereiche zulässig: page,
pattern, template, glyph.
PDF/X Die Ausgabebedingung für das generierte Dokument muss entweder mit dieser Funk-
tion gesetzt oder die Ausgabebedingung eines importierten Dokuments mit PDF_
process_pdi( ) kopiert werden.
Tabelle 8.36 Parameter und Werte für ICC-Profile

set_ ICCProfile Die zugehörige Zeile aus der Ressourcendatei, so wie sie in einer UPR-Datei in der
parameter Standard- entsprechenden Kategorie eingetragen wäre (see Abschnitt 3.1.5,
OutputIntent »Ressourcenkonfiguration und Dateisuche«, Seite 56). Bei mehreren Aufrufen wird
die interne Liste um weitere Einträge ergänzt (siehe auch resourcefile in Tabelle
8.3). Geltungsbereich: beliebig.
set_parameter iccwarning Aktiviert oder deaktiviert Warnungen (nicht-fatale Exceptions), die sich auf ICC-
Profile beziehen. Mögliche Werte sind true und false, Standardwert ist false.
get_value icccomponents Gibt die Anzahl der Farbkomponenten des ICC-Profils zurück, das durch das vom
im Modifizierer übergebenen Handle bezeichnet wird.
set_value setcolor:icc- Definiert ein ICC-Profil für einen Graustufen-Farbraum zum Einsatz mit PDF_
profilegray setcolor( ). Geltungsbereich: document, page, pattern, template, glyph.
set_value setcolor:icc- Definiert ein ICC-Profil für einen RGB-Farbraum zum Einsatz mit PDF_setcolor( ),
profilergb Geltungsbereich: document, page, pattern, template, glyph.
set_value setcolor:icc- Definiert ein ICC-Profil für einen CMYK-Farbraum zum Einsatz mit PDF_setcolor( ).
profilecmyk Geltungsbereich: document, page, pattern, template, glyph.
set_value defaultgray Veraltet: Verwenden Sie die Optionen defaultgray, defaultrgb und defaultcmyk in
defaultrgb PDF_begin/end_page_ext( ).
defaultcmyk
8.5.2 Füllmuster und Farbverläufe
C++ Java int begin_pattern(double width, double height, double xstep, double ystep, int painttype)
Perl PHP int PDF_begin_pattern(resource p,
float width, float height, float xstep, float ystep, int painttype)
C int PDF_begin_pattern(PDF *p,
double width, double height, double xstep, double ystep, int painttype)
Leitet die Definition eines Füllmusters ein.
width, height Die Abmessungen der Boundingbox des Füllmusters in Punkt.
xstep, ystep Die Offsets, die beim Zeichnen oder Füllen eines Objekts bei wiederholter
Platzierung des Füllmusters verwendet werden. In den meisten Anwendungen werden
diese Werte auf width und height gesetzt.
painttype Ist painttype gleich 1, dann muss das Füllmuster eine eigene Farbspezifika-
tion enthalten, die bei seinem Einsatz herangezogen wird; ist painttype gleich 2, darf das
Füllmuster keinerlei Farbspezifikation enthalten. Stattdessen wird die aktuelle Zeichen-

oder Füllfarbe angewandt, wenn das Füllmuster zum Zeichnen oder Füllen benutzt
wird.
Rückgabe Ein Handle auf das Füllmuster, das in nachfolgenden Aufrufen von PDF_setcolor( ) inner-
halb des umschließenden Geltungsbereichs document verwendet werden kann.
werte zurück. Hypertext-Funktionen und Funktionen zum Öffnen von Rasterbildern
dürfen innerhalb einer Füllmusterdefinition nicht verwendet werden. Erlaubt sind da-
gegen alle Text-, Grafik- und Farbfunktionen (mit Ausnahme des Füllmusters, das gera-
de definiert wird).
Gültigkeit document, pattern; mit dieser Funktion beginnt der Geltungsbereich pattern; diese
Funktion muss immer paarweise mit PDF_end_pattern( ) auftreten.
C++ Java void end_pattern( )

Perl PHP PDF_end_pattern(resource p)
C void PDF_end_pattern(PDF *p)
Beendet eine Füllmusterdefinition.
Gültigkeit pattern; mit dieser Funktion endet der Geltungsbereich pattern; diese Funktion muss
immer paarweise mit PDF_begin_pattern( ) auftreten.
C++ Java int shading_pattern(int shading, String optlist)

Perl PHP int PDF_shading_pattern(resource p, int shading, string optlist)
C int PDF_shading_pattern(PDF *p, int shading, const char *optlist)
Definiert ein Farbverlaufsmuster anhand eines Farbverlaufsobjekts (ab PDF 1.4).
shading Farbverlauf-Handle, das von PDF_shading( ) zurückgegeben wurde.
optlist Optionsliste für die Eigenschaften des Farbverlaufmusters entsprechend Ta-

belle 8.37.
Rückgabe Muster-Handle, das innerhalb des Geltungsbereichs document in späteren Aufrufen von
PDF_setcolor( ) verwendet werden kann.
Details Diese Funktion dient zum Füllen beliebiger Objekte mit einem Farbverlauf. Dazu muss
mit PDF_shading( ) zunächst ein Farbverlauf-Handle bezogen und dann mit PDF_
shading_pattern( ) auf Basis dieses Farbverlaufs ein Muster definiert werden. Das Mus-
ter-Handle wiederum wird an PDF_setcolor( ) übergeben, das die aktuelle Farbe auf das
Farbverlaufsmuster setzt.
Gültigkeit document, page, font
Tabelle 8.37 Optionen für PDF_shading_pattern( )

gstate Handle Grafikzustand-Handle

C++ Java void shfill(int shading)
Perl PHP PDF_shfill(resource p, int shading)
C void PDF_shfill(PDF *p, int shading)
Füllt einen Bereich mit einem Farbverlauf, der auf einem Farbverlaufsobjekt basiert (ab
PDF 1.4).
shading Farbverlaufsobjekt, das mit PDF_shading( ) angelegt wurde.
Details Diese Funktion ermöglicht die Verwendung von Farbverläufen, ohne PDF_shading_
pattern( ) oder PDF_setcolor( ) einzubeziehen. Sie funktioniert aber nur bei einfachen For-
men, bei denen die Geometrie des zu füllenden Objekts derjenigen des Farbverlaufs ent-
spricht. Da der aktuelle Clipping-Bereich mit dem Farbverlauf gefüllt wird (was von den
Farbverlaufsoptionen extend0 und extend1 beeinflusst wird), wird diese Funktion in der
Regel in Kombination mit PDF_clip( ) verwendet.
Gültigkeit page, pattern (falls der painttype-Parameter des Musters gleich 1 ist), template, glyph (falls
die Option colorized des Type-3-Fonts gleich true ist), document
C++ Java int shading(String shtype, double x0, double y0, double x1, double y1,
double c1, double c2, double c3, double c4, String optlist)
Perl PHP int PDF_shading(resource p, string shtype, float x0, float y0, float x1, float y1,
float c1, float c2, float c3, float c4, string optlist)
C int PDF_shading(PDF *p, const char *shtype, double x0, double y0, double x1, double y1,
double c1, double c2, double c3, double c4, const char *optlist)
Definiert einen Farbverlauf zwischen der aktuellen Füllfarbe und der übergebenen
Farbe (ab PDF 1.4).
shtype Typ des Farbverlaufs: axial für lineare und radial für kreisförmige Verläufe.
x0, y0, x1, y1 Bei linearen Farbverläufen bilden (x0, y0) und (x1, y1) die Koordinaten des
Anfangs- und Endpunkts des Farbverlaufs. Bei kreisförmigen Farbverläufen legen sie
die Mittelpunkte der Anfangs- und Endkreise fest.
c1, c2, c3, c4 Farbwerte des Endpunkts des Farbverlaufs, die im Farbraum der aktuellen
Füllfarbe auf dieselbe Art wie die Farbparameter in PDF_setcolor( ) interpretiert werden.
Ist die aktuelle Füllfarbe eine Schmuckfarbe, wird c1 ignoriert und c2 enthält den
Farbauftrag.
optlist Optionsliste mit Farbverlaufseigenschaften gemäß Tabelle 8.38.
Rückgabe Farbverlauf-Handle, das innerhalb des Geltungsbereichs document in späteren Aufrufen

von PDF_shading_pattern( ) und PDF_shfill( ) verwendet werden kann.
Details Die aktuelle Füllfarbe wird für den Startpunkt verwendet; sie darf nicht auf einem Mus-
ter basieren.
Gültigkeit document, page, font

Tabelle 8.38 Optionen für PDF_shading( )
N Float Exponent der Farbübergangsfunktion; muss > 0 sein. Standardwert: 1.
r0 Float (Nur relevant bei kreisförmigen Farbverläufen, dann aber erforderlich)
Radius des Anfangskreises.
r1 Float (Nur relevant bei kreisförmigen Farbverläufen, dann aber erforderlich)
Radius des Endkreises.
extend0 Boolean Legt fest, ob der Farbverlauf über den Startpunkt hinaus verlängert
werden soll. Standardwert: false.
extend1 Boolean Legt fest, ob der Farbverlauf über den Endpunkt hinausreichen soll.
antialias Boolean Legt fest, ob Antialiasing (Kantenglättung) für den Farbverlauf aktiviert
wird. Standardwert: false.

8.6 Rasterbild- und Template-Funktionen
Tabelle 8.39 gibt eine Übersicht über alle in diesem Abschnitt relevanten Parameter und
Werte.
Tabelle 8.39 Parameter und Werte für die Rasterbildfunktionen (siehe Abschnitt 8.2.3, »Parameterbehandlung«,
Seite 236)
get_value imagewidth Ermittelt die Breite (width) bzw. Höhe (height) eines Bilds in Pixeln. Der
imageheight Modifizierer enthält das Handle des gewünschten Bilds. Geltungsbereich:
page, pattern, template, glyph, document, path.
get_value orientation Ermittelt die Orientierung eines Bilds. Der Modifizierer enthält das Handle
des gewünschten Bilds. Bei Tiff-Bildern mit Orientation-Tag wird der Wert
dieses Tags zurückgeliefert; in allen anderen Fällen der Wert 1. PDFlib kom-
pensiert automatisch alle Orientation-Werte ungleich 1. Geltungsbereich:
page, pattern, template, glyph, document, path.
get_value resx Ermittelt die horizontale bzw. vertikale Auflösung eines Bilds. Der Modi-
resy fizierer enthält das Handle des gewünschten Bilds. Geltungsbereich: page,
pattern, template, glyph, document, path.
Ist der Rückgabewert positiv, so enthält er die Bildauflösung in Pixeln pro
Zoll (dots per inch, dpi). Ist der Rückgabewert negativ, kann über resx und
resy das Seitenverhältnis nicht-quadratischer Pixel ermittelt werden; ihre
absoluten Werte sind dann aber bedeutungslos. Ist der Rückgabewert 0,
so ist die Bildauflösung unbekannt.
set_ honoriccprofile Liest in Rasterbilder eingebettete ICC-Farbprofile und wendet sie auf die
parameter Bilddaten an. Standardwert: true.
set_parameter imagewarning Mit diesem Parameter kann eine Exception veranlasst werden, wenn ein
Bild mit PDF_load_image( ) nicht geöffnet werden konnte. Standardwert:
false. Geltungsbereich: beliebig.
true Beim Scheitern einer Bildfunktion wird eine Exception ausge-
löst und -1 (in PHP: 0) zurückgegeben. Der mit der Exception
gelieferte Text kann bei der Fehlersuche hilfreich sein.
false Beim Scheitern einer Bildfunktion wird keine Exception
ausgelöst. Stattdessen gibt die Funktion im Fehlerfall einfach -1
(in PHP: 0) zurück. Beachten Sie, dass in bestimmten Fällen
(meist bei beschädigten komprimierten Bilddaten) PDFlib auch
bei imagewarning=false eine Exception auslösen kann.
set_value image:iccprofile Handle für ein ICC-Profil, das auf alle entsprechenden Bilder angewandt
wird, sofern nicht die Option iccprofile übergeben wird.
get_value image:iccprofile Gibt ein Handle für das ICC-Profil zurück, das in das Bild eingebettet ist,
das von dem im Modifizierer übergebenen Handle referenziert wird
set_value renderingintent Rendering-Intent für Bilder. Mögliche Schlüsselwörter und ihre Bedeutung
finden Sie in Tabelle 3.7. Standardwert: Auto.

8.6.1 Rasterbilder
C++ Java int load_image(String imagetype, String filename, String optlist)

Perl PHP int PDF_load_image(resource p, string imagetype, string filename, string optlist)
C int PDF_load_image(PDF *p,
const char *imagetype, const char *filename, int len, const char *optlist)
Öffnet eine (auf der Festplatte liegende oder virtuelle) Bilddatei unter Anwendung ver-
schiedener Optionen.
imagetype Wenn Sie den String auto übergeben, versucht PDFlib, den Typ der Bildda-
tei automatisch zu erkennen (dies ist bei Bildern vom Typ CCITT und raw nicht möglich
und darf bei der Option reftype mit dem Wert url oder fileref nicht verwendet werden). Es
beschleunigt die Verarbeitung etwas, wenn Sie das Bildformat explizit mit einem der
Strings bmp, ccitt, gif, jpeg, jpeg2000, png, raw oder tiff übergeben (weitere Informationen
hierzu finden Sie in Abschnitt 5.1.2, »Unterstützte Rasterbildformate«, Seite 148). Der
Typ jpeg2000 benötigt PDF ab Version 1.5. Der Typ ccitt unterscheidet sich von einer
TIFF-Datei, die CCITT-komprimierte Bilddaten enthält.
filename (Name-String) Name der Bilddatei, die geöffnet werden soll. Es muss sich um
eine lokale oder virtuelle Datei handeln, da PDFlib keine Bilddaten von URLs bezieht.
len (Nur C-Sprachbindung) Länge von filename (in Bytes) für UTF-16-Strings. Ist len
optlist Optionsliste mit Bildeigenschaften gemäß Tabelle 8.40.
Rückgabe Handle für das Bild, das in nachfolgenden Aufrufen von Bildfunktionen verwendet wer-
den kann. Der Rückgabewert muss auf den Wert -1 (in PHP: 0) überprüft werden, der ei-
nen Fehler anzeigt. Um genauere Angaben über die Art eines bildspezifischen Problems
zu erhalten (zum Beispiel falscher Dateiname, nicht unterstütztes Format, fehlerhafte
Bilddaten etc.), setzen Sie den Parameter oder die Option imagewarning auf true (siehe
Tabelle 8.39 und Tabelle 8.40). Das unterstützte Image-Handle kann nicht über mehrere
PDF-Dokumente hinweg verwendet werden.
Details Diese Funktion öffnet und analysiert eine Rasterbilddatei in einem der unterstützten
Dateiformate, das mit dem Parameter imagetype festgelegt wurde, und kopiert alle rele-
vanten Bilddaten in das Ausgabedokument. Die Funktion hat keinen sichtbaren Ein-
fluss auf die Ausgabe. Um das importierte Bild tatsächlich im generierten Ausgabedo-
kument zu platzieren, muss PDF_fit_image( ) aufgerufen werden. Ein Bild sollte für jedes
generiertes Dokument nur einmal geöffnet werden, da die Bilddaten sonst mehrfach
ins Ausgabedokument kopiert werden.
PDFlib öffnet die Bilddatei mit dem in filename übergebenen Namen, verarbeitet den
Inhalt und schließt sie wieder, bevor von diesem Funktionsaufruf zurückgekehrt wird.
Bilder können innerhalb eines Dokuments mehrfach platziert werden (siehe PDF_fit_
image( )), die zugehörige Bilddatei ist dann aber bereits geschlossen.
Ist imagetype = raw oder ccitt, müssen die Optionen width, height, components und bpc
übergeben werden, da PDFlib diese Angaben nicht aus den Bilddaten ableiten kann. Der
Benutzer muss dafür Sorge tragen, dass die Optionswerte auch zum Bild passen. Sonst
besteht die Gefahr, dass die PDF-Ausgabe fehlerhaft ist und Acrobat mit der Meldung
Nicht genügend Daten für ein Bild reagiert.

Ist imagetype = raw, müssen die übergebenen Bilddaten [width x components x bpc / 8]
x height Byte lang sein, wobei der Term in eckigen Klammern auf die nächste ganze Zahl
aufgerundet wird. Die Pixel werden in der Standardreihenfolge von PostScript/PDF er-
wartet, das heißt von oben nach unten und von links nach rechts (unter der Annahme,
dass die Koordinaten nicht transformiert wurden). Bei 16-Bit-Werten muss das höher-
wertige Byte zuerst übergeben werden (Big-Endian- oder »Mac«-Bytereihenfolge). Die
Wertigkeit der Pixel wird in Abschnitt 3.3.1, »Farben und Farbräume«, Seite 69, beschrie-
ben. Ist bpc kleiner 8 ist, beginnt jede Pixelreihe an einer Bytegrenze und die Farbwerte
müssen innerhalb eines Bytes von links nach rechts angeordnet sein. Alle Farbwerte ei-
nes Pixels folgen unmittelbar aufeinander, das heißt dass zuerst alle Farbwerte für das
erste Pixel, dann alle Werte für das zweite Pixel etc. übergeben werden.
Gültigkeit Wurde die Option inline nicht angegeben, so ist der Geltungsbereich document, page, font
und die Funktion muss immer paarweise mit PDF_close_image( ) auftreten. Die Ausgabe-
größe ist ein wenig geringer, wenn das Bild innerhalb des Geltungsbereichs document
oder font statt im Geltungsbereich page geladen wird. Wird die Option inline übergeben,
so ist der Geltungsbereich page, pattern, template, glyph, und ein Aufruf von PDF_close_
image( ) ist nicht erforderlich.
PDF/X Alle PDF/X-Kompatibilitätsstufen:

> Die Optionen OPI-1.3 und OPI-2.0 sind nicht erlaubt.
> Die Option masked ist nur zulässig, wenn sich die Maske auf ein 1-Bit-Bild bezieht.
> JPEG2000-Bilder sind nicht erlaubt, da sie PDF ab Version 1.5 benötigen.
PDF/X-1 und PDF/X-1a: RGB-Bilder sind nicht erlaubt.

PDF/X-3: Graustufenbilder setzen voraus, dass die Option defaultgray in PDF_begin_
page_ext( ) gesetzt wurde, sofern das in der PDF/X-Druckausgabebedingung (Output In-
tent) festgelegte Gerät nicht mit Graustufen oder CMYK arbeitet. Bei RGB-Bildern muss
die Option defaultrgb in PDF_begin_page_ext( ) gesetzt worden sein, sofern das in der
PDF/X-Druckausgabebedingung festgelegte Gerät nicht mit RGB arbeitet. Bei CMYK-Bil-
dern muss die Option defaultcmyk in PDF_begin_page_ext( ) gesetzt worden sein, sofern
das in der PDF/X-Druckausgabebedingung festgelegte Gerät nicht mit CMYK arbeitet.
Parameter imagewidth, imageheight, resx, resy, imagewarning
Tabelle 8.40 Optionen für PDF_load_image( )

bitreverse Boolean (Nur bei imagetype = ccitt) Bei true wird die Bitreihenfolge eines jeden Bytes in
den komprimierten Daten umgekehrt. Standardwert: false.
bpc Integer (Nur bei imagetype = raw und dann erforderlich) Anzahl der Bits pro
Komponente; muss 1, 2, 4 oder 8 sein. In PDF 1.5 ist auch bpc=16 zulässig.
colorize Schmuckfar- (Wird ignoriert, wenn die Option iccprofile übergeben wird; nicht für
ben-Handle imagetype=jpeg2000) Färbt das Bild anhand eines Schmuckfarben-Handle ein,
das mittels PDF_makespotcolor( ) erzeugt wurde. Das Bild muss ein Schwarzweiß-
oder Graustufenbild sein.
components Integer (Nur bei imagetype = raw und dann erforderlich) Anzahl der Bildkomponenten
(Kanäle); muss 1, 3 oder 4 sein.
height Integer (Nur bei imagetype = raw oder ccitt und dann erforderlich) Bildhöhe in Pixeln.
honor- Boolean (Nur bei imagetype = jpeg, png oder tiff; wird auf false gesetzt, wenn die Option
iccprofile colorize übergeben wird) Liest ein eingebettetes ICC-Profil ein (falls vorhanden)
und wendet es auf das Bild an. Standardwert: Wert des Parameters honoricc-
profile.

hypertext- Schlüsselwort Legt den Zeichensatz für die Option iconname fest (siehe Abschnitt 4.5.4, »String-
encoding Behandlung in nicht Unicode-fähigen Sprachen«, Seite 108). Ein leerer String ent-
spricht unicode. Standardwert: Wert des globalen Parameters hypertextencoding.
iccprofile ICC-Handle (Nur bei imagetype = jpeg, png und tiff) Handle eines ICC-Profils, das auf das Bild
angewandt werden soll. Standardwert: eingebettetes Profil, sofern eines im Bild
vorhanden und die Option honoriccprofile gleich true ist.
iconname Hypertext- (Wird ignoriert, falls inline=true; erzwingt template=true) Weist der importierten
String Seite einen Namen zu, über den via JavaScript auf die Seite verwiesen werden
kann. DIes ist z.B. nützlich, um die Seite einem Formularfeld als Symbol
zuzuweisen.
ignoremask Boolean Alle in der Bilddatei vorhandenen Transparenzinformationen werden ignoriert.
ignore- Boolean (Nur für imagetype=tiff) Ignoriert ein eventuell im Bild vorhandenes Orientation-
orientation Tag zur Angabe der Seitenausrichtung. Dies kann zur Korrektur falscher
Orientierungsangaben dienen. Standardwert: false.
image- Boolean Aktiviert Exceptions, falls das Bild nicht geöffnet werden kann. Standardwert:
warning Wert des globalen Parameters imagewarning.
inline Boolean (Nur bei imagetype = ccitt, jpeg oder raw) Bei true wird das Bild direkt in den
Content-Stream der Seiten-, Muster-, Template- oder Glyphenbeschreibung
eingefügt (siehe Abschnitt 5.1.1, »Grundlegende Vorgehensweise«, Seite 147).
interpolate Boolean Aktiviert die Interpolation des Bilds, um das Aussehen auf Bildschirm und
Ausdruck zu verbessern. Dies ist insbesondere bei Rasterbildern nützlich, die als
Glyphenbeschreibungen in Type-3-Fonts dienen. Standardwert: false.
invert Boolean (Nicht für imagetype=jpeg2000, außer bei mask=true) Invertiert das Bild (durch
Vertauschung von hellen und dunklen Farben). Dies kann bei manchen Bildern als
Behelfslösung dienen, wenn sie von Anwendungen unterschiedlich interpretiert
werden. Standardwert: false.
K Integer (Nur bei imagetype = ccitt) CCITT-Kompressionsparameter zur Auswahl des
Kompressionsverfahrens. Standardwert: 0.
-1 G4-Kompression
0 eindimensionale G3-Kompression (G3-1D)
1 gemischte ein- und zweidimensionale Kompression (G3, 2-D)
mask Boolean (Nur für Bilder mit einer Farbkomponente, einschließlich indizierter Farbe) Das
Bild soll als Maske verwendet werden (siehe Abschnitt 5.1.3, »Bildmasken und
Transparenz«, Seite 151); erforderlich bei Masken mit 1-Bit-Pixeltiefe und optional
bei Masken mit mehr als einem Bit pro Pixel. Letztere setzen allerdings PDF 1.4
voraus. Standardwert: false. Es gibt zwei Anwendungsfälle für Masken:
Maskieren eines anderen Bilds
Das zurückgegebene Image-Handle wird später beim Öffnen eines
anderen Bilds verwendet und als Option »masked« übergeben.
Platzieren eines eingefärbten transparenten Bilds
Pixelwerte von 0 im Bild werden als transparent interpretiert, und
Werte von 1 werden mit der aktuellen Füllfarbe eingefärbt.
masked Image- Image-Handle für ein Bild, das als Maske auf das aktuelle Bild angewandt wird.
Handle Der Wert ist ein Image-Handle, das von einem vorangehenden Aufruf von PDF_
load_image( ) (mit der Option »mask«, wenn es sich um eine 1-Bit-Maske handelt
und PDF 1.3 generiert wird) zurückgegeben und noch nicht geschlossen wurde. Im
Kompatibilitätsmodus für PDF 1.3 muss das Image-Handle ein 1-Bit-Bild referen-
zieren, da Transparenzmasken erst ab PDF 1.4 unterstützt werden.

OPI-1.3 Optionsliste Optionsliste mit OPI 1.3-PostScript-Kommentaren als Optionsnamen; folgende
Einträge sind erforderlich:
ALDImageFilename (String), ALDImageDimensions (Integer-Liste),
ALDImageCropRect (Rechteck aus Integers), ALDImagePosition (Float-Liste)
Folgende Einträge sind optional:
ALDImageID (String), ALDObjectComments (String), ALDImageCropFixed
(Rechteck), ALDImageResolution (Float-Liste), ALDImageColorType (Schlüsselwort;
Process, Spot oder Separation; Standardwert: Spot), ALDImageColorType (Liste aus
vier Farbwerten zwischen 0 und 1 und ein Farbname), ALDImageTint (Float),
ALDImageOverprint (Boolean), ALDImageType (Integer-Liste), ALDImageGrayMap
(Integer-Liste), ALDImageTransparency (Boolean), ALDImageAsciiTag (Liste aus
Integer/String-Paaren)
Die Suboption normalizefilename steuert die Verarbeitung von Dateinamen. Falls
sie den Wert true hat, werden Dateinamen so normalisiert, wie es in der PDF-
Referenz vorgeschrieben ist. Beim Wert false werden sie unverändert in die Aus-
gabe übernommen. Letzteres kann bei der Arbeit mit bestimmten OPI-Servern
nützlich sein, die nicht korrekt mit normalisierten Dateinamen umgehen können.
Standardwert: false
OPI-2.0 Optionsliste Optionsliste mit OPI 2.0-PostScript-Kommentaren als Optionsnamen; der
folgende Eintrag ist erforderlich:
ImageFilename (String)
Folgende Einträge sollten gemeinsam vorhanden oder nicht vorhanden sein:
ImageCropRect (Rechteck), ImageDimensions (Float-Liste)
Die folgenden Einträge sind optional:
MainImage (String), TIFFASCIITag (Liste aus Integer/String-Paaren),
ImageOverprint (Boolean), ImageInks (der String full_color, der String registration
oder eine Liste mit dem String monochrome und String/Float-Paaren für jeden
Farbnamen und Farbauftrag), IncludedImageDimensions (Integer-Liste),
IncludedImageQuality (Integer mit einem der Werte 1, 2 oder 3)
Die Suboption normalizefilename wird auch unterstützt (siehe OPI-1.3).
page Integer (Nur bei imagetype = gif oder tiff; muss bei anderen Formaten 1 sein) Das Bild mit
der angegebenen Nummer wird aus einer mehrseitigen Bilddatei extrahiert. Das
erste Bild hat die Nummer 1. Standardwert: 1.
passthrough Boolean (Nur für imagetype=tiff) Steuert die Verarbeitung von Bilddaten (Standardwert:
true):
tiff Bei true werden komprimierte TIFF-Bilddaten möglichst direkt an die
PDF-Ausgabe weitergereicht. Enthält ein TIFF-Bild beschädigte oder
unvollständige Bilddaten, kann es sinnvoll sein, diese Option auf false
zu setzen.
rendering- Schlüsselwort Rendering-Intent für das Bild. In Tabelle 3.7 finden Sie eine Liste möglicher
intent Schlüsselwörter und deren Bedeutung. Standardwert: Wert des globalen
Parameters renderingintent.
template Boolean Ist template gleich true, wird kein normales XObject vom Typ Image, sondern ein
PDF Image XObject generiert, das in ein form XObject (in PDFlib: Template)
eingebettet ist. Dies kann zur Erstellung von Templates für Formularfeldsymbole
nützlich sein, die nur aus einem Bild bestehen. Außerdem ist es zur Kompatibilität
mit bestimmten OPI-Servern bei den Optionen OPI-1.3 und OPI-2.0 erforderlich.
Standardwert: false. Geltungsbereich: document.
width Integer (Nur bei imagetype = raw oder ccitt und dann erforderlich) Breite des Bilds in
Pixeln.

C++ Java void close_image(int image)
Perl PHP PDF_close_image(resource p, int image)
C void PDF_close_image(PDF *p, int image)
Schließt ein Bild.
image Gültiges Image-Handle, das mit PDF_load_image( ) erzeugt wurde.
Details Diese Funktion wirkt sich nur auf die in PDFlib verwaltete interne Bildstruktur aus.
Wurde das Bild aus einer Datei geöffnet, bleibt die eigentliche Bilddatei von dieser
Funktion unberührt, da sie bereits am Ende von PDF_load_image( ) geschlossen wurde.
Ein mit dieser Funktion geschlossenes Image-Handle kann nicht weiter verwendet wer-
den, da damit die interne Verknüpfung des Bilds zu PDFlib gelöst wurde.
Gültigkeit document, page, font; diese Funktion darf nur paarweise mit einem entsprechenden
Aufruf von PDF_load_image( ) auftreten, sofern nicht die Option inline verwendet wurde.
C++ Java void fit_image(int image, double x, double y, String optlist)

Perl PHP PDF_fit_image(resource p, int image, float x, float y, string optlist)
C void PDF_fit_image(PDF *p, int image, double x, double y, const char *optlist)
Platziert ein Bild oder Template unter Berücksichtigung verschiedener Optionen an Po-
sition (x, y).
image Gültiges Image- oder Template-Handle, das mit PDF_load_image( ) oder PDF_
begin_template( ) erzeugt wurde.
x, y Koordinaten des Referenzpunkts im Benutzerkoordinatensystem, an dem sich

das Bild oder Template befinden soll. Die Platzierung wird über verschiedene Optionen
gesteuert.
optlist Optionsliste zur genaueren Steuerung der Platzierung gemäß Tabelle 8.41.
Details Das Bild oder Template (die im Folgenden unterschiedslos »Objekt« genannt werden)
wird relativ zum Referenzpunkt (x, y) platziert. Standardmäßig wird die linke untere
Ecke des Objekts am Referenzpunkt platziert. Dieses Verhalten kann durch die Optio-
nen orientate, boxsize, position und fitmethod geändert werden. Standardmäßig wird ein
Bild gemäß seiner Auflösung skaliert. Dieses Verhalten lässt sich durch die Optionen
dpi, scale und fitmethod modifizieren.
Gültigkeit page, pattern, template, glyph (letzteres nur, wenn die Option colorized des Type-3-Fonts
gleich true oder das Bild eine Maske ist); diese Funktion kann auf beliebigen Seiten
beliebig oft aufgerufen werden, sofern das Image-Handle noch nicht mit PDF_close_
image( ) geschlossen wurde.
8.6.2 Templates
Hinweis Die in diesem Abschnitt beschriebenen Template-Funktionen haben keinen Bezug zur PDFlib-
Blockverarbeitung von variablen Daten. Zum Füllen von mit dem PDFlib-Block-Plugin erstellten
Blöcken verwenden Sie PDF_fill_textblock( ), PDF_fill_imageblock( ) und PDF_fill_pdfblock( )
(siehe Abschnitt 8.8, »Blockfunktionen (PPS)«, Seite 313).

Tabelle 8.41 Optionen für PDF_fit_image( ) und PDF_fit_pdi_page( )
adjustpage Boolean (Wird bei blind=true ignoriert) Passt die Größe der aktuellen Seite an das Objekt
an, so dass die rechte obere Ecke der Seite auf die rechte obere Ecke des Objekts
plus (x,y) zu liegen kommt. Bei einem position-Wert von 0 sind die folgenden
nützlichen Fälle zu erwähnen:
x >= 0 und y >= 0
Das Objekt wird von einem Rand umgeben. Dieser Rand hat die Dicke
y in horizontaler Richtung und die Dicke x in vertikaler Richtung.
x < 0 und y < 0
Vom Bild werden horizontale und vertikale Streifen abgeschnitten.
Diese Option ist nur im Geltungsbereich page wirksam; sie darf nicht verwendet
werden, wenn der Parameter topdown auf true gesetzt ist. Standardwert: false.
blind Boolean Ist blind gleich true, werden zwar alle Positionierungs- und Skalierungsberech-
nungen durchgeführt, das Objekt wird aber nicht auf der Ausgabeseite platziert.
Dies ist bei der Blockverarbeitung sinnvoll, wenn der eigentliche Seiteninhalt nicht
verwendet werden soll. Standardwert: false.
boxsize Float-Liste Zwei Werte, die die Breite und Höhe einer Box festlegen, relativ zu der das Objekt
platziert und gegebenfalls skaliert wird. Die linke untere Ecke der Box kommt
dabei auf den Referenzpunkt (x, y) zu liegen. Das Platzieren des Bilds und
Einpassen in die Box werden von den Optionen position und fitmethod gesteuert.
Ist width = 0, wird nur die Breite berücksichtigt. Ist height = 0, wird nur die Höhe
berücksichtigt. Das Objekt wird dann relativ zur senkrechten Strecke von y nach
y+height bzw. zur waagrechten Strecke von x nach x+width platziert.
Standardwert: {0 0}.
dpi Integer-Liste Einer oder zwei Werte, die die gewünschte Bildauflösung in Pixeln pro Zoll in hori-
zontaler und vertikaler Richtung angeben. Wird nur ein einzelner Wert
übergeben, wird er für beide Richtungen verwendet. Beim Wert 0 wird die interne
Auflösung des Bilds verwendet, sofern vorhanden, und sonst 72 dpi. Alternativ
dazu kann das Schlüsselwort internal übergeben werden. Die durch diese Option
gegebene Auflösung bezieht sich auf das aktuelle Benutzerkoordinatensystem;
wurde dieses skaliert, weicht die tatsächliche physikalische Auflösung von den
hier übergebenen Werten ab.
Diese Option wird bei Templates und PDF-Seiten ignoriert sowie dann, wenn die
Option fitmethod mit einem der Schlüsselwörter meet, slice oder entire
übergeben wird. Standardwert: internal.

fitmethod Schlüsselwort Legt fest, auf welche Art das Objekt in die spezifizierte Box eingepasst wird. Diese
Option wird ignoriert, falls keine Box definiert wurde. Standardwert: nofit.
nofit Platziert das Objekt lediglich, ohne irgendeine Art der Skalierung oder
Beschneidung durchzuführen.
clip Platziert das Objekt und beschneidet es an den Rändern der Box.
meet Platziert das Objekt gemäß der Option position und skaliert es unter
Beibehaltung seiner Proportionen so, dass es vollständig in der Box
enthalten ist. Dabei kommen immer mindestens zwei Ränder des
Objekts genau auf den Rändern der Box zu liegen. Die Optionen dpi
und scale werden ignoriert.
auto Wie meet.
slice Platziert das Objekt gemäß der Option position und skaliert es unter
Beibehaltung seiner Proportionen so, dass es die Box vollständig
ausfüllt. Dabei passt das Objekt in mindestens einer Dimension genau
in die Box. In der anderen Dimension reicht es in der Regel über die Box
hinaus und wird deshalb entsprechend beschnitten. Die Optionen dpi
und scale werden ignoriert.
entire Platziert das Objekt entsprechend der Option position und skaliert es
genau auf die Boxgröße. Dieses Verfahren verändert in der Regel die
Proportionen des Objekts. Die Optionen dpi und scale werden
ignoriert.
ignore- Boolean (Nur für TIFF-Bilder) Ignoriert ein eventuell im Bild vorhandenes Orientation-Tag
orientation zur Angabe der Seitenausrichtung. Dies kann zur Korrektur falscher Orientierungs-
angaben dienen. Standardwert: Wert der gleichnamigen Option bei PDF_load_
image( )
orientate Schlüsselwort Legt die gewünschte Ausrichtung des Objekts bei der Platzierung fest. Standard-
wert: north.
north nach oben
east nach rechts
south nach unten
west nach links
position Float- oder Einer oder zwei Werte, die die Position des Referenzpunkts (x, y) innerhalb des
Schlüsselwort- Objekts festlegen. {0 0} bezeichnet dabei die linke untere Ecke des Objekts und
Liste {100 100} die rechte obere Ecke. Wurde die Option boxsize übergeben, bestimmt
die Option position auch die Platzierung der Box. Die Werte werden in Prozent der
Breite und Höhe des Objekts angegeben. Sind die beiden Prozentwerte gleich, so
kann ein Wert weggelassen werden. Beispiele:
0 oder {0 0} linke untere Ecke
{50 100} Mitte des oberen Rands
50 oder {50 50} Mittelpunkt des Objekts
Statt der Werte 0, 50 und 100 können dementsprechend die Schlüsselwörter left,
center, und right (in x-Richtung) oder bottom, center und top (in y-Richtung)
verwendet werden. Wird nur ein einziges Schlüsselwort angegeben, wird für die
andere Richtung das entsprechende Schlüsselwort verwendet.
Standardwert: 0 (linke untere Ecke).
übergebene Wert als Drehwinkel in Grad benutzt wird. Dabei werden die Box und
das Objekt gedreht. Die Drehung wird zurückgenommen, sobald das Objekt
platziert wurde. Standardwert: 0.

scale Float-Liste Skaliert das Objekt in horizontaler und vertikaler Richtung mit den übergebenen
Skalierungsfaktoren (keine Prozentwerte). Sind beide Faktoren gleich, braucht nur
ein einziger Wert übergeben zu werden. Diese Option wird ignoriert, falls die
Option fitmethod mit einem der Schlüsselwörter meet, slice oder entire
angegeben wurde. Standardwert: 1.
C++ Java int begin_template(double width, double height)

Perl PHP int PDF_begin_template(resource p, float width, float height)
C int PDF_begin_template(PDF *p, double width, double height)
Beginnt eine Template-Definition.
width, height Die Größe der Boundingbox des Templates in Punkt.
Rückgabe Template-Handle, das in nachfolgenden Bildfunktionen, inbesondere PDF_fit_image( ),

verwendet werden kann. Es wird kein Fehlercode zurückgegeben.
werte zurück. Hypertext-Funktionen und Funktionen zum Öffnen von Rasterbildern
dürfen innerhalb einer Template-Definition nicht verwendet werden. Alle Text-, Grafik-
und Farbfunktionen sind hingegen einsetzbar.
Gültigkeit document, page; mit dieser Funktion beginnt der Geltungsbereich template; diese
Funktion muss immer paarweise mit PDF_end_template( ) auftreten.
C++ Java void end_template( )

Perl PHP PDF_end_template(resource p)
C void PDF_end_template(PDF *p)
Beendet eine Template-Definition.
Gültigkeit template; mit dieser Funktion endet der Geltungsbereich template; diese Funktion muss
immer paarweise mit PDF_begin_template( ) auftreten.
8.6.3 Piktogramme (Thumbnails)
C++ Java void add_thumbnail(int image)

Perl PHP PDF_add_thumbnail(resource p, int image)
C void PDF_add_thumbnail(PDF *p, int image)
Fügt ein vorhandenes Rasterbild als Piktogramm (Thumbnail) für die aktuelle Seite ein.
image Gültiges Image-Handle, das von PDF_load_image( ) zurückgegeben wurde.
Details Diese Funktion fügt das übergebene Bild als Piktogramm für die aktuelle Seite ein. Da-
mit ein Bild als Piktogramm verwendet werden kann, muss es folgenden Bedingungen
genügen:
> Das Bild darf maximal 106 x 106 Pixel groß sein.
> Das Bild muss in Graustufen-, RGB- oder indizierten RGB-Farben vorliegen.

> Multi-strip TIFF-Bilder können nicht als Piktogramme verwendet werden, da ein Pik-
togramm nur aus einem einzigen PDF-Bildobjekt bestehen darf (siehe Abschnitt 5.1.2,
»Unterstützte Rasterbildformate«, Seite 148).
Diese Funktion erzeugt keine Piktogramme für die Seiten, sondern bietet lediglich die
Möglichkeit, bereits vorhandene Bilder hinzuzufügen, die gegebenenfalls als Pikto-
gramme verwendet werden. Die tatsächlichen Miniaturseiten müssen vom Client er-
stellt werden. Der Client muss dabei sicherstellen, dass die Farben, das Seitenverhältnis
sowie der tatsächliche Inhalt eines Piktogramms zum entsprechenden Seiteninhalt pas-
sen.
Da Acrobat seit Version 5 Piktogramme dynamisch generiert (mit Ausnahme von
Acrobat 5 und Adobe Reader 6 im Browser) und eine generierte PDF-Datei durch Pikto-
gramme nur vergrößert wird, ist davon abzuraten, Piktogramme selbst hinzuzufügen.
Stattdessen sollte man sich auf die clientseitige Piktogrammgenerierung verlassen.
Gültigkeit page; diese Funktion darf nur einmal pro Seite aufgerufen werden. Nicht alle Seiten
brauchen zugeordnete Piktogramme.
Parameter openmode

8.7 Funktionen für den PDF-Import (PDI)
Hinweis Alle in diesem Abschnitt beschriebenen Funktionen benötigen die PDF-Importbibliothek PDI,
die nicht in PDFlib Lite und PDFlib enthalten ist, sondern PDFlib+PDI oder PDFlib Personaliza-
tion Server (PPS) voraussetzt. Bitte informieren Sie sich zum Erwerb von PDI gegebenenfalls auf
unserer Web-Seite.
8.7.1 Dokument und Seite
C++ Java int open_pdi(String filename, String optlist, int len)

Perl PHP int PDF_open_pdi(resource p, string filename, string optlist, int len)
C int PDF_open_pdi(PDF *p, const char *filename, const char *optlist, int len)
Öffnet ein (auf der Festplatte liegendes oder virtuelles) PDF-Dokument und bereitet es
zur späteren Verwendung vor.
filename (Name-String) Name der PDF-Datei.
optlist Optionsliste mit Optionen zum Öffnen des Dokuments gemäß Tabelle 8.42.
len (Wird nur in der C-Sprachbindung verwendet; muss in anderen Sprachen gleich 0
sein.) Länge von filename (in Bytes) für UTF-16-Strings. Ist len gleich 0, muss ein null-ter-
minierter String übergeben werden.
Rückgabe Dokument-Handle, das zur Verarbeitung einzelner Seiten des Dokuments oder zur Ab-
frage von Dokumenteigenschaften verwendet werden kann. Ein Rückgabewert von -1
(in PHP: 0) zeigt an, dass das PDF-Dokument nicht geöffnet werden konnte. Es kann eine
beliebige Anzahl von PDF-Dokumenten gleichzeitig geöffnet werden. Der Rückgabewert
kann bis zum Ende des umgebenden Geltungsbereichs document verwendet werden.
Details Das Dokument wird standardmäßig nicht akzeptiert, wenn eine oder mehrere der fol-
genden Bedingungen zutreffen (siehe Abschnitt 5.2.3, »Importierbare PDF-Dokumente«,
Seite 157):
> Das Dokument ist beschädigt.
> Das Dokument ist in einer höheren PDF-Version erstellt als das aktuelle Dokument.
> Das Dokument ist verschlüsselt und es wurde kein passendes Kennwort in der Opti-
on password übergeben.
> Das Dokument entspricht der aktuellen PDF/X-Kompatibilitätsstufe nicht.
> Das Dokument enthält Tagged PDF und für PDF_begin_document( ) ist die Option
tagged auf true gesetzt.
Außer bei der ersten Bedingung kann das Dokument mit der Option infomode in jedem
Fall geöffnet werden. Damit lassen sich Informationen über das PDF-Dokument abfra-
gen, zum Beispiel über Verschlüsselung, PDF/X-Status, Dokumentinfofelder etc.
Mit der Funktion PDF_get_errmsg( ) erhalten Sie in Form einer detaillierten Fehler-
meldung genauere Informationen über die Art des mit dem importierten PDF zusam-
menhängenden Problems (PDF-Dateiname falsch, Format nicht unterstützt, PDF-Daten
nicht korrekt etc.).
Gültigkeit object, document, page; im Geltungsbereich object kann ein PDI-Dokument-Handle nur
zur Abfrage von Informationen aus einem PDF-Dokument verwendet werden.

PDF/X Das importierte Dokument muss der aktuellen PDF/X-Kompatibilitätsstufe genügen,
sofern nicht die Option infomode gleich true ist.
Parameter Siehe Tabelle 8.45 und Tabelle 8.46.
Tabelle 8.42 Optionen für PDF_open_pdi( )

infomode Boolean Ist infomode gleich true, wird das Dokument so geöffnet, dass allgemeine
Informationen abfragbar sind, die Seiten sich aber nicht in das Ausgabedokument
importieren lassen. Vorwiegend folgende Dokumenttypen lassen sich mit
infomode=true öffnen. Standardwert: false.
PDF-Dokumente, die zum aktuellen PDF/X-Modus nicht kompatibel sind.
PDF-Dokumente mit einer höheren PDF-Version als das aktuelle Dokument.
Verschlüsselte PDF-Dokumente mit unbekanntem Kennwort (Ausnahme: PDF 1.6-
Dokumente, die mit der Distiller-Einstellung »Komprimierung auf Objektebene:
Maximal« erstellt wurden)
Dokumente in Tagged PDF, wenn die Option tagged in PDF_begin_document( )
gleich true ist.
inmemory Boolean Ist inmemory gleich true, lädt PDI die Datei vollständig in den Speicher und
verarbeitet sie dort. Auf manchen Systemen (insbesondere MVS) lässt sich die
Leistung damit erheblich steigern, es ist jedoch entsprechend viel Speicher
erforderlich. Ist inmemory gleich false, wird das Dokument stückweise von der
Festplatte gelesen. Standardwert: false.
password String (Maximale String-Länge: 32 Zeichen) Hauptkennwort (master password), das zum
Öffnen eines geschützten PDF-Dokuments erforderlich ist. Ist infomode gleich
true, reicht das Benutzerkennwort (das auch leer sein kann) zur Abfrage von
Dokumentinformationen aus. Wurde für ein verschlüsseltes Dokument kein
Kennwort übergeben, lässt sich mit dem Dokument-Handle nur der
Verschlüsselungszustand abfragen.
pdiwarning Boolean Legt fest, ob die Funktion im Fehlerfall eine Exception auslöst. Standardwert ist
der Wert des Parameters pdiwarning (siehe Tabelle 8.46).
C int PDF_open_pdi_callback(PDF *p, void *opaque, size_t filesize,

size_t (*readproc)(void *opaque, void *buffer, size_t size),
int (*seekproc)(void *opaque, long offset),
const char *optlist)
Öffnet ein vorhandenes PDF-Dokument aus einer benutzerdefinierten Datenquelle und

bereitet es zur späteren Verwendung vor.
opaque Zeiger auf Benutzerdaten, die dem zu öffnenden PDF-Dokument zugeordnet

sind. Er wird als erster Parameter an die Callback-Funktionen übergeben und kann be-
liebig genutzt werden. PDI verwendet diesen Zeiger selbst nicht weiter.
filesize Größe des vollständigen PDF-Dokuments in Byte.
readproc Callback-Funktion, die size Byte in den durch buffer bezeichneten Speicher
kopiert. Ist das Ende des Dokuments früher erreicht, werden entsprechend weniger
Bytes kopiert. Die Funktion muss die Anzahl der tatsächlich kopierten Bytes zurück-
geben.

seekproc Callback-Funktion, die die aktuelle Leseposition im Dokument setzt. offset
bezeichnet die Position ausgehend vom Dokumentanfang (0 bezeichnet dabei das erste
Byte). Bei Erfolg muss die Funktion 0 zurückgeben, andernfalls -1.
optlist Optionsliste mit Optionen zum Öffnen des PDF-Dokuments gemäß Tabelle
8.42.
Rückgabe Dokument-Handle, das zur Verarbeitung einzelner Dokumentseiten oder zur Abfrage
von Dokumenteigenschaften verwendet werden kann. Der Rückgabewert -1 zeigt an,
dass das PDF-Dokument nicht geöffnet werden konnte. Es können gleichzeitig beliebig
viele PDF-Dokumente geöffnet werden. Der Rückgabewert kann bis zum Ende des um-
gebenden Geltungsbereichs document verwendet werden.
Details Diese Funktion bietet eine besondere Schnittstelle für Applikationen, die beliebige
Mengen von PDF-Daten aus einer beliebigen Datenquelle beziehen, statt das PDF-Doku-
ment auf der Festplatte oder im Speicher zur Verfügung zu stellen.
Gültigkeit object, document, page; im Geltungsbereich object kann ein PDI-Dokument-Handle nur
zur Abfrage von Informationen aus einem PDF-Dokument verwendet werden.
Bindungen Nur in der C-Sprachbindung verfügbar.
C++ Java void close_pdi(int doc)

Perl PHP PDF_close_pdi(resource p, int doc)
C void PDF_close_pdi(PDF *p, int doc)
Schließt alle geöffneten PDI-Seiten-Handles sowie das PDF-Importdokument.
doc Gültiges PDF-Dokument-Handle, das mit PDF_open_pdi*( ) erzeugt wurde.
Details Diese Funktion schließt ein PDF-Importdokument und gibt alle Ressourcen frei, die sich
auf das Dokument beziehen. Alle noch geöffneten Dokumentseiten werden geschlos-
sen. Das Dokument-Handle darf nach Aufruf dieser Funktion nicht mehr benutzt wer-
den. Ein zu importierendes PDF-Dokument sollte nicht geschlossen werden, wenn noch
weitere Seiten zu importieren sind. Sie können es zwar beliebig oft öffnen und schlie-
ßen, dies kann die PDF-Ausgabedaten aber unnötig vergrößern.
Gültigkeit object, document, page
C++ Java int open_pdi_page(int doc, int pagenumber, String optlist)

Perl PHP int PDF_open_pdi_page(resource p, int doc, int pagenumber, string optlist)
C int PDF_open_pdi_page(PDF *p, int doc, int pagenumber, const char* optlist)
Bereitet eine Seite zur späteren Verwendung mit PDF_fit_pdi_page( ) vor.
doc Gültiges Dokument-Handle, das mit PDF_open_pdi*( ) erzeugt wurde.
pagenumber Nummer der zu öffnenden Seite. Die erste Seite hat die Seitennummer 1.
optlist Optionsliste mit Seitenoptionen gemäß Tabelle 8.43.

Rückgabe Seiten-Handle, das zur Platzierung von Seiten mit PDF_fit_pdi_page( ) verwendet werden
kann. Ein Rückgabewert von -1 (in PHP: 0) zeigt an, dass die Seite nicht geöffnet werden
konnte. Der Rückgabewert kann bis zum Ende des umgebenden Geltungsbereichs
document verwendet werden. Ist die Option infomode gleich true oder war sie beim Öff-
nen des Dokuments mit PDF_open_pdi( ) gleich true, kann das Handle zwar für Informa-
tionen über die Seite mit PDF_get_pdi_value( ) und PDF_get_pdi_parameter( ), aber nicht
mit PDF_fit_pdi_page( ) verwendet werden.
Details Diese Funktion kopiert alle Daten der importierten Seite in das Ausgabedokument, hat
aber keinen sichtbaren Effekt auf die Ausgabe. Um die importierte Seite tatsächlich im
generierten Dokument zu platzieren, müssen Sie PDF_fit_pdi_page( ) verwenden. Um ge-
nauere Informationen über ein Problem mit dem PDF-Import zu erhalten (Format nicht
unterstützt, PDF-Daten nicht korrekt etc.), setzen Sie den Parameter pdiwarning auf true.
War die Option infomode beim Öffnen der Seite gleich true, werden keine Daten in die
Ausgabedatei kopiert.
Die Funktion scheitert, wenn die PDF-Version des importierten Dokuments höher
als die der generierten PDF-Ausgabe ist.
Es kann eine beliebige Anzahl von Seiten gleichzeitig geöffnet sein. Wird dieselbe
Seite mehrfach geöffnet, werden dafür unterschiedliche Handles zurückgegeben, und
jedes Handle muss genau einmal geschlossen werden.
Tabelle 8.43 Optionen für PDF_open_pdi_page( )

hypertext- Schlüsselwort Legt den Zeichensatz für die Option iconname fest (siehe Abschnitt 4.5.4, »String-
iconname Hypertext- Weist der importierten Seite einen Namen zu, über den via JavaScript auf die Seite
String verwiesen werden kann. DIes ist z.B. nützlich, um die Seite einem Formularfeld als
Symbol zuzuweisen.
infomode Boolean Ist infomode gleich true, wird das Dokument so geöffnet, dass allgemeine
Informationen und Blockeigenschaften zwar abfragbar sind, die Seiten sich aber
nicht in das Ausgabedokument importieren lassen. Standardwert: Wert der
Option infomode beim zugehörigen Aufruf von PDF_open_pdi( ) (Standardwert:
false). Bei Dokumenten, die mit infomode=true geöffnet wurden, wird die hier
beschriebene Option ignoriert.
pdiusebox Schlüsselwort pdiusebox bestimmt, welche der folgenden Box-Angaben zur Ermittlung der
Größe einer importierten Seite verwendet wird. Standardwert: crop.
media MediaBox (immer vorhanden)
crop CropBox, falls vorhanden, sonst MediaBox
bleed BleedBox, falls vorhanden, sonst CropBox
trim TrimBox, falls vorhanden, sonst CropBox
art ArtBox, falls vorhanden, sonst CropBox
pdiwarning Boolean Legt fest, ob die Funktion im Fehlerfall eine Exception auslöst. Standardwert ist

C++ Java void close_pdi_page(int page)
Perl PHP PDF_close_pdi_page(resource p, int page)
C void PDF_close_pdi_page(PDF *p, int page)
Schließt das Seiten-Handle und gibt alle Ressourcen frei, die sich auf die Seite beziehen.
page Gültiges PDF-Seiten-Handle (keine Seitennummer!), das mit PDF_open_pdi_

page( ) erzeugt wurde.
Details Diese Funktion schließt die Seite, die mit dem Seiten-Handle page verknüpft ist, und
gibt alle zugehörigen Ressourcen frei. page darf nach diesem Aufruf nicht mehr verwen-
det werden.
C++ Java void fit_pdi_page(int page, double x, double y, String optlist)

Perl PHP PDF_fit_pdi_page(resource p, int page, float x, float y, string optlist)
C void PDF_fit_pdi_page(PDF *p, int page, double x, double y, const char *optlist)
Platziert eine importierte PDF-Seite unter Berücksichtigung verschiedener Optionen an

der Position (x, y).
page Gültiges PDF-Seiten-Handle (keine Seitennummer!), das mit PDF_open_pdi_

page( ) erzeugt wurde. Die Option infomode muss beim Öffnen von Dokument und Seite
auf false gesetzt gewesen sein. Das Seiten-Handle darf nicht bereits geschlossen worden
sein.
x, y Koordinaten des Referenzpunkts im Benutzerkoordinatensystem, an denen die

Seite platziert wird. Die Platzierung wird über verschiedene Optionen gesteuert.
optlist Optionsliste zur genaueren Steuerung der Platzierung gemäß Tabelle 8.41.
Details Diese Funktion entspricht im Wesentlichen PDF_fit_image( ), arbeitet aber mit impor-
tierten PDF-Seiten. Die meisten in Tabelle 8.41 aufgeführten Optionen zur Skalierung
und Platzierung werden auch für PDF-Seiten unterstützt.
PDF/X Das Dokument, aus dem die Seite importiert wird, muss eine passende PDF/X-
Kompatibilitätsstufe und dieselbe Druckausgabebedingung (siehe Tabelle 7.6) wie das
generierte Dokument verwenden.

8.7.2 Weitere Funktionen zur PDI-Verarbeitung
C++ Java int process_pdi(int doc, int page, String optlist)

Perl PHP int PDF_process_pdi(resource p, int doc, int page, string optlist)
C int PDF_process_pdi(PDF *p, int doc, int page, const char* optlist)
Verarbeitet bestimmte Elemente eines importierten PDF-Dokuments.
doc Gültiges PDF-Dokument-Handle, das mit PDF_open_pdi( ) oder PDF_open_pdi_

callback( ) erzeugt wurde.
page Verlangt optlist ein Seiten-Handle (siehe Tabelle 8.44), muss page ein gültiges mit
PDF_open_pdi_page( ) erzeugtes PDF-Seiten-Handle sein (keine Seitennummer!). Das Sei-
ten-Handle darf nicht bereits geschlossen worden sein. Erfordert optlist kein Seiten-
Handle, muss page gleich -1 sein.
optlist Optionsliste mit Verarbeitungsoptionen gemäß Tabelle 8.44.
Rückgabe Wurde die Funktion erfolgreich ausgeführt, wird der Wert 1 zurückgegeben, im Fehler-
fall der Fehlercode -1 (in PHP: 0).
Gültigkeit document
PDF/X Die Druckausgabebedingung für das generierte Dokument muss entweder in dieser
Funktion mit der Option copyoutputintent oder mit PDF_load_profile( ) gesetzt werden.
Tabelle 8.44 Optionen für PDF_process_pdi( )

action1 Schlüsselwort (Erforderlich, auch wenn gegenwärtig nur eine einzige Aktion unterstützt wird)
Legt die Art der PDF-Verarbeitung fest.
copyoutputintent
Kopiert die Druckausgabebedingung für PDF/X des importierten
Dokuments in das Ausgabedokument. Der zweite und nachfolgende
Versuche, eine Druckausgabebedingung zu kopieren, werden
ignoriert.
pdiwarning1 Boolean Legt fest, ob diese Funktion im Fehlerfall eine Exception auslöst. Standardwert ist
1. Benötigt kein Seiten-Handle.
8.7.3 Parameterbehandlung
C++ Java double get_pdi_value(String key, int doc, int page, int reserved)
Perl PHP double PDF_get_pdi_value(resource p, string key, int doc, int page, int reserved)
C double PDF_get_pdi_value(PDF *p, const char *key, int doc, int page, int reserved)
Ermittelt einen numerischen PDI-Dokumentparameter.
key Name (Schlüssel) des zu ermittelnden Parameters, siehe Tabelle 8.45 und Tabelle
8.46.

doc Gültiges PDF-Dokument-Handle, das von PDF_open_pdi( ) erzeugt wurde.
page Gültiges PDF-Seiten-Handle (keine Seitennummer!), das von PDF_open_pdi_

page( ) erzeugt wurde. Bei nicht seitenspezifischen Schlüsseln muss page gleich -1 (in
PHP: 0) sein.
reserved Derzeit nicht benutzt, muss 0 sein.
Rückgabe Numerischer Wert, der aus dem Dokument ermittelt wird.
Tabelle 8.45 Seitenspezifische Parameter und Werte beim PDF-Import

get_pdi_value width Ermittelt die Breite (width) oder Höhe (height) einer importierten Seite in
height Standardeinheiten. Beschneidung und Drehung werden berücksichtigt.
get_pdi_value /Rotate Seitendrehung in Grad (0, 90, 180 oder 270)
get_pdi_value /CropBox, Fragt einen der Box-Parameter der Seite ab. Dem Parameternamen muss
/BleedBox, ein Schrägstrich ’/’ und einer der Strings llx, lly, urx oder ury folgen, zum
/ArtBox, Beispiel: /CropBox/llx. (Einzelheiten hierzu finden Sie in Abschnitt 3.2.2,
/TrimBox, »Höchstwerte für Seiten und Koordinaten«, Seite 64.) Beachten Sie, dass
/MediaBox der Schlüssel /Rotate in diesen Werten nicht berücksichtigt ist. Im
Gegensatz dazu enthalten die Werte für width und height bereits jegliche
Drehung, die auf die Seite angewandt wurde.
get_pdi_parameter isempty Gibt den String true zurück, wenn die Seite leer ist, false, wenn die Seite
nicht leer ist und unknown im Falle eines nicht unterstützten Filters für die
Seite.
C++ Java String get_pdi_parameter(String key, int doc, int page, int reserved)
Perl PHP string PDF_get_pdi_parameter(resource p, string key, int doc, int page, int reserved)
C const char * PDF_get_pdi_parameter(PDF *p,
const char *key, int doc, int page, int reserved, int *len)
Ermittelt einen PDI-Dokumentparameter vom Typ String.
key (Name-String) Legt den Namen (Schlüssel) des zu ermittelnden Parameters fest,
siehe Tabelle 8.45 und Tabelle 8.46.
doc Gültiges PDF-Dokument-Handle, das von PDF_open_pdi( ) erzeugt wurde.
page Gültiges PDF-Seiten-Handle (keine Seitennummer!), das von PDF_open_pdi_

page( ) erzeugt wurde. Bei nicht seitenspezifischen Schlüsseln muss page gleich -1 (in
PHP: 0) sein.
reserved Derzeit nicht benutzt, muss 0 sein.
len (Nur C-Sprachbindung) C-Zeiger auf eine Variable vom Typ Integer, in die die Län-
ge des zurückgegebenen Strings in Byte eingetragen wird. Ist der Zeiger gleich NULL, so
wird er ignoriert. Dieser Parameter ist nur in C nötig und in anderen Sprachbindungen
nicht erlaubt.
Rückgabe String-Parameter, der aus dem Dokument ermittelt wurde, als Hypertextstring. Ist kei-
ne Information verfügbar, so wird ein Leerstring zurückgegeben.

Der Inhalt des Strings kann bis zum Ende des umgebenden Geltungsbereichs object
verwendet werden oder bis zum nächsten Aufruf dieser Funktion, je nachdem, was zu-
erst eintritt.
Details Diese Funktion ermittelt einen String-Parameter, der sich auf ein importiertes PDF-
Dokument bezieht und durch page und index näher spezifiziert sein kann. Tabelle 8.46
zeigt sinnvolle Parameterkombinationen.
Bindungen C und C++: Der Parameter len muss übergeben werden.

Andere: Der Parameter len muss weggelassen werden; stattdessen wird ein String-
Objekt passender Länge zurückgegeben.
Tabelle 8.46 Dokumentspezifische Parameter und Werte zum PDF-Import

get_parameter pdi1 Gibt den String true zurück, wenn die PDI-Bibliothek installiert ist
(nicht der Fall bei PDFlib Lite), andernfalls false. Geltungsbereich:
beliebig, null2.
get_pdi_value /Root/Pages/Count1 Anzahl der Seiten im importierten Dokument
1
get_pdi_parameter filename Name der PDF-Datei; wurde die Datei mit PDF_open_pdi_
callback( ) geöffnet, wird ein Behelfsname zurückgegeben.
get_pdi_parameter /Info/<Schlüssel>1 Ermittelt den String-Wert eines Schlüssels im Info-Dictionary des
Dokuments, zum Beispiel /Info/Title, als Hypertext-String. Es
können auch benutzerdefinierte Schlüssel abgefragt werden. Kann
der Schlüssel im Dokument nicht gefunden werden, so wird ein
Leerstring zurückgegeben. Ist pdiwarning auf true gesetzt, wird
dagegen eine Exception ausgelöst.
get_pdi_parameter tagged Gibt true zurück, wenn das Dokument Tagged PDF enthält (und
deswegen nicht im Tagged-PDF-Ausgabemodus importiert werden
kann).
get_pdi_parameter pdfx1 Ermittelt die PDF/X-Kompatibilitätsstufe des importierten Doku-
ments. Das Ergebnis entspricht »PDF/X-1:2001« , »PDF/X-1a:2001«,
»PDF/X-3:2002«, »none« oder einem String, der eine spätere
Kompatibilitätsstufe bezeichnet (siehe Abschnitt 7.4, »PDF/X«,
Seite 201).
get_pdi_value version1 PDF-Versionsnummer, die mit 10 multipliziert wird, zum Beispiel 15
für PDF 1.5
set_parameter pdiwarning1 Anhand dieses Parameters erhalten Sie genauere Informationen
darüber, warum ein PDF-Dokument oder eine Seite nicht geöffnet
werden konnten. Standardwert: false.
true Eine nicht-fatale Exception wird ausgelöst, wenn die
PDI-Funktion scheitert. Der mit der Exception gelieferte
Text kann bei der Behebung von importspezifischen
Problemen behilflich sein.
false Beim Scheitern einer PDI-Funktion wird keine Exception
ausgelöst. Stattdessen gibt die Funktion im Fehlerfall
-1 (in PHP: 0) zurück.
set_parameter pdiusebox1 Veraltet. Verwenden Sie stattdessen in PDF_open_pdi_page( ) die
Option pdiusebox.

Tabelle 8.46 Dokumentspezifische Parameter und Werte zum PDF-Import
set_pdi_parameter vdp/Blocks/<Block>/ Fragt standardmäßig vorhandene und benutzerdefinierte
get_pdi_value <Eigenschaft> oder Blockeigenschaften ab (siehe Abschnitt 6.5, »Abfragen von
dp/Blocks/<Block>/ Blocknamen und -eigenschaften«, Seite 189). Nur im PDFlib
Custom/ Personalization Server (PPS) verfügbar3.
<Eigenschaft>
get_pdi_value vdp/blockcount Fragt die Anzahl der Blöcke auf der Seite ab.
1. Der Parameter page muss -1 (in PHP: 0) sein.
2. Kann mit dem PDF * Argument NULL oder 0 aufgerufen werden.
3. Ist eine Eigenschaft nicht vorhanden, wird der Wert 0 zurückgegeben. Dies kann bei Eigenschaften mit einem Standardwert
ungleich 0 zu unvorhersehbaren Ergebnissen führen (siehe »Nicht vorhandene Blockeigenschaften und Standardwerte«, Seite
189).

8.8 Blockfunktionen (PPS)
Der PDFlib Personalization Server (PPS) bietet spezielle Funktionen zur Verarbeitung
von variablen Datenblöcken vom Typ Text, Image und PDF. Diese Blöcke müssen in der
importierten PDF-Seite enthalten sein, werden aber nicht in die generierte Ausgabe
übernommen. Die importierte Seite muss vor dem Einsatz jeglicher Blockfunktionen
auf der Ausgabeseite platziert worden sein. Bei der Berechnung der Blockposition auf
der Seite berücksichtigen die Blockfunktionen die Skalierungsoptionen, die beim letz-
ten Aufruf von PDF_fit_pdi_page( ) mit dem entsprechenden PDF-Seiten-Handle überge-
ben wurden.
Wenn eine reine Blockverarbeitung erwünscht ist, ohne den Seiteninhalt tatsächlich
auf der Ausgabeseite zu platzieren (das heißt die importierte Seite wird nur als Blockbe-
hälter verwendet), kann die Option blind von PDF_fit_pdi_page( ) verwendet werden. Da-
mit lassen sich Blöcke zum Beispiel unter dem Inhalt der Originalseite platzieren. Um
dies zu erreichen, verwenden Sie PDF_fit_pdi_page( ) mit der Option blind, füllen dann
die Blöcke wie gewünscht und rufen schließlich PDF_fit_pdi_page( ) erneut auf, diesmal
aber ohne die blind-Option.
Hinweis Alle in diesem Abschnitt erläuterten Blockfunktionen benötigen den PDFlib Personalization
Server (PPS). Außerdem ist das PDFlib-Block-Plugin für Adobe Acrobat erforderlich, um Blöcke in
PDF-Templates zu generieren. Weitere Informationen zum PDF-Block-Plugin finden Sie in Kapi-
tel 6.
C++ Java int fill_textblock(int page, String blockname, String text, String optlist)
Perl PHP int PDF_fill_textblock(resource p, int page, string blockname, string text, string optlist)
C int PDF_fill_textblock(PDF *p,
int page, const char *blockname, const char *text, int len, const char *optlist)
Füllt einen Block des Typs Text mit variablen Daten unter Berücksichtigung verschiede-
ner Optionen.
page Gültiges PDF-Seiten-Handle für eine Seite mit Blöcken.
blockname (Name-String) Name des Blocks.
text (Content-String) Text, der in den Block eingetragen werden soll, oder ein Leer-
string, wenn der (in den Blockeigenschaften definierte) Standardtext verwendet werden
soll.
len (Nur C-Sprachbindung) Länge von text (in Bytes) für UCS-2-Strings, die Nullzeichen
optlist Optionsliste zur genaueren Steuerung der Fülleigenschaften gemäß Tabelle

8.47.
Rückgabe -1 (in PHP: 0), falls kein Block mit dem angegebenen Namen auf der Seite existiert, der
Block nicht gefüllt werden kann (zum Beispiel wegen Fontproblemen) oder der Block
eine aktuellere PDFlib-Version zur Verarbeitung benötigt; 1, falls der Block erfolgreich
verarbeitet werden konnte. Mit der Option pdiwarning erhalten Sie weitere Informatio-
nen über die Art des Problems.

Details Der übergebene Text wird in den Block eingetragen, wobei die Eigenschaften des Blocks
berücksichtigt werden. Ist text leer, verwendet die Funktion den Standardtext des
Blocks, sofern dieser vorhanden ist, oder beendet sich ohne weiteres. Dies kann sinnvoll
sein, um Blockeigenschaften wie die Füll- oder Zeichenfarbe zu nutzen.
Stellt sich das PDF-Dokument als beschädigt heraus, löst die Funktion abhängig von
der Option bzw. dem Parameter pdiwarning entweder eine Exception aus oder gibt -1
zurück.
Gültigkeit page, template
Hinweis Diese Funktion ist nur im PDFlib Personalization Server (PPS) verfügbar.
C++ Java int fill_imageblock(int page, String blockname, int image, String optlist)
Perl PHP int PDF_fill_imageblock(resource p, int page, string blockname, int image, string optlist)
C int PDF_fill_imageblock(PDF *p,
int page, const char *blockname, int image, const char *optlist)
Füllt einen Block des Typs Image mit variablen Daten unter Berücksichtigung verschie-
dener Optionen.
image Gültiges Image-Handle für das Bild, das in den Block gefüllt werden soll, oder -1
zur Verwendung des in den Blockeigenschaften verwendeten Standardbilds.
optlist Optionsliste mit Fülleigenschaften gemäß Tabelle 8.47.
Rückgabe -1 (in PHP: 0), falls kein Block mit dem angegebenen Namen auf der Seite existiert oder
der Block eine aktuellere PDFlib-Version zur Verarbeitung benötigt; 1, falls der Block er-
folgreich verarbeitet werden konnte.
Details Das Bild, auf das mit dem übergebenen Image-Handle verwiesen wird, wird im Block
platziert, wobei die Eigenschaften des Blocks berücksichtigt werden. Ist image gleich -1
(in PHP: 0), verwendet die Funktion das Standardbild des Blocks, sofern dieses vorhan-
den ist, oder beendet sich ohne weiteres.
der Option bzw. dem Parameter pdiwarning entweder eine Exception aus oder gibt -1 zu-
rück.

C++ Java int fill_pdfblock(int page, String blockname, int contents, String optlist)
Perl PHP int PDF_fill_pdfblock(resource p,
int page, string blockname, int contents, string optlist)
C int PDF_fill_pdfblock(PDF *p,
int page, const char *blockname, int contents, const char *optlist)
Füllt einen Block des Typs PDF mit variablen Daten unter Berücksichtigung verschiede-
ner Optionen.
contents Gültiges PDF-Seiten-Handle für die PDF-Seite, die in den Block eingetragen
werden soll, oder -1, falls die in den Blockeigenschaften definierte Standard-PDF-Seite
verwendet werden soll.
optlist Optionsliste mit Fülleigenschaften gemäß Tabelle 8.47.
Rückgabe -1 (in PHP: 0), falls kein Block mit dem angegebenen Namen auf der Seite existiert, oder
der Block eine aktuellere PDFlib-Version zur Verarbeitung benötigt; 1, falls der Block er-
folgreich verarbeitet werden konnte.
Details Die PDF-Seite, auf das mit dem übergebenen Seiten-Handle contents verwiesen wird,
wird im Block platziert, wobei die Eigenschaften des Blocks berücksichtigt werden.
Ist contents gleich -1 (in PHP: 0), verwendet die Funktion die Standard-PDF-Seite des
Blocks, sofern diese vorhanden ist, oder beendet sich ohne weiteres.
der Option bzw. dem Parameter pdiwarning entweder eine Exception aus oder gibt -1 zu-
rück.
Tabelle 8.47 Optionen für die Funktionen PDF_fill_*block( )

boxsize Float-Liste Ändert die Höhe und Breite des Blocks auf die festgelegten Werte (in Koordinaten
des aktuellen Benutzerkoordinatensystems). Standardwerte: Werte in der
Blockeigenschaft Rect.
charref Boolean (Nur für PDF_fill_textblock( )) Siehe Tabelle 8.20.
encoding String Zeichensatz der Schrift, wie von PDF_load_font( ) benötigt. Diese Option ist für
PDF_fill_textblock( ) erforderlich, sofern nicht eine der folgenden Bedingungen
erfüllt ist:
Der String im Parameter text ist leer und die Eigenschaft defaulttext wird
verwendet.
Die Option font wurde übergeben.
glyphwarning Boolean (Nur für PDF_fill_textblock( )) Siehe Tabelle 8.19.
font Font-Handle (Nur für PDF_fill_textblock( )) Font-Handle, das von PDF_load_font( ) zurückge-
geben wurde. Kein Standardwert; entweder font oder fontname müssen
übergeben werden.
fontwarning Boolean (Nur für PDF_fill_textblock( )) Gibt an, ob diese Funktion bei Fontproblemen eine
Exception auslöst. Standardwert: Wert der Option pdiwarning.
ignore- Boolean (Nur für PDF_fill_imageblock( )) Bei true werden die Angaben zur
orientation Seitenausrichtung in TIFF-Bildern ignoriert. Standardwert: false.

Tabelle 8.47 Optionen für die Funktionen PDF_fill_*block( )
imagewarning Boolean (Nur für PDF_fill_imageblock( )) Gibt an, ob diese Funktion bei Problemen mit
Bilddaten eine Exception auslöst. Standardwert: Wert der Option pdiwarning.
pdiwarning Boolean Legt fest, ob die Funktion eine Exception auslöst, wenn auf der PDF-Seite, die den
Block oder die als Blockinhalt zu verwendende Seite enthält, ein Fehler auftritt.
Standardwert ist der Wert des Parameters pdiwarning (siehe Tabelle 8.46).
refpoint Float-Liste Bewegt die linke untere Ecke des Blocks an die in Benutzerkoordinaten festgelegte
Stelle. Standardwerte: Werte in der Blockeigenschaft Rect.
shrinklimit Float oder (Nur für PDF_fill_textblock( )) Siehe Tabelle 8.19.
Prozentwert
textformat String (Nur für PDF_fill_textblock( ), sofern nicht die defaulttext-Eigenschaft verwendet
wird) Das Format, das zur Interpretation des übergebenen Texts verwendet wird
(siehe Abschnitt 4.5.2, »Content-Strings, Hypertext-Strings und Name-Strings«,
Seite 106 und Tabelle 8.19). Standardwert: auto.
Alle Optionen von PDF_ (Nur für PDF_fill_textblock( ) und nur dann, wenn die Option font nicht
load_font( ) übergeben wird) Siehe Tabelle 8.16.
Textflow-Optionen (Nur für PDF_fill_textblock( ) mit textflow=true) Alle Optionen von PDF_create_
textflow( ) und PDF_fit_textflow( ) (siehe Tabelle 8.21 and Tabelle 8.22) mit
Ausnahme von blind, fontscale, rewind und showborder.
Fast alle Namen von Namen und Werte von Blockeigenschaften (siehe Abschnitt 6.4,
Blockeigenschaften »Standardeigenschaften zur automatischen Verarbeitung«, Seite 180), die
Vorrang von jenen in der Blockdefinition haben sollen. Einzelheiten dazu finden
Sie in Abschnitt 6.2.2, »Blockeigenschaften«, Seite 168. Die folgenden
Blockeigenschaften können nicht überschrieben werden:
Name, Description, Locked, Subtype, Type
defaulttext, defaultimage, defaultpdf, defaultpdfpage
Alternativ zur Eigenschaft fontname kann über die Option font ein Font-Handle
angegeben werden (fontname wird dann ignoriert).
In Farbeigenschaften werden die folgenden Farbraum-Schlüsselwörter
unterstützt: none, gray, rgb, cmyk, spot, spotname.

8.9 Hypertext-Funktionen
Tabelle 8.48 zeigt eine Übersicht aller für diesen Abschnitt relevanten Parameter und
Werte.
Tabelle 8.48 Parameter für Hypertext-Funktionen (siehe Abschnitt 8.2.3, »Parameterbehandlung«, Seite 236)
set_parameter hypertextencoding1 Legt den Zeichensatz fest, in dem Hypertext-Funktionen vom Client
get_parameter übergebene Strings erwarten (siehe Abschnitt 4.5.4, »String-Behandlung
in nicht Unicode-fähigen Sprachen«, Seite 108). Ein Leerstring bedeutet
unicode. Standardwert: auto. Geltungsbereich: beliebig.
set_parameter hypertextformat1 Legt fest, in welchem Format der Client Strings an Hypertext-Funktionen
get_parameter übergeben soll. Mögliche Werte sind bytes, utf8, utf16, utf16le, utf16be
und auto. Standardwert: auto. Geltungsbereich: beliebig.
set_ usercoordinates Ist usercoordinates gleich false, werden die Koordinaten für Hypertext-
parameter rechtecke im Standardkoordinatensystem erwartet (siehe Abschnitt 3.2.1,
»Koordinatensysteme«, Seite 62); andernfalls wird das aktuelle Benutzer-
koordinatensystem verwendet. Standardwert: false. Geltungsbereich:
beliebig.
1. Dieser Parameter darf in den Unicode-fähigen Sprachen Java und Tcl nicht verwendet werden.
8.9.1 Aktionen
C++ Java int create_action(String type, String optlist)

Perl PHP int PDF_create_action(resource p, string type, string optlist)
C int PDF_create_action(PDF *p, const char *type, const char *optlist)
Erzeugt eine Aktion, die auf verschiedene Objekte und Events angewandt werden kann.
type Typ der Aktion, der durch eine der folgenden Schlüsselwörter beschrieben wird:
> GoTo: Gehe zu einem Ziel im aktuellen Dokument.
> GoToR: Gehe zu einem Ziel eines anderen (entfernten) Dokuments.
> Launch: Datei öffnen bzw. Anwendung ausführen.
> URI: Uniform Resouce Identifier auflösen, d.h. Webverknüpfung öffnen.
> Hide: Notiz oder Formularfeld ein-/ausblenden.
> Named: Acrobat-Menübefehl ausführen, der durch den Namen definiert ist.
> SubmitForm: Formulardaten an einen Uniform Resource Locator, also eine Internet-
Adresse senden (beachten Sie, dass in Acrobat kein Senden mit Basic Authentication
möglich ist).
> ResetForm: Bestimmte oder alle Formularfelder des Dokuments auf ihre Standard-
werte zurücksetzen.
> ImportData: Formulardaten aus einer Datei importieren.
> JavaScript: Skript mit JavaScript-Code ausführen.
> SetOCGState: (PDF 1.5) Ebenensichtbarkeit einstellen.
optlist Optionsliste mit den Aktionseigenschaften gemäß Tabelle 8.49.
Rückgabe Aktions-Handle, mit dem Aktionen an Objekte im Dokument geknüpft werden können.
Es kann bis zum Ende des umschließenden Geltungsbereichs document verwendet wer-
den.

Details Diese Funktion erstellt eine Einzelaktion. Objekte (wie Seiten, Formularfelder, Ereignis-
se oder Lesezeichen) können mit mehreren Aktionen versehen werden, aber jede Aktion
muss zuvor mit einem eigenen Aufruf von PDF_create_action( ) generiert werden. Eine
Aktion kann an verschiedene Objekte geknüpft werden.
Gültigkeit page, document. Das zurückgegebene Handle kann bis zum nächsten Aufruf von PDF_
end_document( ) verwendet werden.
PDF/X Aktionen sind in allen PDF/X-Modi verboten.
Tabelle 8.49 Optionen für Aktionseigenschaften mit PDF_create_action( )

action- Boolean Ist actionwarning gleich true, werden bei wirkungslosen Aktionsoptionen nicht-
warning fatale Exceptions ausgelöst. Bei false werden sie kommentarlos ignoriert.
Standardwert: true.
canonical- Boolean (SubmitForm) Ist canonicaldate gleich true, werden gesendete Formularfeldwerte,
date die als Datum angesehen werden, in ein Standardformat konvertiert. Ob oder
wann ein Feld als Datum anzusehen ist, wird nicht explizit im Feld selbst definiert,
sondern im verarbeitenden JavaScript-Code. Standardwert: false.
defaultdir String (Launch) Setzt das Standardverzeichnis der auszuführenden Anwendung. Diese
Option wird nur in Acrobat unter Windows unterstützt. Standardwert: none.
destination Optionsliste (GoTo, GoToR; erforderlich, sofern nicht destname übergeben wird) Optionsliste
zur Definition des Sprungziels gemäß Tabelle 8.50.
destname Hypertext- (GoTo, GoToR; erforderlich, sofern nicht destination übergeben wird) Name eines
String Ziels, das mit PDF_add_nameddest( ) definiert wurde (für GoTo) oder Name eines
Ziels im fremden Dokument (für GoToR).
exclude Boolean (SubmitForm) Ist exclude gleich true, werden in der Option namelist die vom
Sendevorgang auszuschließenden Felder aufgeführt; es werden im Prinzip alle
Felder im Dokument gesendet, mit Ausnahme der in namelist aufgeführten und
der Felder, deren Option exportable auf false gesetzt ist. Bei false werden in der
Option namelist die zu sendenden Felder aufgeführt. Feldgruppen werden mit all
ihren Elementen gesendet. Standardwert: false.
(ResetForm) Ist exclude gleich true, werden in der Option namelist die vom
Zurücksetzen auszuschließenden Felder aufgeführt; es werden alle Felder im
Dokument zurückgesetzt mit Ausnahme der in namelist aufgeführten. Bei false
werden in der Option namelist die zurückzusetzenden Felder aufgeführt.
Feldgruppen werden mit all ihren Elementen zurückgesetzt. Standardwert: false.

export- Schlüssel- (SubmitForm) Format, in dem Formularfeldnamen und -werte gesendet werden,
method wortliste einschließlich entsprechender Optionen (Standardwert: fdf):
html in HTML-Format
fdf in FDF-Format
xfdf in XFDF-Format
pdf in PDF-Format mit dem MIME-Content-Typ application/pdf
getrequest (nur für html und pdf) Senden mit HTTP GET; andernfalls HTTP POST
updates (nur für fdf) Bezieht die Inhalt aller schrittweisen Aktualisierungen des
zugrundeliegenden PDF-Dokuments ein
exclurl (nur für fdf) Im gesendeten FDF ist der URL-String nicht enthalten.
annotfields (nur für fdf) Nimmt alle Anmerkungen und Felder auf.
onlyuser (nur für fdf und annotfields) Beim Senden werden nur Anmerkungen
berücksichtigt, deren Name mit dem Namen des aktuellen Benutzers
übereinstimmt, der vom entfernten Server, zu dem das Feld gesendet
werden soll, festgelegt wird.
coordinate (nur für html) Die Koordinaten des Mausklicks, der die Aktion
submitform auslöste, werden in den Formulardaten mitgesendet. Die
Koordinatenwerte beziehen sich auf die linke untere Ecke des
Feldrechtecks.
Beispiel für kombinierte Optionen: exportmethod {fdf updates onlyuser}
filename String (GoToR, Launch; erforderlich) Name einer externen (PDF oder anderen) Datei oder
Anwendung, die beim Auslösen der Aktion geöffnet wird.
(ImportData; erforderlich): Name der externen Datei mit den Formulardaten.
hide Boolean (Hide) Blendet Anmerkungen aus (true) oder ein (false). Standardwert: true.
hypertext- Schlüsselwort Legt den Zeichensatz für den übergebenen Text fest (siehe Abschnitt 4.5.4, »String-
ismap Boolean (URI) Ist ismap gleich true, werden die Koordinaten der Mausposition bei der
Auflösung des URL zum Ziel-URI hinzugefügt. Standardwert: false.
layerstate Optionsliste (SetOCGState; erforderlich) Liste von Paaren, wobei jedes Paar aus einem
Schlüsselwort und einem Ebenen-Handle besteht. Folgende Schlüsselwörter
werden unterstützt:
on Ebene aktivieren
off Ebene deaktivieren
toggle Zustand der Ebene umkehren. Bei dieser Option muss die Option
preserveradio auf false gesetzt werden.
menuname String (Named; erforderlich) Name des auszuführenden Menübefehls. Gängige Namen
sind zum Beispiel nextpage, prevpage, firstpage oder lastpage. Zur Ermittlung der
Namen für andere Menübefehle können Sie folgenden Code in der JavaScript-
Konsole oder im Debugger von Acrobat ausführen:
function MenuList(m, level) {
console.println(m.cName);
if (m.oChildren != null)
for (var i = 0; i < m.oChildren.length; i++)
MenuList(m.oChildren[i], level + 1);
}
var m = app.listMenuItems();
for (var i=0; i < m.length; i++)
MenuList(m[i], 0);

namelist String-Liste (Hide; erforderlich) Namen (einschließlich Gruppennamen) der Anmerkungen
oder Felder, die aus- oder eingeblendet werden sollen.
(SubmitForm) Namen (einschließlich Gruppennamen) der Formularfelder, die
abhängig von der Option exclude in den Sendevorgang einbezogen oder davon
ausgeschlossen werden sollen. Standardwert: Alle Felder außer denjenigen, deren
Option exportable auf false gesetzt ist, werden gesendet.
(ResetForm) Namen (einschließlich Gruppennamen) der Formularfelder, die
abhängig von der Option exclude zurückgesetzt oder nicht zurückgesetzt werden.
Standardwert: Alle Felder werden zurückgesetzt.
newwindow Boolean (GoToR, Launch) Legt fest, ob das Zieldokument in einem eigenen Fenster geöffnet
wird. Ist newwindow gleich false, wird das aktuelle Dokument im selben Fenster
durch das Zieldokument ersetzt. Bei Launch wird dieser Eintrag ignoriert, wenn
die Datei kein PDF-Dokument ist. Standardwert: Acrobat verhält sich so, wie es in
den Grundeinstellungen des aktuellen Benutzers festgelegt ist.
operation Schlüsselwort (Launch) Legt die Operation fest, die auf das in der Option filename festgelegte
Dokument angewandt werden soll. Diese Option wird nur von Acrobat unter
Windows unterstützt. Bezieht sich die Option filename auf eine Anwendung, wird
die Option operation ignoriert und die Anwendung gestartet. Standardwert:
open.
open Dokument öffnen
print Dokument drucken
parameters String (Launch) Parameter-String, der an die in der Option filename festgelegte
Anwendung übergeben wird. Diese Option wird nur von Acrobat unter Windows
unterstützt. Mehrere Parameter werden durch Leerzeichen getrennt, die
Parameter selbst dürfen keine Leerzeichen enthalten. Diese Option ist
wirkungslos, wenn sich die Option filename auf ein Dokument bezieht.
preserve- Boolean (SetOCGState) Ist preserveradio gleich true, bleibt die Radiobutton-Relation
radio zwischen verschiedenen Ebenen erhalten. Standardwert: true.
script Hypertext- (JavaScript; erforderlich) String mit dem auszuführenden Java-Code.
String
scriptname Hypertext- (JavaScript) Wenn vorhanden, wird das JavaScript in der Option script mit dem
String Namen in der Option scriptname als JavaScript-Code auf Dokumentebene
eingefügt. Wird in einem Dokument derselbe Scriptname mehrmals übergeben,
so wird nur das letzte Script verwendet; die anderen werden ignoriert. JavaScripts
auf Dokumentebene werden nach dem Laden des Dokuments in Acrobat
ausgeführt. Dies kann bei Skripten in Formularfeldern nützlich sein.
submit- Boolean (SubmitForm; PDF 1.4) Ist submitemptyfields gleich true, werden alle durch die
emptyfields Optionen namelist und exclude festgelegten Felder gesendet, unabhängig davon,
ob sie einen Wert besitzen oder nicht. Bei Feldern ohne Wert wird nur der
Feldname übertragen. Bei false wird ein Feld nur gesendet, wenn es einen Wert
enthält. Standardwert: false.
url String (URI; erforderlich) Uniform Resource Locator in 7-Bit-ASCII oder EBCDIC (aber nur
ASCII-Zeichen) für das Verknüpfungsziel. Er kann auf eine beliebige lokale oder
Web-Ressource verweisen und muss mit einer Protokollidentifikation beginnen
(zum Beispiel http://). Mit den Parametern textx/texty, currentx/currenty und
imagewidth/imageheight können Informationen abgefragt werden, die bei der
Berechnung von Verknüpfungsrechtecken hilfreich sind.
(SubmitForm; erforderlich) URL-Spezifikation mit dem Uniform Resource Locator
(Adresse) des Scripts auf dem Web-Server, das für den Sendevorgang zuständig ist.

8.9.2 Benannte Ziele
C++ Java void add_nameddest(String name, String optlist)

Perl PHP PDF_add_nameddest(resource p, string name, string optlist)
C void PDF_add_nameddest(PDF *p, const char *name, int len, const char *optlist)
Erzeugt im aktuellen Dokument auf einer beliebigen Seite ein benanntes Ziel.
name (Hypertext-Name) Name des Ziels für Verknüpfungen, Lesezeichen oder andere
Auslöser. Namen für benannte Ziele müssen im Dokument eindeutig sein. Wird dersel-
be Name für ein Dokument mehrmals übergeben, so wird nur die letzte Definition ver-
wendet und die übrigen werden kommentarlos ignoriert.
len (Nur C-Sprachbindung) Länge von name (in Bytes) für UCS-2-Strings. Ist len gleich
0, muss ein null-terminierter String übergeben werden.
optlist Optionsliste zur Festlegung des benannten Ziels gemäß Tabelle 8.50. Eine leere
Liste entspricht {type fitwindow page 0}.
Details Das Ziel muss in optlist genauer festgelegt werden und kann sich auf einer beliebigen
Seite im aktuellen Dokument befinden. Der übergebene name kann mit der Option
destname in PDF_create_action( ), PDF_create_annotation( ), PDF_create_bookmark( ) und
PDF_begin/end_document( ) verwendet werden. Auf diese Weise lassen sich die Definiti-
on und die Anwendung eines Ziels in zwei getrennte Schritte aufspalten.
Alternativ dazu kann die Definition und Verwendung des benannten Ziels auch kom-
biniert werden, sofern das Ziel zum Zeitpunkt seiner Anwendung bereits bekannt ist.
Dazu verwenden Sie in obigen Funktionen die Option destination. PDF_add_nameddest( )
ist in diesem Fall nicht erforderlich.
Tabelle 8.50 Optionen zur Festlegung des Ziels in PDF_add_nameddest( ) sowie für die Option destination
in PDF_create_action( ), PDF_create_annotation( ), PDF_create_bookmark( ) und PDF_begin/end_
document( ).
group String (Erforderlich, wenn die Option page definiert ist und das Dokument Seiten-
gruppen verwendet; sonst nicht zulässig.) Name der Seitengruppe, zu der die
Zielseite gehört.
hypertext- Schlüsselwort Legt den Zeichensatz für den Parameter name fest (siehe Abschnitt 4.5.4, »String-
encoding Behandlung in nicht Unicode-fähigen Sprachen«, Seite 108). Ein leerer String
entspricht unicode. Standardwert: Wert des globalen Parameters
hypertextencoding
hypertext- Schlüsselwort Legt das Format für den Parameter name fest. Mögliche Werte sind bytes, utf8,
format utf16, utf16le, utf16be und auto. Standardwert: Wert des Parameters
hypertextformat

Tabelle 8.50 Optionen zur Festlegung des Ziels in PDF_add_nameddest( ) sowie für die Option destination
in PDF_create_action( ), PDF_create_annotation( ), PDF_create_bookmark( ) und PDF_begin/end_
document( ).
type Schlüsselwort Legt den Ort des Dokumentfensters auf der Zielseite wie folgt fest (Standardwert:
fitwindow):
fixed Verwendet die durch die Optionen left, top und zoom festgelegte
Ansicht. Fehlt eine der Optionen, wird ihr aktueller Wert verwendet.
fitwindow Passt die Seite vollständig in das Fenster ein.
fitwidth Passt die Seitenbreite in das Fenster ein und platziert die Seite mit der
y-Koordinate top am oberen Fensterrand.
fitheight Passt die Seitenhöhe in das Fenster ein und platziert die Seite mit der
x-Koordinate left am linken Fensterrand.
fitrect Passt das durch left, bottom, right und top festgelegte Rechteck in das
Fenster ein.
fitvisible Passt den sichtbaren Seiteninhalt (die ArtBox) in das Fenster ein.
fitvisiblewidth
Passt den sichtbaren Seiteninhalt in das Fenster ein und platziert die
Seite mit der y-Koordinate top am oberen Fensterrand.
fitvisibleheight
Passt den sichtbaren Seiteninhalt in das Fenster ein und platziert die
Seite mit der x-Koordinate left am linken Fensterrand.
nameddest Veraltet.
name Hypertext- Veraltet.
String
page Integer Seitennummer der Zielseite (erste Seite ist 1). Die Seite muss im Zieldokument
vorhanden sein. Seite 0 bedeutet für PDF_add_nameddest( ) und PDF_create_
bookmark( ) die aktuelle Seite im Geltungsbereich page und Seite 1 im
Geltungsbereich document. Beachten Sie, dass Acrobat 6.0 die Seitennummer
ignoriert und fälschlicherweise immer auf Seite 1 springt. Dieser Fehler wurde in
Acrobat 6.0.1 behoben. Ältere Versionen verhalten sich korrekt. Standardwert: 0.
zoom Float (Nur relevant bei type = fixed) Zoomfaktor (1 bedeutet 100%), mit dem der Seiten-
inhalt angezeigt wird. Ist diese Option nicht vorhanden oder gleich 0, so wird der
Zoomfaktor beibehalten, der bei der Aktivierung der Verknüpfung aktuell war.
left Float (Nur relevant bei type = fixed, fitheight, fitrect und fitvisibleheight) x-Koordinate,
mit der die Seite am linken Fensterrand platziert wird. Standardwert: 0
right Float (Nur relevant bei type = fitrect) x-Koordinate, mit der die Seite am rechten
Fensterrand platziert wird. Standardwert: 1000
bottom Float (Nur relevant bei type = fitrect) y-Koordinate, mit der die Seite am unteren
Fensterrand platziert wird. Standardwert: 0
top Float (Nur relevant bei type = fixed, fitwidth, fitrect und fitvisiblewidth) y-Koordinate,
mit der die Seite am oberen Fensterrand platziert wird. Standardwert: 1000

8.9.3 Anmerkungen
C++ Java void create_annotation(double llx, double lly, double urx, double ury,
String type, String optlist)
Perl PHP PDF_create_annotation(resource p,
float llx, float lly, float urx, float ury, string type, string optlist)
C void PDF_create_annotation(PDF *p,
double llx, double lly, double urx, double ury, const char *type, const char *optlist)
Erzeugt eine rechteckige Anmerkung auf der aktuellen Seite.
llx, lly, urx, ury x- und y-Koordinaten der linken unteren und der rechten oberen Ecke
des Anmerkungsrechtecks in Standardkoordinaten (sofern der Parameter oder die Opti-
on usercoordinates gleich false ist) oder in Benutzerkoordinaten (wenn usercoordinates
gleich true ist). Acrobat positioniert die linke obere Ecke der Anmerkung an der linken
oberen Ecke des angegebenen Rechtecks.
Beachten Sie, dass die Koordinaten für Anmerkungen und die Parameter der Funkti-
on PDF_rect( ) unterschiedlich sind. PDF_create_annotation( ) erwartet die Parameter für
zwei Ecken, während an PDF_rect( ) die Koordinaten einer Ecke sowie die Breite und
Höhe übergeben werden.
type Typ der Anmerkung, der durch eines der folgenden Schlüsselwörter festgelegt ist:
> Circle: Kreis-Anmerkung
> FileAttachment: Dateianlage-Anmerkung. Acrobat Reader 5 kann Dateianlagen nicht
verarbeiten und zeigt stattdessen ein Fragezeichen an.
> FreeText: Freier-Text-Anmerkung
> Highlight: Hervorheben-Anmerkung
> Ink: Ink-Anmerkung
> Line: Linien-Anmerkung
> Link: Verknüpfungsanmerkung
> Polygon: (PDF 1.5) Polygon-Anmerkung (geschlossenes Vieleck)
> PolyLine: (PDF 1.5) Polygonlinie-Anmerkung; offenes Vieleck, d.h. die beiden letzten
Punkte sind nicht verbunden.
> Popup: Popup-Anmerkung
> Square: Rechteck-Anmerkung
> Squiggly: (PDF 1.4) Unterringeln-Anmerkung
> Stamp: Stempel-Anmerkung
> StrikeOut: Durchstreichen-Anmerkung
> Text: Text-Anmerkung (in Acrobat Notiz genannt)
> Underline: Unterstreichen-Anmerkung
optlist Optionsliste mit Anmerkungseigenschaften gemäß Tabelle 8.51.
Gültigkeit page
PDF/X In allen PDF/X-Modi sind Anmerkungen nur zulässig, wenn sie vollständig außerhalb
der BleedBox liegen (oder TrimBox/ArtBox, wenn keine BleedBox vorhanden ist).

Tabelle 8.51 Optionen für Anmerkungen mit PDF_create_annotation( )
action Aktionsliste Liste aus Anmerkungsaktionen für das folgende Ereignis. Standardwert: leere
Liste.
activate Aktionen, die bei Aktivierung der Anmerkung durchgeführt werden
sollen. Alle Aktionstypen sind zulässig.
alignment Schlüsselwort (Nur für type=FreeText) Ausrichtung von Text in der Anmerkung: left, center,
right. Diese Option ist in Acrobat 6 wirklungslos, dort wird immer left verwendet.
Standardwert: left.
annotcolor Farbe Farbe des Hintergrunds bei geschlossenem Anmerkungssymbol, der Titelleiste des
Popup-Fensters der Anmerkung und des Randes einer Verknüpfungsanmerkung.
Unterstützte Farbräume: none, gray, rgb. Standardwert: none.
annot- Boolean Ist annotwarning gleich true, wird bei wirkungslosen Anmerkungsoptionen eine
warning nicht-fatale Exception ausgelöst. Bei false werden sie kommentarlos ignoriert.
Standardwert: true.
borderstyle Schlüsselwort Stil des Anmerkungsrandes oder der Linie der Anmerkungstypen Polygon, Poly-
Line, Line, Square, Circle, Ink: solid, beveled, dashed, inset, underline. Beachten Sie,
dass die Stile beveled, inset und underline in Acrobat nicht zuverlässig
funktionieren. Standardwert: solid.
cloudy Float (Nur für type=Polygon) Legt die Intensität des »Wolken«-Effekts beim Zeichnen
des Polygons fest (wird in Acrobat Kommentarwolke genannt). Mögliche Werte
sind 0 (kein Effekt), 1 und 2. Wird diese Option verwendet, dann wird die Option
borderstyle ignoriert. Standardwert: 0.
contents Hypertext- (Erforderlich für type=Text, FreeText, Line, Square, Circle, Highlight, Underline,
String PolyLine, Polygon, Squiggly, Strikeout, Stamp, Ink, FileAttachment; optional für
type=Link, PopUp; bei type=FreeText muss contents ein String sein) Text, der in
der Anmerkung angezeigt werden soll oder (wenn dies nicht der Fall ist) ein den
Inhalt beschreibender Text in lesbarer Form. contents darf maximal 65535 Bytes
umfassen. Mit Carriage-Return oder Line-Feed-Zeichen kann ein neuer Absatz
begonnen werden.
createdate Boolean (PDF ab Version 1.5) Bei true wird für die Anmerkung ein Datum- und Zeiteintrag
angelegt. Standardwert: false.
custom Liste von (Nur für erfahrene Anwender) Mit dieser Option lassen sich beliebig viele private
Optionslisten Einträge ins Annotation-Dictionary einfügen. Die kann bei Spezialanwendungen
hilfreich sein, zum Beispiel für Verarbeitungsanweisungen für Digitaldrucker.
Diese Option erfordert Kenntnisse des PDF-Dateiformats und der Zielanwendung.
Bei unpassenden Werten besteht die Gefahr beschädigter PDF-Ausgabe. Jede Liste
enthält drei Optionen:
key (String) Name des Dictionary-Keys (ohne das Zeichen /). Jeder Nicht-
Standard-PDF-Key kann festgelegt werden und außerdem folgende
Standardkeys: Contents, Name (Option iconname), NM (Option
name), und Open. In diesem Fall werden die entsprechenden Optionen
ignoriert.
type (Schlüsselwort) Typ des entsprechenden Wertes: boolean, name oder
string
value (Hypertext-String bei type=string, sonst String) Wert, wie er in der
PDF-Ausgabe erscheint; PDFlib wendet automatisch die für Strings
und Namen erforderlichen Auszeichnungen an.
dasharray Float-Liste (Nur für borderstyle=dashed). Länge der Striche und Lücken bei einem
gestrichelten Rand in Standardeinheiten (siehe PDF_setdash( )). Standardwert: 3 3.
destination Optionsliste (Nur für type=Link; wird ignoriert, wenn eine activate-Aktion festgelegt wurde)
Definiert das anzuspringende Ziel.

destname Hypertext- (Nur für type=Link; wird ignoriert, wenn die Option destination festgelegt wurde)
String Name eines mit PDF_add_nameddest( ) definierten Ziels. Die Aktionen
destination und destname haben Vorrang vor dieser Option.
display Schlüsselwort Sichtbarkeit auf Bildschirm und Papier: visible, hidden, noview, noprint.
Standardwert: visible.
endingstyles Schlüssel- (Nur für type=Line, PolyLine) Liste aus zwei Schlüsselwörtern, die die Art der
wortliste Linienenden festlegen: none, square, circle, diamond, openarrow, closedarrow.
Standardwert: none none.
filename String (Nur für type=FileAttachment; erforderlich) Datei, die mit der Anmerkung
verknüpft ist. In filename sollten nur ASCII-Zeichen verwendet werden.
fillcolor Farbe (Nur für type=FreeText) Füllfarbe des Texts. Unterstützte Farbräume: gray, rgb,
cmyk. Standardwert: gray 0 (=schwarz)
font Font-Handle (Nur für type=FreeText; erforderlich) Legt die Schrift fest, die für die Anmerkung
verwendet werden soll. Es sind nur PDF-Standardschriften und folgende
Zeichensätze erlaubt: beliebige 8-Bit-Zeichensätze, UCS-2-CMaps, builtin.
fontsize Float (Nur für type=FreeText; erforderlich) Schriftgröße in Standard- oder
Benutzerkoordinaten abhängig von der Option bzw. dem Parameter
usercoordinates.
highlight Schlüsselwort (Nur für type=Link) Hervorheben-Modus der Anmerkung, wenn sie vom Benutzer
angeklickt wird: none, invert, outline, push. Standardwert: invert.
hypertextencoding.
iconname String (Nur für type=Text, Stamp, FileAttachment) Name eines Symbols, mit dem die
Anmerkung angezeigt wird:
Für type=Text (Standardwert: note): comment , key , note ,
help , newparagraph , paragraph , insert
Für type=Stamp (Standardwert: draft): approved (genehmigt), experimental,

notapproved (nicht genehmigt), asis, expired (ungültig), notforpublicrelease
(nicht zur Veröffentlichung), confidential (vertraulich), final (endgültige Version),
sold, departmental, forcomment (zum Kommentar), topsecret, draft (Entwurf),
forpublicrelease (zur Veröffentlichung).
Für type=FileAttachment (Standardwert: pushpin):
graph (Diagramm) , pushpin (Anlage) , paperclip (Büroklammer) ,
tag (Tag)
interiorcolor Farbe (Nur für type=Line, PolyLine, Square, Circle) Farbe für die Linienenden, das
Rechteck bzw. die Ellipse der Anmerkung. Unterstützte Farbräume: none, gray,
rgb. Standardwert: none.
line Liste aus 4 (Nur für type=Line; erforderlich) Liste aus vier Zahlen x1, y1, x2, y2 für die Anfangs-
Floats und Endkoordinaten der Linie in Standardkoordinaten (wenn der Parameter
usercoordinates gleich false ist) oder in Benutzerkoordinaten (bei true).
linewidth Integer Breite des Anmerkungsrandes oder der Linie für die Anmerkungstypen Line,
PolyLine, Polygon, Square, Circle, Ink in Standardeinheiten (=Punkt). Ist linewidth
gleich 0, ist kein Rand sichtbar. Standardwert: 1.
locked Boolean Ist locked gleich true, können die Anmerkungseigenschaften in Acrobat nicht
bearbeitet werden. Standardwert: false.

mimetype Hypertext- (Nur für type=FileAttachment) MIME-Typ der Datei, mit dem Acrobat bei
String Aktivierung der Anmerkung die passende Anwendung startet.
name String Name, der die Anmerkung eindeutig identifiziert. Der Name ist bei einigen
Aktionen erforderlich und muss auf der Seite eindeutig sein. Standardwert: nicht
vorhanden.
open Boolean (Nur für type=Text, Popup) Ist open gleich true, wird die Anmerkung anfangs in
geöffnetem Zustand angezeigt. Standardwert: false.
parentname String (Nur für type=PopUp) Name der in der Anmerkungshierarchie übergeordneten
Anmerkung.
polylinelist Liste aus (Nur für type=Polygon, PolyLine, Ink, Highlight, Underline, Squiggly, Strikeout;
einer oder erforderlich.) Liste aus Float-Werten, die Koordinatenpaare repräsentieren. Die
mehreren Koordinaten werden in Standardkoordinaten interpretiert (wenn die Option user-
Float-Listen coordinates gleich false ist) oder in Benutzerkoordinaten (bei true).
type=Polygon, PolyLine, Ink
Einzelne Liste mit einer Polyline aus n Segmenten (Mindestanzahl:
n=2). Eine Polyline besteht aus einer Liste aus 2 x n Floatwerten für
Koordinatenpaare. Die Punkte werden durch Geraden verbunden.
Beispiel für n=3: {{10 20 30 40 50 60 }}
sonst Liste mit n Unterlisten aus jeweils 8 Floatwerten für n Vierecke
(Mindestanzahl: n=1). Jedes Viereck umschließt eines oder mehrere
Wörter des Texts, der der Anmerkung zugrunde liegt. Die Koordinaten
eines Vierecks werden als x1 y1 x2 y2 x3 y3 x4 y4 angegeben, die die vier
Eckpunkte festlegen. Der Text wird an der Kante ausgerichtet, die die
Punkte (x1, y1) und (x2, y2) verbindet.
Beispiel für n=2: {{1 2 3 4 5 6 7 8} {10 20 30 40 50 60 70 80}}
popup String Name einer Popup-Anmerkung, anhand dessen der Text eingegeben oder
bearbeitet wird. Standardwert: nicht vorhanden.
readonly Boolean Ist readonly gleich true, wird jede Interaktion zwischen Benutzer und Anmerkung
unterbunden. Die Anmerkung lässt sich zwar anzeigen oder drucken, reagiert aber
weder auf Mausklicks noch ändert sie ihr Aussehen bei Mausbewegungen.
rotate Boolean Ist rotate gleich true, dreht sich die Anmerkung zusammen mit der Seite. Bei false
bleibt die Anmerkung unverändert. Diese Option wird für die Symbole von Text-
Anmerkungen ignoriert. Standardwert: true.
title Hypertext- Text, der in der Titelleiste des Fensters einer aktiven und geöffneten Popup-
String Anmerkung erscheint Der Titel darf maximal 255 1-Byte-Zeichen oder 126 Unicode-
Zeichen enthalten. In der Praxis sind aber nicht mehr als 32 Zeichen ratsam.
user- Boolean Ist usercoordinates gleich false, werden die Koordinaten für Anmerkungen sowie
coordinates die Schriftgröße im Standardkoordinatensystem erwartet (siehe Abschnitt 3.2.1,
»Koordinatensysteme«, Seite 62); andernfalls wird das aktuelle Benutzer-
koordinatensystem verwendet. Standardwert: Wert des globalen Parameters
usercoordinates.
zoom Boolean Ist zoom gleich true, wird die Anmerkung in gleichem Maße wie die Seite
vergrößert. Bei false bleibt die Größe der Anmerkung unverändert. Diese Option
wird bei den Symbolen für Text-Anmerkungen ignoriert. Standardwert: true.

8.9.4 Formularfelder
C++ Java void create_field(double llx, double lly, double urx, double ury,
String name, String type, String optlist)
Perl PHP PDF_create_field(resource p, float llx, float lly, float urx, float ury,
string name, string type, string optlist)
C void PDF_create_field(PDF *p, double llx, double lly, double urx, double ury,
const char *name, int len, const char *type, const char *optlist)
Erstellt unter Anwendung verschiedener Optionen ein Formularfeld auf der aktuellen
Seite.
llx, lly, urx, ury x- und y-Koordinaten der linken unteren und rechten oberen Ecke
des Feldrechtecks in Standardkoordinaten (wenn der Parameter oder die Option user-
coordinates gleich false sind) oder in Benutzerkoordinaten (bei true).
Beachten Sie, dass sich die Koordinaten für Formularfelder von den Parametern der
Funktion PDF_rect( ) unterscheiden. Während PDF_create_field( ) explizit die Parameter
für zwei Ecken erwartet, werden an PDF_rect( ) die Koordinaten einer Ecke sowie die Brei-
te und die Höhe übergeben.
name (Hypertext-String) Name des Formularfelds, dem eventuell die Namen einer
oder mehrerer Gruppen vorangestellt werden, die mit PDF_create_fieldgroup( ) erstellt
wurden. Gruppennamen müssen durch einen Punkt ».« voneinander sowie vom Feld-
namen getrennt werden. Feldnamen müssen auf der Seite eindeutig sein und dürfen
nicht mit einem Punkt ».« enden.
type Einer der folgenden Feldtypen:
> pushbutton (Schaltfläche)
> checkbox (Kontrollkästchen)
> radiobutton (Optionsfeld). name muss ein Gruppenname vorangestellt wer-

den, da Radiobuttons immer zu einer Gruppe gehören. Bei allen anderen Feldtypen
ist die Gruppenzugehörigkeit optional.
> listbox (Listenfeld)
> combobox (Kombinationsfeld)
> textfield (Textfeld)
> signature (Digitales Unterschriftsfeld)
optlist Optionsliste mit Feldeigenschaften gemäß Tabelle 8.52. String-Optionen wer-

den je nach Anmerkung in der Tabelle als Hypertext- oder Text-Strings interpretiert.
Details Die Tabulatorreihenfolge der Felder auf der Seite (d.h. die Reihenfolge, in der sie beim
Drücken der Tabulatortaste den Fokus erhalten) bestimmt sich standardmäßig durch
die Reihenfolge der Aufrufe von PDF_create_field( ). Mit der Option taborder lässt sich

Tabelle 8.52 Optionen für Feldeigenschaften in PDF_create_field( ) und PDF_create_fieldgroup( )
action Aktionsliste Liste der Feldaktionen für eines oder mehrere der folgenden Ereignisse. Das
Ereignis activate ist für alle Feldtypen zulässig, die anderen Ereignisse sind nicht
erlaubt bei type gleich pushbutton, checkbox oder radiobutton (Standardwert:
leere Liste):
activate Aktionen, die bei Aktivierung des Felds durchgeführt werden.
keystroke JavaScript-Aktionen, die durchgeführt werden, wenn der Benutzer
Text in ein Text- oder Kombinationsfeld eingibt oder die Auswahl in
einem Listenfeld mit Rollbalken ändert.
format JavaScript-Aktionen, die durchgeführt werden, bevor das Feld zur
Anzeige seines aktuellen Wertes formatiert wird. Damit lässt sich der
Feldwert vor der Formatierung ändern.
validate JavaScript-Aktionen, die bei einer Änderung des Feldwertes
durchgeführt werden. Damit kann der neue Wert auf Gültigkeit
geprüft werden.
calculate JavaScript-Aktionen, die durchgeführt werden, um den Feldwert neu
zu berechnen, wenn sich der Wert eines anderen Felds ändert.
enter Aktionen, die durchgeführt werden, wenn die Maus in den Feldbereich
hineinbewegt wird.
exit Aktionen, die durchgeführt werden, wenn die Maus aus dem
Feldbereich herausbewegt wird.
down Aktionen, die durchgeführt werden, wenn die Maustaste im
Feldbereich gedrückt wird.
up Aktionen, die durchgeführt werden, wenn die Maustaste im
Feldbereich losgelassen wird (damit wird ein Feld in der Regel
aktiviert).
focus Aktionen, die durchgeführt werden, wenn das Feld den Eingabefokus
erhält.
blur Aktionen, die durchgeführt werden, wenn das Feld den Eingabefokus
verliert.
alignment Schlüsselwort Ausrichtung des Texts im Feld: left, center, right. Standardwert: left.
background- Farbe Farbe des Feldhintergrunds bzw. Feldrands. Unterstützte Farbräume: none, gray,
color rgb, cmyk. Standardwert: none.
bordercolor
borderstyle Schlüsselwort Stil des Feldrands: solid (durchgehend), beveled (Relief), dashed (unterbrochen),
inset (eingedrückt) oder underline (unterstrichen). Default: solid
button- Schlüsselwort (Nur für type=pushbutton) Relative Position der in caption übergebenen
layout Schaltflächenbeschriftung zum in icon übergebenen Schaltflächensymbol, sofern
beide auch festgelegt wurden: below (unter), above (über), right (rechts von), left
(links von), overlaid (auf). Standardwert: right.
buttonstyle Schlüsselwort (Nur für type=radiobutton oder checkbox) Legt das Symbol für das Feld fest: check
(Häkchen), cross (Kreuz), diamond (Karo), circle (Kreis), star (Stern), square
(Quadrat). Standardwert: check.
calcorder Integer (Nur bei vorhandener JavaScript-Aktion für das Ereignis calculate) Legt die
Berechnungsreihenfolge des Feldes relativ zu anderen Feldern fest. Felder mit
niedrigen Zahlen werden vor Feldern mit hohen Zahlen berechnet. Standardwert:
10 plus der auf der aktuellen Seite größte verwendete calcorder-Wert (anfangs 10).
caption Content- (Nur für type=pushbutton; eine der Optionen caption und icon muss für
String Schaltflächen übergeben werden) Beschriftung, die angezeigt wird, wenn die
Schaltfläche keinen Eingabefokus hat. Verwenden Sie einen leeren String (d.h.
caption { }), wenn Sie keine Beschriftung und kein Symbol wünschen.
captiondown Content- (Nur für type=pushbutton) Beschriftung, die angezeigt wird, wenn die
String Schaltfläche aktiviert ist. Standardwert: nicht vorhanden.

caption- Content- (Nur für type=pushbutton) Beschriftung, die angezeigt wird, wenn die
rollover String Schaltfläche den Eingabefokus hat. Standardwert: nicht vorhanden.
charspacing1 Float (Nicht für type=radiobutton oder checkbox; wird von Acrobat 7 ignoriert)
Wortabstand für Text im Feld in Einheiten des aktuellen
Benutzerkoordinatensystems. Standardwert: 0,
comb Boolean (Nur für type=textfield; PDF 1.5) Ist comb gleich true und sind die Optionen
multiline, fileselect und password gleich false und wurde die Option maxchar mit
einem Integer-Wert übergeben, so wird das Feld in eine durch maxchar
bestimmte Anzahl von Unterfeldern gleichen Abstandes zur Aufnahme einzelner
Zeichen unterteilt. Standardwert: false.
commit- Boolean (Nur für type=listbox oder combobox; PDF 1.5) Ist commitonselect gleich true, wird
onselect die Selektion eines Listeneintrags sofort festgeschrieben. Bei false geschieht dies
erst beim Verlassen des Feldes. Standardwert: false.
currentvalue (Verschiedene) (Nicht für type=pushbutton oder signature) Anfangswert des Feldes. Typ und
Standardwert hängen vom Feldtyp ab:
checkbox, radiobutton
(String) Jeder von Off verschiedene String bedeutet, dass der Button
aktiviert ist; Acrobat 6 verhält sich fehlerhaft, wenn itemname
festgelegt ist und/oder unisonselect gleich true ist. Der String Off
bedeutet, dass der Button deaktiviert ist. Diese Option sollte für den
ersten Button gesetzt werden. Standardwert: Off.
textfield, combobox
(Content-String) Inhalt des Felds. Standardwert: leer.
listbox (Integer-Liste) Indizes der in itemtextlist selektierten Einträge.
dasharray Float-Liste (Nur für borderstyle=dashed). Länge der Striche und Lücken eines gestrichelten
Randes in Standardeinheiten (siehe PDF_setdash( )). Standardwert: 3 3.
defaultvalue (Verschiedene) (Für type=textfield oder combobox ist diese Option vom Typ Content-String) Der
Feldwert nach einer Zurücksetzen-Aktion. Typen und Standardwerte entsprechen
der Option currentvalue. Ausnahme: bei Listenfeldern ist nur ein einzelner
Integer-Wert erlaubt.
display Schlüsselwort Sichtbarkeit auf Bildschirm und Papier; visible (sichtbar), hidden (unsichtbar),
noview (unsichtbar, aber Drucken möglich), noprint (sichtbar, aber Drucken nicht
mäglich). Standardwert: visible.
editable Boolean (Nur für type=combobox) Ist editable gleich true, kann der momentan im Feld
ausgewählte Text editiert werden. Standardwert: false.
exportable Boolean Das Feld wird exportiert, wenn die Aktion SubmitForm durchgeführt wird.
Standardwert: true.
fieldwarning Boolean Ist fieldwarning gleich true, werden bei wirkungslosen Feldoptionen nicht-fatale
Exceptions ausgelöst. Bei false werden sie kommentarlos ignoriert. Standardwert:
true.
fileselect Boolean (Nur für type=textfield) Ist fileselect gleich true, wird der Text im Feld wie ein
Dateiname behandelt. Standardwert: false.
fillcolor Farbe Füllfarbe für Text. Unterstützte Farbräume: gray, rgb, cmyk. Standardwert: gray 0
(=schwarz).

fitmethod Schlüsselwort (Nur für type=pushbutton) Methode zur Platzierung eines Templates, das mit den
Optionen icon, icondown und iconrollover in der Schaltfläche übergeben wird
(Standardwert: meet):
auto wie meet, wenn das Template in die Schaltfläche hineinpasst, sonst
clip
nofit wie clip
clip Template wird nicht skaliert, sondern am Feldrand beschnitten.
meet Template wird proportional skaliert, so dass es in die Schaltfläche
hineinpasst.
slice wie meet
entire Template wird skaliert, so dass es die Schaltfläche vollständig ausfüllt.
font Font-Handle (Erforderlich, außer für type=radiobutton oder checkbox, die immer mit Zapf-
Dingbats arbeiten.) Legt die Schrift für das Feld fest. Folgende Optionen müssen
im entsprechenden Aufruf von PDF_load_font( ) gesetzt worden sein: embedding
(mit Ausnahme der Standardschriften, die nicht eingebettet werden müssen),
nosubsetting, noautocidfont. Folgende Zeichensätze sind zulässig: 8-Bit-
Zeichensätze, Unicode CMaps, builtin.
fontsize Float oder Schriftgröße in Benutzerkoordinaten. Wird das Schlüsselwort auto statt eines
Schlüsselwort Float-Wertes übergeben, ermittelt Acrobat die Schriftgröße automatisch.
Standardwert: auto.
highlight Schlüsselwort Hervorheben-Modus des Felds, wenn es angeklickt wird: none (kein), invert
(negativ), outline (Umrandung), push (Schaltfläche). Standardwert: invert.
hypertext- Schlüsselwort Legt den Zeichensatz für den Parameter name fest (siehe Abschnitt 4.5.4, »String-
hypertextencoding.
hypertext- Schlüsselwort Setzt das Format für den Parameter name. Mögliche Werte sind bytes, utf8, utf16,
format utf16le, utf16be und auto. Standardwert: Wert des Parameters hypertextformat
icon Template- (Nur für type=pushbutton; eine der Optionen caption und icon muss für
Handle2 Schaltfächen übergeben werden.) Handle für ein Template, das sichtbar ist, wenn
die Schaltfläche keinen Eingabefokus besitzt. Standardwert: nicht vorhanden.
icondown Template- (Nur für type=pushbutton) Handle für ein Template, das angezeigt wird, solange
Handle2 die Schaltfläche aktiviert ist. Standardwert: nicht vorhanden.
iconrollover Template- (Nur für type=pushbutton) Handle für ein Template, das angezeigt wird, solange
Handle2 die Schaltfläche den Eingabefokus hat. Standardwert: nicht vorhanden.
itemname Hypertext- (Nur für type=radiobutton oder checkbox; muss verwendet werden, wenn der
String Exportwert kein Latin-1-String ist.) Exportwert des Felds. Bei mehreren zu einer
Gruppe gehörenden Radiobuttons können die in itemname übergebenen Werte
identisch sein. Acrobat 6: Checkboxen innerhalb einer Gruppe, die denselben
Namen haben, werden gleichzeitig aktiviert oder deaktiviert, sogar wenn sie sich
auf verschiedenen Seiten befinden. Standardwert: Feldname.
item- Hypertext- (Nur für type=listbox oder combobox) Exportwerte der Listeneinträge. Mehrere
namelist String Einträge können denselben Exportwert besitzen. Standardwert: nicht vorhanden.
itemtextlist Liste von (Nur für type=listbox oder combobox und dann erforderlich) Textinhalte für alle
Content- Listeneinträge. Wenn die beiden Optionen itemnamelist und itemtextlist
Strings übergeben werden, so müssen sie dieselbe Anzahl von Strings enthalten.
linewidth Integer Linienbreite des Feldrands in Standardeinheiten (=Punkt). Standardwert: 1.
locked Boolean Ist locked gleich true, lassen sich die Feldeigenschaften in Acrobat nicht
bearbeiten. Standardwert: false.

maxchar Integer oder (Nur für type=textfield) Maximale Anzahl der Zeichen im Feld oder das
Schlüsselwort Schlüsselwort unlimited, wenn keine Beschränkung existiert. Standardwert:
unlimited.
multiline Boolean (Nur für type=textfield) Ist multiline gleich true, wird der Text gegebenenfalls in
mehrere Zeilen umgebrochen. Standardwert: false.
multiselect Boolean (Nur für type=listbox) Ist multiselect gleich true, können mehrere Listeneinträge
selektiert werden. Standardwert: false.
orientate Schlüsselwort Ausrichtung der Inhalte innerhalb des Feldrechtecks: north, west, south, east.
Standardwert: north
password Boolean (Nur für type=textfield) Ist password gleich true, wird der Text bei der Eingabe mit
Punkten oder Sternchen angezeigt. Standardwert: false.
position Float- oder (Nur für type=pushbutton) Relative Position eines Templates, das mit einer der
Schlüsselwort- Optionen icon... für eine Schaltfläche übergeben wurde. Standardwert: 50 50.
Liste
readonly3 Boolean Ist readonly gleich true, ist keine Eingabe in das Feld erlaubt. Standardwert: false.
required Boolean Ist required gleich true, muss das Feld beim Senden des Formulars einen Wert
enthalten. Standardwert: false.
richtext Boolean (Nur für type=textfield; PDF 1.5) Erlaubt Rich Text Formatting. Ist richtext gleich
true, muss fontsize ungleich 0 sein und fillcolor darf nicht mit dem Farbraum
cmyk definiert sein. Standardwert: false.
scrollable Boolean (Nur für type=textfield) Ist scrollable gleich true, wird zu langer Text in den
unsichtbaren Bereich außerhalb des Feldes bewegt. Bei false wird keine Eingabe
mehr akzeptiert, sobald der Text das Feld vollständig ausfüllt. Standardwert: true.
sorted Boolean (Nur für type=listbox oder combobox) Ist sorted gleich true, werden die
Listeneinträge sortiert. Standardwert: false.
spellcheck Boolean (Nur für type=textfield oder combobox) Ist spellcheck gleich true, wird die
Rechtschreibprüfung im Feld aktiviert. Standardwert: true.
strokecolor Farbe Farbe zum Zeichnen des Texts. Unterstützte Farbräume: gray, rgb, cmyk.
Standardwert: gray 0 (=schwarz).
submitname Hypertext- (Ratsam für type=pushbutton) URL-kodierter String der Internet-Adresse, an die
String das Formular gesendet wird. Standardwert: nicht vorhanden.
taborder Integer Legt die Tabulatorreihenfolge des Feldes relativ zu anderen Feldern fest. Felder
mit niedrigen Zahlen werden vor Feldern mit höheren Zahlen betreten.
Standardwert: 10 plus dem maximalen auf der Seite verwendeten taborder-Wert
(und 10 für das erste Feld auf der Seite); im Standardfall richtet sich die
Tabulatorreihenfolge also nach der Erstellungsreihenfolge.
tooltip3 Hypertext- Text, der im Tooltip des Feldes erscheint. Bei Radiobuttons verwendet Acrobat
String immer den tooltip-Wert des ersten Buttons der Gruppe, die anderen werden
ignoriert. Standardwert: nicht vorhanden.
topindex Integer (Nur für type=listbox) Index des ersten sichtbaren Eintrags. Das erste Element hat
den Index 0. Standardwert: 0.
user- Boolean Ist usercoordinates gleich false, werden Feldkoordinaten im Standardkoordi-
coordinates natensystem erwartet (siehe Abschnitt 3.2.1, »Koordinatensysteme«, Seite 62);
andernfalls wird das aktuelle Benutzerkoordinatensystem verwendet.
Standardwert: Wert des globalen Parameters usercoordinates.
1. Diese Option wird von Acrobat 7 ignoriert.
2. Templates für Symbole lassen sich mit der Funktion PDF_begin_template( ) erstellen; besteht das Symbol nur aus einem Bild, kön-
nen Sie das Template durch Übergabe der Option an PDF_load_image( ) erzeugen.
3. Für type=radiobutton sollte diese Option nicht mit PDF_create_field( ), sondern nur mit PDF_create_fieldgroup( ) verwendet wer-
den. Bei fieldwarning=true wird eine Warnung ausgegeben, wenn die Option mit PDF_create_field( ) benutzt wird.

eine andere Reihenfolge festlegen. Die Tabulatorreihenfolge ist nach dem Anlegen der
Felder jedoch nicht mehr änderbar.
In Acrobat können Textfelder mit einem Format versehen werden (Zahl, Prozentwert
etc.). Dies ist in der PDF-Referenz nicht spezifiziert, sondern wird mit benutzerdefinier-
ten JavaScripts implementiert. Sie können diese Funktionalität nutzen, indem Sie ei-
nem Feld JavaScript-Aktionen zuordnen, die auf die vordefinierten (aber nicht standar-
disierten) JavaScript-Funktionen von Acrobat verweisen. Weitere Informationen
einschließlich eines Beispiels finden Sie in Abschnitt 3.4.2, »Formatierungsoptionen für
Textfelder«, Seite 80.
Gültigkeit page
PDF/X Formularfelder sind in allen PDF/X-Modi nur erlaubt, wenn sie vollständig außerhalb
der BleedBox liegen (oder der TrimBox/ArtBox, wenn keine BleedBox vorhanden ist).
C++ Java void create_fieldgroup(String name, String optlist)

Perl PHP PDF_create_fieldgroup(resource p, string name, string optlist)
C void PDF_create_fieldgroup(PDF *p, const char *name, int len, const char *optlist)
Erstellt eine Formularfeldgruppe unter Anwendung verschiedener Optionen.
name (Hypertext-String) Name der Formularfeldgruppe; diesem kann der Name einer
anderen Gruppe vorangestellt sein. Feldgruppen lassen sich beliebig verschachteln.
Gruppennamen müssen durch einen Punkt ».« getrennt werden. Sie müssen innerhalb
des Dokuments eindeutig sein und dürfen nicht mit einem Punkt ».« enden.
optlist Optionsliste mit Feldeigenschaften gemäß Tabelle 8.52 und Tabelle 8.53.
Details Feldgruppen sind nützlich, um den Inhalt eines Feldes in einem oder mehreren anderen
Feldern wiederzugeben. Wird ein Feldgruppenname als Präfix für einen mit PDF_create_
field( ) erzeugten Namen übergeben, gehört das neue Feld zu dieser Gruppe. Die für eine
Gruppe in optlist übergebenen Feldeigenschaften werden von allen zur Gruppe gehö-
renden Feldern geerbt.
Gültigkeit page, document
8.9.5 Lesezeichen
C++ Java int create_bookmark(String text, String optlist)

Perl PHP int PDF_create_bookmark(resource p, string text, string optlist)
C int PDF_create_bookmark(PDF *p, const char *text, int len, const char *optlist)
Erstellt ein Lesezeichen unter Anwendung verschiedener Optionen.
text (Hypertext-String) Enthält den Lesezeichentext. Die maximale Länge von text be-
trägt 255 Ein-Byte-Zeichen (8-Bit-Zeichensätze) oder 126 Unicode-Zeichen. Aus prakti-
schen Gründen sollten jedoch nicht mehr als 32 Zeichen verwendet werden.

Tabelle 8.53 Weitere Optionen für Feldeigenschaften mit PDF_create_fieldgroup( )
fieldtype keyword Typ des in der Gruppe enthaltenen Feldes: mixed, pushbutton, checkbox, radio-
button, listbox, combobox, textfield oder signature. Außer bei fieldtype=mixed
darf die Gruppe nur Felder des festgelegten Typs enthalten. Wurde ein spezieller
Feldtyp für die Gruppe gewählt, wird der aktuelle Wert gleichzeitig in allen
zugehörenden Feldern angezeigt, auch wenn sie sich auf verschiedenen Seiten
befinden. Ist fieldtype gleich radiobutton, muss die Option unisonselect
übergeben werden. Die Optionen itemtextlist, itemnamelist, currentvalue und
defaultvalue müssen in den Optionen der Feldgruppe und nicht der einzelnen
Felder festgelegt werden. Standardwert: mixed.
toggle Boolean (Nur für type=radiobutton) Bei true lässt sich ein Radiobutton innerhalb einer
Gruppe durch Anklicken aktivieren oder deaktivieren. Bei false kann er durch
Anklicken nur aktiviert werden, eine Deaktivierung erfolgt durch Anklicken eines
anderen Buttons. Standardwert: false.
unisonselect Boolean (Nur für type=radiobutton; PDF 1.5) Bei true werden Radiobuttons mit demselben
Feld- oder Elementnamen gleichzeitig selektiert. Standardwert: false.
optlist Optionsliste mit Lesezeicheneigenschaften gemäß Tabelle 8.54.
Rückgabe Handle für das erstellte Lesezeichen, das in nachfolgenden Aufrufen in der Option
parent verwendet werden kann.
Details Diese Funktion fügt ein PDF-Lesezeichen mit dem übergebenen text hinzu. Wird die Op-
tion destination nicht übergeben, zeigt das Lesezeichen auf die aktuelle Seite (bzw. auf
die letzte Seite, wenn es im Geltungsbereich document, oder auf die erste Seite, wenn es
vor der ersten Seite verwendet wird).
Beim Erstellen von Lesezeichen wird die Option openmode für PDF_begin/end_
document( ) auf den Standardwert bookmarks gesetzt.
Tabelle 8.54 Optionen für PDF_create_bookmark( )

action Aktionsliste Liste der Lesezeichenaktionen für das folgende Ereignis (Standardwert: GoTo-
Aktion mit dem Ziel, das mit der Option destination festgelegt wird):
activate Aktionen, die bei Aktivierung des Lesezeichens durchgeführt werden
sollen. Es sind alle Arten von Aktionen zulässig.
destination Optionsliste (Wird ignoriert, wenn eine activate-Aktion festgelegt wurde) Optionliste zur
Festlegung des Lesezeichenziels gemäß Tabelle 8.50. Standardwert: {type
fitwindow page 0}, sofern nicht destination, destname oder action vorhanden
sind.
destname Hypertext- (Kann leer sein; wird ignoriert, wenn die Option destination festgelegt wurde)
String Name eines mit PDF_add_nameddest( ) definierten Ziels. Die Aktionen
destination und destname haben Vorrang vor dieser Option.
Wenn destname ein leerer String (d.h. {}) ist und weder destination noch action
festgelegt sind, ist dem Lesezeichen keine Aktion zugeordnet. Dies kann sinnvoll
sein, wenn das Lesezeichen lediglich als Separator dient.
fontstyle Schlüsselwort Legt den Schriftstil des Lesezeichentexts fest: normal, bold, italic, bolditalic.
Standardwert: normal.

Tabelle 8.54 Optionen für PDF_create_bookmark( )
hypertextencoding.
hypertext- Schlüsselwort Setzt das Format für den übergebenen Text fest. Mögliche Werte sind bytes, utf8,
format utf16, utf16le, utf16be und auto. Standardwert: Wert des globalen Parameters
hypertextformat.
index Integer Index, an dem das Lesezeichen unterhalb des parent-Lesezeichens eingefügt wird.
Anhand von Werten zwischen 0 und der Anzahl der Lesezeichen auf gleicher
Ebene wird das Lesezeichen an der gewünschten Position unterhalb des parent-
Lesezeichens angefügt. Mit -1 lässt sich das Lesezeichen auf der aktuellen Ebene an
letzter Stelle eintragen. Standardwert: -1. Bei später eingefügten oder wieder
aufgenommenen Seiten werden die Lesezeichen so platziert, als wären alle Seiten
in der vorliegenden Reihenfolge erstellt worden (die Lesezeichen geben die
Seitenreihenfolge wieder).
open Boolean Ist open gleich false, sind untergeordnete Lesezeichen nicht sichtbar. Bei true
werden sie vollständig ausgeklappt. Standardwert: false.
parent Lesezeichen- Das neue Lesezeichen wird dem Lesezeichen untergeordnet, das durch das Handle
Handle festgelegt ist. Ist parent gleich 0, wird das Lesezeichen auf der obersten Ebene
erstellt. Standardwert: 0.
textcolor Farbe Legt die Farbe des Lesezeichentexts fest. Unterstützte Farbräume sind: none, gray,
rgb. Standardwert: rgb {0 0 0 } (=schwarz)
8.9.6 Dokumentinfofelder
C++ Java void set_info(String key, String value)

Perl PHP PDF_set_info(resource p, string key, string value)
C void PDF_set_info(PDF *p, const char *key, const char *value)
C void PDF_set_info2(PDF *p, const char *key, const char *value, int len)
Trägt value in das Dokumentinfofeld key ein.
key (Name-String) Name eines Standardinfofelds oder eines benutzerdefinierten

Felds, der beliebig gewählt sein kann (siehe Tabelle 8.55). Die Anzahl der benutzerdefi-
nierten Felder ist nicht beschränkt. Wenn Sie mit benutzerdefinierten Dokumentinfo-
feldern arbeiten, empfehlen wir einen Blick auf den Dublin Core Metadata Element-Set.1
value (Hypertext-String) String, der dem Parameter key zugewiesen wird. Durch Acro-
bat ist die Länge von value auf maximal 255 Byte beschränkt. Beachten Sie, dass auf-
grund eines Fehlers in Adobe Reader 6 für Windows das Zeichen »&« in manchen Info-
Strings nicht korrekt angezeigt wird.
len (Nur PDF_set_info2( ) und C-Sprachbindung) Länge von value (in Byte) für UCS-2-
Strings. Ist len gleich 0, muss ein null-terminierter String übergeben werden.
Details Der übergebene Wert wird nur für das aktuelle und nicht für alle im selben Geltungsbe-
reich object erstellten Dokumente verwendet.
1. Siehe dublincore.org

Gültigkeit object, document, page. Wird diese Funktion im Geltungsbereicht object verwendet, so
werden die übergebenen Werte nur für das nächste Dokument verwendet.
Tabelle 8.55 Werte für den Dokumentinfofeldschlüssel

Schlüssel Erklärung
Subject Thema des Dokuments
Title Titel des Dokuments
Creator Programm, mit dem das Dokument erstellt wurde (im Gegensatz zum Producer
der PDF-Ausgabe, der immer PDFlib ist). In Acrobat 6 wird dieser Eintrag als
»Anwendung« angezeigt.
Author Verfasser des Dokuments
Keywords Stichwörter für das Dokument
Trapped Gibt an, ob die Datei Überfüllungsinformationen enthält. Erlaubt sind die Werte
True, False und Unknown.
Beliebiger Name außer Benutzerdefiniertes Feld. PDFlib unterstützt beliebig viele Felder. Der Name eines
CreationDate, Producer und benutzerdefinierten Felds sollte nur einmal übergeben werden. Tritt er mehrmals
ModDate auf, so wird der zuletzt übergebene Name verwendet. Siehe auch Option moddate
für PDF_begin/end_document( ).
8.9.7 Veraltete Hypertext-Parameter und Funktionen

Tabelle 8.56 führt veraltete Parameter und Werte für Hypertext-Funktionen auf.
Tabelle 8.56 Veraltete Dokument- und Hypertext-Parameter

Funktion Schlüssel Beschreibung
set_parameter openaction Verwenden Sie die Option action mit dem Schlüsselwort open in PDF_be-
gin/end_document( ).
set_parameter openmode Verwenden Sie die Option openmode in PDF_begin/end_document( ).
set_parameter hidetoolbar Verwenden Sie die Option viewerpreferences in PDF_begin/end_
hidemenubar document( ).
hidewindowui
fitwindow
centerwindow
displaydoctitle
nonfullscreen-
pagemode
direction
viewarea, viewclip
printarea, printclip
set_parameter bookmarkdest Verwenden Sie die Optionen action, destination, fontstyle und textcolor in
PDF_create_bookmark( ).
set_parameter transition Verwenden Sie die Option transition in PDF_begin/end_page_ext( ).
set_value duration Verwenden Sie die Option duration in PDF_begin/end_page_ext( ).
set_parameter base Verwenden Sie die Option uri in PDF_begin/end_document( ).
set_parameter launchlink:parameters Verwenden Sie die Optionen parameters, operation und defaultdir in PDF_
launchlink:operation create_action( ).
launchlink:defaultdir

int PDF_add_bookmark(PDF *p, const char *text, int parent, int open)
int PDF_add_bookmark2(PDF *p, const char *text, int len, int parent, int open)
Veraltet, verwenden Sie stattdessen PDF_create_bookmark( ).
void PDF_add_note(PDF *p, double llx, double lly, double urx, double ury,
const char *contents, const char *title, const char *icon, int open)
void PDF_add_note2(PDF *p, double llx, double lly, double urx, double ury,
const char *contents, int contents_len, const char *title, int title_len,
const char *icon, int open)
Veraltet, verwenden Sie stattdessen PDF_create_annotation( ) mit type=Text.
void PDF_attach_file(PDF *p, double llx, double lly, double urx, double ury, const char
*filename, const char *description, const char *author, const char *mimetype,
const char *icon)
void PDF_attach_file2(PDF *p, double llx, double lly, double urx, double ury, const char
*filename, int len, const char *description, int desc_len, const char *author,
int author_len, const char *mimetype, const char *icon)
Veraltet, verwenden Sie stattdessen PDF_create_annotation( ) mit type=FileAttachment.
Der Parameter description entspricht der Option contents, der Parameter author der Opti-
on title und der Parameter icon der Option iconname.
void PDF_add_pdflink(PDF *p, double llx, double lly, double urx, double ury,
const char *filename, int page, const char *optlist)
Veraltet, verwenden Sie stattdessen PDF_create_action( ) mit type=GoToR und PDF_create_
annotation( ) mit type=Link.
void PDF_add_locallink(PDF *p,

double llx, double lly, double urx, double ury, int page, const char *optlist)
Veraltet, verwenden Sie stattdessen PDF_create_action( ) mit type=GoTo und PDF_create_
void PDF_add_launchlink(PDF *p, double llx, double lly, double urx, double ury,
const char *filename)
Veraltet, verwenden Sie stattdessen PDF_create_action( ) mit type=Launch und PDF_
create_annotation( ) mit type=Link.
void PDF_add_weblink(PDF *p, double llx, double lly, double urx, double ury, const char *url)
Veraltet, verwenden Sie stattdessen PDF_create_action( ) mit type=URI und PDF_create_

void PDF_set_border_style(PDF *p, const char *style, double width)
Veraltet, verwenden Sie die Optionen borderstyle und linewidth in PDF_create_
annotation( ).
void PDF_set_border_color(PDF *p, double red, double green, double blue)

Veraltet, verwenden Sie die Option annotcolor in PDF_create_annotation( ).
void PDF_set_border_dash(PDF *p, double b, double w)

Veraltet, verwenden Sie die Option dasharray PDF_create_annotation( ).

8.10 Strukturfunktionen für Tagged PDF
Um Tagged PDF zu generieren, muss die Option tagged in PDF_begin_document( ) auf
true gesetzt werden; die Option lang muss ebenfalls übergeben werden.
C++ Java int begin_item(String tag, String optlist)

Perl PHP int PDF_begin_item(resource p, string tag, string optlist)
C int PDF_begin_item(PDF *p, const char *tag, const char *optlist)
Öffnet ein Strukturelement oder einen anderen Dokumentbestandteil mit den als Opti-
onen übergebenen Attributen.
tag Elementtyp gemäß Tabelle 8.57. Er muss einem der Standardstrukturtypen ent-
sprechen, die für die aktuelle PDF-Kompatibilitätsstufe zulässig sind, oder einem Pseu-
do-Tag.
Tabelle 8.57 Standardelement-Tags

Kategorie Tags
grouping Document, Part, Art, Sect, Div, BlockQuote, Caption, TOC, TOCI, Index, NonStruct, Private
paragraph-like P, H, H1-H6 (BLSEs)
list L, LI, Lbl, LBody (BLSEs)
table Table (BLSE), TR, TH, TD, THead1, TBody1, TFoot1
inline-level Span, Quote, Note, Reference, BibEntry, Code, (ILSEs)
illustration Figure, Formula, Form
Japanese Ruby1 (grouping), RB1, RT1, RP1, Warichu1 (grouping), WT1, WP1
Pseudo-Tags Die folgenden Tags erzeugen Elemente, die keine Strukturelemente sind:
Artifact Legt ein Artefakt fest, das vom tatsächlichen Seiteninhalt zu unterscheiden ist.
ASpan (accessibility span; wird als Span nach PDF geschrieben, ist aber vom Inline-
Level-Element Span zu unterscheiden) Kann verwendet werden, um
Zugriffseigenschaften mit Inhalten zu verknüpfen, die zu keinem oder nur
teilweise zu einem Strukturelement gehören.
ReversedChars
Legt Text in umgekehrter Zeichenreihenfolge in einer von rechts nach links
geschriebenen Sprache fest. Dies ist nützlich, um hebräischen oder arabischen
Text in Acrobat durchsuchbar zu machen.
Clip Legt eine markierte Beschneidungssequenz fest. Dabei handelt es sich um eine
Sequenz, die nur aus Beschneidungspfaden oder Text im Darstellungsmodus
(textrendering) 7 besteht und keine sichtbare Grafik oder PDF_save( ) / PDF_
restore( ) enthält.
1. Erfordert PDF ab Version 1.5
optlist Optionsliste mit Elementeigenschaften gemäß Tabelle 8.58. Alle vererbbaren

Einstellungen werden an die Kindelemente vererbt und brauchen deshalb nicht wieder-
holt zu werden. Alle Elementeigenschaften müssen hier eingestellt werden, da sie spä-
ter nicht mehr veränderbar sind.
Rückgabe Element-Handle, das in nachfolgenden elementspezifischen Aufrufen verwendet wer-

den kann.

Details Diese Funktion generiert den für Tagged PDF essentiellen Strukturbaum eines Doku-
ments. Die Position des neuen Elements im Strukturbaum lässt sich mit den Optionen
parent und index steuern. Strukturelemente können beliebig verschachtelt werden. Re-
guläre Elemente sind nicht an die Seite gebunden, auf der sie geöffnet wurden, sondern
können auf einer beliebigen Anzahl von Seiten fortgesetzt werden.
Gültigkeit page für Inline-Elemente, für reguläre Elemente auch document; diese Funktion muss
immer paarweise mit PDF_end_item( ) auftreten. Sie ist nur im Tagged-PDF-Modus
zulässig.
Tabelle 8.58 Optionen für die Eigenschaften von Struktur- oder Pseudo-Tags in PDF_begin_item( )
Alt Hypertext- (Nicht für Pseudo-Tags außer in PDF 1.5 für ASpan) Alternative Beschreibung für
String den Dokumentbestandteil. Sie sollte für Bilder, etc. übergeben werden, die sich
nicht als Text interpretieren lassen. Bei Bildern ist alternativer Text zur Barriere-
freiheit (Accessibility) erforderlich. Wird diese Option im PDF-1.4-Modus ver-
wendet, muss die Option inline auf false gesetzt sein.
ActualText Hypertext- (Nicht für Pseudo-Tags außer in PDF 1.5 für ASpan; erforderlich für Text mit Zei-
String chensätzen, die nicht Unicode-konform sind.) Äquivalenter Ersatztext für den
Dokumentbestandteil. Er sollte für Textinhalte übergeben werden, die in un-
üblicher Darstellung vorliegen, wie Ligaturen, verwaschene Zeichen in Bildern,
Initialen etc. Wird diese Option im PDF-1.4-Modus verwendet, muss die Option
inline auf false gesetzt sein.
artifacttype Schlüsselwort (Nur für tag=Artifact) Bezeichnet den Artefakttyp des Dokumentbestandteils:
Pagination, Layout oder Page.
Attached Schlüssel- (Nur für tag=Artifact und artifacttype=Pagination) Liste mit ein bis vier der
wortliste Schlüsselwörter Top, Bottom, Left und Right.
BBox Rechteck (Nur für tag=Artifact sowie alle Tabellen- und Grafik-Tags; optional, aber für das
Umfließen von Text ratsam) Die Größenangabe des Artefakts im Standardkoor-
dinatensystem (bei usercoordinates=false) oder im Benutzerkoordinatensystem
(bei usercoordinates=true). Wurde diese Option nicht übergeben, generiert PDFlib
automatisch einen BBox-Eintrag für importierte Bilder und PDF-Seiten.
ColSpan Integer (Nur für tag=TH und TD) Anzahl der von einer Zelle belegten Tabellenspalten.
E Hypertext- (Nicht für Pseudo-Tags außer ASpan; erfordert PDF 1.5 für Struktur-Tags) Abkür-
String zungsergänzung für den Dokumentbestandteil. Sie sollte zur Erklärung von
Abkürzungen und Akronymen übergeben werden. Die Sprachausgabe von Acro-
bat sieht diese Ergänzung auch ohne explizite Wortgrenze als eigenes Wort an.
entspricht unicode. Standardwert: leerer String für Unicode-fähige Sprachbin-
dungen, sonst auto.
index Integer (Nicht für Pseudo-Tags) Index, an dem das Element unterhalb des Elternelements
eingefügt wird. Anhand von Werten zwischen 0 und der aktuellen Anzahl der
Kindelemente wird das Element an der gewünschten Position unterhalb des
Elternelements angefügt. Mit -1 lässt sich das Element an letzter Position
eintragen. Standardwert: -1.
inline Boolean (Nur für tag=ASpan und alle Inline-Level-Tags) Ist inline gleich true, wird der
Dokumentbestandteil inline geschrieben, und es wird kein Strukturelement
erzeugt. Standardwert: true.
Lang String (Nicht für Pseudo-Tags außer ASpan) Sprachidentifikation für den
Dokumentbestandteil in dem Format, das in Tabelle 8.5 für die Option lang
beschrieben wird. Damit lässt sich die für das Dokument eingestellte Sprache in
einzelnen Dokumentbestandteilen überschreiben.
8.10 Strukturfunktionen für Tagged PDF 339

Tabelle 8.58 Optionen für die Eigenschaften von Struktur- oder Pseudo-Tags in PDF_begin_item( )
RowSpan Integer (Nur für tag=TH und TD) Anzahl der Tabellenzeilen, die von einer Zelle belegt
werden.
Scope Schlüsselwort (Nur für tag=TH; PDF ab Version 1.5) Eines der Schlüsselwörter Row, Column oder
Both, die anzeigen, ob sich die Header-Zelle auf alle Zellen in derselben Zeile, alle
Zellen in derselben Spalte oder auf beides erstreckt.
Title Hypertext- (Nicht für Inline- und Pseudo-Tags) Name des Strukturelements.
String
C++ Java void end_item(int id)

Perl PHP PDF_end_item(resource p, int id)
C void PDF_end_item(PDF *p, int id)
Schließt ein Strukturelement oder einen anderen Dokumentbestandteil.
id Element-Handle, das von PDF_begin_item( ) zurückgegeben wurde.
Details Alle Inline-Elemente müssen vor den Seitenende und alle regulären Elemente vor dem
Dokumentende geschlossen werden. Um den Speicherbedarf zu verringern, sollten re-
guläre Elemente aber unbedingt unmittelbar nach Gebrauch geschlossen werden. Ein
Element kann nur geschlossen werden, wenn zuvor all seine Kindelemente geschlossen
wurden. Nach dem Schließen eines Elements wird sein Elternelement zum aktiven Ele-
ment.
Gültigkeit page für Inline-Elemente und für reguläre Elemente auch document; diese Funktion
muss immer paarweise mit PDF_begin_item( ) auftreten. Sie ist nur im Tagged-PDF-
Modus zulässig.
C++ Java void activate_item(int id)

Perl PHP PDF_activate_item(resource p, int id)
C void PDF_activate_item(PDF *p, int id)
Aktiviert ein zuvor generiertes Strukturelement oder einen anderen Dokumentbe-

standteil.
id Element-Handle, das von PDF_begin_item( ) zurückgegeben und noch nicht ge-

schlossen wurde. Pseudo- und Inline-Level-Elemente lassen sich nicht aktivieren.
Details Es ist erhöht die Flexibilität beim effizienten Erstellen von Tagged-PDF-Seiten, wenn
man ein Strukturelement nicht unmittelbar nach der Erzeugung verwendet, sondern
erst später aktiviert. Dies kann sinnvoll sein, wenn mehrere Strukturbäume auf der Sei-
te parallel verlaufen, zum Beispiel bei mehrspaltigen Layouts oder Texteinschüben, die
den Haupttext unterbrechen. Weitere Informationen finden Sie in Abschnitt 7.5.3, »Ak-
tivierung von Elementen für komplexe Layouts«, Seite 210.
Gültigkeit document, page; Diese Funktion ist nur im Tagged-PDF-Modus zulässig.

A Literaturhinweise
[1] Adobe Systems Incorporated: PDF Reference, Fifth Edition: Version 1.6; als PDF-
Dokument erhältlich unter partners.adobe.com/public/developer/pdf/index_reference.html
[2] Das folgende Buch vom Hauptentwickler von PDFlib behandelt zahlreiche Themen
zu PostScript, PDF und Schriften:
Thomas Merz, Olaf Drümmer: Die PostScript- & PDF-Bibel.

Zweite Auflage. ISBN 3-935320-01-9, PDFlib Edition 2002
PDFlib GmbH, 80331 München, Tal 40, Fax +49 • 89 • 29 16 46 86
PDF kostenlos unter www.pdflib.com
Bestellung gedruckter Exemplare per E-Mail über books@pdflib.com
A Literaturhinweise 341
B PDFlib-Kurzreferenz
Allgemeine Funktionen
Funktionsprototyp Seite
void PDF_boot(void) 223
void PDF_shutdown(void) 223
PDF *PDF_new(void) 223
PDF *PDF_new2(void (*errorhandler)(PDF *p, int errortype, const char *msg), void* (*allocproc)(PDF *p, size_t size,
const char *caller), void* (*reallocproc)(PDF *p, void *mem, size_t size, const char *caller), void (*freeproc)(PDF *p,
void *mem), void *opaque) 224
void PDF_delete(PDF *p) 225
int PDF_begin_document(PDF *p, const char *filename, int len, const char *optlist) 226
void PDF_begin_document_callback(PDF *p, size_t (*writeproc) (PDF *p, void *data, size_t size), const char
*optlist) 226
void PDF_end_document(PDF *p, const char *optlist) 228
const char * PDF_get_buffer(PDF *p, long *size) 229
void PDF_begin_page_ext(PDF *p, double width, double height, const char *optlist) 232
void PDF_end_page_ext(PDF *p, const char *optlist) 233
void PDF_suspend_page(PDF *p, const char *optlist) 235
void PDF_resume_page(PDF *p, const char *optlist) 235
double PDF_get_value(PDF *p, const char *key, double modifier) 236
void PDF_set_value(PDF *p, const char *key, double value) 236
const char * PDF_get_parameter(PDF *p, const char *key, double modifier) 237
void PDF_set_parameter(PDF *p, const char *key, const char *value) 237
void PDF_create_pvf(PDF *p, const char *filename, int len, const void *data, size_t size, const char *optlist) 237
int PDF_delete_pvf(PDF *p, const char *filename, int len) 238
int PDF_get_errnum(PDF *p) 239
const char *PDF_get_errmsg(PDF *p) 239
const char *PDF_get_apiname(PDF *p) 240
void *PDF_get_opaque(PDF *p) 240
const char *PDF_utf16_to_utf8(PDF *p, const char *utf16string, int len, int *size) 241
const char * PDF_utf8_to_utf16(PDF *p, const char *utf8string, const char *ordering, int *size) 241
Fontfunktionen
int PDF_load_font(PDF *p, const char *fontname, int len, const char *encoding, const char *optlist) 243
void PDF_setfont(PDF *p, int font, double fontsize) 246
void PDF_begin_font(PDF *p, char *fontname, int reserved, double a, double b, double c, double d, double e,
double f, const char *optlist) 246
void PDF_end_font(PDF *p) 247
void PDF_begin_glyph(PDF *p, char *glyphname, double wx, double llx, double lly, double urx, double ury) 247
void PDF_end_glyph(PDF *p) 248
void PDF_encoding_set_char(PDF *p, const char *encoding, int slot, const char *glyphname, int uv) 248
Textausgabefunktionen
void PDF_set_text_pos(PDF *p, double x, double y) 251
void PDF_show(PDF *p, const char *text) 251
void PDF_xshow(PDF *p, const char *text, int len, const double *xadvancelist) 251
void PDF_show_xy(PDF *p, const char *text, double x, double y) 252
void PDF_continue_text(PDF *p, const char *text) 252
void PDF_fit_textline(PDF *p, const char *text, int len, double x, double y, const char *optlist) 253
double PDF_stringwidth(PDF *p, const char *text, int font, double fontsize) 257
int PDF_create_textflow(PDF *p, const char *text, int len, const char *optlist) 258
const char *PDF_fit_textflow(PDF *p, int textflow, double llx, double lly, double urx, double ury, const char
*optlist) 259
double PDF_info_textflow(PDF *p, int textflow, const char *keyword) 262
void PDF_delete_textflow(PDF *p, int textflow) 262
Grafikfunktionen
void PDF_setdash(PDF *p, double b, double w) 269
void PDF_setdashpattern(PDF *p, const char *optlist) 269
void PDF_setflat(PDF *p, double flatness) 270
void PDF_setlinejoin(PDF *p, int linejoin) 270
void PDF_setlinecap(PDF *p, int linecap) 270
void PDF_setmiterlimit(PDF *p, double miter) 271
void PDF_setlinewidth(PDF *p, double width) 271
void PDF_initgraphics(PDF *p) 272
void PDF_save(PDF *p) 272
void PDF_restore(PDF *p) 273
void PDF_translate(PDF *p, double tx, double ty) 273
void PDF_scale(PDF *p, double sx, double sy) 273
void PDF_rotate(PDF *p, double phi) 274
void PDF_skew(PDF *p, double alpha, double beta) 274
void PDF_concat(PDF *p, double a, double b, double c, double d, double e, double f) 274
void PDF_setmatrix(PDF *p, double a, double b, double c, double d, double e, double f) 275
int PDF_create_gstate(PDF *p, const char *optlist) 275
void PDF_set_gstate(PDF *p, int gstate) 276
void PDF_moveto(PDF *p, double x, double y) 277
void PDF_lineto(PDF *p, double x, double y) 277
void PDF_curveto(PDF *p, double x1, double y1, double x2, double y2, double x3, double y3) 278
void PDF_circle(PDF *p, double x, double y, double r) 278
void PDF_arc(PDF *p, double x, double y, double r, double alpha, double beta) 278
void PDF_arcn(PDF *p, double x, double y, double r, double alpha, double beta) 279
void PDF_rect(PDF *p, double x, double y, double width, double height) 279
void PDF_closepath(PDF *p) 280
void PDF_stroke(PDF *p) 280
344 Anhang B: PDFlib-Kurzreferenz

void PDF_closepath_stroke(PDF *p) 280
void PDF_fill(PDF *p) 281
void PDF_fill_stroke(PDF *p) 281
void PDF_closepath_fill_stroke(PDF *p) 281
void PDF_clip(PDF *p) 281
void PDF_endpath(PDF *p) 282
int PDF_define_layer(PDF *p, const char *name, int len, const char *optlist) 282
void PDF_set_layer_dependency(PDF *p, const char *type, const char *optlist) 283
void PDF_begin_layer(PDF *p, int layer) 284
void PDF_end_layer(PDF *p) 285
Farbfunktionen
void PDF_setcolor(PDF *p, const char *fstype, const char *colorspace, double c1, double c2, double c3, double c4)
286
int PDF_makespotcolor(PDF *p, const char *spotname, int reserved) 288
int PDF_load_iccprofile(PDF *p, const char *profilename, int len, const char *optlist) 288
int PDF_begin_pattern(PDF *p, double width, double height, double xstep, double ystep, int painttype) 290
void PDF_end_pattern(PDF *p) 291
int PDF_shading_pattern(PDF *p, int shading, const char *optlist) 291
void PDF_shfill(PDF *p, int shading) 292
int PDF_shading(PDF *p, const char *shtype, double x0, double y0, double x1, double y1, double c1, double c2,
double c3, double c4, const char *optlist) 292
Rasterbildfunktionen
int PDF_load_image(PDF *p, const char *imagetype, const char *filename, int len, const char *optlist) 295
void PDF_close_image(PDF *p, int image) 299
void PDF_fit_image(PDF *p, int image, double x, double y, const char *optlist) 299
int PDF_begin_template(PDF *p, double width, double height) 302
void PDF_end_template(PDF *p) 302
void PDF_add_thumbnail(PDF *p, int image) 302
Funktionen für den PDF-Import (PDI)

int PDF_open_pdi(PDF *p, const char *filename, const char *optlist, int len) 304
int PDF_open_pdi_callback(PDF *p, void *opaque, size_t filesize, size_t (*readproc)(void *opaque, void *buffer,
size_t size), int (*seekproc)(void *opaque, long offset), const char *optlist) 305
void PDF_close_pdi(PDF *p, int doc) 306
int PDF_open_pdi_page(PDF *p, int doc, int pagenumber, const char* optlist) 306
void PDF_close_pdi_page(PDF *p, int page) 308
void PDF_fit_pdi_page(PDF *p, int page, double x, double y, const char *optlist) 308
int PDF_process_pdi(PDF *p, int doc, int page, const char* optlist) 309
double PDF_get_pdi_value(PDF *p, const char *key, int doc, int page, int reserved) 309
const char * PDF_get_pdi_parameter(PDF *p, const char *key, int doc, int page, int reserved, int *len) 310
Blockfunktionen
int PDF_fill_textblock(PDF *p, int page, const char *blockname, const char *text, int len, const char *optlist) 313
int PDF_fill_imageblock(PDF *p, int page, const char *blockname, int image, const char *optlist) 314
int PDF_fill_pdfblock(PDF *p, int page, const char *blockname, int contents, const char *optlist) 315
Hypertext-Funktionen
int PDF_create_action(PDF *p, const char *type, const char *optlist) 317
void PDF_add_nameddest(PDF *p, const char *name, int len, const char *optlist) 321
void PDF_create_annotation(PDF *p, double llx, double lly, double urx, double ury, const char *type, const char
*optlist) 323
void PDF_create_field(PDF *p, double llx, double lly, double urx, double ury, const char *name, int len, const char
*type, const char *optlist) 327
void PDF_create_fieldgroup(PDF *p, const char *name, int len, const char *optlist) 332
int PDF_create_bookmark(PDF *p, const char *text, int len, const char *optlist) 332
void PDF_set_info(PDF *p, const char *key, const char *value) 334
Tagged PDF und Strukturfunktionen

int PDF_begin_item(PDF *p, const char *tag, const char *optlist) 338
void PDF_end_item(PDF *p, int id) 340
void PDF_activate_item(PDF *p, int id) 340
346 Anhang B: PDFlib-Kurzreferenz

Parameter und Werte
Kategorie Funktion Schlüssel
Konfiguration set_parameter resourcefile, SearchPath, license, licensefile, nodemostamp, warning, asciifile, tra-
ce, tracefile, logmsg
set_value compress
Versionen get_value major, minor, revision
get_parameter version
Seite get_value pagewidth, pageheight
Schrift set_parameter FontAFM, FontPFM, FontOutline, Encoding, fontwarning, kerning, autosubsetting,
autocidfont, textformat, unicodemap
get_parameter ascenderfaked, capheightfaked, descenderfaked, fontname, fontencoding, font-
style, textformat, xheightfaked
set_value subsetlimit, subsetminsize
get_value ascender, capheight, descender, font, fontsize, fontmaxcode, monospace, xheight
Text set_value leading, textrise, horizscaling, textrendering, charspacing, wordspacing, itali-
cangle, underlinewidth, underlineposition
get_value leading, textrise, horizscaling, textrendering, charspacing, wordspacing, textx,
texty, italicangle, underlinewidth, underlineposition
set_parameter autospace, underline, overline, strikeout, kerning, glyphwarning
get_parameter underline, overline, strikeout, fontstyle
Grafik set_parameter fillrule, topdown
get_parameter scope
get_value currentx, currenty, ctm_a, ctm_b, ctm_c, ctm_d, ctm_e, ctm_f
Farbe set_parameter iccwarning, honoriccprofile, ICCProfile, StandardOutputIntent, renderingintent,
preserveoldpantonenames, spotcolorlookup
set_value defaultgray, defaultrgb, defaultcmyk, setcolor:iccprofilegray, setcolor:iccprofi-
lergb, setcolor:iccprofilecmyk
get_value image:iccprofile, icccomponents
Rasterbild get_value imagewidth, imageheight, orientation, resx, resy
set_parameter imagewarning
PDI get_parameter pdi
set_parameter pdiwarning
get_pdi_value /Root/Pages/Count, /Rotate, version, width, height
CropBox, BleedBox, ArtBox, TrimBox: danach muss ein Schrägstrich ’/’ sowie llx,
lly, urx oder ury folgen, zum Beispiel CropBox/llx
get_pdi_ filename, /Info/<key>, vdp/Blocks/<Blockname>/<Eigenschaftsname>,
parameter vdp/Blocks/<Blockname>/Custom/<Eigenschaftsname>
Hypertext set_parameter hypertextformat, hypertextencoding, usercoordinates
get_parameter hypertextformat
C Änderungen an diesem Handbuch
Datum Änderungen
13. März 2006 > Deutsche Übersetzung des Handbuchs für PDFlib 6.0.3 mit kleineren Erweite-
rungen und Korrekturen und einem neuen Abschnitt über Ruby
14. September 2005 > Deutsche Übersetzung des Handbuchs für PDFlib 6.0.2 mit kleineren Erweite-
rungen und Korrekturen
19. November 2004 > Deutsche Übersetzung des Handbuchs für PDFlib 6.0.1 mit kleineren Erweiterun-
gen und Korrekturen
> sprachabhängige Funktionsprototypen in Kapitel 8
> Beispiele für Hypertext-Erstellung in Kapitel 3
19. August 2004 > Deutsche Übersetzung des Handbuchs für PDFlib 6.0.0
18. Juni 2004 > Erweiterungen für PDFlib 6
6. Oktober 2003 > Deutsche Übersetzung des Handbuchs für PDFlib 5.0.2
15. September 2003 > Kleinere Änderungen für PDFlib 5.0.2, Ergänzung der Blockspezifikation
30. Mai 2003 > Deutsche Übersetzung des Handbuchs für PDFlib 5.0.1
6. August 2002 > Deutsche Übersetzung des Handbuchs für PDFlib 4.0.3, Ergänzungen für .NET
14. Juni 2002 > Kleinere Änderungen für PDFlib 4.0.3 und Erweiterungen für die .NET-Bindung
26. Januar 2002 > Kleinere Änderungen für PDFlib 4.0.2 und Erweiterungen für die IBM-eServer-
Edition
17. Mai 2001 > Kleinere Änderungen für PDFlib 4.0.1
1. April 2001 > Dokumentiert PDI- und andere Funktionen von PDFlib 4.0.0
5. Februar 2001 > Dokumentiert Template- und CMYK-Funktionen in PDFlib 3.5.0
22. Dezember 2000 > ColdFusion-Dokumentation und Erweiterungen für PDFlib 3.03; separate
ActiveX-Edition des Handbuchs
8. August 2000 > Delphi-Dokumentation und kleinere Erweiterungen für PDFlib 3.02
1. Juli 2000 > Erweiterungen und Klarstellungen für PDFlib 3.01
20. Februar 2000 > Änderungen für PDFlib 3.0
2. August 1999 > Kleinere Änderungen und Erweiterungen für PDFlib 2.01
29. Juni 1999 > Eigene Abschnitte für die jeweiligen Sprachbindungen
> Erweiterungen für PDFlib 2.0
1. Februar 1999 > Kleinere Änderungen für PDFlib 1.0 (keine öffentliche Freigabe)
10. August 1998 > Erweiterungen für PDFlib 0.7 (nur für einen Kunden)
8. Juli 1998 > Erste Beschreibung der PDFlib-Skriptunterstützung in PDFlib 0.6
25. Februar 1998 > Kleine Erweiterungen am Handbuch für PDFlib 0.5
22. September 1997 > Erste öffentliche Version von PDFlib 0.4 und dieses Handbuchs
348 Anhang C: Änderungen an diesem Handbuch

Index
0-9 builtin-Zeichensatz 102

byte order mark (BOM) 109
16-Bit-Zeichensätze 105 bytes: siehe hypertextformat
8-Bit-Zeichensätze 98 Byteserving 200
bytes-Textformat 111
A
Adobe Font Metrics (AFM) 88 C
Adobe Glyph List (AGL) 84, 101 C++-Sprachbindung 30
AFM (Adobe Font Metrics) 88
Speicherverwaltung 32
AGL (Adobe Glyph List) 84, 101
capheight-Parameter 115, 242
Aktionslisten 220
CCITT 150
aktueller Punkt 66
CCSID 100
All (Schmuckfarbname) 288
CFF (Compact Font Format) 83
alphaisshape-Option 275
Character ID (CID) 120
Alphakanal 151
Character-Referenzen 111
Anlagen 106
characters per inch (CPI) 116
Anmerkungen 106
charref-Parameter 249
antialias-Option 293
charspacing-Parameter 249
API (Application Programming Interface) 217
chinesisch 120, 122, 125
äquidistante Schrift 116
CID-Schriften 120
ArtBox 65, 226, 310, 311
CIE L*a*b* Farbraum 73
AS/400 60
ascender-Parameter 115, 242 CJK (chinesisch, japanisch, koreanisch) 120
asciifile-Parameter 61, 222 benutzerdefinierte Schriften 124
asiatisches Fontpaket 120 CMaps 120
Ausgabegenauigkeit 66 Standardschriften 120
Ausnahmebehandlung 52 Windows-Codepages 125
Ausrichtung (Option position) 255 Clipping (Beschneiden) 66
Author-Feld 335 CMaps 120, 122
autocidfont-Parameter 96, 97, 243 CMYK 69
autospace-Parameter 249 Cobol binding 22
autosubsetting-Parameter 96, 97, 243 Codepage
auto-Textformat 110 Microsoft Windows 1250-1258 99
Unicode-Werte 105
compress-Parameter 222
B COM-Sprachbindung 26
Baseline-Kompression 149 Content-Strings 107
benutzerdefinierte Schriften (Type 3) 91 in nicht Unicode-fähigen Sprachen 108
benutzerdefinierter Zeichensatz 100 copyoutputintent-Option 205
Berechtigungen 197 CPI (characters per inch) 116
Bézier-Kurve 278 Creator-Feld 335
Big Five 125 CropBox 65, 226, 310, 311
Bildfunktionen 294 C-Sprachbindung 26
Bildmasken 151, 152 Speicherverwaltung 29
BleedBox 65, 226, 310, 311 ctm_x-Parameter 277
blendmode-Option 275 currentx- und currenty-Parameter 115, 277
Blends 70
Blöcke 165
Blockeigenschaften 168 D
Block-Plugin 165 Dateianlagen 106
BMP 150 defaultgray/rgb/cmyk-Parameter 76, 290
Index 349
Demostempel 9 font-Parameter 242
descender-Parameter 115, 242 FontPFM-Parameter 242
Deskriptor 95 Fonts
Dokumentfunktionen 225 AFM-Dateien 88
Dokumentinfofelder 106, 334 allgemein 83
Downsampling 148 äquidistante 116
dpi-Berechnungen 148 asiatisches Fontpaket 120
Drehen von Objekten 63 benutzerdefinierte (Type 3) 91
Druckausgabebedingung für PDF/X 202 CID-Schriften 120
Dublin Core 334 Deskriptor 95
Glyphennamen 89
E PDF-Standardschriften 94
PFA-Dateien 88
EBCDIC 60 PFB-Dateien 88
ebcdicutf8: siehe hypertextformat PFM-Dateien 88
ebcdic-Zeichensatz 99 PostScript 83, 88
Einheiten 62 rechtliche Aspekte der Einbettung 96
EJB (Enterprise Java Beans) 34 Ressourcekonfiguration 56
Embedded-Systeme 21 Type 1 88
Encoding Type 3 (benutzerdefiniert) 91, 246
siehe Zeichensatz Unicode-Unterstützung 105
Encoding-Parameter 242 fontsize-Parameter 242
eServer zSeries und iSeries 60 FontSpecific-Encoding 102
EUDC (end-user defined characters) 126 Fontstilnamen für Windows 90
EUDC-Fonts 90 fontstyle-Parameter 242
Eurozeichen 103 fontwarning-Parameter 54, 242
Exceptions 52, 65 Form XObjects 67
explizite Transparenz 151 Formularfelder: Konvertierung in Blöcke 176
expliziter Grafikzustand 275 Funktionalität von PDFlib 17
extend0- und extend1-Optionen 293 Funktionsgeltungsbereich 51
F G
Farbe 69 Gaiji-Zeichen 84
Farbfunktionen 286 GBK 125
Farbverläufe 70 Geltungsbereich 51
Farbwerte in Optionslisten 220 GIF 149
FDFlib Virtual File System (PVF) 55 Glyph-ID-Adressierung 103
Fehlerbehandlung glyphwarning-Parameter 249
API 224 Gradients 70
in C 28 Grafikfunktionen 269
in C++ 31 Grafikzustand
in Cobol 22 expliziter 275
in Java 35 Funktionen 269
in Perl 37 grid.pdf 62
in PHP 40 gstate 291
in Python 41
in RPG 44
in Tcl 49 H
filename-Parameter 311 HKS 72
Filling (Füllen) 66 Hochstellen von Text 116
fillrule-Parameter 280 honoriccprofile-Parameter 294
flatness-Option 275 horizontaler Text 121, 122
FontAFM-Parameter 242 horizscaling-Parameter 249
fontencoding-Parameter 242 host fonts 87
fontmaxcode-Parameter 103, 242 HostFont-Parameter 242
Fontmetrik 115 host-Zeichensatz 98
fontname-Parameter 242 hypertextencoding-Parameter 110, 317
FontOutline-Parameter 242 hypertextformat-Parameter 109, 317
350 Index
Hypertext-Funktionen 317 licensefile-Parameter 222
Hypertext-Strings 107 license-Parameter 222
in nicht Unicode-fähigen Sprachen 108 linearisiertes PDF 200, 227
linecap-Option 275
I linejoin-Option 275
linewidth-Option 275
IBM eServer 60
ICC-based color 69 Listenwerte in Optionslisten 220
icccomponents-Parameter 290 Literaturhinweise 341
ICCProfile-Parameter 290 Lizenzierung von PDFlib und PDI 9
iccwarning-Parameter 290 LWFN (LaserWriter Font) 88
ignoremask 153
image:iccprofile-Parameter 75, 294 M
imagewarning-Parameter 294
Mac OS Classic: UPR-Konfiguration 57
imagewidth- und imageheight-Parameter 294
implizite Transparenz 151 macroman encoding 98
Importfunktionen für PDF 304 macroman_apple-Zeichensatz 99, 103
in-core PDF-Erzeugung 59 macroman-Zeichensatz 98, 99
Index-Farbe 69 major-Parameter 222
Info-Schlüssel in importierten PDF-Dokumenten makepsres Hilfsprogramm 56
311 mask 152
Inline-Optionslisten für Textflüsse 263 masked 152
iSeries 60 Maskierung von Bildern 151
ISO 10646 105 masterpassword-Parameter 198, 226
ISO 8859-2 bis -15 99 MediaBox 65
italicangle-Parameter 249 mehrseitige Bilddateien 154
Metadaten 231, 334
J Metrik 115
japanisch 120, 122, 125 metrische Koordinaten 62
Java-Applikationsserver 33 Millimeter 62
Java-Sprachbindung 32 minor-Parameter 222
EJB 34 miterlimit-Option 276
javadoc 33 monospace parameter 242
Package 33 monospaced: siehe äquidistant
Servlet 33
JFIF 149
Johab 125
N
JPEG 149 Name-Strings 107
JPEG2000 149 in nicht Unicode-fähigen Sprachen 109
.NET-Sprachbindung 35
nodemostamp-Parameter 222
K None (Schmuckfarbname) 288
Kachelung 69 N-Option 293
Kategorien von Ressourcen 56 Notizen 106
Kennwörter 197
Kerning 116
kerning-Parameter 117, 249 O
Keywords-Feld 335 Oberlänge 115
kommerzielle Lizenz 11 opacityfill-Option 276
Koordinatensystem 62 opacitystroke-Option 276
metrisch 62 openwarning-Parameter 225
Top-Down 63 optimiertes PDF 200
koreanisch 120, 123, 125
Optionslisten 218
orientation-Parameter 294
L overline-Parameter 118, 250
Laufweite 116 overprintfill-Option 276
Layer und PDI 157 overprintmode-Option 276
leading-Parameter 115, 249 overprintstroke-Option 276
Index 351
P PDF_fill_pdfblock() 315
PDF_fill_stroke() 281
page-Option 154 PDF_fill_textblock() 313
pagewidth- und pageheight-Parameter 225 PDF_fit_image() 299
PANTONE 71 PDF_fit_pdi_page 308
Parameterbehandlungsfunktionen 236 PDF_fit_text() 253
Passwörter 197 PDF_fit_textflow() 259
Pattern-Farbraum 69 PDF_get_apiname() 240
patterns 69
PDF_get_buffer() 60, 229
PDF/X 201
PDF_get_errmsg() 239
Druckausgabebedingung 309
PDF_get_errnum() 239
Import von PDF-Dokumenten 205
PDF_get_opaque() 240
PDF_activate_item() 340
PDF_get_parameter() 237
PDF_add_nameddest() 321
PDF_get_pdi_parameter 310
PDF_add_thumbnail() 302
PDF_get_pdi_value 309
PDF_arc() 278
PDF_get_value() 236
PDF_arcn() 279
PDF_info_textflow() 262
PDF_begin_document() 226
PDF_initgraphics() 272
PDF_begin_item() 338
PDF_lineto() 277
PDF_begin_layer() 284
PDF_load_font() 243
PDF_begin_page() 232, 233, 235, 236
PDF_load_iccprofile() 288
PDF_begin_pattern 290
PDF_load_image() 295
PDF_begin_template() 302
PDF_makespotcolor() 288
PDF_boot() 223
PDF_moveto() 277
PDF_circle() 278
PDF_new() 223
PDF_clip() 281
PDF_close_image() 299 PDF_new_dl( ) 223
PDF_close_pdi 306 PDF_new2() 224
PDF_close_pdi_page 308 PDF_open_pdi 304
PDF_closepath() 280 PDF_open_pdi_callback 305
PDF_closepath_fill_stroke() 281 PDF_open_pdi_page 306
PDF_closepath_stroke() 280 PDF_process_pdi 309
PDF_concat() 274 PDF_rect() 279
PDF_continue_text() 252 PDF_restore() 273
PDF_continue_text2() 252 PDF_rotate() 274
PDF_create_action() 317 PDF_save() 272
PDF_create_annotation() 323 PDF_scale() 273
PDF_create_bookmark() 332 PDF_set_gstate() 276
PDF_create_field() 327 PDF_set_info() 334
PDF_create_fieldgroup() 332 PDF_set_info2() 334
PDF_create_gstate() 275 PDF_set_layer_dependency() 283
PDF_create_pvf 237 PDF_set_parameter() 59, 237
PDF_create_textflow() 258 PDF_set_text_pos() 251
PDF_curveto() 278 PDF_set_value() 236
PDF_define_layer() 282 PDF_setcolor() 286
PDF_delete() 225 PDF_setdash() 269
PDF_delete_dl( ) 225 PDF_setdashpattern() 269
PDF_delete_pvf 238 PDF_setflat() 270
PDF_delete_textflow() 262 PDF_setfont() 246, 247, 248
PDF_encoding_set_char() 248 PDF_setlinecap() 270
PDF_end_document() 228 PDF_setlinejoin() 270
PDF_end_item() 340 PDF_setlinewidth() 271
PDF_end_layer() 285 PDF_setmatrix() 275
PDF_end_page() 236 PDF_setmiterlimit() 271
PDF_end_pattern 291 PDF_shading() 292
PDF_end_template() 302 PDF_shading_pattern() 291
PDF_endpath() 282 PDF_shfill() 292
PDF_fill() 281 PDF_show() 251
PDF_fill_imageblock() 314 PDF_show_boxed() 257
352 Index
PDF_show_xy() 252
PDF_show_xy2() 252
R
PDF_show2() 251 r0- und r1-Optionen 293
PDF_shutdown() 223 Rasterbilder
PDF_skew() 274 allgemein 147
PDF_stringwidth() 257 Bildmasken 152
PDF_stringwidth2() 257 Daten wiederverwenden 147
PDF_stroke() 280 Downsampling 148
Formate 148
PDF_translate() 273
Funktionen 294
PDF_utf16_to_utf8 241
Rohdaten 151
PDF_utf8_to_utf16() 241
skalieren 148
PDF_xshow() 251
Transparenz 151
PDF-Importbibliothek PDI 155, 304
REALbasic-Sprachbindung 42
PDF-Importfunktionen 304
Rechtecke in Optionslisten 220
PDFlib
Reflexion 273
Funktionalität 17
renderingintent-Option 73, 276
Programmstruktur 51
renderingintent-Parameter 294
PDFlib Personalization Server 165
Rendering-Intents 73
pdflib.upr 59
resourcefile-Parameter 59, 222
PDFlib-API-Referenz 217
Ressourcekategorie 56
PDFlib-Plugin zur Blockerzeugung 165
Ressourcenkonfiguration 56
PDFLIBRESOURCE-Umgebungsvariable 59
resx- und resy-Parameter 294
pdfx-Parameter
revision-Parameter 222
für PDI 205, 311
RGB-Farbe 69
PDI 155, 304 Rohbilddaten 151
pdi-Parameter 311 Rotate-Eintrag in importierten PDF-Seiten 310
pdiusebox-Parameter 157, 311 RPG-Sprachbindung 42
pdiwarning-Option 157 Ruby-Sprachbindung 46
pdiwarning-Parameter 311
Perl-Sprachbindung 35
permissions-Option 199 S
permissions-Parameter 226 S/390 60
PFA (Printer Font ASCII) 88 Scherung 274
Pfad 66 Schmuckfarbe (Separation-Farbraum) 69, 70
zeichnen und beschneiden 280 schnelle Web-Anzeige 227
PFB (Printer Font Binary) 88 Schriften: siehe Fonts
PFM (Printer Font Metrics) 88 Schriftuntergruppen 96
PHP-Sprachbindung 37 scope-Parameter 223
Piktogramme 302 SearchPath-Parameter 58, 222, 242
Plattformen 21 Seitenbeschreibungen 62
Plugin zur Blockerzeugung 165 Seitenformate 64
PNG 148, 151 Begrenzungen in Acrobat 65
Portable Document Format Reference Manual 341 Seitenfunktionen 225
PostScript-Schriften 83, 88 seitenweises Herunterladen 200
PPS (PDFlib Personalization Server) 165 Separation-Farbraum 69
prefix-Parameter 222 serial-Parameter 9
preserveoldpantonenames-Parameter 286 Servlet 33
print_glyphs.ps 89 setcolor:iccprofilegray/rgb/cmyk-Parameter 76,
Printer Font ASCII (PFA) 88 290
Printer Font Binary (PFB) 88 Setup-Funktionen 222
Printer Font Metrics (PFM) 88 Shift-JIS 125
Programmstruktur 51 Sicherheit 197
PVF siehe PDFlib Virtual File System 55 Skalieren von Rasterbildern 148
Python-Sprachbindung 41 Smooth Shadings 70
smoothness-Option 276
Speicher: Erzeugung von PDF-Dokumenten im 59
Q Speicherverwaltung
Querformat 234 API 224
Index 353
in C 29 Thumbnails: siehe Piktogramme
in C++ 32 Tiefstellen von Text 116
Spiegelung 273 TIFF 149
SPIFF 149 mehrseitig 154
spotcolorlookup-Parameter 286 Title-Feld 335
Sprachbindungen 21 Top-Down-Koordinaten 63
sRGB-Farbraum 75 topdown-Parameter 64, 225
Standardausgabe 226 ToUnicode CMap 86, 106
Standard-Druckausgabebedingungen für PDF/X trace, tracefile, tracemsg parameters 223
204 Transparenz 151
Standardkoordinatensystem 62 explizite 151
StandardOutputIntent-Parameter 290 implizite 151
Standardschriften 94 Probleme mit 153
Standardseitenmaße 65 Trapped-Feld 335
stdout-Kanal 226 TrimBox 65, 226, 310, 311
Stilnamen für Windows 90 TrueType Collections 124
strikeout-Parameter 118, 250 TTC (TrueType Collection) 90, 124, 126
strokeadjust-Option 276 TTF (TrueType-Font) 83
Stroking (Zeichnen) 66 Type-1-Schriften 88
Struktur von PDFlib-Programmen 51 Type-3-Schriften 91, 246
Subject-Feld 335
subscript 116, 250
subsetlimit-Parameter 97, 242
U
subsetminsize-Parameter 97, 242 U+XXXX-Encoding 105
superscript 116, 250 Überschreiben von Blockeigenschaften 168
Symbolschrift 102 UHC 125
Systemschriften 87 Umgebungsvariable PDFLIBRESOURCE 59
Systemzeichensätze 100 Umrisslinien von Text zeichnen 250
underline-Parameter 118, 250
underlineposition-Parameter 250
T underlinewidth-Parameter 250
Tcl-Sprachbindung 48 Unicode 105
Teilpfad 66 unicodemap-Parameter 106, 243
Templates 67 unsichtbarer Text 250
Text Untergruppen einer Schrift 96
Funktionen 242 Unterlänge 115
hochstellen 116 Unterschneidung 116
Laufweite 116 UPR (Unix PostScript Resource) 56
Oberlänge 115 Dateiformat 57
Position 115 Dateisuche 59
tiefstellen 116 user space 62
Umrisslinien zeichnen 250 usercoordinates-Parameter 62, 317
unsichtbarer 250 userpassword-Parameter 198, 226
Unterlänge 115 utf16: siehe hypertextformat
unterschneiden 116 utf16be: siehe hypertextformat
Versalhöhe 115 utf16le: siehe hypertextformat
vertikal und horizontal 121, 122 utf8: siehe hypertextformat
x-Höhe 115
Zeilenabstand 115
Textanmerkungen 106 V
Textbehandlung 83 Variable Data Processing (VDP) 313
Textfluss:Inline-Optionslisten 263 variable Datenverarbeitung mit Blöcken 165
textformat-Parameter 109, 250 vdp/blockcount-Parameter für PDI 312
textknockout-Option 276 vdp/Block-Parameter für PDI 312
Textmetrik 115 Verfügbarkeit von PDFlib 21
textrendering-Parameter 118, 250 Versalhöhe 115
textrise-Parameter 250 Verschlüsselung 197
Textvarianten 115 version-Parameter 223, 311
textx- und texty-Parameter 115, 123, 250 vertikaler Text 121, 122
354 Index
virtuelles Dateisystem 55 XObjects 67
W Z
warning-Parameter 53, 239 ZapfDingbats-Schrift 102
web-optimiertes PDF 200, 227 Zeichennamen 89
width- und height-Parameter 310 Zeichensätze 98
winansi-Zeichensatz 99 benutzerdefinierte 100
wordspacing-Parameter 250 CJK 123
für Hypertext 110
X vom System beziehen 100
xheight-Parameter 115 Zeilenabstand 115
x-Höhe 115 Zoll 62
XMP-Metadaten 231 zSeries 60
Index 355

PDFlib Manual D

Hochgeladen von

Dokumentinformationen

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

PDFlib Manual D

Hochgeladen von

Copyright:

Verfügbare Formate

PDFlib GmbH München

Eine Bibliothek für dynamisches PDF

Allgemeine Ausgabe für

PDFlib enthält den Message-Digest-Algorithmus MD5 von RSA Security, Inc.

Autor: Thomas Merz

2 Sprachbindungen von PDFlib 21

5 Import und Platzierung von Objekten 147

6 Variable Daten und Blöcke 165

8 API-Referenz für PDFlib, PDI und PPS 217

C Änderungen an diesem Handbuch 348

> In C++, Java, Ruby und PHP 5 mit objektorienterter Programmierschnittstelle:

> In Perl, PHP 4 und PHP 5 mit prozeduraler Programmierschnittstelle:

> In C++, Java und PHP 5 mit objektorientierter Programmierschnittstelle:

> In Perl, PHP 4 und PHP 5 mit prozeduraler Programmierschnittstelle :

10 Kapitel 0: Anwendung des PDFlib-Lizenzschlüssels

Testen unlizenzierter Funktionen. Ohne Lizenzschlüssel lassen sich alle Funktionen

Lizenzvarianten. Es gibt verschiedene Lizenzierungsmöglichkeiten für die Verwen-

PDFlib GmbH, Lizenzabteilung

1.1 Programmierung mit PDFlib 13

Beispielcode. Das vorliegende Handbuch enthält zahlreiche Codefragmente. PDFlib

Verbesserte Programmierung. Viele in früheren Versionen vorhandene Einschrän-

Unicode. PDFlib 6 bietet erweiterte Unicode-Unterstützung, so dass Unicode-Strings

Textformatierung. Die neue Textflussformatierung bietet ein leistungsstarkes und

Behandlung von Rasterbildern. Die Verarbeitung von TIFF-Bildern wurde um bislang

1.2 Die wichtigsten neuen Funktionen von PDFlib 6 15

PDFlib-Blöcke zur Verarbeitung variabler Daten. Die Benutzerschnittstelle des PDFlib-

REALbasic. Als Neuzugang in der großen Familie unterstützter Programmierumge-

1.3 Funktionalität von PDFlib 17

Tabelle 1.2 Verfügbarkeit von Funktionen in verschiedenen Produkten

1.4 Verfügbarkeit der Funktionen in den Produkten 19

Tabelle 2.1 Getestete Kombinationen von Sprachen und Plattformen

PDFlib auf Embedded-Systemen. PDFlib kann auch auf Embedded-Systemen einge-

Rückgabewerte. Der Rückgabewert einer PDFlib-API-Funktion wird in einem zusätzli-

Fehlerbehandlung. In der Cobol-Sprachbindung gibt es keine PDFlib-Ausnahmebe-

22 Kapitel 2: Sprachbindungen von PDFlib

CALL "PDBEGDOC" USING P,

CALL "PDSETINF" USING P,

CALL "PDSETINF" USING P,

CALL "PDSETINF" USING P,

CALL "PDLODFNT" USING P,

24 Kapitel 2: Sprachbindungen von PDFlib

MOVE PDFLIB-RETURN-LONG TO WS-FONT.

CALL "PDSETFNT" USING P,

CALL "PDSETTP" USING P,

STRING Z'Hello, World!'

CALL "PDSHOW" USING P,

STRING Z'(says COBOL)'

CALL "PDCONT" USING P,

2.4.2 Das Beispiel »Hello world« in C

if ((p = PDF_new()) == (PDF *) 0)

PDF_set_info(p, "Creator", "hello.c");

PDF_begin_page_ext(p, a4_width, a4_height, "");

/* Change "host" encoding to "winansi" or whatever you need! */

26 Kapitel 2: Sprachbindungen von PDFlib

/* PDFlib als dynamische Bibliothek laden und neues PDFlib-Objekt erzeugen */

PDFlib->PDF_set_info(p, "Creator", "hello.c");

PDFlib->PDF_begin_page_ext(p, a4_width, a4_height, "");

/* Ändere Zeichensatz "host" zu "winansi" oder anderem Zeichensatz */

PDFlib->PDF_setfont(p, font, 24);

/* PDFlib-Objekt löschen und Library entfernen */

28 Kapitel 2: Sprachbindungen von PDFlib

Error-Handler alten Typs. Neben der strukturierten Ausnahmebehandlung unter-

Die Syntax der Speicherverwaltungsroutinen wird in Abschnitt 8.2, »Allgemeine Funkti-