PDFlib GmbH München

www.pdflib.com

Referenzhandbuch
®

Eine Bibliothek für dynamisches PDF

Version 6.0.1

Allgemeine Ausgabe für

Cobol, C, C++, Java, Perl,
PHP, Python, RPG und Tcl
Copyright © 1997–2004 PDFlib GmbH und Thomas Merz. Alle Rechte vorbehalten.

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: [email protected]
Support für Inhaber einer kommerziellen PDFlib-Lizenz: [email protected] (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, Windows und Windows NT sind Warenzeichen von Microsoft Corporation. Apple, Macintosh
und TrueType sind Warenzeichen von Apple Computer, Inc. Unicode und das Unicode-Logo sind Warenzei-
chen 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 Waren-
zeichen 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 ([email protected])
JPEG-Software der Indenpendent JPEG Group, Copyright © 1991-1998, Thomas G. Lane

PDFlib enthält den Message-Digest-Algorithmus MD5 von RSA Security, Inc.

Viva Software GmbH (software.viva.de) trug Verbesserungen für die Fontverarbeitung auf dem Mac bei.

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 11
1.1 Programmierung mit PDFlib 11
1.2 Die wichtigsten neuen Funktionen von PDFlib 6 13
1.3 Funktionalität von PDFlib 15
1.4 Verfügbarkeit der Funktionen in den Produkten 17

2 Sprachbindungen von PDFlib 19

2.1 Übersicht 19
2.2 Cobol Binding 19
2.2.1 Besondere Hinweise für Cobol 19
2.2.2 Das Beispiel »Hello world« in Cobol 20
2.3 COM-Sprachbindung 23
2.4 C-Sprachbindung 24
2.4.1 Verfügbarkeit und besondere Hinweise zu C 24
2.4.2 Das Beispiel »Hello world« in C 24
2.4.3 Einsatz von PDFlib als DLL, die zur Laufzeit geladen wird 25
2.4.4 Fehlerbehandlung in C 26
2.4.5 Speicherverwaltung in C 27
2.4.6 Unicode in der C-Sprachbindung 28
2.5 C++-Sprachbindung 28
2.5.1 Verfügbarkeit und besondere Hinweise zu C++ 28
2.5.2 Das Beispiel »Hello world« in C++ 28
2.5.3 Fehlerbehandlung in C++ 29
2.5.4 Speicherverwaltung in C++ 29
2.5.5 Unicode in der C++-Sprachbindung 30
2.6 Java-Sprachbindung 30
2.6.1 Installation der Java-Edition von PDFlib 30
2.6.2 Das Beispiel »Hello world« in Java 32
2.6.3 Fehlerbehandlung in Java 32
2.7 .NET-Sprachbindung 33
2.8 Perl-Sprachbindung 33
2.8.1 Installation der PDFlib-Perl-Edition 33
2.8.2 Das Beispiel »Hello world« in Perl 34
2.8.3 Fehlerbehandlung in Perl 35
2.9 PHP-Sprachbindung 35
2.9.1 Installation der PDFlib-Edition für PHP 35
2.9.2 Das Beispiel »Hello world« in PHP 36

Inhaltsverzeichnis 3
 2.9.3 Fehlerbehandlung in PHP 38
2.10 Python-Sprachbindung 38
2.10.1 Installation der Python-Edition von PDFlib 38
2.10.2 Das Beispiel »Hello world« in Python 39
2.10.3 Fehlerbehandlung in Python 39
2.11 REALbasic-Sprachbindung 39
2.12 RPG-Sprachbindung 40
2.12.1 Kompilieren und Binden von RPG-Programmen für PDFlib 40
2.12.2 Das Beispiel »Hello world« in RPG 40
2.12.3 Fehlerbehandlung in RPG 42
2.13 Tcl-Sprachbindung 44
2.13.1 Installation der PDFlib-Tcl-Edition 44
2.13.2 Das Beispiel »Hello world« in Tcl 44
2.13.3 Fehlerbehandlung in Tcl 45

3 PDFlib-Programmierung 47
3.1 Allgemeine Aspekte 47
3.1.1 PDFlib-Programmstruktur und Geltungsbereich von Funktionen 47
3.1.2 Parameter 47
3.1.3 Behandlung von Ausnahmen (Exceptions) 48
3.1.4 Optionslisten 51
3.1.5 Das PDFlib Virtual File System (PVF) 53
3.1.6 Ressourcenkonfiguration und Dateisuche 54
3.1.7 Erzeugen von PDF-Dokumenten im Arbeitsspeicher 58
3.1.8 Einsatz von PDFlib auf EBCDIC-Systemen 59
3.1.9 Unterstützung für große Dateien 59
3.2 Seitenbeschreibungen 61
3.2.1 Koordinatensysteme 61
3.2.2 Höchstwerte für Seiten und Koordinaten 63
3.2.3 Pfade 65
3.2.4 Templates 65
3.3 Farbe 67
3.3.1 Farben und Farbräume 67
3.3.2 Füllmuster und Farbverläufe 67
3.3.3 Schmuckfarben 68
3.3.4 Colormanagement und ICC-Profile 71
3.4 Hypertext-Elemente 75
3.4.1 Beispiele zur Erstellung von Hypertext-Elementen 75
3.4.2 Formatierungsoptionen für Textfelder 78

4 Textausgabe 81
4.1 Übersicht über Schriften und Zeichensätze 81
4.1.1 Unterstützte Fontformate 81
4.1.2 Zeichensätze 82

4 Inhaltsverzeichnis
 4.1.3 Unicode-Unterstützung 83
4.2 Fontformate im Detail 85
4.2.1 PostScript-Fonts 85
4.2.2 TrueType- und OpenType-Fonts 86
4.2.3 Benutzerdefinierte Schriften (Type-3-Fonts) 88
4.3 Schrifteinbettung und Schriftuntergruppen 90
4.3.1 Wie PDFlib nach Fonts sucht 90
4.3.2 Schrifteinbettung 91
4.3.3 Bildung von Fontuntergruppen (Subsetting) 93
4.4 Zeichensätze 95
4.4.1 8-Bit-Zeichensätze 95
4.4.2 Symbolschriften und fontspezifische Zeichensätze 99
4.4.3 Glyph-ID-Adressierung für TrueType- und OpenType-Fonts 100
4.4.4 Das Eurozeichen 100
4.5 Unicode-Unterstützung 102
4.5.1 Unicode für Seitenbeschreibungen und Hypertext 102
4.5.2 Content-Strings, Hypertext-Strings und Name-Strings 103
4.5.3 Stringbehandlung in Unicode-fähigen Sprachen 104
4.5.4 String-Behandlung in nicht Unicode-fähigen Sprachen 105
4.5.5 Character-Referenzen 108
4.5.6 Unicode-kompatible Fonts 110
4.6 Textmetrik und Textvarianten 112
4.6.1 Font- und Zeichenmetriken 112
4.6.2 Kerning 113
4.6.3 Textvarianten 114
4.7 Chinesischer, japanischer und koreanischer Text 116
4.7.1 CJK-Unterstützung in Acrobat und PDF 116
4.7.2 Standard-CJK-Fonts und -CMaps 117
4.7.3 Benutzerspezifische CJK-Fonts 120
4.7.4 Erzwingen äquidistanter Schrift 122
4.8 Platzieren und Einpassen von einzeiligem Text 124
4.8.1 Einfaches Platzieren von Text 124
4.8.2 Platzieren von Text in einer Box 125
4.8.3 Ausrichten von Text 126
4.9 Mehrzeilige Textflüsse 127
4.9.1 Platzierung eines Textflusses in der Fitbox 128
4.9.2 Optionen für die Absatzformatierung 129
4.9.3 Inline-Optionen und Makros 130
4.9.4 Tabulatoren 133
4.9.5 Nummerierte Listen 133
4.9.6 Steuerzeichen, Zeichenersetzung und Symbolfonts 135
4.9.7 Steuerung des Algorithmus für den Zeilenumbruch 137
4.9.8 Formatierung von CJK-Text in Textflüssen 141

Inhaltsverzeichnis 5
 5 Import und Platzierung von Objekten 143
5.1 Import von Rasterbildern 143
5.1.1 Grundlegende Vorgehensweise 143
5.1.2 Unterstützte Rasterbildformate 144
5.1.3 Bildmasken und Transparenz 146
5.1.4 Einfärben von Bildern 149
5.1.5 Mehrseitige Bilddateien 149
5.1.6 OPI-Unterstützung 150
5.2 Import von PDF-Seiten mit PDI (PDF Import Library) 151
5.2.1 PDI-Funktionen und -Anwendungen 151
5.2.2 Einsatz von PDI-Funktionen mit PDFlib 151
5.2.3 Importierbare PDF-Dokumente 153
5.3 Platzieren von Bildern und importierten PDF-Seiten 155
5.3.1 Skalierung, Ausrichtung und Drehung 155
5.3.2 Anpassen der Seitengröße 157

6 Variable Daten und Blöcke 161

6.1 Installation des PDFlib-Block-Plugins 161
6.2 Überblick über das Blockkonzept von PDFlib 163
6.2.1 Vollständige Trennung von Dokumentdesign und Programmcode 163
6.2.2 Blockeigenschaften 164
6.2.3 Was spricht gegen PDF-Formularfelder? 165
6.3 Anlegen von PDFlib-Blöcken 167
6.3.1 Interaktive Blockerzeugung mit dem PDFlib-Block-Plugin 167
6.3.2 Bearbeiten von Blockeigenschaften 170
6.3.3 Kopieren von Blöcken zwischen Seiten und Dokumenten 171
6.3.4 Konvertieren von PDF-Formularfeldern in PDFlib-Blöcke 172
6.4 Standardeigenschaften zur automatischen Verarbeitung 175
6.4.1 Allgemeine Eigenschaften 175
6.4.2 Textspezifische Eigenschaften 177
6.4.3 Rasterbildspezifische Eigenschaften 181
6.4.4 PDF-spezifische Eigenschaften 182
6.4.5 Selbstdefinierte Eigenschaften 182
6.5 Abfragen von Blocknamen und -eigenschaften 183
6.6 Spezifikation für PDFlib-Blöcke 185
6.6.1 PDF-Objektstruktur für PDFlib-Blöcke 185
6.6.2 Erzeugen von PDFlib-Blöcken mit pdfmarks 187

7 Erstellung verschiedener
PDF-Varianten 189
7.1 Acrobat und PDF-Versionen 189
7.2 Verschlüsseltes PDF 191
7.2.1 Stärken und Schwächen der Sicherheitsfunktionen von PDF 191

6 Inhaltsverzeichnis
 7.2.2 Schützen von Dokumenten mit PDFlib 192
7.3 Web-Optimiertes (Linearisiertes) PDF 194
7.4 PDF/X 195
7.4.1 PDF/X-Standards 195
7.4.2 Erzeugung PDF/X-kompatibler Ausgabe 196
7.4.3 Import von PDF/X-Dokumenten mit PDI 198
7.5 Tagged PDF 200
7.5.1 Erzeugung von Tagged PDF mit PDFlib 200
7.5.2 Erzeugung von Tagged-PDF-Textausgabe und -Textflüssen 202
7.5.3 Aktivierung von Elementen für komplexe Layouts 203
7.5.4 Verwendung von Tagged PDF in Acrobat 206

8 API-Referenz für PDFlib, PDI und PPS 209

8.1 Datentypen und Namenskonventionen 209
8.2 Allgemeine Funktionen 211
8.2.1 Setup 211
8.2.2 Dokument und Seite 214
8.2.3 Parameterbehandlung 224
8.2.4 Virtuelles Dateisystem (PDFlib Virtual File System, PVF) 226
8.2.5 Ausnahmebehandlung 227
8.2.6 Hilfsfunktionen 229
8.3 Textfunktionen 231
8.3.1 Fontbehandlung 231
8.3.2 Benutzerdefinierte (Type 3) Schriften 235
8.3.3 Definition von Zeichensätzen (Encodings) 237
8.3.4 Einfache Textausgabe 238
8.3.5 Mehrzeilige Textausgabe mit Textflüssen 246
8.4 Grafikfunktionen 256
8.4.1 Funktionen für den Grafikzustand 256
8.4.2 Speichern und Wiederherstellen des Grafikzustands 259
8.4.3 Funktionen zur Transformation des Koordinatensystems 260
8.4.4 Explizite Grafikzustände 262
8.4.5 Pfadkonstruktion 263
8.4.6 Zeichnen und Beschneiden von Pfaden 267
8.4.7 Ebenenfunktionen 269
8.5 Farbfunktionen 272
8.5.1 Festlegen von Farbe und Farbraum 272
8.5.2 Füllmuster und Farbverläufe 276
8.6 Rasterbild- und Template-Funktionen 280
8.6.1 Rasterbilder 281
8.6.2 Templates 287
8.6.3 Piktogramme (Thumbnails) 288
8.7 Funktionen für den PDF-Import (PDI) 289
8.7.1 Dokument und Seite 289

Inhaltsverzeichnis 7
 8.7.2 Weitere Funktionen zur PDI-Verarbeitung 294
8.7.3 Parameterbehandlung 294
8.8 Blockfunktionen (PPS) 298
8.9 Hypertext-Funktionen 302
8.9.1 Aktionen 302
8.9.2 Benannte Ziele 306
8.9.3 Anmerkungen 308
8.9.4 Formularfelder 312
8.9.5 Lesezeichen 318
8.9.6 Dokumentinfofelder 319
8.9.7 Veraltete Hypertext-Parameter und Funktionen 320
8.10 Strukturfunktionen für Tagged PDF 323

A Literaturhinweise 327

B PDFlib-Kurzreferenz 329

C Änderungen an diesem Handbuch 334

Index 335
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 [email protected] senden und einen temporären Lizenzschlüssel anfordern (wir behal-
ten uns das Recht vor, einer Anforderung nicht nachzukommen, z.B. bei anonymen An-
fragen).
Nachdem Sie einen Lizenzschlüssel erworben haben, müssen Sie ihn anwenden, da-
mit der Demostempel auch tatsächlich unterdrückt wird. Dazu gibt es mehrere Mög-
lichkeiten:
> Fügen Sie in Ihrem Skript oder Programm eine Zeile ein, die die Seriennummer zur
Laufzeit setzt:
PDF_set_parameter(p, "license", "...Ihre Seriennummer...");

Der Parameter license darf nur einmal gesetzt werden, und dies muss unmittelbar
nach der Instantiierung des PDFlib-Objekts erfolgen (das heißt nach PDF_new( ) oder
einem entsprechenden Aufruf).
> Tragen Sie den 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.1 ...Ihr Lizenzschlüssel...

Sie können auch mehrere Lizenzschlüssel für verschiedene Produkte der PDFlib
GmbH in die Lizenzdatei aufnehmen, wobei jeder dann 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 un-
mittelbar nach der Instantiierung des PDFlib-Objekts (das heißt, nach PDF_new( )
oder einem gleichbedeutenden Aufruf) wie folgt:
PDF_set_parameter(p, "licensefile", "/path/to/license/file");

oder Sie setzen die Umgebungsvariable PDFLIBLICENSEFILE mit einem Befehl der fol-
genden Art:
export PDFLIBLICENSEFILE=/path/to/license/file

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.

9
 Zusammenstellen mehrerer CPU-Schlüssel. Wenn Sie mehrere CPU-Lizenzen in ver-
schiedenen statt einer einzigen Bestellung erworben haben, können Sie sie in der Li-
zenzdatei zusammenstellen, indem Sie sie nacheinander dort eintragen. Auch die Funk-
tion PDF_set_parameter( ) kann für mehrere Lizenzschlüssel mehrmals aufgerufen
werden. In der Windows-Registry lassen sich die Lizenzschlüssel nicht sammeln.

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 den Pseudo-
Lizenzschlüssel 0 verwenden, um die Funktionalität einer höheren Produktkategorie zu
testen:
PDF_set_parameter(p, "license", "0");

Damit werden alle deaktivierten Funktionen wieder aktiviert, und der Demostempel er-
scheint 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: [email protected]
Support für PDFlib-Lizenznehmer: [email protected]

10 Kapitel 0: Anwendung des PDFlib-Lizenzschlüssels

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)
> Tcl

1.1 Programmierung mit PDFlib 11

 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.

12 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 color. 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.

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 13

 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.

14 Kapitel 1: Einführung
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 und CCITT
automatische Erkennung von Rasterbilddateiformaten
transparente (maskierte) Bilder und Transparenzmasken
Bildmasken (eingefärbte Bilder)

1.3 Funktionalität von PDFlib 15

 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, Tcl
mierung
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

16 Kapitel 1: Einführung
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 – 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 17

 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
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

18 Kapitel 1: Einführung
 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 2/3, 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 2/3 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.0, 1.1: –
C#, VB.NET, ASP.NET
Perl Perl 5.6 – 5.8 Perl 5.6 – 5.8 –
PHP PHP 4.3.x, 5.0.x PHP 4.3.x, 5.0.x –
Python Python 1.6, 2.0 – 2.3 Python 1.6, 2.0 – 2.3 –
REALbasic REALbasic 5.5 oder höher für Mac OS Classic, Mac OS X und Windows –
RPG – – ILE RPG
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 [email protected] in Verbindung.

2.2 Cobol Binding

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

2.1 Übersicht 19
 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 vorliegenen 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.

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.

20 Kapitel 2: Sprachbindungen von PDFlib

 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'
DELIMITED BY SIZE INTO WS-STRING.
STRING Z'Hello.cbl'
DELIMITED BY SIZE INTO WS-STRING2.

2.2 Cobol Binding 21

 CALL "PDSETINF" USING P,
WS-STRING,
WS-STRING2,
RC.

STRING Z'Author'
DELIMITED BY SIZE INTO WS-STRING.
STRING Z'Thomas Merz'
DELIMITED BY SIZE INTO WS-STRING2.

CALL "PDSETINF" USING P,

WS-STRING
WS-STRING2,
RC.

STRING Z'Title'
DELIMITED BY SIZE INTO WS-STRING.
STRING Z'Hello, world (COBOL)!'
DELIMITED BY SIZE INTO WS-STRING2.

CALL "PDSETINF" USING P,

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'
DELIMITED BY SIZE INTO WS-STRING.
STRING Z'ebcdic'
DELIMITED BY SIZE INTO WS-STRING2.

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.

22 Kapitel 2: Sprachbindungen von PDFlib

 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* 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!'

DELIMITED BY SIZE INTO WS-STRING.

CALL "PDSHOW" USING P,

WS-STRING,
RC.

STRING Z'(says COBOL)'

DELIMITED BY SIZE INTO WS-STRING.

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.3 COM-Sprachbindung 23
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 25).

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, "");
}

24 Kapitel 2: Sprachbindungen von PDFlib

 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);
}

2.4 C-Sprachbindung 25
 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");
printf("[%d] %s: %s\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");
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);

26 Kapitel 2: Sprachbindungen von PDFlib

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 211, 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

2.4 C-Sprachbindung 27
 ü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");

28 Kapitel 2: Sprachbindungen von PDFlib

 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 {
...PDFlib-Anweisungen...
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.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-

2.5 C++-Sprachbindung 29
 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-

30 Kapitel 2: Sprachbindungen von PDFlib

 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.

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 Java-Sprachbindung 31
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

32 Kapitel 2: Sprachbindungen von PDFlib

 Die Java-Exceptions können mit der üblichen Kombination aus try und catch behandelt
werden:
try {

...PDFlib-Anweisungen...

} 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
(Dieser Abschnitt ist nur in der COM/.NET/REALbasic-Ausgabe des PDFlib-Referenz-
handbuchs enthalten.)

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).
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

1. Siehe www.perl.com

2.7 .NET-Sprachbindung 33
 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, "");
};

if ($@) {
printf("hello: PDFlib Exception occurred:\n");
printf(" $@\n");
exit;
}

1. Siehe www.activestate.com

34 Kapitel 2: Sprachbindungen von PDFlib

 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 {
...PDFlib-Anweisungen...
};
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 auf der PDFlib-Web-Site.
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 die Stan-
dardsystemverzeichnisse durchsucht. Mit dem folgenden einzeiligen PHP-Skript
können Sie ermitteln, welche Version der PDFlib-Sprachbindung für PHP Sie instal-
liert 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:
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.

1. Siehe www.php.net

2.9 PHP-Sprachbindung 35
 > 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 andere Da-
teien auf dem Laufwerk werden in der Unix- und der Windows-Version von PHP unter-
schiedlich 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.6, »Ressourcenkonfiguration und Dateisuche«, Seite 54).

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, "");

36 Kapitel 2: Sprachbindungen von PDFlib

$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);
}

2.9 PHP-Sprachbindung 37
 $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 PDFlibException 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.

1. Siehe www.python.org

38 Kapitel 2: Sprachbindungen von PDFlib

 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:
...PDFlib-Anweisungen...
except:
print 'Exception abgefangen!'

2.11 REALbasic-Sprachbindung1
(Dieser Abschnitt ist nur in der COM/.NET/REALbasic-Ausgabe des PDFlib-Referenz-
handbuchs enthalten.)

1. Siehe www.realbasic.com

2.11 REALbasic-Sprachbindung 39
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:
CRTBNDRPG PGM(PDFLIB/HELLO) SRCFILE(PDFLIB/QRPGLESRC) SRCMBR(*PGM) DFTACTGRP(*NO)
BNDDIR(PDFLIB/PDFLIB)

2.12.2 Das Beispiel »Hello world« in RPG

*****************************************************************************************
d/copy QRPGLESRC,PDFLIB
*****************************************************************************************
d p S *
d font s 10i 0
*
d error s 50
d errmsg_p s *

40 Kapitel 2: Sprachbindungen von PDFlib

 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'
c callp PDF_set_info(p:infokey:infoval)
* Set info "Title"
c eval infokey='Title'+x'00'
c eval infoval='Hello, world (RPG)!'+x'00'
c callp PDF_set_info(p:infokey:infoval)
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)

2.12 RPG-Sprachbindung 41
 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/copy QRPGLESRC,PDFLIB
*****************************************************************************************
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')

42 Kapitel 2: Sprachbindungen von PDFlib

 *
c eval p=pdf_new2(errhdl:*null:*null:*null:*null)

...PDFlib-Anweisungen...

c callp PDF_delete(p)
*
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 callp PDF_delete(p)
*
c return
*
p errhandler E

2.12 RPG-Sprachbindung 43
2.13 Tcl-Sprachbindung
2.13.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.13.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

44 Kapitel 2: Sprachbindungen von PDFlib

 PDF_end_document $p ""

PDF_delete $p

2.13.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.13 Tcl-Sprachbindung 45
46 Kapitel 2: Sprachbindungen von PDFlib
 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 267
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,

3.1 Allgemeine Aspekte 47

 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

48 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 26).
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-

3.1 Allgemeine Aspekte 49

 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 Funk-
tionen 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 re-
agieren 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 */

50 Kapitel 3: PDFlib-Programmierung
 /* Anderen Font probieren oder aufgeben */
...
}
/* Font-Handle ist gültig; weiter wie üblich */

3.1.4 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

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 102.
> 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 108, aber ohne Auszeichnung
durch ’&’ oder ’;’ (shy, #xAD, #173). Unichars müssen im Bereich 0-65535 (0-xFFFF)
liegen.
> 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.

3.1 Allgemeine Aspekte 51

 > 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 in Kapitel 8 erwähnt. Beispiele für einfache Werte sind (die ers-
te 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}

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}

Farbwerte. Farbwerte sind Listen, 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 Abschnitt 8.5.1,
»Festlegen von Farbe und Farbraum«, Seite 272), ), mögliche Werte werden in Abschnitt
3.3.1, »Farben und Farbräume«, Seite 67, 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.

52 Kapitel 3: PDFlib-Programmierung
 > Das Farbraum-Schlüsselwort spot kann mit einem Schmuckfarben-Handle angege-
ben werden. Alternativ dazu kann das Farbraum-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 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 }

3.1.5 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-

3.1 Allgemeine Aspekte 53

 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.6 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. In der UPR-Datei können zur Kompatibilität mit Display-

54 Kapitel 3: PDFlib-Programmierung
PostScript-Installationen auch andere Ressourcenkategorien vorkommen, diese werden
aber kommentarlos ignoriert.

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
Encoding Textdatei mit 8-Bit-Zeichensatz oder Codepagetabelle
HostFont Name einer im System installierten Schrift. Der Wert kann in ASCII oder
UTF-8 mit einleitendem BOM kodiert sein. Letzteres kann bei lokalisierten
Hostfontnamen sinnvoll sein.
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 Textedior 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 Abschnitt, der alle Ressourcenkategorien auflistet, die in der Datei beschrieben
werden. Jede Zeile beschreibt eine Kategorie. Die Liste wird mit einem Punkt abge-
schlossen. Die verfügbaren Ressourcenkategorien werden unten beschrieben.
> 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.

3.1 Allgemeine Aspekte 55

 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 kann eine PDFlib-Anwendung
unabhängig von plattformspezifischen Dateisystemkonventionen ausgeführt werden.
Um diesen Suchmechanismus zu unterbinden, geben Sie vollständige Pfadnamen in
den jeweiligen PDFlib-Funktionsaufrufen an.
Unter Windows initialisiert PDFlib die Ressourcenkategorie SearchPath mit folgen-
dem Eintrag aus der Registry:
HKLM\SOFTWARE\PDFlib\PDFlib\6.0.1\SearchPath

Dieser Eintrag kann eine Liste von Pfadnamen enthalten, die durch Strichpunkte ’;’ ge-
trennt sind.
Auf den Systemen IBM iSeries wird die Ressourcenkategorie SearchPath mit folgenden
Werten initialisiert:
/pdflib/6.0.1/fonts
/pdflib/6.0.1/bind/data

Auf MVS wird die SearchPath-Funktion nicht unterstützt.

UPR-Beispieldatei. Das folgende Listing zeigt ein Beispiel für eine UPR-Konfigurati-
onsdatei für PDFlib. Darin werden die Font- und Metrikdateien einiger Schriften sowie
ein benutzerdefinierter Zeichensatz beschrieben:
PS-Resources-1.0
SearchPath
FontAFM
FontPFM
FontOutline
Encoding
ICCProfile
.
SearchPath
/usr/local/lib/fonts
Classic:Data:Fonts
C:/psfonts/pfm
C:/psfonts

56 Kapitel 3: PDFlib-Programmierung
/users/kurt/my_images
.
FontAFM
Code-128=Code_128.afm
.
FontPFM
Foobar-Bold=foobb___.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.1\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.

3.1 Allgemeine Aspekte 57

 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.7 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_open_file(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

58 Kapitel 3: PDFlib-Programmierung
 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.8 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.9 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-

3.1 Allgemeine Aspekte 59

 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.

60 Kapitel 3: PDFlib-Programmierung
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

3.2 Seitenbeschreibungen 61
 PDFlib-Entwicklung können Sie sich die Seite mit dem für Sie interessanten Format auf
eine durchsichtige Folie ausdrucken.
Acrobat 5/6 (nur die Vollversion, nicht der kostenlose Reader) verfügt ebenfalls über
ein nützliches Hilfsmittel. Mit dem Menübefehl Fenster, Info können Sie dort die Palette
Info mit numerischen Koordinatenwerten in der Einheit Punkt anzeigen. Beachten Sie
dabei, 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_set_text_pos(p, 50, 600);
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.

62 Kapitel 3: PDFlib-Programmierung
 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
<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

1. Weitere Informationen über ISO-Formate, japanische Formate und US-Standardformate finden Sie unter folgenden URLs:
www.twics.com/~eds/paper/papersize.html, www.cl.cam.ac.uk/~mgk25/iso-paper.html

3.2 Seitenbeschreibungen 63
 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.

64 Kapitel 3: PDFlib-Programmierung
 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 267):
> 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. Alle diesbezüglichen Regeln las-
sen sich einfach zusammenfassen: Ȁndern Sie keine Darstellungseigenschaften (zum
Beispiel Farbe oder Strichstärke) während der Definition eines Pfads.«
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-

3.2 Seitenbeschreibungen 65
 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 155). 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 280,
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 302. 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.

66 Kapitel 3: PDFlib-Programmierung
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 71).
> ICC-basierte Farben werden mittels eines ICC-Profils definiert (siehe Abschnitt 3.3.4,
»Colormanagement und ICC-Profile«, Seite 71).
> 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 68.
> 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 67)
> 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 67).
> 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 67
 > 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.

68 Kapitel 3: PDFlib-Programmierung
Hinweis Die PDF-Farbseparation geht über den Rahmen von PDFlib hinaus; dafür ist Acrobat 6, zusätzli-
che Software für Acrobat 5 (wie das Plugin ARTS PDF Crackerjack1) oder In-RIP-Separation erfor-
derlich.

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 Kompatibilität zu älteren Anwendungen zu gewähr-
leisten, die vielleicht andere Farbdefinitionen verwenden.
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 195). 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)

1. Siehe www.artspdf.com

3.3 Farbe 69
 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:

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
(Farbfächer) verwenden (Beispielnamen werden in Klammern
angegeben):
> HKS K (Kunstdruckpapier), 88 Farben (HKS 43 K)
> HKS N (Naturpapier), 88 Farben (HKS 43 N)
> HKS E (Endlospapier) beschichtet, 90 Farben (HKS 43 E)
> HKS Ek (Endlospapier) unbeschichtet, 88 Farben (HKS 43 E)
> HKS En: entspricht HKS E (HKS 43 En)
> HKS Z (Zeitungspapier), 50 Farben (HKS 43 Z)

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,

70 Kapitel 3: PDFlib-Programmierung
 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.

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-

1. Siehe www.color.org

3.3 Farbe 71
 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.
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.

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

72 Kapitel 3: PDFlib-Programmierung
 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.
Über den Parameter image:iccprofile können bestimmte ICC-Profile generell auf alle
Graustufen-, RGB- oder CMYK-Bilder angewandt werden. Im Gegensatz zu den Stan-

3.3 Farbe 73
 dardfarbräumen (siehe unten) beziehen sich diese Parameter nur auf Rasterbilder und
nicht auf Text oder Vektorgrafik.

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.

74 Kapitel 3: PDFlib-Programmierung
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

3.4 Hypertext-Elemente 75
 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.

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 Acrobat: Gehe Zu einer Seite eines anderen Dokuments). In der Options-
liste zu dieser Aktion definieren wir mit filename den Namen des Zieldokuments und
mit der Option destination, dass ein bestimmter Seitenausschnitt deutlich vergrößert
angezeigt wird. Genauer gesagt soll das Dokument auf der zweiten Seite (page 2) in defi-
nierter Darstellung (type fixed) mit der Seitenmitte im sichtbaren 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);

76 Kapitel 3: PDFlib-Programmierung
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

3.4 Hypertext-Elemente 77
 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.

78 Kapitel 3: PDFlib-Programmierung
 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

3.4 Hypertext-Elemente 79
 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);

80 Kapitel 3: PDFlib-Programmierung
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. Windows 2000/XP sowie
Mac OS X bieten native OpenType-Unterstützung. Es gibt zwei Varianten von OpenTy-
pe, 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
116) 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.

4.1 Übersicht über Schriften und Zeichensätze 81

 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).

82 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 116).
> 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.

4.1 Übersicht über Schriften und Zeichensätze 83

 > 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.

84 Kapitel 4: Textausgabe
 4.2 Fontformate im Detail
4.2.1 PostScript-Fonts
Formate für PostScript-Fontdateien. PDFlib unterstützt auf allen Systemen folgende
Formate für PostScript-Type-1-Metrikdaten und Zeichenbeschreibungen:
> 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 PFM-Dateien nur mit folgenden Zei-
chensätzen verwendet werden: winansi, iso8859-1, unicode, ebcdic und builtin (letzterer
nur für Symbolfonts).
> 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, manchmal
LWFN-Fonts (LaserWriter Font) genannt, unterstützt.
> OpenType-Fonts mit PostScript-Zeichenbeschreibungen (*.otf).

Wenn Sie zu einem PostScript-Font die Zeichenbeschreibungs-, aber nicht die Metrikda-
tei besitzen, können Sie versuchen, die fehlenden Metrikdaten mit einem der frei ver-
fügbaren Hilfsprogramme zu generieren. Beachten Sie jedoch, dass solche Konvertie-
rungen häufig zu Schrift- oder Zeichensatzproblemen führen. Es ist deshalb unbedingt
empfehlenswert, die vom Schrifthersteller mitgelieferten Zeichenbeschreibungs- und
Metrikdaten zu verwenden.

PostScript-Fontnamen. Wenn Sie mit Systemschriften arbeiten, müssen Sie immer

den richtigen PostScript-Fontnamen (unter Berücksichtigung von Groß- und Klein-
schreibung) verwenden. 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 90). 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 ATM (Adobe Type Manager) installiert haben oder mit Windows 2000/XP
arbeiten, können Sie auf die Zeichenbeschreibungsdatei (*.pfb) oder auf die Metrikda-
tei (*.pfm) 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

4.2 Fontformate im Detail 85

 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-Level-2- oder Level-3-Drucker, destillieren sie oder betrachten sie mit einem
Level-2-kompatiblen PostScript-Viewer. Das Programm druckt alle in der Schrift vor-
handenen 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.2 TrueType- und OpenType-Fonts

Dateiformate für TrueType und OpenType. PDFlib unterstützt für TrueType- und
OpenType-Fonts folgende Dateiformate:
> Windows-TrueType-Fonts (*.ttf) inklusive CJK-Fonts
> 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).
> Unter Mac OS kann jeder auf dem System installierte TrueType-Font (einschließlich
.dfont) auch in PDFlib verwendet werden.

TrueType- und OpenType-Fontnamen. Wenn Sie mit Systemschriften arbeiten, müs-

sen Sie immer den genauen TrueType-Fontnamen (unter Berücksichtigung von Groß-
und Kleinschreibung) angeben (unter Windows können Sie auch den Basisnamen des
Fonts und den Stilnamen als Suffix angeben, siehe unten). 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 90). Der Name eines TrueType-Fonts im gene-
rierten PDF-Dokument kann von den in PDFlib (oder Windows) benutzten Namen ab-
weichen. Das ist normal und liegt darin begründet, dass PDF den PostScript-Namen ei-
nes TrueType-Fonts verwendet, der nicht unbedingt mit dem ursprünglichen
TrueType-Namen übereinstimmt (zum Beispiel TimesNewRomanPSMT bzw. Times New
Roman).

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).

86 Kapitel 4: Textausgabe
Hinweis Im Gegensatz zu PostScript-Fonts können die Namen von TrueType- und OpenType-Fonts Leer-
zeichen enthalten.

Ermitteln von TrueType-Fontnamen unter Windows. Um den Namen einer installier-

ten Schrift herauszufinden, doppelklicken Sie einfach auf die TrueType-Fontdatei.
Verwenden Sie den Namen in der ersten Zeile des angezeigten Fensters mit Schriftinfor-
mationen (natürlich ohne einen der Begriffe TrueType oder OpenType in Klammern). Be-
nutzen Sie nicht den Namen in der zweiten Zeile nach Schriftart! Auch können Schriftna-
men entsprechend der jeweiligen Windows-Version teilweise lokalisiert sein. So kann
der übliche Bestandteil Bold auf einem deutschen System als Fett erscheinen. In PDFlib
müssen Sie die übersetzte Variante oder den Stilnamen des Fonts verwenden, um die
Schriftdaten vom Betriebssystem zu beziehen. Dagegen müssen Sie die generische
(nicht lokalisierte) Variante des Schriftnamens heranziehen, um die Schriftdaten direkt
aus der Fontdatei abzurufen.
Wenn Sie sich intensiver mit TrueType-Fonts beschäftigen möchten, sollten 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.

Windows-Fontstilnamen. Bei der Abfrage von Systemschriften im Windows-Betriebs-

system können PDFlib-Anwender eine Funktion nutzen, die vom Schriftselektionsme-
chanismus von Windows zur Verfügung gestellt wird: Für das Gewicht 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-Schriften oder Schriften, die über eine Fontdatei auf der Fest-
platte 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:

1. Siehe www.microsoft.com/typography/property/property.htm

4.2 Fontformate im Detail 87

 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.

Ermitteln von Host-Fontnamen auf dem Mac. Unter Mac OS X finden Sie den Namen
eines installierten Fonts im Allgemeinen im Schriftmenü von Anwendungen wie Text-
Edit. Damit erhalten Sie jedoch noch nicht unbedingt den korrekten und von PDFlib er-
warteten Fontnamen. Wir empfehlen daher Apples frei verfügbare Font Tools,1 eine
Sammlung von Befehlszeilen-Programmen inklusive des Programms ftxinstalledfonts
zur Bestimmung der korrekten Namen aller installierten Fonts. Um den von PDFlib er-
warteten Namen zu ermitteln, installieren Sie Font Tools und führen in einem Termi-
nalfenster den folgenden Befehl aus:
ftxinstalledfonts -q

4.2.3 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( )

1. Siehe developer.apple.com/fonts/OSXTools.html

88 Kapitel 4: Textausgabe
ü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 mit Text-
ausgabeoperatoren 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 fehlen-
de Glyphen 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.2 Fontformate im Detail 89

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.6, »Ressourcenkonfiguration und Dateisuche«, Seite 54) oder dyna-
misch über PDF_set_parameter( ) und die Ressourcenkategorie FontOutline konfigu-
riert wurden.
> Fonts, die im Betriebssystem installiert sind und die wir Systemschriften (host fonts)
nennen. Statt sich lange mit Font- und Konfigurationsdateien aufzuhalten, können
Sie die Schrift einfach im Betriebssystem installieren (sprich: ins entsprechende
Fonts-Verzeichnis kopieren) und schon kann PDFlib sie nutzen. Systemschriften sind
auf Mac-Systemen (nur TrueType- und OpenType-, aber keine PostScript-Fonts) und
auf Windows-Systemen verfügbar. Um die Suchreihenfolge festzulegen, lassen sie
sich über die UPR-Ressourcenkategorie HostFont explizit konfigurieren. Diese Mög-
lichkeit kann zum Beispiel genutzt werden, um bevorzugt Systemschriften statt der
integrierten Standardschriften zu verwenden.
> 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.5,
»Das PDFlib Virtual File System (PVF)«, Seite 53.)

Mögliche Probleme mit Windows-Schriften. Wir möchten Anwender auf ein potentiel-
les 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 selektiert, 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 Standardsicherheitsein-
stellungen, bei denen auf Fontdateien außerhalb des Windows-Fonts-Verzeichnisses
unter Umständen nicht zugegriffen werden kann. Lösung: entweder Sie kopieren die
Fontdateien ins Fonts-Verzeichnis oder Sie legen die originale Fontdatei in ein Verzeich-
nis, 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.

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", "");

90 Kapitel 4: Textausgabe
 Schriftsuche. Der an PDF_load_font( ) übergebene Name kann in ASCII, UTF-8 oder UTF-
16 kodiert sein. 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 UTF-8 oder UTF-16 verwendet werden.
> Wurde die Schrift (auch als möglicherweise lokalisierte) Systemschrift nicht gefun-
den oder ist sie nicht in UTF-8 oder UTF-16 kodiert, wird durch Hinzufügen verschie-
dener Namenserweiterungen nach einer passenden Fontdatei gesucht (siehe unten).
> Bei TTC-Schriften (TrueType Collection) kann der Name in ASCII, UTF-8 oder UTF-16
kodiert 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-
Dateinamenerweiterung besteht und sich in einem der in SearchPath festgelegten
Verzeichnisse 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

4.3 Schrifteinbettung und Schriftuntergruppen 91

 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

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. Es
gibt jedoch auch Situationen, in denen PDFlib eine Schrift unabhängig von der Option
embedding auf jeden Fall einbettet (siehe unten).
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 Metrikdatei erforderlich? Fontdatei erforderlich?
Eine der 14 Standardschriften nein nein1
TrueType- oder OpenType-Fonts, die auf dem Mac oder nein nein
TrueType-, OpenType- oder PostScript-Font, die unter
Windows installiert ist (Systemschrift)
PostScript-Nichtstandardschrift PFM oder AFM PFB oder PFA (nur
bei
Schrifteinbettung)
TrueType-Fonts nein TTF, TTE
OpenType-Fonts mit TrueType- oder PS-Zeichenbeschrei- nein TTF, OTF
bungen, auch CJK-TrueType- oder -OpenType-Fonts
Standard-CJK-Fonts2 nein nein
1. Zeichenbeschreibungen können zur Einbettung bereitgestellt werden.

92 Kapitel 4: Textausgabe
 2. Informationen über CJK-Fonts finden Sie in Abschnitt 4.7, »Chinesischer, japanischer und koreanischer Text«, Seite 116.

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

1. Genauer gesagt: wenn das Flag fsType in der OS/2-Tabelle der Schrift den Wert 2 hat.

4.3 Schrifteinbettung und Schriftuntergruppen 93

 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.
> 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-
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.

94 Kapitel 4: Textausgabe
 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 macroman-Zeichensatz. 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_euro entspricht macroman mit der Ausnahme, dass sich an Position 219 =
0xDB das Euro-Zeichen statt des Währungssymbols befindet. Außerdem sind in
macroman_euro und macroman weder das Apple-Zeichen noch die mathematischen
Symbole vorhanden, die im Mac-OS-Zeichensatz definiert sind. Diese finden sich im Zei-
chensatz macroman_apple, die dazu erforderlichen Glyphen sind aber nur in wenigen
Schriften vorhanden.

Der Zeichensatz host. Der Zeichensatz host spielt eine Sonderrolle, da es sich um kei-
nen bestimmten Zeichensatz handelt. Je nach aktueller Plattform wird er auf einen spe-
ziellen 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. Für Textfonts wird mit dem Schlüsselwort auto als Wert für den Parame-
ter encoding folgt ein plattform- und umgebungsspezifischer 8-Bit-Zeichensatz festge-
legt:
> unter Windows: die aktuelle Codepage des Systems (Einzelheiten siehe unten)
> unter Unix und Mac OS X: iso8859-1
> auf Mac OS Classic: macroman
> auf IBM eServer iSeries: Zeichensatz des aktuellen Jobs (IBMCCSID000000000000)
> auf IBM eServer zSeries: ebcdic (=Codepage 1047)

4.4 Zeichensätze 95
 Tabelle 4.2 Verfügbarkeit von Glyphen für vordefinierte Zeichensätze in verschiedenen Schriftkategorien;
manche Sprachen sind mit Acrobat-Standardschriften nicht darstellbar.

Standardschriften

»Big Fonts«5
Acrobat 4/51
PS Level 1/2,

PostScript 3
Acrobat 62

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 ja ja ja
euro
macroman_ Wie macroman_euro, aber mit zusätzlichen – – – ja ja
apple mathematischen Symbolen
ebcdic EBCDIC-Codepage 1047 ja ja ja ja ja
ebcdic_37 EBCDIC Codepage 037 yes yes yes yes yes
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

96 Kapitel 4: Textausgabe
Tabelle 4.2 Verfügbarkeit von Glyphen für vordefinierte Zeichensätze in verschiedenen Schriftkategorien;
manche Sprachen sind mit Acrobat-Standardschriften nicht darstellbar.

Standardschriften

»Big Fonts«5
Acrobat 4/51
PS Level 1/2,

PostScript 3
Acrobat 62

Pro Fonts4
OpenType

TrueType
Fonts3
Codepage Unterstützte Sprachen

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

Für 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 120):
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", "");

4.4 Zeichensätze 97
 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.6, »Ressourcenkonfiguration und Dateisuche«, Seite 54) 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-

98 Kapitel 4: Textausgabe
 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
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.

1. Die AGL kann unter partners.adobe.com/asn/tech/type/glyphlist.txt abgerufen werden.

4.4 Zeichensätze 99
 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, der in PDF unverändert vorhanden ist,
enthält kein Eurozeichen. Apple modifizierte diesen Zeichensatz und ersetzte an Po-
sition 0xDB (hexadezimal) oder 219 (dezimal) das alte Währungszeichen mit dem Eu-

100 Kapitel 4: Textausgabe

 rozeichen. Um den modifizierten Mac-Zeichensatz zu verwenden, wählen Sie
macroman_euro 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) oder 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.4 Zeichensätze 101

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.
> 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 95).

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

102 Kapitel 4: Textausgabe

 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)

4.5 Unicode-Unterstützung 103

 > 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 238, sowie Abschnitt 8.3.5, »Mehrzeilige Textausgabe mit
Textflüssen«, Seite 246, 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 302.
> 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.

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

104 Kapitel 4: Textausgabe

 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 Seitenbeschreibungen am
einfachsten 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
> C++
> Cobol
> Perl
> PHP
> Python
> RPG

Unicode-Text kann in diesen Sprachen zwar verwendet werden, die Behandlung der ver-
schiedenen 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. Die
Länge der UTF-16-Strings ist 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, die String-Objekte nicht direkt unterstützen (Cobol, C und
RPG), ist die Länge der UTF-16-Strings in einem eigenen Längenparameter zu überge-
ben.
> Name-Strings: werden fast wie Strings für Seitenbeschreibungen interpretiert, es wird
aber der Parameter length ausgewertet sowie das Vorhandensein eines BOM am
Stringanfang. In C wird von einem String im Format UTF-16 ausgegangen, wenn der
Parameter length von 0 verschieden ist. Andernfalls (d.h. wenn der Parameter length

4.5 Unicode-Unterstützung 105

 gleich 0 ist, die Funktion keine Angabe liefert oder eine andere Sprache als C verwen-
det wird), wird vom Format UTF-8 ausgegangen, sofern der String mit einem UTF-8-
BOM beginnt, bzw. vom Format EBCDIC UTF-8, wenn der Strings mit einem EBCDIC
UTF-8 BOM beginnt, bzw. von host, wenn kein BOM vorhanden ist (oder ebcdic auf EB-
CDIC-Systemen).

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 die Option 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 mittels winansi (bzw. ebcdic auf EBCDIC-Sys-
temen) 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.
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.

106 Kapitel 4: Textausgabe

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 95). 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-

4.5 Unicode-Unterstützung 107

 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:
&#173; weiches Trennzeichen (soft hyphen)
&#xAD; weiches Trennzeichen (soft hyphen)
&shy; weiches Trennzeichen (soft hyphen)
&#229; Buchstabe a mit kleinem Kreis darüber (dezimal)
&#xE5; Buchstabe a mit kleinem Kreis darüber (hexadezimal, kleines x)
&#Xe5; Buchstabe a mit kleinem Kreis darüber (hexadezimal, großes X)
&#x20AC; Eurozeichen (hexadezimal)
&#8364; Eurozeichen (dezimal)
&euro; Eurozeichen (Entity-Name)
&lt; ’kleiner’-Zeichen
&gt; ’größer’-Zeichen
&amp; kaufmännisches ’und’-Zeichen (ampersand)
&Alpha; 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.
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");

1. Siehe www.w3.org/TR/REC-html40/charset.html#h-5.3

108 Kapitel 4: Textausgabe

 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, "charref", "true");
PDF_set_parameter(p, "textformat", "bytes");
font = PDF_load_font(p, "Helvetica", 0, "unicode", "");
PDF_setfont(p, font, 24);
PDF_show_xy(p, "Price: 500&euro;", 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 Absatzende; die Funktion PDF_fit_textflow( ) 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.
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:

4.5 Unicode-Unterstützung 109

 PDF_set_parameter(p, "charref", "true");

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, "charref", "true");
PDF_set_parameter(p, "textformat", "bytes");
font = PDF_load_font(p, "Helvetica", 0, "unicode", "");
PDF_setfont(p, font, 24);
PDF_show_xy(p, "Preis: 500&euro;", 50, 500);

Character-Referenzen werden in Optionslisten nicht ersetzt, aber in Optionen mit dem

Datentyp Unichar erkannt (siehe Abschnitt 3.1.4, »Optionslisten«, Seite 51). Diese Erken-
nung erfolgt immer und wird nicht durch den Parameter charref gesteuert.

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 200). 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.

110 Kapitel 4: Textausgabe

 > 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.5 Unicode-Unterstützung 111

 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 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 Versalhöhe, Oberlänge und Unterlänge werden als Bruchteil der Schriftgröße ge-
messen und müssen deshalb vor der Verwendung mit der nötigen Schriftgröße multi-
pliziert werden.
Die Werte für Versalhöhe, Oberlänge und Unterlänge für eine bestimmte Schrift
können wie folgt von PDFlib 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;

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.

Abb. 4.2 Font- und Zeichenmetrik

Oberlänge
Versalhöhe (ascender)
(capheight)
Schriftgröße

Grundlinie
Unterlänge (descender)

112 Kapitel 4: Textausgabe

 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.
PDFlib unterstützt Kerning für PostScript-, TrueType- und OpenType-Fonts. Es gibt
in PDFlib zwei Möglichkeiten zur Steuerung von 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.

Abb. 4.3 Kerning

Kein Kerning

Kerning

Zeichenversatz beim Kerning

4.6 Textmetrik und Textvarianten 113

 > 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. Beachten Sie jedoch, dass die Kombination aus horizontaler
Skalierung und Kerning erst ab Acrobat 4.05 funktioniert.
In PDFlib gibt es keine Beschränkung für die Anzahl der Kerning-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.

Note Künstliche Schriftstile sollten nur für die Standard-CJK-Schriften zum Einsatz kommen. Beach-
ten Sie zudem, dass künstliche Schriftstile von anderen PDF-Viewern als Adobe Acrobat unter
Umstä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 91).
> 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-

114 Kapitel 4: Textausgabe

 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.17 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.

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.6 Textmetrik und Textvarianten 115

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 auf der
Acrobat-CD oder 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:
> Die CJK-Unterstützung von Acrobat basiert auf CID-Fonts. Diese können jedoch nicht
auf allen PostScript-Druckern ausgegeben werden. Native Unterstützung für CID-
Fonts wurde erst in PostScript Version 2015 integriert. Das bedeutet, dass Drucker
mit PostScript Level 1 und frühem Level 2 nicht darüber verfügen. Bei frühen Level-2-
Geräten kann man aber davon ausgehen, dass der Druckertreiber passende Kompati-
bilitätsroutinen an Level-2-Drucker vor Version 2015 lädt.
> Aufgrund der immensen Anzahl von Zeichen benötigen CID-Fonts enormen Dru-
ckerspeicher, wenn keine Schriftuntergruppen gebildet wurden. Die Dateigröße für
einen vollständigen CJK-Font beträgt in der Regel 5 bis 10 MB. Nicht alle Drucker ver-
fügen über ausreichend Speicher zur Ausgabe solcher Schriften. Bei unseren Tests
mussten wir zum Beispiel einen Level-3-Laserdrucker von 16 MB auf 48 MB RAM auf-
rüsten, um PDF-Dokumente mit CID-Fonts zuverlässig ausdrucken zu können.
> 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).

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

116 Kapitel 4: Textausgabe

 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-
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 von Acrobat umfassen keine kursiven oder fetten Fonts. Solche Fonts
lassen sich mit künstlichen Schriftstilen simulieren (siehe Abschnitt 4.6.3, »Textvarianten«, Sei-
te 114).

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 sich in Tabelle 4.7.

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.

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.

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«).

4.7 Chinesischer, japanischer und koreanischer Text 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 1.4 oder höher verfügbar.
5. Nur bei der Generierung von PDF 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.

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

118 Kapitel 4: Textausgabe

Tabelle 4.7 Vordefinierte CMaps für japanisch/chinesisch/koreanisch (aus der »PDF Reference«)
Sprache CMap-Name Zeichensatz und Textformat
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
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

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
102), 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.

4.7 Chinesischer, japanischer und koreanischer Text 119

 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 dazu aber Abschnitt 4.7.4,
»Erzwingen äquidistanter Schrift«, Seite 122)
> 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", "");
PDF_setfont(p, font, 24);
PDF_set_text_pos(p, 50, 500);
/* 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.

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.

120 Kapitel 4: Textausgabe

 > 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 90.
> Proportionale lateinische Zeichen sowie Zeichen halber Breite werden bei benutzer-
spezifischen CJK-Fonts vollständig unterstützt.
> Name für japanische Systemschriften können an PDF_load_font( ) in UTF-8 mit ein-
leitendem BOM oder UCS-2 übergeben werden.

Hinweis Original Composite Fonts (OCF) und reine PostScript-CID-Fonts werden nicht unterstützt.
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.2, »TrueType- und
OpenType-Fonts«, Seite 86

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_setfont(p, font, 24);

PDF_set_text_pos(p, 50, 500);

PDF_show2(p, "\x82\xA9\x82\xC8\x8A\xBF\x8E\x9A", 8);

4.7 Chinesischer, japanischer und koreanischer Text 121

 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 90, 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", "");

PDF_setfont(p, font, 24);

PDF_set_text_pos(p, 50, 500);

/* 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);

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 90, 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.7.4 Erzwingen äquidistanter Schrift

Einige Anwendungen können nicht mit proportionalen CJK-Schriften umgehen und be-
rechnen die Textbreite anhand einer konstanten Zeichenbreite und der Zeichenanzahl.
PDFlib kann angewiesen werden, äquidistante Zeichen 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 ansprechende Ergebnisse:
font = PDF_load_font(p, "KozMinPro-Regular-Acro", 0, "UniJIS-UCS2-H", "monospace 1000");

122 Kapitel 4: Textausgabe

Die Option monospace sollte nur bei Standard-CJK-Schriften zum Einsatz kommen.

4.7 Chinesischer, japanischer und koreanischer Text 123

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.18. 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 155, 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
124 Kapitel 4: Textausgabe
 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 125
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

126 Kapitel 4: Textausgabe

4.9 Mehrzeilige Textflüsse
PDFlib bietet unter der Bezeichung Textfluss (textflow) die Möglichkeit, nicht nur einzel-
ne Zeilen, sondern einen beliebig langen zusammenhängenden Text auszugeben. Der
Text kann sich über beliebig viele Zeilen oder Seiten erstrecken und anhand vieler Opti-
onen formatiert werden. Zeicheneigenschaften wie Schriftart, Schriftgröße oder Farbe
sind auf beliebige Textabschnitte anwendbar. Textflusseigenschaften können einge-
stellt werden, zum Beispiel Blocksatz oder Flattersatz, Einzüge und Tabulatorabstände.
Trennstellen, die im Text durch weiche Trennzeichen (soft hyphen) gekennzeichnet sind,
werden berücksichtigt. Abbildung 4.11 und Abbildung 4.12 zeigen, wie verschiedene Ele-
mente einer Rechnung als Textflüsse platziert ausgegeben werden. Die einzelnen Optio-
nen 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
[email protected]
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

4.9 Mehrzeilige Textflüsse 127

 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 erfordlich:
> 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.22.
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 124, 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);

128 Kapitel 4: Textausgabe

 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, "");
PDF_delete_textflow(p, textflow);

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);
while (1)
{
PDF_begin_page_ext(p, pagewidth, pageheight, "");
result = PDF_fit_textflow(p, textflow, left_x, left_y, right_x, right_y, "");
PDF_end_page_ext(p, "");
if (strcmp(result, "_boxfull"))
break;
}
PDF_delete_textflow(p, textflow);

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

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.

4.9 Mehrzeilige Textflüsse 129

 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.

links und rechts mit einem Einzug vom Seitenrand versehen, und zwar links um 15 und
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 */

textflow = PDF_create_textflow(p, text, 0, optlist);
PDF_fit_textflow(p, textflow, left_x, left_y, right_x, right_y, "");
PDF_delete_textflow(p, textflow);

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

130 Kapitel 4: Textausgabe

 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

revolutionary new developments of the traditional common paper planes.

<parindent=20>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 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.22). 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}

4.9 Mehrzeilige Textflüsse 131

 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
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 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.

132 Kapitel 4: Textausgabe

 hortabmethod ruler
tabalignment left right right right
ruler 30 150 250 350

ITEM DESCRIPTION QUANTITY PRICE AMOUNT

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

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):
/* Stelle Optionsliste zusammen */
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);
PDF_fit_textflow(p, textflow, left_x, left_y, right_x, right_y, "");
PDF_delete_textflow(p, textflow);

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.

4.9 Mehrzeilige Textflüsse 133

 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.

1. Long Distance Glider: With this paper rocket you can send all your Abb. 4.18
Nummerierte Liste
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.

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.

134 Kapitel 4: Textausgabe

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 enfernt 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

4.9 Mehrzeilige Textflüsse 135

 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:
/* Stelle Optionsliste zusammen */
strcpy(optlist, "fontname=Helvetica fontsize=9 encoding=winansi alignment=justify ");
strcat(optlist, "charmapping {CRLF {space -1}}");
/* Platziere Textfluss in Fitbox */
textflow = PDF_create_textflow(p, text, 0, optlist);
PDF_fit_textflow(p, textflow, left_x, left_y, right_x, right_y, "");
PDF_delete_textflow(p, textflow);

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
110) 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.22 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.

136 Kapitel 4: Textausgabe

 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.

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.7 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.

4.9 Mehrzeilige Textflüsse 137

 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 mit dem Unterschied, dass lange Zeilen am rechten Rand der
Fitbox (abzüglich der Option rightindent) abgeschnitten 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
Prozentsatz. 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
eingefü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)
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.

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 be-
rücksichtigt.

138 Kapitel 4: Textausgabe

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

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 imText, 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 umso 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, müssen Sie
entweder das Einfügen expliziter »weicher« Trennzeichen erwägen oder die Blocksatz-
Optionen verändern.

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:

4.9 Mehrzeilige Textflüsse 139

 Our paper planes
are the ideal way of
passing the time.We
offer revolutionary
brand new developments Stauchen der Zeile (Methode shrink, Option shrinklimit)
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. All our
models are folded
from one paper
sheet. They are
exclusively folded without
using any adhesive. Abb. 4.24
Stauchung auf bis zu 50% Breite

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

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

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.

140 Kapitel 4: Textausgabe

 Our paper planes
are the ideal way of
passing the time. We
offer revolutionary
brand new develop-
ments of the traditional
common paper planes.
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 %

4.9.8 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 der Verwendung von 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.

4.9 Mehrzeilige Textflüsse 141

142 Kapitel 4: Textausgabe
 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, "jpeg", "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 155.

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-

5.1 Import von Rasterbildern 143

 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, "");
PDF_close_image(p, image);

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. Wenn mög-
lich, reicht PDFlib die komprimierten Bilddaten unverändert an die PDF-Ausgabe wei-
ter, da PDF intern die meisten in Rasterbildformaten verwendeten Kompressionsver-
fahren unterstützt. Diese Technik (in den folgenden Beschreibungen Pass-Through-
Modus genannt) bewirkt einen äußerst schnellen Bildimport, da die Dekompression
und die darauf folgende erneute Kompression der Bilddaten entfallen. In diesem Mo-
dus kann PDFlib die Integrität der komprimierten Bilddaten nicht überprüfen. Unvoll-
stä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).
Wenn eine Rasterbilddatei nicht erfolgreich importiert werden konnte, gibt PDF_
load_image( ) standardmäßig einen Fehlercode zurück. Möchten Sie Einzelheiten über
die Ursachen erfahren, dann setzen Sie die Option imagewarning von PDF_load_image( )
auf true (siehe Abschnitt 8.6, »Rasterbild- und Template-Funktionen«, Seite 280). Alter-
nativ dazu können Sie den Parameter imagewarning global setzen:
PDF_set_parameter(p, "imagewarning", "true"); /* Warnungen aktivieren */

Wird durch PDF_load_image( ) nun eine Exception ausgelöst, so erhalten Sie eine detail-
lierte Fehlerbeschreibung in der entsprechenden Exception-Meldung.

144 Kapitel 5: Import und Platzierung von Objekten

 PNG-Bilder. PDFlib unterstützt alle Varianten von PNG-Bildern (Portable Network Gra-
phics). PNG-Bilder werden meistens im Pass-Through-Modus verarbeitet. PNG-Bilder,
die das Zeilensprungverfahren (Interlacing) nutzen oder einen Alphakanal enthalten
(der in jedem Fall verlorengeht, siehe unten), müssen dekomprimiert werden, was be-
deutend länger dauert als der Pass-Through-Modus. Enthält ein PNG-Bild Transparenz-
informationen, so bleibt diese im generierten PDF erhalten (siehe Abschnitt 5.1.3, »Bild-
masken und Transparenz«, Seite 146). Alphakanäle werden von PDFlib nicht
unterstützt.

JPEG-Bilder. JPEG-Bilder werden immer im Pass-Through-Modus verarbeitet. PDFlib

unterstützt folgende Kompressionsmodi von JPEG:
> 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.

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 149)
> 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 wird sie aber auf 8 Bit reduziert (ZIP-Kompression mit »Little Endian«-Byte-
reihenfolge (Intel) oder indizierte 16-Bit-Bilder).

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

1. Siehe www.libtiff.org

5.1 Import von Rasterbildern 145

 Streifen (»single-strip«) umwandeln. Das Tool ImageMagick1 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.

BMP-Bilder. BMP-Bilder können nicht im Pass-Through-Modus bearbeitet werden.

PDFlib unterstützt folgende Varianten von BMP-Bildern:
> BMP-Versionen 2 und 3
> Farbtiefe von 1, 4 und 8 Bits pro Komponente, einschließlich 3 x 8 = 24 Bit TrueColor
> 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.

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

1. Siehe www.imagemagick.org

146 Kapitel 5: Import und Platzierung von Objekten

 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.

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.

Hinweis Ein Fehler in Acrobat 5 verhindert den Einsatz von transparenten Schwarzweißbildern. Statt
des Bildes erscheint die Fehlermeldung »Beim Verarbeiten einer Seite ist ein Fehler aufgetreten.
Es ist ein Grafikfehler aufgetreten«. Acrobat 6 hat diesen Fehler nicht. Zur Abhilfe können Sie
die Transparenz entfernen oder das Bild mit 4 oder mehr Bit pro Pixel speichern.

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 befindet, wird der entsprechende Be-
reich des maskierten Bildes gezeichnet, während der Wert 1 den Hintergrund durch-
scheinen lässt. Sind mehr als 1 Bit pro Pixel vorhanden, mischen die zwischenliegenden
Werte das Vordergrundbild mit dem Hintergrund und bewirken so einen Transparenz-
effekt. 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.

5.1 Import von Rasterbildern 147

 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 0-Bits
als transparent behandelt werden. Das heißt unabhängig vom bereits auf der Seite vor-
handenen Inhalt scheint dieser durch die transparenten Bestandteile des Bildes. 1-Bit-
Pixel 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 dass die 0-Bits transparent
werden, müssen Sie die Funktion zum Einfärben verwenden (siehe Abschnitt 5.1.4, »Ein-
färben von Bildern«, Seite 149).

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");

148 Kapitel 5: Import und Platzierung von Objekten

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 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_close_image(p, image);
PDF_end_page(p);
}

5.1 Import von Rasterbildern 149

 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.

150 Kapitel 5: Import und Platzierung von Objekten

 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-

5.2 Import von PDF-Seiten mit PDI (PDF Import Library) 151
 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 65).
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 155.

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-

152 Kapitel 5: Import und Platzierung von Objekten

 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 63).
> 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.44).
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.43
und Tabelle 8.44 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 155, 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

5.2 Import von PDF-Seiten mit PDI (PDF Import Library) 153
 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.

154 Kapitel 5: Import und Platzierung von Objekten

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.39.
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

5.3 Platzieren von Bildern und importierten PDF-Seiten 155

 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.

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.

Abb. 5.3 Abb. 5.4

Platzierung mit Platzierung
Ausrichtung mit Drehung

156 Kapitel 5: Import und Platzierung von Objekten

 > 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");

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.

Abb. 5.5
Option orientate
Abb. 5.6
Option rotate

5.3 Platzieren von Bildern und importierten PDF-Seiten 157

 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).

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");

Abb. 5.7
Anpassen der Seitengröße. Von links nach
rechts: exakt, vergrößert, verkleinert.

158 Kapitel 5: Import und Platzierung von Objekten

 Abb. 5.9
Abb. 5.8 Beschneiden eines
Einpassen eines Objekts beim
Objekts in die Box Einpassen in die Box

Abb. 5.10
Einpassen eines
Objekts in die Seite

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");

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.

5.3 Platzieren von Bildern und importierten PDF-Seiten 159

160 Kapitel 5: Import und Platzierung von Objekten
 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 Text, Rasterbildern oder PDF-Vektorgrafik angereichert werden, die aus externen
Quellen bezogen werden. Damit lassen sich problemlos Anwendungen implementie-
ren, die individualisierte PDF-Dokumente erfordern, zum Beispiel:
> 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 PDFlib-Block-Plugin für Adobe Acrobat erforderlich, um Blöcke in PDF-Templates anzu-
legen.

6.1 Installation des PDFlib-Block-Plugins

Das Block-Plugin sowie das Plugin zur Konvertierung von Formularfeldern funktionie-
ren nur mit der Vollversion von Acrobat 5, mit Acrobat 6 Standard und mit Acrobat 6
Professional. Mit Acrobat 6 Elements und Acrobat Reader bzw. Adobe Reader sind sie
nicht einsetzbar.

Hinweis Falls das PDFlib-Block-Plugin nicht zu funktionieren scheint, stellen Sie sicher, dass unter Bear-
beiten, Grundeinstellungen..., [Allgemein...], Programmstart (Acrobat 6) bzw. Bearbeiten,
Grundeinstellungen, Allgemein..., Optionen (Acrobat 5) das Kontrollkästchen »Nur zertifizierte
Zusatzmodule verwenden« deaktiviert ist.

Installation der PDFlib-Plugins für Acrobat unter Windows. Zur Installation des PDF-
lib-Block-Plugins sowie des Plugins zur Konvertierung von PDF-Formularfeldern in
Acrobat 5 oder 6 kopieren Sie die Plugin-Dateien in ein Unterverzeichnis des Acrobat-
Plugin-Verzeichnisses. Dies wird von der Installationsroutine des Plugins automatisch
durchgeführt, kann aber auch manuell erfolgen. Unter Windows heißen die Dateien
Block.api und AcroFormConversion.api, und das Verzeichnis für die PDFlib-Plugins lautet
üblicherweise in etwa:
C:\Programme\Adobe\Acrobat 6.0\Acrobat\Plug_ins\PDFlib

Installation der PDFlib-Block-Plugins für Acrobat auf dem Mac. Bei Acrobat 6 ist der
Plugin-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):
> Extrahieren Sie die Plugin-Dateien durch Doppelklick auf das Laufwerkssymbol.
> 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 6.0 Professional

6.1 Installation des PDFlib-Block-Plugins 161

 > Nach einem Einfachklick auf das Symbol selektieren Sie Datei, Info. Ein Fenster er-
scheint.
> Klicken Sie auf das Dreieck neben Plug-ins.
> Klicken Sie auf Hinzufügen... und selektieren Sie den Ordner PDFlib, der sich in dem
Ordner befindet, der im ersten Schritt angelegt wurde. Beachten Sie, dass der Ordner
PDFlib nicht sofort in der Plugin-Liste erscheint. Er wird erst beim nächsten Öffnen
des Info-Fensters angezeigt.

Zur Installation der Plugins für Acrobat 5 doppelklicken Sie auf das Laufwerkssymbol.
Ziehen Sie den PDFlib-Ordner auf den Acrobat-5-Plugin-Ordner, der üblicherweise wie
folgt lautet:
/Programme/Adobe Acrobat 5.0/Plug-Ins

162 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 PDFlib-Block-Plugin für Acrobat die variablen Datenblöcke und ihre Eigen-
schaften 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);
PDF_end_page_ext(p, "");

6.2 Überblick über das Blockkonzept von PDFlib 163

6.2.2 Blockeigenschaften
Das Verhalten von Blöcken lässt sich über die Blockeigenschaften steuern. Diese werden
einem Block mit dem PDFlib-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:

164 Kapitel 6: Variable Daten und Blöcke

 > 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-

6.2 Überblick über das Blockkonzept von PDFlib 165

 der automatisch in Blöcke konvertiert (siehe Abschnitt 6.3.4, »Konvertieren von PDF-
Formularfeldern in PDFlib-Blöcke«, Seite 172).
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 nein linksbündig, rechtsbündig, mittig, Blocksatz;
Fontwechsel; verschiedene Formatierungs-
algorithmen und Steuermöglichkeiten
kombiniertes Ergebnis ist Bestand- nein ja
teil der PDF-Seitenbeschreibung
Benutzer können kombinierte ja nein
Feldinhalte editieren
Funktionalität erweiterbar nein ja (selbstdefinierte Blockeigenschaften)
Farbunterstützung RGB Graustufen, RGB, CMYK, Schmuckfarbe, Lab
PDF/X-Kompatibilität nein ja (sowohl Template mit Blöcken als auch kombi-
niertes Ergebnis)
Eigenschaften von Text und Grafik nein ja
können beim Füllen geändert
werden

166 Kapitel 6: Variable Daten und Blöcke

 6.3 Anlegen von PDFlib-Blöcken
6.3.1 Interaktive Blockerzeugung mit dem PDFlib-Block-Plugin
Einsatz des PDFlib-Blockwerkzeugs. Das PDFlib-Block-Plugin zur Erzeugung von
PDFlib-Blöcken ist dem Acrobat-Formularwerkzeug recht ähnlich. Solange das Block-
werkzeug ausgewählt ist, sind alle Blöcke auf der Seite sichtbar. Wenn Sie ein anderes
Acrobat-Werkzeug 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. In Acrobat 6 müssen Sie sicherstellen, dass unter
Bearbeiten, Grundeinstellungen..., [Allgemein...], Allgemein das Kontrollkästchen
»Zugriffstasten zum Zugreifen auf Werkzeuge verwenden« aktiviert ist, was standardmä-
ßig nicht der Fall ist.

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 170). Der Blockname wird automatisch angelegt, kann aber nachträglich ge-
ändert werden. Er muss innerhalb einer Seite eindeutig sein. Auf der Registerkarte
Allgemein 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 wer-
den nur bei Auswahl des entsprechenden Blocktyps eingeblendet.

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

6.3 Anlegen von PDFlib-Blöcken 167

 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
Seite. Die Koordinaten werden in der Einheit angezeigt, die in Acrobat gerade eingestellt
ist. Zum Ändern der Einheit wählen Sie Bearbeiten, Grundeinstellungen..., [Allgemein...],
Einheiten und Hilfslinien(Acrobat 6) bzw. Bearbeiten, Grundeinstellungen, Allgemein...,
Anzeigen, Seiteneinheiten (Acrobat 5) und selektieren Punkt, Millimeter, Zoll, Pica oder Ze-
ntimeter (die beiden letzten Einheiten sind nur in Acrobat 6 verfügbar). Sie können
auch Anzeige, Navigationsregisterkarten, Info (Acrobat 6) bzw. Fenster, Info (Acrobat 5),
wählen und eine Einheit aus dem Menü Optionen (Acrobat 6) bzw. Info (Acrobat 5) selek-
tieren. 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,
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.

168 Kapitel 6: Variable Daten und Blöcke

 Abb. 6.1
Einstellung der Blockeigenschaften; die
Registerkarte Textflow erscheint nur bei
textflow=true; die Registerkarte Tabs ist
nur bei hortabmethod=ruler sichtbar

Automatische Erkennung von Fonteigenschaften. Das PDFlib-Block-Plugin ist in der

Lage, den Font zu analysieren, der sich an der Stelle befindet, an der der Block positio-
niert wird. Darauf aufbauend kann es die folgenden entsprechenden Blockeigenschaf-
ten automatisch 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 können jedoch folgende Probleme
auftreten:
> PDF/X-1:2001, PDF/X-1a:2001 und PDF/X-3:2002 basieren auf PDF 1.3, so dass keine
Acrobat-5-Dateien unterstützt werden;
> Das PDFlib-Block-Plugin setzt Acrobat 5 oder höher voraus.

Der Weg aus der Sackgasse hängt von Ihrer Acrobat-Version ab:
> Acrobat 6: Sie können die Datei in Acrobat als PDF 1.3 speichern, indem Sie Datei,
Dateigröße verringern... und dann Acrobat 4.0 und höher wählen.

6.3 Anlegen von PDFlib-Blöcken 169

 > Acrobat 5: Um die generierte PDF-Ausgabe mit Blöcken in der PDF/X-kompatiblen
PDF-Version 1.3 zu speichern, verwenden Sie ein weiteres Plugin, nämlich
pdfSaveAsPDF1.3 von callas software. Demoversionen mit vollem Funktionsumfang
sind auf der Web-Site von callas erhältlich1.

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ü erscheint der Dialog PDFlib
Blockeigenschaften, in dem Sie die Eigenschaften des selektierten Blocks einstellen kön-
nen (siehe Abbildung 6.1). Wie in Abschnitt 6.4, »Standardeigenschaften zur automati-
schen Verarbeitung«, Seite 175, beschrieben, gibt es mehrere Arten von Eigenschaften:
> 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 aktuellen Blocktyp entspre-
chende Registerkarte 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
einen Wert aus der zugehörenden Dropdown-Liste (z.B. bei fitmethod) oder selektieren
mit dem »...«-Button rechts eine Farbe, Schrift oder Datei (z.B. bei backgroundcolor). Bei
der Eigenschaft fontname können Sie einen Schriftnamen eingeben oder die Schrift mit
dem »...«-Button aus einer Liste mit allen im System installierten Schriften auswählen.
Unabhängig von der Auswahlmethode muss der gewählte Font auf dem System vor-
handen sein, auf dem die Blöcke 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-

1. Siehe www.callassoftware.com

170 Kapitel 6: Variable Daten und Blöcke

 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 175, beschreibt, welche
Eigenschaften mehreren Blöcken gemeinsam sein können. Selbstdefinierte Eigenschaf-
ten 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 6) bzw. Dokument, Seiten ersetzen... (Acro-
bat 5).

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.

6.3 Anlegen von PDFlib-Blöcken 171

 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

172 Kapitel 6: Variable Daten und Blöcke

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, textcolor und 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={0 50}, Zentriert={50 50}, Rechts={100,
50}
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

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.

6.3 Anlegen von PDFlib-Blöcken 173

 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.

174 Kapitel 6: Variable Daten und Blöcke

6.4 Standardeigenschaften zur automatischen
Verarbeitung
PDFlib bietet einige allgemeine Eigenschaften, die jedem Blocktyp zugeordnet werden
können. Daneben gibt es für den jeweiligen Blocktyp Text, Image und PDF spezifische Ei-
genschaften. Manche Eigenschaften können gemeinsam genutzt werden, das heißt,
dass sie mit dem Block-Plugin mehreren Blöcken auf einmal zugeordnet werden kön-
nen.
Eigenschaften unterstützen dieselben Datentypen wie Optionslisten (siehe Ab-
schnitt 3.1.4, »Optionslisten«, Seite 51) 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.

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 68) 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 PDFlib-Block-Plugin automatisch generiert. Tabelle 6.3 gibt eine Übersicht
über die allgemeinen Eigenschaften.

Tabelle 6.3 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.

6.4 Standardeigenschaften zur automatischen Verarbeitung 175

 Tabelle 6.3 Allgemeine Blockeigenschaften
Schlüsselwort Typ Mögliche Werte und Erklärung
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.18 und Tabelle 8.39 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.
orientate1 Schlüsselwort (Gemeinsam nutzbar) Legt fest, in welcher Ausrichtung der Inhalt platziert wird
(siehe Tabelle 8.39). Mögliche Werte sind north, east, south, west. Standardwert:
north.

176 Kapitel 6: Variable Daten und Blöcke

 Tabelle 6.3 Allgemeine Blockeigenschaften
Schlüsselwort Typ Mögliche Werte und Erklärung
position1 Float-Liste (Gemeinsam nutzbar) Einer oder zwei Werte, die die Position des Referenzpunkts
innerhalb des Inhalts festlegen (siehe Tabelle 8.18 für text und Tabelle 8.39 für
image/PDF). Standardwert: 0.
rotate Float (Gemeinsam nutzbar) Drehwinkel in Grad, um den der Block gegen den
Uhrzeigersinn 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. Der gewünsche Zeichensatz für den Text (Encoding) muss beim Fül-
len des Blocks als Option für PDF_fill_textblock( ) angegeben werden, sofern nicht die Op-
tion font übergeben wurde.

Generelle Eigenschaften für Textblöcke. Textblöcke können aus einer oder mehreren
Zeilen bestehen. Tabelle 6.4 zeigt alle Eigenschaften, die sich generell auf beide Text-
blockarten anwenden lassen.

Tabelle 6.4 Textspezifische Blockeigenschaften

Schlüsselwort Typ Mögliche Werte und Erklärung
charspacing Float oder Zeichenabstand (siehe Tabelle 8.17). Prozentangaben beziehen sich auf fontsize.
Prozentwert Standardwert: 0
defaulttext String Text, der verwendet wird, wenn im Funktionsaufruf keiner angegeben wird1
fillcolor Color Füllfarbe des Texts. Standardwert: gray 0 (=schwarz)
fontname2 String Name der Schrift, so wie bei PDF_load_font( ) erforderlich
fontsize2 Float Schriftgröße in Punkt
fontstyle Schlüsselwort Schriftstil; mögliche Schlüsselwörter sind normal, bold, italic oder bolditalic (siehe
Tabelle 8.15)
horizscaling Float oder Horizontale Skalierung von Text (siehe Tabelle 8.17). Standardwert: 100.
Prozentwert
italicangle Float Neigungswinkel von kursivem Text in Grad (siehe Tabelle 8.17). Standardwert: 0
kerning Boolean Unterschneidung (siehe Tabelle 8.17). Standardwert: false
margin Float-Liste 1 oder 2 Float-Werte für die horizontale und vertikale Ausdehnung der Textbox
(siehe Tabelle 8.18). Standardwert: 0
monospace Integer Alle Glyphen des Fonts werden in äquidistanter Breite geschrieben (siehe Tabelle
1...2048 8.15). Standardwert: nicht vorhanden (es werden die Metrikdaten der Schrift
verwendet)
overline Boolean Modus für Überstreichen (siehe Tabelle 8.17). Standardwert: false
strikeout Boolean Modus für Durchstreichen (siehe Tabelle 8.17). Standardwert: false
strokecolor Color Farbe, in der Text gezeichnet wird. Standardwert: gray 0 (= schwarz)

6.4 Standardeigenschaften zur automatischen Verarbeitung 177

 Tabelle 6.4 Textspezifische Blockeigenschaften
Schlüsselwort Typ Mögliche Werte und Erklärung
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 allgemeinen Eigenschaften position und orientate werden
ignoriert. Neben den Standardeigenschaften für Text können alle
Textflow-spezifischen Eigenschaften festgelegt werden (siehe Tabelle
6.5).
textrendering Integer Darstellungsmodus für Text (siehe Tabelle 8.17). Standardwert: 0
textrise Float oder Modus für den vertikalen Textversatz (siehe Tabelle 8.17). Prozentwerte beziehen
Prozentwert sich auf fontsize. Standardwert: 0
underline Boolean Modus für Unterstreichen (siehe Tabelle 8.17). Standardwert: false
wordspacing Float Wortabstand (siehe Tabelle 8.17). Prozentwerte beziehen sich auf fontsize.
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 gleich true ist. Anhand der
text-spezifischen Eigenschaften wird die anfängliche Optionsliste zur Textflow-Verar-
beitung 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.5 gibt eine Übersicht.

Tabelle 6.5 Textfluss-spezifische Blockeigenschaften

Schlüsselwort Typ Mögliche Werte und Erklärung
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, Abstand zwischen dem oberen Rand der Fitbox und der Grundlinie der ersten
Prozentwert Textzeile. Angegeben wird er in Benutzerkoordinaten, als Prozentsatz der
oder Schriftgröße (der Größe der ersten in der Zeile auftretenden Schrift, wenn
Schlüsselwort 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 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.
Ist fixedleading=false, wird der größte Wert verwendet, der für Zeilenabstand,
Oberlänge und Versalhöhe in der ersten Zeile ermittelt wurde.

178 Kapitel 6: Variable Daten und Blöcke

Tabelle 6.5 Textfluss-spezifische Blockeigenschaften
Schlüsselwort Typ Mögliche Werte und Erklärung
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 fest-
method gelegte 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, (Wird ignoriert bei fitmethod=nofit) Der kleineste Abstand zwischen der
Prozentwert Grundline der letzten Textzeile und dem unteren Rand der Fitbox. Angegeben wird
oder er in Benutzerkoordinaten, als Prozentsatz der Schriftgröße (der ersten in der Zeile
Schlüsselwort auftretenden 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.
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.

6.4 Standardeigenschaften zur automatischen Verarbeitung 179

 Tabelle 6.5 Textfluss-spezifische Blockeigenschaften
Schlüsselwort Typ Mögliche Werte und Erklärung
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
fort. Füllt der Text die Fitbox nicht vollständig aus, bleibt Weißraum
ü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%.

180 Kapitel 6: Variable Daten und Blöcke

 Tabelle 6.5 Textfluss-spezifische Blockeigenschaften
Schlüsselwort Typ Mögliche Werte und Erklärung
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.6 gibt eine Übersicht.

Tabelle 6.6 Rasterbildspezifische Blockeigenschaften

Schlüsselwort Typ Mögliche Werte und Erklärung
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 Standardeigenschaften zur automatischen Verarbeitung 181

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.7 gibt eine Übersicht.

Tabelle 6.7 PDF-spezifische Blockeigenschaften

Schlüsselwort Typ Mögliche Werte und Erklärung
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.44). 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.8 gibt
eine Übersicht.

Table 6.8 Selbstdefinierte Blockeigenschaften

Schlüsselwort Typ Mögliche Werte und Erklärung
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

182 Kapitel 6: Variable Daten und Blöcke

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 Addressierung der Blockeigenschaft sind folgende
Ausdrücke gleichbedeutend, wobei davon ausgegangen wird, dass der Block mit der
Nummer <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.

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);

6.5 Abfragen von Blocknamen und -eigenschaften 183

 Namen für selbstdefinierte Eigenschaften. Zur Vermeidung von Namenskonflikten
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 firmenspezifi-
sches Präfix wird ein Internet-Domainname empfohlen. Die Eigenschaftsnamen 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 175, definiert) nicht mit selbstdefinierten Namen in
Konflikt geraten.

184 Kapitel 6: Variable Daten und Blöcke

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 Schlüssel /PDFlib, der als Wert wiederum ein
Dictionary mit Applikationsdaten enthält. Das Applikations-Dictionary enthält die bei-
den in Tabelle 6.9 aufgeführten Standardschlüssel.

Tabelle 6.9 Einträge in einem PDFlib-Applikations-Dictionary

Schlüssel Typ Wert
LastModified Datum (Erforderlich) Datum und Zeit der Erstellung oder letzten Änderung der Blöcke auf
der Seite.
Private Dictionary (Erfoderlich) Ein Blocklist-Dictionary (siehe Tabelle 6.10)

Eine Blockliste ist ein Dictionary mit allgemeinen Information zur Blockverarbeitung
sowie einer Liste aller Blöcke auf der Seite. Tabelle 6.10 enthält alle Schlüssel in einem
Blocklist-Dictionary.

Tabelle 6.10 Einträge in einem Blocklist-Dictionary

Schlüssel Typ Wert
Version Zahl (Erforderlich) Die Versionsnummer der Blockspezifikation, gemäß der die Datei
erstellt wurde. Dieses Dokument beschreibt Version 4 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.12). 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 Schlüssel 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 3.1.4, »Optionslisten«, Seite 51). Tabelle 6.11 zeigt, wie diese Typen auf
PDF-Datentypen abgebildet werden.

6.6 Spezifikation für PDFlib-Blöcke 185

 Tabelle 6.11 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.12

enthalten. Abhängig vom Wert des Schlüssels /Subtype dürfen nur Schlüssel aus einer
der Gruppen Text, Image oder PDF vorhanden sein (siehe Tabelle 6.3).

Tabelle 6.12 Einträge in einem Block-Dictionary

Schlüssel Typ Wert
Allgemeine Eigenschaften (Manche Schlüssel sind erforderlich) Allgemeine Blockeigenschaften gemäß
Tabelle 6.3
Text-Eigenschaften (Optional) Text- und textfluss-spezifische Blockeigenschaften gemäß Tabelle 6.4
und Tabelle 6.5
Image-Eigenschaften (Optional) Rasterbildspezifische Blockeigenschaften gemäß Tabelle 6.6
PDF-Eigenschaften (Optional) PDF-spezifische Blockeigenschaften gemäß Tabelle 6.7
Custom Dictionary (Optional) Dictionary mit Schlüssel/Wert-Paaren für selbstdefinierte Eigen-
schaften gemäß Tabelle 6.8
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:

186 Kapitel 6: Variable Daten und Blöcke

 <<
/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 4
/PluginVersion (2.0.2)
>>
/LastModified (D:20040913200730)
>>
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 <<

6.6 Spezifikation für PDFlib-Blöcke 187

 /LastModified (D:20040913200730)
/Private <<
/Version 4
/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. 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 Funktionen nicht
verfügbar. Ihr Einsatz löst im Kompatibilitätsmodus zu PDF 1.3 eine Exception 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.47
einige Optionen für Anmerkungen PDF_create_annotation( ), siehe Tabelle 8.49
einige Feldoptionen PDF_create_field( ) und PDF_create_fieldgroup( ), siehe Tabelle 8.50
Tagged PDF Option tagged in PDF_begin_document( )

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.50
einige Anmerkungsoptionen PDF_create_annotation( ) siehe Tabelle 8.49
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.55 und Tabelle 8.56
Ebenen PDF_define_layer( ), PDF_begin_layer( ), PDF_end_layer( ), PDF_layer_
dependency( )

In allen Kompatibilitätsmodi können mit PDI nur PDF-Dokumente mit derselben oder
einer niedrigeren Kompatibilitätsstufe importiert werden. Soll ein PDF mit einer aktu-

7.1 Acrobat und PDF-Versionen 189

 elleren Kompatibiltätsstufe importiert werden, müssen Sie die Option compatibility ent-
sprechend setzen (siehe Abschnitt 5.2.3, »Importierbare PDF-Dokumente«, Seite 153).

190 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 5 oder
höher. Bei PDF 1.5 beträgt die Schlüssellänge ebenfalls 128 Bit, die Verschlüsselung
unterscheidet sich jedoch ein wenig, was den Einsatz von Acrobat 6 erforderlich
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

7.2 Verschlüsseltes PDF 191

 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-

192 Kapitel 7: Erstellung verschiedener PDF-Varianten

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, "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 1.4 oder 1.5
erforderlich. Sie werden abgelehnt, falls die PDF-Ausgabeversion zu alt 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.

7.2 Verschlüsseltes PDF 193

 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.

194 Kapitel 7: Erstellung verschiedener PDF-Varianten

 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 195

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 198).

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- Für jedes Dokument muss genau einmal PDF_load_iccprofile( ) mit usage = outputintent
bedingung oder PDF_process_pdi( ) mit action=copyoutputintent aufgerufen werden. Werden
(output intent) Schmuckfarben aus einer der integrierten Farbbibliotheken verwendet, muss ein ICC-Profil
für die Druckausgabebedingung eingebettet werden (eine Standard-Druckausgabe-
bedingung 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. Werden
in der Datei ICC-basierte oder Lab-Farben verwendet, muss ein ICC-Profil für die
Druckausgabebedingung eingebettet werden.
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.

196 Kapitel 7: Erstellung verschiedener PDF-Varianten

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 197

 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.6, »Ressourcenkonfiguration und Dateisuche«, Seite 54). Der Benutzer muss
sicherstellen, dass nur Namen als Standard-Druckausgabebedingungen eingetragen
werden, die von PDF/X verarbeitender Software erkannt werden.

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 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 151,
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.

198 Kapitel 7: Erstellung verschiedener PDF-Varianten

Darüber hinaus sind einige andere Kombinationen erlaubt. Wird in PDFlib eine be-
stimmte PDF/X-Kompatibilitätsstufe eingestellt und genügen die importierten Doku-
mente dieser Einstellung, dann gilt dies garantiert auch für die erzeugte Ausgabe. Im-
portierte Dokumente, die der eingestellten PDF/X-Kompatibilitätsstufe nicht genügen,
werden abgelehnt.

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");

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.4 PDF/X 199

 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 110). Das bedeutet, dass alle Zeichen der be-
nutzten 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
alternativer Textinhalt angegeben wird. PDFlib löst eine Exception aus, wenn bei der
Generierung 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.

200 Kapitel 7: Erstellung verschiedener PDF-Varianten

 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.55. 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

7.5 Tagged PDF 201

 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-
kompatible Schriften kompatible Fonts«, Seite 110, 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", "");

202 Kapitel 7: Erstellung verschiedener PDF-Varianten

 PDF_setfont(p, font, 24);
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_page_ext(p, "");
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 127) 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");

7.5 Tagged PDF 203

 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 */
PDF_end_item(p, id_sect2);

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_set_text_pos(p, x_start_table, y_start_table);
...
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);

204 Kapitel 7: Erstellung verschiedener PDF-Varianten

 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_set_text_pos(p, x_start_table, y_start_table);
...
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);

7.5 Tagged PDF 205

 id_insert = PDF_begin_item(p, "P", optlist);
/* 5 Einschubstruktur und -inhalt erzeugen */
PDF_set_text_pos(p, x_start_table, y_start_table);
...
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);
...
PDF_end_item(p, id_sect1);

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 */
PDF_end_item(p, id_sect2);

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.

206 Kapitel 7: Erstellung verschiedener PDF-Varianten

 > 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 beispiels-
weise 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.

7.5 Tagged PDF 207

 > 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.

208 Kapitel 7: Erstellung verschiedener PDF-Varianten

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

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 übergeben werden muss. Dies trifft aber nicht auf Sprachbindungen
zu, die den PDF-Dokumentparameter 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
Python ja ja string string
RPG ja ja string, aber x’00’ muss data
angehängt werden
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 19.
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 103. Achten Sie in diesem Zusammenhang auf folgende String-Typen:
> Content-Strings
> Hypertext-Strings
> Name-Strings

8.1 Datentypen und Namenskonventionen 209

 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);

210 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

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

Tabelle 8.2 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_parameter pdfx Veraltet. Verwenden Sie stattdessen die Option pdfx für PDF_begin_document( ).
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.6, »Ressourcenkonfiguration und
Dateisuche«, Seite 54). 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_parameter asciifile (Nur auf iSeries und zSeries verfügbar.) Es werden Textdateien (PFA, AFM, UPR,
Zeichensätze) in ASCII-Format erwartet. Standardwert: true auf iSeries; false auf
zSeries. Geltungsbereich: beliebig.
set_parameter license Setzt den Lizenzschlüssel für PDFlib, PDFlib+PDI oder PPS. Der Lizenzschlüssel kann
(auch mehrfach) vor dem ersten Aufruf von PDF_begin_page( ) gesetzt werden.
Geltungsbereich: object.
set_parameter licensefile Setzt den Namen der Datei mit dem Lizenzschlüssel. Dieser kann nur einmal vor
dem ersten Aufruf von PDF_begin_page_ext( ) festgelegt werden.
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
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.

8.2 Allgemeine Funktionen 211

 Tabelle 8.2 Parameter und Werte für Setup-Funktionen
Funktion Schlüssel Erklärung
set_parameter trace Wenn auf true gesetzt, werden alle API-Funktionen in einer Trace-Datei
protokolliert. Diese kann bei der Fehlersuche hilfreich sein oder vom PDFlib-
Support angefordert werden. Geltungsbereich: beliebig. Standardwert: false.
set_parameter tracefile Definiert den Namen der Trace-Datei. Geltungsbereich: beliebig, aber bevor
Tracing aktiviert wird. Standardwert: PDFlib.trace.
set_parameter tracemsg Ist Tracing aktiviert, wird der übergebene Nachrichtentext zusätzlich zu den API-
Aufrufen in die Trace-Datei 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 25). 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.

212 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 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

8.2 Allgemeine Funktionen 213

 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

Tabelle 8.3 enthält eine Übersicht aller für diesen Abschnitt relevanten Parameter und
Werte.

Tabelle 8.3 Parameter und Werte für Dokument- und Seitenfunktionen

Funktion Schlüssel Erklärung
set_parameter openwarning Veraltet. Um herauszufinden, warum das Öffnen eines Dokuments scheitert,
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_parameter topdown Ist topdown gleich true, wird zu Beginn einer Seite, eines Füllmusters oder eines
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 61). Geltungsbereich: document. Standardwert: false.
get_value pagewidth Ermittelt die Größe der aktuellen Seite (Größe der MediaBox). Geltungsbereich:
pageheight page, path.
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( ).

214 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 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++ int begin_document_callback(String filename,

size_t (*writeproc) (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.4 oder Tabelle 8.6. Opti-
onen, 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.

8.2 Allgemeine Funktionen 215

 Tabelle 8.4 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 189. 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.7, »Erzeugen von PDF-Dokumenten
im Arbeitsspeicher«, Seite 58. 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 194). Auf MVS-Systemen kann diese Option nicht mit der direkten
Generierung im Speicher kombiniert werden (d.h. einem leeren Dateinamen).
Standardwert: false.
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.
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 195). 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 323). 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.
Standardwert: nicht vorhanden.

216 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 Tabelle 8.4 Dokumentoptionen für PDF_begin_document( ) und PDF_begin_document_callback( )
Option Typ Beschreibung
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.5. 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.5 Dokumentoptionen für PDF_begin_document( ) und PDF_end_document( )

Option Typ Beschreibung
action Aktionsliste (PDF 1.4 außer open, das auch ab PDF 1.3 verfügbar ist; 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 Dokumentereignisse (Standardwert: leere Liste):
open 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 JavaScript-Aktionen nach dem Drucken des Dokuments.
didsave JavaScript-Aktionen nach dem Speichern des Dokuments.
willclose JavaScript-Aktionen vor dem Schließen des Dokuments.
willprint JavaScript-Aktionen vor dem Drucken des Dokuments.
willsave JavaScript-Aktionen vor dem Speichern des Dokuments.
destination Optionsliste Optionsliste zur Festlegung der Aktion beim Dokumentöffnen gemäß Tabelle
8.48. Die Aktion open hat Vorrang vor der Option destination. Standardwert: das
in der Aktion open übergebene Handle oder {type fitwindow page 0}, wenn keine
Aktion open übergeben wurde.

8.2 Allgemeine Funktionen 217

 Tabelle 8.5 Dokumentoptionen für PDF_begin_document( ) und PDF_end_document( )
Option Typ Beschreibung
labels Liste von Liste aus einer oder mehreren Optionslisten gemäß Tabelle 8.7, 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.
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: singlepage.
singlepage Nur einzelne Seiten anzeigen.
onecolumn Seiten fortlaufend anzeigen.
twocolumnleft Doppelseiten anzeigen, ungerade Seiten links.
twocolumnright Doppelseiten anzeigen, ungerade Seiten rechts.
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.
viewer- Optionsliste Optionsliste mit verschiedenen Viewer-Voreinstellungen gemäß Tabelle 8.6.
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-Matadaten 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.6 Unteroptionen für die Option viewerpreference für PDF_begin_document( ) und PDF_end_
document( )
Option Typ Beschreibung
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.

218 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

Tabelle 8.6 Unteroptionen für die Option viewerpreference für PDF_begin_document( ) und PDF_end_
document( )
Option Typ Beschreibung
fitwindow Boolean Legt fest, ob das Dokumentfenster an die Größe der ersten Seite angepasst wird.
Standardwert: false.
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
ignoriert diese Einstellung bei der Anzeige von PDFs im Browser. Standardwert:
false.
hidewindowui Boolean Legt fest, ob die Fenstersteuerelemente von Acrobat ausgeblendet werden.
Standardwert: false.
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.

Tabelle 8.7 Unteroptionen für die Option labels in PDF_begin/end_document( ) und die Option label in PDF_
begin/end_page_ext( )
Option Typ Beschreibung
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 105). 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

8.2 Allgemeine Funktionen 219

 Tabelle 8.7 Unteroptionen für die Option labels in PDF_begin/end_document( ) und die Option label in PDF_
begin/end_page_ext( )
Option Typ Beschreibung
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, ...)

C++ const char *get_buffer(double *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.

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.

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.

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.

220 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

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.9 bei den Optionen width und height.

optlist Optionsliste gemäß Tabelle 8.8 und Tabelle 8.9. 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.8 Optionen für PDF_begin_page_ext( )

Option Typ Beschreibung
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, »Koordinatensysteme«, Seite 61). Standardwert:
false.

8.2 Allgemeine Funktionen 221

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.9. 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.9 Optionen für PDF_begin_page_ext( ) und PDF_end_page_ext( )

Option Typ Beschreibung
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 63). 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.
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.7 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.
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.

222 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 Tabelle 8.9 Optionen für PDF_begin_page_ext( ) und PDF_end_page_ext( )
Option Typ Beschreibung
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 63
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.

8.2 Allgemeine Funktionen 223

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.10.

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.10 Optionen für PDF_resume_page( )

Option Typ Beschreibung
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

224 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 (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.

Gültigkeit Hängt vom Schlüssel ab.

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ügbar,
wird ein Leerstring zurückgegeben.

Gültigkeit Hängt vom Schlüssel ab.

8.2 Allgemeine Funktionen 225

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.

Gültigkeit Hängt vom Schlüssel ab.

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.11.

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.
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.

226 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 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.11 Optionen für PDF_create_pvf( )

Option Typ Erklärung
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
enthalten können. Ist len gleich 0, muss ein null-terminierter String übergeben werden.

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.

Gültigkeit beliebig

8.2.5 Ausnahmebehandlung
Tabelle 8.12 enthält eine Übersicht aller für diesen Abschnitt relevanten Parameter und
Werte.

Tabelle 8.12 Parameter und Werte zur Ausnahmebehandlung

Funktion Schlüssel Erklärung
set_parameter warning Aktiviert oder deaktiviert Warnungen (nicht-fatale Exceptions). Mögliche Werte
sind true und false. Standardwert: true. Geltungsbereich: beliebig.

8.2 Allgemeine Funktionen 227

 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 PDF_delete( ); kann alternativ
unmittelbar nach einer Funktion mit dem Fehlercode -1 (in PHP: 0) als Ergebnis
aufgerufen werden. Dazwischen dürfen nur die in diesem Abschnitt beschriebenen
Funktionen ausgeführt werden.

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.

Gültigkeit Zwischen einer von PDFlib ausgelösten Exception und PDF_delete( ); kann alternativ
unmittelbar nach einer Funktion mit dem Fehlercode -1 (in PHP: 0) als Ergebnis
aufgerufen werden. Dazwischen dürfen nur die in diesem Abschnitt beschriebenen
Funktionen ausgeführt werden.

Bindungen In C++, Java, und PHP 5 ist diese Funktion auch als Methode get_errmsg( ) im Objekt
PDFlibException verfügbar.

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.

Gültigkeit Zwischen einer von PDFlib ausgelösten Exception und PDF_delete( ); Kann alternativ
unmittelbar nach einer Funktion mit dem Fehlercode -1 (in PHP: 0) als Ergebnis
aufgerufen werden. Dazwischen dürfen nur die in diesem Abschnitt beschriebenen
Funktionen ausgeführt werden.

228 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 Bindings In C++, Java, und PHP 5 ist diese Funktion auch als Methode get_apiname( ) im Objekt
PDFlibException verfügbar.

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.

Gültigkeit beliebig

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++ Java 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.

Gültigkeit beliebig

8.2 Allgemeine Funktionen 229

C++ Java 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.

Gültigkeit beliebig

230 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

8.3 Textfunktionen
8.3.1 Fontbehandlung
Tabelle 8.13 enthält eine Übersicht aller für diesen Abschnitt relevanten Parameter und
Werte.

Tabelle 8.13 Parameter und Werte für Fontfunktionen (siehe Abschnitt 8.2.3, »Parameterbehandlung«, Seite 224)
Funktion Schlüssel Erklärung
set_parameter FontAFM Wie die jeweilige Zeile in der entsprechenden Kategorie der UPR-Ressourcendatei
FontPFM (siehe Abschnitt 3.1.6, »Ressourcenkonfiguration und Dateisuche«, Seite 54). Durch
FontOutline mehrere Aufrufe erhält die interne Liste neue Einträge (siehe auch resourcefile in
Encoding Tabelle 8.2). Geltungsbereich: beliebig.
HostFont
SearchPath
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 Anzahl der gültigen Glyphen-IDs des durch den Modifizierer bezeichneten
Font zurück. Geltungsbereich: beliebig.
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 112. Die Werte werden anteilig zur Schriftgröße angegeben und
müssen daher mit der gewünschten Schriftgröße multipliziert werden.
Geltungsbereich: beliebig.
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 90). Standardwert: 100 KB. Geltungsbereich: beliebig.
set_parameter auto- Steuert die automatische Aktivierung der Fontuntergruppenbildung für TrueType-
subsetting und OpenType-Fonts (siehe Abschnitt 4.3, »Schrifteinbettung und
Schriftuntergruppen«, Seite 90). Standardwert: true. Geltungsbereich: beliebig.

8.3 Textfunktionen 231

 Tabelle 8.13 Parameter und Werte für Fontfunktionen (siehe Abschnitt 8.2.3, »Parameterbehandlung«, Seite 224)
Funktion Schlüssel Erklärung
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 90).
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 102). 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 90). Es wird zwischen Groß- und Kleinschreibung unterschieden.

len (Nur C-Sprachbindung) Länge von fontname (in Bytes) bei UTF-16-Strings. Ist len
gleich 0, muss ein null-terminierter String übergeben werden.

encoding Zeichensatz, der mit der Schrift verwendet werden soll. Dabei stehen folgen-
de Zeichensätze zur Auswahl (es wird zwischen Groß- und Kleinschreibung unter-
schieden):
> einer der vordefinierten 8-Bit-Zeichensätze winansi, macroman, macroman_apple,
macroman_euro, 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
> 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 116).
> ein dem Betriebssystem bekannter Zeichensatzname (nicht auf allen Plattformen
verfügbar)

Der gewählte Zeichensatz muss zur Schrift kompatibel sein. Tabelle 8.15 listet die zuläs-
sigen Kombinationen von Encodings und Fontformaten auf. Weitere Informationen
finden Sie in Abschnitt 4.4, »Zeichensätze«, Seite 95.

optlist Optionsliste gemäß Tabelle 8.15.

Table 8.14 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 – –

232 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 Table 8.14 Verhältnis von Encodings und Fontformaten
8-Bit- unicode, Unicode- andere
Fontformat Encodings builtin glyphid cp9361 etc. CMaps CMaps
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.

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-
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.13.

8.3 Textfunktionen 233

PDF/X Die Option embedding muss auf true gesetzt sein.

Tabelle 8.15 Optionen für PDF_load_font( )

Option Typ Erklärung
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 nicht
eingebettete TrueType- und OpenType-Schriften genutzt werden (siehe Abschnitt
4.6.3, »Textvarianten«, Seite 114). 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 112). 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 90).
Standardwert: false.
unicodemap Boolean Steuert die Generierung von ToUnicode-CMaps (siehe Abschnitt 4.5.1, »Unicode für
Seitenbeschreibungen und Hypertext«, Seite 102). Diese Option wird im Tagged-
PDF-Modus ignoriert. Standardwert: true.

234 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

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.13. 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].

optlist Optionsliste gemäß Tabelle 8.16.

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.

8.3 Textfunktionen 235

 Tabelle 8.16 Optionen für PDF_begin_font( )
Option Typ Beschreibung
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 143).
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.

236 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

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 Zeichens im zu definierenden Zeichensatz, 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 Textfunktionen 237

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.

Tabelle 8.17 enthält eine Übersicht aller für diesen Abschnitt relevanten Parameter und
Werte.

Tabelle 8.17 Parameter und Werte für Textfunktionen

Funktion Schlüssel Erklärung
set_parameter autospace Ist autospace gleich true und ist der aktuelle Font Unicode-kompatibel, fügt
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 200). Beachten Sie, dass sich beim
Anfügen eines Leerzeichens die nach der show-Operation aktuelle Textposition
ändert. Standardwert: false. Geltungsbereich: beliebig.
set_parameter charref (Nicht für UTF-8-Textformate) Ist charref gleich true, werden numerische
Referenzen und Entity-Referenzen ersetzt (siehe Abschnitt 4.5.5, »Character-
Referenzen«, Seite 108). 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 114). 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 112).
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.

238 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 Tabelle 8.17 Parameter und Werte für Textfunktionen
Funktion Schlüssel Erklärung
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 103). 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_parameter underline Setzt oder ermittelt den aktuellen Modus für Unterstreichen, Überstreichen bzw.
get_parameter overline Durchstreichen, der bis zu einer expliziten Änderung beibehalten wird. Diese Modi
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 112). Geltungsbereich: page, pattern, template, glyph.
true Text unterstreichen/überstreichen/durchstreichen
false Text nicht unterstreichen/überstreichen/durchstreichen
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.

Gültigkeit page, pattern, template, glyph

8.3 Textfunktionen 239

Parameter Siehe Tabelle 8.17.

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
enthalten können. Ist len gleich 0, muss ein null-terminierter String übergeben werden.

Details Der Font muss zuvor mit PDF_setfont( ) gesetzt worden sein. Die aktuelle Textposition
wird ans Ende des ausgegebenen Texts verschoben.

Gültigkeit page, pattern, template, glyph

Parameter Siehe Tabelle 8.17.

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.

Gültigkeit page, pattern, template, glyph

Parameter Siehe Tabelle 8.17.

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.

240 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 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.

Gültigkeit page, pattern, template, glyph

Parameter Siehe Tabelle 8.17.

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.

8.3 Textfunktionen 241

Parameter Siehe Tabelle 8.17.

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.18 und zur Dar-
stellung gemäß Tabelle 8.19.

Details Der aktuelle Grafikzustand ändert sich durch diese Funktion nicht. Insbesondere die ak-
tuelle Textposition sowie der aktuelle Font bleiben unbeeinflusst.

Gültigkeit page, pattern, template, glyph; diese Funktion sollte nicht im vertikalen Textausgabe-
modus verwendet werden.

Parameter Siehe Tabelle 8.17.

Tabelle 8.18 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}.

242 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

Tabelle 8.18 Formatierungsoptionen für PDF_fit_textline( )
Schlüssel Typ Erklärung
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. Die Optionen dpi und scale werden
ignoriert.
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, das
heißt eine Anmerkung mit type=Link, erzeugt, wobei Standardoptionen
verwendet oder die in der Optionsliste übergebenen Optionen berücksichtigt
werden. Folgende Optionen können übergeben werden (siehe auch Tabelle 8.49):
annotcolor, borderstyle, dasharray, highlight (die Optionen action und usercoor-
dinates 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
position Float-Liste (Ausrichtungssteuerung) Ein oder zwei Werte, die die Position des Referenzpunkts
(x, y) innerhalb der Textbox festlegen. {0 0} bezeichnet dabei die linke untere Ecke
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 Wertes. Dazu einige
Beispiele: bei {0 50} wird der Text linksbündig ausgerichtet; bei {50 50} wird der
Text mittig ausgerichtet; bei {100 50} wird der Text rechtsbündig ausgerichtet.
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.

8.3 Textfunktionen 243

 Tabelle 8.18 Formatierungsoptionen für PDF_fit_textline( )
Schlüssel Typ Erklärung
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.49): annotcolor, borderstyle, dasharray,
highlight (die Optionen action und usercoordinates werden automatisch gesetzt).
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.19 Darstellungsoptionen für PDF_fit_textline( ) und direkte oder Inline-Optionen für PDF_create_
textflow( )
Schlüssel Typ Erklärung
charref Boolean (Nicht für UTF-8-Textformate) Ist charref gleich true, werden numerische
Referenzen und Entity-Referenzen ersetzt (siehe Abschnitt 4.5.5, »Character-
Referenzen«, Seite 108). Standardwert: false.
charspacing Float oder Zeichenabstand (siehe Tabelle 8.17). Prozentangaben beziehen sich auf fontsize.
Prozentwert Standardwert: der Wert des globalen Parameters charspacing.
fillcolor Farbe Füllfarbe des Texts. Standardwert: die aktuelle Füllfarbe.
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.
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: Wert des globalen Parameters glyphwarning.
horizscaling Float oder Skalierung von Text (siehe Tabelle 8.17). Standardwert: Wert des globalen
Prozentwert Parameters horizscaling.
italicangle Float Bestimmt den Neigungswinkel von kursivem Text in Grad (siehe Abschnitt 4.6.3,
»Textvarianten«, Seite 114). Standardwert: Wert des globalen Parameters
italicangle.
kerning Boolean Verhalten in bezug auf Kerning (siehe Tabelle 8.17). Standardwert: Wert des
globalen Parameters kerning.
overline Boolean Modus für Überstreichen (siehe Tabelle 8.17). Standardwert: Wert des globalen
Parameters overline.
strikeout Boolean Modus für Durchstreichen (siehe Tabelle 8.17). Standardwert: Wert des globalen
Parameters strikeout.
strokecolor Farbe Farbe zum Zeichnen des Texts. Standardwert: die aktuelle Farbe zum Zeichnen.
shrinklimit Float oder Untere Grenze, bis zu der Text beim Einpassen maximal gestaucht werden darf.
Prozentwert Standardwert: 0.75.
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
103). Standardwert: Wert des globalen Parameters textformat.

244 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 Tabelle 8.19 Darstellungsoptionen für PDF_fit_textline( ) und direkte oder Inline-Optionen für PDF_create_
textflow( )
Schlüssel Typ Erklärung
textrendering Integer Darstellungsmodus für Text (siehe Tabelle 8.17). Standardwert: Wert des globalen
Parameters textrendering.
textrise Float oder Modus für den vertikalen Textversatz (siehe Tabelle 8.17). Prozentangaben
Prozentwert beziehen sich auf fontsize. Standardwert: Wert des globalen Parameters textrise.
underline Boolean Modus für Unterstreichen (siehe Tabelle 8.17). Standardwert: Wert des globalen
Parameters underline.
wordspacing Float oder Wortabstand (siehe Tabelle 8.17). Prozentangaben beziehen sich auf fontsize.
Prozentwert Standardwert: Wert des globalen Parameters wordspacing.

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. Die zugehörige

Schrift darf nur ein CJK-Font sein, wenn er über eine Unicode-CMap überfügt. 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

Parameter Siehe Tabelle 8.17.

Bindungen PDF_stringwidth2( ) ist nur in C verfügbar, da in allen anderen Sprachbindungen Strings

beliebigen Inhalts an PDF_stringwidth( ) übergeben werden können.

8.3 Textfunktionen 245

 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.20 und Tabelle 8.22 enthalten kann. 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.20 und Tabelle 8.22. 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.
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-

246 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 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.7, »Steuerung des Algorithmus für den Zeilenumbruch«, Seite
137.
Vertikale Schreibrichtung wird nicht unterstützt.

Gültigkeit beliebig außer object

Tabelle 8.20 Optionen für PDF_create_textflow( )

Option Typ Beschreibung
textwarning Boolean Ist textwarning gleich true, wird bei einem Fehler in einer Optionsliste oder im
Text eine Exception ausgelöst (zum Beispiel, wenn ein Zeichen vorkommt, das mit
dem gewählten Font nicht darstellbar ist). Bei false gibt die Funktion den
Fehlercode -1 (in PHP: 0) zurück und ersetzt ggf. eine nicht verfügbare Glyphe
durch ein Leerzeichen. 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.
Standardwert: false.

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.21.

Rückgabe String mit der Ursache für das Beenden der Funktion:
> _stop: der Textfluss wurde vollständig verarbeitet.

8.3 Textfunktionen 247

 > _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.
> 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 Der aktuelle Textzustand beeinflusst die von dieser Funktion erzeugte Textausgabe
nicht. Nach der Rückkehr von dieser Funktion ist der Textzustand unverändert. Die ak-
tuelle Textposition dagegen wird ans Ende des generierten Ausgabetextes gestellt.

Gültigkeit page, pattern, template, glyph

Tabelle 8.21 Optionen für PDF_fit_textflow( )

Option Typ Beschreibung
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.
Ist fixedleading=false, wird der größte Wert verwendet, der für Zeilenabstand,
Oberlänge 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.

248 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 Tabelle 8.21 Optionen für PDF_fit_textflow( )
Option Typ Beschreibung
lastlinedist Float, (Wird ignoriert bei fitmethod=nofit) Der kleineste Abstand zwischen der
Prozentwert Grundline der letzten Textzeile und dem unteren Rand der Fitbox. Angegeben wird
oder er in Benutzerkoordinaten, als Schlüsselwort oder als Prozentsatz der Schriftgröße
Schlüsselwort (der 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.
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( )
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
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
fort. Füllt der Text die Fitbox nicht vollständig aus, bleibt Weißraum
ü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:

> boxlinecount: Anzahl der Zeilen in der letzten Fitbox.

8.3 Textfunktionen 249

 > 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.
> minlinelength, maxlinelength: Länge der kürzesten bzw. längsten Textzeile in der zu-
letzt gefüllten Fitbox.
> minliney, maxliney: y-Koordinate der kürzesten bzw. längsten Textzeile in der zuletzt
gefüllten Fitbox.
> remainchars: Anzahl der noch nicht verarbeiteten Zeichen. Davon ausgeschlossen
sind Zeichen in Inline-Optionslisten und Character-Referenzen.
> textendx, textendy: x- bzw. y-Koordinate der aktuellen Position nach Platzierung des
Texts.
> used: Prozentualer Anteil (0...100) des bereits platzierten Texts.

Rückgabe Der Wert des mit keyword abgefragten Textflussparameters.

Gültigkeit document, page, pattern, template, glyph

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.

Gültigkeit beliebig

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.22 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 der zuletzt ein-
gestellte Wert. Inline-Optionslisten sind im Zeichensatz winansi und auf EBCDIC-Syste-
men in ebcdic zu kodieren. Außerdem müssen sie in die Zeichen eingeschlossen sein, die
in den Optionen begoptlistchar und endoptlistchar festgelegt werden (standardmäßig die
Zeichen < und >).
Besondere Sorgfalt erfordern Textteile zwischen Inline-Optionslisten, die nicht als
Unicode interpretiert werden können; Einzelheiten hierzu finden Sie in Abschnitt 4.9.6,
»Steuerzeichen, Zeichenersetzung und Symbolfonts«, Seite 135. Bei Textteilen, die das in
begoptlistchar definierte Zeichen (standardmäßig <) enthalten, kann die Option textlen
übergeben werden. Alternativ dazu können numerische oder Entity-Referenzen eing-
esetzt werden, um das mit begoptlistchar definierte Zeichen ohne Sonderbedeutung zu
verwenden (z.B. U+003C für <). Bei nicht Unicode-fähigen Sprachbindungen muss die
Option textlen auch bei Textteilen mit textformat=utf16xx übergeben werden.

250 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

Tabelle 8.22 Optionen für den Parameter optlist von PDF_create_textflow( ) und für Inline-Optionslisten
im Text
Option Typ Beschreibung
Alle Optionen und Parameter für PDF_load_font( ) (siehe Tabelle 8.15)
encoding String (Ist für die Option fontname erforderlich) Name des Zeichensatzes.
fontname String (Ist für die Option encoding erforderlich) Fontname.
autocidfont Diese Optionen werden nur in Kombination mit den Optionen fontname und
autosubsetting encoding berücksichtigt. Anmerkung:
embedding fontwarning
fontstyle Wird mit dem Wert der Option textwarning initialisiert.
fontwarning
monospace
subsetlimit
subsetminsize
subsetting
unicodemap
Alle Darstellungsoptionen für PDF_fit_textline( ) (siehe Tabelle 8.19)
charref Diese Optionen werden mit dem Wert des entsprechenden Parameters
charspacing initialisiert.
fillcolor font Wird ignoriert, wenn fontname und encoding angegeben sind.
font fontsize Diese Option ist immer erforderlich.
fontsize glyphwarning
glyphwarning Wird mit dem Wert der Option textwarning initialisiert.
horizscaling
kerning
overline
strikeout
strokecolor
textformat
textrendering
textrise
underline
wordspacing
Optionen zur Verarbeitung von Optionslisten
begoptlistchar Unichar oder Zeichen, mit dem Inline-Optionslisten beginnen. Wenn dieses Zeichen in seiner
Schlüsselwort ursprünglichen Bedeutung im Text enthalten ist, so können Sie die Option textlen
mit dem Schlüsselwort none verwenden, das die Interpretation von Optionslisten
vollständig deaktiviert. 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 (>).
textlen Integer oder (Erforderlich bei Text, der nicht zu Unicode kompatible Schriften oder das in
Schlüsselwort begoptlistchar definierte Zeichen enthält, oder bei 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.
Standardwert: 0.

8.3 Textfunktionen 251

 Tabelle 8.22 Optionen für den Parameter optlist von PDF_create_textflow( ) und für Inline-Optionslisten
im Text
Option Typ Beschreibung
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 festgelegte 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.
leading Float oder Zeilenabstand3. Standardwert: 100%.
Prozentwert
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.

252 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

Tabelle 8.22 Optionen für den Parameter optlist von PDF_create_textflow( ) und für Inline-Optionslisten
im Text
Option Typ Beschreibung
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 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
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 verblei-
bende (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.
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%.

8.3 Textfunktionen 253

 Tabelle 8.22 Optionen für den Parameter optlist von PDF_create_textflow( ) und für Inline-Optionslisten
im Text
Option Typ Beschreibung
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 auch
Prozentwert 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-ko-
mpatible Fonts«, Seite 110).
2. In Benutzerkoordinaten oder als prozentualer Anteil der Fitbox-Breite
3. In Benutzerkoordinaten oder als prozentualer Anteil der Schriftgröße

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.23 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:
<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:

254 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 > 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.23 Makrodefinitionen und -aufrufe in Optionslisten für PDF_fit_textflow( )

Option Typ Beschreibung
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.3 Textfunktionen 255

 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 231, beschrieben.

Hinweis Keine der Funktionen für den Grafikzustand darf im Geltungsbereich path verwendet werden
(siehe Abschnitt 3.2, »Seitenbeschreibungen«, Seite 61).

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.

Gültigkeit page, pattern, template, glyph

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.24. Ist optlist leer, wird eine durchgezogene
Linie generiert.

Tabelle 8.24 Optionen für PDF_setdashpattern( )

Option Typ Erklärung
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 dürfen nicht negativ, und
mindestens ein Wert muss ungleich null sein. Die Array-Werte 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.

Gültigkeit page, pattern, template, glyph

256 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

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.

Gültigkeit page, pattern, template, glyph

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.25).

Details Am Anfang jeder Seite wird der linejoin-Parameter auf den Standardwert 0 gesetzt.

Gültigkeit page, pattern, template, glyph

Tabelle 8.25 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
Linienstä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.26).

Details Am Anfang jeder Seite wird der linecap-Parameter auf den Standardwert 0 gesetzt.

Gültigkeit page, pattern, template, glyph

8.4 Grafikfunktionen 257

 Tabelle 8.26 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 Linienstärke

entsprechenden Durchmesser wird um den Endpunkt gezeichnet und
gefüllt.
2 Hervorstehende rechtwinklige Linienenden: Das Linienende wird um die
halbe Linienstä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 Linienstärke den Wert des miterlimit-Para-
meters übersteigt. Am Anfang jeder Seite wird miterlimit auf den Standardwert 10 ge-
setzt. Dies entspricht einem Winkel von etwa 10,5 Grad.

Gültigkeit page, pattern, template, glyph

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.

Gültigkeit page, pattern, template, glyph

258 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

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.

Gültigkeit page, pattern, template, glyph

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: 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
> 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.

8.4 Grafikfunktionen 259

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.

Gültigkeit page, pattern, template, glyph

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 negativer
Skalierungsfaktor bewirkt eine Spiegelung. Eine Einheit in x-Richtung im neuen Koordi-
natensystem entspricht sx Einheiten in x-Richtung im alten Koordinatensystem; Ent-
sprechendes gilt für die y-Koordinaten.

Gültigkeit page, pattern, template, glyph

260 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

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.

Gültigkeit page, pattern, template, glyph

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 angebenen
Winkel geneigt. alpha wird dabei von der positiven x-Achse des aktuellen Koordinaten-
systems 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.

Gültigkeit page, pattern, template, glyph

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.

Gültigkeit page, pattern, template, glyph

8.4 Grafikfunktionen 261

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.

Gültigkeit page, pattern, template, glyph

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.27.

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.

Gültigkeit document, page, pattern, template, glyph

Parameter Die Optionen opacityfill und opacitystroke dürfen nur mit dem Wert 1 verwendet werden.

Tabelle 8.27 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 Art der Linienenden eines Pfads (siehe PDF_setlinecap( )); muss 0, 1 oder 2
sein.
linejoin Integer Verbindungsart von Linien eines Pfads (siehe PDF_setlinejoin( )); muss 0, 1
oder 2 sein.
linewidth Float Strichstärke (siehe PDF_setlinewidth( )); muss > 0 sein.

262 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 Tabelle 8.27 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.
Standardwert: false.
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 Linienstä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.

Gültigkeit page, pattern, template, glyph

8.4.5 Pfadkonstruktion
Tabelle 8.28 enthält eine Übersicht aller für diesen Abschnitt relevanten Parameter und
Werte.

Hinweis Achten Sie darauf, immer eine der Funktionen aus Abschnitt 8.4.6, »Zeichnen und Beschneiden
von Pfaden«, Seite 267, aufzurufen, nachdem Sie die Funktionen im vorliegenden Abschnitt ver-
wendet haben. Sonst hat der konstruierte Pfad keinerlei Auswirkungen, und nachfolgende
Operationen führen unter Umständen zu einer PDFlib-Exception.

8.4 Grafikfunktionen 263

 Tabelle 8.28 Parameter und Werte für Pfadsegmentfunktionen (siehe Abschnitt 8.2.3,
»Parameterbehandlung«, Seite 224)
Funktion Schlüssel Erklärung
get_value currentx Die x- bzw. y-Koordinate (in Einheiten des aktuellen Koordinatensystems) der
currenty aktuellen Position. Geltungsbereich: page, pattern, template, path.

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 Linienstä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

Parameter currentx, currenty

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.

264 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 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

Parameter currentx, currenty

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.

Gültigkeit page, pattern, template, path, glyph; mit dieser Funktion beginnt der Geltungsbereich
path.

Parameter currentx, currenty

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.

Gültigkeit page, pattern, template, path, glyph; mit dieser Funktion beginnt der Geltungsbereich
path.

8.4 Grafikfunktionen 265

Parameter currentx, currenty

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.

Gültigkeit page, pattern, template, path, glyph; mit dieser Funktion beginnt der Geltungsbereich
path.

Parameter currentx, currenty

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

Parameter currentx, currenty

266 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 8.4.6 Zeichnen und Beschneiden von Pfaden
Tabelle 8.29 enthält eine Übersicht aller für diesen Abschnitt relevanten Parameter und
Werte.

Tabelle 8.29 Parameter und Werte für Funktionen zum Zeichnen und Beschneiden von Pfaden (siehe Abschnitt
8.2.3, »Parameterbehandlung«, Seite 224)
Funktion Schlüssel Erklärung
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 Linienstärke und -farbe 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 Linienstärke und Linienfarbe.

Gültigkeit path; mit dieser Funktion endet der Geltungsbereich path.

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.

Gültigkeit path; mit dieser Funktion endet der Geltungsbereich path.

Parameter fillrule

8.4 Grafikfunktionen 267

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.

Gültigkeit path; mit dieser Funktion endet der Geltungsbereich path.

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.

Gültigkeit path; mit dieser Funktion endet der Geltungsbereich path.

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.

Gültigkeit path; mit dieser Funktion endet der Geltungsbereich path.

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.

Gültigkeit path; mit dieser Funktion endet der Geltungsbereich path.

268 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 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.30.

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.30 Optionen für PDF_define_layer( )

Option Typ Beschreibung
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
105). 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.
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

8.4 Grafikfunktionen 269

 Tabelle 8.30 Optionen für PDF_define_layer( )
Option Typ Beschreibung
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.4 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.31.

270 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

Gültigkeit document, page

Tabelle 8.31 Optionen für PDF_set_layer_dependency( )

Option Typ Beschreibung
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
Sichbarkeit 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.

Gültigkeit page

8.4 Grafikfunktionen 271

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

Tabelle 8.32 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 67):
> 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.

272 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 > 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 to 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üllmuster-
farbe 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 wer-
den können (siehe Tabelle 8.34).

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

8.5 Farbfunktionen 273

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.

274 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 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.33.

Tabelle 8.33 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.
Standardwert: false.

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 71, 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.

8.5 Farbfunktionen 275

Gültigkeit document; ist usage = iccbased, sind auch die folgenden Geltungsbereiche zulässig: page,
pattern, template, glyph.

Parameter Siehe Tabelle 8.34.

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.34 Parameter und Werte für ICC-Profile

Funktion Schlüssel Erklärung
set_parameter ICCProfile Die zugehörige Zeile aus der Ressourcendatei, so wie sie in einer UPR-Datei in der
Standard- entsprechenden Kategorie eingetragen wäre (see Abschnitt 3.1.6,
OutputIntent »Ressourcenkonfiguration und Dateisuche«, Seite 54). Bei mehreren Aufrufen wird
die interne Liste um weitere Einträge ergänzt (siehe auch resourcefile in Tabelle
8.2). 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.
Geltungsbereich: beliebig.
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-

276 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 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.

Details Diese Funktion setzt alle Text-, Grafik- und Farbzustandsparameter auf ihre Standard-
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.35.

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.35 Optionen für PDF_shading_pattern( )

Schlüssel Typ Erklärung und mögliche Werte
gstate Handle Grafikzustand-Handle

8.5 Farbfunktionen 277

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.36.

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

278 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

Tabelle 8.36 Optionen für PDF_shading( )
Schlüssel Typ Erklärung und mögliche Werte
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.
Standardwert: false.
antialias Boolean Legt fest, ob Antialiasing (Kantenglättung) für den Farbverlauf aktiviert
wird. Standardwert: false.

8.5 Farbfunktionen 279

8.6 Rasterbild- und Template-Funktionen
Tabelle 8.37 gibt eine Übersicht über alle in diesem Abschnitt relevanten Parameter und
Werte.

Tabelle 8.37 Parameter und Werte für die Rasterbildfunktionen (siehe Abschnitt 8.2.3, »Parameterbehandlung«,
Seite 224)
Funktion Schlüssel Erklärung
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_parameter honoriccprofile Liest in Rasterbilder eingebettete ICC-Farbprofile und wendet sie auf die
Bilddaten an. Standardwert: true.
set_parameter imagewarning Dieser Parameter kann verwendet werden, um genauere Angaben darü-
ber zu erhalten, warum 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.
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.

280 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 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, png, raw oder tiff übergeben (weitere Informationen hierzu
finden Sie in Abschnitt 5.1.2, »Unterstützte Rasterbildformate«, Seite 144). 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
gleich 0, muss ein null-terminierter String übergeben werden.

optlist Optionsliste mit Bildeigenschaften gemäß Tabelle 8.38.

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.37 und Tabelle 8.38). 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. Dasselbe Bild sollte
nicht mehrmals geöffnet werden, da die eigentlichen Bilddaten dann mehrfach ins Aus-
gabedokument 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.

8.6 Rasterbild- und Template-Funktionen 281

 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 67, 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.
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.38 Optionen für PDF_load_image( )

Schlüssel Typ Erklärung
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) Färbt das Bild anhand
ben-Handle 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.

282 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

Tabelle 8.38 Optionen für PDF_load_image( )
Schlüssel Typ Erklärung
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 105). Ein leerer String ent-
spricht unicode. Standardwert: Wert des globalen Parameters hypertextencoding.
iccprofile ICC-Handle (Nur bei imagetype = jpeg, png oder tiff) Handle eines ICC-Profils, das auf das Bild
angewandt werden soll. Standardwert: Wert des globalen Parameters image:icc-
profile.
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.
Standardwert: false.
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: 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 143).
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 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 Das Bild soll als Maske verwendet werden (siehe Abschnitt 5.1.3, »Bildmasken und
Transparenz«, Seite 146); 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. Diese Option ist nur zulässig bei Bildern mit einer Farbkomponente
(einschließlich indizierter Farbe). Standardwert: false. Es gibt zwei Anwendungs-
fä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.

8.6 Rasterbild- und Template-Funktionen 283

 Tabelle 8.38 Optionen für PDF_load_image( )
Schlüssel Typ Erklärung
OPI-1.3 Optionsliste Optionsliste mit OPI 1.3-PostScript-Kommentaren als Optionsnamen; folgende
Einträge sind erforderlich:
ALDImageFilename (String), ALDImageDimensions (Integer-Liste), ALDImageCrop-
Rect (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)
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)
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.
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.

284 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 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.39.

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.

Tabelle 8.39 Optionen für PDF_fit_image( ) und PDF_fit_pdi_page( )

Schlüssel Typ Erklärung
adjustpage Boolean 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.

8.6 Rasterbild- und Template-Funktionen 285

 Tabelle 8.39 Optionen für PDF_fit_image( ) und PDF_fit_pdi_page( )
Schlüssel Typ Erklärung
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 übergebe-
nen 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

286 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 Tabelle 8.39 Optionen für PDF_fit_image( ) und PDF_fit_pdi_page( )
Schlüssel Typ Erklärung
position Float-Liste Einer oder zwei Werte, die die Position des Referenzpunkts (x, y) innerhalb des
Objekts festlegen. {0 0} bezeichnet dabei die linke untere Ecke des Objekts und
{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. Standardwert: 0. Dazu einige Beispiele:
0 oder {0 0} bezeichnet die linke untere Ecke
{50 100} bezeichnet die Mitte des oberen Rands
50 oder {50 50} bezeichnet den Mittelpunkt des Objekts.
rotate Float Dreht das Koordinatensystem, wobei der Referenzpunkt als Mittelpunkt und der
ü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.

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 298).

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.

Details Diese Funktion setzt alle Text-, Grafik- und Farbzustandsparameter auf ihre Standard-
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.

8.6 Rasterbild- und Template-Funktionen 287

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 144).

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

288 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 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)

Perl PHP int PDF_open_pdi(resource p, string filename, string optlist)
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.40.

len (Nur C-Sprachbindung; 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-terminierter 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 153):
> 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.

8.7 Funktionen für den PDF-Import (PDI) 289

 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.43 und Tabelle 8.44.

Tabelle 8.40 Optionen für PDF_open_pdi( )

Schlüssel Typ Erklärung
infomode Boolean Ist infomode gleich true, wird das Dokument so geöffnet, dass allgemeine
Informationen zwar 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.44).

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.

290 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 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.40.

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.

Parameter Siehe Tabelle 8.43 und Tabelle 8.44.

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

Parameter Siehe Tabelle 8.43 und Tabelle 8.44.

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.41.

8.7 Funktionen für den PDF-Import (PDI) 291

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.

Gültigkeit document, page

Parameter Siehe Tabelle 8.43 und Tabelle 8.44.

Tabelle 8.41 Optionen für PDF_open_pdi_page( )

Schlüssel Typ Erklärung
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 105). Ein leerer String ent-
spricht unicode. Standardwert: Wert des globalen Parameters hypertextencoding.

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 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
der Wert des Parameters pdiwarning (siehe Tabelle 8.44).

292 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

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.

Gültigkeit document, page

Parameter Siehe Tabelle 8.43 und Tabelle 8.44.

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.39.

Details Diese Funktion entspricht im Wesentlichen PDF_fit_image( ), arbeitet aber mit impor-
tierten PDF-Seiten. Die meisten in Tabelle 8.39 aufgeführten Optionen zur Skalierung
und Platzierung werden auch für PDF-Seiten unterstützt.

Gültigkeit page, pattern, template, glyph

Parameter Siehe Tabelle 8.43 und Tabelle 8.44.

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 Funktionen für den PDF-Import (PDI) 293

 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*( ) erzeugt wurde.

page Verlangt optlist ein Seiten-Handle (siehe Tabelle 8.42), 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.42.

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

Parameter Siehe Tabelle 8.44.

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.42 Optionen für PDF_process_pdi( )

Schlüssel Typ Erklärung
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
der Wert des Parameters pdiwarning (siehe Tabelle 8.43).
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.43 und Tabelle
8.44.

doc Gültiges PDF-Dokument-Handle, das von PDF_open_pdi( ) erzeugt wurde.

294 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 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.

Gültigkeit beliebig

Tabelle 8.43 Seitenspezifische Parameter und Werte beim PDF-Import

Funktion Schlüssel Erklärung
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 63.) 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.43 und Tabelle 8.44.

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.

8.7 Funktionen für den PDF-Import (PDI) 295

 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.44
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.

Gültigkeit beliebig

Tabelle 8.44 Dokumentspezifische Parameter und Werte zum PDF-Import

Funktion Schlüssel Erklärung
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 195).
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.

296 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

Tabelle 8.44 Dokumentspezifische Parameter und Werte zum PDF-Import
Funktion Schlüssel Erklärung
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 183). Nur im PDFlib
Custom/ Personalization Server (PPS) verfügbar.
<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.

8.7 Funktionen für den PDF-Import (PDI) 297

 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
enthalten können. Ist len gleich 0, muss ein null-terminierter String übergeben werden.

optlist Optionsliste zur genaueren Steuerung der Fülleigenschaften gemäß Tabelle

8.45.

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.

298 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 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.

page Gültiges PDF-Seiten-Handle für eine Seite mit Blöcken.

blockname (Name-String) Name des Blocks.

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.45.

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.
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 zu-
rück.

Gültigkeit page, template

Hinweis Diese Funktion ist nur im PDFlib Personalization Server (PPS) verfügbar.

8.8 Blockfunktionen (PPS) 299

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.

page Gültiges PDF-Seiten-Handle für eine Seite mit Blöcken.

blockname (Name-String) Name des Blocks.

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.45.

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.
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 zu-
rück.

Gültigkeit page, template

Tabelle 8.45 Optionen für die Funktionen PDF_fill_*block( )

Schlüssel Typ Erklärung
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.19.
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.18.
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.

300 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 Tabelle 8.45 Optionen für die Funktionen PDF_fill_*block( )
Schlüssel Typ Erklärung
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.44).
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.18.
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 103 und Tabelle 8.18). 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.15.
Fast alle Namen von Namen und Werte von Blockeigenschaften (siehe Abschnitt 6.4,
Blockeigenschaften »Standardeigenschaften zur automatischen Verarbeitung«, Seite 175), die Vorrang
von jenen in der Blockdefinition haben sollen. Einzelheiten dazu finden Sie in
Abschnitt 6.2.2, »Blockeigenschaften«, Seite 164. 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.

Hinweis Diese Funktion ist nur im PDFlib Personalization Server (PPS) verfügbar.

8.8 Blockfunktionen (PPS) 301

 8.9 Hypertext-Funktionen
Tabelle 8.46 zeigt eine Übersicht aller für diesen Abschnitt relevanten Parameter und
Werte.

Tabelle 8.46 Parameter für Hypertext-Funktionen (siehe Abschnitt 8.2.3, »Parameterbehandlung«, Seite 224)
Funktion Schlüssel Erklärung
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 105). 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_parameter usercoordinates Ist usercoordinates gleich false, werden die Koordinaten für Hypertext-
rechtecke im Standardkoordinatensystem erwartet (siehe Abschnitt 3.2.1,
»Koordinatensysteme«, Seite 61); 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.47.

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.

302 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 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.47 Optionen für Aktionseigenschaften mit PDF_create_action( )

Option Typ Beschreibung
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.48.
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.

8.9 Hypertext-Funktionen 303

 Tabelle 8.47 Optionen für Aktionseigenschaften mit PDF_create_action( )
Option Typ Beschreibung
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-
encoding Behandlung in nicht Unicode-fähigen Sprachen«, Seite 105). Ein leerer String ent-
spricht unicode. Standardwert: Wert des globalen Parameters hypertextencoding.
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);

304 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

Tabelle 8.47 Optionen für Aktionseigenschaften mit PDF_create_action( )
Option Typ Beschreibung
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.
Standardwert: nicht vorhanden.
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 Hypertext-Funktionen 305

 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.48. Eine leere
Liste entspricht {type fitwindow page 0}.

Details Das benannte Ziel muss in optlist genauer festgelegt werden und kann auf eine beliebige
Seite im aktuellen Dokument verweisen. Der übergebene name kann als Ziel für alle
Funktionen und Parameter verwendet werden, die Optionen zur Festlegung des Ziels
gemäß Tabelle 8.48 akzeptieren.

Gültigkeit document, page

Tabelle 8.48 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( ).
Option Typ Erklärung
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 105). 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

306 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

Tabelle 8.48 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( ).
Option Typ Erklärung
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
(Nicht für PDF_add_nameddest( )) Benanntes Ziel, das durch die Option
name festgelegt ist.
name Hypertext- (Nicht für PDF_add_nameddest( ); wird bei type = nameddest benötigt und sonst
String ignoriert) Bezeichnet ein benanntes Ziel, das in der Zieldatei definiert sein muss.
Wird diese Option übergeben, darf außer type keine andere Option verwendet
werden. Die Namen benannter Ziele müssen innerhalb eines Dokuments
eindeutig sein.
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 Hypertext-Funktionen 307

 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.49.

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).

308 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

Tabelle 8.49 Optionen für Anmerkungen mit PDF_create_annotation( )
Option Typ Beschreibung
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.
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) Definiert das anzuspringende Ziel. Die Aktionen destination
und destname haben Vorrang vor dieser Option.
destname Hypertext- (Nur für type=Link) Name eines mit PDF_add_nameddest( ) definierten Ziels. Die
String Aktionen destination und destname haben Vorrang vor dieser Option.
display Schlüsselwort Sichtbarkeit auf Bildschirm und Papier: visible, hidden, noview, noprint.
Standardwert: visible.

8.9 Hypertext-Funktionen 309

 Tabelle 8.49 Optionen für Anmerkungen mit PDF_create_annotation( )
Option Typ Beschreibung
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.
hypertext- Schlüsselwort Legt den Zeichensatz für den übergebenen Text fest (siehe Abschnitt 4.5.4, »String-
encoding Behandlung in nicht Unicode-fähigen Sprachen«, Seite 105). Ein leerer String
entspricht unicode. Standardwert: Wert des globalen Parameters
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 sold (endgültige
Version), 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 String (Nur für type=FileAttachment) MIME-Typ der Datei, mit dem Acrobat bei
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.

310 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

Tabelle 8.49 Optionen für Anmerkungen mit PDF_create_annotation( )
Option Typ Beschreibung
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 vier (Nur für type=Polygon, PolyLine, Ink, Highlight, Underline, Squiggly, Strikeout;
oder mehr erforderlich.) Liste aus Float-Werten, die Koordinatenpaare repräsentieren. Die
Floats Koordinaten werden in Standardkoordinaten interpretiert (wenn die Option user-
coordinates gleich false ist) oder in Benutzerkoordinaten (bei true).
type=Polygon, PolyLine, Ink
Die Liste enthält 2 x n Floatwerte für die Koordinaten von n Punkten
(Minimum: 2). Die Punkte werden durch Geraden verbunden.
sonst Liste mit 8 x n Floatwerten für n Vierecke (Mindestanzahl: 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.
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.
Standardwert: false.
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.
Standardwert: nicht vorhanden.
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 61); 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 Hypertext-Funktionen 311

 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.

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.

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.50. 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 durch die Reihenfolge
der Aufrufe von PDF_create_field( ). Nachträglich kann sie nicht mehr geändert werden.

312 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

Tabelle 8.50 Optionen für Feldeigenschaften in PDF_create_field( ) und PDF_create_fieldgroup( )
Option Typ Beschreibung
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. Standardwert: nicht vorhanden.
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.

8.9 Hypertext-Funktionen 313

 Tabelle 8.50 Optionen für Feldeigenschaften in PDF_create_field( ) und PDF_create_fieldgroup( )
Option Typ Beschreibung
charspacing Float (Nicht für type=radiobutton oder checkbox) 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.
Standardwert: nicht vorhanden.
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).

314 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

Tabelle 8.50 Optionen für Feldeigenschaften in PDF_create_field( ) und PDF_create_fieldgroup( )
Option Typ Beschreibung
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-
encoding Behandlung in nicht Unicode-fähigen Sprachen«, Seite 105). Ein leerer String
entspricht unicode. Standardwert: Wert des globalen Parameters
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
Handle1 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
Handle1 die Schaltfläche aktiviert ist. Standardwert: nicht vorhanden.
iconrollover Template- (Nur für type=pushbutton) Handle für ein Template, das angezeigt wird, solange
Handle1 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.

8.9 Hypertext-Funktionen 315

 Tabelle 8.50 Optionen für Feldeigenschaften in PDF_create_field( ) und PDF_create_fieldgroup( )
Option Typ Beschreibung
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-Liste (Nur für type=pushbutton) Relative Position eines Templates, das mit einer der
Optionen icon... für eine Schaltfläche übergeben wurde, in Prozent. Standardwert:
50 50.
readonly 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 (anfangs 10); im
Standardfall richtet sich die Tabulatorreihenfolge also nach der Erstellungs-
reihenfolge.
toggle Boolean (Nur für type=radiobutton) Ist toggle gleich 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.
tooltip 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.

316 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 Tabelle 8.50 Optionen für Feldeigenschaften in PDF_create_field( ) und PDF_create_fieldgroup( )
Option Typ Beschreibung
unisonselect Boolean (Nur für type=radiobutton; PDF 1.5) Ist unisonselect gleich true, werden Radio-
buttons mit demselben Feld- oder Elementnamen gleichzeitig selektiert.
Standardwert: false.
user- Boolean Ist usercoordinates gleich false, werden Feldkoordinaten im Standardkoordi-
coordinates natensystem erwartet (siehe Abschnitt 3.2.1, »Koordinatensysteme«, Seite 61);
andernfalls wird das aktuelle Benutzerkoordinatensystem verwendet.
Standardwert: Wert des globalen Parameters usercoordinates.
1. 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.

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 78.

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.

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.

optlist Optionsliste mit Feldeigenschaften gemäß Tabelle 8.50 und Tabelle 8.51.

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 Hypertext-Funktionen 317

 Tabelle 8.51 Weitere Optionen für Feldeigenschaften mit PDF_create_fieldgroup( )
Option Typ Beschreibung
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.

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.

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.

optlist Optionsliste mit Lesezeicheneigenschaften gemäß Tabelle 8.52.

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_end_document( )
auf den Standardwert bookmarks gesetzt.

Gültigkeit document, page

Tabelle 8.52 Optionen für PDF_create_bookmark( )

Option Typ Beschreibung
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 Optionliste zur Festlegung des Lesezeichenziels gemäß Tabelle 8.48. Aktionen
haben Vorrang vor dieser Option. Standardwert: {type fitwindow page 0}, sofern
nicht destination, destname und action vorhanden sind.
destname Hypertext- Name eines mit PDF_add_nameddest( ) definierten Ziels. Die Aktionen
String destination und destname haben Vorrang vor dieser Option.

318 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 Tabelle 8.52 Optionen für PDF_create_bookmark( )
Option Typ Beschreibung
fontstyle Schlüsselwort Legt den Schriftstil des Lesezeichentexts fest: normal, bold, italic, bolditalic.
Standardwert: normal.
hypertext- Schlüsselwort Legt den Zeichensatz für den übergebenen Text fest (siehe Abschnitt 4.5.4, »String-
encoding Behandlung in nicht Unicode-fähigen Sprachen«, Seite 105). Ein leerer String
entspricht unicode. Standardwert: Wert des globalen Parameters
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.53). 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.

1. Siehe dublincore.org

8.9 Hypertext-Funktionen 319

 Details Der übergebene Wert wird nur für das aktuelle und nicht für alle im selben Geltungsbe-
reich object erstellten Dokumente verwendet.

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.53 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.

8.9.7 Veraltete Hypertext-Parameter und Funktionen

Tabelle 8.54 führt veraltete Parameter und Werte für Hypertext-Funktionen auf.

Tabelle 8.54 Veraltete Dokument- und Hypertext-Parameter

Funktion Schlüssel Beschreibung
set_parameter openaction Verwenden Sie die Option action mit type=open in PDF_begin/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

320 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

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 Op-
tion 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_
annotation( ) mit type=Link.

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_
annotation( ) mit type=Link.

8.9 Hypertext-Funktionen 321

 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( ).

322 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 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.55. 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.55 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 1.5

optlist Optionsliste mit Elementeigenschaften gemäß Tabelle 8.56. 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.

8.10 Strukturfunktionen für Tagged PDF 323

 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.56 Optionen für die Eigenschaften von Struktur- oder Pseudo-Tags in PDF_begin_item( )
Option Typ Beschreibung
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
Barrierefreiheit (Accessibility) erforderlich. Wird diese Option im PDF-1.4-Modus
verwendet, 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
String Zeichensä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
Standardkoordinatensystem (bei usercoordinates gleich false) oder im
Benutzerkoordinatensystem (bei usercoordinates gleich true). Wurde diese Option
nicht übergeben, generiert PDFlib automatisch einen BBox-Eintrag für importierte
Bilder und PDF-Seiten.
ColSpan Integer 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)
String Abkürzungsergänzung für den Dokumentbestandteil. Sie sollte zur Erklärung von
Abkürzungen und Akronymen übergeben werden. Die Sprachausgabe von
Acrobat sieht diese Ergänzung auch ohne explizite Wortgrenze als eigenes Wort
an.
hypertext- Schlüsselwort Legt den Zeichensatz für den übergebenen Text fest (siehe Abschnitt 4.5.4, »String-
encoding Behandlung in nicht Unicode-fähigen Sprachen«, Seite 105). Ein leerer String
entspricht unicode. Standardwert: leerer String für Unicode-fähige
Sprachbindungen, 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.

324 Kapitel 8: API-Referenz für PDFlib, PDI und PPS

 Tabelle 8.56 Optionen für die Eigenschaften von Struktur- oder Pseudo-Tags in PDF_begin_item( )
Option Typ Beschreibung
Lang String (Nicht für Pseudo-Tags außer ASpan) Sprachidentifikation für den
Dokumentbestandteil in dem Format, das in Tabelle 8.4 für die Option lang
beschrieben wird. Damit lässt sich die für das Dokument eingestellte Sprache in
einzelnen Dokumentbestandteilen überschreiben.
RowSpan Integer Anzahl der Tabellenzeilen, die von einer Zelle belegt werden.
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 203.

Gültigkeit document, page; Diese Funktion ist nur im Tagged-PDF-Modus zulässig.

Gültigkeit

8.10 Strukturfunktionen für Tagged PDF 325

326 Kapitel 8: API-Referenz für PDFlib, PDI und PPS
A Literaturhinweise
[1] Adobe Systems Incorporated: PDF Reference, Fourth Edition: Version 1.5; als PDF-
Dokument erhältlich unter partners.adobe.com/asn/tech/pdf/specifications.jsp

[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 http://www.pdflib.com
Bestellung gedruckter Exemplare per E-Mail über [email protected]

327
B PDFlib-Kurzreferenz
Allgemeine Funktionen
Funktionsprototyp Seite
void PDF_boot(void) 212
void PDF_shutdown(void) 212
PDF *PDF_new(void) 212
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) 213
void PDF_delete(PDF *p) 213
int PDF_begin_document(PDF *p, const char *filename, int len, const char *optlist) 215
void PDF_begin_document_callback(PDF *p, size_t (*writeproc) (PDF *p, void *data, size_t size), const char
*optlist) 215
void PDF_end_document(PDF *p, const char *optlist) 217
const char * PDF_get_buffer(PDF *p, long *size) 220
void PDF_begin_page_ext(PDF *p, double width, double height, const char *optlist) 221
void PDF_end_page_ext(PDF *p, const char *optlist) 222
void PDF_suspend_page(PDF *p, const char *optlist) 223
void PDF_resume_page(PDF *p, const char *optlist) 224
double PDF_get_value(PDF *p, const char *key, double modifier) 225
void PDF_set_value(PDF *p, const char *key, double value) 225
const char * PDF_get_parameter(PDF *p, const char *key, double modifier) 225
void PDF_set_parameter(PDF *p, const char *key, const char *value) 226
void PDF_create_pvf(PDF *p, const char *filename, int len, const void *data, size_t size, const char *optlist) 226
int PDF_delete_pvf(PDF *p, const char *filename, int len) 227
int PDF_get_errnum(PDF *p) 228
const char *PDF_get_errmsg(PDF *p) 228
const char *PDF_get_apiname(PDF *p) 228
void *PDF_get_opaque(PDF *p) 229
const char *PDF_utf16_to_utf8(PDF *p, const char *utf16string, int len, int *size) 229
const char * PDF_utf8_to_utf16(PDF *p, const char *utf8string, const char *ordering, int *size) 230

Fontfunktionen
Funktionsprototyp Seite
int PDF_load_font(PDF *p, const char *fontname, int len, const char *encoding, const char *optlist) 232
void PDF_setfont(PDF *p, int font, double fontsize) 235
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) 235
void PDF_end_font(PDF *p) 236
void PDF_begin_glyph(PDF *p, char *glyphname, double wx, double llx, double lly, double urx, double ury) 236
void PDF_end_glyph(PDF *p) 237
void PDF_encoding_set_char(PDF *p, const char *encoding, int slot, const char *glyphname, int uv) 237

B PDFlib-Kurzreferenz 329
 Textausgabefunktionen
Funktionsprototyp Seite
void PDF_set_text_pos(PDF *p, double x, double y) 239
void PDF_show(PDF *p, const char *text) 240
void PDF_xshow(PDF *p, const char *text, int len, const double *xadvancelist) 240
void PDF_show_xy(PDF *p, const char *text, double x, double y) 241
void PDF_continue_text(PDF *p, const char *text) 241
void PDF_fit_textline(PDF *p, const char *text, int len, double x, double y, const char *optlist) 242
double PDF_stringwidth(PDF *p, const char *text, int font, double fontsize) 245
int PDF_create_textflow(PDF *p, const char *text, int len, const char *optlist) 246
const char *PDF_fit_textflow(PDF *p, int textflow, double llx, double lly, double urx, double ury, const char
*optlist) 247
double PDF_info_textflow(PDF *p, int textflow, const char *keyword) 249
void PDF_delete_textflow(PDF *p, int textflow) 250

Grafikfunktionen
Funktionsprototyp Seite
void PDF_setdash(PDF *p, double b, double w) 256
void PDF_setdashpattern(PDF *p, const char *optlist) 256
void PDF_setflat(PDF *p, double flatness) 257
void PDF_setlinejoin(PDF *p, int linejoin) 257
void PDF_setlinecap(PDF *p, int linecap) 257
void PDF_setmiterlimit(PDF *p, double miter) 258
void PDF_setlinewidth(PDF *p, double width) 258
void PDF_initgraphics(PDF *p) 259
void PDF_save(PDF *p) 259
void PDF_restore(PDF *p) 260
void PDF_translate(PDF *p, double tx, double ty) 260
void PDF_scale(PDF *p, double sx, double sy) 260
void PDF_rotate(PDF *p, double phi) 261
void PDF_skew(PDF *p, double alpha, double beta) 261
void PDF_concat(PDF *p, double a, double b, double c, double d, double e, double f) 261
void PDF_setmatrix(PDF *p, double a, double b, double c, double d, double e, double f) 262
int PDF_create_gstate(PDF *p, const char *optlist) 262
void PDF_set_gstate(PDF *p, int gstate) 263
void PDF_moveto(PDF *p, double x, double y) 264
void PDF_lineto(PDF *p, double x, double y) 264
void PDF_curveto(PDF *p, double x1, double y1, double x2, double y2, double x3, double y3) 264
void PDF_circle(PDF *p, double x, double y, double r) 265
void PDF_arc(PDF *p, double x, double y, double r, double alpha, double beta) 265
void PDF_arcn(PDF *p, double x, double y, double r, double alpha, double beta) 266
void PDF_rect(PDF *p, double x, double y, double width, double height) 266
void PDF_closepath(PDF *p) 266
void PDF_stroke(PDF *p) 267

330 B PDFlib-Kurzreferenz
Funktionsprototyp Seite
void PDF_closepath_stroke(PDF *p) 267
void PDF_fill(PDF *p) 267
void PDF_fill_stroke(PDF *p) 268
void PDF_closepath_fill_stroke(PDF *p) 268
void PDF_clip(PDF *p) 268
void PDF_endpath(PDF *p) 268
int PDF_define_layer(PDF *p, const char *name, int len, const char *optlist) 269
void PDF_set_layer_dependency(PDF *p, const char *type, const char *optlist) 270
void PDF_begin_layer(PDF *p, int layer) 271
void PDF_end_layer(PDF *p) 271

Farbfunktionen
Funktionsprototyp Seite
void PDF_setcolor(PDF *p, const char *fstype, const char *colorspace, double c1, double c2, double c3, double c4)
272
int PDF_makespotcolor(PDF *p, const char *spotname, int reserved) 274
int PDF_load_iccprofile(PDF *p, const char *profilename, int len, const char *optlist) 274
int PDF_begin_pattern(PDF *p, double width, double height, double xstep, double ystep, int painttype) 276
void PDF_end_pattern(PDF *p) 277
int PDF_shading_pattern(PDF *p, int shading, const char *optlist) 277
void PDF_shfill(PDF *p, int shading) 278
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) 278

Rasterbildfunktionen
Funktionsprototyp Seite
int PDF_load_image(PDF *p, const char *imagetype, const char *filename, int len, const char *optlist) 281
void PDF_close_image(PDF *p, int image) 284
void PDF_fit_image(PDF *p, int image, double x, double y, const char *optlist) 285
int PDF_begin_template(PDF *p, double width, double height) 287
void PDF_end_template(PDF *p) 288
void PDF_add_thumbnail(PDF *p, int image) 288

Funktionen für den PDF-Import (PDI)

Funktionsprototyp Seite
int PDF_open_pdi(PDF *p, const char *filename, const char *optlist, int len) 289
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) 290
void PDF_close_pdi(PDF *p, int doc) 291
int PDF_open_pdi_page(PDF *p, int doc, int pagenumber, const char* optlist) 291
void PDF_close_pdi_page(PDF *p, int page) 293

B PDFlib-Kurzreferenz 331
 Funktionsprototyp Seite
void PDF_fit_pdi_page(PDF *p, int page, double x, double y, const char *optlist) 293
int PDF_process_pdi(PDF *p, int doc, int page, const char* optlist) 294
double PDF_get_pdi_value(PDF *p, const char *key, int doc, int page, int reserved) 294
const char * PDF_get_pdi_parameter(PDF *p, const char *key, int doc, int page, int reserved, int *len) 295

Blockfunktionen
Funktionsprototyp Seite
int PDF_fill_textblock(PDF *p, int page, const char *blockname, const char *text, int len, const char *optlist) 298
int PDF_fill_imageblock(PDF *p, int page, const char *blockname, int image, const char *optlist) 299
int PDF_fill_pdfblock(PDF *p, int page, const char *blockname, int contents, const char *optlist) 300

Hypertext-Funktionen
Funktionsprototyp Seite
int PDF_create_action(PDF *p, const char *type, const char *optlist) 302
void PDF_add_nameddest(PDF *p, const char *name, int len, const char *optlist) 306
void PDF_create_annotation(PDF *p, double llx, double lly, double urx, double ury, const char *type, const char
*optlist) 308
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) 312
void PDF_create_fieldgroup(PDF *p, const char *name, int len, const char *optlist) 317
int PDF_create_bookmark(PDF *p, const char *text, int len, const char *optlist) 318
void PDF_set_info(PDF *p, const char *key, const char *value) 319

Tagged PDF und Strukturfunktionen

Funktionsprototyp Seite
int PDF_begin_item(PDF *p, const char *tag, const char *optlist) 323
void PDF_end_item(PDF *p, int id) 325
void PDF_activate_item(PDF *p, int id) 325

332 B PDFlib-Kurzreferenz
Parameter und Werte
Kategorie Funktion Schlüssel
Konfiguration set_parameter resourcefile, SearchPath, license, licensefile, warning, asciifile, trace, tracefile,
tracemsg
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 fontname, fontencoding, fontstyle, textformat
set_value subsetlimit, subsetminsize
get_value ascender, capheight, descender, font, fontsize, fontmaxcode, monospace
Text set_value leading, textrise, horizscaling, textrendering, charspacing, wordspacing,
italicangle
get_value leading, textrise, horizscaling, textrendering, charspacing, wordspacing, textx,
texty, italicangle
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
Farbe set_parameter iccwarning, honoriccprofile, ICCProfile, StandardOutputIntent, renderingintent,
preserveoldpantonenames, spotcolorlookup
set_value defaultgray, defaultrgb, defaultcmyk, setcolor:iccprofilegray,
setcolor:iccprofilergb, 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

B PDFlib-Kurzreferenz 333
C Änderungen an diesem Handbuch
Revisionsübersicht dieses Handbuchs
Datum Änderungen
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

334 C Änderungen an diesem Handbuch

Index

0-9 builtin-Zeichensatz 99
byte order mark (BOM) 106
16-Bit-Zeichensätze 102 bytes: siehe hypertextformat
8-Bit-Zeichensätze 95 Byteserving 194
bytes-Textformat 107
A
Adobe Font Metrics (AFM) 85 C
Adobe Glyph List (AGL) 82, 99 C++-Sprachbindung 28
AFM (Adobe Font Metrics) 85
Speicherverwaltung 29
AGL (Adobe Glyph List) 82, 99
capheight-Parameter 112, 231
Aktionslisten 52
CCITT 146
aktueller Punkt 65
CCSID 97
All (Schmuckfarbname) 274
CFF (Compact Font Format) 81
alphaisshape-Option 262
Character ID (CID) 116
Alphakanal 146
Character-Referenzen 108
Anlagen 103
characters per inch (CPI) 113
Anmerkungen 103
charref-Parameter 238
antialias-Option 279
charspacing-Parameter 238
API (Application Programming Interface) 209
chinesisch 116, 118, 121
äquidistante Schrift 113
CID-Schriften 116
ArtBox 64, 214, 295, 296
CIE L*a*b* Farbraum 71
AS/400 59
ascender-Parameter 112, 231 CJK (chinesisch, japanisch, koreanisch) 116
asciifile-Parameter 59, 211 benutzerdefinierte Schriften 120
asiatisches Fontpaket 116 CMaps 117
Ausgabegenauigkeit 64 Standardschriften 117
Ausnahmebehandlung 48 Windows-Codepages 121
Ausrichtung (Option position) 243 Clipping (Beschneiden) 65
Author-Feld 320 CMaps 117, 118
autocidfont-Parameter 93, 94, 232 CMYK 67
autospace-Parameter 238 Cobol binding 19
autosubsetting-Parameter 94, 231 Codepage
auto-Textformat 107 Microsoft Windows 1250-1258 96
Unicode-Werte 102
compress-Parameter 211
B COM-Sprachbindung 23
Baseline-Kompression 145 copyoutputintent-Option 199
benutzerdefinierte Schriften (Type 3) 88 CPI (characters per inch) 113
benutzerdefinierter Zeichensatz 98 Creator-Feld 320
Berechtigungen 191 CropBox 64, 214, 295, 296
Bézier-Kurve 265 C-Sprachbindung 24
Big Five 121 Speicherverwaltung 27
Bildfunktionen 280 currentx- und currenty-Parameter 112, 264
Bildmasken 146, 148
BleedBox 64, 214, 295, 296
blendmode-Option 262 D
Blends 68 Dateianlagen 103
Blöcke 161 defaultgray/rgb/cmyk-Parameter 74, 276
Blockeigenschaften 164 Demostempel 9
Block-Plugin 161 descender-Parameter 112, 231
BMP 146 Deskriptor 92

Index 335
 Dokumentfunktionen 214 äquidistante 113
Dokumentinfofelder 103, 319 asiatisches Fontpaket 116
Downsampling 144 benutzerdefinierte (Type 3) 88
dpi-Berechnungen 144 CID-Schriften 116
Drehen von Objekten 62 Deskriptor 92
Druckausgabebedingung für PDF/X 196 Glyphennamen 86
Dublin Core 319 PDF-Standardschriften 91
PFA-Dateien 85
E PFB-Dateien 85
PFM-Dateien 85
EBCDIC 59 PostScript 81, 85
ebcdic encoding 96 rechtliche Aspekte der Einbettung 93
ebcdicutf8: siehe hypertextformat Ressourcekonfiguration 54
Einheiten 61 Type 1 85
EJB (Enterprise Java Beans) 31
Type 3 (benutzerdefiniert) 88, 235
Embedded-Systeme 19
Unicode-Unterstützung 102
Encoding-Parameter 231
fontsize-Parameter 231
eServer zSeries und iSeries 59
FontSpecific-Encoding 99
EUDC (end-user defined characters) 122
Fontstilnamen für Windows 87
EUDC-Fonts 86
fontstyle-Parameter 231
Eurozeichen 100
fontwarning-Parameter 50, 231
Exceptions 48, 64
Form XObjects 65
explizite Transparenz 147
Formularfelder: Konvertierung in Blöcke 172
expliziter Grafikzustand 262
Funktionalität von PDFlib 15
extend0- und extend1-Optionen 279
Funktionsgeltungsbereich 47

F G
Farbe 67
Gaiji-Zeichen 82
Farbfunktionen 272
GBK 121
Farbverläufe 68
Geltungsbereich 47
Farbwerte in Optionslisten 52
GIF 145
FDFlib Virtual File System (PVF) 53
Glyph-ID-Adressierung 100
Fehlerbehandlung
glyphwarning-Parameter 238
API 213
Gradients 68
in C 26
Grafikfunktionen 256
in C++ 29
Grafikzustand
in Cobol 20
expliziter 262
in Java 32
Funktionen 256
in Perl 35
grid.pdf 61
in PHP 38
gstate 277
in Python 39
in RPG 42
in Tcl 45 H
filename-Parameter 296 HKS 70
Filling (Füllen) 65 Hochstellen von Text 112
fillrule-Parameter 267 honoriccprofile-Parameter 280
flatness-Option 262 horizontaler Text 117
FontAFM-Parameter 231 horizscaling-Parameter 238
fontencoding-Parameter 231 host fonts 90
fontmaxcode-Parameter 100, 231 HostFont-Parameter 231
Fontmetrik 112 host-Zeichensatz 95
fontname-Parameter 231 hypertextencoding-Parameter 107, 302
FontOutline-Parameter 231 hypertextformat-Parameter 106, 302
font-Parameter 231 Hypertext-Funktionen 302
FontPFM-Parameter 231
Fonts
AFM-Dateien 85 I
allgemein 81 IBM eServer 59

336 Index
ICC-based color 67 Literaturhinweise 327
icccomponents-Parameter 276 Lizenzierung von PDFlib und PDI 9
ICCProfile-Parameter 276 LWFN (LaserWriter Font) 85
iccwarning-Parameter 276
ignoremask 148
image:iccprofile-Parameter 73, 280
M
imagewarning-Option 144 Mac OS Classic: UPR-Konfiguration 55
macroman encoding 95, 96
imagewarning-Parameter 280
macroman-Zeichensatz 95
imagewidth- und imageheight-Parameter 280
major-Parameter 211
implizite Transparenz 147
makepsres Hilfsprogramm 54
Importfunktionen für PDF 289
mask 147
in-core PDF-Erzeugung 58
masked 147
Index-Farbe 67
Maskierung von Bildern 146
Info-Schlüssel in importierten PDF-Dokumenten
masterpassword-Parameter 192, 214
296
MediaBox 64
iSeries 59
mehrseitige Bilddateien 149
ISO 10646 102
Metadaten 218, 319
ISO 8859-2 bis -15 96
Metrik 112
italicangle-Parameter 238
metrische Koordinaten 61
Millimeter 61
J minor-Parameter 211
japanisch 116, 119, 121 miterlimit-Option 263
Java-Applikationsserver 31 monospace parameter 231
Java-Sprachbindung 30 monospaced: siehe äquidistant
EJB 31
javadoc 30 N
Package 30 .NET-Sprachbindung 33
Servlet 31 None (Schmuckfarbname) 274
JFIF 145 N-Option 279
Johab 121 Notizen 103
JPEG 145

O
K Oberlänge 112
Kachelung 67 opacityfill-Option 263
Kategorien von Ressourcen 55 opacitystroke-Option 263
Kennwörter 191 openwarning-Parameter 214
Kerning 113 optimiertes PDF 194
kerning-Parameter 114, 238 Optionslisten 51
Keywords-Feld 320 orientation-Parameter 280
kommerzielle Lizenz 10 overline-Parameter 115, 239
Koordinatensystem 61 overprintfill-Option 263
metrisch 61 overprintmode-Option 263
Top-Down 62 overprintstroke-Option 263
koreanisch 116, 119, 121
P
L page-Option 149
Laufweite 113 pagewidth- und pageheight-Parameter 214
Layer und PDI 153 PANTONE 69
leading-Parameter 112, 238 Parameterbehandlungsfunktionen 224
licensefile-Parameter 211 Passwörter 191
license-Parameter 211 Pattern-Farbraum 67
linearisiertes PDF 194, 216 patterns 67
linecap-Option 262 PDF/X 195
linejoin-Option 262 Druckausgabebedingung 294
linewidth-Option 262 Import von PDF-Dokumenten 198
Listenwerte in Optionslisten 52 PDF_activate_item() 325

Index 337
 PDF_add_nameddest() 306 PDF_get_parameter() 225
PDF_add_thumbnail() 288 PDF_get_pdi_parameter 295
PDF_arc() 265 PDF_get_pdi_value 294
PDF_arcn() 266 PDF_get_value() 225
PDF_begin_document() 215 PDF_info_textflow() 249
PDF_begin_item() 323 PDF_initgraphics() 259
PDF_begin_layer() 271 PDF_lineto() 264
PDF_begin_page() 221, 222, 223, 224 PDF_load_font() 232
PDF_begin_pattern 276 PDF_load_iccprofile() 274
PDF_begin_template() 287 PDF_load_image() 281
PDF_boot() 212 PDF_makespotcolor() 274
PDF_circle() 265 PDF_moveto() 264
PDF_clip() 268 PDF_new() 212
PDF_close_image() 284 PDF_new_dl( ) 212
PDF_close_pdi 291 PDF_new2() 213
PDF_close_pdi_page 293 PDF_open_pdi 289
PDF_closepath() 266 PDF_open_pdi_callback 290
PDF_closepath_fill_stroke() 268 PDF_open_pdi_page 291
PDF_closepath_stroke() 267 PDF_process_pdi 294
PDF_concat() 261 PDF_rect() 266
PDF_continue_text() 241 PDF_restore() 260
PDF_continue_text2() 241 PDF_rotate() 261
PDF_create_action() 302 PDF_save() 259
PDF_create_annotation() 308 PDF_scale() 260
PDF_create_bookmark() 318 PDF_set_gstate() 263
PDF_create_field() 312 PDF_set_info() 319
PDF_create_fieldgroup() 317 PDF_set_info2() 319
PDF_create_gstate() 262 PDF_set_layer_dependency() 270
PDF_create_pvf 226 PDF_set_parameter() 58, 226
PDF_create_textflow() 246 PDF_set_text_pos() 239
PDF_curveto() 264 PDF_set_value() 225
PDF_define_layer() 269 PDF_setcolor() 272
PDF_delete() 213 PDF_setdash() 256
PDF_delete_dl( ) 214 PDF_setdashpattern() 256
PDF_delete_pvf 227 PDF_setflat() 257
PDF_delete_textflow() 250 PDF_setfont() 235, 236, 237
PDF_encoding_set_char() 237 PDF_setlinecap() 257
PDF_end_document() 217 PDF_setlinejoin() 257
PDF_end_item() 325 PDF_setlinewidth() 258
PDF_end_layer() 271 PDF_setmatrix() 262
PDF_end_page() 224 PDF_setmiterlimit() 258
PDF_end_pattern 277 PDF_shading() 278
PDF_end_template() 288 PDF_shading_pattern() 277
PDF_endpath() 268 PDF_shfill() 278
PDF_fill() 267 PDF_show() 240
PDF_fill_imageblock() 299 PDF_show_boxed() 246
PDF_fill_pdfblock() 300 PDF_show_xy() 241
PDF_fill_stroke() 268 PDF_show_xy2() 241
PDF_fill_textblock() 298 PDF_show2() 240
PDF_fit_image() 285 PDF_shutdown() 212
PDF_fit_pdi_page 293 PDF_skew() 261
PDF_fit_text() 242 PDF_stringwidth() 245
PDF_fit_textflow() 247 PDF_stringwidth2() 245
PDF_get_apiname() 228 PDF_stroke() 267
PDF_get_buffer() 58, 220 PDF_translate() 260
PDF_get_errmsg() 228 PDF_utf16_to_utf8 229, 230
PDF_get_errnum() 228 PDF_utf8_to_utf16() 230
PDF_get_opaque() 229 PDF_xshow() 240

338 Index
PDF-Importbibliothek PDI 151, 289 skalieren 144
PDF-Importfunktionen 289 Transparenz 146
PDFlib REALbasic-Sprachbindung 39
Funktionalität 15 Rechtecke in Optionslisten 52
Programmstruktur 47 Reflexion 260
PDFlib Personalization Server 161 renderingintent-Option 71, 263
pdflib.upr 57 renderingintent-Parameter 280
PDFlib-API-Referenz 209 Rendering-Intents 71
PDFlib-Plugin zur Blockerzeugung 161 resourcefile-Parameter 57, 211
PDFLIBRESOURCE-Umgebungsvariable 57 Ressourcekategorie 55
pdfx-Parameter Ressourcenkonfiguration 54
für PDI 199, 296 resx- und resy-Parameter 280
PDI 151, 289 revision-Parameter 211
pdi-Parameter 296 RGB-Farbe 67
pdiusebox-Parameter 153, 296 Rohbilddaten 146
pdiwarning-Option 153 Rotate-Eintrag in importierten PDF-Seiten 295
pdiwarning-Parameter 296 RPG-Sprachbindung 40
Perl-Sprachbindung 33
permissions-Option 193 S
permissions-Parameter 214
S/390 59
PFA (Printer Font ASCII) 85
Scherung 261
Pfad 65
Schmuckfarbe (Separation-Farbraum) 67, 68
zeichnen und beschneiden 267
schnelle Web-Anzeige 216
PFB (Printer Font Binary) 85
Schriften: siehe Fonts
PFM (Printer Font Metrics) 85
Schriftuntergruppen 93
PHP-Sprachbindung 35
scope-Parameter 211
Piktogramme 288
SearchPath-Parameter 56, 211, 231
Plattformen 19
Seitenbeschreibungen 61
Plugin zur Blockerzeugung 161
Seitenformate 63
PNG 145, 147
Begrenzungen in Acrobat 64
Portable Document Format Reference Manual
Seitenfunktionen 214
327
seitenweises Herunterladen 194
PostScript-Schriften 81, 85
Separation-Farbraum 67
PPS (PDFlib Personalization Server) 161
serial-Parameter 9
prefix-Parameter 211
Servlet 31
preserveoldpantonenames-Parameter 272
setcolor:iccprofilegray/rgb/cmyk-Parameter 74,
print_glyphs.ps 86
276
Printer Font ASCII (PFA) 85
Setup-Funktionen 211
Printer Font Binary (PFB) 85
Shift-JIS 121
Printer Font Metrics (PFM) 85
Sicherheit 191
Programmstruktur 47
Skalieren von Rasterbildern 144
PVF siehe PDFlib Virtual File System 53
Smooth Shadings 68
Python-Sprachbindung 38
smoothness-Option 263
Speicher: Erzeugung von PDF-Dokumenten im 58
Q Speicherverwaltung
Querformat 223 API 213
in C 27
in C++ 29
R Spiegelung 260
r0- und r1-Optionen 279 SPIFF 145
Rasterbilder spotcolorlookup-Parameter 272
allgemein 143 Sprachbindungen 19
Bildmasken 148 sRGB-Farbraum 73
Daten wiederverwenden 143 Standardausgabe 215
Downsampling 144 Standard-Druckausgabebedingungen für PDF/X
Formate 145 198
Funktionen 280 Standardkoordinatensystem 61
Rohdaten 146 StandardOutputIntent-Parameter 276

Index 339
 Standardschriften 91 TrimBox 64, 214, 295, 296
Standardseitenmaße 63 TrueType Collections 120
stdout-Kanal 215 TTC (TrueType Collection) 86, 120
Stilnamen für Windows 87 TTF (TrueType-Font) 81
strikeout-Parameter 115, 239 Type-1-Schriften 85
strokeadjust-Option 263 Type-3-Schriften 88, 235
Stroking (Zeichnen) 65
Struktur von PDFlib-Programmen 47
Subject-Feld 320
U
subscript 112, 239 U+XXXX-Encoding 102
subsetlimit-Parameter 94, 231 Überschreiben von Blockeigenschaften 164
subsetminsize-Parameter 94, 231 UHC 121
superscript 112, 239 Umgebungsvariable PDFLIBRESOURCE 57
Symbolschrift 99 Umrisslinien von Text zeichnen 239
Systemschriften 90 underline-Parameter 115, 239
Systemzeichensätze 97 Unicode 102
unicodemap-Parameter 103, 232
unsichtbarer Text 239
T Untergruppen einer Schrift 93
Tcl-Sprachbindung 44 Unterlänge 112
Teilpfad 65 Unterschneidung 113
Templates 65 UPR (Unix PostScript Resource) 54
Text Dateiformat 55
Funktionen 231 Dateisuche 57
hochstellen 112 user space 61
Laufweite 113 usercoordinates-Parameter 61, 302
Oberlänge 112 userpassword-Parameter 192, 214
Position 112 utf16: siehe hypertextformat
tiefstellen 112 utf16be: siehe hypertextformat
Umrisslinien zeichnen 239 utf16le: siehe hypertextformat
unsichtbarer 239 utf8: siehe hypertextformat
Unterlänge 112
unterschneiden 113
Versalhöhe 112
V
Variable Data Processing (VDP) 298
vertikal und horizontal 117
variable Datenverarbeitung mit Blöcken 161
Zeilenabstand 112
vdp/blockcount-Parameter für PDI 297
Textanmerkungen 103
vdp/Block-Parameter für PDI 297
Textbehandlung 81
Verfügbarkeit von PDFlib 19
textformat-Parameter 106, 239
Versalhöhe 112
textknockout-Option 263
Verschlüsselung 191
Textmetrik 112
version-Parameter 211, 296
textrendering-Parameter 115, 239
vertikaler Text 117
textrise-Parameter 239
virtuelles Dateisystem 53
Textvarianten 112
textx- und texty-Parameter 112, 120, 239
Thumbnails: siehe Piktogramme W
Tiefstellen von Text 112 warning-Parameter 49, 227
TIFF 145 web-optimiertes PDF 194, 216
mehrseitig 149 width- und height-Parameter 295
Title-Feld 320 winansi-Zeichensatz 96
Top-Down-Koordinaten 62 wordspacing-Parameter 239
topdown-Parameter 63, 214
ToUnicode CMap 84, 103
trace, tracefile, tracemsg parameters 212 X
Transparenz 146 XMP-Metadaten 218
explizite 147 XObjects 65
implizite 147
Probleme mit 148
Trapped-Feld 320

340 Index
Z
ZapfDingbats-Schrift 99
Zeichennamen 86
Zeichensätze 95
benutzerdefinierte 98
CJK 117
für Hypertext 107
vom System beziehen 97
Zeilenabstand 112
Zoll 61
zSeries 59

Index 341